Matrix 迁移

从之前的公开 matrix 插件升级到当前实现。

对大多数用户而言，升级是原地进行的：

• 插件仍为 @openclaw/matrix
• 通道仍为 matrix
• 你的配置仍位于 channels.matrix 下
• 缓存凭据会迁移到共享的 state/openclaw.sqlite 插件状态中
• 运行时状态仍位于 ~/.openclaw/matrix/ 下

你无需重命名配置键，也无需以新名称重新安装插件。 根 openclaw 包不再捆绑 Matrix 运行时代码或 Matrix SDK 依赖。如果 openclaw channels status 显示 Matrix 已配置但插件未安装，请运行 openclaw doctor --fix 或 openclaw plugins install @openclaw/matrix；不要将 Matrix SDK 包安装到根 OpenClaw 包中。

迁移自动执行的操作¶

当你运行 openclaw doctor --fix 时，Matrix 迁移会执行。专用 Matrix 存储旁边的基于文件的 sidecar 仍保留客户端启动回退机制，但凭据文件导入仅由 Doctor 执行；运行时仅读取规范的 SQLite 凭据状态。

Doctor 迁移涵盖：

• 在归档之前，导入并验证已弃用的 ~/.openclaw/credentials/matrix/credentials*.json 文件
• 保持相同的账户选择和 channels.matrix 配置
• 将基于文件的 sidecar 状态（bot-storage.json 同步缓存、recovery-key.json、legacy-crypto-migration.json、IndexedDB 快照）导入 Matrix SQLite 状态；已迁移的文件会以 .migrated 后缀归档
• 当 access token 稍后发生变化时，为相同的 Matrix 账户、homeserver、用户和设备复用最完整的现有 token-hash 存储根

从 2026.4 之前的 OpenClaw 版本升级¶

截至 2026.6 系列的版本还会迁移原始的扁平单存储 Matrix 布局（~/.openclaw/matrix/bot-storage.json 加上 ~/.openclaw/matrix/crypto/），并准备从旧的 rust 加密存储恢复加密状态。当前版本不再包含该迁移。

如果你正在升级仍使用扁平布局的安装，请先升级到 2026.6 版本，运行 openclaw doctor --fix，并启动一次 gateway，以便扁平存储和任何可恢复的房间密钥被迁移。然后更新到最新版本。

之前的公开 Matrix 插件没有自动创建 Matrix 房间密钥备份。如果你的旧安装只有本地加密历史且从未备份，那么无论迁移路径如何，一些较早的加密消息在升级后可能仍无法读取。

推荐升级流程¶

1. 正常更新 OpenClaw 和 Matrix 插件。
2. 运行：

openclaw doctor --fix

1. 启动或重启 gateway。
2. 检查当前验证和备份状态：

openclaw matrix verify status
openclaw matrix verify backup status

1. 将你要修复的 Matrix 账户的恢复密钥放入账户专属环境变量。对于单个默认账户，使用 MATRIX_RECOVERY_KEY 即可。对于多个账户，每个账户使用一个变量，例如 MATRIX_RECOVERY_KEY_ASSISTANT，并在命令中添加 --account assistant。

2. 如果 OpenClaw 提示需要恢复密钥，请为匹配的账户运行命令：

printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin
printf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | openclaw matrix verify backup restore --recovery-key-stdin --account assistant

1. 如果此设备仍未验证，请为匹配的账户运行命令：

printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
printf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | openclaw matrix verify device --recovery-key-stdin --account assistant

如果恢复密钥被接受且备份可用，但 Cross-signing verified 仍为 no，请从另一个 Matrix 客户端完成自验证：

openclaw matrix verify self

在另一个 Matrix 客户端中接受请求，比较表情符号或十进制数， 并且仅在它们匹配时输入 yes。该命令会等待完整的 Matrix 身份信任建立后才报告成功。

1. 如果你有意放弃无法恢复的旧历史，并希望为未来消息建立新的备份基线，请运行：

openclaw matrix verify backup reset --yes

仅当旧恢复密钥应停止解锁新备份时，才添加 --rotate-recovery-key。

1. 如果尚不存在服务器端密钥备份，请创建一个用于未来恢复：

openclaw matrix verify bootstrap

常见消息及其含义¶

Failed migrating legacy Matrix client storage: ...

• 含义：在将基于文件的 sidecar 状态导入 SQLite 时，Matrix 客户端回退失败。启动会停止。已完成的 SQLite 导入和已归档的 sidecar 保持原样；尚未归档的文件仍可用于重试。
• 处理方法：检查文件系统权限或冲突，保持 SQLite 状态以及源文件或 .migrated 文件完整，并在修复错误后重试。

Matrix is installed from a custom path: ...

• 含义：Matrix 被固定为路径安装，因此主线更新不会自动将其替换为默认 Matrix 包。
• 处理方法：当你想返回默认 Matrix 插件时，使用 openclaw plugins install @openclaw/matrix 重新安装。

Matrix is installed from a custom path that no longer exists: ...

• 含义：你的插件安装记录指向一个已不存在的本地路径。
• 处理方法：使用 openclaw plugins install @openclaw/matrix 重新安装，或者如果你是从仓库检出运行，则使用 openclaw plugins install ./path/to/local/matrix-plugin。openclaw doctor --fix 也可以为你移除过时的 Matrix 插件引用。

手动恢复消息¶

openclaw matrix verify status 和 openclaw matrix verify backup status 会在此设备的房间密钥备份不健康时，打印一行 Backup issue: 以及 Next steps: 指导：

其他恢复错误：

Matrix recovery key is required

• 含义：在需要恢复密钥时，未提供恢复密钥就尝试了恢复步骤。
• 处理方法：使用 --recovery-key-stdin 重新运行命令，例如 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin。

Invalid Matrix recovery key: ...

• 含义：提供的密钥无法解析或不符合预期格式。
• 处理方法：使用 Matrix 客户端或恢复密钥导出中的准确恢复密钥重试。

Matrix recovery key was applied, but this device still lacks full Matrix identity trust.

• 含义：恢复密钥解锁了可用的备份材料，但 Matrix 尚未为此设备建立完整的交叉签名身份信任。检查命令输出中的 Recovery key accepted、Backup usable、Cross-signing verified 和 Device verified by owner。
• 处理方法：运行 openclaw matrix verify self，在另一个 Matrix 客户端中接受请求，比较 SAS，并且仅在匹配时输入 yes。仅当您有意替换当前交叉签名身份时，才使用 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing。

如果您接受丢失无法恢复的旧加密历史，您也可以改为使用 openclaw matrix verify backup reset --yes 重置当前备份基线。当存储的备份秘密损坏时，该重置还会修复秘密存储，使新的备份密钥在重启后能够正确加载。

如果加密历史仍然无法恢复¶

按顺序运行这些检查：

openclaw matrix verify status --verbose
openclaw matrix verify backup status --verbose
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin --verbose

如果备份成功恢复，但某些旧房间仍然缺少历史，那么这些缺失的密钥可能从未被之前的插件备份。

如果您想为未来消息重新开始¶

如果您接受丢失无法恢复的旧加密历史，并且只想为今后建立一个干净的备份基线，请按顺序运行以下命令：

openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status

如果之后设备仍未验证，请从您的 Matrix 客户端完成验证：比较 SAS 表情符号或十进制代码，并确认它们匹配。

相关¶

• Matrix：频道设置与配置。
• Matrix 推送规则：通知路由。
• Doctor：健康检查与自动迁移触发。
• 迁移指南：所有迁移路径（机器迁移、跨系统导入）。
• 插件：插件安装与注册。