chore(i18n): refresh zh-CN translations

docs/zh-CN/channels/telegram.md

@@ -1,18 +1,18 @@
 ---
 read_when:
-    - 开发 Telegram 功能或网络钩子
+    - 处理 Telegram 功能或网络钩子
 summary: Telegram 机器人支持状态、能力和配置
 title: Telegram
 x-i18n:
-    generated_at: "2026-05-04T07:02:42Z"
+    generated_at: "2026-05-04T07:29:50Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 6ef1b019a6a0e261b33972b5edffaedd29310b1333d112bade2e79e9d56887c6
+    source_hash: 5711d53cf908a14024bc5a94f7d590bb4bcb6963a1d78049d7782871f4eae932
     source_path: channels/telegram.md
     workflow: 16
 ---
 
-可用于 bot 私信和群组的生产就绪方案，基于 grammY。长轮询是默认模式；webhook 模式可选。
+通过 grammY，可用于生产环境中的 bot 私信和群组。默认模式是长轮询；webhook 模式可选。
 
 <CardGroup cols={3}>
   <Card title="配对" icon="link" href="/zh-CN/channels/pairing">
@@ -30,7 +30,7 @@ x-i18n:
 
 <Steps>
   <Step title="在 BotFather 中创建 bot token">
-    打开 Telegram，并与 **@BotFather** 聊天（确认句柄确实是 `@BotFather`）。
+    打开 Telegram 并与 **@BotFather** 聊天（确认账号名正是 `@BotFather`）。
 
     运行 `/newbot`，按提示操作，并保存 token。
 
@@ -51,12 +51,12 @@ x-i18n:
 }
 ```
 
-    环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账户）。
-    Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置 token，然后启动 Gateway 网关。
+    环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账号）。
+    Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置 token，然后启动 gateway。
 
   </Step>
 
-  <Step title="启动 Gateway 网关并批准第一条私信">
+  <Step title="启动 gateway 并批准第一条私信">
 
 ```bash
 openclaw gateway
@@ -64,44 +64,44 @@ openclaw pairing list telegram
 openclaw pairing approve telegram <CODE>
 ```
 
-    配对码在 1 小时后过期。
+    配对码会在 1 小时后过期。
 
   </Step>
 
   <Step title="将 bot 添加到群组">
-    将 bot 添加到你的群组，然后设置 `channels.telegram.groups` 和 `groupPolicy`，使其与你的访问模型匹配。
+    将 bot 添加到你的群组，然后设置 `channels.telegram.groups` 和 `groupPolicy` 以匹配你的访问模型。
   </Step>
 </Steps>
 
 <Note>
-token 解析顺序会感知账户。实际使用中，配置值优先于环境变量回退，且 `TELEGRAM_BOT_TOKEN` 只适用于默认账户。
+Token 解析顺序可感知账号。实际使用中，配置值优先于环境变量回退，且 `TELEGRAM_BOT_TOKEN` 仅适用于默认账号。
 </Note>
 
 ## Telegram 侧设置
 
 <AccordionGroup>
   <Accordion title="隐私模式和群组可见性">
-    Telegram bot 默认启用**隐私模式**，这会限制它们能接收哪些群组消息。
+    Telegram bot 默认启用**隐私模式**，这会限制它们能收到哪些群组消息。
 
     如果 bot 必须看到所有群组消息，可以：
 
     - 通过 `/setprivacy` 禁用隐私模式，或
     - 将 bot 设为群组管理员。
 
-    切换隐私模式时，请在每个群组中移除并重新添加 bot，以便 Telegram 应用该变更。
+    切换隐私模式时，请在每个群组中移除并重新添加 bot，以便 Telegram 应用变更。
 
   </Accordion>
 
   <Accordion title="群组权限">
     管理员状态在 Telegram 群组设置中控制。
 
-    管理员 bot 会接收所有群组消息，这对始终在线的群组行为很有用。
+    管理员 bot 会收到所有群组消息，这对于始终在线的群组行为很有用。
 
   </Accordion>
 
   <Accordion title="有用的 BotFather 开关">
 
-    - `/setjoingroups` 用于允许/拒绝添加到群组
+    - `/setjoingroups` 用于允许/拒绝加入群组
     - `/setprivacy` 用于群组可见性行为
 
   </Accordion>
@@ -118,21 +118,21 @@ token 解析顺序会感知账户。实际使用中，配置值优先于环境
     - `open`（要求 `allowFrom` 包含 `"*"`）
     - `disabled`
 
-    `dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 会让任何找到或猜到 bot 用户名的 Telegram 账户都能指挥这个 bot。仅在有意公开且工具受到严格限制的 bot 中使用；单所有者 bot 应使用 `allowlist` 并配置数字用户 ID。
+    `dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 会允许任何找到或猜到 bot 用户名的 Telegram 账号向 bot 发送命令。仅应将其用于工具受到严格限制、刻意公开的 bot；单所有者 bot 应使用带数字用户 ID 的 `allowlist`。
 
     `channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。`telegram:` / `tg:` 前缀会被接受并规范化。
-    在多账户配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：账户级 `allowFrom: ["*"]` 条目不会让该账户公开，除非合并后的有效账户 allowlist 仍然包含显式通配符。
-    `dmPolicy: "allowlist"` 搭配空 `allowFrom` 会阻止所有私信，并会被配置验证拒绝。
-    设置只会要求提供数字用户 ID。
-    如果你已升级且配置中包含 `@username` allowlist 条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram bot token）。
-    如果你以前依赖配对存储 allowlist 文件，`openclaw doctor --fix` 可以在 allowlist 流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 尚无显式 ID 时）。
+    在多账号配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：账号级 `allowFrom: ["*"]` 条目不会使该账号公开，除非合并后的有效账号允许列表仍包含显式通配符。
+    `dmPolicy: "allowlist"` 搭配空的 `allowFrom` 会阻止所有私信，并会被配置验证拒绝。
+    设置流程只会请求数字用户 ID。
+    如果你已升级且配置中包含 `@username` 允许列表条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram bot token）。
+    如果你之前依赖配对存储允许列表文件，`openclaw doctor --fix` 可以在允许列表流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 尚无显式 ID 时）。
 
-    对于单所有者 bot，优先使用 `dmPolicy: "allowlist"` 并配置显式数字 `allowFrom` ID，使访问策略持久保存在配置中（而不是依赖以前的配对批准）。
+    对于单所有者 bot，建议使用 `dmPolicy: "allowlist"` 并配置显式数字 `allowFrom` ID，以便在配置中持久保存访问策略（而不是依赖之前的配对批准）。
 
