从旧版 Matrix 插件升级到当前实现的指南。对大多数用户来说，升级是原地进行的，无需重命名配置键或重新安装插件。
升级后保持不变的内容
- 插件名：
@openclaw/matrix - channel 名：
matrix - 配置路径：
channels.matrix - 缓存凭证：
~/.openclaw/credentials/matrix/ - 运行时状态：
~/.openclaw/matrix/
自动迁移内容
Gateway 启动或运行 openclaw doctor --fix 时，OpenClaw 会自动：
- 在
~/Backups/openclaw-migrations/创建迁移前快照 - 复用缓存的 Matrix 凭证
- 将旧的 flat Matrix sync store 移至当前账号作用域位置
- 将旧的 flat Matrix crypto store 移至当前账号作用域位置
- 从旧 rust crypto store 提取 room-key backup 解密密钥
- 在下次 Matrix 启动时将备份的 room keys 恢复到新 crypto store
无法自动迁移的内容
- 从未备份的本地 room keys
- 目标 Matrix 账号无法解析时的加密状态（缺少
homeserver、userId或accessToken） - 配置了多个 Matrix 账号但未设置
channels.matrix.defaultAccount时的共享 flat store - 固定到自定义路径的插件安装
- 旧 store 有备份但本地没有解密密钥时
推荐升级流程
# 1. 更新 OpenClaw 和 Matrix 插件
openclaw update
# 2. 运行健康检查和自动修复
openclaw doctor --fix
# 3. 重启 gateway
openclaw gateway restart
# 4. 检查验证和备份状态
openclaw matrix verify status
openclaw matrix verify backup status
# 5. 如需恢复密钥，恢复 room keys
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin
# 6. 如设备仍未验证
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
# 7. 如需完成自我验证
openclaw matrix verify self
# 8. 如需重置备份基线（接受丢失不可恢复的历史）
openclaw matrix verify backup reset --yes常见消息含义
| 消息 | 含义 | 处理方式 |
|---|---|---|
Matrix plugin upgraded in place. | 旧状态已迁移 | 无需操作 |
Legacy Matrix state detected ... channels.matrix is not configured yet. | 旧状态存在但未配置 | 配置 channels.matrix 后重新运行 doctor --fix |
Legacy Matrix state detected ... multiple Matrix accounts ... defaultAccount is not set. | 多账号但无默认账号 | 设置 channels.matrix.defaultAccount |
matrix: restored X/Y room key(s) from legacy encrypted-state backup | room keys 恢复成功 | 通常无需操作 |
matrix: N legacy local-only room key(s) were never backed up | 部分旧 keys 无法恢复 | 预期部分旧加密历史不可读 |
加密历史仍无法恢复时
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若备份恢复成功但部分旧房间历史仍缺失，说明这些 keys 在旧插件中从未备份。
从头开始（放弃旧历史）
openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status相关链接
- channel-matrix - Matrix channel 配置
- channel-matrix-push-rules - Matrix 推送规则