chore(i18n): refresh zh-CN translations

2026-04-29 12:08:05 +00:00 · 2026-04-29 12:08:05 +00:00 · becbf6ea16
commit becbf6ea16
parent d15ff62a13
2 changed files with 459 additions and 456 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
@ -4,22 +4,22 @@ read_when:
 summary: Telegram 机器人支持状态、能力和配置
 title: Telegram
 x-i18n:
-    generated_at: "2026-04-29T11:47:17Z"
+    generated_at: "2026-04-29T12:05:10Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 8bae9845e95669fe21d75694d81172bfb4fc6329b67ef232e7fe4cbf67b87958
+    source_hash: 8db902132bd9b93deda2f951353dadc6ea2d4d76a59919cf1fb90f7e75615556
    source_path: channels/telegram.md
    workflow: 16
 ---

-可用于生产环境，通过 grammY 支持机器人私信和群组。默认模式是长轮询；Webhook 模式可选。
+可用于生产环境的机器人私信和群组，基于 grammY。默认模式是长轮询；webhook 模式可选。

 <CardGroup cols={3}>
  <Card title="配对" icon="link" href="/zh-CN/channels/pairing">
    Telegram 的默认私信策略是配对。
  </Card>
  <Card title="渠道故障排除" icon="wrench" href="/zh-CN/channels/troubleshooting">
-    跨渠道诊断和修复手册。
+    跨渠道诊断和修复操作手册。
  </Card>
  <Card title="Gateway 网关配置" icon="settings" href="/zh-CN/gateway/configuration">
    完整的渠道配置模式和示例。
@ -30,9 +30,9 @@ x-i18n:

 <Steps>
  <Step title="在 BotFather 中创建机器人令牌">
-    打开 Telegram 并与 **@BotFather** 聊天（确认账号名正好是 `@BotFather`）。
+    打开 Telegram 并与 **@BotFather** 聊天（确认账号名正是 `@BotFather`）。

-    运行 `/newbot`，按照提示操作，并保存令牌。
+    运行 `/newbot`，按提示操作，并保存令牌。

  </Step>

@ -51,12 +51,12 @@ x-i18n:
 }
 ```

-    环境回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账号）。
-    Telegram **不** 使用 `openclaw channels login telegram`；请在配置/环境中配置令牌，然后启动 Gateway 网关。
+    环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账户）。
+    Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置令牌，然后启动 Gateway 网关。

  </Step>

-  <Step title="启动 Gateway 网关并批准首次私信">
+  <Step title="启动 Gateway 网关并批准第一条私信">

 ```bash
 openclaw gateway
@ -74,21 +74,21 @@ openclaw pairing approve telegram <CODE>
 </Steps>

 <Note>
-令牌解析顺序支持按账号区分。实际上，配置值优先于环境回退，且 `TELEGRAM_BOT_TOKEN` 只适用于默认账号。
+令牌解析顺序会识别账户。实践中，配置值优先于环境变量回退，并且 `TELEGRAM_BOT_TOKEN` 只适用于默认账户。
 </Note>

 ## Telegram 端设置

 <AccordionGroup>
  <Accordion title="隐私模式和群组可见性">
-    Telegram 机器人默认使用**隐私模式**，这会限制它们能接收哪些群组消息。
+    Telegram 机器人默认使用**隐私模式**，这会限制它们接收的群组消息。

    如果机器人必须看到所有群组消息，可以：

    - 通过 `/setprivacy` 禁用隐私模式，或
    - 将机器人设为群组管理员。

-    切换隐私模式时，请在每个群组中移除并重新添加机器人，这样 Telegram 才会应用变更。
+    切换隐私模式后，请在每个群组中移除并重新添加机器人，以便 Telegram 应用该变更。

  </Accordion>

@ -102,7 +102,7 @@ openclaw pairing approve telegram <CODE>
  <Accordion title="有用的 BotFather 开关">

    - `/setjoingroups` 用于允许/拒绝添加到群组
-    - `/setprivacy` 用于控制群组可见性行为
+    - `/setprivacy` 用于群组可见性行为

  </Accordion>
 </AccordionGroup>
@ -118,27 +118,27 @@ openclaw pairing approve telegram <CODE>
    - `open`（要求 `allowFrom` 包含 `"*"`）
    - `disabled`

