Skip to main content
从之前的公开 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 存储旁基于文件的附属状态仍保留客户端启动时的回退机制，但凭据文件导入仅由 Doctor 执行；运行时只读取规范的 SQLite 凭据状态。 Doctor 迁移包括：
  • 在归档已停用的 ~/.openclaw/credentials/matrix/credentials*.json 文件前导入并验证它们
  • 保留相同的账户选择和 channels.matrix 配置
  • 将基于文件的附属状态（bot-storage.json 同步缓存、recovery-key.json、legacy-crypto-migration.json、IndexedDB 快照）导入 Matrix SQLite 状态；已迁移的文件会使用 .migrated 后缀归档
  • 当访问令牌之后发生变化时，为相同的 Matrix 账户、主服务器、用户和设备复用内容最完整的现有令牌哈希存储根目录

​
从早于 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. 运行：
  3. 启动或重启 Gateway 网关。
  4. 检查当前验证和备份状态：
  5. 将正在修复的 Matrix 账户的恢复密钥放入账户专用的环境变量中。对于单个默认账户，使用 MATRIX_RECOVERY_KEY 即可。对于多个账户，请为每个账户使用一个变量，例如 MATRIX_RECOVERY_KEY_ASSISTANT，并在命令中添加 --account assistant。
  6. 如果 OpenClaw 提示需要恢复密钥，请对相应账户运行命令：
  7. 如果此设备仍未验证，请对相应账户运行命令：
    如果恢复密钥已被接受且备份可用，但 Cross-signing verified 仍为 no，请从另一个 Matrix 客户端完成自我验证：
    在另一个 Matrix 客户端中接受请求，比较表情符号或十进制数字， 仅当它们匹配时才输入 yes。该命令会等待 Matrix 身份获得完全信任后才报告成功。
  8. 如果你有意放弃无法恢复的旧历史记录，并希望为未来消息建立全新的备份基线，请运行：
    仅当旧恢复密钥不应再能解锁新备份时，才添加 --rotate-recovery-key。
  9. 如果尚不存在服务器端密钥备份，请创建一个，以便将来恢复：

​
常见消息及其含义

Failed migrating legacy Matrix client storage: ...
  • 含义：Matrix 客户端侧回退机制发现了基于文件的附属状态，但导入 SQLite 失败。OpenClaw 会回滚已完成的移动操作并中止该回退，而不是在不发出提示的情况下使用全新存储启动。
  • 处理方式：检查文件系统权限或冲突，保持旧状态不变，修复错误后重试。
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 重置当前备份基线。当 存储的备份密钥损坏时，此重置操作还会修复密钥存储，以便 新备份密钥在重启后可以正确加载。

​
如果加密历史记录仍未恢复

按顺序运行以下检查：
如果备份恢复成功，但部分旧房间仍缺少历史记录，则这些缺失的密钥很可能从未由之前的插件备份。

​
如果你希望为未来消息重新开始

如果你接受丢失无法恢复的旧加密历史记录，并且只希望今后使用干净的备份基线，请按顺序运行以下命令：
如果之后设备仍未验证，请在 Matrix 客户端中比较 SAS 表情符号或十进制代码，并确认它们匹配，以完成验证。

​
相关内容