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

chore(i18n): refresh zh-CN translations
Some checks are pending
Translate uk / translate (push) Waiting to run
Details
Translate zh-CN / translate (push) Waiting to run
Details

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-27 20:30:13 +00:00
parent 8b706e33a3
commit cfc0f0fc91
3 changed files with 394 additions and 378 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,41 +1,41 @@
---
read_when:
- 在 OpenClaw 中设置 Matrix
- 配置 Matrix E2EE 和验证
- 配置 Matrix 端到端加密和验证
summary: Matrix 支持状态、设置和配置示例
title: Matrix
x-i18n:
generated_at: "2026-04-27T18:55:37Z"
generated_at: "2026-04-27T20:27:49Z"
model: gpt-5.4
provider: openai
source_hash: adfd82ef371046cd537455db77285ab27e3a09f7e589a773c5e12bc766d25512
source_hash: 42380d57ad7da25bc1fb8a1968671e91372f7dc681ea8503013729b764b74811
source_path: channels/matrix.md
workflow: 15
---
Matrix 是 OpenClaw 的一个内置渠道插件。
它使用官方 `matrix-js-sdk`，并支持私信、房间、线程、媒体、回应、投票、位置和 E2EE。
它使用官方的 `matrix-js-sdk`，并支持私信、房间、线程、媒体、回应、投票、位置和端到端加密。
## 内置插件
当前打包发布的 OpenClaw 版本已内置 Matrix 插件。你无需安装任何内容；配置 `channels.matrix.*`（参见 [设置](#setup)）即可激活它。
对于较旧的构建版本或排除了 Matrix 的自定义安装，请先手动安装：
对于较旧的构建版本，或排除了 Matrix 的自定义安装，请先手动安装：
```bash
openclaw plugins install @openclaw/matrix
# or, from a local checkout
# 或者，从本地检出安装
openclaw plugins install ./path/to/local/matrix-plugin
```
`plugins install` 会注册并启用该插件，因此无需单独执行 `openclaw plugins enable matrix`。不过，在你配置下方的渠道之前，该插件仍不会执行任何操作。有关插件的一般行为和安装规则，请参见 [插件](/zh-CN/tools/plugin)。
`plugins install` 会注册并启用该插件，因此不需要单独执行 `openclaw plugins enable matrix`。在你完成下方的渠道配置之前，该插件仍不会执行任何操作。有关插件的一般行为和安装规则，请参见 [插件](/zh-CN/tools/plugin)。
## 设置
1. 在你的 homeserver 上创建一个 Matrix 账户。
2. 配置 `channels.matrix`，使用 `homeserver` + `accessToken`，或 `homeserver` + `userId` + `password`。
1. 在你的 homeserver 上创建一个 Matrix 账号。
2. 使用 `homeserver` + `accessToken`，或 `homeserver` + `userId` + `password` 配置 `channels.matrix`。
3. 重启 Gateway 网关。
4. 与机器人发起私信，或邀请它加入房间（参见 [自动加入](#auto-join) —— 只有当 `autoJoin` 允许时，新邀请才会生效）。
4. 与机器人开始私信，或邀请它加入房间（参见 [自动加入](#auto-join)——只有在 `autoJoin` 允许时，新邀请才会生效）。
### 交互式设置
@ -44,9 +44,9 @@ openclaw channels add
openclaw configure --section channels
```
向导会询问以下内容：homeserver URL、认证方式（访问令牌或密码）、用户 ID（仅密码认证）、可选的设备名称、是否启用 E2EE，以及是否配置房间访问和自动加入。
向导会询问以下内容：homeserver URL、认证方式（访问令牌或密码）、用户 ID（仅密码认证）、可选的设备名称、是否启用端到端加密，以及是否配置房间访问和自动加入。
如果匹配的 `MATRIX_*` 环境变量已存在，且所选账户没有已保存的认证信息，向导会提供环境变量快捷方式。在保存允许列表前，如需解析房间名称，请运行 `openclaw channels resolve --channel matrix "Project Room"`。启用 E2EE 后，向导会写入配置，并运行与 [`openclaw matrix encryption setup`](#encryption-and-verification) 相同的引导流程。
如果匹配的 `MATRIX_*` 环境变量已存在，并且所选账号没有已保存的认证信息，向导会提供环境变量快捷方式。在保存允许列表之前，如需解析房间名称，请运行 `openclaw channels resolve --channel matrix "Project Room"`。启用端到端加密后，向导会写入配置，并运行与 [`openclaw matrix encryption setup`](#encryption-and-verification) 相同的引导流程。
### 最小配置
@ -83,14 +83,14 @@ openclaw configure --section channels
### 自动加入
`channels.matrix.autoJoin` 默认值为 `off`。使用默认值时，在你手动加入之前，机器人不会出现在通过新邀请加入的新房间或私信中。
`channels.matrix.autoJoin` 默认为 `off`。使用默认值时，在你手动加入之前，机器人不会出现在由新邀请产生的新房间或私信中。
OpenClaw 无法在收到邀请时判断被邀请的房间是私信还是群组，因此所有邀请——包括类似私信的邀请——都会先经过 `autoJoin`。`dm.policy` 只会在机器人加入后、且房间已被分类之后才生效。
OpenClaw 无法在邀请时判断被邀请的房间是私信还是群组，因此所有邀请——包括类似私信的邀请——都会先经过 `autoJoin`。`dm.policy` 只会在机器人加入之后、并且房间已被分类后才生效。
<Warning>
设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，可限制机器人接受哪些邀请；或者设置 `autoJoin: "always"`，以接受所有邀请。
设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，可以限制机器人接受哪些邀请；或者设置 `autoJoin: "always"` 以接受所有邀请。
`autoJoinAllowlist` 只接受稳定目标：`!roomId:server`、`#alias:server` 或 `*`。普通房间名会被拒绝；别名条目会针对 homeserver 进行解析，而不是依据被邀请房间声称的状态进行解析。
`autoJoinAllowlist` 只接受稳定目标：`!roomId:server`、`#alias:server` 或 `*`。普通房间名称会被拒绝；别名条目会针对 homeserver 进行解析，而不会根据受邀房间声明的状态进行解析。
</Warning>
```json5
@ -107,49 +107,49 @@ OpenClaw 无法在收到邀请时判断被邀请的房间是私信还是群组
}
```
如需接受所有邀请，请使用 `autoJoin: "always"`。
若要接受所有邀请，请使用 `autoJoin: "always"`。
### 允许列表目标格式
私信和房间允许列表最好使用稳定 ID 填充：
- 私信（`dm.allowFrom`、`groupAllowFrom`、`groups.<room>.users`）：使用 `@user:server`。显示名称只有在 homeserver 目录恰好返回一个匹配项时才会解析。
- 房间（`groups`、`autoJoinAllowlist`）：使用 `!room:server` 或 `#alias:server`。名称会尽力在已加入的房间中解析；运行时会忽略无法解析的条目。
- 私信（`dm.allowFrom`、`groupAllowFrom`、`groups.<room>.users`）：使用 `@user:server`。仅当 homeserver 目录返回恰好一个匹配项时，显示名称才会被解析。
- 房间（`groups`、`autoJoinAllowlist`）：使用 `!room:server` 或 `#alias:server`。名称会尽力根据已加入的房间进行解析；未解析的条目会在运行时被忽略。
### 账户 ID 规范化
### 账号 ID 规范化
向导会将友好名称转换为规范化账户 ID。例如，`Ops Bot` 会变成 `ops-bot`。在带作用域的环境变量名称中，标点符号会被转义，以避免两个账户发生冲突：`-` → `_X2D_`，因此 `ops-prod` 会映射为 `MATRIX_OPS_X2D_PROD_*`。
向导会将易读名称转换为规范化的账号 ID。例如，`Ops Bot` 会变成 `ops-bot`。在带作用域的环境变量名称中，标点符号会被转义，以避免两个账号发生冲突：`-` → `_X2D_`，因此 `ops-prod` 会映射为 `MATRIX_OPS_X2D_PROD_*`。
### 缓存凭证
### 缓存的凭证
Matrix 会将缓存凭证存储在 `~/.openclaw/credentials/matrix/` 下：
Matrix 会将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 下：
- 默认账户：`credentials.json`
- 命名账户：`credentials-<account>.json`
- 默认账号：`credentials.json`
- 命名账号：`credentials-<account>.json`
当这些位置存在缓存凭证时，即使配置文件中没有访问令牌，OpenClaw 也会将 Matrix 视为已配置——这适用于设置、`openclaw doctor` 和渠道状态探测。
当这些位置存在缓存凭证时，即使配置文件中没有访问令牌，OpenClaw 仍会将 Matrix 视为已配置——这适用于设置流程、`openclaw doctor` 和渠道状态探测。
### 环境变量
当等效配置键未设置时使用。默认账户使用不带前缀的名称；命名账户会在后缀前插入账户 ID。
当等效的配置键未设置时会使用这些变量。默认账号使用不带前缀的名称；命名账号会在后缀前插入账号 ID。
| 默认账户 | 命名账户（`<ID>` 是规范化后的账户 ID） |
| --------------------- | -------------------------------------------------- |
| `MATRIX_HOMESERVER` | `MATRIX_<ID>_HOMESERVER` |
| `MATRIX_ACCESS_TOKEN` | `MATRIX_<ID>_ACCESS_TOKEN` |
| `MATRIX_USER_ID` | `MATRIX_<ID>_USER_ID` |
| `MATRIX_PASSWORD` | `MATRIX_<ID>_PASSWORD` |
| `MATRIX_DEVICE_ID` | `MATRIX_<ID>_DEVICE_ID` |
| `MATRIX_DEVICE_NAME` | `MATRIX_<ID>_DEVICE_NAME` |
| `MATRIX_RECOVERY_KEY` | `MATRIX_<ID>_RECOVERY_KEY` |
| 默认账号 | 命名账号（`<ID>` 是规范化后的账号 ID） |
| ------------------- | -------------------------------------- |
| `MATRIX_HOMESERVER` | `MATRIX_<ID>_HOMESERVER` |
| `MATRIX_ACCESS_TOKEN` | `MATRIX_<ID>_ACCESS_TOKEN` |
| `MATRIX_USER_ID` | `MATRIX_<ID>_USER_ID` |
| `MATRIX_PASSWORD` | `MATRIX_<ID>_PASSWORD` |
| `MATRIX_DEVICE_ID` | `MATRIX_<ID>_DEVICE_ID` |
| `MATRIX_DEVICE_NAME` | `MATRIX_<ID>_DEVICE_NAME` |
| `MATRIX_RECOVERY_KEY` | `MATRIX_<ID>_RECOVERY_KEY` |
对于账户 `ops`，这些名称会变成 `MATRIX_OPS_HOMESERVER`、`MATRIX_OPS_ACCESS_TOKEN` 等。恢复密钥环境变量会被支持恢复流程的 CLI 命令读取（`verify backup restore`、`verify device`、`verify bootstrap`），前提是你通过 `--recovery-key-stdin` 管道传入密钥。
对于账号 `ops`，名称会变为 `MATRIX_OPS_HOMESERVER`、`MATRIX_OPS_ACCESS_TOKEN` 等。恢复密钥环境变量会被具备恢复能力的 CLI 流程读取（`verify backup restore`、`verify device`、`verify bootstrap`），前提是你通过 `--recovery-key-stdin` 管道传入该密钥。
`MATRIX_HOMESERVER` 不能从工作区 `.env` 设置；参见 [工作区 `.env` 文件](/zh-CN/gateway/security)。
`MATRIX_HOMESERVER` 不能从工作区 `.env` 中设置；参见 [工作区 `.env` 文件](/zh-CN/gateway/security)。
## 配置示例
一个实用的基础配置，包含私信配对、房间允许列表和 E2EE：
一个实用的基础配置，包含私信配对、房间允许列表和端到端加密：
```json5
{
@ -184,7 +184,7 @@ Matrix 会将缓存凭证存储在 `~/.openclaw/credentials/matrix/` 下：
## 流式预览
Matrix 回复流式传输为选择启用。`streaming` 控制 OpenClaw 如何传递生成中的助手回复；`blockStreaming` 控制每个已完成的分块是否保留为单独的 Matrix 消息。
Matrix 回复流式传输为可选启用。`streaming` 控制 OpenClaw 如何传递正在生成中的助手回复；`blockStreaming` 控制每个已完成的块是否保留为单独的 Matrix 消息。
```json5
{
@ -196,40 +196,58 @@ Matrix 回复流式传输为选择启用。`streaming` 控制 OpenClaw 如何传
}
```
| `streaming` | 行为 |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"off"`（默认） | 等待完整回复，然后发送一次。`true` ↔ `"partial"`，`false` ↔ `"off"`。 |
| `"partial"` | 在模型写入当前分块时，就地编辑一条普通文本消息。标准 Matrix 客户端可能会在首次预览时通知，而不是在最终编辑时通知。 |
| `"quiet"` | 与 `"partial"` 相同，但消息为不触发通知的 notice。只有当某条按用户设置的推送规则匹配到最终完成的编辑时，接收者才会收到通知（见下文）。 |
如果你希望保留实时回答预览，但隐藏中间的工具/进度行，请使用对象形式：
`blockStreaming` 与 `streaming` 相互独立：
```json5
{
channels: {
matrix: {
streaming: {
mode: "partial",
preview: {
toolProgress: false,
},
},
},
},
}
```
| `streaming` | `blockStreaming: true` | `blockStreaming: false`（默认） |
| ----------------------- | --------------------------------------------------------------- | ----------------------------------------------- |
| `"partial"` / `"quiet"` | 当前分块使用实时草稿，已完成分块保留为消息 | 当前分块使用实时草稿，并原地完成最终定稿 |
| `"off"` | 每个已完成分块发送一条会通知的 Matrix 消息 | 整个完整回复发送一条会通知的 Matrix 消息 |
| `streaming` | 行为 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"off"`（默认） | 等待完整回复，然后发送一次。`true` ↔ `"partial"`，`false` ↔ `"off"`。 |
| `"partial"` | 在模型写入当前块时，原地编辑一条普通文本消息。标准 Matrix 客户端可能会在首次预览时通知，而不是在最终编辑时通知。 |
| `"quiet"` | 与 `"partial"` 相同，但该消息是一个不通知的 notice。只有当某条按用户生效的推送规则与最终完成的编辑匹配时，接收者才会收到通知（见下文）。 |
`blockStreaming` 独立于 `streaming`：
| `streaming` | `blockStreaming: true` | `blockStreaming: false`（默认） |
| ----------------------- | ------------------------------------------------------------------- | ---------------------------------------------------- |
| `"partial"` / `"quiet"` | 当前块使用实时草稿，已完成的块保留为消息 | 当前块使用实时草稿，并原地完成最终定稿 |
| `"off"` | 每个已完成块发送一条会通知的 Matrix 消息 | 完整回复发送一条会通知的 Matrix 消息 |
说明：
- 如果预览内容增长超过 Matrix 的单事件大小限制，OpenClaw 会停止预览流式传输，并回退为仅发送最终内容。
- 媒体回复始终会正常发送附件。如果过期预览已无法安全复用，OpenClaw 会在发送最终媒体回复前将其隐藏。
- 预览编辑会额外消耗 Matrix API 调用。如果你希望采用最保守的速率限制配置，请保持 `streaming: "off"`。
- 如果预览内容增长到超过 Matrix 的单事件大小限制，OpenClaw 会停止预览流式传输，并回退到仅发送最终结果。
- 媒体回复始终会正常发送附件。如果陈旧的预览已无法安全复用，OpenClaw 会在发送最终媒体回复前将其擦除。
- 当 Matrix 预览流式传输处于激活状态时，工具进度预览更新默认启用。设置 `streaming.preview.toolProgress: false` 可以保留回答文本的预览编辑，同时让工具进度继续走普通传递路径。
- 预览编辑会产生额外的 Matrix API 调用。如果你希望采用最保守的速率限制配置，请保持 `streaming: "off"`。
## 审批元数据
Matrix 原生审批提示是普通的 `m.room.message` 事件，并在 `com.openclaw.approval` 下携带 OpenClaw 特有的自定义事件内容。Matrix 允许自定义事件内容键，因此标准客户端仍会渲染文本正文，而支持 OpenClaw 的客户端则可以读取结构化的审批 ID、类型、状态、可用决策以及 exec/plugin 详情。
Matrix 原生审批提示是普通的 `m.room.message` 事件，其中包含位于 `com.openclaw.approval` 下的 OpenClaw 专用自定义事件内容。Matrix 允许自定义事件内容键，因此标准客户端仍会渲染文本正文，而支持 OpenClaw 的客户端则可以读取结构化的审批 ID、类型、状态、可用决定以及 exec/plugin 详细信息。
当审批提示过长、无法放入单个 Matrix 事件时，OpenClaw 会对可见文本进行分块，并且只将 `com.openclaw.approval` 附加到第一块。用于允许/拒绝决策的回应会绑定到第一个事件，因此长提示与单事件提示会保持相同的审批目标。
当审批提示过长、无法放入单个 Matrix 事件时，OpenClaw 会将可见文本分块，并且仅将 `com.openclaw.approval` 附加到第一个块。用于允许/拒绝决定的回应会绑定到第一个事件，因此长提示与单事件提示保持相同的审批目标。
### quiet 最终预览的自托管推送规则
`streaming: "quiet"` 只会在某个分块或整轮内容最终完成时通知接收者——按用户设置的推送规则必须匹配最终完成的预览标记。完整配置方法（接收者令牌、pusher 检查、规则安装、各 homeserver 注意事项）请参见 [quiet 预览的 Matrix 推送规则](/zh-CN/channels/matrix-push-rules)。
`streaming: "quiet"` 只有在某个块或轮次最终完成时才会通知接收者——必须有一条按用户生效的推送规则与最终预览标记匹配。完整做法请参见 [用于 quiet 预览的 Matrix 推送规则](/zh-CN/channels/matrix-push-rules)（接收者令牌、pusher 检查、规则安装、各 homeserver 说明）。
## 机器人到机器人房间
## 机器人到机器人的房间
默认情况下，来自其他已配置 OpenClaw Matrix 账户的 Matrix 消息会被忽略。
默认情况下，来自其他已配置 OpenClaw Matrix 账号的 Matrix 消息会被忽略。
当你确实希望启用智能体之间的 Matrix 通信时，请使用 `allowBots`：
当你明确希望允许智能体之间的 Matrix 通信时，请使用 `allowBots`：
```json5
{
@ -246,19 +264,19 @@ Matrix 原生审批提示是普通的 `m.room.message` 事件，并在 `com.open
}
```
- `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 状态。
在加密的（端到端加密）房间中，出站图片事件会使用 `thumbnail_file`，因此图片预览会与完整附件一起被加密。未加密房间仍使用普通的 `thumbnail_url`。无需配置——该插件会自动检测端到端加密状态。
所有 `openclaw matrix` 命令都支持 `--verbose`（完整诊断）、`--json`（机器可读输出）和 `--account <id>`（多账户设置）。默认输出较为简洁，并使用安静的内部 SDK 日志记录。以下示例展示的是规范形式；可根据需要添加这些标志。
所有 `openclaw matrix` 命令都接受 `--verbose`（完整诊断信息）、`--json`（机器可读输出）和 `--account <id>`（多账号设置）。默认输出较为简洁，内部 SDK 日志保持安静。下面的示例展示了规范形式；你可以按需添加这些标志。
### 启用加密
@ -266,12 +284,12 @@ Matrix 原生审批提示是普通的 `m.room.message` 事件，并在 `com.open
openclaw matrix encryption setup
```
引导设置秘密存储和交叉签名，在需要时创建房间密钥备份，然后打印状态和后续步骤。常用标志：
引导初始化密钥存储和交叉签名，必要时创建房间密钥备份，然后输出 Status 和后续步骤。常用标志：
- `--recovery-key <key>` 在引导设置前应用恢复密钥（优先使用下面记录的 stdin 形式）
- `--force-reset-cross-signing` 丢弃当前交叉签名身份并创建新身份（仅在你明确要这么做时使用）
- `--recovery-key <key>` 在引导初始化之前应用恢复密钥（更推荐使用下文记录的 stdin 形式）
- `--force-reset-cross-signing` 丢弃当前的交叉签名身份并创建新身份（仅在明确需要时使用）
对于新账户，请在创建时启用 E2EE：
对于新账号，可在创建时启用端到端加密：
```bash
openclaw matrix account add \
@ -305,19 +323,21 @@ openclaw matrix verify status
openclaw matrix verify status --include-recovery-key --json
```
`verify status` 会报告三个独立的信任信号（`--verbose` 会显示全部）：
`verify status` 会报告三个彼此独立的信任信号（`--verbose` 会显示全部）：
- `Locally trusted`：仅被此客户端信任
- `Locally trusted`：仅被当前客户端信任
- `Cross-signing verified`：SDK 报告已通过交叉签名验证
- `Signed by owner`：已由你自己的 self-signing 密钥签名（仅用于诊断）
- `Signed by owner`：已由你自己的自签名密钥签名（仅用于诊断）
只有当 `Cross-signing verified` 为 `yes` 时，`Verified by owner` 才会变为 `yes`。仅有本地信任或 owner 签名并不足够。
只有当 `Cross-signing verified` 为 `yes` 时，`Verified by owner` 才会变为 `yes`。
`--allow-degraded-local-state` 会在不先准备 Matrix 账户的情况下返回尽力而为的诊断信息；适用于离线或部分已配置的探测。
单独的本地信任或 owner 签名都不足以满足条件。
`--allow-degraded-local-state` 会在不预先准备 Matrix 账号的情况下返回尽力而为的诊断信息；这对于离线或仅部分配置的探测很有用。
### 使用恢复密钥验证此设备
恢复密钥是敏感信息——应通过 stdin 管道传入，而不是直接放在命令行中。设置 `MATRIX_RECOVERY_KEY`（或命名账户使用 `MATRIX_<ID>_RECOVERY_KEY`）：
恢复密钥属于敏感信息——应通过 stdin 管道传入，而不要直接写在命令行中。请设置 `MATRIX_RECOVERY_KEY`（或命名账号的 `MATRIX_<ID>_RECOVERY_KEY`）：
```bash
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
@ -325,39 +345,39 @@ printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-
该命令会报告三种状态：
- `Recovery key accepted`：Matrix 已接受该密钥用于秘密存储或设备信任。
- `Backup usable`：可使用受信任的恢复材料加载房间密钥备份。
- `Device verified by owner`：此设备已获得完整的 Matrix 交叉签名身份信任。
- `Recovery key accepted`：Matrix 已接受该密钥，用于密钥存储或设备信任。
- `Backup usable`：可以使用受信任的恢复材料加载房间密钥备份。
- `Device verified by owner`：该设备已获得完整的 Matrix 交叉签名身份信任。
即使恢复密钥已解锁备份材料，只要完整身份信任尚未完成，该命令仍会以非零状态退出。在这种情况下，请从另一个 Matrix 客户端完成自我验证：
即使恢复密钥已解锁备份材料，只要完整身份信任尚未完成，命令仍会以非零状态退出。这种情况下，请在另一个 Matrix 客户端中完成自验证：
```bash
openclaw matrix verify self
```
`verify self` 会等待直到 `Cross-signing verified: yes`，然后才会成功退出。可使用 `--timeout-ms <ms>` 调整等待时间。
`verify self` 会等待 `Cross-signing verified: yes`，然后才会成功退出。可使用 `--timeout-ms <ms>` 调整等待时间。
也接受字面密钥形式 `openclaw matrix verify device "<recovery-key>"`，但密钥会进入你的 shell 历史记录。
也支持字面量密钥形式 `openclaw matrix verify device "<recovery-key>"`，但该密钥会进入你的 shell 历史记录。
### 引导设置或修复交叉签名
### 引导初始化或修复交叉签名
```bash
openclaw matrix verify bootstrap
```
`verify bootstrap` 是加密账户的修复和设置命令。它会按顺序执行以下操作：
`verify bootstrap` 是面向加密账号的修复和设置命令。它会依次执行以下操作：
- 引导设置秘密存储，并在可能时复用现有恢复密钥
- 引导设置交叉签名并上传缺失的公钥
- 引导初始化密钥存储，并在可能时复用现有恢复密钥
- 引导初始化交叉签名，并上传缺失的公钥
- 标记并交叉签名当前设备
- 如果服务器端尚不存在房间密钥备份，则创建一个
如果 homeserver 需要 UIA 才能上传交叉签名密钥，OpenClaw 会先尝试无认证方式，然后尝试 `m.login.dummy`，最后尝试 `m.login.password`（需要 `channels.matrix.password`）。
如果 homeserver 在上传交叉签名密钥时要求 UIA，OpenClaw 会先尝试无认证，再尝试 `m.login.dummy`，最后尝试 `m.login.password`（需要 `channels.matrix.password`）。
常用标志：
- `--recovery-key-stdin`（与 `printf '%s\n' "$MATRIX_RECOVERY_KEY" | …` 搭配使用）或 `--recovery-key <key>`
- `--force-reset-cross-signing`，用于丢弃当前交叉签名身份（仅在明确需要时）
- `--recovery-key-stdin`（搭配 `printf '%s\n' "$MATRIX_RECOVERY_KEY" | …` 使用）或 `--recovery-key <key>`
- `--force-reset-cross-signing` 用于丢弃当前交叉签名身份（仅在明确需要时使用）
### 房间密钥备份
@ -366,15 +386,15 @@ openclaw matrix verify backup status
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin
```
`backup status` 会显示是否存在服务器端备份，以及此设备是否可以解密该备份。`backup restore` 会将已备份的房间密钥导入本地加密存储；如果恢复密钥已存在于磁盘上，则可以省略 `--recovery-key-stdin`。
`backup status` 会显示服务器端备份是否存在，以及当前设备是否能够解密它。`backup restore` 会将已备份的房间密钥导入本地加密存储；如果恢复密钥已经保存在磁盘上，你可以省略 `--recovery-key-stdin`。
如需用新的基线替换损坏的备份（接受丢失无法恢复的旧历史记录；如果当前备份密钥无法加载，也可重新创建秘密存储）：
若要使用全新的基线替换损坏的备份（接受丢失无法恢复的旧历史；如果当前备份密钥无法加载，也可以重建密钥存储）：
```bash
openclaw matrix verify backup reset --yes
```
仅当你明确希望先前的恢复密钥不再能解锁新的备份基线时，才添加 `--rotate-recovery-key`。
只有在你明确希望旧恢复密钥不再能解锁新的备份基线时，才添加 `--rotate-recovery-key`。
### 列出、请求和响应验证
@ -382,46 +402,46 @@ openclaw matrix verify backup reset --yes
openclaw matrix verify list
```
列出所选账户的待处理验证请求。
列出所选账号的待处理验证请求。
```bash
openclaw matrix verify request --own-user
openclaw matrix verify request --user-id @ops:example.org --device-id ABCDEF
```
从此 OpenClaw 账户发送验证请求。`--own-user` 请求自我验证（你需要在同一用户的另一个 Matrix 客户端中接受提示）；`--user-id`/`--device-id`/`--room-id` 则用于指定其他人。`--own-user` 不能与其他目标标志组合使用。
从当前 OpenClaw 账号发送验证请求。`--own-user` 请求自验证（你需要在同一用户的另一个 Matrix 客户端中接受提示）；`--user-id` / `--device-id` / `--room-id` 用于指定其他人。`--own-user` 不能与其他目标标志一起使用。
对于更底层的生命周期处理——通常是在你从另一个客户端跟踪入站请求时——以下命令会作用于某个特定请求 `<id>`（由 `verify list` 和 `verify request` 输出）：
对于更底层的生命周期处理——通常是在跟随来自另一个客户端的入站请求时——以下命令会作用于某个特定请求 `<id>`（由 `verify list` 和 `verify request` 输出）：
| Command | 用途 |
| ------------------------------------------ | ------------------------------------ |
| `openclaw matrix verify accept <id>` | 接受入站请求 |
| `openclaw matrix verify start <id>` | 启动 SAS 流程 |
| `openclaw matrix verify sas <id>` | 打印 SAS 表情符号或数字 |
| `openclaw matrix verify confirm-sas <id>` | 确认 SAS 与另一客户端显示内容一致 |
| `openclaw matrix verify mismatch-sas <id>` | 当表情符号或数字不匹配时拒绝 SAS |
| `openclaw matrix verify cancel <id>` | 取消；可选 `--reason <text>` 和 `--code <matrix-code>` |
| 命令 | 用途 |
| ------------------------------------------ | ------------------------------------------------------------------- |
| `openclaw matrix verify accept <id>` | 接受入站请求 |
| `openclaw matrix verify start <id>` | 启动 SAS 流程 |
| `openclaw matrix verify sas <id>` | 输出 SAS 表情符号或数字 |
| `openclaw matrix verify confirm-sas <id>` | 确认 SAS 与另一客户端显示的内容一致 |
| `openclaw matrix verify mismatch-sas <id>` | 当表情符号或数字不一致时拒绝 SAS |
| `openclaw matrix verify cancel <id>` | 取消；可选接受 `--reason <text>` 和 `--code <matrix-code>` |
当验证锚定到特定私信房间时，`accept`、`start`、`sas`、`confirm-sas`、`mismatch-sas` 和 `cancel` 都接受 `--user-id` 和 `--room-id` 作为私信后续提示。
`accept`、`start`、`sas`、`confirm-sas`、`mismatch-sas` 和 `cancel` 都接受 `--user-id` 和 `--room-id`，可在验证锚定到特定私信房间时，作为私信后续提示。
### 多账户说明
### 多账号说明
如果不传入 `--account <id>`，Matrix CLI 命令会使用隐式默认账户。如果你有多个命名账户且未设置 `channels.matrix.defaultAccount`，命令将拒绝猜测并要求你选择。当某个命名账户的 E2EE 被禁用或不可用时，错误会指向该账户的配置键，例如 `channels.matrix.accounts.assistant.encryption`。
如果未提供 `--account <id>`，Matrix CLI 命令会使用隐式默认账号。如果你有多个命名账号，且未设置 `channels.matrix.defaultAccount`，命令将拒绝猜测并要求你进行选择。当某个命名账号的端到端加密被禁用或不可用时，错误信息会指向该账号的配置键，例如 `channels.matrix.accounts.assistant.encryption`。
<AccordionGroup>
<Accordion title="启动行为">
当 `encryption: true` 时，`startupVerification` 默认值为 `"if-unverified"`。启动时，未验证设备会在另一个 Matrix 客户端中请求自我验证，同时跳过重复请求并应用冷却时间（默认 24 小时）。可使用 `startupVerificationCooldownHours` 调整，或通过 `startupVerification: "off"` 禁用。
当 `encryption: true` 时，`startupVerification` 默认为 `"if-unverified"`。启动时，未验证设备会在另一个 Matrix 客户端中请求自验证，同时跳过重复请求并应用冷却时间（默认 24 小时）。可使用 `startupVerificationCooldownHours` 调整，或通过 `startupVerification: "off"` 禁用。
启动时还会运行一次保守的加密引导流程，复用当前的秘密存储和交叉签名身份。如果引导状态损坏，OpenClaw 即使没有 `channels.matrix.password` 也会尝试受保护的修复；如果 homeserver 需要密码 UIA，启动时会记录警告，但不会导致致命错误。已由 owner 签名的设备会被保留。
启动时还会执行一次保守的加密引导检查，复用当前的密钥存储和交叉签名身份。如果引导状态损坏，即使没有 `channels.matrix.password`，OpenClaw 也会尝试受保护的修复；如果 homeserver 需要密码 UIA，启动时会记录警告，但不会造成致命错误。已由 owner 签名的设备会被保留。
完整升级流程请参见 [Matrix 迁移](/zh-CN/channels/matrix-migration)。
</Accordion>
<Accordion title="验证通知">
Matrix 会将验证生命周期通知作为 `m.notice` 消息发布到严格的私信验证房间中：请求、就绪（附“通过表情符号验证”的说明）、开始/完成，以及在可用时发布 SAS（表情符号/数字）详情。
Matrix 会将验证生命周期通知作为 `m.notice` 消息发布到严格私信验证房间中：请求、就绪（带有“通过表情符号验证”的说明）、开始/完成，以及在可用时显示 SAS（表情符号/数字）详情。
来自另一个 Matrix 客户端的入站请求会被跟踪并自动接受。对于自我验证，OpenClaw 会在表情符号验证可用时自动启动 SAS 流程并确认自己这一侧——你仍需要在你的 Matrix 客户端中比较并确认“它们匹配”。
来自另一个 Matrix 客户端的入站请求会被跟踪并自动接受。对于自验证，OpenClaw 会在表情符号验证可用后自动启动 SAS 流程并确认自身这一侧——你仍然需要在你的 Matrix 客户端中进行比对并确认“它们匹配”。
验证系统通知不会转发到智能体聊天管道。
@ -439,7 +459,7 @@ openclaw matrix account add \
--device-name OpenClaw-Gateway
```
对于令牌认证，请在你的 Matrix 客户端或管理员 UI 中创建一个新的访问令牌，然后更新 OpenClaw：
对于令牌认证，请先在你的 Matrix 客户端或管理界面中创建一个新的访问令牌，然后更新 OpenClaw：
```bash
openclaw matrix account add \
@ -448,12 +468,12 @@ openclaw matrix account add \
--access-token '<token>'
```
将 `assistant` 替换为失败命令中的账户 ID，或省略 `--account` 以使用默认账户。
将 `assistant` 替换为失败命令中的账号 ID；如果是默认账号，则省略 `--account`。
</Accordion>
<Accordion title="设备管理">
旧的由 OpenClaw 管理的设备可能会不断累积。列出并清理：
<Accordion title="设备卫生">
旧的由 OpenClaw 管理的设备可能会逐渐累积。可列出并清理：
```bash
openclaw matrix devices list
@ -463,78 +483,78 @@ openclaw matrix devices prune-stale
</Accordion>
<Accordion title="加密存储">
Matrix E2EE 使用官方 `matrix-js-sdk` Rust 加密路径，并以 `fake-indexeddb` 作为 IndexedDB 兼容层。加密状态会持久化到 `crypto-idb-snapshot.json`（文件权限受限）。
Matrix 端到端加密使用官方 `matrix-js-sdk` 的 Rust 加密路径，并使用 `fake-indexeddb` 作为 IndexedDB shim。加密状态会持久化到 `crypto-idb-snapshot.json`（文件权限受限）。
加密运行时状态位于 `~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/` 下，其中包括同步存储、加密存储、恢复密钥、IDB 快照、线程绑定和启动验证状态。当令牌变化但账户身份保持不变时，OpenClaw 会复用现有的最佳根目录，以便先前状态仍然可见。
加密的运行时状态位于 `~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/` 下，其中包括同步存储、加密存储、恢复密钥、IDB 快照、线程绑定和启动验证状态。当令牌变化但账号身份保持不变时，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 可直接接受 `mxc://` 头像 URL；当你传入 `http://` 或 `https://` 时，OpenClaw 会先上传文件，然后将解析后的 `mxc://` URL 存储到 `channels.matrix.avatarUrl`（或按账户覆盖的值）中。
你可以在一次调用中同时传入这两个选项。Matrix 可直接接受 `mxc://` 头像 URL；当你传入 `http://` 或 `https://` 时，OpenClaw 会先上传文件，然后将解析得到的 `mxc://` URL 存入 `channels.matrix.avatarUrl`（或对应账号的覆盖项）。
## 线程
Matrix 同时支持自动回复和消息工具发送使用原生 Matrix 线程。有两个相互独立的旋钮用于控制行为：
Matrix 同时支持自动回复和消息工具发送时使用原生 Matrix 线程。有两个彼此独立的开关控制其行为：
### 会话路由（`sessionScope`）
`dm.sessionScope` 决定 Matrix 私信房间如何映射到 OpenClaw 会话：
- `"per-user"`（默认）：与同一路由对端相关的所有私信房间共享一个会话。
- `"per-room"`：每个 Matrix 私信房间都会获得自己的会话键，即使对端是同一个人。
- `"per-room"`：每个 Matrix 私信房间都有各自独立的会话键，即使对端相同也是如此。
显式会话绑定始终优先于 `sessionScope`，因此已绑定的房间和线程会保持其选定的目标会话。
显式的对话绑定始终优先于 `sessionScope`，因此已绑定的房间和线程会继续使用其选定的目标会话。
### 回复线程（`threadReplies`）
### 回复线程化（`threadReplies`）
`threadReplies` 决定机器人将回复发布到哪里：
- `"off"`：回复位于顶层。入站线程消息仍保留在父级会话上。
- `"inbound"`：仅当入站消息本身已经位于该线程中时，才在线程内回复。
- `"always"`：在线程中回复，线程根为触发消息；从第一次触发开始，该会话将通过匹配的线程作用域会话进行路由。
- `"off"`：回复为顶层消息。入站线程消息仍保留在父会话中。
- `"inbound"`：仅当入站消息本身已位于某线程中时，才在线程内回复。
- `"always"`：在线程中回复，且该线程以触发消息为根；从第一次触发开始，该对话就会通过匹配的线程作用域会话进行路由。
`dm.threadReplies` 仅对私信覆盖此行为——例如，让房间线程保持隔离，同时让私信保持扁平。
`dm.threadReplies` 仅对私信覆盖此设置——例如，可让房间线程彼此隔离，同时保持私信为扁平形式。
### 线程继承和斜杠命令
- 入站线程消息会将线程根消息作为额外的智能体上下文。
- 当消息工具发送目标为同一房间（或同一私信用户目标）时，会自动继承当前 Matrix 线程，除非显式提供了 `threadId`。
- 只有当当前会话元数据能证明是在同一 Matrix 账户上的同一个私信对端时，才会复用私信用户目标；否则 OpenClaw 会回退到常规的按用户作用域路由。
- `/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 和绑定线程的 `/acp spawn` 都可在 Matrix 房间和私信中使用。
- 入站线程消息会将线程根消息作为额外的智能体上下文包含进来。
- 消息工具发送在目标为同一房间（或相同的私信用户目标）时，会自动继承当前 Matrix 线程，除非显式提供了 `threadId`。
- 私信用户目标复用仅会在当前会话元数据能够证明：这是同一个 Matrix 账号下的同一私信对端时才会生效；否则 OpenClaw 会回退到普通的用户作用域路由。
- `/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定线程的 `/acp spawn` 都可在 Matrix 房间和私信中使用。
- 当 `threadBindings.spawnSubagentSessions: true` 时，顶层 `/focus` 会创建一个新的 Matrix 线程，并将其绑定到目标会话。
- 在现有 Matrix 线程中运行 `/focus` 或 `/acp spawn --thread here`，会就地绑定该线程。
- 在现有 Matrix 线程中运行 `/focus` 或 `/acp spawn --thread here` 时，会直接在该线程上完成绑定。
当 OpenClaw 检测到某个 Matrix 私信房间与同一共享会话上的另一个私信房间发生冲突时，它会在该房间中发布一次性 `m.notice`，指向 `/focus` 这一逃生口，并建议调整 `dm.sessionScope`。只有在线程绑定已启用时，才会显示此通知。
当 OpenClaw 检测到某个 Matrix 私信房间与同一共享会话上的另一个私信房间发生冲突时，它会在该房间中发布一条一次性的 `m.notice`，指向 `/focus` 这一脱困方式，并建议更改 `dm.sessionScope`。仅当线程绑定已启用时，才会显示该通知。
## ACP 会话绑定
Matrix 房间、私信和现有 Matrix 线程都可以转换为持久化 ACP 工作区，而无需更改聊天界面。
Matrix 房间、私信和现有 Matrix 线程都可以转换为持久的 ACP 工作区，而无需改变聊天界面。
适合操作员的快速流程：
快速操作流程：
- 在你想继续使用的 Matrix 私信、房间或现有线程中运行 `/acp spawn codex --bind here`。
- 在顶层 Matrix 私信或房间中，当前私信/房间会保留为聊天界面，后续消息会路由到新建的 ACP 会话。
- 在现有 Matrix 线程中，`--bind here` 会就地绑定当前线程。
- `/new` 和 `/reset` 会就地重置同一个已绑定的 ACP 会话。
- `/acp close` 会关闭 ACP 会话并移除绑定。
- 在顶层 Matrix 私信或房间中，当前私信/房间仍然是聊天界面，后续消息会路由到新创建的 ACP 会话。
- 在现有 Matrix 线程中，`--bind here` 会直接绑定当前线程。
- `/new` 和 `/reset` 会在原地重置同一个已绑定的 ACP 会话。
- `/acp close` 会关闭 ACP 会话并移除该绑定。
说明：
- `--bind here` 不会创建子 Matrix 线程。
- `threadBindings.spawnAcpSessions` 仅在 `/acp spawn --thread auto|here` 时需要，因为此时 OpenClaw 需要创建或绑定子 Matrix 线程。
- `threadBindings.spawnAcpSessions` 仅在 `/acp spawn --thread auto|here` 时需要，此时 OpenClaw 需要创建或绑定一个子 Matrix 线程。
### 线程绑定配置
Matrix 会继承来自 `session.threadBindings` 的全局默认值，同时也支持按渠道覆盖：
Matrix 会继承 `session.threadBindings` 中的全局默认值，同时也支持按渠道覆盖：
- `threadBindings.enabled`
- `threadBindings.idleHours`
@ -542,50 +562,50 @@ Matrix 会继承来自 `session.threadBindings` 的全局默认值，同时也
- `threadBindings.spawnSubagentSessions`
- `threadBindings.spawnAcpSessions`
Matrix 线程绑定的 spawn 标志为选择启用：
Matrix 的线程绑定生成标志为显式启用：
- 设置 `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` 只会移除机器人指定表情符号的回应。
- `react` 向 Matrix 事件添加一个回应。
- `reactions` 列出 Matrix 事件当前的回应汇总。
- `emoji=""` 会移除该事件上机器人自己的回应。
- `remove: true` 仅移除机器人对此指定 emoji 的回应。
**解析顺序**（先定义的值优先）：
| Setting | 顺序 |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `ackReaction` | 按账户 → 渠道 → `messages.ackReaction` → 智能体身份 emoji 回退值 |
| `ackReactionScope` | 按账户 → 渠道 → `messages.ackReactionScope` → 默认 `"group-mentions"` |
| `reactionNotifications` | 按账户 → 渠道 → 默认 `"own"` |
| 设置 | 顺序 |
| ----------------------- | -------------------------------------------------------------------------------- |
| `ackReaction` | 按账号 → 按渠道 → `messages.ackReaction` → 智能体身份 emoji 回退值 |
| `ackReactionScope` | 按账号 → 按渠道 → `messages.ackReactionScope` → 默认 `"group-mentions"` |
| `reactionNotifications` | 按账号 → 按渠道 → 默认 `"own"` |
当 `reactionNotifications: "own"` 时，如果新增的 `m.reaction` 事件目标是机器人发送的 Matrix 消息，则会转发该事件；`"off"` 则会禁用回应系统事件。回应移除不会被合成为系统事件，因为 Matrix 将其表现为 redaction，而不是独立的 `m.reaction` 移除事件。
`reactionNotifications: "own"` 会在新增的 `m.reaction` 事件目标是由机器人发送的 Matrix 消息时转发这些事件；`"off"` 会禁用回应系统事件。回应移除不会被合成为系统事件，因为 Matrix 将其表现为 redact，而不是独立的 `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: "allowlist"` 会将补充上下文过滤为仅保留通过当前房间/用户允许列表检查的发送者内容。
- `contextVisibility: "allowlist_quote"` 与 `allowlist` 类似，但仍会保留一条显式引用的回复。
- `contextVisibility: "all"` 是默认值。补充上下文会按接收到的样子保留。
- `contextVisibility: "allowlist"` 会根据当前房间/用户允许列表检查，将补充上下文过滤到允许的发送者。
- `contextVisibility: "allowlist_quote"` 的行为类似 `allowlist`，但仍会保留一条明确引用的回复。
此设置影响的是补充上下文的可见性，而不是入站消息本身是否可以触发回复。
触发授权仍由 `groupPolicy`、`groups`、`groupAllowFrom` 和私信策略设置决定。
触发授权仍然来自 `groupPolicy`、`groups`、`groupAllowFrom` 和私信策略设置。
## 私信和房间策略
@ -608,7 +628,7 @@ Matrix 支持共享的 `contextVisibility` 控制，用于补充房间上下文
}
```
如果你想完全静默私信，同时保留房间功能，请设置 `dm.enabled: false`：
如果要完全静默私信，同时保持房间功能正常，请设置 `dm.enabled: false`：
```json5
{
@ -631,13 +651,13 @@ openclaw pairing list matrix
openclaw pairing approve matrix <CODE>
```
如果某个尚未批准的 Matrix 用户在获批前持续向你发消息，OpenClaw 会复用同一个待处理配对码，并且可能会在短暂冷却后发送提醒回复，而不是生成新的配对码。
如果某个尚未获批的 Matrix 用户在批准前持续向你发送消息，OpenClaw 会复用同一个待处理配对码，并且在短暂冷却后，可能发送提醒回复，而不是生成新的配对码。
有关共享的私信配对流程和存储布局，请参见 [配对](/zh-CN/channels/pairing)。
## 直接房间修复
如果私信状态漂移而不同步，OpenClaw 可能会出现过时的 `m.direct` 映射，指向旧的一对一房间，而不是当前有效的私信。要检查某个对端的当前映射：
如果私信状态发生漂移并失去同步，OpenClaw 可能会保留过时的 `m.direct` 映射，指向旧的一对一房间，而不是当前有效的私信。检查某个对端的当前映射：
```bash
openclaw matrix direct inspect --user-id @alice:example.org
@ -649,47 +669,47 @@ openclaw matrix direct inspect --user-id @alice:example.org
openclaw matrix direct repair --user-id @alice:example.org
```
这两个命令都接受 `--account <id>`，用于多账户设置。修复流程会：
这两个命令都支持 `--account <id>`，用于多账号设置。修复流程如下：
- 优先选择已在 `m.direct` 中映射的严格一对一私信
- 如果没有，则回退到当前已加入的、与该用户的任意严格一对一私信
- 如果仍不存在健康的私信，则创建一个新的直接房间并重写 `m.direct`
- 如果不存在健康的私信，则创建一个新的直接房间并重写 `m.direct`
它不会自动删除旧房间。它会选取健康的私信并更新映射，以便未来的 Matrix 发送、验证通知和其他私信流程都能指向正确的房间。
它不会自动删除旧房间。它会选择健康的私信并更新映射，以便后续的 Matrix 发送、验证通知和其他私信流程都能定位到正确房间。
## Exec 审批
Matrix 可以作为原生审批客户端。配置位于 `channels.matrix.execApprovals` 下（或按账户覆盖时使用 `channels.matrix.accounts.<account>.execApprovals`）：
Matrix 可以作为原生审批客户端。配置位于 `channels.matrix.execApprovals` 下（或按账号覆盖时使用 `channels.matrix.accounts.<account>.execApprovals`）：
- `enabled`：通过 Matrix 原生提示传递审批。未设置或为 `"auto"` 时，一旦至少能解析出一个审批者，Matrix 就会自动启用。显式设置 `false` 可禁用。
- `approvers`：允许批准 exec 请求的 Matrix 用户 ID（`@owner:example.org`）。可选——默认回退到 `channels.matrix.dm.allowFrom`。
- `target`：提示发送到哪里。`"dm"`（默认）发送到审批者私信；`"channel"` 发送到发起请求的 Matrix 房间或私信；`"both"` 同时发送到两者。
- `enabled`：通过 Matrix 原生提示传递审批。未设置或为 `"auto"` 时，一旦至少能解析出一个审批人，Matrix 就会自动启用。设置为 `false` 可显式禁用。
- `approvers`：允许审批 exec 请求的 Matrix 用户 ID（`@owner:example.org`）。可选——会回退到 `channels.matrix.dm.allowFrom`。
- `target`：提示发送到哪里。`"dm"`（默认）发送到审批人的私信；`"channel"` 发送到原始 Matrix 房间或私信；`"both"` 同时发送到两处。
- `agentFilter` / `sessionFilter`：可选允许列表，用于限制哪些智能体/会话会触发 Matrix 传递。
不同审批类型的授权略有不同：
- **Exec 审批** 使用 `execApprovals.approvers`，回退到 `dm.allowFrom`。
- **插件审批** 仅通过 `dm.allowFrom` 进行授权。
- **Exec 审批** 使用 `execApprovals.approvers`，并回退到 `dm.allowFrom`。
- **插件审批** 仅通过 `dm.allowFrom` 授权。
这两类审批共享 Matrix 回应快捷方式和消息更新。审批者会在主要审批消息上看到回应快捷方式：
这两种审批都共享 Matrix 回应快捷方式和消息更新。审批人在主审批消息上会看到回应快捷方式：
- `✅` 允许一次
- `❌` 拒绝
- `♾️` 始终允许（当有效 exec 策略允许时）
- `♾️` 始终允许（当实际的 exec 策略允许时）
回退斜杠命令：`/approve <id> allow-once`、`/approve <id> allow-always`、`/approve <id> deny`。
只有已解析出的审批者才能批准或拒绝。通过渠道发送的 exec 审批会包含命令文本——仅应在可信房间中启用 `channel` 或 `both`。
只有已解析出的审批人才能批准或拒绝。通过渠道传递 exec 审批时会包含命令文本——仅应在受信任房间中启用 `channel` 或 `both`。
相关内容： [Exec 审批](/zh-CN/tools/exec-approvals)。
## 斜杠命令
斜杠命令（`/new`、`/reset`、`/model`、`/focus`、`/unfocus`、`/agents`、`/session`、`/acp`、`/approve` 等）可以直接在私信中使用。在房间中，OpenClaw 也能识别以前缀为机器人自身 Matrix 提及的命令，因此 `@bot:server /new` 会触发命令路径，而无需自定义提及正则表达式。这样一来，当用户在 Element 或类似客户端中先通过 Tab 补全机器人再输入命令时，机器人仍能响应这种房间风格的 `@mention /command` 消息。
斜杠命令（`/new`、`/reset`、`/model`、`/focus`、`/unfocus`、`/agents`、`/session`、`/acp`、`/approve` 等）可直接在私信中使用。在房间中，OpenClaw 还会识别以前缀为机器人自身 Matrix 提及的命令，因此 `@bot:server /new` 会触发命令路径，而无需自定义提及正则。这使机器人能够响应 Element 及类似客户端发出的房间风格 `@mention /command` 帖子——即用户在输入命令前先通过 Tab 补全了机器人。
授权规则仍然适用：命令发送者必须满足与普通消息相同的私信或房间允许列表 / owner 策略。
## 多账户
## 多账号
```json5
{
@ -721,29 +741,27 @@ Matrix 可以作为原生审批客户端。配置位于 `channels.matrix.execApp
**继承：**
- 顶层 `channels.matrix` 值会作为命名账户的默认值，除非某个账户进行了覆盖。
- 可通过 `groups.<room>.account` 将继承的房间条目限定到特定账户。未设置 `account` 的条目会由各账户共享；当默认账户配置在顶层时，`account: "default"` 仍然有效。
- 顶层 `channels.matrix` 值会作为命名账号的默认值，除非账号自身进行了覆盖。
- 可通过 `groups.<room>.account` 将继承的房间条目限定到特定账号。未设置 `account` 的条目会在各账号之间共享；当默认账号配置在顶层时，`account: "default"` 仍然有效。
**默认账户选择：**
**默认账号选择：**
- 设置 `defaultAccount` 以选择隐式路由、探测和 CLI 命令优先使用的命名账户。
- 如果你有多个账户，且其中一个账户名称恰好是 `default`，即使未设置 `defaultAccount`，OpenClaw 也会隐式使用它。
- 如果你有多个命名账户但未选择默认账户，CLI 命令会拒绝猜测——请设置 `defaultAccount` 或传入 `--account <id>`。
- 只有当顶层 `channels.matrix.*` 配置块的认证完整时（`homeserver` + `accessToken`，或 `homeserver` + `userId` + `password`），它才会被视为隐式 `default` 账户。只要缓存凭证已覆盖认证，命名账户仍可通过 `homeserver` + `userId` 被发现。
- 设置 `defaultAccount`，以指定隐式路由、探测和 CLI 命令优先使用的命名账号。
- 如果你有多个账号，其中一个账号的名称恰好就是 `default`，即使未设置 `defaultAccount`，OpenClaw 也会隐式使用它。
- 如果你有多个命名账号且未选择默认账号，CLI 命令将拒绝猜测——请设置 `defaultAccount` 或传入 `--account <id>`。
- 只有当顶层 `channels.matrix.*` 块的认证完整时（`homeserver` + `accessToken`，或 `homeserver` + `userId` + `password`），它才会被视为隐式 `default` 账号。命名账号在 `homeserver` + `userId` 且缓存凭证可覆盖认证的情况下，仍可被发现。
**提升：**
- 当 OpenClaw 在修复或设置过程中将单账户配置提升为多账户配置时，如果现有命名账户存在，或 `defaultAccount` 已指向某个命名账户，它会保留该账户。只有 Matrix 认证 / 引导设置相关键会移动到提升后的账户中；共享的传递策略键会保留在顶层。
- 当 OpenClaw 在修复或设置期间将单账号配置提升为多账号配置时，如果已存在命名账号，或 `defaultAccount` 已经指向某个命名账号，它会保留现有命名账号。只有 Matrix 认证 / 引导初始化键会移动到提升后的账号中；共享的传递策略键仍保留在顶层。
有关共享的多账户模式，请参见 [配置参考](/zh-CN/gateway/config-channels#multi-account-all-channels)。
有关共享的多账号模式，请参见 [配置参考](/zh-CN/gateway/config-channels#multi-account-all-channels)。
## 私有 / LAN homeserver
## 私有 / 局域网 homeserver
默认情况下，出于 SSRF 防护，OpenClaw 会阻止私有 / 内部 Matrix homeserver，除非你
为每个账户显式选择启用。
默认情况下，出于 SSRF 防护，OpenClaw 会阻止连接私有 / 内部 Matrix homeserver，除非你为每个账号显式选择启用。
如果你的 homeserver 运行在 localhost、LAN/Tailscale IP 或内部主机名上，请为该 Matrix 账户启用
`network.dangerouslyAllowPrivateNetwork`：
如果你的 homeserver 运行在 localhost、局域网 / Tailscale IP 或内部主机名上，请为该 Matrix 账号启用 `network.dangerouslyAllowPrivateNetwork`：
```json5
{
@ -769,10 +787,10 @@ openclaw matrix account add \
--access-token syt_ops_xxx
```
此选择启用仅允许受信任的私有 / 内部目标。像
`http://matrix.example.org:8008` 这样的公共明文 homeserver 仍会被阻止。请尽可能优先使用 `https://`。
此显式启用仅允许受信任的私有 / 内部目标。像
`http://matrix.example.org:8008` 这样的公网明文 homeserver 仍会被阻止。请尽可能优先使用 `https://`。
## 通过代理转发 Matrix 流量
## 代理 Matrix 流量
如果你的 Matrix 部署需要显式的出站 HTTP(S) 代理，请设置 `channels.matrix.proxy`：
@ -788,52 +806,52 @@ openclaw matrix account add \
}
```
命名账户可通过 `channels.matrix.accounts.<id>.proxy` 覆盖顶层默认值。
OpenClaw 会对运行时 Matrix 流量和账户状态探测使用同一个代理设置。
命名账号可以使用 `channels.matrix.accounts.<id>.proxy` 覆盖顶层默认值。
OpenClaw 会将相同的代理设置用于运行时 Matrix 流量和账号 Status 探测。
## 目标解析
在 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 房间 ID 区分大小写。
在配置显式传递目标、cron 作业、绑定或允许列表时，请使用 Matrix 中房间 ID 的准确大小写。
OpenClaw 会为存储保留内部会话键的规范形式，因此这些小写键并不是 Matrix 传递 ID 的可靠来源。
在配置显式传递目标、cron 作业、绑定或允许列表时，请使用 Matrix 中房间 ID 的精确大小写。
OpenClaw 会将内部会话键规范化以便存储，因此这些小写键并不是可靠的 Matrix 传递 ID 来源。
实时目录查找使用已登录的 Matrix 账户：
实时目录查找使用已登录的 Matrix 账号：
- 用户查找会查询该 homeserver 上的 Matrix 用户目录。
- 房间查找会直接接受显式房间 ID 和别名，然后回退为搜索该账户已加入的房间名称。
- 已加入房间名称查找属于尽力而为。如果某个房间名无法解析为 ID 或别名，它会在运行时允许列表解析中被忽略。
- 房间查找会直接接受显式房间 ID 和别名，然后回退到搜索该账号已加入房间的名称。
- 已加入房间名称查找是尽力而为的。如果某个房间名称无法解析为 ID 或别名，在运行时允许列表解析中会被忽略。
## 配置参考
允许列表风格的字段（`groupAllowFrom`、`dm.allowFrom`、`groups.<room>.users`）接受完整的 Matrix 用户 ID（最安全）。精确目录匹配会在启动时以及监控运行期间允许列表发生变化时解析；无法解析的条目会在运行时被忽略。出于同样原因，房间允许列表优先使用房间 ID 或别名。
允许列表风格字段（`groupAllowFrom`、`dm.allowFrom`、`groups.<room>.users`）接受完整 Matrix 用户 ID（最安全）。精确的目录匹配会在启动时以及监视器运行期间允许列表发生更改时进行解析；无法解析的条目会在运行时被忽略。出于同样原因，房间允许列表更推荐使用房间 ID 或别名。
### 账户和连接
### 账号和连接
- `enabled`：启用或禁用该渠道。
- `name`：账户的可选显示标签。
- `defaultAccount`：配置多个 Matrix 账户时的首选账户 ID。
- `accounts`：按账户命名的覆盖项。顶层 `channels.matrix` 值会作为默认值继承。
- `name`：账号的可选显示标签。
- `defaultAccount`：配置了多个 Matrix 账号时的首选账号 ID。
- `accounts`：按账号命名的覆盖项。顶层 `channels.matrix` 值会作为默认值继承。
- `homeserver`：homeserver URL，例如 `https://matrix.example.org`。
- `network.dangerouslyAllowPrivateNetwork`：允许该账户连接到 `localhost`、LAN/Tailscale IP 或内部主机名。
- `proxy`：Matrix 流量的可选 HTTP(S) 代理 URL。支持按账户覆盖。
- `userId`：完整的 Matrix 用户 ID（`@bot:example.org`）。
- `accessToken`：基于令牌认证的访问令牌。支持跨 env/file/exec 提供商使用明文和 SecretRef 值（[Secrets Management](/zh-CN/gateway/secrets)）。
- `network.dangerouslyAllowPrivateNetwork`：允许该账号连接到 `localhost`、局域网 / Tailscale IP 或内部主机名。
- `proxy`：Matrix 流量的可选 HTTP(S) 代理 URL。支持按账号覆盖。
- `userId`：完整 Matrix 用户 ID（`@bot:example.org`）。
- `accessToken`：基于令牌认证的访问令牌。支持跨 env/file/exec 提供商的明文和 SecretRef 值（[Secrets Management](/zh-CN/gateway/secrets)）。
- `password`：基于密码登录的密码。支持明文和 SecretRef 值。
- `deviceId`：显式 Matrix 设备 ID。
- `deviceName`：密码登录时使用的设备显示名称。
- `avatarUrl`：用于资料同步和 `profile set` 更新的已存储自身头像 URL。
- `avatarUrl`：用于资料同步和 `profile set` 更新的已存储自头像 URL。
- `initialSyncLimit`：启动同步期间获取的最大事件数。
### 加密
- `encryption`：启用 E2EE。默认值：`false`。
- `startupVerification`：`"if-unverified"`（启用 E2EE 时的默认值）或 `"off"`。当此设备未验证时，会在启动时自动请求自我验证。
- `encryption`：启用端到端加密。默认值：`false`。
- `startupVerification`：`"if-unverified"`（启用端到端加密时的默认值）或 `"off"`。当该设备未验证时，在启动时自动请求自验证。
- `startupVerificationCooldownHours`：下次自动启动请求前的冷却时间。默认值：`24`。
### 访问和策略
@ -841,45 +859,45 @@ OpenClaw 会为存储保留内部会话键的规范形式，因此这些小写
- `groupPolicy`：`"open"`、`"allowlist"` 或 `"disabled"`。默认值：`"allowlist"`。
- `groupAllowFrom`：房间流量的用户 ID 允许列表。
- `dm.enabled`：为 `false` 时，忽略所有私信。默认值：`true`。
- `dm.policy`：`"pairing"`（默认）、`"allowlist"`、`"open"` 或 `"disabled"`。它在机器人加入并将房间分类为私信后才生效；不会影响邀请处理。
- `dm.policy`：`"pairing"`（默认）、`"allowlist"`、`"open"` 或 `"disabled"`。它在机器人加入并将房间归类为私信后生效；不会影响邀请处理。
- `dm.allowFrom`：私信流量的用户 ID 允许列表。
- `dm.sessionScope`：`"per-user"`（默认）或 `"per-room"`。
- `dm.threadReplies`：仅私信的回复线程覆盖项（`"off"`、`"inbound"`、`"always"`）。
- `allowBots`：接受来自其他已配置 Matrix 机器人账户的消息（`true` 或 `"mentions"`）。
- `allowlistOnly`：为 `true` 时，会将所有活动中的私信策略（`"disabled"` 除外）和 `"open"` 群组策略强制为 `"allowlist"`。不会更改 `"disabled"` 策略。
- `dm.threadReplies`：仅用于私信的回复线程覆盖项（`"off"`、`"inbound"`、`"always"`）。
- `allowBots`：接受来自其他已配置 Matrix 机器人账号的消息（`true` 或 `"mentions"`）。
- `allowlistOnly`：为 `true` 时，会将所有处于激活状态的私信策略（`"disabled"` 除外）和 `"open"` 群组策略强制改为 `"allowlist"`。不会更改 `"disabled"` 策略。
- `autoJoin`：`"always"`、`"allowlist"` 或 `"off"`。默认值：`"off"`。适用于所有 Matrix 邀请，包括类似私信的邀请。
- `autoJoinAllowlist`：当 `autoJoin` 为 `"allowlist"` 时允许的房间 / 别名。别名条目会针对 homeserver 解析，而不是依据被邀请房间声称的状态进行解析。
- `contextVisibility`：补充上下文可见性（默认 `"all"`，也可为 `"allowlist"`、`"allowlist_quote"`）。
- `autoJoinAllowlist`：当 `autoJoin` 为 `"allowlist"` 时允许的房间 / 别名。别名条目会针对 homeserver 进行解析，而不是根据受邀房间声明的状态进行解析。
- `contextVisibility`：补充上下文可见性（默认 `"all"`、`"allowlist"`、`"allowlist_quote"`）。
### 回复行为
- `replyToMode`：`"off"`、`"first"`、`"all"` 或 `"batched"`。
- `threadReplies`：`"off"`、`"inbound"` 或 `"always"`。
- `threadBindings`：按渠道覆盖线程绑定的会话路由和生命周期。
- `streaming`：`"off"`（默认）、`"partial"`、`"quiet"`。`true` ↔ `"partial"`，`false` ↔ `"off"`。
- `blockStreaming`：为 `true` 时，已完成的助手分块会保留为独立的进度消息。
- `threadBindings`：用于线程绑定会话路由和生命周期的按渠道覆盖项。
- `streaming`：`"off"`（默认）、`"partial"`、`"quiet"`，或对象形式 `{ mode, preview: { toolProgress } }`。`true` ↔ `"partial"`，`false` ↔ `"off"`。
- `blockStreaming`：为 `true` 时，已完成的助手块会作为独立的进度消息保留。
- `markdown`：出站文本的可选 Markdown 渲染配置。
- `responsePrefix`：添加到出站回复前的可选字符串。
- `textChunkLimit`：当 `chunkMode: "length"` 时，按字符数拆分的出站分块大小。默认值：`4000`。
- `chunkMode`：`"length"`（默认，按字符数拆分）或 `"newline"`（在换行边界拆分）。
- `responsePrefix`：附加到出站回复前的可选字符串。
- `textChunkLimit`：当 `chunkMode: "length"` 时，出站分块的字符数上限。默认值：`4000`。
- `chunkMode`：`"length"`（默认，按字符数拆分）或 `"newline"`（按行边界拆分）。
- `historyLimit`：当房间消息触发智能体时，作为 `InboundHistory` 包含的最近房间消息数量。回退到 `messages.groupChat.historyLimit`；有效默认值为 `0`（禁用）。
- `mediaMaxMb`：出站发送和入站处理的媒体大小上限（MB）。
- `mediaMaxMb`：用于出站发送和入站处理的媒体大小上限，单位 MB。
### 回应设置
- `ackReaction`：此渠道 / 账户的 ack 回应覆盖值。
- `ackReactionScope`：作用域覆盖值（默认 `"group-mentions"`，也可为 `"group-all"`、`"direct"`、`"all"`、`"none"`、`"off"`）。
- `reactionNotifications`：入站回应通知模式（默认 `"own"`，也可为 `"off"`）。
- `ackReaction`：此渠道 / 账号的确认回应覆盖项。
- `ackReactionScope`：作用域覆盖（默认 `"group-mentions"`、`"group-all"`、`"direct"`、`"all"`、`"none"`、`"off"`）。
- `reactionNotifications`：入站回应通知模式（默认 `"own"`、`"off"`）。
### 工具和按房间覆盖
- `actions`：按操作的工具门控（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。
- `groups`：按房间的策略映射。解析后，会话身份使用稳定的房间 ID。（`rooms` 是旧版别名。）
- `groups.<room>.account`：将某个继承的房间条目限制到特定账户。
- `groups.<room>.allowBots`：对渠道级设置的按房间覆盖（`true` 或 `"mentions"`）。
- `groups`：按房间的策略映射。解析后，会话身份使用稳定房间 ID。（`rooms` 是旧别名。）
- `groups.<room>.account`：将某条继承的房间条目限制到特定账号。
- `groups.<room>.allowBots`：房间级覆盖渠道级设置（`true` 或 `"mentions"`）。
- `groups.<room>.users`：按房间的发送者允许列表。
- `groups.<room>.tools`：按房间的工具允许 / 拒绝覆盖。
- `groups.<room>.autoReply`：按房间的提及门控覆盖。`true` 会禁用该房间的提及要求；`false` 会强制重新开启。
- `groups.<room>.autoReply`：按房间的提及门控覆盖。`true` 会禁用该房间的提及要求；`false` 会强制重新启用。
- `groups.<room>.skills`：按房间的 Skills 过滤器。
- `groups.<room>.systemPrompt`：按房间的系统提示片段。
@ -896,4 +914,4 @@ OpenClaw 会为存储保留内部会话键的规范形式，因此这些小写
- [配对](/zh-CN/channels/pairing) — 私信认证和配对流程
- [群组](/zh-CN/channels/groups) — 群聊行为和提及门控
- [渠道路由](/zh-CN/channels/channel-routing) — 消息的会话路由
- [安全性](/zh-CN/gateway/security) — 访问模型和加固
- [安全](/zh-CN/gateway/security) — 访问模型与加固

133
docs/zh-CN/concepts/qa-matrix.md
View File

@ -2,21 +2,21 @@
read_when:
- 在本地运行 `pnpm openclaw qa matrix`
- 添加或选择 Matrix QA 场景
- 排查 Matrix QA 失败、超时或清理卡住的问题
summary: Docker 支持的 Matrix 实时 QA 通道维护者参考：CLI、配置文件、环境变量、场景和输出工件。
- 排查 Matrix QA 失败、超时或卡住的清理流程
summary: Docker 支持的 Matrix 实时 QA 通道的维护者参考：CLI、配置文件、环境变量、场景和输出产物。
title: Matrix QA
x-i18n:
generated_at: "2026-04-27T17:44:05Z"
generated_at: "2026-04-27T20:27:53Z"
model: gpt-5.4
provider: openai
source_hash: 6b49528cafbdc1b3ca52b6dce9f5d98e806032c1d8fea49e1c49190982dd5767
source_hash: 55fcacd1348b681ef9e550d3f4cdf7c5ed3a2cb8d0df6d93b8ac025ec3280329
source_path: concepts/qa-matrix.md
workflow: 15
---
Matrix QA 通道会在 Docker 中针对一次性 Tuwunel homeserver 运行内置的 `@openclaw/matrix` 插件，并使用临时的 driver、SUT 和 observer 账号以及预置房间。它为 Matrix 提供基于真实传输的实时覆盖。
Matrix QA 通道会针对一次性 Docker 中的 Tuwunel homeserver 运行内置的 `@openclaw/matrix` 插件，并使用临时的驱动、SUT 和观察者账号以及预置房间。这是 Matrix 的实时传输覆盖。
这是仅供维护者使用的工具。打包后的 OpenClaw 发布版本会刻意省略 `qa-lab`，因此 `openclaw qa` 只能在源码检出中使用。源码检出会直接加载内置运行器——不需要安装插件。
这是仅供维护者使用的工具。打包后的 OpenClaw 发布版本会刻意省略 `qa-lab`，因此 `openclaw qa` 只能在源码检出环境中使用。源码检出会直接加载内置运行器——不需要安装插件。
有关更广泛的 QA 框架背景，请参阅 [QA overview](/zh-CN/concepts/qa-e2e-automation)。
@ -26,16 +26,16 @@ Matrix QA 通道会在 Docker 中针对一次性 Tuwunel homeserver 运行内置
pnpm openclaw qa matrix --profile fast --fail-fast
```
直接运行 `pnpm openclaw qa matrix` 会执行 `--profile all`，并且不会在首次失败时停止。将 `--profile fast --fail-fast` 用作发布门禁；在并行运行完整清单时，可使用 `--profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli` 对目录进行分片。
直接运行 `pnpm openclaw qa matrix` 会使用 `--profile all`，并且不会在首次失败时停止。将 `--profile fast --fail-fast` 用于发布门禁；当你要并行运行完整场景清单时，可使用 `--profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli` 对目录进行分片。
## 该通道会执行什么
## 此通道会执行什么
1. 在 Docker 中配置一次性的 Tuwunel homeserver（默认镜像为 `ghcr.io/matrix-construct/tuwunel:v1.5.1`，服务器名称为 `matrix-qa.test`，端口为 `28008`）。
1. 在 Docker 中创建一个一次性的 Tuwunel homeserver（默认镜像为 `ghcr.io/matrix-construct/tuwunel:v1.5.1`，服务器名称为 `matrix-qa.test`，端口为 `28008`）。
2. 注册三个临时用户——`driver`（发送入站流量）、`sut`（被测的 OpenClaw Matrix 账号）、`observer`（第三方流量捕获）。
3. 为所选场景预置所需房间（主房间、线程房间、媒体房间、重启房间、次要房间、allowlist 房间、E2EE 房间、验证私信等）。
4. 启动一个子 OpenClaw Gateway 网关，并将真实 Matrix 插件限定在 SUT 账号上；子进程中不会加载 `qa-channel`。
5. 按顺序运行场景，并通过 driver/observer Matrix 客户端观测事件。
6. 拆除 homeserver，写入报告和摘要工件，然后退出。
3. 为所选场景预置所需房间（主房间、线程房间、媒体房间、重启房间、次级房间、allowlist 房间、E2EE 房间、验证私信房间等）。
4. 启动一个子 OpenClaw Gateway 网关，并在其中加载限定到 SUT 账号的真实 Matrix 插件；子进程中不会加载 `qa-channel`。
5. 按顺序运行场景，并通过 driver/observer Matrix 客户端观察事件。
6. 清理 homeserver，写出报告和摘要产物，然后退出。
## CLI
@ -45,99 +45,100 @@ pnpm openclaw qa matrix [options]
### 常用标志
| 标志 | 默认值 | 说明 |
| --------------------- | --------------------------------------------- | -------------------------------------------------------------------- |
| `--profile <profile>` | `all` | 场景配置文件。参见 [Profiles](#profiles)。 |
| `--fail-fast` | 关闭 | 在第一个失败的检查或场景后停止。 |
| `--scenario <id>` | — | 仅运行此场景。可重复使用。参见 [Scenarios](#scenarios)。 |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/matrix-<timestamp>` | 报告、摘要、观测事件和输出日志的写入位置。相对路径会基于 `--repo-root` 解析。 |
| `--repo-root <path>` | `process.cwd()` | 当你从中立工作目录调用时使用的仓库根目录。 |
| `--sut-account <id>` | `sut` | QA Gateway 网关配置中的 Matrix 账号 id。 |
| 标志 | 默认值 | 说明 |
| --------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `--profile <profile>` | `all` | 场景配置文件。参见 [Profiles](#profiles)。 |
| `--fail-fast` | off | 在首次检查或场景失败后停止。 |
| `--scenario <id>` | — | 仅运行此场景。可重复使用。参见 [Scenarios](#scenarios)。 |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/matrix-<timestamp>` | 报告、摘要、观测事件和输出日志的写入位置。相对路径会相对于 `--repo-root` 解析。 |
| `--repo-root <path>` | `process.cwd()` | 当你从中立工作目录调用时使用的仓库根目录。 |
| `--sut-account <id>` | `sut` | QA Gateway 网关配置中的 Matrix 账号 id。 |
### 提供商标志
该通道使用真实的 Matrix 传输，但模型提供商可配置：
| 标志 | 默认值 | 说明 |
| ------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `--provider-mode <mode>` | `live-frontier` | 对于确定性的 mock 分发使用 `mock-openai`，或对实时 frontier 提供商使用 `live-frontier`。旧别名 `live-openai` 仍然可用。 |
| `--model <ref>` | provider 默认值 | 主 `provider/model` 引用。 |
| `--alt-model <ref>` | provider 默认值 | 在场景运行中切换时使用的备用 `provider/model` 引用。 |
| `--fast` | 关闭 | 在支持的情况下启用提供商快速模式。 |
| 标志 | 默认值 | 说明 |
| ------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `--provider-mode <mode>` | `live-frontier` | 使用 `mock-openai` 可获得确定性的 mock 调度，使用 `live-frontier` 可运行实时 frontier 提供商。旧别名 `live-openai` 仍然可用。 |
| `--model <ref>` | provider 默认值 | 主 `provider/model` 引用。 |
| `--alt-model <ref>` | provider 默认值 | 运行过程中场景切换时使用的备用 `provider/model` 引用。 |
| `--fast` | off | 在支持的情况下启用提供商快速模式。 |
Matrix QA 不接受 `--credential-source` 或 `--credential-role`。该通道会在本地配置一次性用户；没有可供租用的共享凭证池。
Matrix QA 不接受 `--credential-source` 或 `--credential-role`。该通道会在本地创建一次性用户；没有可供租用的共享凭证池。
## Profiles
所选配置文件决定运行哪些场景。
| 配置文件 | 用途 |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `all`（默认） | 完整目录。较慢，但最全面。 |
| `fast` | 用于发布门禁的子集，覆盖实时传输契约：canary、mention gating、allowlist 拦截、回复形态、重启恢复、线程跟进、线程隔离、reaction 观测。 |
| `transport` | 传输层级的线程、私信、房间、自动加入、mention/allowlist 场景。 |
| `media` | 图片、音频、视频、PDF、EPUB 附件覆盖。 |
| `e2ee-smoke` | 最小 E2EE 覆盖——基础加密回复、线程跟进、bootstrap 成功。 |
| `e2ee-deep` | 全面的 E2EE 状态丢失、备份、密钥和恢复场景。 |
| `e2ee-cli` | 通过 QA harness 驱动的 `openclaw matrix encryption setup` 和 `verify *` CLI 场景。 |
| 配置文件 | 适用场景 |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `all`（默认） | 完整目录。较慢，但覆盖最全面。 |
| `fast` | 用于发布门禁的子集，覆盖实时传输契约：canary、提及门控、allowlist 阻止、回复形态、重启恢复、线程后续跟进、线程隔离、reaction 观测。 |
| `transport` | 传输层级的线程、私信、房间、自动加入、提及/allowlist 场景。 |
| `media` | 图像、音频、视频、PDF、EPUB 附件覆盖。 |
| `e2ee-smoke` | 最小 E2EE 覆盖——基础加密回复、线程后续跟进、bootstrap 成功。 |
| `e2ee-deep` | 全面的 E2EE 状态丢失、备份、密钥和恢复场景。 |
| `e2ee-cli` | 通过 QA harness 驱动的 `openclaw matrix encryption setup` 和 `verify *` CLI 场景。 |
精确映射位于 `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts`。
## Scenarios
完整场景 id 列表是 `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15` 中的 `MatrixQaScenarioId` 联合类型。类别包括：
完整的场景 id 列表是 `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15` 中的 `MatrixQaScenarioId` 联合类型。类别包括：
- threading —— `matrix-thread-*`、`matrix-subagent-thread-spawn`
- 顶层 / 私信 / 房间 —— `matrix-top-level-reply-shape`、`matrix-room-*`、`matrix-dm-*`
- top-level / DM / room —— `matrix-top-level-reply-shape`、`matrix-room-*`、`matrix-dm-*`
- streaming and tool progress —— `matrix-room-partial-streaming-preview`、`matrix-room-quiet-streaming-preview`、`matrix-room-tool-progress-*`、`matrix-room-block-streaming`
- media —— `matrix-media-type-coverage`、`matrix-room-image-understanding-attachment`、`matrix-attachment-only-ignored`、`matrix-unsupported-media-safe`
- routing —— `matrix-room-autojoin-invite`、`matrix-secondary-room-*`
- reactions —— `matrix-reaction-*`
- restart 和 replay —— `matrix-restart-*`、`matrix-stale-sync-replay-dedupe`、`matrix-room-membership-loss`、`matrix-homeserver-restart-resume`、`matrix-initial-catchup-then-incremental`
- mention gating 和 allowlists —— `matrix-mention-*`、`matrix-allowlist-*`、`matrix-multi-actor-ordering`、`matrix-inbound-edit-*`、`matrix-mxid-prefixed-command-block`、`matrix-observer-allowlist-override`
- E2EE —— `matrix-e2ee-*`（基础回复、线程跟进、bootstrap、recovery key 生命周期、状态丢失变体、服务器备份行为、设备清理、SAS / QR / 私信验证、重启、工件脱敏）
- E2EE CLI —— `matrix-e2ee-cli-*`（encryption setup、幂等 setup、bootstrap 失败、recovery-key 生命周期、多账号、gateway-reply 往返、自验证）
- restart and replay —— `matrix-restart-*`、`matrix-stale-sync-replay-dedupe`、`matrix-room-membership-loss`、`matrix-homeserver-restart-resume`、`matrix-initial-catchup-then-incremental`
- mention gating and allowlists —— `matrix-mention-*`、`matrix-allowlist-*`、`matrix-multi-actor-ordering`、`matrix-inbound-edit-*`、`matrix-mxid-prefixed-command-block`、`matrix-observer-allowlist-override`
- E2EE —— `matrix-e2ee-*`（基础回复、线程后续跟进、bootstrap、恢复密钥生命周期、状态丢失变体、服务器备份行为、设备卫生、SAS / QR / 私信验证、重启、产物脱敏）
- E2EE CLI —— `matrix-e2ee-cli-*`（加密设置、幂等设置、bootstrap 失败、恢复密钥生命周期、多账号、Gateway 网关回复往返、自我验证）
传入 `--scenario <id>`（可重复）可运行手动挑选的一组场景；与 `--profile all` 组合使用可忽略配置文件限制。
传入 `--scenario <id>`（可重复）以运行一组手工挑选的场景；与 `--profile all` 组合使用可忽略配置文件门控。
## 环境变量
| 变量 | 默认值 | 作用 |
| --------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_QA_MATRIX_TIMEOUT_MS` | `1800000`（30 分钟） | 整个运行过程的硬性上限。 |
| `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` | `8000` | 用于负向“无回复”断言的静默窗口。会被限制为 `≤` 运行超时时间。 |
| `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` | `90000` | Docker 拆除的时间上限。失败时暴露的信息包括恢复用的 `docker compose ... down --remove-orphans` 命令。 |
| `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` | `ghcr.io/matrix-construct/tuwunel:v1.5.1` | 在针对其他 Tuwunel 版本进行验证时覆盖 homeserver 镜像。 |
| `OPENCLAW_QA_MATRIX_PROGRESS` | 开启 | `0` 会关闭 stderr 上的 `[matrix-qa] ...` 进度行。`1` 会强制开启。 |
| `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT` | 已脱敏 | `1` 会在 `matrix-qa-observed-events.json` 中保留消息正文和 `formatted_body`。默认会脱敏，以保证 CI 工件安全。 |
| `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT` | 关闭 | `1` 会跳过写入工件后的确定性 `process.exit`。默认会强制退出，因为 `matrix-js-sdk` 的原生加密句柄可能会在工件写入完成后仍让事件循环保持活动。 |
| `OPENCLAW_RUN_NODE_OUTPUT_LOG` | 未设置 | 当由外部启动器设置时（例如 `scripts/run-node.mjs`），Matrix QA 会复用该日志路径，而不是启动自己的 tee。 |
| 变量 | 默认值 | 作用 |
| --------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_QA_MATRIX_TIMEOUT_MS` | `1800000`（30 分钟） | 整个运行过程的硬性最长时间上限。 |
| `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` | `8000` | 用于否定性“无回复”断言的静默窗口。会被限制为 `≤` 运行超时时间。 |
| `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` | `90000` | Docker 清理的时间上限。失败信息中会包含恢复命令 `docker compose ... down --remove-orphans`。 |
| `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` | `ghcr.io/matrix-construct/tuwunel:v1.5.1` | 在针对不同 Tuwunel 版本进行验证时，用于覆盖 homeserver 镜像。 |
| `OPENCLAW_QA_MATRIX_PROGRESS` | on | `0` 会静默 stderr 上的 `[matrix-qa] ...` 进度行。`1` 会强制开启。 |
| `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT` | redacted | `1` 会在 `matrix-qa-observed-events.json` 中保留消息正文和 `formatted_body`。默认会脱敏，以保证 CI 产物安全。 |
| `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT` | off | `1` 会跳过写入产物后的确定性 `process.exit`。默认会强制退出，因为 `matrix-js-sdk` 的原生加密句柄可能在产物写完后仍让事件循环保持活跃。 |
| `OPENCLAW_RUN_NODE_OUTPUT_LOG` | unset | 当外层启动器设置了该值时（例如 `scripts/run-node.mjs`），Matrix QA 会复用该日志路径，而不是自行启动 tee。 |
## 输出工件
## 输出产物
写入到 `--output-dir`：
- `matrix-qa-report.md` —— Markdown 协议报告（哪些通过、失败、跳过，以及原因）。
- `matrix-qa-summary.json` —— 适合 CI 解析和仪表板使用的结构化摘要。
- `matrix-qa-observed-events.json` —— 来自 driver 和 observer 客户端观测到的 Matrix 事件。除非设置 `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1`，否则正文会被脱敏。
- `matrix-qa-output.log` —— 运行期间合并的 stdout/stderr。如果设置了 `OPENCLAW_RUN_NODE_OUTPUT_LOG`，则会改为复用外部启动器的日志。
- `matrix-qa-summary.json` —— 适用于 CI 解析和仪表盘的结构化摘要。
- `matrix-qa-observed-events.json` —— 来自 driver 和 observer 客户端观测到的 Matrix 事件。除非设置了 `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1`，否则正文会被脱敏。
- `matrix-qa-output.log` —— 运行过程中的合并 stdout/stderr。如果设置了 `OPENCLAW_RUN_NODE_OUTPUT_LOG`，则会改为复用外层启动器的日志。
默认输出目录为 `<repo>/.artifacts/qa-e2e/matrix-<timestamp>`，因此连续运行不会互相覆盖。
## 排查提示
- **运行接近结束时卡住：** `matrix-js-sdk` 的原生加密句柄可能会在 harness 结束后仍然存活。默认行为是在写入工件后强制执行一次干净的 `process.exit`；如果你取消设置了 `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1`，预计进程会继续挂起。
- **清理错误：** 查找打印出来的恢复命令（一个 `docker compose ... down --remove-orphans` 调用），并手动运行它以释放 homeserver 端口。
- **CI 中负向断言窗口不稳定：** 当 CI 较快时，调低 `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS`（默认 8 秒）；在较慢的共享 runner 上则调高。
- **需要为缺陷报告保留未脱敏正文：** 使用 `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1` 重新运行，并附上 `matrix-qa-observed-events.json`。请将生成的工件视为敏感内容。
- **不同的 Tuwunel 版本：** 将 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 指向待测版本。该通道仓库中只检入了固定的默认镜像。
- **运行在接近结束时卡住：** `matrix-js-sdk` 的原生加密句柄可能会比 harness 存活得更久。默认行为是在写入产物后强制执行一次干净的 `process.exit`；如果你设置了 `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1`，则应预期进程会继续挂住一段时间。
- **清理错误：** 查找打印出来的恢复命令（一个 `docker compose ... down --remove-orphans` 调用），然后手动运行它以释放 homeserver 端口。
- **CI 中否定断言窗口不稳定：** 当 CI 很快时，调低 `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS`（默认 8 秒）；在较慢的共享 runner 上则调高它。
- **需要为 bug 报告保留未脱敏正文：** 使用 `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1` 重新运行，并附上 `matrix-qa-observed-events.json`。请将生成的产物视为敏感内容。
- **不同的 Tuwunel 版本：** 将 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 指向正在测试的版本。该通道仓库中只固定提交了默认钉住的镜像版本。
## 实时传输契约
Matrix 是三个实时传输通道之一（Matrix、Telegram、Discord），它们共享同一个契约检查清单，定义见 [QA overview → Live transport coverage](/zh-CN/concepts/qa-e2e-automation#live-transport-coverage)。`qa-channel` 仍然是覆盖范围更广的合成测试套件，并且有意不属于该矩阵的一部分。
Matrix 是三个实时传输通道之一（Matrix、Telegram、Discord），它们共享同一份契约检查清单，该清单定义于 [QA overview → Live transport coverage](/zh-CN/concepts/qa-e2e-automation#live-transport-coverage)。`qa-channel` 仍然是覆盖范围更广的合成测试套件，并且被刻意排除在该矩阵之外。
## 相关内容
- [QA overview](/zh-CN/concepts/qa-e2e-automation) —— 整体 QA 栈和实时传输契约
- [QA channel](/zh-CN/channels/qa-channel) —— 用于基于仓库场景的合成渠道适配器
- [QA channel](/zh-CN/channels/qa-channel) —— 用于仓库驱动场景的合成渠道适配器
- [Testing](/zh-CN/help/testing) —— 运行测试和添加 QA 覆盖
- [Matrix](/zh-CN/channels/matrix) —— 被测的渠道插件
- [Matrix](/zh-CN/channels/matrix) —— 正在测试的渠道插件

141
docs/zh-CN/concepts/streaming.md
View File

@ -1,29 +1,29 @@
---
read_when:
- 解释渠道上的流式传输或分块处理如何工作
- 解释流式传输或分块处理在渠道中的工作方式
- 更改分块流式传输或渠道分块处理行为
- 调试重复或过早的分块回复，或渠道预览流式传输
- 调试重复或过早的分块回复或渠道预览流式传输
summary: 流式传输 + 分块处理行为（分块回复、渠道预览流式传输、模式映射）
title: 流式传输和分块处理
x-i18n:
generated_at: "2026-04-26T22:47:41Z"
generated_at: "2026-04-27T20:27:50Z"
model: gpt-5.4
provider: openai
source_hash: 7143421c98e8f4523e0f63653965ab0f63364d83f1073a6752385712551ec818
source_hash: 8210204d146f406320b977efe364ded0a19d233a943053fb1a90e6c59fb74a0f
source_path: concepts/streaming.md
workflow: 15
---
OpenClaw 有两个独立的流式传输层：
OpenClaw 有两个彼此独立的流式传输层：
- **分块流式传输（渠道）：** 在助手写入时发送已完成的**块**。这些是普通的渠道消息（不是 token 增量）。
- **预览流式传输（Telegram/Discord/Slack）：** 在生成过程中更新一条临时的**预览消息**。
- **分块流式传输（渠道）：** 在助手写作时，按已完成的**块**发出。这些是普通的渠道消息（不是 token 增量）。
- **预览流式传输（Telegram/Discord/Slack）：** 在生成过程中更新一个临时的**预览消息**。
目前**没有真正的 token 增量流式传输**到渠道消息。预览流式传输是基于消息的（发送 + 编辑/追加）。
当前**没有真正的 token 增量流式传输**到渠道消息。预览流式传输是基于消息的（发送 + 编辑/追加）。
## 分块流式传输（渠道消息）
分块流式传输会在助手输出可用时，以较粗粒度的块发送内容。
分块流式传输会在助手输出可用时，以较粗粒度的块发送。
```
Model output
@ -37,89 +37,86 @@ Model output
图例：
- `text_delta/events`：模型流事件（对于非流式传输模型，可能较少）。
- `chunker`：`EmbeddedBlockChunker`，应用最小/最大边界 + 断点偏好。
- `channel send`：实际发送出去的消息（分块回复）。
- `text_delta/events`：模型流事件（对于非流式模型，可能较为稀疏）。
- `chunker`：应用最小/最大边界和断点偏好的 `EmbeddedBlockChunker`。
- `channel send`：实际发出的消息（分块回复）。
**控制项：**
- `agents.defaults.blockStreamingDefault`：`"on"`/`"off"`（默认关闭）。
- 渠道覆盖：`*.blockStreaming`（以及按账户区分的变体），用于按渠道强制设为 `"on"`/`"off"`。
- 渠道覆盖：`*.blockStreaming`（以及每账户变体），用于按渠道强制设为 `"on"`/`"off"`。
- `agents.defaults.blockStreamingBreak`：`"text_end"` 或 `"message_end"`。
- `agents.defaults.blockStreamingChunk`：`{ minChars, maxChars, breakPreference? }`。
- `agents.defaults.blockStreamingCoalesce`：`{ minChars?, maxChars?, idleMs? }`（在发送前合并流式传输的块）。
- `agents.defaults.blockStreamingCoalesce`：`{ minChars?, maxChars?, idleMs? }`（在发送前合并流式块）。
- 渠道硬上限：`*.textChunkLimit`（例如 `channels.whatsapp.textChunkLimit`）。
- 渠道分块模式：`*.chunkMode`（默认 `length`，`newline` 会先按空行〈段落边界〉切分，再按长度分块）。
- Discord 软上限：`channels.discord.maxLinesPerMessage`（默认 17），用于拆分过高的回复以避免 UI 裁切。
- 渠道分块模式：`*.chunkMode`（默认 `length`，`newline` 会先按空行即段落边界拆分，再按长度分块）。
- Discord 软上限：`channels.discord.maxLinesPerMessage`（默认 17），用于拆分过高的回复，以避免 UI 裁剪。
**边界语义：**
- `text_end`：只要 chunker 产生块就立即流式发送；每次 `text_end` 时刷新。
- `message_end`：等待助手消息完成后，再刷新缓冲的输出。
- `text_end`：只要 chunker 发出块就立即流式发送；在每个 `text_end` 时刷新。
- `message_end`：等待助手消息完成后，再刷新缓冲输出。
如果缓冲文本超过 `maxChars`，`message_end` 仍然会使用 chunker，因此它可能在结束时发出多个块。
即使是 `message_end`，如果缓冲文本超过 `maxChars`，仍会使用 chunker，因此它可能在结尾发出多个块。
### 分块流式传输中的媒体发送
### 分块流式传输中的媒体投递
`MEDIA:` 指令是普通的发送元数据。当分块流式传输提前发送一个媒体块时，OpenClaw 会为该轮对话记住这次发送。如果最终的助手负载重复了相同的媒体 URL，最终发送会去掉重复的媒体，而不是再次发送附件。
`MEDIA:` 指令是普通的投递元数据。当分块流式传输提前发送一个媒体块时，OpenClaw 会为该轮次记住这次投递。如果最终助手载荷重复了相同的媒体 URL，最终投递会去掉重复媒体，而不是再次发送附件。
完全重复的最终负载会被抑制。如果最终负载在已流式发送过的媒体周围新增了不同文本，OpenClaw 仍会发送这些新文本，同时保持媒体只发送一次。这可以防止在 Telegram 等渠道上出现重复的语音笔记或文件；例如当智能体在流式传输期间输出 `MEDIA:`，而提供商也在完成回复中包含它时。
完全重复的最终载荷会被抑制。如果最终载荷在已经流式发送过的媒体前后新增了不同的文本，OpenClaw 仍会发送这些新文本，同时保持媒体只投递一次。这可以防止在 Telegram 等渠道上出现重复的语音消息或文件：例如，当智能体在流式传输期间发出 `MEDIA:`，而提供商也在完整回复中包含它时，就会发生这种情况。
## 分块算法（低/高边界）
分块处理由 `EmbeddedBlockChunker` 实现：
- **低边界：** 在缓冲区达到 `minChars` 之前不发送（除非被强制发送）。
- **高边界：** 尽量在 `maxChars` 之前切分；如果被强制切分，则在 `maxChars` 处切分。
- **断点偏好：** `paragraph` → `newline` → `sentence` → `whitespace` → 硬切分。
- **代码围栏：** 绝不在围栏内部切分；当必须在 `maxChars` 处强制切分时，会关闭并重新打开围栏，以保持 Markdown 有效。
- **低边界：** 在缓冲区达到 `minChars` 之前不发出（除非强制）。
- **高边界：** 优先在 `maxChars` 之前拆分；如果必须强制拆分，则在 `maxChars` 处拆分。
- **断点偏好：** `paragraph` → `newline` → `sentence` → `whitespace` → 硬断开。
- **代码围栏：** 绝不在围栏内部拆分；如果必须在 `maxChars` 处强制拆分，会先关闭再重新打开围栏，以保持 Markdown 有效。
`maxChars` 会被限制为渠道的 `textChunkLimit`，因此不能超过每个渠道的上限。
`maxChars` 会被限制在渠道的 `textChunkLimit` 以内，因此你不能超过各渠道的上限。
## 合并（合并流式块）
启用分块流式传输时，OpenClaw 可以在发送前**合并连续的分块**。这样可以减少“单行刷屏”，同时仍然提供渐进式输出。
启用分块流式传输时，OpenClaw 可以在发送前**合并连续的分块片段**。这样可以减少“单行刷屏”，同时仍然提供渐进式输出。
- 合并会等待**空闲间隔**（`idleMs`）后再刷新。
- 缓冲区受 `maxChars` 限制，超出时会刷新。
- `minChars` 会阻止过小的片段被发送，直到积累足够文本（最终刷新总会发送剩余文本）。
- 连接符取决于 `blockStreamingChunk.breakPreference`
（`paragraph` → `\n\n`，`newline` → `\n`，`sentence` → 空格）。
- 可通过 `*.blockStreamingCoalesce` 提供渠道覆盖（包括按账户配置）。
- 对于 Signal/Slack/Discord，默认的合并 `minChars` 会提升到 1500，除非另有覆盖。
- 缓冲区受 `maxChars` 限制，超过时会立即刷新。
- `minChars` 会阻止过小的片段被发送，直到累积足够文本（最终刷新总会发送剩余文本）。
- 连接符由 `blockStreamingChunk.breakPreference` 决定（`paragraph` → `\n\n`，`newline` → `\n`，`sentence` → 空格）。
- 可通过 `*.blockStreamingCoalesce` 提供渠道级覆盖（包括每账户配置）。
- 对于 Signal/Slack/Discord，默认的 coalesce `minChars` 会提升到 1500，除非另有覆盖。
## 块之间更像人类的节奏
## 块之间更像人的节奏
启用分块流式传输时，你可以在分块回复之间加入**随机暂停**（首个块之后）。这会让多气泡回复看起来更自然。
启用分块流式传输时，你可以在各个分块回复之间加入**随机暂停**（首个块之后）。这会让多气泡回复看起来更自然。
- 配置：`agents.defaults.humanDelay`（可通过 `agents.list[].humanDelay` 按智能体覆盖）。
- 模式：`off`（默认）、`natural`（800–2500 毫秒）、`custom`（`minMs`/`maxMs`）。
- 配置：`agents.defaults.humanDelay`（也可通过 `agents.list[].humanDelay` 按智能体覆盖）。
- 模式：`off`（默认）、`natural`（800–2500ms）、`custom`（`minMs`/`maxMs`）。
- 仅适用于**分块回复**，不适用于最终回复或工具摘要。
## “流式分块”还是“最后一次性发出全部”
## “流式输出分块”还是“一次性输出全部”
这对应到：
这对应于：
- **流式分块：** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（边生成边发送）。非 Telegram 渠道还需要 `*.blockStreaming: true`。
- **最后一次性流式发出全部：** `blockStreamingBreak: "message_end"`（只在最后刷新一次；如果内容很长，可能仍分成多个块）。
- **流式输出分块：** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（边生成边发出）。非 Telegram 渠道还需要设置 `*.blockStreaming: true`。
- **在结尾一次性流式输出全部：** `blockStreamingBreak: "message_end"`（刷新一次；如果内容很长，仍可能分成多个块）。
- **不使用分块流式传输：** `blockStreamingDefault: "off"`（只发送最终回复）。
**渠道说明：** 只有在显式设置
`*.blockStreaming` 为 `true` 时，分块流式传输才会开启。渠道可以在没有分块回复的情况下，仍然流式显示实时预览
（`channels.<channel>.streaming`）。
**渠道说明：** 除非显式将 `*.blockStreaming` 设为 `true`，否则分块流式传输**默认关闭**。渠道可以启用实时预览流式传输（`channels.<channel>.streaming`），而不发送分块回复。
配置位置提醒：`blockStreaming*` 默认值位于 `agents.defaults` 下，而不是根配置。
## 预览流式传输模式
规范键名：`channels.<channel>.streaming`
规范键：`channels.<channel>.streaming`
模式：
- `off`：禁用预览流式传输。
- `partial`：单个预览，用最新文本替换。
- `block`：预览以分块/追加的方式更新。
- `progress`：生成期间显示进度/状态预览，完成时发送最终答案。
- `block`：以分块/追加的方式更新预览。
- `progress`：在生成过程中显示进度/状态预览，完成时发送最终答案。
### 渠道映射
@ -130,23 +127,23 @@ Model output
| Slack | ✅ | ✅ | ✅ | ✅ |
| Mattermost | ✅ | ✅ | ✅ | ✅ |
仅 Slack：
仅限 Slack：
- `channels.slack.streaming.nativeTransport` 在 `channels.slack.streaming.mode="partial"` 时切换 Slack 原生流式 API 调用（默认：`true`）。
- 当 `channels.slack.streaming.mode="partial"` 时，`channels.slack.streaming.nativeTransport` 控制是否使用 Slack 原生流式 API 调用（默认：`true`）。
- Slack 原生流式传输和 Slack 助手线程状态都需要一个回复线程目标；顶层私信不会显示这种线程式预览。
旧键迁移：
- Telegram：会通过 doctor/配置兼容路径检测并迁移旧版 `streamMode` 和标量/布尔型 `streaming` 值到 `streaming.mode`。
- Discord：`streamMode` + 布尔型 `streaming` 会自动迁移到 `streaming` 枚举。
- Slack：`streamMode` 会自动迁移到 `streaming.mode`；布尔型 `streaming` 会自动迁移到 `streaming.mode` 加 `streaming.nativeTransport`；旧版 `nativeStreaming` 会自动迁移到 `streaming.nativeTransport`。
- Telegram：旧版 `streamMode` 以及标量/布尔 `streaming` 值，会由 doctor/config 兼容路径检测并迁移到 `streaming.mode`。
- Discord：`streamMode` + 布尔 `streaming` 会自动迁移到 `streaming` 枚举。
- Slack：`streamMode` 会自动迁移到 `streaming.mode`；布尔 `streaming` 会自动迁移到 `streaming.mode` 加 `streaming.nativeTransport`；旧版 `nativeStreaming` 会自动迁移到 `streaming.nativeTransport`。
### 运行时行为
Telegram：
- 在私信和群组/话题中使用 `sendMessage` + `editMessageText` 更新预览。
- 当预览已显示约一分钟时，会发送一条新的最终消息，而不是原地编辑，然后清理预览，以便 Telegram 的时间戳能反映回复完成时间。
- 在私信和群组/话题中使用 `sendMessage` + `editMessageText` 进行预览更新。
- 如果预览已显示大约一分钟，则发送一条新的最终消息，而不是原地编辑，然后清理预览，以便 Telegram 的时间戳反映回复完成时间。
- 当 Telegram 分块流式传输被显式启用时，会跳过预览流式传输（以避免双重流式传输）。
- `/reasoning stream` 可以将推理内容写入预览。
@ -155,38 +152,38 @@ Discord：
- 使用发送 + 编辑预览消息。
- `block` 模式使用草稿分块（`draftChunk`）。
- 当 Discord 分块流式传输被显式启用时，会跳过预览流式传输。
- 最终媒体、错误和显式回复负载会取消待处理的预览，而不会刷新新的草稿，然后使用正常发送。
- 最终媒体、错误和显式回复载荷会取消待处理预览，而不会刷新新的草稿，然后改用正常投递。
Slack：
- `partial` 可在可用时使用 Slack 原生流式传输（`chat.startStream`/`append`/`stop`）。
- `partial` 在可用时可使用 Slack 原生流式传输（`chat.startStream`/`append`/`stop`）。
- `block` 使用追加式草稿预览。
- `progress` 使用状态预览文本，然后发送最终答案。
- 原生和草稿预览流式传输会抑制该轮对话的分块回复，因此一条 Slack 回复只会通过一种发送路径流式传输。
- 最终媒体/错误负载和进度模式的最终结果不会创建临时草稿消息；只有能够编辑预览的文本/块最终结果才会刷新待处理的草稿文本。
- 原生和草稿预览流式传输会抑制该轮次的分块回复，因此一条 Slack 回复只会通过一种投递路径进行流式传输。
- 最终媒体/错误载荷和 `progress` 的最终结果不会创建一次性的草稿消息；只有可以编辑预览的文本/块最终结果，才会刷新待处理的草稿文本。
Mattermost：
- 将思考、工具活动和部分回复文本流式写入单个草稿预览帖子，并在最终答案可以安全发送时原地完成。
- 如果预览帖子已被删除或在完成时不可用，则回退为发送一条新的最终帖子。
- 最终媒体/错误负载会先取消待处理的预览更新，再进行正常发送，而不是刷新一条临时预览帖子。
- 将思考、工具活动和部分回复文本流式写入单个草稿预览帖子；当最终答案可以安全发送时，就地完成。
- 如果预览帖子已被删除或在完成时不可用，则回退为发送一个新的最终帖子。
- 最终媒体/错误载荷会在正常投递前取消待处理的预览更新，而不是刷新临时预览帖子。
Matrix：
- 当最终文本可以复用预览事件时，草稿预览会原地完成。
- 仅媒体、错误以及回复目标不匹配的最终结果会在正常发送前取消待处理的预览更新；如果已有可见的陈旧预览，则会将其隐藏。
- 仅媒体、错误以及回复目标不匹配的最终结果，会在正常投递前取消待处理的预览更新；如果已经显示了过期预览，则会将其撤回。
### 工具进度预览更新
预览流式传输还可以包含**工具进度**更新——例如“正在搜索网页”“正在读取文件”或“正在调用工具”之类的简短状态行——这些内容会在工具运行期间显示在同一条预览消息中，先于最终回复出现。这样可以让多步骤工具回合在视觉上保持活跃，而不是在首次思考预览和最终答案之间沉默。
预览流式传输还可以包含**工具进度**更新——例如“正在搜索网页”“正在读取文件”或“正在调用工具”之类的简短状态行——这些内容会在工具运行时显示在同一条预览消息中，先于最终回复出现。这样可以让多步骤工具轮次在视觉上保持活跃，而不是在首次思考预览与最终答案之间显得沉默。
支持的界面：
- **Discord**、**Slack** 和 **Telegram** 在预览流式传输处于活动状态时，默认会把工具进度流式写入实时预览编辑中。
- Telegram 自 `v2026.4.22` 起已启用工具进度预览更新；保持启用可维持该已发布行为。
- **Mattermost** 已经将工具活动合并进其单一草稿预览帖子中（见上文）。
- 工具进度编辑遵循当前的预览流式传输模式；当预览流式传输为 `off`，或消息已由分块流式传输接管时，会跳过这些编辑。
- 若要保留预览流式传输但隐藏工具进度行，请将该渠道的 `streaming.preview.toolProgress` 设为 `false`。若要完全禁用预览编辑，请将 `streaming.mode` 设为 `off`。
- 当预览流式传输处于活动状态时，**Discord**、**Slack**、**Telegram** 和 **Matrix** 默认会将工具进度流式写入实时预览编辑中。
- Telegram 自 `v2026.4.22` 起已发布并启用了工具进度预览更新；保持启用可保留这一已发布行为。
- **Mattermost** 已经会将工具活动整合进其单一草稿预览帖子中（见上文）。
- 工具进度编辑遵循当前启用的预览流式传输模式；当预览流式传输为 `off`，或消息已切换为分块流式传输时，会跳过这些编辑。
- 如果你想保留预览流式传输，但隐藏工具进度行，请将该渠道的 `streaming.preview.toolProgress` 设为 `false`。如果要完全禁用预览编辑，请将 `streaming.mode` 设为 `off`。
示例：
@ -207,6 +204,6 @@ Matrix：
## 相关内容
- [消息](/zh-CN/concepts/messages) —— 消息生命周期与发送
- [重试](/zh-CN/concepts/retry) —— 发送失败时的重试行为
- [渠道](/zh-CN/channels) —— 各渠道的流式传输支持
- [Messages](/zh-CN/concepts/messages) — 消息生命周期与投递
- [Retry](/zh-CN/concepts/retry) — 投递失败时的重试行为
- [Channels](/zh-CN/channels) — 各渠道的流式传输支持