-    常见混淆：私信配对批准并不意味着“这个发送者在所有地方都已授权”。
-    配对授予私信访问权限。如果尚不存在命令所有者，第一次批准的配对还会设置 `commands.ownerAllowFrom`，使仅所有者命令和执行批准拥有显式操作员账户。
-    群组发送者授权仍来自显式配置 allowlist。
-    如果你希望“我授权一次，私信和群组命令都可用”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:<your user id>`。
+    常见误解：私信配对批准并不意味着“此发送者在所有地方都已授权”。
+    配对授予私信访问权限。如果尚不存在命令所有者，第一次批准的配对也会设置 `commands.ownerAllowFrom`，使仅所有者命令和 exec 批准拥有显式操作员账号。
+    群组发送者授权仍来自显式配置允许列表。
+    如果你想要“我授权一次后，私信和群组命令都可用”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:<your user id>`。
 
     ### 查找你的 Telegram 用户 ID
 
@@ -152,14 +152,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
   </Tab>
 
-  <Tab title="群组策略和 allowlist">
+  <Tab title="群组策略和允许列表">
     两个控制项会共同生效：
 
     1. **允许哪些群组**（`channels.telegram.groups`）
        - 没有 `groups` 配置：
          - 使用 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查
          - 使用 `groupPolicy: "allowlist"`（默认）：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`）
-       - 已配置 `groups`：作为 allowlist 生效（显式 ID 或 `"*"`）
+       - 已配置 `groups`：作为允许列表生效（显式 ID 或 `"*"`）
 
     2. **群组中允许哪些发送者**（`channels.telegram.groupPolicy`）
        - `open`
@@ -169,12 +169,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     `groupAllowFrom` 用于群组发送者过滤。如果未设置，Telegram 会回退到 `allowFrom`。
     `groupAllowFrom` 条目应为数字 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被规范化）。
     不要将 Telegram 群组或超级群组聊天 ID 放入 `groupAllowFrom`。负数聊天 ID 应放在 `channels.telegram.groups` 下。
-    非数字条目会在发送者授权中被忽略。
-    安全边界（`2026.2.25+`）：群组发送者身份验证**不会**继承私信配对存储批准。
-    配对保持仅用于私信。对于群组，请设置 `groupAllowFrom` 或按群组/按话题设置 `allowFrom`。
+    非数字条目在发送者授权中会被忽略。
+    安全边界（`2026.2.25+`）：群组发送者认证**不会**继承私信配对存储批准。
+    配对仅适用于私信。对于群组，请设置 `groupAllowFrom` 或每群组/每话题的 `allowFrom`。
     如果未设置 `groupAllowFrom`，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。
     单所有者 bot 的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。
-    运行时注意事项：如果完全缺少 `channels.telegram`，运行时默认会故障关闭为 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。
+    运行时说明：如果完全缺少 `channels.telegram`，除非显式设置了 `channels.defaults.groupPolicy`，否则运行时默认以失败关闭方式使用 `groupPolicy="allowlist"`。
 
     示例：允许某个特定群组中的任何成员：
 
@@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 }
 ```
 
-    示例：仅允许某个特定群组内的特定用户：
+    示例：只允许某个特定群组中的特定用户：
 
 ```json5
 {
@@ -211,10 +211,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 ```
 
     <Warning>
-      常见错误：`groupAllowFrom` 不是 Telegram 群组 allowlist。
+      常见错误：`groupAllowFrom` 不是 Telegram 群组允许列表。
 
-      - 将类似 `-1001234567890` 的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。
-      - 当你想限制允许群组内哪些人可以触发 bot 时，将类似 `8734062810` 的 Telegram 用户 ID 放在 `groupAllowFrom` 下。
+      - 将像 `-1001234567890` 这样的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。
+      - 当你想限制允许群组中哪些人可以触发 bot 时，将像 `8734062810` 这样的 Telegram 用户 ID 放在 `groupAllowFrom` 下。
       - 仅当你希望允许群组中的任何成员都能与 bot 对话时，才使用 `groupAllowFrom: ["*"]`。
 
     </Warning>
@@ -222,12 +222,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
   </Tab>
 
   <Tab title="提及行为">
-    群组回复默认要求提及。
+    群组回复默认需要提及。
 
     提及可以来自：
 
     - 原生 `@botusername` 提及，或
-    - 以下位置中的提及模式：
+    - 以下位置的提及模式：
       - `agents.list[].groupChat.mentionPatterns`
       - `messages.groupChat.mentionPatterns`
 
@@ -255,7 +255,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     获取群组聊天 ID：
 
     - 将群组消息转发给 `@userinfobot` / `@getidsbot`
-    - 或从 `openclaw logs --follow` 中读取 `chat.id`
+    - 或从 `openclaw logs --follow` 读取 `chat.id`
     - 或检查 Bot API `getUpdates`
 
   </Tab>
@@ -263,14 +263,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
 ## 运行时行为
 
-- Telegram 由 Gateway 网关进程拥有。
-- 路由是确定性的：Telegram 入站会回复到 Telegram（模型不会选择渠道）。
-- 入站消息会规范化为共享渠道信封，并包含回复元数据和媒体占位符。
+- Telegram 由 gateway 进程拥有。
+- 路由是确定性的：Telegram 入站消息会回复到 Telegram（模型不会选择渠道）。
+- 入站消息会规范化为共享渠道信封，包含回复元数据和媒体占位符。
 - 群组会话按群组 ID 隔离。论坛话题会追加 `:topic:<threadId>` 以保持话题隔离。
-- 私信消息可以携带 `message_thread_id`；OpenClaw 会为回复保留线程 ID，但默认让私信保持扁平会话。当你确实想要私信话题会话隔离时，请配置 `channels.telegram.dm.threadReplies: "inbound"`、`channels.telegram.direct.<chatId>.threadReplies: "inbound"`、`requireTopic: true`，或匹配的话题配置。
-- 长轮询使用 grammY runner，并按聊天/线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。
-- 每个 Gateway 网关进程内部都会保护长轮询，因此同一时间只能有一个活跃轮询器使用一个 bot token。如果你仍然看到 `getUpdates` 409 冲突，很可能是另一个 OpenClaw Gateway 网关、脚本或外部轮询器正在使用同一个 token。
-- 长轮询看门狗默认会在 120 秒内没有完成 `getUpdates` 活性检查后触发重启。仅当你的部署在长时间运行工作期间仍然出现误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账户覆盖。
+- 私信消息可以携带 `message_thread_id`；OpenClaw 会保留线程 ID 用于回复，但默认保持私信使用扁平会话。当你有意需要私信话题会话隔离时，请配置 `channels.telegram.dm.threadReplies: "inbound"`、`channels.telegram.direct.<chatId>.threadReplies: "inbound"`、`requireTopic: true`，或匹配的话题配置。
+- 长轮询使用 grammY runner，并按每聊天/每线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。
+- 每个 gateway 进程内部都会保护长轮询，因此同一时间只有一个活跃 poller 可以使用一个 bot token。如果你仍然看到 `getUpdates` 409 冲突，很可能是另一个 OpenClaw gateway、脚本或外部 poller 正在使用同一个 token。
+- 默认情况下，长轮询看门狗重启会在 120 秒没有完成 `getUpdates` 存活检查后触发。只有当你的部署在长时间运行的工作期间仍看到误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账号覆盖。
 - Telegram Bot API 不支持已读回执（`sendReadReceipts` 不适用）。
 
 ## 功能参考
