chore(i18n): refresh zh-CN translations

2026-05-03 21:08:11 +00:00 · 2026-05-03 21:08:11 +00:00 · 8bd5a2a30b
commit 8bd5a2a30b
parent f793b50b76
5 changed files with 968 additions and 696 deletions
--- a/docs/zh-CN/channels/discord.md
+++ b/docs/zh-CN/channels/discord.md
--- a/docs/zh-CN/channels/telegram.md
+++ b/docs/zh-CN/channels/telegram.md
@ -1,42 +1,42 @@
 ---
 read_when:
-    - 处理 Telegram 功能或网络钩子
+    - 处理 Telegram 功能或 webhook
 summary: Telegram 机器人支持状态、能力和配置
 title: Telegram
 x-i18n:
-    generated_at: "2026-05-03T19:29:14Z"
+    generated_at: "2026-05-03T21:05:28Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 06252b1540d5794aa5d8fe1066bf9d121e682a0df969a265d890445e97d5d647
+    source_hash: 528ace9dae29eda22f98cc1436ec16146eb9d83edc73aa6db1ab8283f4f873c0
    source_path: channels/telegram.md
    workflow: 16
 ---

-Production-ready for bot DMs and groups via grammY. Long polling is the default mode; webhook mode is optional.
+可用于生产环境中的 bot 私信和群组，基于 grammY。长轮询是默认模式；webhook 模式是可选项。

 <CardGroup cols={3}>
-  <Card title="Pairing" icon="link" href="/zh-CN/channels/pairing">
-    Default DM policy for Telegram is pairing.
+  <Card title="配对" icon="link" href="/zh-CN/channels/pairing">
+    Telegram 的默认私信策略是配对。
  </Card>
-  <Card title="Channel troubleshooting" icon="wrench" href="/zh-CN/channels/troubleshooting">
-    Cross-channel diagnostics and repair playbooks.
+  <Card title="渠道故障排除" icon="wrench" href="/zh-CN/channels/troubleshooting">
+    跨渠道诊断和修复手册。
  </Card>
-  <Card title="Gateway configuration" icon="settings" href="/zh-CN/gateway/configuration">
-    Full channel config patterns and examples.
+  <Card title="Gateway 网关配置" icon="settings" href="/zh-CN/gateway/configuration">
+    完整的渠道配置模式和示例。
  </Card>
 </CardGroup>

-## Quick setup
+## 快速设置

 <Steps>
-  <Step title="Create the bot token in BotFather">
-    Open Telegram and chat with **@BotFather** (confirm the handle is exactly `@BotFather`).
+  <Step title="在 BotFather 中创建 bot token">
+    打开 Telegram 并与 **@BotFather** 聊天（确认句柄完全是 `@BotFather`）。

-    Run `/newbot`, follow prompts, and save the token.
+    运行 `/newbot`，按提示操作，并保存 token。

  </Step>

-  <Step title="Configure token and DM policy">
+  <Step title="配置 token 和私信策略">

 ```json5
 {
@ -51,12 +51,12 @@ Production-ready for bot DMs and groups via grammY. Long polling is the default
 }
 ```

-    Env fallback: `TELEGRAM_BOT_TOKEN=...` (default account only).
-    Telegram does **not** use `openclaw channels login telegram`; configure token in config/env, then start gateway.
+    环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账号）。
+    Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置 token，然后启动 Gateway 网关。

  </Step>

-  <Step title="Start gateway and approve first DM">
+  <Step title="启动 Gateway 网关并批准第一条私信">

 ```bash
 openclaw gateway
@ -64,119 +64,119 @@ openclaw pairing list telegram
 openclaw pairing approve telegram <CODE>
 ```

-    Pairing codes expire after 1 hour.
+    配对码将在 1 小时后过期。

  </Step>

-  <Step title="Add the bot to a group">
-    Add the bot to your group, then set `channels.telegram.groups` and `groupPolicy` to match your access model.
+  <Step title="将 bot 添加到群组">
+    将 bot 添加到你的群组，然后设置 `channels.telegram.groups` 和 `groupPolicy`，以匹配你的访问模型。
  </Step>
 </Steps>

 <Note>
-Token resolution order is account-aware. In practice, config values win over env fallback, and `TELEGRAM_BOT_TOKEN` only applies to the default account.
+token 解析顺序感知账号。实践中，配置值优先于环境变量回退，且 `TELEGRAM_BOT_TOKEN` 只适用于默认账号。
 </Note>

-## Telegram side settings
+## Telegram 侧设置

 <AccordionGroup>
-  <Accordion title="Privacy mode and group visibility">
-    Telegram bots default to **Privacy Mode**, which limits what group messages they receive.
+  <Accordion title="隐私模式和群组可见性">
+    Telegram bot 默认启用 **Privacy Mode**，这会限制它们能接收哪些群组消息。

-    If the bot must see all group messages, either:
+    如果 bot 必须看到所有群组消息，请执行以下任一操作：

-    - disable privacy mode via `/setprivacy`, or
-    - make the bot a group admin.
+    - 通过 `/setprivacy` 禁用隐私模式，或
+    - 将 bot 设为群组管理员。

-    When toggling privacy mode, remove + re-add the bot in each group so Telegram applies the change.
+    切换隐私模式时，请在每个群组中移除并重新添加 bot，以便 Telegram 应用更改。

  </Accordion>

-  <Accordion title="Group permissions">
-    Admin status is controlled in Telegram group settings.
+  <Accordion title="群组权限">
+    管理员状态在 Telegram 群组设置中控制。

-    Admin bots receive all group messages, which is useful for always-on group behavior.
+    管理员 bot 会接收所有群组消息，这对始终在线的群组行为很有用。

  </Accordion>

-  <Accordion title="Helpful BotFather toggles">
+  <Accordion title="有用的 BotFather 开关">

-    - `/setjoingroups` to allow/deny group adds
-    - `/setprivacy` for group visibility behavior
+    - `/setjoingroups` 用于允许/拒绝添加到群组
+    - `/setprivacy` 用于群组可见性行为

  </Accordion>
 </AccordionGroup>

-## Access control and activation
+## 访问控制和激活

 <Tabs>
-  <Tab title="DM policy">
-    `channels.telegram.dmPolicy` controls direct message access:
+  <Tab title="私信策略">
+    `channels.telegram.dmPolicy` 控制直接消息访问：

-    - `pairing` (default)
-    - `allowlist` (requires at least one sender ID in `allowFrom`)
-    - `open` (requires `allowFrom` to include `"*"`)
+    - `pairing`（默认）
+    - `allowlist`（要求 `allowFrom` 中至少有一个发送者 ID）
+    - `open`（要求 `allowFrom` 包含 `"*"`）
    - `disabled`

-    `dmPolicy: "open"` with `allowFrom: ["*"]` lets any Telegram account that finds or guesses the bot username command the bot. Use it only for intentionally public bots with tightly restricted tools; one-owner bots should use `allowlist` with numeric user IDs.
+    `dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 会让任何找到或猜到 bot 用户名的 Telegram 账号都能命令该 bot。仅将其用于有意公开且工具受到严格限制的 bot；单所有者 bot 应使用 `allowlist` 并搭配数字用户 ID。

-    `channels.telegram.allowFrom` accepts numeric Telegram user IDs. `telegram:` / `tg:` prefixes are accepted and normalized.
-    In multi-account configs, a restrictive top-level `channels.telegram.allowFrom` is treated as a safety boundary: account-level `allowFrom: ["*"]` entries do not make that account public unless the effective account allowlist still contains an explicit wildcard after merging.
-    `dmPolicy: "allowlist"` with empty `allowFrom` blocks all DMs and is rejected by config validation.
-    Setup asks for numeric user IDs only.
-    If you upgraded and your config contains `@username` allowlist entries, run `openclaw doctor --fix` to resolve them (best-effort; requires a Telegram bot token).
-    If you previously relied on pairing-store allowlist files, `openclaw doctor --fix` can recover entries into `channels.telegram.allowFrom` in allowlist flows (for example when `dmPolicy: "allowlist"` has no explicit IDs yet).
+    `channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。`telegram:` / `tg:` 前缀会被接受并规范化。
+    在多账号配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：账号级 `allowFrom: ["*"]` 条目不会让该账号公开，除非合并后的有效账号允许列表仍包含显式通配符。
+    `dmPolicy: "allowlist"` 搭配空的 `allowFrom` 会阻止所有私信，并会被配置验证拒绝。
+    设置只会要求数字用户 ID。
+    如果你已升级且配置中包含 `@username` 允许列表条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram bot token）。
+    如果你之前依赖配对存储的允许列表文件，`openclaw doctor --fix` 可以在 allowlist 流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 尚无显式 ID 时）。

-    For one-owner bots, prefer `dmPolicy: "allowlist"` with explicit numeric `allowFrom` IDs to keep access policy durable in config (instead of depending on previous pairing approvals).
+    对于单所有者 bot，建议使用 `dmPolicy: "allowlist"` 并搭配显式数字 `allowFrom` ID，以便在配置中保持持久的访问策略（而不是依赖之前的配对批准）。

-    Common confusion: DM pairing approval does not mean "this sender is authorized everywhere".
-    Pairing grants DM access. If no command owner exists yet, the first approved pairing also sets `commands.ownerAllowFrom` so owner-only commands and exec approvals have an explicit operator account.
-    Group sender authorization still comes from explicit config allowlists.
-    If you want "I am authorized once and both DMs and group commands work", put your numeric Telegram user ID in `channels.telegram.allowFrom`; for owner-only commands, make sure `commands.ownerAllowFrom` contains `telegram:<your user id>`.
+    常见误解：批准私信配对并不意味着“此发送者在所有地方都已获授权”。
+    配对授予私信访问权限。如果尚无命令所有者，第一次获批的配对还会设置 `commands.ownerAllowFrom`，使仅所有者命令和 exec 批准拥有显式操作员账号。
+    群组发送者授权仍来自显式配置允许列表。
+    如果你希望“我授权一次后，私信和群组命令都能使用”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:<your user id>`。

-    ### Finding your Telegram user ID
+    ### 查找你的 Telegram 用户 ID

-    Safer (no third-party bot):
+    更安全（无第三方 bot）：

-    1. DM your bot.
-    2. Run `openclaw logs --follow`.
-    3. Read `from.id`.
+    1. 私信你的 bot。
+    2. 运行 `openclaw logs --follow`。
+    3. 读取 `from.id`。

-    Official Bot API method:
+    官方 Bot API 方法：

 ```bash
 curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 ```

-    Third-party method (less private): `@userinfobot` or `@getidsbot`.
+    第三方方法（隐私性较低）：`@userinfobot` 或 `@getidsbot`。

  </Tab>

-  <Tab title="Group policy and allowlists">
-    Two controls apply together:
+  <Tab title="群组策略和允许列表">
+    两项控制共同生效：

-    1. **Which groups are allowed** (`channels.telegram.groups`)
-       - no `groups` config:
-         - with `groupPolicy: "open"`: any group can pass group-ID checks
-         - with `groupPolicy: "allowlist"` (default): groups are blocked until you add `groups` entries (or `"*"`)
-       - `groups` configured: acts as allowlist (explicit IDs or `"*"`)
+    1. **允许哪些群组**（`channels.telegram.groups`）
+       - 没有 `groups` 配置：
+         - 使用 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查
+         - 使用 `groupPolicy: "allowlist"`（默认）：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`）
+       - 已配置 `groups`：作为允许列表（显式 ID 或 `"*"`）

-    2. **Which senders are allowed in groups** (`channels.telegram.groupPolicy`)
+    2. **群组中允许哪些发送者**（`channels.telegram.groupPolicy`）
       - `open`
-       - `allowlist` (default)
+       - `allowlist`（默认）
       - `disabled`

-    `groupAllowFrom` is used for group sender filtering. If not set, Telegram falls back to `allowFrom`.
-    `groupAllowFrom` entries should be numeric Telegram user IDs (`telegram:` / `tg:` prefixes are normalized).
-    Do not put Telegram group or supergroup chat IDs in `groupAllowFrom`. Negative chat IDs belong under `channels.telegram.groups`.
-    Non-numeric entries are ignored for sender authorization.
-    Security boundary (`2026.2.25+`): group sender auth does **not** inherit DM pairing-store approvals.
-    Pairing stays DM-only. For groups, set `groupAllowFrom` or per-group/per-topic `allowFrom`.
-    If `groupAllowFrom` is unset, Telegram falls back to config `allowFrom`, not the pairing store.
-    Practical pattern for one-owner bots: set your user ID in `channels.telegram.allowFrom`, leave `groupAllowFrom` unset, and allow the target groups under `channels.telegram.groups`.
-    Runtime note: if `channels.telegram` is completely missing, runtime defaults to fail-closed `groupPolicy="allowlist"` unless `channels.defaults.groupPolicy` is explicitly set.
+    `groupAllowFrom` 用于群组发送者过滤。如果未设置，Telegram 会回退到 `allowFrom`。
+    `groupAllowFrom` 条目应为数字 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被规范化）。
+    不要将 Telegram 群组或超级群组 chat ID 放入 `groupAllowFrom`。负数 chat ID 应放在 `channels.telegram.groups` 下。
+    非数字条目会在发送者授权中被忽略。
+    安全边界（`2026.2.25+`）：群组发送者认证**不会**继承私信配对存储批准。
+    配对仅限私信。对于群组，请设置 `groupAllowFrom` 或每群组/每 topic 的 `allowFrom`。
+    如果未设置 `groupAllowFrom`，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。
+    单所有者 bot 的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。
+    运行时说明：如果 `channels.telegram` 完全缺失，运行时会默认故障关闭为 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。

-    Example: allow any member in one specific group:
+    示例：允许一个特定群组中的任何成员：

 ```json5
 {
@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 }
 ```

-    Example: allow only specific users inside one specific group:
+    示例：只允许一个特定群组内的特定用户：

 ```json5
 {
@ -211,34 +211,34 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 ```

    <Warning>
-      Common mistake: `groupAllowFrom` is not a Telegram group allowlist.
+      常见错误：`groupAllowFrom` 不是 Telegram 群组允许列表。

-      - Put negative Telegram group or supergroup chat IDs like `-1001234567890` under `channels.telegram.groups`.
-      - Put Telegram user IDs like `8734062810` under `groupAllowFrom` when you want to limit which people inside an allowed group can trigger the bot.
-      - Use `groupAllowFrom: ["*"]` only when you want any member of an allowed group to be able to talk to the bot.
+      - 将 `-1001234567890` 这样的负数 Telegram 群组或超级群组 chat ID 放在 `channels.telegram.groups` 下。
+      - 当你想限制已允许群组内哪些人可以触发 bot 时，将 `8734062810` 这样的 Telegram 用户 ID 放在 `groupAllowFrom` 下。
+      - 仅当你希望已允许群组的任何成员都能与 bot 对话时，才使用 `groupAllowFrom: ["*"]`。

    </Warning>

  </Tab>

-  <Tab title="Mention behavior">
-    Group replies require mention by default.
+  <Tab title="提及行为">
+    群组回复默认要求提及。

-    Mention can come from:
+    提及可以来自：

-    - native `@botusername` mention, or
-    - mention patterns in:
+    - 原生 `@botusername` 提及，或
+    - 以下位置中的提及模式：
      - `agents.list[].groupChat.mentionPatterns`
      - `messages.groupChat.mentionPatterns`

-    Session-level command toggles:
+    会话级命令开关：

    - `/activation always`
    - `/activation mention`

-    These update session state only. Use config for persistence.
+    这些只会更新会话状态。使用配置来持久化。

-    Persistent config example:
+    持久配置示例：

 ```json5
 {
@ -252,44 +252,44 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 }
 ```

-    Getting the group chat ID:
+    获取群组 chat ID：

-    - forward a group message to `@userinfobot` / `@getidsbot`
-    - or read `chat.id` from `openclaw logs --follow`
-    - or inspect Bot API `getUpdates`
+    - 将群组消息转发给 `@userinfobot` / `@getidsbot`
+    - 或从 `openclaw logs --follow` 读取 `chat.id`
+    - 或检查 Bot API `getUpdates`

  </Tab>
 </Tabs>

-## Runtime behavior
+## 运行时行为

- Telegram is owned by the gateway process.
- Routing is deterministic: Telegram inbound replies back to Telegram (the model does not pick channels).
- Inbound messages normalize into the shared channel envelope with reply metadata and media placeholders.
- Group sessions are isolated by group ID. Forum topics append `:topic:<threadId>` to keep topics isolated.
- DM messages can carry `message_thread_id`; OpenClaw preserves the thread ID for replies but keeps DMs on the flat session by default. Configure `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct.<chatId>.threadReplies: "inbound"`, `requireTopic: true`, or a matching topic config when you intentionally want DM topic session isolation.
- Long polling uses grammY runner with per-chat/per-thread sequencing. Overall runner sink concurrency uses `agents.defaults.maxConcurrent`.
- Long polling is guarded inside each gateway process so only one active poller can use a bot token at a time. If you still see `getUpdates` 409 conflicts, another OpenClaw gateway, script, or external poller is likely using the same token.
- Long-polling watchdog restarts trigger after 120 seconds without completed `getUpdates` liveness by default. Increase `channels.telegram.pollingStallThresholdMs` only if your deployment still sees false polling-stall restarts during long-running work. The value is in milliseconds and is allowed from `30000` to `600000`; per-account overrides are supported.
- Telegram Bot API has no read-receipt support (`sendReadReceipts` does not apply).
+- Telegram 由 Gateway 网关进程拥有。
+- 路由是确定性的：Telegram 入站会回复到 Telegram（模型不会选择渠道）。
+- 入站消息会规范化为共享渠道信封，并带有回复元数据和媒体占位符。
+- 群组会话按群组 ID 隔离。论坛 topic 会追加 `:topic:<threadId>` 以保持 topic 隔离。
+- 私信消息可以携带 `message_thread_id`；OpenClaw 会保留线程 ID 用于回复，但默认将私信保留在扁平会话中。当你有意希望进行私信 topic 会话隔离时，请配置 `channels.telegram.dm.threadReplies: "inbound"`、`channels.telegram.direct.<chatId>.threadReplies: "inbound"`、`requireTopic: true`，或匹配的 topic 配置。
+- 长轮询使用 grammY runner，并按每个 chat/每个 thread 排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。
+- 长轮询在每个 Gateway 网关进程内部受保护，因此同一时间只有一个活跃 poller 可以使用一个 bot token。如果你仍看到 `getUpdates` 409 冲突，很可能是另一个 OpenClaw Gateway 网关、脚本或外部 poller 正在使用同一个 token。
+- 默认情况下，长轮询 watchdog 会在 120 秒内没有完成的 `getUpdates` 活性后触发重启。仅当你的部署在长时间运行任务期间仍出现误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账号覆盖。
+- Telegram Bot API 不支持已读回执（`sendReadReceipts` 不适用）。

-## Feature reference
+## 功能参考

 <AccordionGroup>
-  <Accordion title="Live stream preview (message edits)">
-    OpenClaw can stream partial replies in real time:
+  <Accordion title="实时流预览（消息编辑）">
+    OpenClaw 可以实时流式传输部分回复：

-    - direct chats: preview message + `editMessageText`
-    - groups/topics: preview message + `editMessageText`
+    - 直接聊天：预览消息 + `editMessageText`
+    - 群组/topic：预览消息 + `editMessageText`

-    Requirement:
+    要求：

-    - `channels.telegram.streaming` is `off | partial | block | progress` (default: `partial`)
-    - `progress` maps to `partial` on Telegram (compat with cross-channel naming)
-    - `streaming.preview.toolProgress` controls whether tool/progress updates reuse the same edited preview message (default: `true` when preview streaming is active)
-    - legacy `channels.telegram.streamMode` and boolean `streaming` values are detected; run `openclaw doctor --fix` to migrate them to `channels.telegram.streaming.mode`
+    - `channels.telegram.streaming` 为 `off | partial | block | progress`（默认：`partial`）
+    - `progress` 会保留一个可编辑的状态草稿，并用工具进度更新它，直到最终交付
+    - `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑的预览消息（当预览流式传输处于活动状态时，默认：`true`）
+    - 旧版 `channels.telegram.streamMode` 和布尔 `streaming` 值会被检测到；运行 `openclaw doctor --fix` 将它们迁移到 `channels.telegram.streaming.mode`

-    Tool-progress preview updates are the short "Working..." lines shown while tools run, for example command execution, file reads, planning updates, or patch summaries. Telegram keeps these enabled by default to match released OpenClaw behavior from `v2026.4.22` and later. To keep the edited preview for answer text but hide tool-progress lines, set:
+    工具进度预览更新是在工具运行时显示的短状态行，例如命令执行、文件读取、规划更新或补丁摘要。Telegram 默认保持这些更新启用，以匹配 `v2026.4.22` 及之后版本发布的 OpenClaw 行为。若要保留答案文本的已编辑预览，但隐藏工具进度行，请设置：

    ```json
    {
@ -306,30 +306,30 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    }
    ```

-    仅在你希望仅最终交付时使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，通用工具/进度闲聊会被抑制，而不是作为独立的 “Working...” 消息发送。审批提示、媒体载荷和错误仍会通过正常的最终交付路径路由。仅当你希望保留答案预览编辑，同时隐藏工具进度状态行时，使用 `streaming.preview.toolProgress: false`。
+    Use `streaming.mode: "off"` 仅在你想要仅最终内容投递时使用：Telegram 预览编辑会被禁用，通用工具/进度闲聊会被抑制，而不是作为独立 Status 消息发送。审批提示、媒体载荷和错误仍会通过正常的最终投递路径发送。当你只想保留答案预览编辑，同时隐藏工具进度 Status 行时，请使用 `streaming.preview.toolProgress: false`。

    <Note>
-      Telegram 选中引用回复是例外。当 `replyToMode` 为 `"first"`、`"all"` 或 `"batched"`，且入站消息包含选中的引用文本时，OpenClaw 会通过 Telegram 原生引用回复路径发送最终答案，而不是编辑答案预览，因此 `streaming.preview.toolProgress` 无法为该轮显示简短的 “Working...” 行。没有选中引用文本的当前消息回复仍会保留预览流式传输。当工具进度可见性比原生引用回复更重要时，设置 `replyToMode: "off"`；或者设置 `streaming.preview.toolProgress: false` 以确认这一权衡。
+      Telegram 选中文本引用回复是例外。当 `replyToMode` 为 `"first"`、`"all"` 或 `"batched"`，且入站消息包含选中的引用文本时，OpenClaw 会通过 Telegram 的原生引用回复路径发送最终答案，而不是编辑答案预览，因此 `streaming.preview.toolProgress` 无法为该轮显示短 Status 行。没有选中引用文本的当前消息回复仍会保留预览流式传输。当工具进度可见性比原生引用回复更重要时，请设置 `replyToMode: "off"`；或者设置 `streaming.preview.toolProgress: false` 以确认这一取舍。
    </Note>

    对于纯文本回复：

-    - 简短的私信/群组/topic 预览：OpenClaw 会保留同一条预览消息，并在原位置执行最终编辑，除非预览出现后发送过可见的非预览消息
-    - 预览后跟随可见的非预览输出：OpenClaw 会将完成后的回复作为新的最终消息发送，并清理较旧的预览，因此最终答案会出现在中间输出之后
-    - 超过约一分钟的预览：OpenClaw 会将完成后的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳反映的是完成时间，而不是预览创建时间
+    - 短私信/群组/topic 预览：OpenClaw 会保留同一条预览消息，并在原处执行最终编辑，除非预览出现后发送过可见的非预览消息
+    - 预览后跟随可见的非预览输出：OpenClaw 会将完成后的回复作为新的最终消息发送，并清理旧预览，因此最终答案会出现在中间输出之后
+    - 超过约一分钟的预览：OpenClaw 会将完成后的回复作为新的最终消息发送，然后清理预览，因此 Telegram 可见时间戳会反映完成时间，而不是预览创建时间

-    对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常的最终交付，然后清理预览消息。
+    对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常的最终投递，然后清理预览消息。

-    预览流式传输独立于分块流式传输。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。
+    预览流式传输与分块流式传输相互独立。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。

    仅限 Telegram 的推理流：

-    - `/reasoning stream` 会在生成过程中将推理发送到实时预览
+    - `/reasoning stream` 会在生成时把推理发送到实时预览
    - 最终答案发送时不包含推理文本

  </Accordion>

-  <Accordion title="格式化与 HTML 回退">
+  <Accordion title="格式化和 HTML 回退">
    出站文本使用 Telegram `parse_mode: "HTML"`。

    - 类 Markdown 文本会渲染为 Telegram 安全的 HTML。
@ -364,24 +364,24 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"

    规则：

-    - 名称会被规范化（去掉开头的 `/`，转为小写）
+    - 名称会被规范化（移除开头的 `/`，转为小写）
    - 有效模式：`a-z`、`0-9`、`_`，长度 `1..32`
    - 自定义命令不能覆盖原生命令
    - 冲突/重复项会被跳过并记录日志

-    注意事项：
+    注意：

    - 自定义命令只是菜单项；它们不会自动实现行为
-    - plugin/skill 命令即使未显示在 Telegram 菜单中，输入时仍可生效
+    - 插件/skill 命令即使未显示在 Telegram 菜单中，输入时仍可工作

-    如果原生命令被禁用，内置命令会被移除。自定义/plugin 命令在配置后仍可能注册。
+    如果禁用原生命令，内置项会被移除。自定义/插件命令在配置后仍可注册。

    常见设置失败：

-    - `setMyCommands failed` 搭配 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 菜单在裁剪后仍然溢出；减少 plugin/skill/自定义命令，或禁用 `channels.telegram.commands.native`。
-    - 当直接的 Bot API curl 命令可用，但 `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 失败并显示 `404: Not Found` 时，可能表示 `channels.telegram.apiRoot` 被设置成了完整的 `/bot<TOKEN>` 端点。`apiRoot` 必须只是 Bot API 根地址，并且 `openclaw doctor --fix` 会移除意外附加的尾部 `/bot<TOKEN>`。
-    - `getMe returned 401` 表示 Telegram 拒绝了配置的机器人 token。使用当前 BotFather token 更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。
-    - `setMyCommands failed` 搭配网络/fetch 错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻断。
+    - `setMyCommands failed` 伴随 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 菜单在裁剪后仍然溢出；请减少插件/skill/自定义命令，或禁用 `channels.telegram.commands.native`。
+    - 当直接 Bot API curl 命令可用，但 `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 失败并显示 `404: Not Found` 时，可能表示 `channels.telegram.apiRoot` 被设置成了完整的 `/bot<TOKEN>` 端点。`apiRoot` 必须只是 Bot API 根地址，并且 `openclaw doctor --fix` 会移除意外尾随的 `/bot<TOKEN>`。
+    - `getMe returned 401` 表示 Telegram 拒绝了配置的 bot 令牌。请使用当前 BotFather 令牌更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。
+    - `setMyCommands failed` 伴随网络/fetch 错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。

    ### 设备配对命令（`device-pair` 插件）

@ -395,9 +395,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
       - 只有一个待处理请求时使用 `/pair approve`
       - `/pair approve latest` 用于最近的请求

-    设置代码携带一个短期有效的 bootstrap token。内置 bootstrap 交接会将主节点 token 保持在 `scopes: []`；任何被交接的 operator token 都限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。Bootstrap 作用域检查带有角色前缀，因此该 operator 允许列表只满足 operator 请求；非 operator 角色仍需要位于自身角色前缀下的作用域。
+    设置代码携带一个短期有效的 bootstrap 令牌。内置 bootstrap 交接会让主节点令牌保持在 `scopes: []`；任何交接出去的 operator 令牌都会被限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write` 范围内。Bootstrap 作用域检查带有角色前缀，因此该 operator 允许列表只满足 operator 请求；非 operator 角色仍需要其自身角色前缀下的作用域。

