Matrix 迁移

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• 插件仍是 @openclaw/matrix
• 渠道仍是 matrix
• 你的配置仍位于 channels.matrix 下
• 缓存凭证仍位于 ~/.openclaw/credentials/matrix/ 下
• 运行时状态仍位于 ~/.openclaw/matrix/ 下

​

迁移会自动执行什么

• 源码安装会在更新流程中运行 openclaw doctor --fix，然后默认重启 Gateway 网关
• 包管理器安装会更新包，运行一次非交互式 Doctor 检查，然后依赖默认的 Gateway 网关重启，让启动过程完成 Matrix 迁移
• 如果你使用 openclaw update --no-restart，基于启动的 Matrix 迁移会延后，直到你稍后运行 openclaw doctor --fix 并重启 Gateway 网关

• 在 ~/Backups/openclaw-migrations/ 下创建或复用迁移前快照
• 复用你缓存的 Matrix 凭证
• 保持相同的账号选择和 channels.matrix 配置
• 将最旧的扁平 Matrix 同步存储移动到当前按账号划分的位置
• 当可以安全解析目标账号时，将最旧的扁平 Matrix 加密存储移动到当前按账号划分的位置
• 当本地存在先前保存的 Matrix 房间密钥备份解密密钥时，从旧的 rust 加密存储中提取该密钥
• 当访问令牌稍后发生变化时，为同一个 Matrix 账号、homeserver 和用户复用现有最完整的 token-hash 存储根目录
• 当 Matrix 访问令牌发生变化但账号/设备身份保持不变时，扫描同级 token-hash 存储根目录中的待处理加密状态恢复元数据
• 在下一次 Matrix 启动时，将已备份的房间密钥恢复到新的加密存储中

• OpenClaw 会在成功创建快照后，将标记文件写入 ~/.openclaw/matrix/migration-snapshot.json，以便之后的启动和修复流程可以复用同一个归档。
• 这些自动 Matrix 迁移快照仅备份配置 + 状态（includeWorkspace: false）。
• 如果 Matrix 只有仅警告的迁移状态，例如因为仍缺少 userId 或 accessToken，OpenClaw 暂时不会创建快照，因为没有可执行的 Matrix 修改。
• 如果快照步骤失败，OpenClaw 会跳过该次运行的 Matrix 迁移，而不是在没有恢复点的情况下修改状态。

• 最旧的扁平 Matrix 存储（~/.openclaw/matrix/bot-storage.json 和 ~/.openclaw/matrix/crypto/）来自单存储布局，因此 OpenClaw 只能将其迁移到一个已解析的 Matrix 账号目标
• 已经按账号划分的旧版 Matrix 存储会按每个已配置的 Matrix 账号进行检测和准备

​

迁移无法自动完成什么

• 从未备份过的仅本地房间密钥
• 当目标 Matrix 账号还无法解析时的加密状态，因为 homeserver、userId 或 accessToken 仍不可用
• 当配置了多个 Matrix 账号但未设置 channels.matrix.defaultAccount 时，自动迁移一个共享的扁平 Matrix 存储
• 固定到仓库路径而不是标准 Matrix 包的自定义插件路径安装
• 当旧存储中有已备份密钥但本地没有保留解密密钥时，缺失的恢复密钥

• 自定义 Matrix 插件路径安装会同时由 Gateway 网关启动和 openclaw doctor 显示

​

推荐升级流程

1. 正常更新 OpenClaw 和 Matrix 插件。 优先使用不带 --no-restart 的普通 openclaw update，这样启动过程可以立即完成 Matrix 迁移。
2. 运行：
   openclaw doctor --fix
   
   如果 Matrix 有可执行的迁移工作，Doctor 会先创建或复用迁移前快照，并打印归档路径。
3. 启动或重启 Gateway 网关。
4. 检查当前验证和备份状态：
   openclaw matrix verify status
   openclaw matrix verify backup status
   
5. 将你正在修复的 Matrix 账号的恢复密钥放入账号专用的环境变量。对于单个默认账号，MATRIX_RECOVERY_KEY 就可以。对于多个账号，请为每个账号使用一个变量，例如 MATRIX_RECOVERY_KEY_ASSISTANT，并向命令添加 --account assistant。
6. 如果 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
   