@@ -285,12 +285,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     要求：
 
     - `channels.telegram.streaming` 为 `off | partial | block | progress`（默认：`partial`）
-    - `progress` 会保留一条可编辑的状态草稿，并用工具进度更新它，直到最终送达
-    - `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑的预览消息（默认：预览流式传输启用时为 `true`）
-    - `streaming.preview.commandText` 控制这些工具进度行中的命令/执行细节：`raw`（默认，保留已发布行为）或 `status`（仅工具标签）
-    - 会检测旧版 `channels.telegram.streamMode` 和布尔型 `streaming` 值；运行 `openclaw doctor --fix` 可将它们迁移到 `channels.telegram.streaming.mode`
+    - `progress` 会保留一个可编辑的 Status 草稿，并使用工具进度更新它，直到最终送达
+    - `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑预览消息（默认：预览流式传输启用时为 `true`）
+    - `streaming.preview.commandText` 控制这些工具进度行中的命令/exec 详情：`raw`（默认，保留已发布行为）或 `status`（仅工具标签）
+    - 会检测旧版 `channels.telegram.streamMode` 和布尔型 `streaming` 值；运行 `openclaw doctor --fix` 将它们迁移到 `channels.telegram.streaming.mode`
 
-    工具进度预览更新是在工具运行时显示的短状态行，例如命令执行、文件读取、规划更新或补丁摘要。Telegram 默认保持启用这些更新，以匹配 `v2026.4.22` 及更高版本中已发布的 OpenClaw 行为。若要为回答文本保留已编辑预览，但隐藏工具进度行，请设置：
+    工具进度预览更新是在工具运行时显示的短 Status 行，例如命令执行、文件读取、规划更新或 patch 摘要。Telegram 默认启用这些更新，以匹配 `v2026.4.22` 及之后版本中已发布的 OpenClaw 行为。若要保留答案文本的已编辑预览，但隐藏工具进度行，请设置：
 
     ```json
     {
@@ -307,7 +307,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     }
     ```
 
-    若要保持工具进度可见但隐藏命令/执行文本，请设置：
+    若要保持工具进度可见但隐藏命令/exec 文本，请设置：
 
     ```json
     {
@@ -324,7 +324,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     }
     ```
 
-    对于进度草稿模式，请把相同的命令文本策略放在 `streaming.progress` 下：
+    对于进度草稿模式，将同样的命令文本策略放在 `streaming.progress` 下：
 
     ```json
     {
@@ -342,31 +342,31 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     }
     ```
 
-    仅当你希望只交付最终消息时，才使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，通用工具/进度闲聊会被抑制，而不是作为独立 Status 消息发送。审批提示、媒体载荷和错误仍会通过正常的最终交付路径路由。当你只想保留答案预览编辑，同时隐藏工具进度 Status 行时，请使用 `streaming.preview.toolProgress: false`。
+    仅在你需要只交付最终内容时使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，通用工具/进度杂讯会被抑制，而不是作为独立 Status 消息发送。审批提示、媒体载荷和错误仍会通过正常最终交付路径发送。当你只想保留回答预览编辑，同时隐藏工具进度 Status 行时，使用 `streaming.preview.toolProgress: false`。
 
     <Note>
-      Telegram 选中文本引用回复是例外。当 `replyToMode` 为 `"first"`、`"all"` 或 `"batched"`，且入站消息包含选中的引用文本时，OpenClaw 会通过 Telegram 原生引用回复路径发送最终答案，而不是编辑答案预览，因此 `streaming.preview.toolProgress` 无法为该轮显示简短 Status 行。没有选中文本引用的当前消息回复仍会保留预览流式传输。当工具进度可见性比原生引用回复更重要时，请设置 `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 的可见时间戳会反映完成时间，而不是预览创建时间
+    - 预览之后跟随可见的非预览输出：OpenClaw 会将完成后的回复作为新的最终消息发送，并清理较旧的预览，因此最终回答会出现在中间输出之后
+    - 超过约一分钟的预览：OpenClaw 会将完成后的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间
 
-    对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常的最终交付，然后清理预览消息。
+    对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常最终交付，然后清理预览消息。
 
-    预览流式传输独立于分块流式传输。当 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。
+    预览流式传输与分块流式传输相互独立。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。
 
     仅限 Telegram 的推理流：
 
-    - `/reasoning stream` 会在生成期间把推理发送到实时预览
-    - 推理预览会在最终交付后删除；当推理应保持可见时，请使用 `/reasoning on`
-    - 最终答案会在不包含推理文本的情况下发送
+    - `/reasoning stream` 会在生成期间将推理发送到实时预览
+    - 最终交付后会删除推理预览；当推理应保持可见时，使用 `/reasoning on`
+    - 最终回答发送时不包含推理文本
 
   </Accordion>
 
-  <Accordion title="格式化和 HTML 回退">
+  <Accordion title="Formatting and HTML fallback">
     出站文本使用 Telegram `parse_mode: "HTML"`。
 
     - 类 Markdown 文本会渲染为 Telegram 安全的 HTML。
@@ -377,7 +377,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
   </Accordion>
 
-  <Accordion title="原生命令和自定义命令">
+  <Accordion title="Native commands and custom commands">
     Telegram 命令菜单注册会在启动时通过 `setMyCommands` 处理。
 
     原生命令默认值：
@@ -401,24 +401,24 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
     规则：
 
-    - 名称会被规范化（移除开头的 `/`，转为小写）
+    - 名称会规范化（去掉前导 `/`，转为小写）
     - 有效模式：`a-z`、`0-9`、`_`，长度 `1..32`
     - 自定义命令不能覆盖原生命令
     - 冲突/重复项会被跳过并记录日志
 
-    说明：
+    注意：
 
     - 自定义命令只是菜单条目；它们不会自动实现行为
-    - 插件/skill 命令即使未显示在 Telegram 菜单中，在输入时仍可工作
+    - 插件/skill 命令即使未显示在 Telegram 菜单中，键入时仍可工作
 
-    如果禁用原生命令，内置命令会被移除。自定义/插件命令在配置后仍可注册。
+    如果禁用原生命令，内置命令会被移除。自定义/插件命令在配置后仍可能注册。
 
     常见设置失败：
 
-    - `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 被阻止。
+    - `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` 插件）
 
@@ -428,20 +428,20 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     2. 在 iOS 应用中粘贴代码
     3. `/pair pending` 列出待处理请求（包括角色/作用域）
     4. 批准请求：