-    如果设备使用变更后的认证详情重试（例如角色/作用域/公钥），先前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。
+    如果设备使用变更后的认证详情（例如角色/作用域/公钥）重试，之前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。

    更多详情：[配对](/zh-CN/channels/pairing#pair-via-telegram-recommended-for-ios)。

@ -446,7 +446,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"

    旧版 `capabilities: ["inlineButtons"]` 会映射到 `inlineButtons: "all"`。

-    消息操作示例：
+    消息动作示例：

 ```json5
 {
@ -469,8 +469,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"

  </Accordion>

-  <Accordion title="面向智能体和自动化的 Telegram 消息操作">
-    Telegram 工具操作包括：
+  <Accordion title="面向智能体和自动化的 Telegram 消息动作">
+    Telegram 工具动作包括：

    - `sendMessage`（`to`、`content`、可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`）
    - `react`（`chatId`、`messageId`、`emoji`）
@ -478,7 +478,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    - `editMessage`（`chatId`、`messageId`、`content`）
    - `createForumTopic`（`chatId`、`name`、可选 `iconColor`、`iconCustomEmojiId`）

-    渠道消息操作提供易用别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。
+    渠道消息动作会暴露符合人体工程学的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。

    门控控制项：

@ -488,14 +488,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    - `channels.telegram.actions.sticker`（默认：禁用）

    注意：`edit` 和 `topic-create` 目前默认启用，且没有单独的 `channels.telegram.actions.*` 开关。
-    运行时发送使用当前有效的配置/secret 快照（启动/重载），因此操作路径不会在每次发送时执行临时 SecretRef 重新解析。
+    运行时发送使用活动配置/密钥快照（启动/重载），因此动作路径不会在每次发送时执行临时 SecretRef 重新解析。

-    移除回应的语义：[/tools/reactions](/zh-CN/tools/reactions)
+    Reaction 移除语义：[/tools/reactions](/zh-CN/tools/reactions)

  </Accordion>

  <Accordion title="回复线程标签">
-    Telegram 支持在生成的输出中使用显式回复线程标签：
+    Telegram 支持在生成输出中使用显式回复线程标签：

    - `[[reply_to_current]]` 回复触发消息
    - `[[reply_to:<id>]]` 回复特定的 Telegram 消息 ID
@ -506,29 +506,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    - `first`
    - `all`

-    启用回复线程且原始 Telegram 文本或说明可用时，OpenClaw 会自动包含一段原生 Telegram 引用摘录。Telegram 将原生引用文本限制为 1024 个 UTF-16 代码单元，因此较长消息会从开头开始引用；如果 Telegram 拒绝该引用，则回退为普通回复。
+    当启用回复线程，且原始 Telegram 文本或标题可用时，OpenClaw 会自动包含一段原生 Telegram 引用摘录。Telegram 将原生引用文本限制为 1024 个 UTF-16 代码单元，因此更长的消息会从开头引用；如果 Telegram 拒绝该引用，则会回退为普通回复。

    注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵循。

  </Accordion>

-  <Accordion title="论坛 topic 与线程行为">
+  <Accordion title="论坛 topic 和线程行为">
    论坛超级群组：

    - topic 会话键追加 `:topic:<threadId>`
-    - 回复和正在输入状态会指向 topic 线程
+    - 回复和输入状态会面向 topic 线程
    - topic 配置路径：
      `channels.telegram.groups.<chatId>.topics.<threadId>`

-    常规 topic（`threadId=1`）特殊情况：
+    General topic（`threadId=1`）特殊情况：

-    - 消息发送会省略 `message_thread_id`（Telegram 会拒绝 `sendMessage(...thread_id=1)`）
-    - 正在输入操作仍会包含 `message_thread_id`
+    - 消息发送会省略 `message_thread_id`（Telegram 拒绝 `sendMessage(...thread_id=1)`）
+    - 输入状态动作仍会包含 `message_thread_id`

    Topic 继承：topic 条目会继承群组设置，除非被覆盖（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。
-    `agentId` 仅限 topic，不会从群组默认值继承。
+    `agentId` 仅属于 topic，不会从群组默认值继承。

-    **按 topic 的智能体路由**：每个 topic 都可以通过在 topic 配置中设置 `agentId` 路由到不同智能体。这让每个 topic 都拥有自己的隔离工作区、记忆和会话。示例：
+    **按 topic 的智能体路由**：每个 topic 都可以通过在 topic 配置中设置 `agentId` 路由到不同的智能体。这让每个 topic 拥有自己隔离的工作区、记忆和会话。示例：

    ```json5
    {
@ -548,26 +548,28 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    }
    ```

-    随后每个 topic 都会有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3`
+    然后每个 topic 都有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3`

-    **持久 ACP topic 绑定**：论坛 topic 可以通过顶层 typed ACP 绑定固定 ACP harness 会话（`bindings[]`，其中 `type: "acp"`、`match.channel: "telegram"`、`peer.kind: "group"`，以及类似 `-1001234567890:topic:42` 的 topic 限定 id）。目前作用域限于群组/超级群组中的论坛 topic。参见 [ACP Agents](/zh-CN/tools/acp-agents)。
+    **持久 ACP topic 绑定**：论坛 topic 可以通过顶层类型化 ACP 绑定（`bindings[]`，其中 `type: "acp"`、`match.channel: "telegram"`、`peer.kind: "group"`，以及类似 `-1001234567890:topic:42` 的 topic 限定 ID）固定 ACP harness 会话。目前作用域限定为群组/超级群组中的论坛 topic。参见 [ACP Agents](/zh-CN/tools/acp-agents)。

-    **从聊天派生线程绑定 ACP**：`/acp spawn <agent> --thread here|auto` 会将当前 topic 绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在 topic 内固定派生确认消息。需要保持启用 `channels.telegram.threadBindings.spawnSessions`（默认：`true`）。
+    **从聊天生成线程绑定的 ACP**：`/acp spawn <agent> --thread here|auto` 会将当前 topic 绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在 topic 内固定生成确认。要求 `channels.telegram.threadBindings.spawnSessions` 保持启用（默认：`true`）。

-    模板上下文公开 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天默认保留私信路由，并在扁平会话上保留回复元数据；只有在配置了 `threadReplies: "inbound"`、`threadReplies: "always"`、`requireTopic: true` 或匹配的 topic 配置时，才会使用线程感知的会话键。使用顶层 `channels.telegram.dm.threadReplies` 作为账户默认值，或使用 `direct.<chatId>.threadReplies` 配置单个私信。
+    模板上下文会暴露 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天默认会在扁平会话上保留私信路由和回复元数据；只有配置了 `threadReplies: "inbound"`、`threadReplies: "always"`、`requireTopic: true`，或匹配的 topic 配置时，才会使用线程感知会话键。使用顶层 `channels.telegram.dm.threadReplies` 作为账户默认值，或使用 `direct.<chatId>.threadReplies` 配置某个私信。

  </Accordion>

  <Accordion title="音频、视频和贴纸">
    ### 音频消息

-    Telegram 会区分语音消息和音频文件。
+    Telegram 区分语音消息和音频文件。

    - 默认：音频文件行为
-    - 在智能体回复中使用标签 `[[audio_as_voice]]` 以强制作为语音消息发送
-    - 入站语音消息转写会在智能体上下文中被框定为机器生成的、不受信任文本；提及检测仍使用原始转写，因此需要提及门控的语音消息会继续工作。
+    - 在智能体回复中使用标签 `[[audio_as_voice]]` 以强制按语音消息发送
+    - 入站语音消息转录会在智能体上下文中被框定为机器生成的、
+      不受信任文本；提及检测仍使用原始
+      转录，因此受提及门控的语音消息会继续工作。

-    消息操作示例：
+    消息动作示例：

 ```json5
 {
@ -581,9 +583,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"

    ### 视频消息

-    Telegram 区分视频文件和圆形视频消息。
+    Telegram 会区分视频文件和视频便笺。

-    消息 action 示例：
+    消息操作示例：

 ```json5
 {
@ -595,14 +597,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 }
 ```

-    圆形视频消息不支持说明文字；提供的消息文本会单独发送。
+    视频便笺不支持字幕；提供的消息文本会单独发送。

    ### 贴纸

    入站贴纸处理：

    - 静态 WEBP：下载并处理（占位符 `<media:sticker>`）
-    - 动态 TGS：跳过
+    - 动画 TGS：跳过
    - 视频 WEBM：跳过

    贴纸上下文字段：
@ -617,9 +619,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"

    - `~/.openclaw/telegram/sticker-cache.json`

-    贴纸会被描述一次（如果可能）并缓存，以减少重复的视觉调用。
+    贴纸会被描述一次（如果可行）并缓存，以减少重复的视觉调用。

-    启用贴纸 action：
+    启用贴纸操作：

 ```json5
 {
@ -633,7 +635,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 }
 ```

-    发送贴纸 action：
+    发送贴纸操作：

 ```json5
 {
@ -644,7 +646,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 }
 ```

-    搜索已缓存的贴纸：
+    搜索缓存的贴纸：

 ```json5
 {
@ -658,7 +660,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
  </Accordion>

  <Accordion title="回应通知">
-    Telegram 回应会作为 `message_reaction` 更新到达（与消息负载分离）。
+    Telegram 回应会以 `message_reaction` 更新到达（独立于消息载荷）。

    启用后，OpenClaw 会将如下系统事件加入队列：

@ -672,12 +674,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    注意：

    - `own` 表示仅用户对机器人发送消息的回应（通过已发送消息缓存尽力判断）。
-    - 回应事件仍会遵守 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。
-    - Telegram 不会在回应更新中提供话题 ID。
+    - 回应事件仍遵守 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。
+    - Telegram 不会在回应更新中提供线程 ID。
      - 非论坛群组路由到群聊会话
-      - 论坛群组路由到群组通用话题会话（`:topic:1`），而不是确切的原始话题
+      - 论坛群组路由到群组通用主题会话（`:topic:1`），而不是确切的原始主题

-    用于轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。
+    轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。

  </Accordion>

@ -689,19 +691,19 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    - `channels.telegram.accounts.<accountId>.ackReaction`
    - `channels.telegram.ackReaction`
    - `messages.ackReaction`
-    - agent 身份 emoji 回退（`agents.list[].identity.emoji`，否则为 "👀"）
+    - 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 “👀”）

    注意：

-    - Telegram 需要 unicode emoji（例如 "👀"）。
-    - 使用 `""` 可为某个 channel 或账户禁用该回应。
+    - Telegram 需要 Unicode emoji（例如 “👀”）。
+    - 使用 `""` 可禁用某个渠道或账号的回应。

  </Accordion>

  <Accordion title="来自 Telegram 事件和命令的配置写入">
-    channel 配置写入默认启用（`configWrites !== false`）。
+    渠道配置写入默认启用（`configWrites !== false`）。

-    由 Telegram 触发的写入包括：
+    Telegram 触发的写入包括：

    - 群组迁移事件（`migrate_to_chat_id`），用于更新 `channels.telegram.groups`
    - `/config set` 和 `/config unset`（需要启用命令）
@ -721,29 +723,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
  </Accordion>

  <Accordion title="长轮询与 webhook">
-    默认使用长轮询。对于 webhook 模式，请设置 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`；可选项包括 `webhookPath`、`webhookHost`、`webhookPort`（默认值为 `/telegram-webhook`、`127.0.0.1`、`8787`）。
+    默认是长轮询。对于 webhook 模式，设置 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`；可选 `webhookPath`、`webhookHost`、`webhookPort`（默认值为 `/telegram-webhook`、`127.0.0.1`、`8787`）。

-    本地监听器绑定到 `127.0.0.1:8787`。对于公开入口，要么在本地端口前放置反向代理，要么有意设置 `webhookHost: "0.0.0.0"`。
+    本地监听器绑定到 `127.0.0.1:8787`。对于公共入口，可以在本地端口前放置反向代理，或有意设置 `webhookHost: "0.0.0.0"`。

-    Webhook 模式会先验证请求防护、Telegram secret token 和 JSON 正文，然后再向 Telegram 返回 `200`。
-    随后 OpenClaw 会通过与长轮询相同的按聊天/按话题机器人通道异步处理更新，因此缓慢的 agent 回合不会阻塞 Telegram 的投递 ACK。
+    Webhook 模式会先验证请求防护、Telegram 密钥令牌和 JSON 正文，然后再向 Telegram 返回 `200`。
+    随后 OpenClaw 会通过与长轮询相同的按聊天/按主题机器人通道异步处理该更新，因此缓慢的智能体轮次不会占用 Telegram 的投递 ACK。

  </Accordion>

  <Accordion title="限制、重试和 CLI 目标">
    - `channels.telegram.textChunkLimit` 默认值为 4000。
-    - `channels.telegram.chunkMode="newline"` 在按长度拆分前优先使用段落边界（空行）。
+    - `channels.telegram.chunkMode="newline"` 会在按长度拆分前优先使用段落边界（空行）。
    - `channels.telegram.mediaMaxMb`（默认 100）限制入站和出站 Telegram 媒体大小。
-    - `channels.telegram.mediaGroupFlushMs`（默认 500）控制在 OpenClaw 将 Telegram 相册/媒体组作为一条入站消息分发前缓冲多久。如果相册部分到达较晚，请增大该值；如果要降低相册回复延迟，请减小该值。
-    - `channels.telegram.timeoutSeconds` 会覆盖 Telegram API 客户端超时（如果未设置，则使用 grammY 默认值）。机器人客户端会将配置值限制在 60 秒出站文本/正在输入请求防护以下，以便 grammY 不会在 OpenClaw 的传输防护和回退运行前中止可见回复投递。长轮询仍使用 45 秒 `getUpdates` 请求防护，因此空闲轮询不会被无限期放弃。
+    - `channels.telegram.mediaGroupFlushMs`（默认 500）控制 Telegram 相册/媒体组在 OpenClaw 将其作为一条入站消息派发前的缓冲时长。如果相册部分到达较晚，可以增大该值；如果想降低相册回复延迟，可以减小该值。
+    - `channels.telegram.timeoutSeconds` 覆盖 Telegram API 客户端超时（如果未设置，则使用 grammY 默认值）。机器人客户端会将低于 60 秒出站文本/正在输入请求防护的配置值进行限制，这样 grammY 就不会在 OpenClaw 的传输防护和回退运行前中止可见回复投递。长轮询仍使用 45 秒的 `getUpdates` 请求防护，因此空闲轮询不会被无限期放弃。
    - `channels.telegram.pollingStallThresholdMs` 默认值为 `120000`；仅在误报轮询停滞重启时，在 `30000` 到 `600000` 之间调整。
    - 群组上下文历史使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（默认 50）；`0` 表示禁用。
-    - 回复/引用/转发的补充上下文目前按接收内容传递。
-    - Telegram 允许列表主要控制谁可以触发 agent，而不是完整的补充上下文删减边界。
+    - 回复/引用/转发补充上下文目前按接收到的内容传递。
+    - Telegram 允许列表主要控制谁可以触发智能体，而不是完整的补充上下文脱敏边界。
    - 私信历史控制：
      - `channels.telegram.dmHistoryLimit`
      - `channels.telegram.dms["<user_id>"].historyLimit`
-    - `channels.telegram.retry` 配置适用于 Telegram 发送辅助方法（CLI/工具/action），用于可恢复的出站 API 错误。入站最终回复投递也会对 Telegram 预连接失败使用有界安全发送重试，但不会重试可能导致可见消息重复的不明确发送后网络信封。
+    - `channels.telegram.retry` 配置适用于 Telegram 发送辅助函数（CLI/工具/操作）中可恢复的出站 API 错误。入站最终回复投递也会对 Telegram 预连接失败使用有界安全发送重试，但不会重试可能重复可见消息的模糊发送后网络信封。

    CLI 发送目标可以是数字聊天 ID 或用户名：

@ -752,7 +754,7 @@ openclaw message send --channel telegram --target 123456789 --message "hi"
 openclaw message send --channel telegram --target @name --message "hi"
 ```

-    Telegram 投票使用 `openclaw message poll`，并支持论坛话题：
+    Telegram 投票使用 `openclaw message poll`，并支持论坛主题：

 ```bash
 openclaw message poll --channel telegram --target 123456789 \
@ -762,57 +764,57 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
  --poll-duration-seconds 300 --poll-public
 ```

-    仅 Telegram 支持的投票标志：
+    仅 Telegram 投票标志：

    - `--poll-duration-seconds`（5-600）
    - `--poll-anonymous`
    - `--poll-public`
-    - 用于论坛话题的 `--thread-id`（或使用 `:topic:` 目标）
+    - `--thread-id` 用于论坛主题（或使用 `:topic:` 目标）

    Telegram 发送还支持：

-    - 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带有 `buttons` 块的 `--presentation` 来生成内联键盘
-    - 当机器人可以在该聊天中置顶时，使用 `--pin` 或 `--delivery '{"pin":true}'` 请求置顶投递
-    - 使用 `--force-document` 将出站图片和 GIF 作为文档发送，而不是作为压缩照片或动态媒体上传
+    - 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带有 `buttons` 块的 `--presentation` 来实现内联键盘
+    - `--pin` 或 `--delivery '{"pin":true}'`，在机器人可在该聊天中置顶时请求置顶投递
+    - `--force-document`，将出站图片和 GIF 作为文档发送，而不是压缩照片或动画媒体上传

-    Action 门控：
+    操作门控：

-    - `channels.telegram.actions.sendMessage=false` 会禁用出站 Telegram 消息，包括投票
-    - `channels.telegram.actions.poll=false` 会禁用 Telegram 投票创建，但保留常规发送启用
+    - `channels.telegram.actions.sendMessage=false` 禁用出站 Telegram 消息，包括投票
+    - `channels.telegram.actions.poll=false` 禁用 Telegram 投票创建，同时保留常规发送启用

  </Accordion>

-  <Accordion title="Telegram 中的 exec 审批">
-    Telegram 支持在审批者私信中进行 exec 审批，并可选择在原始聊天或话题中发布提示。审批者必须是数字 Telegram 用户 ID。
+  <Accordion title="Telegram 中的执行审批">
+    Telegram 支持在审批者私信中进行执行审批，也可以选择在原始聊天或主题中发布提示。审批者必须是数字 Telegram 用户 ID。

    配置路径：

-    - `channels.telegram.execApprovals.enabled`（当至少一个审批者可解析时自动启用）
+    - `channels.telegram.execApprovals.enabled`（至少有一个审批者可解析时自动启用）
    - `channels.telegram.execApprovals.approvers`（回退到 `commands.ownerAllowFrom` 中的数字所有者 ID）
    - `channels.telegram.execApprovals.target`：`dm`（默认）| `channel` | `both`
    - `agentFilter`、`sessionFilter`

-    `channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制谁可以与机器人对话，以及机器人将普通回复发送到哪里。它们不会让某人成为 exec 审批者。当还没有命令所有者时，首次获批的私信配对会引导写入 `commands.ownerAllowFrom`，因此单所有者设置仍然无需在 `execApprovals.approvers` 下重复 ID 即可工作。
+    `channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制谁可以与机器人交谈，以及它在哪里发送普通回复。它们不会让某人成为执行审批者。当尚无命令所有者时，第一次获批的私信配对会引导写入 `commands.ownerAllowFrom`，因此单所有者设置仍可工作，而无需在 `execApprovals.approvers` 下重复 ID。

-    channel 投递会在聊天中显示命令文本；仅在可信群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。Exec 审批默认在 30 分钟后过期。
+    渠道投递会在聊天中显示命令文本；仅在可信群组/主题中启用 `channel` 或 `both`。当提示落在论坛主题中时，OpenClaw 会为审批提示和后续回复保留该主题。执行审批默认 30 分钟后过期。

-    内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 会通过插件审批解析；其他 ID 会先通过 exec 审批解析。
+    内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 会通过插件审批解析；其他 ID 会先通过执行审批解析。

-    参见 [Exec 审批](/zh-CN/tools/exec-approvals)。
+    参见 [执行审批](/zh-CN/tools/exec-approvals)。

  </Accordion>
 </AccordionGroup>

 ## 错误回复控制

-当 agent 遇到投递或提供商错误时，Telegram 可以回复错误文本，也可以抑制该回复。两个配置键控制此行为：
+当智能体遇到投递或提供商错误时，Telegram 可以回复错误文本，也可以抑制它。两个配置键控制此行为：

-| 键                                  | 值                | 默认值  | 描述                                                                                     |
-| ----------------------------------- | ----------------- | ------- | ---------------------------------------------------------------------------------------- |
-| `channels.telegram.errorPolicy`     | `reply`, `silent` | `reply` | `reply` 会向聊天发送友好的错误消息。`silent` 会完全抑制错误回复。                       |
-| `channels.telegram.errorCooldownMs` | number (ms)       | `60000` | 向同一聊天发送错误回复之间的最短时间。防止故障期间产生错误刷屏。                       |
+| 键                                  | 值                | 默认值  | 描述                                                                                            |
+| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
+| `channels.telegram.errorPolicy`     | `reply`, `silent` | `reply` | `reply` 会向聊天发送友好的错误消息。`silent` 会完全抑制错误回复。                               |
+| `channels.telegram.errorCooldownMs` | number (ms)       | `60000` | 对同一聊天的错误回复之间的最短时间。防止故障期间出现错误刷屏。                                  |

-支持按账户、按群组和按话题覆盖（继承方式与其他 Telegram 配置键相同）。
+支持按账号、按群组和按主题覆盖（与其他 Telegram 配置键使用相同继承规则）。

 ```json5
 {
@ -835,20 +837,20 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
 <AccordionGroup>
  <Accordion title="机器人不响应群组中的非提及消息">

-    - 如果 `requireMention=false`，Telegram 隐私模式必须允许完整可见性。
+    - 如果 `requireMention=false`，Telegram 隐私模式必须允许完全可见。
      - BotFather：`/setprivacy` -> Disable
      - 然后将机器人从群组移除并重新添加
-    - 当配置预期接收未提及的群组消息时，`openclaw channels status` 会发出警告。
-    - `openclaw channels status --probe` 可以检查显式数字群组 ID；通配符 `"*"` 无法进行成员身份探测。
+    - 当配置期望未提及的群组消息时，`openclaw channels status` 会发出警告。
+    - `openclaw channels status --probe` 可以检查显式数字群组 ID；通配符 `"*"` 无法进行成员探测。
    - 快速会话测试：`/activation always`。

  </Accordion>

  <Accordion title="机器人完全看不到群组消息">

-    - 当存在 `channels.telegram.groups` 时，必须列出该群组（或包含 `"*"`）
+    - 当 `channels.telegram.groups` 存在时，群组必须列出（或包含 `"*"`）
    - 验证机器人在群组中的成员身份
-    - 查看日志：`openclaw logs --follow` 以了解跳过原因
+    - 查看日志：`openclaw logs --follow`，了解跳过原因

  </Accordion>

@ -856,32 +858,32 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \

    - 授权你的发送者身份（配对和/或数字 `allowFrom`）
    - 即使群组策略为 `open`，命令授权仍然适用
-    - `setMyCommands failed` 并带有 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生命令菜单
-    - 启动时的 `deleteMyCommands` / `setMyCommands` 调用以及 `sendChatAction` 正在输入调用都是有界的，并会在请求超时时通过 Telegram 的传输回退重试一次。持续的网络/fetch 错误通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性问题
+    - `setMyCommands failed` 与 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生命令菜单
+    - `deleteMyCommands` / `setMyCommands` 启动调用和 `sendChatAction` 正在输入调用是有界的，并会在请求超时时通过 Telegram 的传输回退重试一次。持续的网络/fetch 错误通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性问题

  </Accordion>

-  <Accordion title="启动报告未授权 token">
+  <Accordion title="启动报告未授权令牌">

-    - `getMe returned 401` 是配置的机器人令牌发生 Telegram 身份验证失败。
-    - 在 BotFather 中重新复制或重新生成机器人令牌，然后为默认账户更新 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts.<id>.botToken` 或 `TELEGRAM_BOT_TOKEN`。
-    - 启动期间的 `deleteWebhook 401 Unauthorized` 也是身份验证失败；把它当作“不存在 webhook”只会把同一个无效令牌失败推迟到后续 API 调用。
+    - `getMe returned 401` 是已配置机器人令牌的 Telegram 身份验证失败。
+    - 在 BotFather 中重新复制或重新生成机器人令牌，然后为默认账号更新 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts.<id>.botToken` 或 `TELEGRAM_BOT_TOKEN`。
+    - 启动期间的 `deleteWebhook 401 Unauthorized` 也是身份验证失败；将其视为“不存在网络钩子”只会把同一个无效令牌故障推迟到后续 API 调用。

  </Accordion>

  <Accordion title="轮询或网络不稳定">

-    - Node 22+ + 自定义 fetch/proxy 可能会在 AbortSignal 类型不匹配时触发立即中止行为。
-    - 某些主机会先把 `api.telegram.org` 解析到 IPv6；损坏的 IPv6 出站连接可能导致间歇性的 Telegram API 失败。
+    - Node 22+ 加自定义 fetch/代理在 AbortSignal 类型不匹配时可能触发立即中止行为。
+    - 某些主机会先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出站连接可能导致间歇性的 Telegram API 失败。
    - 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些作为可恢复的网络错误重试。
-    - 在轮询启动期间，OpenClaw 会为 grammY 复用成功的启动 `getMe` 探测，因此运行器在第一次 `getUpdates` 之前不需要第二次 `getMe`。
-    - 如果 `deleteWebhook` 在轮询启动期间因瞬时网络错误失败，OpenClaw 会继续进入长轮询，而不是再发起一次轮询前控制平面调用。仍处于活动状态的 webhook 会表现为 `getUpdates` 冲突；随后 OpenClaw 会重建 Telegram 传输并重试 webhook 清理。
-    - 如果 Telegram 套接字按很短的固定周期回收，请检查是否有过低的 `channels.telegram.timeoutSeconds`；机器人客户端会将低于出站和 `getUpdates` 请求保护阈值的配置值钳制到保护阈值以上，但旧版本在该值设置低于这些保护阈值时，可能会中止每次轮询或回复。
-    - 如果日志包含 `Polling stall detected`，默认情况下，OpenClaw 会在 120 秒内没有完成长轮询活性检查后重启轮询并重建 Telegram 传输。
-    - 当正在运行的轮询账户在启动宽限期后尚未完成 `getUpdates`、正在运行的 webhook 账户在启动宽限期后尚未完成 `setWebhook`，或上一次成功的轮询传输活动已经陈旧时，`openclaw channels status --probe` 和 `openclaw doctor` 会发出警告。
-    - 只有当长时间运行的 `getUpdates` 调用是健康的，但你的主机仍然报告误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。持续停滞通常指向主机与 `api.telegram.org` 之间的代理、DNS、IPv6 或 TLS 出站问题。
-    - Telegram 还会遵循进程代理环境变量用于 Bot API 传输，包括 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 及其小写变体。`NO_PROXY` / `no_proxy` 仍可绕过 `api.telegram.org`。
-    - 如果 OpenClaw 托管代理在服务环境中通过 `OPENCLAW_PROXY_URL` 配置，且不存在标准代理环境变量，Telegram 也会将该 URL 用于 Bot API 传输。
+    - 在轮询启动期间，OpenClaw 会为 grammY 复用启动时成功的 `getMe` 探测，因此运行器在第一次 `getUpdates` 之前不需要第二次 `getMe`。
+    - 如果轮询启动期间 `deleteWebhook` 因瞬时网络错误而失败，OpenClaw 会继续进入长轮询，而不是再发起一次轮询前控制平面调用。仍处于活动状态的网络钩子会表现为 `getUpdates` 冲突；随后 OpenClaw 会重建 Telegram 传输层并重试网络钩子清理。
+    - 如果 Telegram 套接字按较短的固定周期回收，请检查 `channels.telegram.timeoutSeconds` 是否过低；机器人客户端会把低于出站请求和 `getUpdates` 请求保护下限的配置值提升到该下限，但旧版本在该值设为低于这些保护阈值时，可能会中止每一次轮询或回复。
+    - 如果日志包含 `Polling stall detected`，默认情况下，OpenClaw 会在 120 秒内没有完成长轮询活性检查后重启轮询并重建 Telegram 传输层。
+    - 当正在运行的轮询账号在启动宽限期后仍未完成 `getUpdates`、正在运行的网络钩子账号在启动宽限期后仍未完成 `setWebhook`，或上次成功的轮询传输活动已过期时，`openclaw channels status --probe` 和 `openclaw doctor` 会发出警告。
+    - 仅当长时间运行的 `getUpdates` 调用是健康的，但你的主机仍报告误判的轮询停滞重启时，才增大 `channels.telegram.pollingStallThresholdMs`。持续停滞通常指向主机与 `api.telegram.org` 之间的代理、DNS、IPv6 或 TLS 出站问题。
+    - Telegram 还会为 Bot API 传输遵循进程代理环境变量，包括 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 及其小写变体。`NO_PROXY` / `no_proxy` 仍可绕过 `api.telegram.org`。
+    - 如果服务环境通过 `OPENCLAW_PROXY_URL` 配置了 OpenClaw 托管代理，且不存在标准代理环境变量，Telegram 也会使用该 URL 进行 Bot API 传输。
    - 在直接出站/TLS 不稳定的 VPS 主机上，通过 `channels.telegram.proxy` 路由 Telegram API 调用：

 ```yaml
@ -890,8 +892,8 @@ channels:
    proxy: socks5://<user>:<password>@proxy-host:1080
 ```

-    - Node 22+ 默认使用 `autoSelectFamily=true`（WSL2 除外）。Telegram DNS 结果顺序依次遵循 `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`、`channels.telegram.network.dnsResultOrder`，再到进程默认值，例如 `NODE_OPTIONS=--dns-result-order=ipv4first`；如果都不适用，Node 22+ 会回退到 `ipv4first`。
-    - 如果你的主机是 WSL2，或明确更适合仅 IPv4 行为，请强制选择地址族：
+    - Node 22+ 默认使用 `autoSelectFamily=true`（WSL2 除外）。Telegram DNS 结果顺序会依次遵循 `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`、`channels.telegram.network.dnsResultOrder`，然后遵循进程默认值，例如 `NODE_OPTIONS=--dns-result-order=ipv4first`；如果都不适用，Node 22+ 会回退到 `ipv4first`。
+    - 如果你的主机是 WSL2，或明确在仅 IPv4 行为下表现更好，请强制设置地址族选择：

 ```yaml
 channels:
@ -900,7 +902,10 @@ channels:
      autoSelectFamily: false
 ```

-    - 默认情况下，Telegram 媒体下载已允许 RFC 2544 基准测试范围地址（`198.18.0.0/15`）。如果可信的 fake-IP 或透明代理在媒体下载期间把 `api.telegram.org` 重写为其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过：
+    - RFC 2544 基准测试范围响应（`198.18.0.0/15`）默认已允许
+      用于 Telegram 媒体下载。如果受信任的 fake-IP 或
+      透明代理在媒体下载期间把 `api.telegram.org` 重写为其他
+      私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过：

 ```yaml
 channels:
@ -909,20 +914,25 @@ channels:
      dangerouslyAllowPrivateNetwork: true
 ```

-    - 同一个选择启用项也可按账户在
+    - 同样的选择加入也可以按账号在
      `channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork` 配置。
-    - 如果你的代理将 Telegram 媒体主机解析为 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已允许 RFC 2544 基准测试范围。
+    - 如果你的代理将 Telegram 媒体主机解析为 `198.18.x.x`，请先保持
+      危险标志关闭。Telegram 媒体默认已允许 RFC 2544
+      基准测试范围。

    <Warning>
      `channels.telegram.network.dangerouslyAllowPrivateNetwork` 会削弱 Telegram
-      媒体 SSRF 防护。仅在可信、由操作员控制的代理环境中使用它，例如 Clash、Mihomo 或 Surge fake-IP 路由，且它们会在 RFC 2544 基准测试范围之外合成私有或特殊用途答案。对于正常的公网 Telegram 访问，请保持关闭。
+      媒体 SSRF 防护。仅在受信任、由运维方控制的代理环境中使用它，
+      例如 Clash、Mihomo 或 Surge fake-IP 路由，并且这些环境会合成
+      RFC 2544 基准测试范围以外的私有或特殊用途响应。普通公共互联网
+      Telegram 访问应保持关闭。
    </Warning>

    - 环境覆盖（临时）：
      - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
      - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
      - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
-    - 验证 DNS 答案：
+    - 验证 DNS 响应：

 ```bash
 dig +short api.telegram.org A
@ -938,34 +948,34 @@ dig +short api.telegram.org AAAA

 主要参考：[配置参考 - Telegram](/zh-CN/gateway/config-channels#telegram)。

-<Accordion title="高信号 Telegram 字段">
+<Accordion title="高信息量 Telegram 字段">

 - 启动/身份验证：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向常规文件；符号链接会被拒绝）
 - 访问控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`、`groups.*.topics.*`、顶层 `bindings[]`（`type: "acp"`）
- 执行批准：`execApprovals`、`accounts.*.execApprovals`
+- 执行审批：`execApprovals`、`accounts.*.execApprovals`
 - 命令/菜单：`commands.native`、`commands.nativeSkills`、`customCommands`
 - 线程/回复：`replyToMode`、`dm.threadReplies`、`direct.*.threadReplies`
 - 流式传输：`streaming`（预览）、`streaming.preview.toolProgress`、`blockStreaming`
 - 格式化/投递：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix`
 - 媒体/网络：`mediaMaxMb`、`mediaGroupFlushMs`、`timeoutSeconds`、`pollingStallThresholdMs`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy`
- 自定义 API 根：`apiRoot`（仅 Bot API 根；不要包含 `/bot<TOKEN>`）
- webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost`
+- 自定义 API 根地址：`apiRoot`（仅 Bot API 根地址；不要包含 `/bot<TOKEN>`）
+- 网络钩子：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost`
 - 操作/能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
- 表情回应：`reactionNotifications`、`reactionLevel`
+- 回应：`reactionNotifications`、`reactionLevel`
 - 错误：`errorPolicy`、`errorCooldownMs`
- 写入/历史：`configWrites`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
+- 写入/历史记录：`configWrites`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`

 </Accordion>

 <Note>
-多账户优先级：配置两个或更多账户 ID 时，请设置 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`）以明确默认路由。否则 OpenClaw 会回退到第一个规范化账户 ID，且 `openclaw doctor` 会发出警告。命名账户会继承 `channels.telegram.allowFrom` / `groupAllowFrom`，但不会继承 `accounts.default.*` 值。
+多账号优先级：当配置了两个或更多账号 ID 时，设置 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`）以明确默认路由。否则 OpenClaw 会回退到第一个规范化后的账号 ID，并且 `openclaw doctor` 会发出警告。命名账号会继承 `channels.telegram.allowFrom` / `groupAllowFrom`，但不会继承 `accounts.default.*` 值。
 </Note>

 ## 相关内容

 <CardGroup cols={2}>
  <Card title="配对" icon="link" href="/zh-CN/channels/pairing">
-    将 Telegram 用户配对到 Gateway 网关。
+    将 Telegram 用户与 Gateway 网关配对。
  </Card>
  <Card title="群组" icon="users" href="/zh-CN/channels/groups">
    群组和话题允许列表行为。
--- a/docs/zh-CN/concepts/progress-drafts.md
+++ b/docs/zh-CN/concepts/progress-drafts.md
@ -0,0 +1,254 @@
+---
+read_when:
+    - 为长时间运行的聊天轮次配置可见的进度更新
+    - 在部分、分块和进度流式传输模式之间选择
+    - 解释 OpenClaw 如何在工作进行期间更新一条渠道消息
+    - 进度草稿、独立进度消息或最终化回退的故障排除
+summary: 进度草稿：智能体运行时会更新的一条可见的进行中消息
+title: 进度草稿
+x-i18n:
+    generated_at: "2026-05-03T21:05:45Z"
+    model: gpt-5.5
+    provider: openai
+    source_hash: 0fc0dff38232228b49872d66f4498f065675cdd3abf3a0f4003cb34fcbb7de8c
+    source_path: concepts/progress-drafts.md
+    workflow: 16
+---
+
+进度草稿让长时间运行的智能体回合在聊天中显得仍然活跃，同时不会把对话变成一堆临时状态回复。
+
+启用进度草稿后，OpenClaw 会创建一条可见的进行中消息，在智能体读取、规划、调用工具或等待批准时更新它，然后在渠道可以安全执行时，将该草稿转换为最终答案。
+
+```text
+Shelling
+- reading recent channel context
+- checking matching issues
+- preparing reply
+```
+
+当你希望在工具密集型工作期间只显示一条整洁的状态消息，并在回合完成后显示最终答案时，请使用进度草稿。
+
+## 快速开始
+
+使用 `streaming.mode: "progress"` 按渠道启用进度草稿：
+
+```json5
+{
+  channels: {
+    discord: {
+      streaming: {
+        mode: "progress",
+      },
+    },
+  },
+}
+```
+
+这通常就足够了。OpenClaw 会自动选择一个单词标签，在有用工作发生时添加紧凑的进度行，并在该回合中抑制重复的独立进度提示。
+
+## 用户会看到什么
+
+进度草稿包含两个部分：
+
+| 部分 | 用途 |
+| -------------- | ----------------------------------------------------------------- |
+| 标签 | 简短标题，例如 `Thinking` 或 `Shelling`。 |
+| 进度行 | 紧凑的运行更新，例如工具调用、任务步骤或批准。 |
+
+标签会在智能体开始回复时立即显示。只有当智能体发出有用的工作更新时，才会添加进度行。在可能的情况下，最终答案会替换草稿；否则，OpenClaw 会正常发送最终答案，并根据渠道传输方式清理草稿或停止更新草稿。
+
+## 选择模式
+
+`channels.<channel>.streaming.mode` 控制可见的进行中行为：
+
+| 模式 | 最适合 | 聊天中显示的内容 |
+| ---------- | -------------------------------- | ------------------------------------------------- |
+| `off` | 安静渠道 | 仅最终答案。 |
+| `partial` | 观察答案文本逐步出现 | 一个草稿，编辑为最新答案文本。 |
+| `block` | 更大的答案预览分块 | 一个预览，以更大分块更新或追加。 |
+| `progress` | 工具密集型或长时间运行的回合 | 一条状态草稿，然后是最终答案。 |
+
+当用户更关心“正在发生什么”，而不是逐个 token 观看答案文本流式输出时，请选择 `progress`。
+
+当答案本身就是进度信号时，请选择 `partial`。
+
+当你想用更大的文本块更新草稿预览时，请选择 `block`。在 Discord 和 Telegram 上，`streaming.mode: "block"` 仍然是预览流式传输，而不是普通分块投递。当你想要普通分块回复时，请使用 `streaming.block.enabled` 或旧版 `blockStreaming`。
+
+## 配置标签
+
+进度标签位于 `channels.<channel>.streaming.progress` 下。
+
+默认标签是 `auto`，它会从 OpenClaw 的内置单词标签池中选择：
+
+```text
+Thinking
+Shelling
+Scuttling
+Clawing
+Pinching
+Molting
+Bubbling
+Tiding
+Reefing
+Cracking
+Sifting
+Brining
+Nautiling
+Krilling
+Barnacling
+Lobstering
+Tidepooling
+Pearling
+Snapping
+Surfacing
+```
+
+使用固定标签：
+
+```json5
+{
+  channels: {
+    discord: {
+      streaming: {
+        mode: "progress",
+        progress: {
+          label: "Investigating",
+        },
+      },
+    },
+  },
+}
+```
+
+使用你自己的自动标签池：
+
+```json5
+{
+  channels: {
+    discord: {
+      streaming: {
+        mode: "progress",
+        progress: {
+          label: "auto",
+          labels: ["Checking", "Reading", "Testing", "Finishing"],
+        },
+      },
+    },
+  },
+}
+```
+
+隐藏标签，只显示进度行：
+
+```json5
+{
+  channels: {
+    discord: {
+      streaming: {
+        mode: "progress",
+        progress: {
+          label: false,
+        },
+      },
+    },
+  },
+}
+```
+
+## 控制进度行
+
+在进度模式下，进度行默认启用。它们来自真实的运行事件：工具启动、项目更新、任务计划、批准、命令输出、补丁摘要以及类似的智能体活动。
+
+限制保持可见的行数：
+
+```json5
+{
+  channels: {
+    discord: {
+      streaming: {
+        mode: "progress",
+        progress: {
+          maxLines: 4,
+        },
+      },
+    },
+  },
+}
+```
+
+保留单条进度草稿，但隐藏工具和任务行：
+
+```json5
+{
+  channels: {
+    discord: {
+      streaming: {
+        mode: "progress",
+        progress: {
+          toolProgress: false,
+        },
+      },
+    },
+  },
+}
+```
+
+使用 `toolProgress: false` 时，OpenClaw 仍会抑制该回合中较旧的独立工具进度消息。除已配置的标签外，渠道会在视觉上保持安静，直到最终答案出现。
+
+## 渠道行为
+
+每个渠道都会使用其支持的最简洁传输方式：
+
+| 渠道 | 进度传输 | 说明 |
+| --------------- | -------------------------------------- | --------------------------------------------------------------------- |
+| Discord | 发送一条消息，然后编辑它。 | 当最终文本适合一条安全预览消息时，会就地编辑。 |
+| Matrix | 发送一个事件，然后编辑它。 | 账号级流式传输配置控制账号级草稿。 |
+| Microsoft Teams | 个人聊天中的原生 Teams 流。 | `streaming.mode: "block"` 映射到 Teams 分块投递。 |
+| Slack | 原生流或可编辑草稿帖。 | 线程可用性会影响是否可以使用原生流式传输。 |
+| Telegram | 发送一条消息，然后编辑它。 | 较旧的可见草稿可能会被替换，以保持最终时间戳有用。 |
+| Mattermost | 可编辑草稿帖。 | 工具活动会折叠到同一个草稿样式帖子中。 |
+
+没有安全编辑支持的渠道通常会回退到输入指示器或仅最终答案投递。
+
+## 最终化
+
+当最终答案准备好时，OpenClaw 会尝试保持聊天整洁：
+
+- 如果草稿可以安全地成为最终答案，OpenClaw 会就地编辑它。
+- 如果渠道使用原生进度流式传输，OpenClaw 会在原生传输接受最终文本时最终化该流。
+- 如果最终答案包含媒体、批准提示、显式回复目标、过多分块，或者编辑/发送失败，OpenClaw 会通过正常渠道投递路径发送最终答案。
+
+回退路径是有意设计的。发送新的最终答案，优于丢失文本、把回复串到错误线程，或用渠道无法安全表示的载荷覆盖草稿。
+
+## 故障排除
+
+**我只看到最终答案。**
+
+检查处理该消息的账号或渠道是否已将 `channels.<channel>.streaming.mode` 设置为 `progress`。当渠道无法安全编辑正确消息时，一些群组或引用回复路径可能会禁用该回合的草稿预览。
+
+**我看到标签，但没有工具行。**
+
+检查 `streaming.progress.toolProgress`。如果它是 `false`，OpenClaw 会保留单草稿行为，但隐藏工具和任务进度行。
+
+**我看到一条新的最终消息，而不是编辑后的草稿。**
+
+这是安全回退。媒体回复、长答案、显式回复目标、旧 Telegram 草稿、缺失的 Slack 线程目标、已删除的预览消息，或原生流最终化失败，都可能导致这种情况。
+
+**我仍然看到独立进度消息。**
+
+当草稿处于活动状态时，进度模式会抑制默认的独立工具进度消息。如果独立消息仍然出现，请确认该回合确实在使用进度模式，而不是 `streaming.mode: "off"`，也不是某个无法为该消息创建草稿的渠道路径。
+
+**Teams 的行为与 Discord 或 Telegram 不同。**
+
+Microsoft Teams 在个人聊天中使用原生流，而不是通用的发送并编辑预览传输。Teams 还会将 `streaming.mode: "block"` 视为 Teams 分块投递，因为它没有 Discord 和 Telegram 使用的同一种草稿预览分块模式。
+
+## 相关内容
+
+- [流式传输和分块](/zh-CN/concepts/streaming)
+- [消息](/zh-CN/concepts/messages)
+- [频道配置](/zh-CN/gateway/config-channels)
+- [Discord](/zh-CN/channels/discord)
+- [Matrix](/zh-CN/channels/matrix)
+- [Microsoft Teams](/zh-CN/channels/msteams)
+- [Slack](/zh-CN/channels/slack)
+- [Telegram](/zh-CN/channels/telegram)
--- a/docs/zh-CN/concepts/streaming.md
+++ b/docs/zh-CN/concepts/streaming.md
@ -3,27 +3,27 @@ read_when:
    - 说明流式传输或分块在渠道上的工作方式
    - 更改分块流式传输或渠道分块行为
    - 调试重复/过早的分块回复或渠道预览流式传输
-summary: 流式传输 + 分块行为（块回复、渠道预览流式传输、模式映射）
+summary: 流式传输 + 分块行为（分块回复、渠道预览流式传输、模式映射）
 title: 流式传输和分块
 x-i18n:
-    generated_at: "2026-05-03T15:33:28Z"
+    generated_at: "2026-05-03T21:05:41Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 4a62b333123d317cad9a8063a68c5c026fb91b23731a6ccdb97d995d9bb8bdba
+    source_hash: 1335f4f5532060bd8bf839683a2b1fbab38f38887c5583135652b4753e0f6a50
    source_path: concepts/streaming.md
    workflow: 16
 ---

 OpenClaw 有两个独立的流式传输层：

- **分块流式传输（渠道）：** 在 assistant 写入时发出已完成的 **blocks**。这些是普通渠道消息（不是 token 增量）。
+- **分块流式传输（渠道）：** 在助手写入时发出已完成的 **块**。这些是普通的渠道消息（不是 token 增量）。
 - **预览流式传输（Telegram/Discord/Slack）：** 生成期间更新临时的 **预览消息**。

-目前渠道消息没有**真正的 token 增量流式传输**。预览流式传输基于消息（发送 + 编辑/追加）。
+目前没有面向渠道消息的 **真正 token 增量流式传输**。预览流式传输基于消息（发送 + 编辑/追加）。

 ## 分块流式传输（渠道消息）

-分块流式传输会在 assistant 输出可用时，以较粗粒度的分块发送输出。
+分块流式传输会在助手输出可用时，以较粗的分块发送输出。

 ```
 Model output
@ -38,74 +38,74 @@ Model output
 图例：

 - `text_delta/events`：模型流事件（对于非流式模型可能较稀疏）。
- `chunker`：`EmbeddedBlockChunker`，应用最小/最大边界 + 断点偏好。
+- `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? }`（发送前合并流式块）。
 - 渠道硬上限：`*.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`：等到 assistant 消息完成后，再刷新缓冲的输出。
+- `text_end`：只要 chunker 发出块就流式发送；每次 `text_end` 时刷新。
+- `message_end`：等待助手消息完成，然后刷新已缓冲的输出。

 如果缓冲文本超过 `maxChars`，`message_end` 仍会使用 chunker，因此它可以在末尾发出多个分块。

-### 使用分块流式传输交付媒体
+### 使用分块流式传输传递媒体

-`MEDIA:` 指令是普通交付元数据。当分块流式传输提前发送媒体块时，OpenClaw 会记住该回合的交付。如果最终 assistant payload 重复同一媒体 URL，最终交付会移除重复媒体，而不是再次发送附件。
+`MEDIA:` 指令是普通的投递元数据。当分块流式传输提前发送媒体块时，OpenClaw 会记住该轮次的这次投递。如果最终助手载荷重复同一个媒体 URL，最终投递会去除重复媒体，而不是再次发送附件。

-完全重复的最终 payload 会被抑制。如果最终 payload 在已流式传输的媒体周围添加不同文本，OpenClaw 仍会发送新文本，同时保持媒体只交付一次。这可防止在 Telegram 等渠道上出现重复语音消息或文件，例如智能体在流式传输期间发出 `MEDIA:`，而提供商也在完成的回复中包含它时。
+完全重复的最终载荷会被抑制。如果最终载荷在已流式发送的媒体周围添加了不同文本，OpenClaw 仍会发送新文本，同时保持媒体只投递一次。这可以避免在 Telegram 等渠道上出现重复语音留言或文件，例如当智能体在流式传输期间发出 `MEDIA:`，而提供商也在完成回复中包含它时。

 ## 分块算法（低/高边界）

-分块由 `EmbeddedBlockChunker` 实现：
+块分块由 `EmbeddedBlockChunker` 实现：

- **低边界：** 直到缓冲区 >= `minChars` 才发出（除非强制）。
- **高边界：** 优先在 `maxChars` 前拆分；如果强制，则在 `maxChars` 处拆分。
+- **低边界：** 缓冲区 >= `minChars` 前不发出（除非强制）。
+- **高边界：** 优先在 `maxChars` 之前拆分；如果强制，则在 `maxChars` 处拆分。
 - **断点偏好：** `paragraph` → `newline` → `sentence` → `whitespace` → 硬断点。
- **代码围栏：** 绝不在围栏内拆分；在 `maxChars` 处强制拆分时，会关闭 + 重新打开围栏，以保持 Markdown 有效。
+- **代码围栏：** 永不在围栏内部拆分；当在 `maxChars` 处强制拆分时，会关闭 + 重新打开围栏，以保持 Markdown 有效。

-`maxChars` 会被限制到渠道的 `textChunkLimit`，因此你不能超过每个渠道的上限。
+`maxChars` 会被限制到渠道的 `textChunkLimit`，所以你不能超过每个渠道的上限。

 ## 合并（合并流式块）

-启用分块流式传输时，OpenClaw 可以在发送前**合并连续的块分片**。这会减少“单行刷屏”，同时仍然提供渐进式输出。
+启用分块流式传输时，OpenClaw 可以在发送前 **合并连续的块分块**。这会减少“单行刷屏”，同时仍提供渐进式输出。

- 合并会等待**空闲间隔**（`idleMs`）后再刷新。
+- 合并会等待 **空闲间隔**（`idleMs`）后再刷新。
 - 缓冲区受 `maxChars` 限制，超过时会刷新。
- `minChars` 会阻止过小片段发送，直到累积足够文本（最终刷新始终发送剩余文本）。
- 连接符源自 `blockStreamingChunk.breakPreference`（`paragraph` → `\n\n`，`newline` → `\n`，`sentence` → 空格）。
- 可通过 `*.blockStreamingCoalesce` 设置渠道覆盖（包括按账户配置）。
- 除非覆盖，Signal/Slack/Discord 的默认合并 `minChars` 会提升到 1500。
+- `minChars` 会防止过小片段发送，直到累积足够文本（最终刷新总会发送剩余文本）。
+- 连接符来自 `blockStreamingChunk.breakPreference`（`paragraph` → `\n\n`，`newline` → `\n`，`sentence` → 空格）。
+- 可通过 `*.blockStreamingCoalesce` 使用渠道覆盖（包括按账号配置）。
+- 除非覆盖，否则 Signal/Slack/Discord 的默认合并 `minChars` 会提升到 1500。

 ## 分块之间的拟人化节奏

-启用分块流式传输时，你可以在分块回复之间（第一个块之后）添加**随机暂停**。这会让多气泡回复感觉更自然。
+启用分块流式传输时，你可以在分块回复之间（第一个分块之后）添加 **随机化暂停**。这会让多气泡响应感觉更自然。

 - 配置：`agents.defaults.humanDelay`（通过 `agents.list[].humanDelay` 按智能体覆盖）。
 - 模式：`off`（默认）、`natural`（800–2500ms）、`custom`（`minMs`/`maxMs`）。
- 仅适用于**分块回复**，不适用于最终回复或工具摘要。
+- 仅适用于 **分块回复**，不适用于最终回复或工具摘要。

 ## “流式传输分块或全部内容”

-这映射到：
+这对应于：

 - **流式传输分块：** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（边生成边发出）。非 Telegram 渠道还需要 `*.blockStreaming: true`。
- **在末尾流式传输全部内容：** `blockStreamingBreak: "message_end"`（刷新一次，如果很长可能有多个分块）。
+- **在末尾流式传输全部内容：** `blockStreamingBreak: "message_end"`（刷新一次；如果很长，可能产生多个分块）。
 - **无分块流式传输：** `blockStreamingDefault: "off"`（仅最终回复）。

-**渠道说明：** 除非显式将 `*.blockStreaming` 设置为 `true`，否则分块流式传输**关闭**。渠道可以流式传输实时预览（`channels.<channel>.streaming`），而不发送分块回复。
+**渠道注意事项：** 除非明确将 `*.blockStreaming` 设置为 `true`，否则分块流式传输为 **关闭**。渠道可以流式传输实时预览（`channels.<channel>.streaming`），而不发送分块回复。

-配置位置提醒：`blockStreaming*` 默认值位于 `agents.defaults` 下，而不是根配置。
+配置位置提醒：`blockStreaming*` 默认值位于 `agents.defaults` 下，而不是根配置中。

 ## 预览流式传输模式

@ -116,25 +116,28 @@ Model output
 - `off`：禁用预览流式传输。
 - `partial`：单个预览，会被最新文本替换。
 - `block`：以分块/追加步骤更新预览。
- `progress`：生成期间显示进度/Status 预览，完成时给出最终答案。
+- `progress`：生成期间显示进度/状态预览，完成时给出最终答案。
+
+`streaming.mode: "block"` 是适用于 Discord 和 Telegram 等可编辑渠道的预览流式传输模式。它不会在这些渠道启用渠道分块投递。需要普通分块回复时，请使用 `streaming.block.enabled` 或旧版 `blockStreaming` 渠道键。Microsoft Teams 是例外：它没有草稿预览分块传输，因此 `streaming.mode: "block"` 会映射到 Teams 分块投递，而不是原生 partial/progress 流式传输。

 ### 渠道映射

-| 渠道 | `off` | `partial` | `block` | `progress` |
-| ---------- | ----- | --------- | ------- | ----------------- |
-| Telegram | ✅ | ✅ | ✅ | 映射到 `partial` |
-| Discord | ✅ | ✅ | ✅ | 映射到 `partial` |
-| Slack | ✅ | ✅ | ✅ | ✅ |
-| Mattermost | ✅ | ✅ | ✅ | ✅ |
+| 渠道    | `off` | `partial` | `block` | `progress`              |
+| ---------- | ----- | --------- | ------- | ----------------------- |
+| Telegram   | ✅    | ✅        | ✅      | 可编辑进度草稿 |
+| Discord    | ✅    | ✅        | ✅      | 可编辑进度草稿 |
+| Slack      | ✅    | ✅        | ✅      | ✅                      |
+| Mattermost | ✅    | ✅        | ✅      | ✅                      |
+| MS Teams   | ✅    | ✅        | ✅      | 原生进度流  |

 仅 Slack：

 - 当 `channels.slack.streaming.mode="partial"` 时，`channels.slack.streaming.nativeTransport` 会切换 Slack 原生流式传输 API 调用（默认：`true`）。
- Slack 原生流式传输和 Slack assistant 线程 Status 需要回复线程目标。顶层私信不会显示这种线程样式预览，但它们仍可使用 Slack 草稿预览帖子和编辑。
+- Slack 原生流式传输和 Slack 助手线程状态需要一个回复线程目标。顶层私信不会显示那种线程样式预览，但仍可使用 Slack 草稿预览帖子和编辑。

-旧键迁移：
+旧版键迁移：

- Telegram：旧版 `streamMode` 和标量/布尔 `streaming` 值会被 Doctor/配置兼容路径检测并迁移到 `streaming.mode`。
+- Telegram：旧版 `streamMode` 以及标量/布尔 `streaming` 值会被 Doctor/配置兼容路径检测并迁移到 `streaming.mode`。
 - Discord：`streamMode` + 布尔 `streaming` 会自动迁移到 `streaming` 枚举。
 - Slack：`streamMode` 会自动迁移到 `streaming.mode`；布尔 `streaming` 会自动迁移到 `streaming.mode` 加 `streaming.nativeTransport`；旧版 `nativeStreaming` 会自动迁移到 `streaming.nativeTransport`。

@ -143,49 +146,49 @@ Model output
 Telegram：

 - 在私信和群组/话题中使用 `sendMessage` + `editMessageText` 预览更新。
- 当预览已可见约一分钟时，会发送一条新的最终消息，而不是就地编辑，然后清理预览，使 Telegram 的时间戳反映回复完成时间。
- 当 Telegram 分块流式传输被显式启用时，会跳过预览流式传输（避免双重流式传输）。
+- 当预览已可见约一分钟时，会发送新的最终消息，而不是就地编辑；随后清理预览，使 Telegram 的时间戳反映回复完成时间。
+- 当显式启用 Telegram 分块流式传输时，会跳过预览流式传输（避免双重流式传输）。
 - `/reasoning stream` 可以将推理写入预览。

 Discord：

 - 使用发送 + 编辑预览消息。
 - `block` 模式使用草稿分块（`draftChunk`）。
- 当 Discord 分块流式传输被显式启用时，会跳过预览流式传输。
- 最终媒体、错误和显式回复 payload 会取消待处理预览，而不刷新新的草稿，然后使用正常交付。
+- 当显式启用 Discord 分块流式传输时，会跳过预览流式传输。
+- 最终媒体、错误和显式回复载荷会取消待处理预览，而不刷新新草稿，然后使用普通投递。

 Slack：

- 可用时，`partial` 可以使用 Slack 原生流式传输（`chat.startStream`/`append`/`stop`）。
- `block` 使用追加样式的草稿预览。
- `progress` 使用 Status 预览文本，然后给出最终答案。
+- `partial` 可在可用时使用 Slack 原生流式传输（`chat.startStream`/`append`/`stop`）。
+- `block` 使用追加式草稿预览。
+- `progress` 使用状态预览文本，然后发送最终答案。
 - 没有回复线程的顶层私信会使用草稿预览帖子和编辑，而不是 Slack 原生流式传输。
- 原生和草稿预览流式传输会抑制该回合的分块回复，因此 Slack 回复只通过一条交付路径流式传输。
- 最终媒体/错误 payload 和进度最终内容不会创建一次性草稿消息；只有能编辑预览的文本/块最终内容才会刷新待处理草稿文本。
+- 原生和草稿预览流式传输会抑制该轮次的分块回复，因此 Slack 回复只会通过一种投递路径流式传输。
+- 最终媒体/错误载荷和进度最终消息不会创建一次性草稿消息；只有可编辑预览的文本/块最终消息会刷新待处理草稿文本。

 Mattermost：

- 将思考、工具活动和部分回复文本流式传输到单个草稿预览帖子中，并在最终答案可安全发送时就地完成。
- 如果预览帖子在完成时已被删除或无法使用，则回退为发送新的最终帖子。
- 最终媒体/错误 payload 会先取消待处理预览更新，再正常交付，而不是刷新临时预览帖子。
+- 将思考、工具活动和部分回复文本流式写入单个草稿预览帖子，并在最终答案可以安全发送时就地完成。
+- 如果预览帖子在完成时已被删除或不可用，则回退为发送新的最终帖子。
+- 最终媒体/错误载荷会在普通投递前取消待处理预览更新，而不是刷新临时预览帖子。

 Matrix：

 - 当最终文本可以复用预览事件时，草稿预览会就地完成。
- 仅媒体、错误和回复目标不匹配的最终内容会先取消待处理预览更新，再正常交付；已可见的过时预览会被撤回。
+- 仅媒体、错误和回复目标不匹配的最终消息会在普通投递前取消待处理预览更新；已可见的过期预览会被撤回。

 ### 工具进度预览更新

-预览流式传输还可以包含**工具进度**更新，即“正在搜索网络”、“正在读取文件”或“正在调用工具”这类短 Status 行。工具运行时，它们会显示在同一条预览消息中，早于最终回复。这能让多步骤工具回合在第一个思考预览和最终答案之间保持视觉上的进行状态，而不是沉默。
+预览流式传输还可以包含 **工具进度** 更新，即类似“正在搜索网络”、“正在读取文件”或“正在调用工具”的短状态行。它们会在工具运行期间出现在同一条预览消息中，早于最终回复。这让多步骤工具轮次在第一个思考预览和最终答案之间保持视觉上的活跃，而不是静默。

-支持的表面：
+支持的界面：

- **Discord**、**Slack**、**Telegram** 和 **Matrix** 在预览流式传输处于活动状态时，默认会将工具进度流式传输到实时预览编辑中。
- Telegram 自 `v2026.4.22` 起已发布启用工具进度预览更新的行为；保持启用可保留该已发布行为。
- **Mattermost** 已将工具活动合并到它的单个草稿预览帖子中（见上文）。
- 工具进度编辑遵循活动的预览流式传输模式；当预览流式传输为 `off`，或分块流式传输已接管消息时会跳过。在 Telegram 上，`streaming.mode: "off"` 表示仅最终回复：通用进度闲聊也会被抑制，而不是作为独立的“Working...”消息交付；同时审批提示、媒体 payload 和错误仍会正常路由。
- 要保留预览流式传输但隐藏工具进度行，请为该渠道将 `streaming.preview.toolProgress` 设置为 `false`。要完全禁用预览编辑，请将 `streaming.mode` 设置为 `off`。
- Telegram 所选引用回复是一个例外：当 `replyToMode` 不是 `"off"` 且存在所选引用文本时，OpenClaw 会跳过该回合的答案预览流，因此工具进度预览行无法渲染。没有所选引用文本的当前消息回复仍会保留预览流式传输。详见 [Telegram 渠道文档](/zh-CN/channels/telegram)。
+- 默认情况下，当预览流式传输处于活动状态时，**Discord**、**Slack**、**Telegram** 和 **Matrix** 会将工具进度流式写入实时预览编辑。Microsoft Teams 在个人聊天中使用其原生进度流。
+- Telegram 自 `v2026.4.22` 起已发布并启用工具进度预览更新；保持启用可保留该已发布行为。
+- **Mattermost** 已经将工具活动折叠进其单个草稿预览帖子（见上文）。
+- 工具进度编辑会遵循活动的预览流式传输模式；当预览流式传输为 `off`，或分块流式传输已接管消息时，会跳过它们。在 Telegram 上，`streaming.mode: "off"` 表示仅最终消息：通用进度闲聊也会被抑制，而不是作为独立状态消息投递；审批提示、媒体载荷和错误仍会正常路由。
+- 若要保留预览流式传输但隐藏工具进度行，请将该渠道的 `streaming.preview.toolProgress` 设置为 `false`。若要完全禁用预览编辑，请将 `streaming.mode` 设置为 `off`。
+- Telegram 选定引用回复是例外：当 `replyToMode` 不是 `"off"` 且存在选定引用文本时，OpenClaw 会跳过该轮次的答案预览流，因此工具进度预览行无法渲染。没有选定引用文本的当前消息回复仍会保留预览流式传输。详情参见 [Telegram 渠道文档](/zh-CN/channels/telegram)。

 示例：

@ -204,8 +207,9 @@ Matrix：
 }
 ```

-## 相关内容
+## 相关

- [消息](/zh-CN/concepts/messages) — 消息生命周期和交付
- [重试](/zh-CN/concepts/retry) — 交付失败时的重试行为
- [渠道](/zh-CN/channels) — 各渠道流式传输支持
+- [进度草稿](/zh-CN/concepts/progress-drafts) — 长轮次期间会更新的可见进行中消息
+- [消息](/zh-CN/concepts/messages) — 消息生命周期和投递
+- [重试](/zh-CN/concepts/retry) — 投递失败时的重试行为
+- [渠道](/zh-CN/channels) — 按渠道列出的流式传输支持
--- a/docs/zh-CN/gateway/config-channels.md
+++ b/docs/zh-CN/gateway/config-channels.md
@ -1,54 +1,54 @@
 ---
 read_when:
-    - 配置渠道插件（身份验证、访问控制、多账号）
-    - 各渠道配置键名的故障排除
+    - 配置渠道插件（认证、访问控制、多账号）
+    - 按渠道配置键的故障排除
    - 审计私信策略、群组策略或提及门控
-summary: 渠道配置：跨 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等的访问控制、配对和按渠道密钥
+summary: 频道配置：Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等渠道的访问控制、配对和每渠道密钥
 title: 配置 — 渠道
 x-i18n:
-    generated_at: "2026-05-03T18:19:09Z"
+    generated_at: "2026-05-03T21:05:42Z"
    model: gpt-5.5
    provider: openai
-    source_hash: b92d7fe63a3d27c1740abb0986d6641d14d8d1017051f1744a02e1db77fda3c8
+    source_hash: 366bcee632c649219bbf6cf44d64cc13d966ec813abc74d54088d89de640b47c
    source_path: gateway/config-channels.md
    workflow: 16
 ---

 `channels.*` 下的每渠道配置键。涵盖私信和群组访问、多账号设置、提及门控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他内置渠道插件的每渠道键。

-对于智能体、工具、Gateway 网关运行时和其他顶层键，请参阅
+关于智能体、工具、Gateway 网关运行时和其他顶级键，请参阅
 [配置参考](/zh-CN/gateway/configuration-reference)。

 ## 渠道

-每个渠道会在其配置段存在时自动启动（除非设置了 `enabled: false`）。
+每个渠道会在其配置部分存在时自动启动（除非设置了 `enabled: false`）。

 ### 私信和群组访问

 所有渠道都支持私信策略和群组策略：

-| 私信策略            | 行为                                                            |
+| 私信策略            | 行为                                                        |
 | ------------------- | --------------------------------------------------------------- |
-| `pairing`（默认）   | 未知发送者会收到一次性配对码；所有者必须批准                    |
-| `allowlist`         | 仅允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者）     |
-| `open`              | 允许所有入站私信（需要 `allowFrom: ["*"]`）                     |
-| `disabled`          | 忽略所有入站私信                                                |
+| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 |
+| `allowlist`         | 仅允许 `allowFrom`（或已配对的允许存储）中的发送者             |
+| `open`              | 允许所有入站私信（需要 `allowFrom: ["*"]`）             |
+| `disabled`          | 忽略所有入站私信                                          |

-| 群组策略              | 行为                                                 |
-| --------------------- | ---------------------------------------------------- |
-| `allowlist`（默认）   | 仅允许匹配已配置允许列表的群组                       |
-| `open`                | 绕过群组允许列表（提及门控仍然适用）                 |
-| `disabled`            | 阻止所有群组/房间消息                                |
+| 群组策略          | 行为                                               |
+| --------------------- | ------------------------------------------------------ |
+| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组          |
+| `open`                | 跳过群组允许列表（提及门控仍适用） |
+| `disabled`            | 阻止所有群组/房间消息                          |

 <Note>
-`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时设定默认值。
-配对码在 1 小时后过期。待处理的私信配对请求每个渠道最多 **3 个**。
-如果提供商块完全缺失（`channels.<provider>` 不存在），运行时群组策略会回退到 `allowlist`（故障关闭）并在启动时发出警告。
+当提供商的 `groupPolicy` 未设置时，`channels.defaults.groupPolicy` 会设置默认值。
+配对码会在 1 小时后过期。待处理的私信配对请求限制为**每个渠道 3 个**。
+如果提供商块完全缺失（不存在 `channels.<provider>`），运行时群组策略会回退到 `allowlist`（失败关闭），并在启动时给出警告。
 </Note>

 ### 渠道模型覆盖

-使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当会话尚未有模型覆盖时（例如通过 `/model` 设置），会应用渠道映射。
+使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当会话还没有模型覆盖时（例如通过 `/model` 设置），会应用该渠道映射。

 ```json5
 {
@ -71,7 +71,7 @@ x-i18n:

 ### 渠道默认值和 Heartbeat

-使用 `channels.defaults` 设置跨提供商共享的群组策略和 Heartbeat 行为：
+使用 `channels.defaults` 跨提供商共享群组策略和 Heartbeat 行为：

 ```json5
 {
@ -90,14 +90,14 @@ x-i18n:
 ```

 - `channels.defaults.groupPolicy`：提供商级 `groupPolicy` 未设置时的回退群组策略。
- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/话题串/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。每渠道覆盖：`channels.<channel>.contextVisibility`。
+- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与允许列表相同，但保留明确的引用/回复上下文）。每渠道覆盖：`channels.<channel>.contextVisibility`。
 - `channels.defaults.heartbeat.showOk`：在 Heartbeat 输出中包含健康的渠道 Status。
 - `channels.defaults.heartbeat.showAlerts`：在 Heartbeat 输出中包含降级/错误 Status。
- `channels.defaults.heartbeat.useIndicator`：渲染紧凑指示器样式的 Heartbeat 输出。
+- `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器风格 Heartbeat 输出。

 ### WhatsApp

-WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链接会话存在时，它会自动启动。
+WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在已链接会话时，它会自动启动。

 ```json5
 {
@ -135,7 +135,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链
 }
 ```

-<Accordion title="多账号 WhatsApp">
+<Accordion title="Multi-account WhatsApp">

 ```json5
 {
@ -153,9 +153,9 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链
 }
 ```

- 出站命令默认使用 `default` 账号（如果存在）；否则使用第一个已配置账号 ID（排序后）。
- 可选的 `channels.whatsapp.defaultAccount` 会在匹配已配置账号 ID 时覆盖该回退默认账号选择。
- 旧版单账号 Baileys 凭证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。
+- 如果存在 `default`，出站命令默认使用账号 `default`；否则使用第一个已配置的账号 ID（排序后）。
+- 可选的 `channels.whatsapp.defaultAccount` 在匹配已配置账号 ID 时，会覆盖该回退默认账号选择。
+- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。
 - 每账号覆盖：`channels.whatsapp.accounts.<id>.sendReadReceipts`、`channels.whatsapp.accounts.<id>.dmPolicy`、`channels.whatsapp.accounts.<id>.allowFrom`。

 </Accordion>
@ -215,13 +215,13 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链
 }
 ```

- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅普通文件；拒绝符号链接），默认账号以 `TELEGRAM_BOT_TOKEN` 作为回退。
- `apiRoot` 只是 Telegram Bot API 根地址。使用 `https://api.telegram.org` 或你的自托管/代理根地址，而不是 `https://api.telegram.org/bot<TOKEN>`；`openclaw doctor --fix` 会移除意外的尾随 `/bot<TOKEN>` 后缀。
- 可选的 `channels.telegram.defaultAccount` 会在匹配已配置账号 ID 时覆盖默认账号选择。
- 在多账号设置（2 个或更多账号 ID）中，设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；当该项缺失或无效时，`openclaw doctor` 会发出警告。
+- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅限常规文件；拒绝符号链接），默认账号会回退使用 `TELEGRAM_BOT_TOKEN`。
+- `apiRoot` 仅是 Telegram Bot API 根地址。使用 `https://api.telegram.org` 或你的自托管/代理根地址，而不是 `https://api.telegram.org/bot<TOKEN>`；`openclaw doctor --fix` 会移除意外追加的 `/bot<TOKEN>` 后缀。
+- 可选的 `channels.telegram.defaultAccount` 在匹配已配置账号 ID 时，会覆盖默认账号选择。
+- 在多账号设置（2 个以上账号 ID）中，设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；缺失或无效时，`openclaw doctor` 会发出警告。
 - `configWrites: false` 会阻止由 Telegram 发起的配置写入（超级群组 ID 迁移、`/config set|unset`）。
- 顶层 `bindings[]` 条目中带有 `type: "acp"` 的项会为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings) 中共享。
- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于直接聊天和群组聊天）。
+- 带有 `type: "acp"` 的顶级 `bindings[]` 条目会为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#persistent-channel-bindings) 中共享。
+- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于私聊和群组聊天）。
 - 重试策略：请参阅[重试策略](/zh-CN/concepts/retry)。

 ### Discord
@ -277,7 +277,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
-      streaming: "off", // off | partial | block | progress (progress maps to partial on Discord)
+      streaming: "off", // off | partial | block | progress
      maxLinesPerMessage: 17,
      ui: {
        components: {
@ -327,41 +327,41 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链
 }
 ```

- 令牌：`channels.discord.token`，默认账户以 `DISCORD_BOT_TOKEN` 作为后备。
- 提供显式 Discord `token` 的直接出站调用会使用该令牌进行调用；账户重试/策略设置仍来自活动运行时快照中所选账户。
- 可选的 `channels.discord.defaultAccount` 在匹配已配置账户 ID 时会覆盖默认账户选择。
- 使用 `user:<id>`（私信）或 `channel:<id>`（公会渠道）作为投递目标；裸数字 ID 会被拒绝。
- 公会 slug 使用小写，并将空格替换为 `-`；渠道键使用 slug 化名称（不含 `#`）。优先使用公会 ID。
- 默认忽略机器人撰写的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 仅接受提及机器人的机器人消息（仍会过滤自己的消息）。
- `channels.discord.guilds.<id>.ignoreOtherMentions`（以及渠道覆盖项）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。
- `channels.discord.mentionAliases` 在发送前将稳定的出站 `@handle` 文本映射到 Discord 用户 ID，这样即使临时目录缓存为空，也能确定性地提及已知队友。每账户覆盖项位于 `channels.discord.accounts.<accountId>.mentionAliases` 下。
- `maxLinesPerMessage`（默认 17）即使在低于 2000 个字符时也会拆分行数较多的消息。
+- 令牌：`channels.discord.token`，默认账号使用 `DISCORD_BOT_TOKEN` 作为回退。
+- 提供显式 Discord `token` 的直接出站调用会使用该令牌发起调用；账号重试/策略设置仍来自活动运行时快照中选定的账号。
+- 可选的 `channels.discord.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
+- 对投递目标使用 `user:<id>`（私信）或 `channel:<id>`（服务器渠道）；裸数字 ID 会被拒绝。
+- 服务器 slug 为小写，并将空格替换为 `-`；渠道键使用 slug 化名称（不带 `#`）。优先使用服务器 ID。
+- 默认忽略由机器人发送的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 仅接受提及机器人的机器人消息（仍会过滤自身消息）。
+- `channels.discord.guilds.<id>.ignoreOtherMentions`（以及渠道级覆盖）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。
+- `channels.discord.mentionAliases` 会在发送前将稳定的出站 `@handle` 文本映射到 Discord 用户 ID，因此即使临时目录缓存为空，也能确定性地提及已知队友。按账号覆盖位于 `channels.discord.accounts.<accountId>.mentionAliases` 下。
+- `maxLinesPerMessage`（默认 17）即使在少于 2000 个字符时也会拆分过高的消息。
 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由：
-  - `enabled`：线程绑定会话功能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定投递/路由）的 Discord 覆盖项
-  - `idleHours`：非活动自动取消聚焦的 Discord 覆盖项，单位为小时（`0` 表示禁用）
-  - `maxAgeHours`：硬性最大时长的 Discord 覆盖项，单位为小时（`0` 表示禁用）
-  - `spawnSessions`：`sessions_spawn({ thread: true })` 和 ACP 线程生成自动线程创建/绑定的开关（默认：`true`）
+  - `enabled`：线程绑定会话功能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由）的 Discord 覆盖
+  - `idleHours`：按小时设置的不活动自动取消聚焦 Discord 覆盖（`0` 禁用）
+  - `maxAgeHours`：按小时设置的硬性最长时限 Discord 覆盖（`0` 禁用）
+  - `spawnSessions`：`sessions_spawn({ thread: true })` 和 ACP 线程生成自动创建/绑定线程的开关（默认：`true`）
  - `defaultSpawnContext`：线程绑定生成的原生子智能体上下文（默认 `"fork"`）
- 顶层 `bindings[]` 条目使用 `type: "acp"` 为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 ID）。字段语义在 [ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings) 中共享。
+- 带有 `type: "acp"` 的顶层 `bindings[]` 条目会为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 ID）。字段语义在 [ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings) 中共享。
 - `channels.discord.ui.components.accentColor` 设置 Discord components v2 容器的强调色。
- `channels.discord.voice` 启用 Discord 语音渠道对话，以及可选的自动加入 + LLM + TTS 覆盖项。仅文本的 Discord 配置默认关闭语音；设置 `channels.discord.voice.enabled=true` 以选择启用。
- `channels.discord.voice.model` 可选地覆盖用于 Discord 语音渠道回复的 LLM 模型。
+- `channels.discord.voice` 启用 Discord 语音渠道对话，以及可选的自动加入 + LLM + TTS 覆盖。纯文本 Discord 配置默认关闭语音；设置 `channels.discord.voice.enabled=true` 以选择启用。
+- `channels.discord.voice.model` 可选地覆盖用于 Discord 语音渠道响应的 LLM 模型。
 - `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` DAVE 选项（默认分别为 `true` 和 `24`）。
 - `channels.discord.voice.connectTimeoutMs` 控制 `/vc join` 和自动加入尝试的初始 `@discordjs/voice` Ready 等待时间（默认 `30000`）。
- `channels.discord.voice.reconnectGraceMs` 控制断开连接的语音会话在 OpenClaw 销毁它之前可进入重连信令的时长（默认 `15000`）。
- OpenClaw 还会在重复解密失败后，通过离开/重新加入语音会话来尝试恢复语音接收。
+- `channels.discord.voice.reconnectGraceMs` 控制已断开的语音会话在 OpenClaw 销毁它之前可花多长时间进入重连信令（默认 `15000`）。
+- OpenClaw 还会在重复解密失败后，通过离开/重新加入语音会话来尝试语音接收恢复。
 - `channels.discord.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔值 `streaming` 会自动迁移。
- `channels.discord.autoPresence` 将运行时可用性映射到机器人在线状态（healthy => online、degraded => idle、exhausted => dnd），并允许可选的状态文本覆盖。
- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/标签匹配（破窗兼容模式）。
- `channels.discord.execApprovals`：Discord 原生 exec 审批投递和审批人授权。
-  - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析审批人时，exec 审批会激活。
+- `channels.discord.autoPresence` 将运行时可用性映射到机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。
+- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/标签匹配（应急兼容模式）。
+- `channels.discord.execApprovals`：Discord 原生 exec 审批投递和审批者授权。
+  - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析审批者时，exec 审批会激活。
  - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。
  - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。
-  - `sessionFilter`：可选的会话键模式（子字符串或正则表达式）。
-  - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到来源渠道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮只能由已解析的审批人使用。
+  - `sessionFilter`：可选的会话键模式（子字符串或正则）。
+  - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批者私信，`"channel"` 发送到发起渠道，`"both"` 发送到两者。当 target 包含 `"channel"` 时，按钮仅可由已解析的审批者使用。
  - `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。

-**回应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自所有消息上的 `guilds.<id>.users`）。
+**反应通知模式：**`off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自所有消息上的 `guilds.<id>.users`）。

 ### Google Chat

@ -392,11 +392,11 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链
 }
 ```

- 服务账户 JSON：内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。
- 也支持服务账户 SecretRef（`serviceAccountRef`）。
- 环境变量后备：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。
- 使用 `spaces/<spaceId>` 或 `users/<userId>` 作为投递目标。
- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（破窗兼容模式）。
+- 服务账号 JSON：内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。
+- 也支持服务账号 SecretRef（`serviceAccountRef`）。
+- 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。
+- 对投递目标使用 `spaces/<spaceId>` 或 `users/<userId>`。
+- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（应急兼容模式）。

 ### Slack

@ -468,27 +468,27 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链
 }
 ```

- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账户环境变量后备为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。
- **HTTP mode** 需要 `botToken` 加 `signingSecret`（位于根级别或每账户）。
- `socketMode` 会将 Slack SDK Socket Mode 传输调优透传到公开的 Bolt receiver API。仅在调查 ping/pong 超时或陈旧 websocket 行为时使用它。
+- **Socket 模式** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。
+- **HTTP 模式** 需要 `botToken` 加 `signingSecret`（位于根级或按账号配置）。
+- `socketMode` 会将 Slack SDK Socket Mode 传输调优透传到公开的 Bolt 接收器 API。仅在调查 ping/pong 超时或陈旧 websocket 行为时使用它。
 - `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。
- Slack 账户快照会暴露每凭证的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的 `signingSecretStatus`。`configured_unavailable` 表示账户通过 SecretRef 配置，但当前命令/运行时路径无法解析 secret 值。
+- Slack 账号快照会暴露按凭证划分的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef 配置，但当前命令/运行时路径无法解析密钥值。
 - `configWrites: false` 会阻止由 Slack 发起的配置写入。
- 可选的 `channels.slack.defaultAccount` 在匹配已配置账户 ID 时会覆盖默认账户选择。
+- 可选的 `channels.slack.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
 - `channels.slack.streaming.mode` 是规范的 Slack 流模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔值 `streaming` 和 `nativeStreaming` 会自动迁移。
- 使用 `user:<id>`（私信）或 `channel:<id>` 作为投递目标。
+- 对投递目标使用 `user:<id>`（私信）或 `channel:<id>`。

-**回应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
+**反应通知模式：**`off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。

-**线程会话隔离：** `thread.historyScope` 是每线程（默认）或跨渠道共享。`thread.inheritParent` 会将父渠道转录复制到新线程。
+**线程会话隔离：**`thread.historyScope` 是按线程（默认）或跨渠道共享。`thread.inheritParent` 会将父渠道转录复制到新线程。

- Slack 原生流式传输以及 Slack assistant 风格的“正在输入...”线程状态需要回复线程目标。顶层私信默认保持在线程外，因此它们仍可通过 Slack 草稿发布并编辑预览来流式传输，而不是显示线程风格的原生流/状态预览。
- `typingReaction` 会在回复运行期间向传入的 Slack 消息添加一个临时回应，然后在完成时移除它。使用 Slack emoji 短代码，例如 `"hourglass_flowing_sand"`。
- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批人授权。与 Discord 使用相同架构：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。
+- Slack 原生流式传输以及 Slack 助手风格的 “is typing...” 线程状态需要回复线程目标。顶层私信默认保持在线程外，因此它们仍可通过 Slack 草稿发布并编辑预览进行流式传输，而不是显示线程风格的原生流/状态预览。
+- `typingReaction` 会在回复运行期间向传入的 Slack 消息添加临时反应，然后在完成时移除它。使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。
+- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批者授权。与 Discord 相同的 schema：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。

-| 操作组 | 默认值 | 备注                  |
+| 操作组 | 默认值 | 说明                  |
 | ------------ | ------- | ---------------------- |
-| reactions    | 已启用 | 回应 + 列出回应 |
+| reactions    | 已启用 | 反应 + 列出反应 |
 | messages     | 已启用 | 读取/发送/编辑/删除  |
 | pins         | 已启用 | 置顶/取消置顶/列出         |
 | memberInfo   | 已启用 | 成员信息            |
@ -496,7 +496,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链

 ### Mattermost

-在当前 OpenClaw 版本中，Mattermost 作为内置插件提供。较旧或自定义构建可以使用 `openclaw plugins install @openclaw/mattermost` 安装当前 npm 包。固定版本前，请查看 [npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost) 获取当前 dist-tags。
+Mattermost 在当前 OpenClaw 版本中作为内置插件提供。较旧或自定义构建可以使用 `openclaw plugins install @openclaw/mattermost` 安装当前 npm 包。固定版本前，请查看 [npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost) 了解当前 dist-tags。

 ```json5
 {
@ -526,18 +526,18 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链
 }
 ```

-聊天模式：`oncall`（在 @ 提及时回复，默认）、`onmessage`（每条消息）、`onchar`（以触发前缀开头的消息）。
+聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息）、`onchar`（以触发前缀开头的消息）。

 启用 Mattermost 原生命令时：

- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。
- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且可由 Mattermost 服务器访问。
- 原生斜杠命令回调使用 Mattermost 在注册斜杠命令期间返回的每命令令牌进行身份验证。如果注册失败或没有命令被激活，OpenClaw 会拒绝回调并返回 `Unauthorized: invalid command token.`
+- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），而不是完整 URL。
+- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器能够访问。
+- 原生斜杠回调使用 Mattermost 在斜杠命令注册期间返回的逐命令令牌进行身份验证。如果注册失败或没有激活任何命令，OpenClaw 会以 `Unauthorized: invalid command token.` 拒绝回调。
 - 对于私有/tailnet/内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。使用主机/域名值，而不是完整 URL。
 - `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。
 - `channels.mattermost.requireMention`：在渠道中回复前要求 `@mention`。
- `channels.mattermost.groups.<channelId>.requireMention`：按渠道的提及门控覆盖项（`"*"` 表示默认值）。
- 可选的 `channels.mattermost.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
+- `channels.mattermost.groups.<channelId>.requireMention`：逐渠道的提及门控覆盖（`"*"` 表示默认）。
+- 可选的 `channels.mattermost.defaultAccount` 在匹配已配置账户 ID 时覆盖默认账户选择。

 ### Signal

@ -558,11 +558,11 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链
 }
 ```

-**回应通知模式：**`off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
+**表情回应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。

