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 房间密钥备份。如果你的旧安装包含仅本地保存且从未备份的加密历史,那么无论迁移路径如何,一些较早的加密消息在升级后可能仍无法读取。
推荐升级流程¶
- 正常更新 OpenClaw 和 Matrix 插件。
- 运行:
- 启动或重启网关。
- 检查当前验证和备份状态:
-
将你要修复的 Matrix 账户的恢复密钥放入账户专属环境变量中。对于单个默认账户,使用
MATRIX_RECOVERY_KEY即可。对于多个账户,每个账户使用一个变量,例如MATRIX_RECOVERY_KEY_ASSISTANT,并在命令中添加--account assistant。 -
如果 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
- 如果此设备仍未验证,请为匹配的账户运行命令:
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 客户端完成自我验证:
在另一个 Matrix 客户端中接受请求,比较表情符号或十进制数,并且仅在它们匹配时输入 yes。该命令会等待完整的 Matrix 身份信任建立后才报告成功。
- 如果你有意放弃无法恢复的旧历史,并希望为未来消息建立新的备份基线,请运行:
仅当旧恢复密钥应停止解锁新备份时,才添加 --rotate-recovery-key。
- 如果尚不存在服务器端密钥备份,请为未来恢复创建一个:
常见消息及其含义¶
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 表情符号或十进制代码,并确认它们匹配。
相关¶
- Matrix:频道设置和配置。
- Matrix 推送规则:通知路由。
- Doctor:健康检查和自动迁移触发。
- 迁移指南:所有迁移路径(机器迁移、跨系统导入)。
- 插件:插件安装和注册。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw