跳转至

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 迁移会执行。受支持的同步缓存 JSON 导入会保留其客户端启动回退。凭据文件导入仅由 Doctor 执行;运行时只读取规范的 SQLite 凭据状态。

Doctor 迁移涵盖:

  • 在归档之前导入并验证已弃用的 ~/.openclaw/credentials/matrix/credentials*.json 文件
  • 保持相同的账户选择和 channels.matrix 配置
  • 将受支持的账户级 bot-storage.json 同步缓存导入 Matrix SQLite 状态,并将已迁移文件以 .migrated 后缀归档
  • 当访问令牌后续发生变化时,为相同的 Matrix 账户、homeserver、用户和设备复用最完整的现有令牌哈希存储根目录

已弃用的 7 月前状态文件

当前版本支持 2026 年 7 月 1 日或之后写入的状态格式。 Matrix 线程绑定、启动验证冷却、恢复密钥、加密快照、存储元数据和入站去重标记到那时已经使用 SQLite。对 thread-bindings.json、startup-verification.json、recovery-key.json、legacy-crypto-migration.json、crypto-idb-snapshot.json、storage-meta.json 和 inbound-dedupe.json 的导入已弃用。Doctor 和受影响的运行时会拒绝这些文件并保持其不变。如果它们仍存在于活动的 Matrix 存储根目录中,请先安装 OpenClaw 2026.9.5,运行 openclaw doctor --fix,并启动一次 Matrix 频道以完成导入。然后升级到最新版本。

从早于 2026.4 的 OpenClaw 版本升级

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

如果你正在升级仍使用扁平布局的安装,请先升级到 2026.6 版本,运行 openclaw doctor --fix,并启动一次网关,以便迁移扁平存储和任何可恢复的房间密钥。接下来,通过 2026.9.5 升级,运行其 Doctor,并启动一次 Matrix,以在安装最新版本之前将任何剩余的 JSON 附属文件转换为 SQLite。

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

  1. 正常更新 OpenClaw 和 Matrix 插件。
  2. 运行:
openclaw doctor --fix
  1. 启动或重启网关。
  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: ...

  • 含义:在将基于文件的附属状态导入 SQLite 时,Matrix 客户端侧回退失败。启动会停止。已完成的 SQLite 导入和已归档的附属文件保持原样;尚未归档的文件仍可用于重试。
  • 处理方法:检查文件系统权限或冲突,保持 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: 指导:

备份问题 含义 修复
no room-key backup exists on the homeserver 没有可恢复的内容 使用 openclaw matrix verify bootstrap 创建房间密钥备份
backup decryption key is not loaded on this device 密钥存在但在此设备上未激活 openclaw matrix verify backup restore;如果仍无法加载密钥,通过 --recovery-key-stdin 传入恢复密钥
backup decryption key could not be loaded from secret storage (...) 密钥存储加载失败或不受支持 传入恢复密钥:printf '%s\n' "$MATRIX_RECOVERY_KEY" \| openclaw matrix verify backup restore --recovery-key-stdin
backup key mismatch (...) 存储的密钥与当前服务器备份不匹配 使用当前服务器备份密钥重新运行 verify backup restore --recovery-key-stdin,或运行 verify backup reset --yes 建立新的基线
backup signature chain is not trusted by this device 设备尚未信任交叉签名链 运行 verify device --recovery-key-stdin,如果信任仍不完整,再从另一个已验证客户端运行 verify self
backup exists but is not active on this device 服务器备份存在,但本地会话未激活 先验证设备,然后使用 openclaw matrix verify backup status 重新检查
backup trust state could not be fully determined 诊断结果不确定 openclaw matrix verify status --verbose

其他恢复错误:

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 表情符号或十进制代码,并确认它们匹配。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw