Matrix 迁移指南

本页介绍从旧版公开 matrix 插件升级到当前实现的迁移细节。

对于大多数用户，升级是就地完成的：

插件名称仍是 @openclaw/matrix
渠道名称仍是 matrix
配置仍在 channels.matrix 下
缓存凭证仍在 ~/.openclaw/credentials/matrix/
运行时状态仍在 ~/.openclaw/matrix/

无需重命名配置键或以新名称重新安装插件。

自动迁移内容

Gateway 启动时，以及运行 openclaw doctor --fix 时，OpenClaw 会尝试自动修复旧的 Matrix 状态。在任何实质性的 Matrix 迁移步骤修改磁盘状态之前，OpenClaw 会创建或复用一个专注的恢复快照。

使用 openclaw update 时，具体触发时机取决于安装方式：

源码安装在更新流程中运行 openclaw doctor --fix，然后默认重启 Gateway
包管理器安装会更新包，运行非交互式 doctor 检查，然后依赖默认的 Gateway 重启来完成 Matrix 迁移
使用 openclaw update --no-restart 时，基于启动的 Matrix 迁移会推迟到稍后运行 openclaw doctor --fix 并重启 Gateway

自动迁移覆盖：

在 ~/Backups/openclaw-migrations/ 创建或复用迁移前快照
复用缓存的 Matrix 凭证
保持相同的账号选择和 channels.matrix 配置
将最旧的扁平 Matrix 同步存储迁移到当前账号范围的位置
在目标账号可安全解析的情况下，将最旧的扁平 Matrix 加密存储迁移到当前账号范围的位置
从旧 rust 加密存储中提取之前保存的 Matrix 房间密钥备份解密密钥（如果本地存在）
当访问令牌变更但账号/设备身份不变时，复用相同 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 插件没有自动创建 Matrix 房间密钥备份。它会持久化本地加密状态并请求设备验证，但不保证房间密钥已备份到 Homeserver。

这意味着某些加密安装只能部分迁移。

OpenClaw 无法自动恢复：

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

当前警告范围：

自定义 Matrix 插件路径安装会在 Gateway 启动和 openclaw doctor 中提示

如果旧安装有从未备份的本地加密历史，升级后部分旧的加密消息可能无法读取。

加密迁移工作原理

加密迁移是两阶段过程：

启动或 openclaw doctor --fix 在加密迁移可操作时创建或复用迁移前快照。
启动或 openclaw doctor --fix 通过活跃的 Matrix 插件安装检查旧的 Matrix 加密存储。
如果找到备份解密密钥，OpenClaw 将其写入新的恢复密钥流程并标记房间密钥恢复为待处理。
在下次 Matrix 启动时，OpenClaw 自动将备份的房间密钥恢复到新的加密存储。

如果旧存储报告有从未备份的房间密钥，OpenClaw 会警告而不是假装恢复成功。

常见消息及含义

升级和检测消息

Matrix plugin upgraded in place.

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

Matrix migration snapshot created before applying Matrix upgrades.

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

Matrix migration snapshot reused before applying Matrix upgrades.

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

Legacy Matrix state detected at ... but channels.matrix is not configured yet.

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

Legacy Matrix state detected at ... but the new account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).

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

Legacy Matrix state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.

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

Matrix legacy sync store not migrated because the target already exists (...)

含义：新的账号范围位置已有同步或加密存储，OpenClaw 不会自动覆盖。
处理：手动移除或移动冲突的目标前，先验证当前账号是否正确。

Failed migrating Matrix legacy sync store (...) 或 Failed migrating Matrix legacy crypto store (...)

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

Legacy Matrix encrypted state detected at ... but channels.matrix is not configured yet.

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

Legacy Matrix encrypted state detected at ... but the account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).

含义：加密存储存在，但 OpenClaw 无法安全确定它属于哪个当前账号/设备。
处理：用有效的 Matrix 登录状态启动一次 Gateway，或在缓存凭证可用后重新运行 openclaw doctor --fix。

Legacy Matrix encrypted state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.

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

Matrix migration warnings are present, but no on-disk Matrix mutation is actionable yet. No pre-migration snapshot was needed.

含义：OpenClaw 检测到旧的 Matrix 状态，但迁移仍因缺少身份或凭证数据而受阻。
处理：完成 Matrix 登录或配置设置，然后重新运行 openclaw doctor --fix 或重启 Gateway。

Legacy Matrix encrypted state was detected, but the Matrix plugin helper is unavailable. Install or repair @openclaw/matrix so OpenClaw can inspect the old rust crypto store before upgrading.

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

Matrix plugin helper path is unsafe: ... Reinstall @openclaw/matrix and try again.

含义：OpenClaw 发现辅助文件路径超出插件根目录或未通过插件边界检查，拒绝导入。
处理：从可信路径重新安装 Matrix 插件，然后重新运行 openclaw doctor --fix 或重启 Gateway。

- Failed creating a Matrix migration snapshot before repair: ...

- Skipping Matrix migration changes for now. Resolve the snapshot failure, then rerun "openclaw doctor --fix".

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

Failed migrating legacy Matrix client storage: ...

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

Matrix is installed from a custom path: ...

含义：Matrix 固定在路径安装，主线更新不会自动用仓库标准 Matrix 包替换它。
处理：需要回到默认 Matrix 插件时，用 openclaw plugins install @openclaw/matrix 重新安装。

加密状态恢复消息

matrix: restored X/Y room key(s) from legacy encrypted-state backup

含义：备份的房间密钥已成功恢复到新的加密存储。
处理：通常无需操作。

matrix: N legacy local-only room key(s) were never backed up and could not be restored automatically

含义：部分旧房间密钥只存在于旧的本地存储中，从未上传到 Matrix 备份。
处理：预期部分旧加密历史将不可访问，除非你能从其他已验证客户端手动恢复这些密钥。

Legacy Matrix encrypted state for account "..." has backed-up room keys, but no local backup decryption key was found. Ask the operator to run "openclaw matrix verify backup restore --recovery-key <key>" after upgrade if they have the recovery key.

含义：备份存在，但 OpenClaw 无法自动恢复恢复密钥。
处理：运行 openclaw matrix verify backup restore --recovery-key "<your-recovery-key>"。

Failed inspecting legacy Matrix encrypted state for account "..." (...): ...

含义：OpenClaw 找到旧的加密存储，但无法安全检查以准备恢复。
处理：重新运行 openclaw doctor --fix。如果持续出现，保持旧状态目录完整，使用另一个已验证的 Matrix 客户端加 openclaw matrix verify backup restore --recovery-key "<your-recovery-key>" 进行恢复。

Legacy Matrix backup key was found for account "...", but .../recovery-key.json already contains a different recovery key. Leaving the existing file unchanged.

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

Legacy Matrix encrypted state for account "..." cannot be fully converted automatically because the old rust crypto store does not expose all local room keys for export.

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

matrix: failed restoring room keys from legacy encrypted-state backup: ...

含义：新插件尝试恢复但 Matrix 返回了错误。
处理：运行 openclaw matrix verify backup status，如需要再用 openclaw matrix verify backup restore --recovery-key "<your-recovery-key>" 重试。

手动恢复消息

Backup key is not loaded on this device. Run 'openclaw matrix verify backup restore' to load it and restore old room keys.

含义：OpenClaw 知道你应该有备份密钥，但它在此设备上未激活。
处理：运行 openclaw matrix verify backup restore，如需要可加 --recovery-key。

Store a recovery key with 'openclaw matrix verify device <key>', then run 'openclaw matrix verify backup restore'.

含义：此设备当前没有存储的恢复密钥。
处理：先用你的恢复密钥验证设备，然后恢复备份。

Backup key mismatch on this device. Re-run 'openclaw matrix verify device <key>' with the matching recovery key.

含义：存储的密钥与活跃的 Matrix 备份不匹配。
处理：用正确的密钥重新运行 openclaw matrix verify device "<your-recovery-key>"。

如果你接受丢失无法恢复的旧加密历史，可以用 openclaw matrix verify backup reset --yes 重置当前备份基线。

Backup trust chain is not verified on this device. Re-run 'openclaw matrix verify device <key>'.

含义：备份存在，但此设备对交叉签名链的信任还不够强。
处理：重新运行 openclaw matrix verify device "<your-recovery-key>"。

Matrix recovery key is required

含义：你尝试了一个需要恢复密钥的恢复步骤，但未提供密钥。
处理：带上你的恢复密钥重新运行命令。

Invalid Matrix recovery key: ...

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

Matrix device is still unverified after applying recovery key. Verify your recovery key and ensure cross-signing is available.

含义：密钥已应用，但设备仍无法完成验证。
处理：确认使用了正确的密钥且账号上可用交叉签名，然后重试。

Matrix key backup is not active on this device after loading from secret storage.

含义：密钥存储未在此设备上产生活跃的备份会话。
处理：先验证设备，然后用 openclaw matrix verify backup status 重新检查。

Matrix crypto backend cannot load backup keys from secret storage. Verify this device with 'openclaw matrix verify device <key>' first.

含义：此设备在设备验证完成前无法从密钥存储恢复。
处理：先运行 openclaw matrix verify device "<your-recovery-key>"。

自定义插件安装消息

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

含义：你的插件安装记录指向一个已不存在的本地路径。
处理：用 openclaw plugins install @openclaw/matrix 重新安装，或仓库检出时用 openclaw plugins install ./extensions/matrix。

加密历史仍然无法恢复时

按顺序运行以下检查：

bash

openclaw matrix verify status --verbose
openclaw matrix verify backup status --verbose
openclaw matrix verify backup restore --recovery-key "<your-recovery-key>" --verbose

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

想要从头开始保存将来的消息

如果你接受丢失无法恢复的旧加密历史，只想要一个干净的前向备份基线，按顺序运行：

bash

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

如果设备在此之后仍未验证，通过你的 Matrix 客户端比对 SAS 表情符号或十进制码并确认匹配来完成验证。

Matrix 迁移指南

自动迁移内容

无法自动迁移的内容

推荐升级流程

加密迁移工作原理

常见消息及含义

升级和检测消息

加密状态恢复消息

手动恢复消息

自定义插件安装消息

加密历史仍然无法恢复时

想要从头开始保存将来的消息

相关页面

Matrix 迁移指南 ​

自动迁移内容 ​

无法自动迁移的内容 ​

推荐升级流程 ​

加密迁移工作原理 ​

常见消息及含义 ​

升级和检测消息 ​

加密状态恢复消息 ​

手动恢复消息 ​

自定义插件安装消息 ​

加密历史仍然无法恢复时 ​

想要从头开始保存将来的消息 ​

相关页面 ​

Matrix 迁移指南

自动迁移内容

无法自动迁移的内容

推荐升级流程

加密迁移工作原理

常见消息及含义

升级和检测消息

加密状态恢复消息

手动恢复消息

自定义插件安装消息

加密历史仍然无法恢复时

想要从头开始保存将来的消息

相关页面