- `channels.signal.account`：将渠道启动固定到特定的 Signal 账号身份。
+- `channels.signal.account`：将渠道启动固定到特定 Signal 账户身份。
 - `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。
- 可选的 `channels.signal.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
+- 可选的 `channels.signal.defaultAccount` 在匹配已配置账户 ID 时覆盖默认账户选择。

 ### BlueBubbles

@ -582,13 +582,13 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，在 `channels.blueb
 ```

 - 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。
- 可选的 `channels.bluebubbles.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
- 顶层 `bindings[]` 条目如果带有 `type: "acp"`，可以将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings)。
- 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles)。
+- 可选的 `channels.bluebubbles.defaultAccount` 在匹配已配置账户 ID 时覆盖默认账户选择。
+- 带有 `type: "acp"` 的顶层 `bindings[]` 条目可以将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles 句柄或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings)。
+- 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。

 ### iMessage

-OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。
+OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。

 ```json5
 {
@ -612,15 +612,15 @@ OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护
 }
 ```

- 可选的 `channels.imessage.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
+- 可选的 `channels.imessage.defaultAccount` 在匹配已配置账户 ID 时覆盖默认账户选择。

- 需要对 Messages DB 具备完全磁盘访问权限。
+- 需要对 Messages 数据库的完全磁盘访问权限。
 - 优先使用 `chat_id:<id>` 目标。使用 `imsg chats --limit 20` 列出聊天。
- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）用于通过 SCP 获取附件。
+- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。
 - `attachmentRoots` 和 `remoteAttachmentRoots` 会限制入站附件路径（默认：`/Users/*/Library/Messages/Attachments`）。
 - SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts`。
 - `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。
- 顶层 `bindings[]` 条目如果带有 `type: "acp"`，可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或明确的聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings)。
+- 带有 `type: "acp"` 的顶层 `bindings[]` 条目可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化句柄或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings)。

 <Accordion title="iMessage SSH 包装器示例">

@ -663,21 +663,21 @@ Matrix 由插件支持，并在 `channels.matrix` 下配置。
 }
 ```

- 令牌认证使用 `accessToken`；密码认证使用 `userId` + `password`。
- `channels.matrix.proxy` 通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可以用 `channels.matrix.accounts.<id>.proxy` 覆盖它。
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和这个网络选择加入项是相互独立的控制项。
- `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。
- `channels.matrix.autoJoin` 默认是 `off`，因此受邀房间和新的类似私信邀请会被忽略，直到你设置带有 `autoJoinAllowlist` 的 `autoJoin: "allowlist"`，或设置 `autoJoin: "always"`。
- `channels.matrix.execApprovals`：Matrix 原生执行审批投递和审批者授权。
-  - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批者时，执行审批会激活。
-  - `approvers`：允许批准执行请求的 Matrix 用户 ID（例如 `@owner:example.org`）。
-  - `agentFilter`：可选智能体 ID 允许列表。省略则转发所有智能体的审批。
-  - `sessionFilter`：可选会话键模式（子字符串或正则表达式）。
-  - `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。
-  - 按账号覆盖：`channels.matrix.accounts.<id>.execApprovals`。
- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组到会话中：`per-user`（默认）按路由到的对等方共享，而 `per-room` 会隔离每个私信房间。
+- 令牌身份验证使用 `accessToken`；密码身份验证使用 `userId` + `password`。
+- `channels.matrix.proxy` 通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账户可以使用 `channels.matrix.accounts.<id>.proxy` 覆盖它。
+- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和这个网络选择加入是独立控制项。
+- `channels.matrix.defaultAccount` 在多账户设置中选择首选账户。
+- `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并配置 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。
+- `channels.matrix.execApprovals`：Matrix 原生的 exec 批准投递和批准者授权。
+  - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析批准者时，exec 批准会激活。
+  - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。
+  - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的批准。
+  - `sessionFilter`：可选的会话键模式（子字符串或正则表达式）。
+  - `target`：发送批准提示的位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。
+  - 逐账户覆盖：`channels.matrix.accounts.<id>.execApprovals`。
+- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组为会话：`per-user`（默认）按路由的对端共享，而 `per-room` 会隔离每个私信房间。
 - Matrix Status 探测和实时目录查找使用与运行时流量相同的代理策略。