-    `dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 会让任何找到或猜到机器人用户名的 Telegram 账号都能命令该机器人。仅应将它用于有意公开且工具受到严格限制的机器人；单所有者机器人应使用带数字用户 ID 的 `allowlist`。
+    `dmPolicy: "open"` 配合 `allowFrom: ["*"]` 会允许任何找到或猜到机器人用户名的 Telegram 账户向机器人发出命令。仅应将它用于有意公开且工具严格受限的机器人；单一所有者机器人应使用带数字用户 ID 的 `allowlist`。

-    `channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。接受 `telegram:` / `tg:` 前缀，并会规范化。
-    在多账号配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：账号级 `allowFrom: ["*"]` 条目不会使该账号公开，除非合并后的有效账号允许列表仍包含显式通配符。
-    `dmPolicy: "allowlist"` 搭配空 `allowFrom` 会阻止所有私信，并会被配置校验拒绝。
-    设置只要求填写数字用户 ID。
-    如果你已升级且配置包含 `@username` 允许列表条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram 机器人令牌）。
-    如果你之前依赖配对存储允许列表文件，`openclaw doctor --fix` 可以在允许列表流程中将条目恢复到 `channels.telegram.allowFrom`（例如 `dmPolicy: "allowlist"` 尚无显式 ID 时）。
+    `channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。`telegram:` / `tg:` 前缀会被接受并规范化。
+    在多账户配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：账户级 `allowFrom: ["*"]` 条目不会让该账户公开，除非合并后的有效账户允许列表中仍包含显式通配符。
+    `dmPolicy: "allowlist"` 配合空的 `allowFrom` 会阻止所有私信，并会被配置校验拒绝。
+    设置只会询问数字用户 ID。
+    如果你已升级且配置中包含 `@username` 允许列表条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram 机器人令牌）。
+    如果你之前依赖配对存储的允许列表文件，`openclaw doctor --fix` 可以在 allowlist 流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 尚无显式 ID 时）。

-    对于单所有者机器人，建议使用 `dmPolicy: "allowlist"` 并设置显式数字 `allowFrom` ID，使访问策略在配置中保持持久（而不是依赖之前的配对批准）。
+    对于单一所有者机器人，建议使用 `dmPolicy: "allowlist"` 并配置显式数字 `allowFrom` ID，以便将访问策略持久保存在配置中（而不是依赖之前的配对批准）。

-    常见混淆：私信配对批准并不意味着“此发送者在所有地方都已授权”。
-    配对授予私信访问权限。如果还没有命令所有者，首次获批配对还会设置 `commands.ownerAllowFrom`，从而为仅所有者命令和执行批准提供显式操作员账号。
+    常见混淆：私信配对批准并不表示“此发送者在所有地方都已授权”。
+    配对授予私信访问权限。如果尚无命令所有者，第一次批准的配对还会设置 `commands.ownerAllowFrom`，使仅所有者命令和 exec 批准拥有显式操作员账户。
    群组发送者授权仍来自显式配置允许列表。
-    如果你想要“一次授权后私信和群组命令都能工作”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:<your user id>`。
+    如果你希望“我授权一次后，私信和群组命令都能工作”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:<your user id>`。

    ### 查找你的 Telegram 用户 ID

    更安全（无需第三方机器人）：

-    1. 向你的机器人发送私信。
+    1. 私信你的机器人。
    2. 运行 `openclaw logs --follow`。
    3. 读取 `from.id`。

@ -153,12 +153,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
  </Tab>

  <Tab title="群组策略和允许列表">
-    两个控制项会同时生效：
+    两项控制会共同生效：

    1. **允许哪些群组**（`channels.telegram.groups`）
       - 没有 `groups` 配置：
-         - 搭配 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查
-         - 搭配 `groupPolicy: "allowlist"`（默认）：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`）
+         - 配合 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查
+         - 配合 `groupPolicy: "allowlist"`（默认）：在你添加 `groups` 条目（或 `"*"`）之前，群组会被阻止
       - 已配置 `groups`：作为允许列表（显式 ID 或 `"*"`）

    2. **群组中允许哪些发送者**（`channels.telegram.groupPolicy`）
@ -167,16 +167,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
       - `disabled`

    `groupAllowFrom` 用于群组发送者过滤。如果未设置，Telegram 会回退到 `allowFrom`。