-       - `/pair approve <requestId>` 用于明确批准
-       - 只有一个待处理请求时使用 `/pair approve`
-       - `/pair approve latest` 用于最近的请求
+       - `/pair approve <requestId>` 用于显式批准
+       - `/pair approve` 用于只有一个待处理请求的情况
+       - `/pair approve latest` 用于最新请求
 
-    设置代码携带一个短生命周期的 bootstrap 令牌。内置 bootstrap 移交会把主节点令牌保留在 `scopes: []`；任何移交的操作员令牌都会被限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write` 内。Bootstrap 作用域检查带有角色前缀，因此该操作员允许列表只满足操作员请求；非操作员角色仍需要其自身角色前缀下的作用域。
+    设置代码携带一个短期有效的引导令牌。内置引导交接会将主节点令牌保持在 `scopes: []`；任何交接的 operator 令牌仍被限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。引导作用域检查带有角色前缀，因此该 operator 允许列表只满足 operator 请求；非 operator 角色仍需要其自身角色前缀下的作用域。
 
-    如果设备使用变更后的认证详情（例如角色/作用域/公钥）重试，之前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。
+    如果设备使用变更后的认证详细信息重试（例如角色/作用域/公钥），之前的待处理请求会被取代，新的请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。
 
     更多详情：[配对](/zh-CN/channels/pairing#pair-via-telegram-recommended-for-ios)。
 
   </Accordion>
 
-  <Accordion title="内联按钮">
-    配置内联键盘作用域：
+  <Accordion title="Inline buttons">
+    配置内联键盘范围：
 
 ```json5
 {
@@ -455,7 +455,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 }
 ```
 
-    按账户覆盖：
+    单账号覆盖：
 
 ```json5
 {
@@ -473,7 +473,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 }
 ```
 
-    作用域：
+    范围：
 
     - `off`
     - `dm`
@@ -481,7 +481,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     - `all`
     - `allowlist`（默认）
 
-    旧版 `capabilities: ["inlineButtons"]` 映射到 `inlineButtons: "all"`。
+    旧版 `capabilities: ["inlineButtons"]` 会映射到 `inlineButtons: "all"`。
 
     消息操作示例：
 
@@ -506,16 +506,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
   </Accordion>
 
-  <Accordion title="面向智能体和自动化的 Telegram 消息操作">
+  <Accordion title="Telegram message actions for agents and automation">
     Telegram 工具操作包括：
 
-    - `sendMessage`（`to`、`content`，可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`）
+    - `sendMessage`（`to`、`content`、可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`）
     - `react`（`chatId`、`messageId`、`emoji`）
     - `deleteMessage`（`chatId`、`messageId`）
     - `editMessage`（`chatId`、`messageId`、`content`）
-    - `createForumTopic`（`chatId`、`name`，可选 `iconColor`、`iconCustomEmojiId`）
+    - `createForumTopic`（`chatId`、`name`、可选 `iconColor`、`iconCustomEmojiId`）
 
-    渠道消息操作会公开符合人体工学的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。
+    渠道消息操作会暴露符合人体工学的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。
 
     门控控制：
 
@@ -525,14 +525,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     - `channels.telegram.actions.sticker`（默认：禁用）
 
     注意：`edit` 和 `topic-create` 当前默认启用，并且没有单独的 `channels.telegram.actions.*` 开关。
-    运行时发送使用活动配置/密钥快照（启动/重新加载），因此操作路径不会在每次发送时执行临时 SecretRef 重新解析。
+    运行时发送使用活动配置/密钥快照（启动/重载），因此操作路径不会在每次发送时执行临时 SecretRef 重新解析。
 
-    反应移除语义：[/tools/reactions](/zh-CN/tools/reactions)
+    移除回应的语义：[/tools/reactions](/zh-CN/tools/reactions)
 
   </Accordion>
 
-  <Accordion title="回复线程标签">
-    Telegram 支持在生成的输出中使用显式回复线程标签：
+  <Accordion title="Reply threading tags">
+    Telegram 支持在生成输出中使用显式回复线程标签：
 
     - `[[reply_to_current]]` 回复触发消息
     - `[[reply_to:<id>]]` 回复特定 Telegram 消息 ID
@@ -543,29 +543,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_*]]` 标签仍会生效。
+    注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵循。
 
   </Accordion>
 
-  <Accordion title="论坛 topic 和线程行为">
+  <Accordion title="Forum topics and thread behavior">
     论坛超级群组：
 
-    - topic 会话键会附加 `:topic:<threadId>`
-    - 回复和正在输入状态会定向到 topic 线程
+    - topic 会话键会追加 `:topic:<threadId>`
+    - 回复和正在输入目标指向 topic 线程
     - topic 配置路径：
       `channels.telegram.groups.<chatId>.topics.<threadId>`
 
-    通用 topic（`threadId=1`）特例：
+    常规 topic（`threadId=1`）特殊情况：
 
-    - 发送消息会省略 `message_thread_id`（Telegram 会拒绝 `sendMessage(...thread_id=1)`）
+    - 消息发送会省略 `message_thread_id`（Telegram 会拒绝 `sendMessage(...thread_id=1)`）
     - 正在输入操作仍包含 `message_thread_id`
 
     Topic 继承：topic 条目会继承群组设置，除非被覆盖（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。
     `agentId` 仅限 topic，不会从群组默认值继承。
 
-    **按 topic 路由智能体**：每个 topic 都可以通过在 topic 配置中设置 `agentId` 路由到不同的智能体。这会给每个 topic 提供各自隔离的工作区、记忆和会话。示例：
+    **按 topic 的智能体路由**：每个 topic 都可以通过在 topic 配置中设置 `agentId` 路由到不同的智能体。这会让每个 topic 拥有各自隔离的工作区、记忆和会话。示例：
 
     ```json5
     {
@@ -587,23 +587,24 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
     然后每个 topic 都有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3`
 
-    **持久 ACP topic 绑定**：论坛 topic 可以通过顶层类型化 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 绑定固定 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**：`/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` 或匹配的话题配置时，它们才会使用感知线程的会话键。使用顶层 `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]]`，强制以语音便签发送
+    - 入站语音便签转写会在智能体上下文中被标记为机器生成、
+      不受信任的文本；提及检测仍使用原始
+      转写，因此受提及门控的语音消息会继续工作。
 
     消息操作示例：
 
@@ -619,7 +620,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
     ### 视频消息
 
-    Telegram 区分视频文件和视频留言。
+    Telegram 会区分视频文件和视频便签。
 
     消息操作示例：
 
