openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-24 22:04:49 +00:00
parent c805c6bf30
commit 6ec6309792
2 changed files with 468 additions and 345 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

572
docs/zh-CN/channels/matrix.md
View File

@ -1,26 +1,26 @@
---
read_when:
- 在 OpenClaw 中设置 Matrix
- 配置 Matrix 端到端加密和验证
- 配置 Matrix E2EE 和验证
summary: Matrix 支持状态、设置和配置示例
title: Matrix
x-i18n:
generated_at: "2026-04-24T03:37:20Z"
generated_at: "2026-04-24T22:02:31Z"
model: gpt-5.4
provider: openai
source_hash: bf25a6f64ed310f33b72517ccd1526876e27caae240e9fa837a86ca2c392ab25
source_hash: 9e764c837f34131f20d1e912c059ffdce61421227a44b7f91faa624a6f878ed2
source_path: channels/matrix.md
workflow: 15
---
Matrix 是 OpenClaw 的一个内置渠道插件。
它使用官方 `matrix-js-sdk`，并支持私信、房间、线程、媒体、表情回应、投票、位置以及端到端加密（E2EE）。
Matrix 是 OpenClaw 的一个内置渠道插件。
它使用官方的 `matrix-js-sdk`，并支持私信、房间、线程、媒体、表情回应、投票、位置和 E2EE。
## 内置插件
Matrix 在当前的 OpenClaw 版本中作为内置插件提供，因此常规的打包构建不需要单独安装。
Matrix 在当前的 OpenClaw 版本中作为内置插件提供，因此普通的打包构建不需要单独安装。
如果你使用的是较旧的构建版本，或是不包含 Matrix 的自定义安装，请手动安装：
如果你使用的是较旧的构建版本，或者是排除了 Matrix 的自定义安装，请手动安装：
从 npm 安装：
@ -39,15 +39,15 @@ openclaw plugins install ./path/to/local/matrix-plugin
## 设置
1. 确保 Matrix 插件可用。
- 当前打包的 OpenClaw 版本已内置它。
- 较旧版本或自定义安装可使用上面的命令手动添加。
2. 在你的 homeserver 上创建一个 Matrix 账号。
- 当前打包发布的 OpenClaw 版本已内置它。
- 较旧版本或自定义安装可以使用上面的命令手动添加它。
2. 在你的 homeserver 上创建一个 Matrix 账户。
3. 使用以下任一方式配置 `channels.matrix`：
- `homeserver` + `accessToken`，或
- `homeserver` + `userId` + `password`。
4. 重启 Gateway 网关。
5. 与机器人发起私信，或将其邀请到房间中。
- 只有当 `channels.matrix.autoJoin` 允许时，新建的 Matrix 邀请才会生效。
5. 与机器人开始私信，或邀请它加入房间。
- 只有当 `channels.matrix.autoJoin` 允许时，新发出的 Matrix 邀请才会生效。
交互式设置路径：
@ -56,30 +56,30 @@ openclaw channels add
openclaw configure --section channels
```
Matrix 向导会询问：
Matrix 向导会询问以下内容：
- homeserver URL
- 认证方式：access token 或 password
- 用户 ID（仅密码认证时）
- 用户 ID（仅密码认证）
- 可选的设备名称
- 是否启用 E2EE
- 是否配置房间访问和邀请自动加入
向导的关键行为：
- 如果 Matrix 认证环境变量已存在，且该账号尚未在配置中保存认证信息，则向导会提供一个环境变量快捷方式，以便将认证信息保存在环境变量中。
- 账号名称会标准化为账号 ID。例如，`Ops Bot` 会变成 `ops-bot`。
- 私信允许列表条目可直接接受 `@user:server`；显示名称仅在实时目录查询找到唯一精确匹配时可用。
- 房间允许列表条目可直接接受房间 ID 和别名。优先使用 `!room:server` 或 `#alias:server`；未解析的名称在运行时进行允许列表解析时会被忽略。
- 在邀请自动加入的允许列表模式中，只能使用稳定的邀请目标：`!roomId:server`、`#alias:server` 或 `*`。普通房间名称会被拒绝。
- 如果 Matrix 认证环境变量已经存在，并且该账户的认证信息尚未保存在配置中，向导会提供一个环境变量快捷方式，以将认证信息保留在环境变量中。
- 账户名称会规范化为账户 ID。例如，`Ops Bot` 会变为 `ops-bot`。
- 私信允许列表条目可直接接受 `@user:server`；显示名称只有在实时目录查找能找到唯一精确匹配时才有效。
- 房间允许列表条目可直接接受房间 ID 和别名。优先使用 `!room:server` 或 `#alias:server`；无法解析的名称在运行时的允许列表解析中会被忽略。
- 在邀请自动加入的允许列表模式下，只能使用稳定的邀请目标：`!roomId:server`、`#alias:server` 或 `*`。纯房间名称会被拒绝。
- 若要在保存前解析房间名称，请使用 `openclaw channels resolve --channel matrix "Project Room"`。
<Warning>
`channels.matrix.autoJoin` 默认值为 `off`。
`channels.matrix.autoJoin` 的默认值是 `off`。
如果你不设置它，机器人将不会加入被邀请的房间或新建的私信式邀请，因此除非你先手动加入，否则它不会出现在新群组或受邀私信中。
如果你不设置它，机器人将不会加入被邀请的房间或新的私信式邀请，因此除非你先手动加入，否则它不会出现在新群组或被邀请的私信中。
设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，可限制它接受哪些邀请；或者设置 `autoJoin: "always"`，让它加入所有邀请。
设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist` 可限制它接受哪些邀请；如果你希望它加入每一个邀请，则设置 `autoJoin: "always"`。
在 `allowlist` 模式下，`autoJoinAllowlist` 只接受 `!roomId:server`、`#alias:server` 或 `*`。
</Warning>
@ -102,7 +102,7 @@ Matrix 向导会询问：
}
```
加入所有邀请：
加入每一个邀请：
```json5
{
@ -145,11 +145,11 @@ Matrix 向导会询问：
}
```
Matrix 会将缓存凭证存储在 `~/.openclaw/credentials/matrix/` 中。
默认账号使用 `credentials.json`；命名账号使用 `credentials-<account>.json`。
当该位置存在缓存凭证时，即使当前认证信息未直接写在配置中，OpenClaw 也会在设置、Doctor 和渠道状态发现中将 Matrix 视为已配置。
Matrix 会将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。
默认账户使用 `credentials.json`；命名账户使用 `credentials-<account>.json`。
如果那里存在缓存凭证，即使当前认证信息没有直接在配置中设置，OpenClaw 仍会在设置、Doctor 和渠道状态发现中将 Matrix 视为已配置。
对应的环境变量（仅当配置键未设置时使用）：
对应的环境变量（当配置键未设置时使用）：
- `MATRIX_HOMESERVER`
- `MATRIX_ACCESS_TOKEN`
@ -158,7 +158,7 @@ Matrix 会将缓存凭证存储在 `~/.openclaw/credentials/matrix/` 中。
- `MATRIX_DEVICE_ID`
- `MATRIX_DEVICE_NAME`
对于非默认账号，请使用账号作用域环境变量：
对于非默认账户，请使用带账户作用域的环境变量：
- `MATRIX_<ACCOUNT_ID>_HOMESERVER`
- `MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN`
@ -167,26 +167,26 @@ Matrix 会将缓存凭证存储在 `~/.openclaw/credentials/matrix/` 中。
- `MATRIX_<ACCOUNT_ID>_DEVICE_ID`
- `MATRIX_<ACCOUNT_ID>_DEVICE_NAME`
账号 `ops` 的示例：
账户 `ops` 的示例：
- `MATRIX_OPS_HOMESERVER`
- `MATRIX_OPS_ACCESS_TOKEN`
对于标准化账号 ID `ops-bot`，请使用：
对于规范化后的账户 ID `ops-bot`，请使用：
- `MATRIX_OPS_X2D_BOT_HOMESERVER`
- `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN`
Matrix 会对账号 ID 中的标点进行转义，以避免作用域环境变量发生冲突。
例如，`-` 会变成 `_X2D_`，因此 `ops-prod` 会映射为 `MATRIX_OPS_X2D_PROD_*`。
Matrix 会对账户 ID 中的标点进行转义，以避免带作用域的环境变量发生冲突。
例如，`-` 会变为 `_X2D_`，因此 `ops-prod` 会映射为 `MATRIX_OPS_X2D_PROD_*`。
只有当这些认证环境变量已存在，且所选账号尚未在配置中保存 Matrix 认证信息时，交互式向导才会提供环境变量快捷方式。
只有当这些认证环境变量已经存在，并且所选账户还没有在配置中保存 Matrix 认证信息时，交互式向导才会提供环境变量快捷方式。
`MATRIX_HOMESERVER` 不能通过工作区 `.env` 设置；请参阅 [Workspace `.env` files](/zh-CN/gateway/security)。
## 配置示例
这是一个实用的基础配置，启用了私信配对、房间允许列表和 E2EE：
这是一个实用的基线配置，启用了私信配对、房间允许列表和 E2EE：
```json5
{
@ -221,13 +221,13 @@ Matrix 会对账号 ID 中的标点进行转义，以避免作用域环境变量
}
```
`autoJoin` 适用于所有 Matrix 邀请，包括私信式邀请。OpenClaw 无法在邀请时可靠地将一个被邀请的房间分类为私信还是群组，因此所有邀请都会先经过 `autoJoin`。`dm.policy` 会在机器人加入后、并且该房间被分类为私信后才会生效。
`autoJoin` 适用于所有 Matrix 邀请，包括私信式邀请。OpenClaw 无法在邀请时可靠地将被邀请的房间分类为私信或群组，因此所有邀请都会先经过 `autoJoin`。`dm.policy` 会在机器人加入房间并且该房间被分类为私信后再生效。
## 流式预览
Matrix 回复流式传输为选择启用功能。
Matrix 回复流式传输是选择启用的。
当你希望 OpenClaw 发送一条实时预览回复、在模型生成文本时原地编辑该预览，并在回复完成时将其定稿，请将 `channels.matrix.streaming` 设置为 `"partial"`：
当你希望 OpenClaw 发送一条实时预览回复、在模型生成文本时原地编辑该预览，并在回复完成后将其定稿时，请将 `channels.matrix.streaming` 设置为 `"partial"`：
```json5
{
@ -240,31 +240,31 @@ Matrix 回复流式传输为选择启用功能。
```
- `streaming: "off"` 是默认值。OpenClaw 会等待最终回复并一次性发送。
- `streaming: "partial"` 会为当前 assistant block 创建一条可编辑的预览消息，使用普通 Matrix 文本消息。这会保留 Matrix 传统的“先预览后完成”通知行为，因此标准客户端可能会对第一段流式预览文本发出通知，而不是对最终完成的 block 发出通知。
- `streaming: "quiet"` 会为当前 assistant block 创建一条可编辑的静默预览通知。仅当你还为已定稿的预览编辑配置了接收方推送规则时才使用此选项。
- `blockStreaming: true` 会启用单独的 Matrix 进度消息。启用预览流式传输时，Matrix 会保留当前 block 的实时草稿，并将已完成的 block 保留为单独消息。
- 当预览流式传输开启且 `blockStreaming` 为关闭时，Matrix 会原地编辑实时草稿，并在 block 或整个轮次结束时定稿该同一事件。
- 如果预览内容不再适合放入单个 Matrix 事件中，OpenClaw 会停止预览流式传输，并回退到正常的最终发送方式。
- 媒体回复仍会正常发送附件。如果旧预览无法再被安全复用，OpenClaw 会先将其撤销标记，然后再发送最终的媒体回复。
- 预览编辑会增加额外的 Matrix API 调用。如果你想要最保守的速率限制行为，请保持关闭流式传输。
- `streaming: "partial"` 会为当前 assistant 块创建一条可编辑的预览消息，使用的是普通 Matrix 文本消息。这会保留 Matrix 旧式的“先预览后通知”行为，因此标准客户端可能会在第一次流式预览文本时发出通知，而不是在最终完成的块上通知。
- `streaming: "quiet"` 会为当前 assistant 块创建一条可编辑的静默预览通知。只有当你同时为最终定稿的预览编辑配置了接收方 push rules 时，才应使用此模式。
- `blockStreaming: true` 会启用单独的 Matrix 进度消息。启用预览流式传输后，Matrix 会为当前块保留实时草稿，并将已完成的块保留为单独的消息。
- 当预览流式传输开启且 `blockStreaming` 关闭时，Matrix 会原地编辑实时草稿，并在块或轮次结束时定稿同一个事件。
- 如果预览内容已无法容纳在单个 Matrix 事件中，OpenClaw 会停止预览流式传输并回退到普通的最终投递。
- 媒体回复仍会正常发送附件。如果某个过期的预览已无法安全复用，OpenClaw 会在发送最终媒体回复前将其撤销。
- 预览编辑会产生额外的 Matrix API 调用。如果你希望采用最保守的速率限制行为，请保持关闭流式传输。
`blockStreaming` 本身不会启用草稿预览。
使用 `streaming: "partial"` 或 `streaming: "quiet"` 进行预览编辑；然后仅在你还希望已完成的 assistant block 作为单独进度消息保留可见时，再添加 `blockStreaming: true`。
`blockStreaming` 本身不会启用草稿预览。
使用 `streaming: "partial"` 或 `streaming: "quiet"` 来启用预览编辑；如果你还希望已完成的 assistant 块保留为单独的进度消息，再额外设置 `blockStreaming: true`。
如果你需要标准 Matrix 通知而不想配置自定义推送规则，可使用 `streaming: "partial"` 以获得“先预览”行为，或保持 `streaming` 关闭以仅发送最终结果。对于 `streaming: "off"`：
如果你需要标准 Matrix 通知而不想使用自定义 push rules，请使用 `streaming: "partial"` 以获得“先预览后通知”的行为，或者保持 `streaming` 关闭以仅投递最终消息。使用 `streaming: "off"` 时：
- `blockStreaming: true` 会将每个已完成的 block 作为普通的 Matrix 通知消息发送。
- `blockStreaming: false` 只会将最终完整回复作为普通的 Matrix 通知消息发送。
- `blockStreaming: true` 会将每个已完成的块作为普通的可通知 Matrix 消息发送。
- `blockStreaming: false` 只会将最终完成的回复作为普通的可通知 Matrix 消息发送。
### 自托管静默定稿预览的推送规则
### 自托管的静默定稿预览 push rules
静默流式传输（`streaming: "quiet"`）只会在某个 block 或轮次定稿后通知接收方——必须有一条按用户设置的推送规则匹配该定稿预览标记。完整设置（接收方 token、pusher 检查、规则安装、各 homeserver 说明）请参阅 [Matrix push rules for quiet previews](/zh-CN/channels/matrix-push-rules)。
静默流式传输（`streaming: "quiet"`）只有在一个块或轮次定稿后才会通知接收者——必须有一条按用户生效的 push rule 匹配已定稿的预览标记。完整设置（接收方 token、pusher 检查、规则安装、各 homeserver 说明）请参阅 [Matrix push rules for quiet previews](/zh-CN/channels/matrix-push-rules)。
## 机器人到机器人房间
默认情况下，来自其他已配置 OpenClaw Matrix 账号的 Matrix 消息会被忽略。
默认情况下，来自其他已配置 OpenClaw Matrix 账户的 Matrix 消息会被忽略。
当你明确希望启用智能体之间的 Matrix 通信时，请使用 `allowBots`：
当你确实希望启用智能体之间的 Matrix 通信时，请使用 `allowBots`：
```json5
{
@ -281,17 +281,17 @@ Matrix 回复流式传输为选择启用功能。
}
```
- `allowBots: true` 会在允许的房间和私信中接受来自其他已配置 Matrix 机器人账号的消息。
- `allowBots: "mentions"` 仅当这些消息在房间中显式提到此机器人时才接受。私信仍然允许。
- `groups.<room>.allowBots` 会覆盖某个房间的账号级设置。
- OpenClaw 仍会忽略来自相同 Matrix 用户 ID 的消息，以避免自回复循环。
- Matrix 在这里不提供原生机器人标记；OpenClaw 将“机器人发送”定义为“由此 OpenClaw Gateway 网关上的另一个已配置 Matrix 账号发送”。
- `allowBots: true` 会在允许的房间和私信中接受来自其他已配置 Matrix 机器人账户的消息。
- `allowBots: "mentions"` 仅在这些消息在房间中明确提到该机器人时才接受。私信仍然允许。
- `groups.<room>.allowBots` 会覆盖单个房间的账户级设置。
- OpenClaw 仍会忽略来自同一个 Matrix 用户 ID 的消息，以避免自回复循环。
- Matrix 在这里不提供原生的机器人标记；OpenClaw 将“由机器人撰写”视为“由此 OpenClaw Gateway 网关上另一个已配置的 Matrix 账户发送”。
在共享房间中启用机器人到机器人通信时，请使用严格的房间允许列表和提及要求。
## 加密和验证
在加密（E2EE）房间中，出站图片事件会使用 `thumbnail_file`，以便图片预览与完整附件一同加密。未加密房间仍使用普通的 `thumbnail_url`。无需任何配置——插件会自动检测 E2EE 状态。
在加密的（E2EE）房间中，出站图片事件会使用 `thumbnail_file`，这样图片预览会与完整附件一起加密。未加密房间仍使用普通的 `thumbnail_url`。无需任何配置——该插件会自动检测 E2EE 状态。
启用加密：
@ -309,22 +309,131 @@ Matrix 回复流式传输为选择启用功能。
}
```
验证命令（全部支持使用 `--verbose` 输出诊断信息，并支持使用 `--json` 输出机器可读结果）：
验证命令（全部支持 `--verbose` 用于诊断，支持 `--json` 用于机器可读输出）：
| 命令 | 用途 |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `openclaw matrix verify status` | 检查交叉签名和设备验证状态 |
| `openclaw matrix verify status --include-recovery-key --json` | 包含已存储的恢复密钥 |
| `openclaw matrix verify bootstrap` | 初始化交叉签名和验证（见下文） |
| `openclaw matrix verify bootstrap --force-reset-cross-signing` | 丢弃当前交叉签名身份并创建新的身份 |
| `openclaw matrix verify device "<recovery-key>"` | 使用恢复密钥验证此设备 |
| `openclaw matrix verify backup status` | 检查房间密钥备份健康状态 |
| `openclaw matrix verify backup restore` | 从服务器备份恢复房间密钥 |
| `openclaw matrix verify backup reset --yes` | 删除当前备份并创建全新基线（可能会重新创建 secret storage） |
```bash
openclaw matrix verify status
```
在多账号设置中，除非你传入 `--account <id>`，否则 Matrix CLI 命令会使用隐式的 Matrix 默认账号。
如果你配置了多个命名账号，请先设置 `channels.matrix.defaultAccount`，否则这些隐式 CLI 操作会停止并要求你显式选择一个账号。
当你希望验证或设备操作明确针对某个命名账号时，请使用 `--account`：
详细状态（完整诊断）：
```bash
openclaw matrix verify status --verbose
```
在机器可读输出中包含已存储的恢复密钥：
```bash
openclaw matrix verify status --include-recovery-key --json
```
引导 cross-signing 和验证状态：
```bash
openclaw matrix verify bootstrap
```
详细引导诊断：
```bash
openclaw matrix verify bootstrap --verbose
```
在引导前强制执行一次全新的 cross-signing 身份重置：
```bash
openclaw matrix verify bootstrap --force-reset-cross-signing
```
使用恢复密钥验证此设备：
```bash
openclaw matrix verify device "<your-recovery-key>"
```
此命令会报告三个独立状态：
- `Recovery key accepted`：Matrix 已接受该恢复密钥，可用于秘密存储或设备信任。
- `Backup usable`：可以使用受信任的恢复材料加载房间密钥备份。
- `Device verified by owner`：当前 OpenClaw 设备已获得完整的 Matrix cross-signing 身份信任。
详细输出或 JSON 输出中的 `Signed by owner` 仅用于诊断。除非 `Cross-signing verified` 也是 `yes`，否则 OpenClaw 不会将其视为充分条件。
即使恢复密钥可以解锁备份材料，只要完整的 Matrix 身份信任尚未完成，该命令仍会以非零状态退出。
在这种情况下，请从另一个 Matrix 客户端完成自我验证：
```bash
openclaw matrix verify self
```
在另一个 Matrix 客户端中接受请求，比较 SAS 表情符号或数字，
仅在它们匹配时输入 `yes`。该命令会等待 Matrix 报告
`Cross-signing verified: yes` 后才会成功退出。
仅当你明确希望替换当前的 cross-signing 身份时，
才使用 `verify bootstrap --force-reset-cross-signing`。
详细设备验证信息：
```bash
openclaw matrix verify device "<your-recovery-key>" --verbose
```
检查房间密钥备份健康状态：
```bash
openclaw matrix verify backup status
```
详细备份健康状态诊断：
```bash
openclaw matrix verify backup status --verbose
```
从服务器备份恢复房间密钥：
```bash
openclaw matrix verify backup restore
```
交互式自我验证流程：
```bash
openclaw matrix verify self
```
对于更底层或入站的验证请求，请使用：
```bash
openclaw matrix verify accept <id>
openclaw matrix verify start <id>
openclaw matrix verify sas <id>
openclaw matrix verify confirm-sas <id>
```
使用 `openclaw matrix verify cancel <id>` 取消请求。
详细恢复诊断：
```bash
openclaw matrix verify backup restore --verbose
```
删除当前服务器备份并创建一个全新的备份基线。如果存储的
备份密钥无法被干净地加载，此重置还可以重新创建秘密存储，以便
未来冷启动时能够加载新的备份密钥：
```bash
openclaw matrix verify backup reset --yes
```
默认情况下，所有 `verify` 命令都保持简洁（包括安静的内部 SDK 日志），只有在使用 `--verbose` 时才显示详细诊断信息。
编写脚本时请使用 `--json` 获取完整的机器可读输出。
在多账户设置中，除非你传入 `--account <id>`，否则 Matrix CLI 命令会使用隐式的 Matrix 默认账户。
如果你配置了多个命名账户，请先设置 `channels.matrix.defaultAccount`，否则这些隐式 CLI 操作将停止并要求你显式选择一个账户。
当你希望验证或设备操作明确指向某个命名账户时，请使用 `--account`：
```bash
openclaw matrix verify status --account assistant
@ -332,29 +441,31 @@ openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant
```
当某个命名账号未启用加密或无法使用加密时，Matrix 警告和验证错误会指向该账号的配置键，例如 `channels.matrix.accounts.assistant.encryption`。
当某个命名账户的加密被禁用或不可用时，Matrix 警告和验证错误会指向该账户的配置键，例如 `channels.matrix.accounts.assistant.encryption`。
<AccordionGroup>
<Accordion title="已验证意味着什么">
只有当你自己的交叉签名身份对某个设备进行了签名时，OpenClaw 才会将其视为已验证。`verify status --verbose` 会显示三个信任信号：
<Accordion title="验证的含义">
只有当你自己的 cross-signing 身份对设备进行签名时，OpenClaw 才会将该设备视为已验证。`verify status --verbose` 会显示三个信任信号：
- `Locally trusted`：仅被此客户端本地信任
- `Cross-signing verified`：SDK 报告该设备已通过交叉签名验证
- `Signed by owner`：已由你自己的 self-signing key 签名
- `Locally trusted`：仅被此客户端信任
- `Cross-signing verified`：SDK 报告该设备已通过 cross-signing 验证
- `Signed by owner`：已由你自己的 self-signing 密钥签名
只有存在交叉签名或所有者签名时，`Verified by owner` 才会变为 `yes`。仅有本地信任还不够。
只有在存在 cross-signing 验证时，`Verified by owner` 才会变为 `yes`。
仅有本地信任或所有者签名本身，都不足以让 OpenClaw 将
该设备视为完全已验证。
</Accordion>
<Accordion title="bootstrap 会做什么">
`verify bootstrap` 是加密账号的修复和设置命令。按顺序，它会：
<Accordion title="bootstrap 的作用">
`verify bootstrap` 是加密账户的修复和设置命令。按顺序，它会：
- 初始化 secret storage，并在可能时复用现有恢复密钥
- 初始化交叉签名并上传缺失的公开交叉签名密钥
- 标记并交叉签名当前设备
- 引导秘密存储，并在可能时复用现有恢复密钥
- 引导 cross-signing，并上传缺失的公开 cross-signing 密钥
- 标记并进行当前设备的 cross-signing
- 如果服务器端房间密钥备份尚不存在，则创建一个
如果 homeserver 在上传交叉签名密钥时要求 UIA，OpenClaw 会先尝试无认证方式，然后尝试 `m.login.dummy`，再尝试 `m.login.password`（需要 `channels.matrix.password`）。仅当你明确要丢弃当前身份时，才使用 `--force-reset-cross-signing`。
如果 homeserver 需要 UIA 才能上传 cross-signing 密钥，OpenClaw 会先尝试无认证，然后尝试 `m.login.dummy`，再尝试 `m.login.password`（需要 `channels.matrix.password`）。只有在你明确要丢弃当前身份时，才使用 `--force-reset-cross-signing`。
</Accordion>
@ -367,30 +478,30 @@ openclaw matrix verify backup status --verbose
openclaw matrix verify status
```
添加 `--account <id>` 以指定某个命名账号。这也可能在当前备份 secret 无法安全加载时重新创建 secret storage。
添加 `--account <id>` 以指向某个命名账户。如果当前备份秘密无法安全加载，这也可以重新创建秘密存储。
</Accordion>
<Accordion title="启动行为">
当设置 `encryption: true` 时，`startupVerification` 默认值为 `"if-unverified"`。启动时，未验证设备会在另一个 Matrix 客户端中请求自我验证，同时跳过重复请求并应用冷却时间。可使用 `startupVerificationCooldownHours` 调整，或使用 `startupVerification: "off"` 禁用。
当 `encryption: true` 时，`startupVerification` 默认值为 `"if-unverified"`。启动时，未验证的设备会在另一个 Matrix 客户端中请求自我验证，同时跳过重复请求并应用冷却时间。可使用 `startupVerificationCooldownHours` 调整，或使用 `startupVerification: "off"` 禁用。
启动时还会运行一次保守的加密 bootstrap 流程，复用当前的 secret storage 和交叉签名身份。如果 bootstrap 状态损坏，即使没有 `channels.matrix.password`，OpenClaw 也会尝试进行受保护的修复；如果 homeserver 需要密码 UIA，启动时会记录警告，但不会导致致命错误。已由所有者签名的设备会被保留。
启动时还会运行一次保守的加密 bootstrap 检查，复用当前的秘密存储和 cross-signing 身份。如果 bootstrap 状态已损坏，即使没有 `channels.matrix.password`，OpenClaw 也会尝试受保护的修复；如果 homeserver 需要密码 UIA，启动时会记录一条警告，但不会导致致命错误。已由所有者签名的设备会被保留。
完整升级流程请参阅 [Matrix migration](/zh-CN/install/migrating-matrix)。
</Accordion>
<Accordion title="验证通知">
Matrix 会将验证生命周期通知作为 `m.notice` 消息发布到严格的私信验证房间中：请求、就绪（附带“通过 emoji 验证”的说明）、开始/完成，以及在可用时提供 SAS（emoji/十进制）详细信息。
Matrix 会将验证生命周期通知作为 `m.notice` 消息发布到严格私信验证房间中：请求、就绪（包含“通过表情符号验证”的指引）、开始/完成，以及可用时的 SAS（表情符号/数字）详情。
来自另一个 Matrix 客户端的传入请求会被跟踪并自动接受。对于自我验证，OpenClaw 会在 emoji 验证可用后自动启动 SAS 流程并确认自己这一侧——你仍然需要在你的 Matrix 客户端中比较并确认“它们匹配”。
来自另一个 Matrix 客户端的入站请求会被跟踪并自动接受。对于自我验证，OpenClaw 会在表情符号验证可用时自动启动 SAS 流程并确认自己这一侧——你仍然需要在你的 Matrix 客户端中比较并确认“它们匹配”。
验证系统通知不会转发到智能体聊天流水线。
</Accordion>
<Accordion title="设备清理">
旧的 OpenClaw 管理设备可能会不断累积。可列出并清理：
旧的由 OpenClaw 管理的设备可能会逐渐累积。列出并清理：
```bash
openclaw matrix devices list
@ -400,66 +511,65 @@ openclaw matrix devices prune-stale
</Accordion>
<Accordion title="加密存储">
Matrix E2EE 使用官方 `matrix-js-sdk` Rust 加密路径，并以 `fake-indexeddb` 作为 IndexedDB shim。加密状态会持久化到 `crypto-idb-snapshot.json`（文件权限受限）。
Matrix E2EE 使用官方 `matrix-js-sdk` 的 Rust 加密路径，并使用 `fake-indexeddb` 作为 IndexedDB shim。加密状态会持久化到 `crypto-idb-snapshot.json`（限制性文件权限）。
加密运行时状态位于 `~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/` 下，其中包括 sync store、crypto store、恢复密钥、IDB 快照、线程绑定和启动验证状态。当 token 变化但账号身份保持不变时，OpenClaw 会复用现有的最佳根目录，因此先前状态仍然可见。
加密运行时状态位于 `~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/` 下，其中包括同步存储、加密存储、恢复密钥、IDB 快照、线程绑定和启动验证状态。当 token 变化但账户身份保持不变时，OpenClaw 会复用最佳的现有根目录，以便先前状态仍然可见。
</Accordion>
</AccordionGroup>
## 配置文件管理
## 资料管理
使用以下命令更新所选账号的 Matrix 自身资料：
使用以下命令更新所选账户的 Matrix 自我资料：
```bash
openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png
```
如果你想显式针对某个命名 Matrix 账号，请添加 `--account <id>`。
当你希望明确指向某个命名 Matrix 账户时，请添加 `--account <id>`。
Matrix 可直接接受 `mxc://` 头像 URL。
当你传入 `http://` 或 `https://` 头像 URL 时，OpenClaw 会先将其上传到 Matrix，然后将解析后的 `mxc://` URL 回写到 `channels.matrix.avatarUrl`（或所选账号的覆盖配置）中。
Matrix 可直接接受 `mxc://` 头像 URL。当你传入 `http://` 或 `https://` 头像 URL 时，OpenClaw 会先将其上传到 Matrix，然后将解析后的 `mxc://` URL 回写到 `channels.matrix.avatarUrl`（或所选账户的覆盖配置）中。
## 线程
Matrix 同时支持自动回复和 message-tool 发送的原生 Matrix 线程。
Matrix 支持原生 Matrix 线程，既可用于自动回复，也可用于 message-tool 发送。
- `dm.sessionScope: "per-user"`（默认）会让 Matrix 私信路由保持按发送者作用域，因此多个私信房间在解析到同一对端时可以共享一个会话。
- `dm.sessionScope: "per-room"` 会将每个 Matrix 私信房间隔离到各自独立的会话键中，同时仍使用普通私信认证和允许列表检查。
- 显式 Matrix 会话绑定仍然优先于 `dm.sessionScope`，因此已绑定的房间和线程会继续保持其所选目标会话。
- `threadReplies: "off"` 会让回复保持在顶层，并将传入的线程消息保留在父会话上。
- `threadReplies: "inbound"` 仅当传入消息已经位于某个线程中时，才在线程内回复。
- `threadReplies: "always"` 会将房间回复保持在线程中，该线程以触发消息为根，并从第一条触发消息起，通过匹配的线程作用域会话路由该会话。
- `dm.threadReplies` 仅覆盖私信的顶层设置。例如，你可以让房间线程保持隔离，同时让私信保持扁平化。
- 传入的线程消息会将线程根消息作为额外智能体上下文包含进来。
- 当目标是同一房间或同一私信用户目标时，message-tool 发送会自动继承当前 Matrix 线程，除非显式提供了 `threadId`。
- 仅当当前会话元数据能证明是同一 Matrix 账号上的同一私信对端时，才会启用同会话私信用户目标复用；否则 OpenClaw 会回退到普通的按用户作用域路由。
- 当 OpenClaw 发现一个 Matrix 私信房间与同一共享 Matrix 私信会话上的另一个私信房间发生冲突时，如果启用了线程绑定并设置了 `dm.sessionScope` 提示，它会在该房间中发布一次性的 `m.notice`，附带 `/focus` 逃生入口。
- Matrix 支持运行时线程绑定。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及线程绑定的 `/acp spawn` 可在 Matrix 房间和私信中使用。
- `dm.sessionScope: "per-user"`（默认）会让 Matrix 私信路由保持为发送方作用域，因此多个私信房间在解析到同一对端时可以共享一个会话。
- `dm.sessionScope: "per-room"` 会将每个 Matrix 私信房间隔离到其各自的会话键中，同时仍使用普通的私信认证和允许列表检查。
- 显式的 Matrix 会话绑定仍然优先于 `dm.sessionScope`，因此已绑定的房间和线程会继续使用其选定的目标会话。
- `threadReplies: "off"` 会让回复保持在顶层，并使入站线程消息继续使用父级会话。
- `threadReplies: "inbound"` 仅当入站消息本身已经位于某个线程中时，才在线程内回复。
- `threadReplies: "always"` 会将房间回复保持在线程中，并以触发消息为根，同时从第一条触发消息开始，通过匹配的线程作用域会话来路由该对话。
- `dm.threadReplies` 仅覆盖私信的顶层设置。例如，你可以让房间线程保持隔离，同时让私信保持扁平。
- 入站线程消息会将线程根消息作为额外的智能体上下文一并包含。
- 当目标是同一房间，或同一私信用户目标时，message-tool 发送会自动继承当前 Matrix 线程，除非显式提供了 `threadId`。
- 只有当当前会话元数据能证明这是同一 Matrix 账户上的同一私信对端时，才会启用同会话私信用户目标复用；否则 OpenClaw 会回退到普通的按用户作用域路由。
- 当 OpenClaw 发现某个 Matrix 私信房间与另一个私信房间在同一个共享 Matrix 私信会话上发生冲突时，如果启用了线程绑定，并且提供了 `dm.sessionScope` 提示，它会在该房间中发布一次性的 `m.notice`，提示可使用 `/focus` 逃生口。
- Matrix 支持运行时线程绑定。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 和绑定到线程的 `/acp spawn` 都可在 Matrix 房间和私信中使用。
- 当 `threadBindings.spawnSubagentSessions=true` 时，顶层 Matrix 房间/私信中的 `/focus` 会创建一个新的 Matrix 线程，并将其绑定到目标会话。
- 在现有 Matrix 线程中运行 `/focus` 或 `/acp spawn --thread here`，则会改为绑定当前线程本身。
- 在现有 Matrix 线程中运行 `/focus` 或 `/acp spawn --thread here` 时，则会绑定当前线程本身。
## ACP 会话绑定
Matrix 房间、私信和现有 Matrix 线程都可以变成持久化的 ACP 工作区，而无需改变聊天界面。
Matrix 房间、私信和现有 Matrix 线程都可以变为持久的 ACP 工作区，而无需改变聊天界面。
快速操作流程：
- 在你想继续使用的 Matrix 私信、房间或现有线程中运行 `/acp spawn codex --bind here`。
- 在顶层 Matrix 私信或房间中，当前私信/房间会继续作为聊天界面，后续消息将路由到新建的 ACP 会话。
- 在现有线程中，`--bind here` 会将该当前线程原地绑定。
- `/new` 和 `/reset` 会原地重置同一个已绑定 ACP 会话。
- 在顶层 Matrix 私信或房间中，当前私信/房间会保持为聊天界面，后续消息将路由到新建的 ACP 会话。
- 在现有线程中，`--bind here` 会将当前线程原地绑定。
- `/new` 和 `/reset` 会原地重置同一个已绑定的 ACP 会话。
- `/acp close` 会关闭 ACP 会话并移除绑定。
说明：
- `--bind here` 不会创建子 Matrix 线程。
- 只有在 `/acp spawn --thread auto|here` 场景下，才需要 `threadBindings.spawnAcpSessions`，因为此时 OpenClaw 需要创建或绑定一个子 Matrix 线程。
- `threadBindings.spawnAcpSessions` 仅在 `/acp spawn --thread auto|here` 时需要，因为此时 OpenClaw 需要创建或绑定一个子 Matrix 线程。
### 线程绑定配置
Matrix 会继承来自 `session.threadBindings` 的全局默认值，同时也支持每渠道覆盖：
Matrix 会继承 `session.threadBindings` 中的全局默认值，同时也支持按渠道覆盖：
- `threadBindings.enabled`
- `threadBindings.idleHours`
@ -469,27 +579,27 @@ Matrix 会继承来自 `session.threadBindings` 的全局默认值，同时也
Matrix 线程绑定的 spawn 标志为选择启用：
- 设置 `threadBindings.spawnSubagentSessions: true`，允许顶层 `/focus` 创建并绑定新的 Matrix 线程。
- 设置 `threadBindings.spawnAcpSessions: true`，允许 `/acp spawn --thread auto|here` 将 ACP 会话绑定到 Matrix 线程。
- 设置 `threadBindings.spawnSubagentSessions: true`，以允许顶层 `/focus` 创建并绑定新的 Matrix 线程。
- 设置 `threadBindings.spawnAcpSessions: true`，以允许 `/acp spawn --thread auto|here` 将 ACP 会话绑定到 Matrix 线程。
## 表情回应
Matrix 支持出站表情回应操作、入站表情回应通知和入站 ack 表情回应。
Matrix 支持出站表情回应操作、入站表情回应通知和入站确认表情回应。
- 出站表情回应工具功能由 `channels["matrix"].actions.reactions` 控制。
- `react` 会向指定 Matrix 事件添加一个表情回应。
- `reactions` 会列出指定 Matrix 事件当前的表情回应摘要。
- `emoji=""` 会移除机器人账号在该事件上的所有自身表情回应。
- `remove: true` 仅移除机器人账号上的指定 emoji 表情回应。
- 出站表情回应工具受 `channels["matrix"].actions.reactions` 控制。
- `react` 会向特定 Matrix 事件添加一个表情回应。
- `reactions` 会列出特定 Matrix 事件当前的表情回应摘要。
- `emoji=""` 会移除机器人账户自己在该事件上的所有表情回应。
- `remove: true` 只会移除机器人账户在该事件上的指定表情回应。
ack 表情回应使用标准 OpenClaw 解析顺序：
确认表情回应使用标准的 OpenClaw 解析顺序：
- `channels["matrix"].accounts.<accountId>.ackReaction`
- `channels["matrix"].ackReaction`
- `messages.ackReaction`
- 智能体身份 emoji 回退值
ack 表情回应范围按以下顺序解析：
确认表情回应作用域按以下顺序解析：
- `channels["matrix"].accounts.<accountId>.ackReactionScope`
- `channels["matrix"].ackReactionScope`
@ -503,28 +613,28 @@ ack 表情回应范围按以下顺序解析：
行为：
- `reactionNotifications: "own"` 会在新增的 `m.reaction` 事件针对机器人编写的 Matrix 消息时转发这些事件。
- `reactionNotifications: "own"` 会在目标为机器人撰写的 Matrix 消息时，转发已添加的 `m.reaction` 事件。
- `reactionNotifications: "off"` 会禁用表情回应系统事件。
- 表情回应移除不会被合成为系统事件，因为 Matrix 将其表现为 redaction，而不是独立的 `m.reaction` 移除事件。
- 表情回应移除不会被合成为系统事件，因为 Matrix 将其显示为 redaction，而不是独立的 `m.reaction` 移除事件。
## 历史上下文
- `channels.matrix.historyLimit` 控制当 Matrix 房间消息触发智能体时，作为 `InboundHistory` 包含多少条最近的房间消息。它会回退到 `messages.groupChat.historyLimit`；如果两者都未设置，则实际默认值为 `0`。设置为 `0` 可禁用。
- Matrix 房间历史仅限房间。私信仍使用正常的会话历史。
- Matrix 房间历史是“仅待处理”模式：OpenClaw 会缓冲那些尚未触发回复的房间消息，然后在提及或其他触发到来时对该窗口进行快照。
- 当前触发消息不会包含在 `InboundHistory` 中；在该轮中，它会保留在主入站正文里。
- 对同一个 Matrix 事件的重试会复用原始历史快照，而不会漂移到较新的房间消息。
- `channels.matrix.historyLimit` 控制当 Matrix 房间消息触发智能体时，有多少条最近的房间消息会作为 `InboundHistory` 包含进来。它会回退到 `messages.groupChat.historyLimit`；如果两者都未设置，则有效默认值为 `0`。设置为 `0` 可禁用。
- Matrix 房间历史仅限房间。私信仍继续使用普通会话历史。
- Matrix 房间历史采用仅待处理模式：OpenClaw 会缓冲尚未触发回复的房间消息，然后在提及或其他触发到来时对该窗口进行快照。
- 当前触发消息不会包含在 `InboundHistory` 中；该消息会保留在本轮的主入站正文中。
- 对同一 Matrix 事件的重试会复用原始历史快照，而不是漂移到更新的房间消息。
## 上下文可见性
Matrix 支持共享的 `contextVisibility` 控制，用于补充房间上下文，例如获取到的回复文本、线程根消息和待处理历史。
Matrix 支持共享的 `contextVisibility` 控制，用于管理补充房间上下文，例如获取到的回复文本、线程根消息和待处理历史。
- `contextVisibility: "all"` 是默认值。补充上下文会按接收时原样保留。
- `contextVisibility: "all"` 是默认值。补充上下文会按接收时的样子保留。
- `contextVisibility: "allowlist"` 会将补充上下文过滤为仅保留通过当前房间/用户允许列表检查的发送者内容。
- `contextVisibility: "allowlist_quote"` 的行为类似 `allowlist`，但仍会保留一条显式引用回复。
- `contextVisibility: "allowlist_quote"` 的行为与 `allowlist` 相同，但仍会保留一条显式引用的回复。
此设置影响的是补充上下文的可见性，而不是入站消息本身是否可以触发回复。
触发授权仍由 `groupPolicy`、`groups`、`groupAllowFrom` 和私信策略设置决定。
此设置影响的是补充上下文的可见性，而不是入站消息本身是否可以触发回复。
触发授权仍来自 `groupPolicy`、`groups`、`groupAllowFrom` 和私信策略设置。
## 私信和房间策略
@ -551,20 +661,20 @@ Matrix 支持共享的 `contextVisibility` 控制，用于补充房间上下文
有关提及门控和允许列表行为，请参阅 [Groups](/zh-CN/channels/groups)。
Matrix 私信配对示例：
Matrix 私信的配对示例：
```bash
openclaw pairing list matrix
openclaw pairing approve matrix <CODE>
```
如果某个未获批准的 Matrix 用户在获批前持续给你发消息，OpenClaw 会复用同一个待处理配对码，并且在短暂冷却后可能再次发送提醒回复，而不是生成新的配对码。
如果某个尚未获批的 Matrix 用户在获批前持续向你发送消息，OpenClaw 会复用同一个待处理配对码，并且可能会在短暂冷却后再次发送提醒回复，而不是生成新的配对码。
共享的私信配对流程和存储布局请参阅 [Pairing](/zh-CN/channels/pairing)。
有关共享的私信配对流程和存储布局，请参阅 [Pairing](/zh-CN/channels/pairing)。
## 直连房间修复
## 直接房间修复
如果直连消息状态不同步，OpenClaw 可能会留下过时的 `m.direct` 映射，指向旧的单人房间而不是当前正在使用的私信。使用以下命令查看某个对端的当前映射：
如果私信状态不同步，OpenClaw 可能会留下过时的 `m.direct` 映射，将其指向旧的单独房间，而不是当前有效的私信。可使用以下命令检查某个对端的当前映射：
```bash
openclaw matrix direct inspect --user-id @alice:example.org
@ -578,48 +688,49 @@ openclaw matrix direct repair --user-id @alice:example.org
修复流程：
- 优先选择已经在 `m.direct` 中映射的严格 1:1 私信
- 优先选择已在 `m.direct` 中映射的严格 1:1 私信
- 如果没有，则回退到当前已加入的、与该用户的任意严格 1:1 私信
- 如果不存在健康的私信，则创建一个新的直连房间并重写 `m.direct`
- 如果不存在健康的私信，则创建一个新的直接房间并重写 `m.direct`
修复流程不会自动删除旧房间。它只会选出健康的私信并更新映射，以便新的 Matrix 发送、验证通知和其他直连消息流程再次定位到正确的房间。
修复流程不会自动删除旧房间。它只会选出健康的私信并更新映射，以便新的 Matrix 发送、验证通知和其他私信流程再次指向正确的房间。
## Exec 审批
## Exec approvals
Matrix 可以作为 Matrix 账号的原生审批客户端。原生私信/渠道路由控制项仍位于 exec 审批配置下：
Matrix 可以作为某个 Matrix 账户的原生审批客户端。原生的
私信/渠道路由控制仍位于 exec approval 配置下：
- `channels.matrix.execApprovals.enabled`
- `channels.matrix.execApprovals.approvers`（可选；会回退到 `channels.matrix.dm.allowFrom`）
- `channels.matrix.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`）
- `channels.matrix.execApprovals.approvers`（可选；回退到 `channels.matrix.dm.allowFrom`）
- `channels.matrix.execApprovals.target`（`dm` | `channel` | `both`，默认值：`dm`）
- `channels.matrix.execApprovals.agentFilter`
- `channels.matrix.execApprovals.sessionFilter`
审批人必须是 Matrix 用户 ID，例如 `@owner:example.org`。当 `enabled` 未设置或为 `"auto"`，且至少有一个审批人可解析时，Matrix 会自动启用原生审批。Exec 审批会优先使用 `execApprovals.approvers`，并可回退到 `channels.matrix.dm.allowFrom`。插件审批则通过 `channels.matrix.dm.allowFrom` 授权。设置 `enabled: false` 可显式禁用 Matrix 作为原生审批客户端。否则，审批请求会回退到其他已配置的审批路由或审批回退策略。
审批人必须是 Matrix 用户 ID，例如 `@owner:example.org`。当 `enabled` 未设置或为 `"auto"`，且至少有一个审批人可被解析时，Matrix 会自动启用原生审批。Exec approvals 会优先使用 `execApprovals.approvers`，并且可以回退到 `channels.matrix.dm.allowFrom`。插件审批通过 `channels.matrix.dm.allowFrom` 进行授权。设置 `enabled: false` 可显式禁用 Matrix 作为原生审批客户端。否则，审批请求会回退到其他已配置的审批路由或审批回退策略。
Matrix 原生路由支持两种审批类型：
Matrix 原生路由同时支持两种审批类型：
- `channels.matrix.execApprovals.*` 控制 Matrix 审批提示的原生私信/渠道扇出模式。
- Exec 审批使用来自 `execApprovals.approvers` 或 `channels.matrix.dm.allowFrom` 的 exec 审批人集合。
- 插件审批使用来自 `channels.matrix.dm.allowFrom` 的 Matrix 私信允许列表。
- Matrix 表情回应快捷方式和消息更新适用于 exec 审批和插件审批。
- Exec approvals 使用来自 `execApprovals.approvers` 或 `channels.matrix.dm.allowFrom` 的 exec 审批人集合。
- 插件审批使用 `channels.matrix.dm.allowFrom` 中的 Matrix 私信允许列表。
- Matrix 表情回应快捷方式和消息更新同时适用于 exec 和插件审批。
发送规则：
投递规则：
- `target: "dm"` 会将审批提示发送到审批人的私信
- `target: "channel"` 会将提示发回到原始 Matrix 房间或私信
- `target: "both"` 会同时发送到审批人的私信和原始 Matrix 房间或私信
- `target: "channel"` 会将提示发回到发起的 Matrix 房间或私信
- `target: "both"` 会同时发送到审批人的私信以及发起的 Matrix 房间或私信
Matrix 审批提示会在主审批消息上预置表情回应快捷方式：
Matrix 审批提示会在主审批消息上植入表情回应快捷方式：
- `✅` = 允许一次
- `❌` = 拒绝
- `♾️` = 当该决定被当前生效的 exec 策略允许时，始终允许
- `♾️` = 在有效 exec 策略允许该决定时始终允许
审批人可以在该消息上添加表情回应，或使用回退斜杠命令：`/approve <id> allow-once`、`/approve <id> allow-always` 或 `/approve <id> deny`。
审批人可以对该消息添加表情回应，或使用回退斜杠命令：`/approve <id> allow-once`、`/approve <id> allow-always` 或 `/approve <id> deny`。
只有已解析的审批人才能批准或拒绝。对于 exec 审批，渠道发送会包含命令文本，因此只应在受信任房间中启用 `channel` 或 `both`。
只有已解析的审批人可以批准或拒绝。对于 exec approvals，渠道投递会包含命令文本，因此仅应在受信任的房间中启用 `channel` 或 `both`。
每账号覆盖：
按账户覆盖：
- `channels.matrix.accounts.<account>.execApprovals`
@ -627,11 +738,11 @@ Matrix 审批提示会在主审批消息上预置表情回应快捷方式：
## 斜杠命令
Matrix 斜杠命令（例如 `/new`、`/reset`、`/model`）可直接在私信中使用。在房间中，OpenClaw 也能识别以机器人自身 Matrix 提及为前缀的斜杠命令，因此 `@bot:server /new` 会触发命令路径，而无需自定义提及正则。这让机器人能够响应 Element 和类似客户端在用户先用 Tab 补全机器人名称、再输入命令时发出的房间式 `@mention /command` 消息。
Matrix 斜杠命令（例如 `/new`、`/reset`、`/model`）可直接在私信中使用。在房间中，OpenClaw 也能识别带有机器人自身 Matrix 提及前缀的斜杠命令，因此 `@bot:server /new` 会触发命令路径，而不需要自定义提及正则。这让机器人能够响应房间风格的 `@mention /command` 帖子；当用户在输入命令前先通过补全选中机器人时，Element 和类似客户端就会发送这种格式。
授权规则仍然适用：命令发送者必须像普通消息一样满足私信或房间允许列表/所有者策略。
授权规则仍然适用：命令发送者必须像发送普通消息一样满足私信或房间允许列表/所有者策略。
## 多账号
## 多账户
```json5
{
@ -661,23 +772,25 @@ Matrix 斜杠命令（例如 `/new`、`/reset`、`/model`）可直接在私信
}
```
顶层 `channels.matrix` 值会作为命名账号的默认值，除非某个账号自行覆盖。
你可以使用 `groups.<room>.account` 将继承的房间条目限定到某个 Matrix 账号。
未带 `account` 的条目会在所有 Matrix 账号之间共享，而带有 `account: "default"` 的条目在默认账号直接配置在顶层 `channels.matrix.*` 时仍然有效。
部分共享认证默认值本身不会创建单独的隐式默认账号。只有当该默认账号具有新的认证信息（`homeserver` 加 `accessToken`，或 `homeserver` 加 `userId` 和 `password`）时，OpenClaw 才会合成顶层 `default` 账号；命名账号仍可在稍后由缓存凭证满足认证时，通过 `homeserver` 加 `userId` 的方式保持可发现。
如果 Matrix 已经恰好有一个命名账号，或者 `defaultAccount` 指向现有命名账号键，则单账号到多账号的修复/设置提升会保留该账号，而不是创建新的 `accounts.default` 条目。只有 Matrix 认证/bootstrap 键会移动到被提升的账号中；共享的发送策略键仍保留在顶层。
当你希望 OpenClaw 在隐式路由、探测和 CLI 操作中优先使用某个命名 Matrix 账号时，请设置 `defaultAccount`。
如果配置了多个 Matrix 账号，且其中一个账号 ID 为 `default`，即使 `defaultAccount` 未设置，OpenClaw 也会隐式使用该账号。
如果你配置了多个命名账号，请设置 `defaultAccount`，或为依赖隐式账号选择的 CLI 命令传入 `--account <id>`。
当你想针对单个命令覆盖该隐式选择时，请向 `openclaw matrix verify ...` 和 `openclaw matrix devices ...` 传入 `--account <id>`。
顶层 `channels.matrix` 值会作为命名账户的默认值，除非某个账户进行了覆盖。
你可以通过 `groups.<room>.account` 将继承的房间条目限定到某个 Matrix 账户。
未设置 `account` 的条目会在所有 Matrix 账户间共享，而设置了 `account: "default"` 的条目在默认账户直接配置在顶层 `channels.matrix.*` 时仍然有效。
部分共享认证默认值本身不会创建一个单独的隐式默认账户。只有当该默认值具有新的认证信息（`homeserver` 加 `accessToken`，或 `homeserver` 加 `userId` 和 `password`）时，OpenClaw 才会合成顶层 `default` 账户；命名账户仍然可以在稍后由缓存凭证满足认证条件时，通过 `homeserver` 加 `userId` 保持可发现。
如果 Matrix 已经恰好有一个命名账户，或者 `defaultAccount` 指向了一个现有的命名账户键，那么从单账户到多账户的修复/设置升级会保留该账户，而不会创建一个新的 `accounts.default` 条目。只有 Matrix 认证/bootstrap 键会移动到这个升级后的账户中；共享投递策略键会保留在顶层。
当你希望 OpenClaw 在隐式路由、探测和 CLI 操作中优先使用某个命名 Matrix 账户时，请设置 `defaultAccount`。
如果配置了多个 Matrix 账户，并且其中一个账户 ID 为 `default`，即使未设置 `defaultAccount`，OpenClaw 也会隐式使用该账户。
如果你配置了多个命名账户，请设置 `defaultAccount`，或为依赖隐式账户选择的 CLI 命令传入 `--account <id>`。
当你希望对某一条命令覆盖该隐式选择时，请为 `openclaw matrix verify ...` 和 `openclaw matrix devices ...` 传入 `--account <id>`。
共享的多账号模式请参阅 [Configuration reference](/zh-CN/gateway/config-channels#multi-account-all-channels)。
有关共享的多账户模式，请参阅 [Configuration reference](/zh-CN/gateway/config-channels#multi-account-all-channels)。
## 私有/LAN homeserver
默认情况下，出于 SSRF 保护，OpenClaw 会阻止连接私有/内部 Matrix homeserver，除非你为每个账号显式选择启用。
默认情况下，出于 SSRF 防护，OpenClaw 会阻止私有/内部 Matrix homeserver，除非你
为每个账户显式选择启用。
如果你的 homeserver 运行在 localhost、LAN/Tailscale IP 或内部主机名上，请为该 Matrix 账号启用 `network.dangerouslyAllowPrivateNetwork`：
如果你的 homeserver 运行在 localhost、LAN/Tailscale IP 或内部主机名上，请为该 Matrix 账户启用
`network.dangerouslyAllowPrivateNetwork`：
```json5
{
@ -703,7 +816,8 @@ openclaw matrix account add \
--access-token syt_ops_xxx
```
此选择启用仅允许受信任的私有/内部目标。像 `http://matrix.example.org:8008` 这样的公开明文 homeserver 仍会被阻止。尽可能优先使用 `https://`。
此选择启用仅允许受信任的私有/内部目标。公共明文 homeserver，例如
`http://matrix.example.org:8008`，仍会被阻止。请尽可能优先使用 `https://`。
## 代理 Matrix 流量
@ -721,85 +835,85 @@ openclaw matrix account add \
}
```
命名账号可以通过 `channels.matrix.accounts.<id>.proxy` 覆盖顶层默认值。
OpenClaw 对运行时 Matrix 流量和账号状态探测都会使用同一代理设置。
命名账户可以使用 `channels.matrix.accounts.<id>.proxy` 覆盖顶层默认值。
OpenClaw 会将同一个代理设置用于运行时 Matrix 流量和账户状态探测。
## 目标解析
在 OpenClaw 要求你提供房间或用户目标的任何位置，Matrix 都接受以下目标形式：
在 OpenClaw 要求你提供房间或用户目标的任何地方，Matrix 都接受以下目标形式：
- 用户：`@user:server`、`user:@user:server` 或 `matrix:user:@user:server`
- 房间：`!room:server`、`room:!room:server` 或 `matrix:room:!room:server`
- 别名：`#alias:server`、`channel:#alias:server` 或 `matrix:channel:#alias:server`
实时目录查询使用已登录的 Matrix 账号：
实时目录查找使用已登录的 Matrix 账户：
- 用户查询会在该 homeserver 的 Matrix 用户目录中进行。
- 房间查询会直接接受显式房间 ID 和别名，然后回退为搜索该账号已加入房间的名称。
- 已加入房间名称查询是尽力而为的。如果某个房间名称无法解析为 ID 或别名，它会在运行时允许列表解析中被忽略。
- 用户查找会查询该 homeserver 上的 Matrix 用户目录。
- 房间查找会直接接受显式的房间 ID 和别名，然后回退到搜索该账户已加入的房间名称。
- 已加入房间名称查找属于尽力而为。如果某个房间名称无法解析为 ID 或别名，它会在运行时允许列表解析中被忽略。
## 配置参考
- `enabled`：启用或禁用该渠道。
- `name`：账号的可选标签。
- `defaultAccount`：配置了多个 Matrix 账号时的首选账号 ID。
- `name`：账户的可选标签。
- `defaultAccount`：配置了多个 Matrix 账户时的首选账户 ID。
- `homeserver`：homeserver URL，例如 `https://matrix.example.org`。
- `network.dangerouslyAllowPrivateNetwork`：允许此 Matrix 账号连接到私有/内部 homeserver。当 homeserver 解析到 `localhost`、LAN/Tailscale IP 或诸如 `matrix-synapse` 这样的内部主机时，请启用此项。
- `proxy`：Matrix 流量的可选 HTTP(S) 代理 URL。命名账号可以用自己的 `proxy` 覆盖顶层默认值。
- `network.dangerouslyAllowPrivateNetwork`：允许此 Matrix 账户连接到私有/内部 homeserver。当 homeserver 解析到 `localhost`、LAN/Tailscale IP 或内部主机（例如 `matrix-synapse`）时，请启用此项。
- `proxy`：Matrix 流量的可选 HTTP(S) 代理 URL。命名账户可以使用自己的 `proxy` 覆盖顶层默认值。
- `userId`：完整的 Matrix 用户 ID，例如 `@bot:example.org`。
- `accessToken`：用于基于 token 认证的 access token。`channels.matrix.accessToken` 和 `channels.matrix.accounts.<id>.accessToken` 支持明文值和 SecretRef 值，适用于 env/file/exec 提供商。请参阅 [Secrets Management](/zh-CN/gateway/secrets)。
- `accessToken`：用于基于 token 认证的 access token。`channels.matrix.accessToken` 和 `channels.matrix.accounts.<id>.accessToken` 在 env/file/exec 提供商中都支持明文值和 SecretRef 值。请参阅 [Secrets Management](/zh-CN/gateway/secrets)。
- `password`：用于基于密码登录的密码。支持明文值和 SecretRef 值。
- `deviceId`：显式 Matrix 设备 ID。
- `deviceId`：显式的 Matrix 设备 ID。
- `deviceName`：用于密码登录的设备显示名称。
- `avatarUrl`：用于资料同步和 `profile set` 更新的已存储自身头像 URL。
- `avatarUrl`：用于资料同步和 `profile set` 更新的已存储自头像 URL。
- `initialSyncLimit`：启动同步期间获取的最大事件数。
- `encryption`：启用 E2EE。
- `allowlistOnly`：当为 `true` 时，会将 `open` 房间策略升级为 `allowlist`，并强制所有活动中的私信策略（除 `disabled` 外，包括 `pairing` 和 `open`）变为 `allowlist`。不影响 `disabled` 策略。
- `allowBots`：允许来自其他已配置 OpenClaw Matrix 账号的消息（`true` 或 `"mentions"`）。
- `allowlistOnly`：当为 `true` 时，会将 `open` 房间策略升级为 `allowlist`，并强制所有活动私信策略（除 `disabled` 外，包括 `pairing` 和 `open`）变为 `allowlist`。不会影响 `disabled` 策略。
- `allowBots`：允许来自其他已配置 OpenClaw Matrix 账户的消息（`true` 或 `"mentions"`）。
- `groupPolicy`：`open`、`allowlist` 或 `disabled`。
- `contextVisibility`：补充房间上下文的可见性模式（`all`、`allowlist`、`allowlist_quote`）。
- `groupAllowFrom`：房间流量的允许列表用户 ID。完整 Matrix 用户 ID 最安全；当监视器运行时，在启动时以及允许列表变化时会解析精确的目录匹配。无法解析的名称会被忽略。
- `historyLimit`：作为群组历史上下文包含的最大房间消息数。会回退到 `messages.groupChat.historyLimit`；如果两者都未设置，则实际默认值为 `0`。设置为 `0` 可禁用。
- `groupAllowFrom`：房间流量的允许列表用户 ID。完整的 Matrix 用户 ID 最安全；精确的目录匹配会在启动时以及监视器运行期间允许列表变更时解析。无法解析的名称会被忽略。
- `historyLimit`：作为群组历史上下文包含的最大房间消息数。会回退到 `messages.groupChat.historyLimit`；如果两者都未设置，则有效默认值为 `0`。设置 `0` 可禁用。
- `replyToMode`：`off`、`first`、`all` 或 `batched`。
- `markdown`：出站 Matrix 文本的可选 Markdown 渲染配置。
- `streaming`：`off`（默认）、`"partial"`、`"quiet"`、`true` 或 `false`。`"partial"` 和 `true` 会使用普通 Matrix 文本消息启用“预览优先”的草稿更新。`"quiet"` 则为自托管推送规则设置使用不通知的预览通知。`false` 等同于 `"off"`。
- `blockStreaming`：当草稿预览流式传输处于活动状态时，`true` 会为已完成的 assistant block 启用单独的进度消息。
- `streaming`：`off`（默认）、`"partial"`、`"quiet"`、`true` 或 `false`。`"partial"` 和 `true` 会使用普通 Matrix 文本消息启用“先预览后更新”的草稿更新。`"quiet"` 为自托管 push-rule 设置使用不通知的预览通知。`false` 等同于 `"off"`。
- `blockStreaming`：当草稿预览流式传输处于活动状态时，`true` 会为已完成的 assistant 块启用单独的进度消息。
- `threadReplies`：`off`、`inbound` 或 `always`。
- `threadBindings`：线程绑定会话路由和生命周期的每渠道覆盖。
- `startupVerification`：启动时自动自我验证请求模式（`if-unverified`、`off`）。
- `startupVerificationCooldownHours`：再次尝试自动启动验证请求前的冷却小时数。
- `textChunkLimit`：出站消息按字符计的分块大小限制（当 `chunkMode` 为 `length` 时适用）。
- `threadBindings`：线程绑定会话路由和生命周期的按渠道覆盖。
- `startupVerification`：启动时的自动自我验证请求模式（`if-unverified`、`off`）。
- `startupVerificationCooldownHours`：重试自动启动验证请求前的冷却时间。
- `textChunkLimit`：出站消息的分块大小（按字符数，适用于 `chunkMode` 为 `length` 时）。
- `chunkMode`：`length` 按字符数拆分消息；`newline` 按行边界拆分。
- `responsePrefix`：为该渠道所有出站回复添加的可选前缀字符串。
- `ackReaction`：该渠道/账号的可选 ack 表情回应覆盖值。
- `ackReactionScope`：可选 ack 表情回应范围覆盖（`group-mentions`、`group-all`、`direct`、`all`、`none`、`off`）。
- `responsePrefix`：为此渠道的所有出站回复添加的可选前缀字符串。
- `ackReaction`：此渠道/账户的可选确认表情回应覆盖值。
- `ackReactionScope`：可选的确认表情回应作用域覆盖值（`group-mentions`、`group-all`、`direct`、`all`、`none`、`off`）。
- `reactionNotifications`：入站表情回应通知模式（`own`、`off`）。
- `mediaMaxMb`：出站发送和入站媒体处理的媒体大小上限（MB）。
- `mediaMaxMb`：用于出站发送和入站媒体处理的媒体大小上限，单位为 MB。
- `autoJoin`：邀请自动加入策略（`always`、`allowlist`、`off`）。默认值：`off`。适用于所有 Matrix 邀请，包括私信式邀请。
- `autoJoinAllowlist`：当 `autoJoin` 为 `allowlist` 时允许的房间/别名。别名条目会在处理邀请时解析为房间 ID；OpenClaw 不信任被邀请房间宣称的别名状态。
- `autoJoinAllowlist`：当 `autoJoin` 为 `allowlist` 时允许的房间/别名。别名条目会在处理邀请时解析为房间 ID；OpenClaw 不会信任被邀请房间所声明的别名状态。
- `dm`：私信策略块（`enabled`、`policy`、`allowFrom`、`sessionScope`、`threadReplies`）。
- `dm.policy`：控制 OpenClaw 加入房间并将其分类为私信之后的私信访问。它不会改变邀请是否自动加入。
- `dm.allowFrom`：私信流量的允许列表用户 ID。完整 Matrix 用户 ID 最安全；当监视器运行时，在启动时以及允许列表变化时会解析精确的目录匹配。无法解析的名称会被忽略。
- `dm.sessionScope`：`per-user`（默认）或 `per-room`。如果你希望即使对端相同，每个 Matrix 私信房间也保持独立上下文，请使用 `per-room`。
- `dm.threadReplies`：仅私信的线程策略覆盖（`off`、`inbound`、`always`）。它会覆盖顶层 `threadReplies` 设置，影响私信中的回复位置和会话隔离。
- `execApprovals`：Matrix 原生 exec 审批发送（`enabled`、`approvers`、`target`、`agentFilter`、`sessionFilter`）。
- `execApprovals.approvers`：允许批准 exec 请求的 Matrix 用户 ID。当 `dm.allowFrom` 已经标识出审批人时可选。
- `execApprovals.target`：`dm | channel | both`（默认：`dm`）。
- `accounts`：命名的每账号覆盖。顶层 `channels.matrix` 值会作为这些条目的默认值。
- `groups`：每房间策略映射。优先使用房间 ID 或别名；无法解析的房间名称会在运行时被忽略。解析后会话/群组身份使用稳定的房间 ID。
- `groups.<room>.account`：在多账号设置中，将某个继承的房间条目限制到特定 Matrix 账号。
- `groups.<room>.allowBots`：针对已配置机器人发送者的房间级覆盖（`true` 或 `"mentions"`）。
- `groups.<room>.users`：每房间发送者允许列表。
- `groups.<room>.tools`：每房间工具允许/拒绝覆盖。
- `groups.<room>.autoReply`：房间级提及门控覆盖。`true` 会禁用该房间的提及要求；`false` 会强制重新启用。
- `dm.policy`：控制 OpenClaw 加入房间并将其分类为私信后如何访问私信。它不会改变邀请是否会被自动加入。
- `dm.allowFrom`：私信流量的允许列表用户 ID。完整的 Matrix 用户 ID 最安全；精确的目录匹配会在启动时以及监视器运行期间允许列表变更时解析。无法解析的名称会被忽略。
- `dm.sessionScope`：`per-user`（默认）或 `per-room`。如果你希望每个 Matrix 私信房间即使面对同一对端也保留独立上下文，请使用 `per-room`。
- `dm.threadReplies`：仅私信的线程策略覆盖值（`off`、`inbound`、`always`）。它会覆盖顶层 `threadReplies` 设置，同时影响私信中的回复放置和会话隔离。
- `execApprovals`：Matrix 原生 exec 审批投递（`enabled`、`approvers`、`target`、`agentFilter`、`sessionFilter`）。
- `execApprovals.approvers`：允许批准 exec 请求的 Matrix 用户 ID。当 `dm.allowFrom` 已经标识了审批人时，此项可选。
- `execApprovals.target`：`dm | channel | both`（默认值：`dm`）。
- `accounts`：按名称定义的每账户覆盖项。顶层 `channels.matrix` 值会作为这些条目的默认值。
- `groups`：按房间定义的策略映射。优先使用房间 ID 或别名；无法解析的房间名称会在运行时被忽略。会话/群组身份在解析后使用稳定的房间 ID。
- `groups.<room>.account`：在多账户设置中，将一个继承的房间条目限制到特定 Matrix 账户。
- `groups.<room>.allowBots`：对已配置机器人发送者的房间级覆盖值（`true` 或 `"mentions"`）。
- `groups.<room>.users`：按房间定义的发送者允许列表。
- `groups.<room>.tools`：按房间定义的工具允许/拒绝覆盖值。
- `groups.<room>.autoReply`：房间级提及门控覆盖值。`true` 会禁用该房间的提及要求；`false` 会强制重新启用。
- `groups.<room>.skills`：可选的房间级 Skills 过滤器。
- `groups.<room>.systemPrompt`：可选的房间级 system prompt 片段。
- `groups.<room>.systemPrompt`：可选的房间级系统提示片段。
- `rooms`：`groups` 的旧别名。
- `actions`：每操作工具门控（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。
- `actions`：按操作定义的工具门控（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。
## 相关内容
## 相关
- [Channels Overview](/zh-CN/channels) — 所有支持的渠道
- [Channels Overview](/zh-CN/channels) — 所有受支持的渠道
- [Pairing](/zh-CN/channels/pairing) — 私信认证和配对流程
- [Groups](/zh-CN/channels/groups) — 群聊行为和提及门控
- [Channel Routing](/zh-CN/channels/channel-routing) — 消息的会话路由

241
docs/zh-CN/install/migrating-matrix.md
View File

@ -1,26 +1,26 @@
---
read_when:
- 升级现有的 Matrix 安装
- 迁移加密的 Matrix 历史记录和设备状态
summary: OpenClaw 如何原地升级先前的 Matrix 插件，包括加密状态恢复限制和手动恢复步骤。
- 迁移已加密的 Matrix 历史记录和设备状态
summary: OpenClaw 如何原地升级之前的 Matrix 插件，包括加密状态恢复限制和手动恢复步骤。
title: Matrix 迁移
x-i18n:
generated_at: "2026-04-23T20:52:25Z"
generated_at: "2026-04-24T22:02:29Z"
model: gpt-5.4
provider: openai
source_hash: e8210f5fbe476148736417eec29dfb5e27c132c6a0bb80753ce254129c14da4f
source_hash: 3c35794d7d56d2083905fe4a478463223813b6c901c5c67935fbb9670b51f225
source_path: install/migrating-matrix.md
workflow: 15
---
本页介绍如何从之前公开的 `matrix` 插件升级到当前实现。
对大多数用户来说，升级是原地进行的：
对于大多数用户，升级是原地进行的：
- 插件仍然是 `@openclaw/matrix`
- 渠道仍然是 `matrix`
- 你的配置仍然位于 `channels.matrix`
- 缓存凭证仍然位于 `~/.openclaw/credentials/matrix/`
- 缓存的凭证仍然位于 `~/.openclaw/credentials/matrix/`
- 运行时状态仍然位于 `~/.openclaw/matrix/`
你不需要重命名配置键，也不需要以新名称重新安装插件。
@ -28,71 +28,71 @@ x-i18n:
## 迁移会自动执行的内容
当 Gateway 网关启动时，以及当你运行 [`openclaw doctor --fix`](/zh-CN/gateway/doctor) 时，OpenClaw 会尝试自动修复旧的 Matrix 状态。
在任何可执行的 Matrix 迁移步骤修改磁盘状态之前，OpenClaw 都会创建或复用一个专门的恢复快照。
在任何会变更磁盘状态的可执行 Matrix 迁移步骤开始之前，OpenClaw 都会创建或复用一个专门的恢复快照。
当你使用 `openclaw update` 时，具体触发方式取决于 OpenClaw 的安装方式：
- 源码安装会在更新流程中运行 `openclaw doctor --fix`，然后默认重启 gateway
- 包管理器安装会更新包、运行一次非交互式 doctor 检查，然后依赖默认的 gateway 重启来完成 Matrix 迁移
- 如果你使用 `openclaw update --no-restart`，则依赖启动的 Matrix 迁移会延后到你之后运行 `openclaw doctor --fix` 并重启 gateway 时才执行
- 源码安装会在更新流程中运行 `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 room-key backup 解密密钥
- 当访问令牌之后发生变化时，为同一 Matrix 账户、homeserver 和用户复用最完整的现有 token-hash 存储根目录
- 当 Matrix 访问令牌已变化但账户/设备身份保持不变时，扫描同级 token-hash 存储根目录中的待恢复加密状态元数据
- 在下一次 Matrix 启动时，将备份的 room keys 恢复到新的加密存储中
- 将最旧的扁平 Matrix 同步存储迁移到当前按账户划分的位置
- 在能够安全解析目标账户的情况下，将最旧的扁平 Matrix 加密存储迁移到当前按账户划分的位置
- 当旧的 Rust 加密存储中本地存在此前保存的 Matrix 房间密钥备份解密密钥时，将其提取出来
- 当访问令牌之后发生变化时，针对同一个 Matrix 账户、homeserver 和用户，复用现有最完整的令牌哈希存储根目录
- 当 Matrix 访问令牌发生变化但账户 / 设备身份保持不变时，扫描同级令牌哈希存储根目录中待恢复的加密状态元数据
- 在下一次 Matrix 启动时，将已备份的房间密钥恢复到新的加密存储中
快照详情：
- 成功创建快照后，OpenClaw 会在 `~/.openclaw/matrix/migration-snapshot.json` 写入一个标记文件，以便后续启动和修复流程复用同一个归档。
- 这些自动 Matrix 迁移快照只备份配置 + 状态（`includeWorkspace: false`）。
- 如果 Matrix 只有仅警告级别的迁移状态，例如 `userId` 或 `accessToken` 仍然缺失，则 OpenClaw 暂时不会创建快照，因为此时没有可执行的 Matrix 变更。
- 如果快照步骤失败，OpenClaw 会跳过该次运行中的 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 存储（`~/.openclaw/matrix/bot-storage.json` 和 `~/.openclaw/matrix/crypto/`）来自单一存储布局，因此 OpenClaw 只能将其迁移到一个已解析的 Matrix 账户目标中
- 已经是按账户划分的旧版 Matrix 存储会按已配置的 Matrix 账户分别检测和准备
## 迁移无法自动执行的内容
之前公开的 Matrix 插件**不会**自动创建 Matrix room-key backups。它会持久化本地加密状态并请求设备验证，但它并不能保证你的 room keys 已备份到 homeserver。
之前公开的 Matrix 插件**不会**自动创建 Matrix 房间密钥备份。它会持久化本地加密状态并请求设备验证，但不会保证你的房间密钥已备份到 homeserver。
这意味着某些加密安装只能部分迁移。
这意味着某些加密安装只能被部分迁移。
OpenClaw 无法自动恢复：
- 从未备份过、仅存在于本地的 room keys
- 在 `homeserver`、`userId` 或 `accessToken` 仍不可用、导致目标 Matrix 账户尚无法解析时的加密状态
- 当配置了多个 Matrix 账户但未设置 `channels.matrix.defaultAccount` 时，对单个共享扁平 Matrix 存储的自动迁移
- 固定到仓库路径而不是标准 Matrix 包的自定义插件路径安装
- 当旧存储中有已备份密钥但未在本地保留解密密钥时，缺失的恢复密钥
- 从未备份过、仅存在于本地的房间密钥
- 当 `homeserver`、`userId` 或 `accessToken` 仍不可用，导致目标 Matrix 账户尚无法解析时的加密状态
- 在配置了多个 Matrix 账户但未设置 `channels.matrix.defaultAccount` 时，对单个共享扁平 Matrix 存储的自动迁移
- 固定到仓库路径而不是标准 Matrix 软件包的自定义插件路径安装
- 当旧存储中有已备份密钥，但本地未保留解密密钥时，缺失的恢复密钥
当前警告范围：
- Gateway 网关启动和 `openclaw doctor` 都会提示自定义 Matrix 插件路径安装
- 自定义 Matrix 插件路径安装会同时在 Gateway 网关启动时和 `openclaw doctor` 中提示
如果你的旧安装包含从未备份的本地加密历史，升级后某些较旧的加密消息可能仍然无法读取。
如果你的旧安装中有从未备份过、仅保存在本地的加密历史记录，那么升级后某些较旧的加密消息可能仍然无法读取。
## 推荐升级流程
## 推荐的升级流程
1. 正常更新 OpenClaw 和 Matrix 插件。
优先使用不带 `--no-restart` 的普通 `openclaw update`，这样启动时就能立即完成 Matrix 迁移。
建议优先使用普通的 `openclaw update`，不要加 `--no-restart`，这样启动过程可以立即完成 Matrix 迁移。
2. 运行：
```bash
openclaw doctor --fix
```
如果 Matrix 存在可执行的迁移任务，doctor 会先创建或复用迁移前快照，并打印归档路径。
如果 Matrix 存在可执行的迁移工作，Doctor 会先创建或复用迁移前快照，并打印归档路径。
3. 启动或重启 gateway。
3. 启动或重启 Gateway 网关。
4. 检查当前验证和备份状态：
```bash
@ -112,28 +112,39 @@ OpenClaw 无法自动恢复：
openclaw matrix verify device "<your-recovery-key>"
```
7. 如果你打算放弃无法恢复的旧历史，并希望为未来消息建立一个全新的备份基线，请运行：
如果恢复密钥已被接受且备份可用，但 `Cross-signing verified`
仍然是 `no`，请在另一个 Matrix 客户端中完成自我验证：
```bash
openclaw matrix verify self
```
在另一个 Matrix 客户端中接受请求，比较表情符号或十进制数字，
并且仅当它们匹配时才输入 `yes`。只有在 `Cross-signing verified` 变为 `yes` 后，
该命令才会成功退出。
7. 如果你打算主动放弃无法恢复的旧历史记录，并希望为未来消息建立新的备份基线，请运行：
```bash
openclaw matrix verify backup reset --yes
```
8. 如果服务器端尚未存在密钥备份，请为未来恢复创建一个：
8. 如果服务器端密钥备份尚不存在，请创建一个以便未来恢复使用：
```bash
openclaw matrix verify bootstrap
```
## 加密迁移如何工作
## 加密迁移的工作方式
加密迁移是一个两阶段流程：
加密迁移是一个两阶段过程：
1. 启动时或运行 `openclaw doctor --fix` 时，如果加密迁移可执行，则会创建或复用迁移前快照。
2. 启动时或运行 `openclaw doctor --fix` 时，OpenClaw 会通过当前激活的 Matrix 插件安装检查旧的 Matrix 加密存储。
3. 如果找到备份解密密钥，OpenClaw 会将其写入新的恢复密钥流程，并将 room-key 恢复标记为待处理。
4. 在下一次 Matrix 启动时，OpenClaw 会自动将备份的 room keys 恢复到新的加密存储中。
1. 如果加密迁移可执行，启动过程或 `openclaw doctor --fix` 会创建或复用迁移前快照。
2. 启动过程或 `openclaw doctor --fix` 会通过当前启用的 Matrix 插件安装检查旧的 Matrix 加密存储。
3. 如果找到了备份解密密钥，OpenClaw 会将其写入新的恢复密钥流程，并将房间密钥恢复标记为待处理。
4. 在下一次 Matrix 启动时，OpenClaw 会自动将已备份的房间密钥恢复到新的加密存储中。
如果旧存储报告存在从未备份过的 room keys，OpenClaw 会发出警告，而不是假装恢复已经成功。
如果旧存储报告存在从未备份过的房间密钥，OpenClaw 会发出警告，而不是假装恢复已经成功。
## 常见消息及其含义
@ -141,189 +152,187 @@ OpenClaw 无法自动恢复：
`Matrix plugin upgraded in place.`
- 含义：已检测到旧的磁盘 Matrix 状态，并已将其迁移到当前布局。
- 应对方式：除非同一输出中还包含警告，否则无需操作。
- 含义：检测到了旧的磁盘 Matrix 状态，并已将其迁移到当前布局中。
- 该怎么做：除非同一输出中还包含警告，否则无需操作。
`Matrix migration snapshot created before applying Matrix upgrades.`
- 含义：OpenClaw 在修改 Matrix 状态之前创建了一个恢复归档。
- 应对方式：在确认迁移成功之前，请保留输出中的归档路径。
- 含义：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 状态，但 OpenClaw 无法将其映射到当前 Matrix 账户，因为 Matrix 尚未配置。
- 应对方式：配置 `channels.matrix`，然后重新运行 `openclaw doctor --fix` 或重启 gateway。
- 该怎么做：配置 `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`。
- 含义：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。
- 含义：OpenClaw 找到了一个共享的扁平 Matrix 存储，但它不会猜测应该将其分配给哪个已命名的 Matrix 账户。
- 该怎么做：将 `channels.matrix.defaultAccount` 设置为目标账户，然后重新运行 `openclaw doctor --fix` 或重启 Gateway 网关。
`Matrix legacy sync store not migrated because the target already exists (...)`
- 含义：新的按账户划分位置已经存在同步或加密存储，因此 OpenClaw 没有自动覆盖它。
- 应对方式：在手动删除或移动冲突目标之前，请先确认当前账户是否正确。
- 含义：新的按账户划分位置中已经存在同步或加密存储，因此 OpenClaw 没有自动覆盖它。
- 该怎么做：在手动删除或移动发生冲突的目标之前，先确认当前账户是否正确。
`Failed migrating Matrix legacy sync store (...)` 或 `Failed migrating Matrix legacy crypto store (...)`
`Failed migrating Matrix legacy sync store (...)` or `Failed migrating Matrix legacy crypto store (...)`
- 含义：OpenClaw 尝试移动旧的 Matrix 状态，但文件系统操作失败。
- 应对方式：检查文件系统权限和磁盘状态，然后重新运行 `openclaw doctor --fix`。
- 含义：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。
- 含义：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`。
- 含义：加密存储确实存在，但 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。
- 含义：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。
- 含义：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 插件 helper 入口点。
- 应对方式：重新安装或修复 Matrix 插件（`openclaw plugins install @openclaw/matrix`，若是仓库检出则使用 `openclaw plugins install ./path/to/local/matrix-plugin`），然后重新运行 `openclaw doctor --fix` 或重启 gateway。
- 含义：OpenClaw 找到了旧的已加密 Matrix 状态，但无法从通常用于检查该存储的 Matrix 插件中加载辅助入口点。
- 该怎么做：重新安装或修复 Matrix 插件（`openclaw plugins install @openclaw/matrix`，或者如果你使用的是仓库检出版本，则运行 `openclaw plugins install ./path/to/local/matrix-plugin`），然后重新运行 `openclaw doctor --fix` 或重启 Gateway 网关。
`Matrix plugin helper path is unsafe: ... Reinstall @openclaw/matrix and try again.`
- 含义：OpenClaw 发现某个 helper 文件路径逃逸出了插件根目录或未通过插件边界检查，因此拒绝导入它。
- 应对方式：从受信任路径重新安装 Matrix 插件，然后重新运行 `openclaw doctor --fix` 或重启 gateway。
- 含义：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。
- 该怎么做：解决备份错误，然后重新运行 `openclaw doctor --fix` 或重启 Gateway 网关。
`Failed migrating legacy Matrix client storage: ...`
- 含义：Matrix 客户端侧回退路径发现了旧的扁平存储，但移动失败。OpenClaw 现在会中止该回退，而不是默默以一个全新存储启动。
- 应对方式：检查文件系统权限或冲突，保持旧状态不变，并在修复错误后重试。
- 含义：Matrix 客户端侧回退逻辑找到了旧的扁平存储，但迁移失败了。OpenClaw 现在会中止该回退流程，而不是悄悄使用一个新的存储启动。
- 该怎么做：检查文件系统权限或冲突，保持旧状态完整，在修复错误后重试。
`Matrix is installed from a custom path: ...`
- 含义：Matrix 被固定为路径安装，因此主线更新不会自动将其替换为仓库中的标准 Matrix 包。
- 应对方式：当你想恢复到默认 Matrix 插件时，使用 `openclaw plugins install @openclaw/matrix` 重新安装。
- 含义：Matrix 被固定为路径安装，因此主线更新不会自动将其替换为仓库中的标准 Matrix 软件包。
- 该怎么做：当你想恢复为默认 Matrix 插件时，使用 `openclaw plugins install @openclaw/matrix` 重新安装。
### 加密状态恢复消息
### 已加密状态恢复消息
`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 and could not be restored automatically`
- 含义：一些旧的 room keys 只存在于旧的本地存储中，从未上传到 Matrix backup。
- 应对方式：除非你能从另一个已验证的客户端手动恢复这些密钥，否则某些旧的加密历史将继续不可用。
- 含义：某些旧房间密钥仅存在于旧的本地存储中，且从未上传到 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>"`。
- 该怎么做：运行 `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>"` 进行恢复。
- 含义：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 检测到了备份密钥冲突，并拒绝自动覆盖当前 recovery-key 文件。
- 应对方式：在重试任何恢复命令之前，请先确认哪个恢复密钥才是正确的。
- 含义：OpenClaw 检测到了备份密钥冲突，因此拒绝自动覆盖当前的 recovery-key 文件。
- 该怎么做：在重试任何恢复命令之前，先确认哪个恢复密钥是正确的。
`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>"` 重试。
- 含义：新插件尝试恢复时失败了，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`。
- 含义：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 backup 不匹配。
- 应对方式：使用正确的密钥重新运行 `openclaw matrix verify device "<your-recovery-key>"`。
- 含义：已存储的密钥与当前激活的 Matrix 备份不匹配。
- 该怎么做：使用正确的密钥重新运行 `openclaw matrix verify device "<your-recovery-key>"`。
如果你接受丢失无法恢复的旧加密历史，也可以改为使用 `openclaw matrix verify backup reset --yes` 重置
当前备份基线。当已存储的备份密钥损坏时，该重置也可能会重新创建密钥存储，从而让
新的备份密钥在重启后能够正确加载。
如果你接受丢失无法恢复的旧加密历史记录，也可以改为使用 `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>"`。
- 含义：备份存在，但此设备对交叉签名信任链的信任强度仍然不足。
- 该怎么做：重新运行 `openclaw matrix verify device "<your-recovery-key>"`。
`Matrix recovery key is required`
- 含义：你尝试执行恢复步骤时，没有在需要时提供恢复密钥。
- 应对方式：使用你的恢复密钥重新运行该命令。
- 含义：你尝试执行恢复步骤时，没有提供所需的恢复密钥。
- 该怎么做：使用你的恢复密钥重新运行该命令。
`Invalid Matrix recovery key: ...`
- 含义：提供的密钥无法解析，或不符合预期格式。
- 应对方式：使用来自你的 Matrix 客户端或 recovery-key 文件中的准确恢复密钥重试。
- 含义：提供的密钥无法解析，或与预期格式不匹配。
- 该怎么做：使用来自你的 Matrix 客户端或 recovery-key 文件中的准确恢复密钥重试。
`Matrix device is still unverified after applying recovery key. Verify your recovery key and ensure cross-signing is available.`
`Matrix recovery key was applied, but this device still lacks full Matrix identity trust.`
- 含义：密钥已应用，但设备仍无法完成验证。
- 应对方式：确认你使用的是正确的密钥，并确保该账户启用了跨签名，然后重试。
- 含义：OpenClaw 可以应用恢复密钥，但 Matrix 仍未为此设备建立完整的交叉签名身份信任。请检查命令输出中的 `Recovery key accepted`、`Backup usable`、`Cross-signing verified` 和 `Device verified by owner`。
- 该怎么做：运行 `openclaw matrix verify self`，在另一个 Matrix 客户端中接受请求，比较 SAS，并且仅在匹配时输入 `yes`。该命令会等待完整的 Matrix 身份信任建立后才报告成功。仅当你明确想替换当前交叉签名身份时，才使用 `openclaw matrix verify bootstrap --recovery-key "<your-recovery-key>" --force-reset-cross-signing`。
`Matrix key backup is not active on this device after loading from secret storage.`
- 含义：从密钥存储加载后，此设备上没有形成活动的备份会话。
- 应对方式：先验证该设备，然后使用 `openclaw matrix verify backup status` 再次检查。
- 含义：密钥存储未能在此设备上生成一个激活的备份会话。
- 该怎么做：先验证设备，然后使用 `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>"`。
- 该怎么做：先运行 `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 ./path/to/local/matrix-plugin`。
- 含义：你的插件安装记录指向了一个已经不存在的本地路径。
- 该怎么做：使用 `openclaw plugins install @openclaw/matrix` 重新安装；如果你是从仓库检出运行，则使用 `openclaw plugins install ./path/to/local/matrix-plugin`。
## 如果加密历史仍然没有恢复
## 如果加密历史记录仍未恢复
请按顺序运行以下检查：
按顺序运行以下检查：
```bash
openclaw matrix verify status --verbose
@ -335,7 +344,7 @@ openclaw matrix verify backup restore --recovery-key "<your-recovery-key>" --ver
## 如果你想为未来消息重新开始
如果你接受丢失无法恢复的旧加密历史，并且只想为未来建立一个干净的备份基线，请按顺序运行以下命令：
如果你接受丢失无法恢复的旧加密历史记录，并且只想为今后的消息建立一个干净的备份基线，请按顺序运行以下命令：
```bash
openclaw matrix verify backup reset --yes
@ -343,7 +352,7 @@ openclaw matrix verify backup status --verbose
openclaw matrix verify status
```
如果之后设备仍未验证，请在你的 Matrix 客户端中通过比较 SAS emoji 或十进制代码并确认匹配来完成验证。
如果此后设备仍未验证，请在你的 Matrix 客户端中通过比较 SAS 表情符号或十进制代码并确认它们一致来完成验证。
## 相关页面