-    `groupAllowFrom` 条目应为数字 Telegram 用户 ID（`telegram:` / `tg:` 前缀会规范化）。
+    `groupAllowFrom` 条目应为数字 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被规范化）。
    不要将 Telegram 群组或超级群组聊天 ID 放入 `groupAllowFrom`。负数聊天 ID 应放在 `channels.telegram.groups` 下。
    非数字条目会在发送者授权中被忽略。
-    安全边界（`2026.2.25+`）：群组发送者认证**不会**继承私信配对存储批准。
-    配对仅用于私信。对于群组，请设置 `groupAllowFrom` 或按群组/按话题设置 `allowFrom`。
-    如果未设置 `groupAllowFrom`，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。
-    单所有者机器人的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。
-    运行时注意事项：如果完全缺少 `channels.telegram`，除非显式设置了 `channels.defaults.groupPolicy`，否则运行时默认会以失败关闭方式使用 `groupPolicy="allowlist"`。
+    安全边界（`2026.2.25+`）：群组发送者身份验证**不会**继承私信配对存储批准。
+    配对仅限私信。对于群组，请设置 `groupAllowFrom` 或每群组/每话题的 `allowFrom`。
+    如果未设置 `groupAllowFrom`，Telegram 会回退到配置 `allowFrom`，而不是配对存储。
+    单一所有者机器人的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。
+    运行时注意：如果完全缺少 `channels.telegram`，运行时会默认故障关闭为 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。

-    示例：允许某个特定群组中的任何成员：
+    示例：允许一个特定群组中的任何成员：

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