@@ -633,14 +634,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 }
 ```
 
-    视频留言不支持说明文字；提供的消息文本会单独发送。
+    视频便签不支持字幕；提供的消息文本会单独发送。
 
     ### 贴纸
 
     入站贴纸处理：
 
     - 静态 WEBP：下载并处理（占位符 `<media:sticker>`）
-    - 动态 TGS：跳过
+    - 动画 TGS：跳过
     - 视频 WEBM：跳过
 
     贴纸上下文字段：
@@ -696,7 +697,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
   </Accordion>
 
   <Accordion title="回应通知">
-    Telegram 回应会作为 `message_reaction` 更新到达（与消息负载分离）。
+    Telegram 回应会作为 `message_reaction` 更新到达（与消息载荷分离）。
 
     启用后，OpenClaw 会将如下系统事件加入队列：
 
@@ -707,19 +708,19 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     - `channels.telegram.reactionNotifications`：`off | own | all`（默认：`own`）
     - `channels.telegram.reactionLevel`：`off | ack | minimal | extensive`（默认：`minimal`）
 
-    说明：
+    注意事项：
 
-    - `own` 表示仅用户对机器人已发送消息的回应（通过已发送消息缓存尽力而为）。
-    - 回应事件仍遵守 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权的发送者会被丢弃。
+    - `own` 表示仅用户对机器人发送消息的回应（通过已发送消息缓存尽力实现）。
+    - 回应事件仍遵循 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。
     - Telegram 不会在回应更新中提供线程 ID。
       - 非论坛群组路由到群组聊天会话
-      - 论坛群组路由到群组通用话题会话（`:topic:1`），而不是精确的来源话题
+      - 论坛群组路由到群组通用 topic 会话（`:topic:1`），而不是确切的来源 topic
 
     轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。
 
   </Accordion>
 
-  <Accordion title="确认回应">
+  <Accordion title="ACK 回应">
     `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认 emoji。
 
     解析顺序：
@@ -729,10 +730,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     - `messages.ackReaction`
     - 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 "👀"）
 
-    说明：
+    注意事项：
 
-    - Telegram 期望 unicode emoji（例如 "👀"）。
-    - 使用 `""` 可为某个渠道或账号禁用回应。
+    - Telegram 期望使用 unicode emoji（例如 "👀"）。
+    - 使用 `""` 可为某个渠道或账户禁用回应。
 
   </Accordion>
 
@@ -759,38 +760,39 @@ 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 密钥令牌和 JSON 正文，然后再向 Telegram 返回 `200`。
-    随后 OpenClaw 会通过与长轮询相同的按聊天/按话题机器人通道异步处理该更新，因此较慢的智能体轮次不会阻塞 Telegram 的投递 ACK。
+    webhook 模式会先验证请求守卫、Telegram secret token 和 JSON 正文，然后才向 Telegram 返回 `200`。
+    随后 OpenClaw 会通过与长轮询相同的每聊天/每 topic 机器人通道异步处理该更新，因此较慢的智能体轮次不会阻塞 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）控制 Telegram 相册/媒体组在 OpenClaw 将其作为一条入站消息派发前缓冲多久。如果相册片段到达较晚，请增大它；如果要减少相册回复延迟，请减小它。
-    - `channels.telegram.timeoutSeconds` 覆盖 Telegram API 客户端超时（如果未设置，则使用 grammY 默认值）。机器人客户端会将低于 60 秒出站文本/输入状态请求防护的配置值钳制住，因此 grammY 不会在 OpenClaw 的传输防护和回退运行之前中止可见回复投递。长轮询仍使用 45 秒的 `getUpdates` 请求防护，因此空闲轮询不会被无限期遗弃。
-    - `channels.telegram.pollingStallThresholdMs` 默认值为 `120000`；仅在轮询停滞重启出现误报时，在 `30000` 到 `600000` 之间调整。
+    - `channels.telegram.mediaGroupFlushMs`（默认 500）控制 Telegram 相册/媒体组在 OpenClaw 将其作为一条入站消息分发前的缓冲时长。如果相册部分到达较晚，请增大该值；如果要降低相册回复延迟，请减小该值。
+    - `channels.telegram.timeoutSeconds` 覆盖 Telegram API 客户端超时（如果未设置，则使用 grammY 默认值）。机器人客户端会将配置值限制在低于 60 秒出站文本/typing 请求守卫的范围内，避免 grammY 在 OpenClaw 的传输守卫和回退运行前中止可见回复投递。长轮询仍使用 45 秒的 `getUpdates` 请求守卫，因此空闲轮询不会被无限期遗弃。
+    - `channels.telegram.pollingStallThresholdMs` 默认值为 `120000`；仅在误报轮询停滞重启时，在 `30000` 到 `600000` 之间调节。
     - 群组上下文历史使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（默认 50）；`0` 表示禁用。
-    - 回复/引用/转发的补充上下文目前会按收到的形式传递。
-    - Telegram allowlist 主要控制谁可以触发智能体，而不是完整的补充上下文脱敏边界。
-    - 私信历史控制项：
+    - 回复/引用/转发的补充上下文目前按接收内容传递。
+    - Telegram 允许列表主要用于控制谁可以触发智能体，而不是完整的补充上下文删减边界。
+    - 私信历史控制：
       - `channels.telegram.dmHistoryLimit`
       - `channels.telegram.dms["<user_id>"].historyLimit`
-    - `channels.telegram.retry` 配置适用于 Telegram 发送助手（CLI/工具/操作）中的可恢复出站 API 错误。入站最终回复投递也会对 Telegram 预连接失败使用有界的安全发送重试，但不会重试可能重复可见消息的模糊发送后网络信封。
+    - `channels.telegram.retry` 配置适用于 Telegram 发送辅助函数（CLI/工具/操作），用于可恢复的出站 API 错误。入站最终回复投递也会对 Telegram 预连接失败使用有界安全发送重试，但不会重试可能造成可见消息重复的模糊发送后网络信封。
 
-    CLI 发送目标可以是数字聊天 ID 或用户名：
+    CLI 和消息工具发送目标可以是数字聊天 ID、用户名或论坛 topic 目标：
 
 ```bash
 openclaw message send --channel telegram --target 123456789 --message "hi"
 openclaw message send --channel telegram --target @name --message "hi"
+openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"
 ```
 
-    Telegram 投票使用 `openclaw message poll`，并支持论坛话题：
+    Telegram 投票使用 `openclaw message poll`，并支持论坛 topic：
 
 ```bash
 openclaw message poll --channel telegram --target 123456789 \
@@ -800,57 +802,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:` 目标）
+    - 用于论坛 topic 的 `--thread-id`（或使用 `:topic:` 目标）
 
     Telegram 发送还支持：
 
-    - 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带 `buttons` 块的 `--presentation` 创建内联键盘
-    - 在机器人可以固定该聊天中的消息时，使用 `--pin` 或 `--delivery '{"pin":true}'` 请求固定投递
-    - 使用 `--force-document` 将出站图片和 GIF 作为文档发送，而不是压缩照片或动态媒体上传
+    - 当 `channels.telegram.capabilities.inlineButtons` 允许时，将 `--presentation` 与 `buttons` 块配合用于内联键盘
+    - 当机器人可以在该聊天中置顶时，使用 `--pin` 或 `--delivery '{"pin":true}'` 请求置顶投递
+    - 使用 `--force-document` 将出站图片和 GIF 作为文档发送，而不是压缩照片或动画媒体上传
 
     操作门控：
 
