# Matrix 迁移

> OpenClaw 如何就地升级先前的 Matrix 插件，包括加密状态恢复限制和手动恢复步骤。

- 网址：https://funcoding.ai/agents/openclaw/channels/matrix-migration/
- 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/channels/matrix-migration

---
从之前的公开 `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`](https://funcoding.ai/agents/openclaw/gateway/doctor/) 时会执行 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. 运行：

   ```bash
   openclaw doctor --fix
   ```

3. 启动或重启 Gateway 网关。
4. 检查当前验证和备份状态：

   ```bash
   openclaw matrix verify status
   openclaw matrix verify backup status
   ```

5. 将正在修复的 Matrix 账户的恢复密钥放入账户专用的环境变量中。对于单个默认账户，使用 `MATRIX_RECOVERY_KEY` 即可。对于多个账户，请为每个账户使用一个变量，例如 `MATRIX_RECOVERY_KEY_ASSISTANT`，并在命令中添加 `--account assistant`。

6. 如果 OpenClaw 提示需要恢复密钥，请对相应账户运行命令：

   ```bash
   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
   ```

7. 如果此设备仍未验证，请对相应账户运行命令：

   ```bash
   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 客户端完成自我验证：

   ```bash
   openclaw matrix verify self
   ```

   在另一个 Matrix 客户端中接受请求，比较表情符号或十进制数字，
   仅当它们匹配时才输入 `yes`。该命令会等待 Matrix
   身份获得完全信任后才报告成功。

8. 如果你有意放弃无法恢复的旧历史记录，并希望为未来消息建立全新的备份基线，请运行：

   ```bash
   openclaw matrix verify backup reset --yes
   ```

   仅当旧恢复密钥不应再能解锁新备份时，才添加 `--rotate-recovery-key`。

9. 如果尚不存在服务器端密钥备份，请创建一个，以便将来恢复：

   ```bash
   openclaw matrix verify bootstrap
   ```

## 常见消息及其含义

`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:` 指引：

| 备份问题                                                              | 含义                                               | 修复方法                                                                                                                                  |
| --------------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `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` 重置当前备份基线。当
存储的备份密钥损坏时，此重置操作还会修复密钥存储，以便
新备份密钥在重启后可以正确加载。

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

按顺序运行以下检查：

```bash
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
```

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

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

如果你接受丢失无法恢复的旧加密历史记录，并且只希望今后使用干净的备份基线，请按顺序运行以下命令：

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

如果之后设备仍未验证，请在 Matrix 客户端中比较 SAS 表情符号或十进制代码，并确认它们匹配，以完成验证。

## 相关内容

- [Matrix](https://funcoding.ai/agents/openclaw/channels/matrix/)：渠道设置和配置。
- [Matrix 推送规则](https://funcoding.ai/agents/openclaw/channels/matrix-push-rules/)：通知路由。
- [Doctor](https://funcoding.ai/agents/openclaw/gateway/doctor/)：健康检查和自动迁移触发器。
- [迁移指南](https://funcoding.ai/agents/openclaw/install/migrating/)：所有迁移路径（计算机迁移、跨系统导入）。
- [插件](https://funcoding.ai/agents/openclaw/tools/plugin/)：插件安装和注册。