- 完整的 Matrix 配置、定向规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix)。
+- 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。

 ### Microsoft Teams

@ -697,7 +697,7 @@ Microsoft Teams 由插件支持，并在 `channels.msteams` 下配置。
 ```

 - 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。
- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/按渠道覆盖项）记录在 [Microsoft Teams](/zh-CN/channels/msteams)。
+- 完整的 Teams 配置（凭证、webhook、私信/群组策略、逐 team/逐渠道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。

 ### IRC

@ -723,12 +723,12 @@ IRC 由插件支持，并在 `channels.irc` 下配置。
 ```

 - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。
- 可选的 `channels.irc.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
- 完整的 IRC 渠道配置（主机/端口/TLS/渠道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc)。
+- 可选的 `channels.irc.defaultAccount` 在匹配已配置账户 ID 时覆盖默认账户选择。
+- 完整的 IRC 渠道配置（主机/端口/TLS/渠道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。

-### 多账号（所有渠道）
+### 多账户（所有渠道）

-每个渠道运行多个账号（每个账号都有自己的 `accountId`）：
+每个渠道运行多个账户（每个账户都有自己的 `accountId`）：

 ```json5
 {
@ -749,34 +749,34 @@ IRC 由插件支持，并在 `channels.irc` 下配置。
 }
 ```

- 省略 `accountId` 时使用 `default`（CLI + 路由）。
- 环境令牌只应用于**默认**账号。
- 基础渠道设置应用于所有账号，除非按账号覆盖。
- 使用 `bindings[].match.accountId` 将每个账号路由到不同的智能体。
- 如果你在仍使用单账号顶层渠道配置时，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先把账号作用域的顶层单账号值提升到渠道账号映射中，这样原账号会继续工作。大多数渠道会把它们移入 `channels.<channel>.accounts.default`；Matrix 则可以改为保留现有匹配的命名/默认目标。
- 现有的仅渠道绑定（没有 `accountId`）会继续匹配默认账号；账号作用域绑定仍是可选的。
- `openclaw doctor --fix` 还会修复混合形态，方法是把账号作用域的顶层单账号值移入为该渠道选择的已提升账号。大多数渠道使用 `accounts.default`；Matrix 则可以改为保留现有匹配的命名/默认目标。
+- 省略 `accountId` 时会使用 `default`（CLI + 路由）。
+- 环境变量令牌只应用于**默认**账户。
+- 基础渠道设置应用于所有账户，除非逐账户覆盖。
+- 使用 `bindings[].match.accountId` 将每个账户路由到不同智能体。
+- 如果你通过 `openclaw channels add`（或渠道新手引导）添加非默认账户，而当前仍使用单账户顶层渠道配置，OpenClaw 会先将账户作用域的顶层单账户值提升到渠道账户映射中，以便原账户继续工作。大多数渠道会将它们移入 `channels.<channel>.accounts.default`；Matrix 则可以改为保留现有匹配的命名/默认目标。
+- 现有的仅渠道绑定（无 `accountId`）继续匹配默认账户；账户作用域绑定仍为可选。
+- `openclaw doctor --fix` 也会通过将账户作用域的顶层单账户值移动到为该渠道选择的已提升账户来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 则可以改为保留现有匹配的命名/默认目标。

 ### 其他插件渠道

-许多插件渠道配置为 `channels.<id>`，并记录在它们专用的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。
-参见完整渠道索引：[Channels](/zh-CN/channels)。
+许多插件渠道配置为 `channels.<id>`，并记录在各自专用的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。
+请参阅完整渠道索引：[Channels](/zh-CN/channels)。

 ### 群聊提及门控

-群组消息默认**要求提及**（元数据提及或安全正则表达式模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。
+群组消息默认**要求提及**（元数据提及或安全的正则表达式模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。

-可见回复单独控制。群组/渠道房间默认使用 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍会处理该轮对话，但普通最终回复会保持私密，可见的房间输出需要 `message(action=send)`。只有当你想要旧版行为，也就是普通回复会发回房间时，才设置 `"automatic"`。若要把相同的仅工具可见回复行为也应用到直接聊天，请设置 `messages.visibleReplies: "message_tool"`；Codex harness 也将这种仅工具行为用作未设置时的直接聊天默认值。
+可见回复由单独设置控制。群组/渠道房间默认为 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍会处理该轮对话，但普通最终回复保持私密，房间中的可见输出需要 `message(action=send)`。仅当你想要普通回复发布回房间的旧版行为时，才设置 `"automatic"`。若要将同样的仅工具可见回复行为也应用到直接聊天，请设置 `messages.visibleReplies: "message_tool"`；Codex harness 也将这种仅工具行为用作其未设置时的直接聊天默认值。

-如果在当前工具策略下消息工具不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。`openclaw doctor` 会警告这种不匹配。
+如果消息工具在当前有效工具策略下不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。`openclaw doctor` 会警告此不匹配。

-文件保存后，Gateway 网关会热重载 `messages` 配置。只有在部署中禁用了文件监视或配置重载时才需要重启。
+Gateway 网关会在文件保存后热重载 `messages` 配置。只有在部署中禁用了文件监视或配置重载时才需要重启。

 **提及类型：**

- **元数据提及**：原生平台 @ 提及。在 WhatsApp 自聊模式中会被忽略。
+- **元数据提及**：原生平台 @ 提及。在 WhatsApp 自聊模式中忽略。
 - **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则表达式模式。无效模式和不安全的嵌套重复会被忽略。
- 只有在可以检测时（原生提及或至少一个模式），才会强制执行提及门控。
+- 仅在可以检测时（原生提及或至少一个模式）强制执行提及门控。

 ```json5
 {
@ -793,9 +793,9 @@ IRC 由插件支持，并在 `channels.irc` 下配置。
 }
 ```

-`messages.groupChat.historyLimit` 设置全局默认值。渠道可以用 `channels.<channel>.historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。
+`messages.groupChat.historyLimit` 设置全局默认值。渠道可以使用 `channels.<channel>.historyLimit`（或按账号）覆盖。设为 `0` 可禁用。