-    - `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 中的 exec 批准">
+    Telegram 支持在批准者私信中进行 exec 批准，也可以选择在来源聊天或 topic 中发布提示。批准者必须是数字 Telegram 用户 ID。
 
     配置路径：
 
-    - `channels.telegram.execApprovals.enabled`（至少有一个审批者可解析时自动启用）
-    - `channels.telegram.execApprovals.approvers`（回退到来自 `commands.ownerAllowFrom` 的数字所有者 ID）
+    - `channels.telegram.execApprovals.enabled`（当至少一个批准者可解析时自动启用）
+    - `channels.telegram.execApprovals.approvers`（回退到 `commands.ownerAllowFrom` 中的数字 owner 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` 控制谁可以与机器人对话，以及机器人把普通回复发送到哪里。它们不会让某人成为 exec 批准者。当尚无命令 owner 时，第一个已批准的私信配对会引导初始化 `commands.ownerAllowFrom`，因此单 owner 设置仍可工作，而无需在 `execApprovals.approvers` 下重复 ID。
 
-    渠道投递会在聊天中显示命令文本；仅在可信的群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。exec 审批默认在 30 分钟后过期。
+    渠道投递会在聊天中显示命令文本；仅在受信任的群组/topic 中启用 `channel` 或 `both`。当提示落在论坛 topic 中时，OpenClaw 会为批准提示和后续消息保留该 topic。exec 批准默认在 30 分钟后过期。
 
-    内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。带有 `plugin:` 前缀的审批 ID 会通过插件审批解析；其他 ID 会先通过 exec 审批解析。
+    内联批准按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的批准 ID 会通过插件批准解析；其他 ID 会先通过 exec 批准解析。
 
-    参见 [Exec 审批](/zh-CN/tools/exec-approvals)。
+    请参阅 [exec 批准](/zh-CN/tools/exec-approvals)。
 
   </Accordion>
 </AccordionGroup>
 
 ## 错误回复控制
 
-当智能体遇到投递错误或提供商错误时，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 配置键相同）。
+支持按账户、按群组和按 topic 覆盖（继承方式与其他 Telegram 配置键相同）。
 
 ```json5
 {
@@ -871,20 +873,20 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
 ## 故障排除
 
 <AccordionGroup>
-  <Accordion title="机器人不响应非提及群组消息">
+  <Accordion title="机器人不响应未提及它的群组消息">
 
     - 如果 `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` 以了解跳过原因
 
@@ -894,32 +896,32 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
 
     - 授权你的发送者身份（配对和/或数字 `allowFrom`）
     - 即使群组策略为 `open`，命令授权仍然适用
-    - 出现带有 `BOT_COMMANDS_TOO_MUCH` 的 `setMyCommands failed` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生命令菜单
-    - `deleteMyCommands` / `setMyCommands` 启动调用和 `sendChatAction` 输入状态调用都有边界，并会在请求超时时通过 Telegram 的传输回退重试一次。持续的网络/fetch 错误通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性存在问题
+    - `setMyCommands failed` 携带 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生菜单
+    - `deleteMyCommands` / `setMyCommands` 启动调用和 `sendChatAction` 输入状态调用都有边界限制，并会在请求超时时通过 Telegram 的传输回退重试一次。持续的网络/抓取错误通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性存在问题
 
   </Accordion>
 
-  <Accordion title="启动报告未授权 token">
+  <Accordion title="启动报告未授权令牌">
 
-    - `getMe returned 401` 是已配置机器人 token 的 Telegram 认证失败。
-    - 在 BotFather 中重新复制或重新生成机器人 token，然后为默认账户更新 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts.<id>.botToken` 或 `TELEGRAM_BOT_TOKEN`。
-    - 启动期间的 `deleteWebhook 401 Unauthorized` 也是认证失败；将其视为“没有 webhook 存在”只会把同一个错误 token 失败推迟到后续 API 调用。
+    - `getMe returned 401` 是已配置机器人令牌的 Telegram 身份验证失败。
+    - 在 BotFather 中重新复制或重新生成机器人令牌，然后更新默认账户的 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts.<id>.botToken` 或 `TELEGRAM_BOT_TOKEN`。
+    - 启动期间出现 `deleteWebhook 401 Unauthorized` 也是身份验证失败；将其视为“没有 webhook 存在”只会把相同的错误令牌失败推迟到后续 API 调用。
 
   </Accordion>
 
   <Accordion title="轮询或网络不稳定">
 
-    - 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 socket 按较短的固定周期回收，请检查是否设置了较低的 `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_PROXY_URL` 配置了 OpenClaw 托管代理，且没有标准代理环境变量，Telegram 也会将该 URL 用于 Bot API 传输。
+    - Node 22+ + 自定义 fetch/proxy 在 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_PROXY_URL` 配置了 OpenClaw 托管代理，并且不存在标准代理环境，Telegram 也会将该 URL 用于 Bot API 传输。
     - 在直接出站/TLS 不稳定的 VPS 主机上，通过 `channels.telegram.proxy` 路由 Telegram API 调用：
 
 ```yaml
@@ -928,8 +930,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:
@@ -938,7 +940,7 @@ channels:
       autoSelectFamily: false
 ```
 
-    - 默认情况下，Telegram 媒体下载已经允许 RFC 2544 基准测试范围地址（`198.18.0.0/15`）。如果可信的假 IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写为其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过：
+    - 默认已允许 Telegram 媒体下载使用 RFC 2544 基准测试范围应答（`198.18.0.0/15`）。如果可信的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写为其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过：
 
 ```yaml
 channels:
@@ -947,20 +949,22 @@ 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 假 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
@@ -978,35 +982,35 @@ dig +short api.telegram.org AAAA
 
 <Accordion title="高信号 Telegram 字段">
 
-- 启动/认证：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向普通文件；符号链接会被拒绝）
+- 启动/身份验证：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向常规文件；符号链接会被拒绝）
 - 访问控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`、`groups.*.topics.*`、顶层 `bindings[]`（`type: "acp"`）
-- exec 审批：`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`
+- 格式/投递：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix`
 - 媒体/网络：`mediaMaxMb`、`mediaGroupFlushMs`、`timeoutSeconds`、`pollingStallThresholdMs`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy`
-- 自定义 API 根地址：`apiRoot`（仅 Bot API 根地址；不要包含 `/bot<TOKEN>`）
+- 自定义 API 根：`apiRoot`（仅 Bot API 根；不要包含 `/bot<TOKEN>`）
 - webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost`
 - 操作/能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
-- reactions：`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">
-    群组和主题允许列表行为。
+    群组和话题允许列表行为。
   </Card>
   <Card title="渠道路由" icon="route" href="/zh-CN/channels/channel-routing">
     将入站消息路由到智能体。