7. 如果此设备仍未验证，请为对应账号运行命令：
   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 客户端中接受请求，比较 emoji 或十进制数字， 只有在它们匹配时才输入 yes。该命令只有在 Cross-signing verified 变为 yes 后才会成功退出。
8. 如果你有意放弃无法恢复的旧历史记录，并希望为未来消息创建新的备份基线，请运行：
   openclaw matrix verify backup reset --yes
   
9. 如果还没有服务端密钥备份，请为将来的恢复创建一个：
   openclaw matrix verify bootstrap
   

​

加密迁移的工作方式

1. 如果加密迁移可执行，启动过程或 openclaw doctor --fix 会创建或复用迁移前快照。
2. 启动过程或 openclaw doctor --fix 会通过当前有效的 Matrix 插件安装检查旧的 Matrix 加密存储。
3. 如果找到备份解密密钥，OpenClaw 会将其写入新的恢复密钥流程，并将房间密钥恢复标记为待处理。
4. 在下一次 Matrix 启动时，OpenClaw 会自动将已备份的房间密钥恢复到新的加密存储中。

​

常见消息及其含义

​

升级和检测消息

• 含义：检测到了磁盘上的旧 Matrix 状态，并已迁移到当前布局。
• 处理方式：除非同一输出还包含警告，否则无需操作。

• 含义：OpenClaw 在修改 Matrix 状态之前创建了恢复归档。
• 处理方式：保留打印出的归档路径，直到你确认迁移成功。

• 含义：OpenClaw 找到了现有 Matrix 迁移快照标记，并复用了该归档，而不是创建重复备份。
• 处理方式：保留打印出的归档路径，直到你确认迁移成功。

• 含义：存在旧 Matrix 状态，但 OpenClaw 无法将其映射到当前 Matrix 账号，因为尚未配置 Matrix。
• 处理方式：配置 channels.matrix，然后重新运行 openclaw doctor --fix 或重启 Gateway 网关。

• 含义：OpenClaw 找到了旧状态，但仍无法确定确切的当前账号/设备根目录。
• 处理方式：使用可工作的 Matrix 登录启动一次 Gateway 网关，或在缓存凭证存在后重新运行 openclaw doctor --fix。

• 含义：OpenClaw 找到了一个共享的扁平 Matrix 存储，但拒绝猜测应由哪个具名 Matrix 账号接收它。
• 处理方式：将 channels.matrix.defaultAccount 设置为目标账号，然后重新运行 openclaw doctor --fix 或重启 Gateway 网关。

• 含义：新的按账号划分的位置已经有同步或加密存储，因此 OpenClaw 没有自动覆盖它。
• 处理方式：在手动删除或移动冲突目标之前，确认当前账号是正确账号。

• 含义：OpenClaw 尝试移动旧 Matrix 状态，但文件系统操作失败。
• 处理方式：检查文件系统权限和磁盘状态，然后重新运行 openclaw doctor --fix。

• 含义：OpenClaw 找到了旧的加密 Matrix 存储，但没有当前 Matrix 配置可附加到它。
• 处理方式：配置 channels.matrix，然后重新运行 openclaw doctor --fix 或重启 Gateway 网关。

• 含义：加密存储存在，但 OpenClaw 无法安全判断它属于哪个当前账号/设备。
• 处理方式：使用可工作的 Matrix 登录启动一次 Gateway 网关，或在缓存凭证可用后重新运行 openclaw doctor --fix。

• 含义：OpenClaw 找到了一个共享的扁平旧版加密存储，但拒绝猜测应由哪个具名 Matrix 账号接收它。
• 处理方式：将 channels.matrix.defaultAccount 设置为目标账号，然后重新运行 openclaw doctor --fix 或重启 Gateway 网关。

• 含义：OpenClaw 检测到了旧 Matrix 状态，但迁移仍被缺失的身份或凭证数据阻塞。
• 处理方式：完成 Matrix 登录或配置设置，然后重新运行 openclaw doctor --fix 或重启 Gateway 网关。