-`messages.visibleReplies` 是全局源回合默认值；`messages.groupChat.visibleReplies` 会为群组/渠道源回合覆盖它。当未设置 `messages.visibleReplies` 时，harness 可以提供自己的直接/源默认值；Codex harness 默认为 `message_tool`。渠道允许列表和提及门控仍会决定是否处理某个回合。
+`messages.visibleReplies` 是全局源轮次默认值；`messages.groupChat.visibleReplies` 会为群组/渠道源轮次覆盖它。当未设置 `messages.visibleReplies` 时，harness 可以提供自己的直接/源默认值；Codex harness 默认使用 `message_tool`。渠道允许列表和提及门控仍会决定是否处理某个轮次。

 #### 私信历史限制

@ -818,7 +818,7 @@ IRC 由插件支持，并在 `channels.irc` 下配置。

 #### 自聊模式

-在 `allowFrom` 中包含你自己的号码，以启用自聊模式（忽略原生 @ 提及，只响应文本模式）：
+在 `allowFrom` 中包含你自己的号码以启用自聊模式（忽略原生 @ 提及，仅响应文本模式）：

 ```json5
 {
@ -868,30 +868,30 @@ IRC 由插件支持，并在 `channels.irc` 下配置。

 <Accordion title="命令详情">

- 此区块配置命令界面。当前内置 + 捆绑命令目录见 [Slash Commands](/zh-CN/tools/slash-commands)。
- 本页是**配置键参考**，不是完整命令目录。由渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、设备配对 `/pair`、记忆 `/dreaming`、手机控制 `/phone` 和 Talk `/voice`，记录在各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。
+- 此块配置命令界面。有关当前内置 + 捆绑命令目录，请参阅 [Slash Commands](/zh-CN/tools/slash-commands)。
+- 此页面是**配置键参考**，不是完整命令目录。由渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、设备配对 `/pair`、记忆 `/dreaming`、手机控制 `/phone` 和 Talk `/voice`，记录在各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。
 - 文本命令必须是以 `/` 开头的**独立**消息。
- `native: "auto"` 会为 Discord/Telegram 启用原生命令，并让 Slack 保持关闭。
- `nativeSkills: "auto"` 会为 Discord/Telegram 启用原生 Skills 命令，并让 Slack 保持关闭。
+- `native: "auto"` 会为 Discord/Telegram 开启原生命令，并让 Slack 保持关闭。
+- `nativeSkills: "auto"` 会为 Discord/Telegram 开启原生 Skills 命令，并让 Slack 保持关闭。
 - 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。对于 Discord，`false` 会在启动期间跳过原生命令注册和清理。
- 用 `channels.<provider>.commands.nativeSkills` 按渠道覆盖原生 Skills 注册。
- `channels.telegram.customCommands` 会添加额外的 Telegram 机器人菜单项。
- `bash: true` 会为主机 shell 启用 `! <cmd>`。需要 `tools.elevated.enabled`，且发送者位于 `tools.elevated.allowFrom.<channel>` 中。
- `config: true` 会启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化的 `/config set|unset` 写入还需要 `operator.admin`；只读 `/config show` 仍可供普通写入范围的 operator 客户端使用。
+- 使用 `channels.<provider>.commands.nativeSkills` 按渠道覆盖原生 Skills 注册。
+- `channels.telegram.customCommands` 会添加额外的 Telegram Bot 菜单项。
+- `bash: true` 会为主机 shell 启用 `! <cmd>`。需要 `tools.elevated.enabled`，且发送者在 `tools.elevated.allowFrom.<channel>` 中。
+- `config: true` 会启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化 `/config set|unset` 写入还需要 `operator.admin`；只读 `/config show` 仍可供普通写入范围的 operator 客户端使用。
 - `mcp: true` 会为 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。
 - `plugins: true` 会为插件发现、安装以及启用/禁用控制启用 `/plugins`。
- `channels.<provider>.configWrites` 按渠道对配置变更进行门控（默认：true）。
- 对于多账号渠道，`channels.<provider>.accounts.<id>.configWrites` 也会对以该账号为目标的写入进行门控（例如 `/allowlist --config --account <id>` 或 `/config set channels.<provider>.accounts.<id>...`）。
+- `channels.<provider>.configWrites` 按渠道门控配置变更（默认值：true）。
+- 对于多账号渠道，`channels.<provider>.accounts.<id>.configWrites` 也会门控面向该账号的写入（例如 `/allowlist --config --account <id>` 或 `/config set channels.<provider>.accounts.<id>...`）。
 - `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。