@@ -1015,7 +1019,7 @@ dig +short api.telegram.org AAAA
     威胁模型和加固。
   </Card>
   <Card title="多智能体路由" icon="sitemap" href="/zh-CN/concepts/multi-agent">
-    将群组和主题映射到智能体。
+    将群组和话题映射到智能体。
   </Card>
   <Card title="故障排除" icon="wrench" href="/zh-CN/channels/troubleshooting">
     跨渠道诊断。

docs/zh-CN/cli/message.md

@@ -5,10 +5,10 @@ read_when:
 summary: '`openclaw message` 的 CLI 参考（发送 + 渠道操作）'
 title: 消息
 x-i18n:
-    generated_at: "2026-05-02T20:13:39Z"
+    generated_at: "2026-05-04T07:29:53Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 6b73a50da34838f80ad5d0d266f5c66f95436f8535e6312296ae022918b1ab55
+    source_hash: 9ef57d33c93206a61a6d044667de4faf6340f7d8cc324300f235e838ee3b7ff1
     source_path: cli/message.md
     workflow: 16
 ---
@@ -26,28 +26,28 @@ openclaw message <subcommand> [flags]
 
 渠道选择：
 
-- 如果配置了多个渠道，则必须提供 `--channel`。
+- 如果配置了多个渠道，则必须使用 `--channel`。
 - 如果只配置了一个渠道，它会成为默认渠道。
 - 值：`discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp`（Mattermost 需要插件）
-- 当存在 `--channel` 或带渠道前缀的目标时，`openclaw message` 会将所选渠道解析到拥有它的插件；否则，它会加载已配置的渠道插件来推断默认渠道。
+- 当存在 `--channel` 或带渠道前缀的目标时，`openclaw message` 会将所选渠道解析为拥有它的插件；否则，它会加载已配置的渠道插件以推断默认渠道。
 
 目标格式（`--target`）：
 
 - WhatsApp：E.164、群组 JID，或 WhatsApp Channel/Newsletter JID（`...@newsletter`）
-- Telegram：聊天 id 或 `@username`
-- Discord：`channel:<id>` 或 `user:<id>`（或 `<@id>` 提及；原始数字 id 会被视为频道）
+- Telegram：聊天 ID、`@username`，或论坛话题目标（`-1001234567890:topic:42`，或 `--thread-id 42`）
+- Discord：`channel:<id>` 或 `user:<id>`（或 `<@id>` 提及；原始数字 ID 会被视为渠道）
 - Google Chat：`spaces/<spaceId>` 或 `users/<userId>`
-- Slack：`channel:<id>` 或 `user:<id>`（接受原始频道 id）
-- Mattermost（插件）：`channel:<id>`、`user:<id>` 或 `@username`（裸 id 会被视为频道）
+- Slack：`channel:<id>` 或 `user:<id>`（接受原始渠道 ID）
+- Mattermost（插件）：`channel:<id>`、`user:<id>`，或 `@username`（裸 ID 会被视为渠道）
 - Signal：`+E.164`、`group:<id>`、`signal:+E.164`、`signal:group:<id>`，或 `username:<name>`/`u:<name>`
-- iMessage：handle、`chat_id:<id>`、`chat_guid:<guid>`，或 `chat_identifier:<id>`
+- iMessage：句柄、`chat_id:<id>`、`chat_guid:<guid>`，或 `chat_identifier:<id>`
 - Matrix：`@user:server`、`!room:server`，或 `#alias:server`
-- Microsoft Teams：会话 id（`19:...@thread.tacv2`）或 `conversation:<id>` 或 `user:<aad-object-id>`
+- Microsoft Teams：会话 ID（`19:...@thread.tacv2`）或 `conversation:<id>` 或 `user:<aad-object-id>`
 
 名称查找：
 
-- 对于支持的提供商（Discord/Slack 等），像 `Help` 或 `#help` 这样的渠道名称会通过目录缓存解析。
-- 缓存未命中时，如果提供商支持，OpenClaw 会尝试实时目录查找。
+- 对于受支持的提供商（Discord/Slack 等），`Help` 或 `#help` 这样的渠道名称会通过目录缓存解析。
+- 如果缓存未命中，且提供商支持，OpenClaw 会尝试实时目录查找。
 
 ## 常用标志
 
@@ -61,13 +61,13 @@ openclaw message <subcommand> [flags]
 
 ## SecretRef 行为
 
-- `openclaw message` 会在运行所选操作之前解析受支持渠道的 SecretRefs。
-- 尽可能将解析范围限定到活动操作目标：
-  - 设置了 `--channel` 时按渠道限定（或从 `discord:...` 这类带前缀目标推断）
-  - 设置了 `--account` 时按账号限定（渠道全局项 + 所选账号表面）
-  - 省略 `--account` 时，OpenClaw 不会强制使用 `default` 账号 SecretRef 作用域
-- 不相关渠道上未解析的 SecretRefs 不会阻止有目标的消息操作。
-- 如果所选渠道/账号的 SecretRef 未解析，该命令会针对该操作关闭失败。
+- `openclaw message` 会在运行所选操作之前解析受支持渠道的 SecretRef。
+- 可行时，解析范围限定为当前操作目标：
+  - 当设置了 `--channel` 时按渠道限定范围（或从 `discord:...` 这样的前缀目标推断）
+  - 当设置了 `--account` 时按账户限定范围（渠道全局配置 + 所选账户相关表面）
+  - 省略 `--account` 时，OpenClaw 不会强制使用 `default` 账户 SecretRef 范围
+- 无关渠道上未解析的 SecretRef 不会阻止定向消息操作。
+- 如果所选渠道/账户的 SecretRef 未解析，该命令会对该操作失败关闭。
 
 ## 操作
 
@@ -77,10 +77,10 @@ openclaw message <subcommand> [flags]
   - 渠道：WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost（插件）/Signal/iMessage/Matrix/Microsoft Teams
   - 必需：`--target`，以及 `--message`、`--media` 或 `--presentation`
   - 可选：`--media`、`--presentation`、`--delivery`、`--pin`、`--reply-to`、`--thread-id`、`--gif-playback`、`--force-document`、`--silent`
-  - 共享 presentation 载荷：`--presentation` 发送语义块（`text`、`context`、`divider`、`buttons`、`select`），核心会通过所选渠道声明的能力进行渲染。参见 [Message Presentation](/zh-CN/plugins/message-presentation)。
-  - 通用投递偏好：`--delivery` 接受诸如 `{ "pin": true }` 的投递提示；当渠道支持时，`--pin` 是固定投递的简写。
+  - 共享呈现载荷：`--presentation` 发送语义块（`text`、`context`、`divider`、`buttons`、`select`），核心会通过所选渠道声明的能力进行渲染。参见 [消息呈现](/zh-CN/plugins/message-presentation)。
+  - 通用投递偏好：`--delivery` 接受投递提示，例如 `{ "pin": true }`；当渠道支持置顶投递时，`--pin` 是它的简写。
   - 仅 Telegram：`--force-document`（将图片和 GIF 作为文档发送，以避免 Telegram 压缩）