• 含义：OpenClaw 找到了旧的加密 Matrix 状态，但无法从通常用于检查该存储的 Matrix 插件加载辅助入口点。
• 处理方式：重新安装或修复 Matrix 插件（openclaw plugins install @openclaw/matrix，或对于仓库检出使用 openclaw plugins install ./path/to/local/matrix-plugin），然后重新运行 openclaw doctor --fix 或重启 Gateway 网关。

• 含义：OpenClaw 发现某个辅助文件路径逃逸了插件根目录，或未通过插件边界检查，因此拒绝导入它。
• 处理方式：从受信任路径重新安装 Matrix 插件，然后重新运行 openclaw doctor --fix 或重启 Gateway 网关。

• 含义：OpenClaw 拒绝修改 Matrix 状态，因为它无法先创建恢复快照。
• 处理方式：解决备份错误，然后重新运行 openclaw doctor --fix 或重启 Gateway 网关。

• 含义：Matrix 客户端侧回退逻辑发现了旧的扁平存储，但移动失败。OpenClaw 现在会中止该回退逻辑，而不是静默地用全新存储启动。
• 处理方式：检查文件系统权限或冲突，保持旧状态完整，并在修复错误后重试。

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

​

加密状态恢复消息

• 含义：已备份的房间密钥已成功恢复到新的加密存储中。
• 处理方式：通常不需要做任何事。

• 含义：一些旧房间密钥只存在于旧本地存储中，从未上传到 Matrix 备份。
• 处理方式：除非你能从另一个已验证客户端手动恢复这些密钥，否则预计部分旧加密历史仍不可用。

• 含义：备份存在，但 OpenClaw 无法自动恢复恢复密钥。
• 处理方式：运行 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin。

• 含义：OpenClaw 找到了旧的加密存储，但无法以足够安全的方式检查它以准备恢复。
• 处理方式：重新运行 openclaw doctor --fix。如果问题重复出现，请保持旧状态目录完整，并使用另一个已验证的 Matrix 客户端加上 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin 进行恢复。

• 含义：OpenClaw 检测到备份密钥冲突，并拒绝自动覆盖当前的 recovery-key 文件。
• 处理方式：在重试任何恢复命令前，确认哪个恢复密钥是正确的。

• 含义：这是旧存储格式的硬性限制。
• 处理方式：已备份的密钥仍可恢复，但仅本地存在的加密历史可能仍不可用。

• 含义：新插件尝试恢复，但 Matrix 返回了错误。
• 处理方式：运行 openclaw matrix verify backup status，然后在需要时使用 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin 重试。

​

手动恢复消息

• 含义：OpenClaw 知道你应该有备份密钥，但它未在此设备上激活。
• 处理方式：运行 openclaw matrix verify backup restore，或设置 MATRIX_RECOVERY_KEY 并在需要时运行 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin。

• 含义：此设备当前没有存储恢复密钥。
• 处理方式：设置 MATRIX_RECOVERY_KEY，运行 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin，然后恢复备份。

• 含义：已存储的密钥与当前活动的 Matrix 备份不匹配。
• 处理方式：将 MATRIX_RECOVERY_KEY 设置为正确密钥，并运行 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin。

• 含义：备份存在，但此设备尚未足够信任交叉签名链。
• 处理方式：设置 MATRIX_RECOVERY_KEY 并运行 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin。

• 含义：你尝试执行恢复步骤时没有提供所需的恢复密钥。
• 处理方式：使用 --recovery-key-stdin 重新运行命令，例如 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin。

• 含义：提供的密钥无法解析，或不符合预期格式。
• 处理方式：使用你的 Matrix 客户端或 recovery-key 文件中的确切恢复密钥重试。

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

• 含义：密文存储未在此设备上生成活动的备份会话。
• 处理方式：先验证设备，然后使用 openclaw matrix verify backup status 重新检查。

• 含义：在设备验证完成前，此设备无法从密文存储恢复。
• 处理方式：先运行 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin。

​

自定义插件安装消息

• 含义：你的插件安装记录指向一个已经不存在的本地路径。
• 处理方式：使用 openclaw plugins install @openclaw/matrix 重新安装；如果你是从仓库检出运行，则使用 openclaw plugins install ./path/to/local/matrix-plugin。

​

如果加密历史仍未恢复

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