- `ownerAllowFrom` 是仅所有者命令/工具的显式所有者允许列表。它独立于 `allowFrom`。
+- `ownerAllowFrom` 是 owner-only 命令/工具的显式所有者允许列表。它独立于 `allowFrom`。
 - `ownerDisplay: "hash"` 会在系统提示中哈希所有者 ID。设置 `ownerDisplaySecret` 可控制哈希。
- `allowFrom` 按提供商配置。设置后，它就是**唯一**授权来源（会忽略渠道允许列表/配对以及 `useAccessGroups`）。
+- `allowFrom` 按提供商设置。设置后，它是**唯一**授权来源（渠道允许列表/配对和 `useAccessGroups` 都会被忽略）。
 - 当未设置 `allowFrom` 时，`useAccessGroups: false` 允许命令绕过访问组策略。
 - 命令文档映射：
  - 内置 + 捆绑目录：[Slash Commands](/zh-CN/tools/slash-commands)
-  - 渠道特定命令界面：[渠道](/zh-CN/channels)
+  - 渠道特定命令界面：[Channels](/zh-CN/channels)
  - QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot)
-  - 配对命令：[配对](/zh-CN/channels/pairing)
+  - 配对命令：[Pairing](/zh-CN/channels/pairing)
  - LINE 卡片命令：[LINE](/zh-CN/channels/line)
  - 记忆 Dreaming：[Dreaming](/zh-CN/concepts/dreaming)

@ -901,6 +901,6 @@ IRC 由插件支持，并在 `channels.irc` 下配置。

 ## 相关内容

- [配置参考](/zh-CN/gateway/configuration-reference) — 顶级键
+- [配置参考](/zh-CN/gateway/configuration-reference) — 顶层键
 - [配置 — 智能体](/zh-CN/gateway/config-agents)
- [渠道概览](/zh-CN/channels)
+- [Channels 概览](/zh-CN/channels)