-    示例：仅允许某个特定群组内的特定用户：
+    示例：只允许一个特定群组中的特定用户：

 ```json5
 {
@ -213,21 +213,21 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    <Warning>
      常见错误：`groupAllowFrom` 不是 Telegram 群组允许列表。

-      - 将 `-1001234567890` 这样的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。
-      - 当你想限制已允许群组内哪些人可以触发机器人时，将 `8734062810` 这样的 Telegram 用户 ID 放在 `groupAllowFrom` 下。
-      - 仅在你希望已允许群组中的任何成员都能与机器人对话时，才使用 `groupAllowFrom: ["*"]`。
+      - 将类似 `-1001234567890` 的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。
+      - 当你想限制已允许群组中哪些人可以触发机器人时，将类似 `8734062810` 的 Telegram 用户 ID 放在 `groupAllowFrom` 下。
+      - 只有在你希望已允许群组中的任何成员都能与机器人对话时，才使用 `groupAllowFrom: ["*"]`。

    </Warning>

  </Tab>

  <Tab title="提及行为">
-    群组回复默认需要提及。
+    群组回复默认要求提及。

    提及可以来自：

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

@ -236,7 +236,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    - `/activation always`
    - `/activation mention`

-    这些只会更新会话状态。使用配置实现持久化。
+    这些只会更新会话状态。使用配置来持久化。

    持久化配置示例：

@ -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>
@ -265,18 +265,18 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"

 - Telegram 由 Gateway 网关进程拥有。
 - 路由是确定性的：Telegram 入站会回复到 Telegram（模型不会选择渠道）。
- 入站消息会规范化为共享渠道信封，并包含回复元数据和媒体占位符。
+- 入站消息会规范化为共享渠道信封，包含回复元数据和媒体占位符。
 - 群组会话按群组 ID 隔离。论坛话题会追加 `:topic:<threadId>` 以保持话题隔离。
- 私信消息可以携带 `message_thread_id`；OpenClaw 会使用线程感知的会话键路由它们，并为回复保留线程 ID。
- 长轮询使用 grammY runner，并按每个聊天/每个线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。
- 每个 Gateway 网关进程内部都会保护长轮询，因此同一时间只有一个活动轮询器可以使用一个机器人令牌。如果你仍然看到 `getUpdates` 409 冲突，可能是另一个 OpenClaw Gateway 网关、脚本或外部轮询器正在使用同一令牌。
- 默认情况下，长轮询看门狗会在 120 秒内没有完成的 `getUpdates` 活跃性后触发重启。仅当你的部署在长时间运行工作期间仍出现误报轮询停滞重启时，才提高 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账号覆盖。
+- 私信消息可以携带 `message_thread_id`；OpenClaw 会用支持线程的会话键对其进行路由，并为回复保留线程 ID。
+- 长轮询使用 grammY runner，并按聊天/线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。
+- 每个 Gateway 网关进程内都会保护长轮询，确保同一时间只有一个活动 poller 可以使用一个机器人令牌。如果你仍看到 `getUpdates` 409 冲突，可能有另一个 OpenClaw Gateway 网关、脚本或外部 poller 正在使用同一个令牌。
+- 默认情况下，如果 120 秒内没有完成的 `getUpdates` 存活信号，长轮询 watchdog 会触发重启。仅当你的部署在长时间运行工作期间仍看到误判的轮询停滞重启时，才增大 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账户覆盖。
 - Telegram Bot API 不支持已读回执（`sendReadReceipts` 不适用）。

 ## 功能参考

 <AccordionGroup>
-  <Accordion title="实时流式预览（消息编辑）">
+  <Accordion title="实时流预览（消息编辑）">
    OpenClaw 可以实时流式传输部分回复：

    - 直接聊天：预览消息 + `editMessageText`
@ -285,11 +285,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    要求：

    - `channels.telegram.streaming` 为 `off | partial | block | progress`（默认：`partial`）
-    - 在 Telegram 上，`progress` 会映射到 `partial`（与跨渠道命名兼容）
-    - `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑的预览消息（默认：预览流式传输启用时为 `true`）
-    - 会检测旧版 `channels.telegram.streamMode` 和布尔 `streaming` 值；运行 `openclaw doctor --fix` 可将它们迁移到 `channels.telegram.streaming.mode`
+    - `progress` 在 Telegram 上映射到 `partial`（兼容跨渠道命名）
+    - `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑的预览消息（默认：预览流式传输处于活动状态时为 `true`）
+    - 会检测旧版 `channels.telegram.streamMode` 和布尔值 `streaming`；运行 `openclaw doctor --fix` 可将它们迁移到 `channels.telegram.streaming.mode`

-    工具进度预览更新是在工具运行时显示的简短“正在工作...”行，例如命令执行、文件读取、计划更新或补丁摘要。Telegram 默认保持启用这些内容，以匹配 `v2026.4.22` 及更高版本已发布的 OpenClaw 行为。若要保留答案文本的已编辑预览，但隐藏工具进度行，请设置：
+    工具进度预览更新是在工具运行时显示的简短 “Working...” 行，例如命令执行、文件读取、规划更新或补丁摘要。Telegram 默认保持这些更新启用，以匹配 `v2026.4.22` 及更高版本发布的 OpenClaw 行为。若要保留回答文本的已编辑预览，但隐藏工具进度行，请设置：

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

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

    对于纯文本回复：

-    - 短私信/群组/话题预览：OpenClaw 保留同一条预览消息，并在原处执行最终编辑
-    - 早于约一分钟的预览：OpenClaw 将完成的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间
+    - 简短的私信/群组/topic 预览：OpenClaw 保留同一条预览消息，并在原处执行最终编辑
+    - 超过约一分钟的预览：OpenClaw 将完成的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间

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

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

-    如果原生草稿传输不可用或被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。
+    如果原生草稿传输不可用/被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。

-    仅限 Telegram 的推理流：
+    仅 Telegram 推理流：

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

  </Accordion>

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

    - 类 Markdown 文本会渲染为 Telegram 安全的 HTML。
    - 原始模型 HTML 会被转义，以减少 Telegram 解析失败。
-    - 如果 Telegram 拒绝解析后的 HTML，OpenClaw 会以纯文本重试。
+    - 如果 Telegram 拒绝已解析的 HTML，OpenClaw 会重试为纯文本。

-    链接预览默认启用，可以用 `channels.telegram.linkPreview: false` 禁用。
+    链接预览默认启用，可通过 `channels.telegram.linkPreview: false` 禁用。

  </Accordion>

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

    原生命令默认值：

-    - `commands.native: "auto"` 为 Telegram 启用原生命令
+    - `commands.native: "auto"` 会为 Telegram 启用原生命令

    添加自定义命令菜单项：

@ -361,40 +361,40 @@ 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 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 拒绝了已配置的机器人令牌。请用当前 BotFather 令牌更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。
+    - `setMyCommands failed` 带有网络/fetch 错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。

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

    安装 `device-pair` 插件后：

    1. `/pair` 生成设置代码
-    2. 在 iOS 应用中粘贴代码
+    2. 将代码粘贴到 iOS 应用中
    3. `/pair pending` 列出待处理请求（包括角色/作用域）
    4. 批准请求：
       - `/pair approve <requestId>` 用于显式批准
       - 只有一个待处理请求时使用 `/pair approve`
       - `/pair approve latest` 用于最近的请求

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

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

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

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

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

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

 ```json5
 {
@ -466,8 +466,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`）
@ -475,7 +475,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`）。

    门控控制：

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

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

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

  </Accordion>

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

    - `[[reply_to_current]]` 回复触发消息
-    - `[[reply_to:<id>]]` 回复指定的 Telegram 消息 ID
+    - `[[reply_to:<id>]]` 回复特定 Telegram 消息 ID

    `channels.telegram.replyToMode` 控制处理方式：

@ -503,29 +503,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="论坛话题和线程行为">
+  <Accordion title="论坛 topic 和线程行为">
    论坛超级群组：

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

-    常规话题（`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`

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

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

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

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

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

-    **从聊天中生成线程绑定 ACP**：`/acp spawn <agent> --thread here|auto` 将当前话题绑定到新的 ACP 会话；后续消息会直接路由到该处。OpenClaw 会将生成确认固定在话题内。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。
+    **从聊天生成线程绑定的 ACP**：`/acp spawn <agent> --thread here|auto` 会将当前 topic 绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在 topic 内固定生成确认。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。

-    模板上下文公开 `MessageThreadId` 和 `IsForum`。带 `message_thread_id` 的私信聊天会保留私信路由，但使用感知线程的会话键。
+    模板上下文暴露 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天会保持私信路由，但使用线程感知的会话键。

  </Accordion>

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

-    Telegram 区分语音便笺和音频文件。
+    Telegram 会区分语音便条与音频文件。

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

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

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

    ### 视频消息

-    Telegram 区分视频文件和视频便笺。
+    Telegram 会区分视频文件与视频便条。

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

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

-    视频便笺不支持标题；提供的消息文本会单独发送。
+    视频便条不支持说明；提供的消息文本会单独发送。

    ### 贴纸

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

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

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

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

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

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

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

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

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

  </Accordion>

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

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

    - `Telegram reaction added: 👍 by Alice (@alice) on msg 42`

    配置：

-    - `channels.telegram.reactionNotifications`：`off | own | all`（默认值：`own`）
-    - `channels.telegram.reactionLevel`：`off | ack | minimal | extensive`（默认值：`minimal`）
+    - `channels.telegram.reactionNotifications`: `off | own | all`（默认：`own`）
+    - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive`（默认：`minimal`）

-    注意事项：
+    备注：

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

    轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。

  </Accordion>

-  <Accordion title="确认回应反应">
-    `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。
+  <Accordion title="确认回应">
+    `ackReaction` 会在 OpenClaw 处理传入消息时发送一个确认 emoji。

    解析顺序：

    - `channels.telegram.accounts.<accountId>.ackReaction`
    - `channels.telegram.ackReaction`
    - `messages.ackReaction`
-    - 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"）
+    - 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 "👀"）

-    注意事项：
+    备注：

-    - Telegram 需要 unicode 表情符号（例如 "👀"）。
-    - 使用 `""` 可为某个渠道或账号禁用反应。
+    - Telegram 需要 unicode emoji（例如 "👀"）。
+    - 使用 `""` 可为某个渠道或账号禁用回应。

  </Accordion>

@ -720,28 +720,28 @@ 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"`。

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

  </Accordion>

  <Accordion title="限制、重试和 CLI 目标">
-    - `channels.telegram.textChunkLimit` 默认值为 4000。
-    - `channels.telegram.chunkMode="newline"` 会在按长度拆分前优先使用段落边界（空行）。
-    - `channels.telegram.mediaMaxMb`（默认 100）限制入站和出站 Telegram 媒体大小。
-    - `channels.telegram.timeoutSeconds` 覆盖 Telegram API 客户端超时（如未设置，则使用 grammY 默认值）。
-    - `channels.telegram.pollingStallThresholdMs` 默认值为 `120000`；仅在轮询停滞重启误报时，在 `30000` 到 `600000` 之间调整。
+    - `channels.telegram.textChunkLimit` 默认是 4000。
+    - `channels.telegram.chunkMode="newline"` 在按长度拆分前优先使用段落边界（空行）。
+    - `channels.telegram.mediaMaxMb`（默认 100）限制传入和传出的 Telegram 媒体大小。
+    - `channels.telegram.timeoutSeconds` 会覆盖 Telegram API 客户端超时（如未设置，则使用 grammY 默认值）。
+    - `channels.telegram.pollingStallThresholdMs` 默认为 `120000`；仅在轮询停滞重启出现误报时，在 `30000` 到 `600000` 之间调整。
    - 群组上下文历史使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（默认 50）；`0` 表示禁用。
-    - 回复/引用/转发补充上下文目前会按接收内容传递。
-    - Telegram 允许列表主要限制谁可以触发智能体，而不是完整的补充上下文编辑边界。
+    - 回复/引用/转发的补充上下文目前会按收到的内容传递。
+    - Telegram allowlist 主要限制谁可以触发智能体，而不是完整的补充上下文脱敏边界。
    - 私信历史控制：
      - `channels.telegram.dmHistoryLimit`
      - `channels.telegram.dms["<user_id>"].historyLimit`
-    - `channels.telegram.retry` 配置适用于可恢复出站 API 错误的 Telegram 发送辅助函数（CLI/工具/动作）。入站最终回复投递也会对 Telegram 预连接失败使用有界安全发送重试，但不会重试可能导致可见消息重复的模糊发送后网络封包。
+    - `channels.telegram.retry` 配置适用于 Telegram 发送辅助函数（CLI/工具/actions）中的可恢复出站 API 错误。传入最终回复投递也会对 Telegram 预连接失败使用有界安全发送重试，但不会重试可能导致可见消息重复的含糊发送后网络信封。

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

@ -765,52 +765,52 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
    - `--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 中的执行审批">
-    Telegram 支持在审批者私信中进行执行审批，并且可以选择在来源聊天或话题中发布提示。审批者必须是数字 Telegram 用户 ID。
+  <Accordion title="Telegram 中的 exec 审批">
+    Telegram 支持在审批人私信中进行 exec 审批，也可以选择在原始聊天或话题中发布提示。审批人必须是数字 Telegram 用户 ID。

    配置路径：

-    - `channels.telegram.execApprovals.enabled`（当至少一个审批者可解析时自动启用）
-    - `channels.telegram.execApprovals.approvers`（回退到 `commands.ownerAllowFrom` 中的数字所有者 ID）
-    - `channels.telegram.execApprovals.target`：`dm`（默认）| `channel` | `both`
+    - `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` 控制谁可以与机器人对话以及机器人向何处发送普通回复。它们不会让某人成为执行审批者。当还没有命令所有者时，第一个已批准的私信配对会引导创建 `commands.ownerAllowFrom`，因此单所有者设置仍可工作，无需在 `execApprovals.approvers` 下重复 ID。
+    `channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制谁可以与机器人对话，以及它在哪里发送常规回复。它们不会让某人成为 exec 审批人。当还没有命令 owner 时，第一个获批的私信配对会引导写入 `commands.ownerAllowFrom`，因此单 owner 设置仍可工作，无需在 `execApprovals.approvers` 下重复 ID。

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

-    内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 通过插件审批解析；其他 ID 会先通过执行审批解析。
+    内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 会通过插件审批解析；其他 ID 会先通过 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` | 数字（ms）        | `60000` | 向同一聊天发送错误回复的最小间隔。防止故障期间出现错误刷屏。                          |
+| 键                                  | 值                | 默认值  | 描述                                                                                         |
+| ----------------------------------- | ----------------- | ------- | -------------------------------------------------------------------------------------------- |
+| `channels.telegram.errorPolicy`     | `reply`, `silent` | `reply` | `reply` 会向聊天发送友好的错误消息。`silent` 会完全抑制错误回复。 |
+| `channels.telegram.errorCooldownMs` | 数字（ms）        | `60000` | 对同一聊天发送错误回复的最短间隔。可防止故障期间出现错误刷屏。        |

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

 ```json5
 {
@ -831,52 +831,53 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
 ## 故障排除

 <AccordionGroup>
-  <Accordion title="机器人不响应非提及群组消息">
+  <Accordion title="机器人不响应未提及它的群组消息">

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

  </Accordion>

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

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

  </Accordion>

  <Accordion title="命令部分可用或完全不可用">

    - 授权你的发送者身份（配对和/或数字 `allowFrom`）
-    - 即使群组策略为 `open`，命令授权仍然适用
-    - 带有 `BOT_COMMANDS_TOO_MUCH` 的 `setMyCommands failed` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生命令菜单
-    - 带有网络/fetch 错误的 `setMyCommands failed` 通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性问题
+    - 即使群组策略是 `open`，命令授权仍然适用
+    - `setMyCommands failed` 携带 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生命令菜单
+    - `setMyCommands failed` 携带网络/fetch 错误通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性存在问题

  </Accordion>

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

-    - `getMe returned 401` 是配置的机器人令牌导致的 Telegram 身份验证失败。
-    - 在 BotFather 中重新复制或重新生成机器人令牌，然后为默认账号更新 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts.<id>.botToken` 或 `TELEGRAM_BOT_TOKEN`。
-    - 启动期间的 `deleteWebhook 401 Unauthorized` 也是身份验证失败；将其视为“webhook 不存在”只会把同一个错误令牌失败推迟到后续 API 调用。
-    - 如果轮询启动期间 `deleteWebhook` 因临时网络错误失败，OpenClaw 会检查 `getWebhookInfo`；当 Telegram 报告空 webhook URL 时，轮询会继续，因为清理已经满足。
+    - `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 调用。
+    - 如果 `deleteWebhook` 在轮询启动期间因临时网络错误而失败，OpenClaw 会检查 `getWebhookInfo`；当 Telegram 报告 webhook URL 为空时，轮询会继续，因为清理已满足。

  </Accordion>

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

-    - 如果 AbortSignal 类型不匹配，Node 22+ 加自定义 fetch/代理可能会触发立即中止行为。
-    - 某些主机会先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出站可能导致间歇性 Telegram API 故障。
-    - 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些作为可恢复网络错误进行重试。
-    - 如果日志包含 `Polling stall detected`，默认情况下，OpenClaw 会在 120 秒内没有完成长轮询活性检查后重启轮询并重建 Telegram 传输。
-    - 仅当长时间运行的 `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 传输。
+    - Node 22+ 与自定义 fetch/proxy 组合时，如果 AbortSignal 类型不匹配，可能触发立即中止行为。
+    - 某些主机会优先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出站可能导致 Telegram API 间歇性失败。
+    - 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些作为可恢复网络错误重试。
+    - 如果日志包含 `Polling stall detected`，默认情况下，在 120 秒没有完成长轮询活性后，OpenClaw 会重启轮询并重建 Telegram 传输。
+    - 当正在运行的轮询账号在启动宽限期后尚未完成 `getUpdates`，或其最近一次成功的轮询传输活动已陈旧时，`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 传输。
    - 在直接出站/TLS 不稳定的 VPS 主机上，通过 `channels.telegram.proxy` 路由 Telegram API 调用：

 ```yaml
@ -886,7 +887,7 @@ channels:
 ```

    - Node 22+ 默认使用 `autoSelectFamily=true`（WSL2 除外）和 `dnsResultOrder=ipv4first`。
-    - 如果你的主机是 WSL2，或明确在仅 IPv4 行为下工作得更好，请强制选择地址族：
+    - 如果你的主机是 WSL2，或者明确更适合仅 IPv4 的行为，请强制选择地址族：

 ```yaml
 channels:
@ -895,7 +896,7 @@ 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:
@ -904,21 +905,20 @@ channels:
      dangerouslyAllowPrivateNetwork: true
 ```

-    - 每个账户也可以在
-      `channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork` 单独启用同一选项。
-    - 如果你的代理将 Telegram 媒体主机解析为 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已允许 RFC 2544
-      基准测试范围。
+    - 同一选择也可按账号在
+      `channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork` 配置。
+    - 如果你的代理将 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
@ -934,15 +934,15 @@ dig +short api.telegram.org AAAA

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

-<Accordion title="高价值 Telegram 字段">
+<Accordion title="Telegram 关键信息字段">

- 启动/凭证：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向常规文件；符号链接会被拒绝）
+- 启动/认证：`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`
 - 流式传输：`streaming`（预览）、`streaming.preview.toolProgress`、`blockStreaming`
- 格式化/投递：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix`
+- 格式/交付：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix`
 - 媒体/网络：`mediaMaxMb`、`timeoutSeconds`、`pollingStallThresholdMs`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy`
 - 自定义 API 根地址：`apiRoot`（仅 Bot API 根地址；不要包含 `/bot<TOKEN>`）
 - webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost`
@ -954,14 +954,14 @@ dig +short api.telegram.org AAAA
 </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">
    群组和话题允许列表行为。