-  - 仅 Telegram：`--thread-id`（论坛主题 id）
+  - 仅 Telegram：`--thread-id`（论坛话题 ID）
   - 仅 Slack：`--thread-id`（线程时间戳；`--reply-to` 使用同一字段）
   - Telegram + Discord：`--silent`
   - 仅 WhatsApp：`--gif-playback`；WhatsApp Channels/Newsletters 使用其原生 `@newsletter` JID 寻址。
@@ -96,7 +96,7 @@ openclaw message <subcommand> [flags]
   - 渠道：Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/Matrix
   - 必需：`--message-id`、`--target`
   - 可选：`--emoji`、`--remove`、`--participant`、`--from-me`、`--target-author`、`--target-author-uuid`
-  - 注意：`--remove` 需要 `--emoji`（省略 `--emoji` 可在支持的情况下清除自己的反应；参见 /tools/reactions）
+  - 注意：`--remove` 需要 `--emoji`（省略 `--emoji` 可在受支持位置清除自己的反应；参见 /tools/reactions）
   - 仅 WhatsApp：`--participant`、`--from-me`
   - Signal 群组反应：需要 `--target-author` 或 `--target-author-uuid`
 
@@ -124,14 +124,14 @@ openclaw message <subcommand> [flags]
   - 渠道：Discord/Slack/Matrix
   - 必需：`--message-id`、`--target`
 
-- `pins`（列出）
+- `pins`（列表）
   - 渠道：Discord/Slack/Matrix
   - 必需：`--target`
 
 - `permissions`
   - 渠道：Discord/Matrix
   - 必需：`--target`
-  - 仅 Matrix：当 Matrix 加密已启用且允许验证操作时可用
+  - 仅 Matrix：在启用 Matrix 加密且允许验证操作时可用
 
 - `search`
   - 渠道：Discord
@@ -142,7 +142,7 @@ openclaw message <subcommand> [flags]
 
 - `thread create`
   - 渠道：Discord
-  - 必需：`--thread-name`、`--target`（频道 id）
+  - 必需：`--thread-name`、`--target`（渠道 ID）
   - 可选：`--message-id`、`--message`、`--auto-archive-min`
 
 - `thread list`
@@ -152,14 +152,14 @@ openclaw message <subcommand> [flags]
 
 - `thread reply`
   - 渠道：Discord
-  - 必需：`--target`（线程 id）、`--message`
+  - 必需：`--target`（线程 ID）、`--message`
   - 可选：`--media`、`--reply-to`
 
 ### 表情符号
 
 - `emoji list`
   - Discord：`--guild-id`
-  - Slack：没有额外标志
+  - Slack：无额外标志
 
 - `emoji upload`
   - 渠道：Discord
@@ -177,7 +177,7 @@ openclaw message <subcommand> [flags]
   - 渠道：Discord
   - 必需：`--guild-id`、`--sticker-name`、`--sticker-desc`、`--sticker-tags`、`--media`
 
-### 角色 / 频道 / 成员 / 语音
+### 角色 / 渠道 / 成员 / 语音
 
 - `role info`（Discord）：`--guild-id`
 - `role add` / `role remove`（Discord）：`--guild-id`、`--user-id`、`--role-id`
@@ -192,9 +192,9 @@ openclaw message <subcommand> [flags]
 - `event create`（Discord）：`--guild-id`、`--event-name`、`--start-time`
   - 可选：`--end-time`、`--desc`、`--channel-id`、`--location`、`--event-type`
 
-### 内容治理（Discord）
+### 管理（Discord）
 
-- `timeout`：`--guild-id`、`--user-id`（可选 `--duration-min` 或 `--until`；两者都省略则清除 timeout）
+- `timeout`：`--guild-id`、`--user-id`（可选 `--duration-min` 或 `--until`；两者都省略可清除超时）
 - `kick`：`--guild-id`、`--user-id`（+ `--reason`）
 - `ban`：`--guild-id`、`--user-id`（+ `--delete-days`、`--reason`）
   - `timeout` 也支持 `--reason`
@@ -202,7 +202,7 @@ openclaw message <subcommand> [flags]
 ### 广播
 
 - `broadcast`
-  - 渠道：任何已配置渠道；使用 `--channel all` 以面向所有提供商
+  - 渠道：任何已配置的渠道；使用 `--channel all` 以面向所有提供商
   - 必需：`--targets <target...>`
   - 可选：`--message`、`--media`、`--dry-run`
 
@@ -223,9 +223,9 @@ openclaw message send --channel discord \
   --presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Approve","value":"approve","style":"success"},{"label":"Decline","value":"decline","style":"danger"}]}]}'
 ```
 
-核心会根据渠道能力，将同一个 `presentation` 载荷渲染为 Discord 组件、Slack 块、Telegram 行内按钮、Mattermost props，或 Teams/Feishu 卡片。完整契约和回退规则请参见 [Message Presentation](/zh-CN/plugins/message-presentation)。
+核心会根据渠道能力，将相同的 `presentation` 载荷渲染为 Discord 组件、Slack 块、Telegram 内联按钮、Mattermost props，或 Teams/Feishu 卡片。完整契约和回退规则见 [消息呈现](/zh-CN/plugins/message-presentation)。
 
-发送更丰富的 presentation 载荷：
+发送更丰富的呈现载荷：
 
 ```bash
 openclaw message send --channel googlechat --target spaces/AAA... \
@@ -269,14 +269,14 @@ openclaw message poll --channel msteams \
   --poll-option Pizza --poll-option Sushi
 ```
 
-在 Slack 中添加反应：
+在 Slack 中反应：
 
 ```
 openclaw message react --channel slack \
   --target C123 --message-id 456 --emoji "✅"
 ```
 
-在 Signal 群组中添加反应：
+在 Signal 群组中反应：
 
 ```
 openclaw message react --channel signal \
@@ -284,14 +284,14 @@ openclaw message react --channel signal \
   --emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
 ```
 
-通过通用 presentation 发送 Telegram 行内按钮：
+通过通用呈现发送 Telegram 内联按钮：
 
 ```
 openclaw message send --channel telegram --target @mychat --message "Choose:" \
   --presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Yes","value":"cmd:yes"},{"label":"No","value":"cmd:no"}]}]}'
 ```
 
-通过通用 presentation 发送 Teams 卡片：
+通过通用呈现发送 Teams 卡片：
 
 ```bash
 openclaw message send --channel msteams \