From c186f129ee5a4e3dce8a9848d42201240a4847e5 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 3 May 2026 15:28:07 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/telegram.md | 380 ++++++++++++++++---------------- 1 file changed, 189 insertions(+), 191 deletions(-) diff --git a/docs/zh-CN/channels/telegram.md b/docs/zh-CN/channels/telegram.md index 4af2b91eb..5ac56b41e 100644 --- a/docs/zh-CN/channels/telegram.md +++ b/docs/zh-CN/channels/telegram.md @@ -1,25 +1,25 @@ --- read_when: - - 开发 Telegram 功能或网络钩子 + - 处理 Telegram 功能或网络钩子 summary: Telegram 机器人支持状态、能力和配置 title: Telegram x-i18n: - generated_at: "2026-05-03T15:20:54Z" + generated_at: "2026-05-03T15:25:49Z" model: gpt-5.5 provider: openai - source_hash: 2300e613cd54084c533a0328bc7e1d08f677360e213cb7f3d9364e1e82a30020 + source_hash: c3b97d3dff3d3a91db568dc689f82c0b63ad8028fb716cc772e84d7afe071869 source_path: channels/telegram.md workflow: 16 --- -可用于通过 grammY 支撑生产级机器人私信和群组。长轮询是默认模式；webhook 模式可选。 +可投入生产环境，用于通过 grammY 支持机器人私信和群组。默认模式是长轮询；webhook 模式是可选的。 Telegram 的默认私信策略是配对。 - 跨渠道诊断和修复操作手册。 + 跨渠道诊断和修复手册。 完整的渠道配置模式和示例。 @@ -30,7 +30,7 @@ x-i18n: - 打开 Telegram，并与 **@BotFather** 对话（确认用户名正好是 `@BotFather`）。 + 打开 Telegram 并与 **@BotFather** 聊天（确认用户名完全是 `@BotFather`）。 运行 `/newbot`，按提示操作，并保存令牌。 @@ -51,8 +51,8 @@ x-i18n: } ``` - 环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账户）。 - Telegram **不会**使用 `openclaw channels login telegram`；请在配置/环境变量中配置令牌，然后启动 Gateway 网关。 + 环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账号）。 + Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置令牌，然后启动 Gateway 网关。 @@ -74,28 +74,28 @@ openclaw pairing approve telegram -令牌解析顺序会感知账户。实际中，配置值优先于环境变量回退，且 `TELEGRAM_BOT_TOKEN` 仅适用于默认账户。 +令牌解析顺序支持账号感知。实际使用中，配置值优先于环境变量回退，且 `TELEGRAM_BOT_TOKEN` 只适用于默认账号。 ## Telegram 侧设置 - Telegram 机器人默认启用**隐私模式**，这会限制它们能接收的群组消息。 + Telegram 机器人默认使用**隐私模式**，这会限制它们能接收哪些群组消息。 如果机器人必须看到所有群组消息，可以： - 通过 `/setprivacy` 禁用隐私模式，或 - 将机器人设为群组管理员。 - 切换隐私模式时，请在每个群组中移除并重新添加机器人，以便 Telegram 应用更改。 + 切换隐私模式时，请在每个群组中移除并重新添加机器人，以便 Telegram 应用该变更。 管理员状态在 Telegram 群组设置中控制。 - 管理员机器人会接收所有群组消息，这对于始终在线的群组行为很有用。 + 管理员机器人会接收所有群组消息，这对始终在线的群组行为很有用。 @@ -111,32 +111,32 @@ openclaw pairing approve telegram - `channels.telegram.dmPolicy` 控制直接消息访问： + `channels.telegram.dmPolicy` 控制私信访问： - `pairing`（默认） - `allowlist`（要求 `allowFrom` 中至少有一个发送者 ID） - `open`（要求 `allowFrom` 包含 `"*"`） - `disabled` - `dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 会让任何找到或猜到机器人用户名的 Telegram 账户都能命令机器人。仅在有意公开且工具受到严格限制的机器人上使用；单一所有者机器人应使用 `allowlist` 并配置数字用户 ID。 + `dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 会让任何找到或猜到机器人用户名的 Telegram 账号都能向机器人发出命令。仅应将它用于刻意公开、且工具受到严格限制的机器人；单所有者机器人应使用包含数字用户 ID 的 `allowlist`。 `channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。`telegram:` / `tg:` 前缀会被接受并规范化。 - 在多账户配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：账户级 `allowFrom: ["*"]` 条目不会使该账户公开，除非合并后的有效账户允许列表仍包含显式通配符。 + 在多账号配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：账号级 `allowFrom: ["*"]` 条目不会让该账号公开，除非合并后的有效账号允许列表仍包含显式通配符。 `dmPolicy: "allowlist"` 搭配空的 `allowFrom` 会阻止所有私信，并会被配置校验拒绝。 - 设置只会要求输入数字用户 ID。 - 如果你已升级且配置中包含 `@username` 允许列表条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram 机器人令牌）。 - 如果你之前依赖配对存储的允许列表文件，`openclaw doctor --fix` 可以在允许列表流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 尚无显式 ID 时）。 + 设置只会要求数字用户 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`，让仅所有者命令和执行批准拥有一个显式操作账号。 群组发送者授权仍来自显式配置允许列表。 - 如果你希望“我授权一次后，私信和群组命令都可用”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:`。 + 如果你希望“我授权一次后，私信和群组命令都可用”，请把你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:`。 ### 查找你的 Telegram 用户 ID - 更安全（无第三方机器人）： + 更安全的方法（无第三方机器人）： 1. 私信你的机器人。 2. 运行 `openclaw logs --follow`。 @@ -156,10 +156,10 @@ curl "https://api.telegram.org/bot/getUpdates" 两个控制项会共同生效： 1. **允许哪些群组**（`channels.telegram.groups`） - - 无 `groups` 配置： + - 没有 `groups` 配置： - 搭配 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查 - 搭配 `groupPolicy: "allowlist"`（默认）：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`） - - 已配置 `groups`：作为允许列表生效（显式 ID 或 `"*"`） + - 已配置 `groups`：充当允许列表（显式 ID 或 `"*"`） 2. **群组中允许哪些发送者**（`channels.telegram.groupPolicy`） - `open` @@ -170,11 +170,11 @@ curl "https://api.telegram.org/bot/getUpdates" `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`，而不是配对存储。 - 单一所有者机器人的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。 - 运行时说明：如果完全缺少 `channels.telegram`，运行时默认会失败关闭为 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。 + 单所有者机器人的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。 + 运行时注意事项：如果完全缺少 `channels.telegram`，运行时会默认故障关闭为 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。 示例：允许一个特定群组中的任何成员： @@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 示例：仅允许一个特定群组中的特定用户： + 示例：仅允许一个特定群组内的特定用户： ```json5 { @@ -213,9 +213,9 @@ curl "https://api.telegram.org/bot/getUpdates" 常见错误：`groupAllowFrom` 不是 Telegram 群组允许列表。 - - 将 `-1001234567890` 这样的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。 - - 当你想限制已允许群组中哪些人可以触发机器人时，将 `8734062810` 这样的 Telegram 用户 ID 放在 `groupAllowFrom` 下。 - - 仅当你希望已允许群组中的任何成员都能与机器人对话时，才使用 `groupAllowFrom: ["*"]`。 + - 将类似 `-1001234567890` 的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。 + - 当你想限制允许群组内哪些人可以触发机器人时，将类似 `8734062810` 的 Telegram 用户 ID 放在 `groupAllowFrom` 下。 + - 仅当你希望允许群组的任何成员都能与机器人对话时，才使用 `groupAllowFrom: ["*"]`。 @@ -227,7 +227,7 @@ curl "https://api.telegram.org/bot/getUpdates" 提及可以来自： - 原生 `@botusername` 提及，或 - - 以下位置中的提及模式： + - 以下位置的提及模式： - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` @@ -236,7 +236,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `/activation always` - `/activation mention` - 这些只会更新会话状态。使用配置来持久化。 + 这些只会更新会话状态。使用配置实现持久化。 持久配置示例： @@ -255,7 +255,7 @@ curl "https://api.telegram.org/bot/getUpdates" 获取群组聊天 ID： - 将群组消息转发给 `@userinfobot` / `@getidsbot` - - 或从 `openclaw logs --follow` 中读取 `chat.id` + - 或从 `openclaw logs --follow` 读取 `chat.id` - 或检查 Bot API `getUpdates` @@ -266,17 +266,17 @@ curl "https://api.telegram.org/bot/getUpdates" - Telegram 由 Gateway 网关进程拥有。 - 路由是确定性的：Telegram 入站消息会回复到 Telegram（模型不会选择渠道）。 - 入站消息会规范化为共享渠道信封，并带有回复元数据和媒体占位符。 -- 群组会话按群组 ID 隔离。论坛话题会追加 `:topic:`，以保持话题隔离。 -- 私信消息可以携带 `message_thread_id`；OpenClaw 会保留线程 ID 用于回复，但默认将私信保持在扁平会话上。当你有意需要私信话题会话隔离时，请配置 `channels.telegram.dm.threadReplies: "inbound"`、`channels.telegram.direct..threadReplies: "inbound"`、`requireTopic: true`，或匹配的话题配置。 -- 长轮询使用 grammY runner，并按每聊天/每线程进行排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。 -- 每个 Gateway 网关进程内部都会保护长轮询，因此同一时间只有一个活跃 poller 可以使用一个机器人令牌。如果你仍看到 `getUpdates` 409 冲突，可能是另一个 OpenClaw Gateway 网关、脚本或外部 poller 正在使用同一个令牌。 -- 默认情况下，长轮询看门狗会在 120 秒内没有完成的 `getUpdates` 活性后触发重启。只有当你的部署在长时间运行工作期间仍出现误报的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账户覆盖。 +- 群组会话按群组 ID 隔离。论坛话题会追加 `:topic:` 以保持话题隔离。 +- 私信消息可以携带 `message_thread_id`；OpenClaw 会保留线程 ID 用于回复，但默认让私信保持在扁平会话上。当你确实需要私信话题会话隔离时，请配置 `channels.telegram.dm.threadReplies: "inbound"`、`channels.telegram.direct..threadReplies: "inbound"`、`requireTopic: true`，或匹配的话题配置。 +- 长轮询使用 grammY runner，并按聊天/按线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。 +- 每个 Gateway 网关进程内部都会保护长轮询，因此一次只有一个活跃轮询器可以使用一个机器人令牌。如果你仍看到 `getUpdates` 409 冲突，很可能是另一个 OpenClaw Gateway 网关、脚本或外部轮询器正在使用同一个令牌。 +- 默认情况下，如果 120 秒内没有完成的 `getUpdates` 活性信号，就会触发长轮询 watchdog 重启。仅当你的部署在长时间运行工作期间仍出现误判的轮询停滞重启时，才增大 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账号覆盖。 - Telegram Bot API 不支持已读回执（`sendReadReceipts` 不适用）。 ## 功能参考 - + OpenClaw 可以实时流式传输部分回复： - 直接聊天：预览消息 + `editMessageText` @@ -285,11 +285,11 @@ curl "https://api.telegram.org/bot/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` - 工具进度预览更新是在工具运行时显示的短 “Working...” 行，例如命令执行、文件读取、规划更新或补丁摘要。Telegram 默认保持这些更新启用，以匹配从 `v2026.4.22` 及之后版本发布的 OpenClaw 行为。若要保留答案文本的已编辑预览但隐藏工具进度行，请设置： + 工具进度预览更新是在工具运行时显示的短 “Working...” 行，例如命令执行、文件读取、计划更新或补丁摘要。Telegram 默认保持这些更新启用，以匹配 `v2026.4.22` 及更高版本发布的 OpenClaw 行为。若要保留用于答案文本的已编辑预览，但隐藏工具进度行，请设置： ```json { @@ -306,20 +306,20 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Use `streaming.mode: "off"` 仅在你想要只发送最终结果时使用：Telegram 预览编辑会被禁用，通用工具/进度闲聊会被抑制，而不是作为独立的 “Working...” 消息发送。审批提示、媒体载荷和错误仍会通过正常的最终发送路径发送。仅当你想保留答案预览编辑，同时隐藏工具进度状态行时，使用 `streaming.preview.toolProgress: false`。 + Use `streaming.mode: "off"` 仅在你需要只交付最终回复时使用：Telegram 预览编辑会被禁用，通用工具/进度提示会被抑制，而不是作为独立的 “Working...” 消息发送。审批提示、媒体载荷和错误仍然通过正常的最终交付路径发送。仅想保留答案预览编辑、同时隐藏工具进度状态行时，使用 `streaming.preview.toolProgress: false`。 对于纯文本回复： - - 较短的私信/群组/话题预览：OpenClaw 会保留同一条预览消息，并在原处执行最终编辑 - - 超过约一分钟的预览：OpenClaw 会将完成后的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳反映的是完成时间，而不是预览创建时间 + - 简短的私信/群组/话题预览：OpenClaw 保留同一条预览消息，并原地执行最终编辑 + - 超过约一分钟的预览：OpenClaw 将完成的回复作为新的最终消息发送，然后清理预览，这样 Telegram 可见的时间戳会反映完成时间，而不是预览创建时间 - 对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常的最终发送路径，然后清理预览消息。 + 对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常的最终交付，然后清理预览消息。 - 预览流式传输独立于分块流式传输。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 + 预览流式传输独立于分块流式传输。当 Telegram 明确启用分块流式传输时，OpenClaw 会跳过预览流，以避免重复流式传输。 - 仅限 Telegram 的推理流： + 仅 Telegram 的推理流： - - `/reasoning stream` 会在生成过程中将推理发送到实时预览 + - `/reasoning stream` 会在生成过程中把推理发送到实时预览 - 最终答案发送时不包含推理文本 @@ -331,7 +331,7 @@ curl "https://api.telegram.org/bot/getUpdates" - 原始模型 HTML 会被转义，以减少 Telegram 解析失败。 - 如果 Telegram 拒绝解析后的 HTML，OpenClaw 会以纯文本重试。 - 链接预览默认启用，可以通过 `channels.telegram.linkPreview: false` 禁用。 + 链接预览默认启用，可以用 `channels.telegram.linkPreview: false` 禁用。 @@ -342,7 +342,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `commands.native: "auto"` 为 Telegram 启用原生命令 - 添加自定义命令菜单条目： + 添加自定义命令菜单项： ```json5 { @@ -359,24 +359,24 @@ curl "https://api.telegram.org/bot/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` 端点。`apiRoot` 必须只是 Bot API 根地址，`openclaw doctor --fix` 会移除意外追加的 `/bot`。 - - `getMe returned 401` 表示 Telegram 拒绝了配置的机器人令牌。使用当前 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`。 + - `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 失败并显示 `404: Not Found`，但直接的 Bot API curl 命令可用，可能表示 `channels.telegram.apiRoot` 被设置成了完整的 `/bot` 端点。`apiRoot` 必须只是 Bot API 根地址，`openclaw doctor --fix` 会移除意外尾随的 `/bot`。 + - `getMe returned 401` 表示 Telegram 拒绝了配置的 bot token。使用当前 BotFather token 更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。 + - `setMyCommands failed` 搭配网络/fetch 错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。 ### 设备配对命令（`device-pair` 插件） @@ -384,22 +384,22 @@ curl "https://api.telegram.org/bot/getUpdates" 1. `/pair` 生成设置代码 2. 在 iOS 应用中粘贴代码 - 3. `/pair pending` 列出待处理请求（包括角色/作用域） + 3. `/pair pending` 列出待处理请求（包括角色/范围） 4. 批准请求： - `/pair approve ` 用于显式批准 - - 当只有一个待处理请求时使用 `/pair approve` + - 只有一个待处理请求时使用 `/pair approve` - `/pair approve latest` 用于最近的请求 - 设置代码携带一个短期有效的引导令牌。内置引导交接会将主节点令牌保持在 `scopes: []`；任何交接出去的 operator 令牌都限定在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write` 范围内。引导作用域检查带有角色前缀，因此该 operator 允许列表只满足 operator 请求；非 operator 角色仍然需要其自身角色前缀下的作用域。 + 设置代码携带一个短期有效的引导 token。内置引导交接会将主节点 token 保持在 `scopes: []`；任何交接的操作员 token 都会限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write` 内。引导范围检查带有角色前缀，因此该操作员 allowlist 只满足操作员请求；非操作员角色仍需要自己角色前缀下的范围。 - 如果设备使用已更改的认证详情（例如角色/作用域/公钥）重试，之前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。 + 如果设备使用已更改的认证详情（例如角色/范围/公钥）重试，先前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。 更多详情：[配对](/zh-CN/channels/pairing#pair-via-telegram-recommended-for-ios)。 - 配置内联键盘作用域： + 配置内联键盘范围： ```json5 { @@ -413,7 +413,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 按账号覆盖： + 按账户覆盖： ```json5 { @@ -431,7 +431,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 作用域： + 范围： - `off` - `dm` @@ -439,9 +439,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist`（默认） - 旧版 `capabilities: ["inlineButtons"]` 会映射到 `inlineButtons: "all"`。 + 旧版 `capabilities: ["inlineButtons"]` 映射到 `inlineButtons: "all"`。 - 消息动作示例： + 消息操作示例： ```json5 { @@ -459,21 +459,21 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 回调点击会作为文本传给智能体： + 回调点击会作为文本传递给智能体： `callback_data: ` - - Telegram 工具动作包括： + + 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`）。 门控控制： @@ -482,18 +482,18 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker`（默认：禁用） - 注意：`edit` 和 `topic-create` 当前默认启用，且没有单独的 `channels.telegram.actions.*` 开关。 - 运行时发送使用活动配置/密钥快照（启动/重载），因此动作路径不会在每次发送时执行临时 SecretRef 重新解析。 + 注意：`edit` 和 `topic-create` 当前默认启用，并且没有单独的 `channels.telegram.actions.*` 开关。 + 运行时发送使用活动的配置/密钥快照（启动/重新加载），因此操作路径不会在每次发送时执行临时 SecretRef 重新解析。 - 反应移除语义：[/tools/reactions](/zh-CN/tools/reactions) + 表情反应移除语义：[/tools/reactions](/zh-CN/tools/reactions) - Telegram 支持在生成的输出中使用显式回复线程标签： + Telegram 支持在生成输出中使用显式回复线程标签： - `[[reply_to_current]]` 回复触发消息 - - `[[reply_to:]]` 回复特定的 Telegram 消息 ID + - `[[reply_to:]]` 回复特定 Telegram 消息 ID `channels.telegram.replyToMode` 控制处理方式： @@ -501,7 +501,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - 当启用回复线程，并且原始 Telegram 文本或标题可用时，OpenClaw 会自动包含原生 Telegram 引用摘录。Telegram 将原生引用文本限制为 1024 个 UTF-16 码元，因此更长的消息会从开头引用；如果 Telegram 拒绝该引用，则回退到普通回复。 + 启用回复线程，并且原始 Telegram 文本或说明文字可用时，OpenClaw 会自动包含原生 Telegram 引用摘录。Telegram 将原生引用文本限制为 1024 个 UTF-16 代码单元，因此更长的消息会从开头引用；如果 Telegram 拒绝引用，则回退到普通回复。 注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会生效。 @@ -511,19 +511,19 @@ curl "https://api.telegram.org/bot/getUpdates" 论坛超级群组： - 话题会话键追加 `:topic:` - - 回复和正在输入状态会定向到话题线程 + - 回复和输入状态会指向话题线程 - 话题配置路径： `channels.telegram.groups..topics.` - 普通话题（`threadId=1`）特殊情况： + 常规话题（`threadId=1`）特殊情况： - 消息发送会省略 `message_thread_id`（Telegram 会拒绝 `sendMessage(...thread_id=1)`） - - 正在输入动作仍包含 `message_thread_id` + - 输入状态操作仍包含 `message_thread_id` - 话题继承：话题条目会继承群组设置，除非被覆盖（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。 - `agentId` 仅属于话题，不会从群组默认值继承。 + 话题继承：除非覆盖，话题条目会继承群组设置（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。 + `agentId` 仅适用于话题，不会从群组默认值继承。 - **按话题路由智能体**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同的智能体。这会让每个话题拥有自己的隔离工作区、记忆和会话。示例： + **按话题的智能体路由**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同的智能体。这让每个话题都有自己的隔离工作区、记忆和会话。示例： ```json5 { @@ -545,26 +545,26 @@ curl "https://api.telegram.org/bot/getUpdates" 然后每个话题都有自己的会话键：`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 话题绑定**：论坛话题可以通过顶层类型化 ACP 绑定（`bindings[]`，其中 `type: "acp"`、`match.channel: "telegram"`、`peer.kind: "group"`，以及类似 `-1001234567890:topic:42` 的带话题限定 ID）固定 ACP harness 会话。当前范围限于群组/超级群组中的论坛话题。参见 [ACP 智能体](/zh-CN/tools/acp-agents)。 - **从聊天生成线程绑定的 ACP**：`/acp spawn --thread here|auto` 会将当前话题绑定到新的 ACP 会话；后续消息会直接路由到该处。OpenClaw 会在话题内固定生成确认。需要 `channels.telegram.threadBindings.spawnSessions` 保持启用（默认：`true`）。 + **从聊天生成线程绑定的 ACP**：`/acp spawn --thread here|auto` 会将当前话题绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在话题内固定生成确认。需要 `channels.telegram.threadBindings.spawnSessions` 保持启用（默认：`true`）。 - 模板上下文公开 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天默认保持私信路由，并在扁平会话上保留回复元数据；只有在配置了 `threadReplies: "inbound"`、`threadReplies: "always"`、`requireTopic: true` 或匹配的话题配置时，才会使用线程感知会话键。对账号默认值使用顶层 `channels.telegram.dm.threadReplies`，或对单个私信使用 `direct..threadReplies`。 + 模板上下文公开 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天默认会保留私信路由，并在扁平会话上保留回复元数据；只有在配置了 `threadReplies: "inbound"`、`threadReplies: "always"`、`requireTopic: true` 或匹配的话题配置时，才会使用线程感知会话键。使用顶层 `channels.telegram.dm.threadReplies` 设置账户默认值，或为单个私信使用 `direct..threadReplies`。 ### 音频消息 - Telegram 会区分语音消息和音频文件。 + Telegram 区分语音消息和音频文件。 - 默认：音频文件行为 - - 在智能体回复中使用标签 `[[audio_as_voice]]` 强制作为语音消息发送 - - 入站语音消息转录会在智能体上下文中被标记为机器生成的、 + - 在智能体回复中使用标签 `[[audio_as_voice]]` 强制发送语音消息 + - 入站语音消息转写会在智能体上下文中被框定为机器生成的、 不可信文本；提及检测仍使用原始 - 转录，因此受提及门控的语音消息仍可继续工作。 + 转写，因此提及门控的语音消息仍能工作。 - 消息动作示例： + 消息操作示例： ```json5 { @@ -578,9 +578,9 @@ curl "https://api.telegram.org/bot/getUpdates" ### 视频消息 - Telegram 会区分视频文件和视频消息。 + Telegram 区分视频文件和视频消息。 - 消息动作示例： + 消息操作示例： ```json5 { @@ -592,14 +592,14 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 视频消息不支持标题；提供的消息文本会单独发送。 + 视频消息不支持说明文字；提供的消息文本会单独发送。 ### 贴纸 入站贴纸处理： - 静态 WEBP：下载并处理（占位符 ``） - - 动态 TGS：跳过 + - 动画 TGS：跳过 - 视频 WEBM：跳过 贴纸上下文字段： @@ -616,7 +616,7 @@ curl "https://api.telegram.org/bot/getUpdates" 贴纸会被描述一次（如果可能），并缓存以减少重复的视觉调用。 - 启用贴纸动作： + 启用贴纸操作： ```json5 { @@ -641,7 +641,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 搜索已缓存的贴纸： + 搜索缓存的贴纸： ```json5 { @@ -654,8 +654,8 @@ curl "https://api.telegram.org/bot/getUpdates" - - Telegram Reaction 会作为 `message_reaction` 更新到达（与消息负载分开）。 + + Telegram 回应会作为 `message_reaction` 更新到达（与消息载荷分离）。 启用后，OpenClaw 会将如下系统事件加入队列： @@ -666,32 +666,32 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.reactionNotifications`：`off | own | all`（默认：`own`） - `channels.telegram.reactionLevel`：`off | ack | minimal | extensive`（默认：`minimal`） - 注意事项： + 说明： - - `own` 表示仅用户对 Bot 发送消息的 Reaction（通过已发送消息缓存尽力判断）。 - - Reaction 事件仍会遵循 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。 - - Telegram 不会在 Reaction 更新中提供话题 ID。 - - 非论坛群组会路由到群聊会话 - - 论坛群组会路由到群组通用话题会话（`:topic:1`），而不是确切的原始话题 + - `own` 表示仅限用户对机器人发送消息的回应（通过已发送消息缓存尽力判断）。 + - 回应事件仍会遵循 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权的发送者会被丢弃。 + - Telegram 不会在回应更新中提供话题 ID。 + - 非论坛群组路由到群聊会话 + - 论坛群组路由到群组通用话题会话（`:topic:1`），而不是精确的原始话题 用于轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。 - - `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。 + + `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认 emoji。 解析顺序： - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"） + - 智能体身份 emoji 兜底（`agents.list[].identity.emoji`，否则为 "👀"） - 注意事项： + 说明： - - Telegram 期望 Unicode 表情符号（例如 "👀"）。 - - 使用 `""` 可为某个渠道或账号禁用该 Reaction。 + - Telegram 需要 unicode emoji（例如 "👀"）。 + - 使用 `""` 可禁用某个渠道或账号的回应。 @@ -700,7 +700,7 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram 触发的写入包括： - - 用于更新 `channels.telegram.groups` 的群组迁移事件（`migrate_to_chat_id`） + - 群组迁移事件（`migrate_to_chat_id`），用于更新 `channels.telegram.groups` - `/config set` 和 `/config unset`（需要启用命令） 禁用： @@ -718,28 +718,28 @@ curl "https://api.telegram.org/bot/getUpdates" - 默认使用长轮询。对于 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 secret token 和 JSON 正文，然后再向 Telegram 返回 `200`。 - 之后 OpenClaw 会通过与长轮询相同的按聊天/按话题 Bot 通道异步处理更新，因此缓慢的智能体轮次不会占用 Telegram 的投递 ACK。 + webhook 模式会先验证请求保护、Telegram secret token 和 JSON 正文，然后再向 Telegram 返回 `200`。 + 随后 OpenClaw 会通过与长轮询相同的按聊天/按话题机器人通道异步处理该更新，因此缓慢的智能体轮次不会阻塞 Telegram 的投递 ACK。 - - `channels.telegram.textChunkLimit` 默认值为 4000。 - - `channels.telegram.chunkMode="newline"` 会在按长度拆分之前优先使用段落边界（空行）。 + - `channels.telegram.textChunkLimit` 默认是 4000。 + - `channels.telegram.chunkMode="newline"` 在按长度拆分前优先使用段落边界（空行）。 - `channels.telegram.mediaMaxMb`（默认 100）限制入站和出站 Telegram 媒体大小。 - - `channels.telegram.timeoutSeconds` 会覆盖 Telegram API 客户端超时（如果未设置，则使用 grammY 默认值）。Bot 客户端会将低于 60 秒出站文本/输入中请求防护的配置值钳制到该防护之下，避免 grammY 在 OpenClaw 的传输防护和回退运行之前中止可见回复投递。长轮询仍使用 45 秒的 `getUpdates` 请求防护，因此空闲轮询不会被无限期遗弃。 - - `channels.telegram.pollingStallThresholdMs` 默认值为 `120000`；仅针对误报的轮询卡滞重启，在 `30000` 到 `600000` 之间调整。 + - `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 allowlist 主要用于限制谁可以触发智能体，而不是完整的补充上下文脱敏边界。 - - 私信历史控制项： + - 回复/引用/转发的补充上下文目前按接收原样传递。 + - Telegram 允许列表主要限制谁可以触发智能体，并不是完整的补充上下文删改边界。 + - 私信历史控制： - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - `channels.telegram.retry` 配置适用于可恢复的出站 API 错误下的 Telegram 发送辅助函数（CLI/工具/操作）。入站最终回复投递也会对 Telegram 预连接失败使用有界安全发送重试，但不会重试可能导致可见消息重复的、发送后语义不明确的网络信封。 + - `channels.telegram.retry` 配置适用于 Telegram 发送辅助能力（CLI/工具/操作）中的可恢复出站 API 错误。入站最终回复投递也会对 Telegram 预连接失败使用有界安全发送重试，但不会重试可能重复可见消息的发送后网络信封不明确情况。 CLI 发送目标可以是数字聊天 ID 或用户名： @@ -767,46 +767,46 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ Telegram 发送还支持： - - 在 `channels.telegram.capabilities.inlineButtons` 允许时，使用带有 `buttons` 块的 `--presentation` 来创建内联键盘 - - 当 Bot 可以在该聊天中置顶时，使用 `--pin` 或 `--delivery '{"pin":true}'` 请求置顶投递 + - 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带有 `buttons` 块的 `--presentation` 发送内联键盘 + - 当机器人可在该聊天中置顶时，使用 `--pin` 或 `--delivery '{"pin":true}'` 请求置顶投递 - 使用 `--force-document` 将出站图片和 GIF 作为文档发送，而不是压缩照片或动画媒体上传 操作门控： - `channels.telegram.actions.sendMessage=false` 会禁用出站 Telegram 消息，包括投票 - - `channels.telegram.actions.poll=false` 会禁用 Telegram 投票创建，同时保持常规发送启用 + - `channels.telegram.actions.poll=false` 会禁用 Telegram 投票创建，同时保留常规发送启用 - Telegram 支持在审批人私信中进行 exec 审批，并且可以选择在原始聊天或话题中发布提示。审批人必须是数字 Telegram 用户 ID。 + Telegram 支持在审批者私信中进行 exec 审批，并可选地在原始聊天或话题中发布提示。审批者必须是数字 Telegram 用户 ID。 配置路径： - - `channels.telegram.execApprovals.enabled`（至少能解析出一个审批人时自动启用） - - `channels.telegram.execApprovals.approvers`（回退到 `commands.ownerAllowFrom` 中的数字 owner ID） + - `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` 控制谁可以与 Bot 对话，以及它将普通回复发送到哪里。它们不会让某人成为 exec 审批人。当还没有命令 owner 时，首次获批的私信配对会引导创建 `commands.ownerAllowFrom`，因此单 owner 设置无需在 `execApprovals.approvers` 下重复 ID 也能工作。 + `channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制谁可以与机器人交谈，以及它向哪里发送普通回复。它们不会让某人成为 exec 审批者。当尚不存在命令所有者时，首次获批的私信配对会引导写入 `commands.ownerAllowFrom`，因此单所有者设置无需在 `execApprovals.approvers` 下重复 ID 也能正常工作。 - 渠道投递会在聊天中显示命令文本；仅在受信任的群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。exec 审批默认在 30 分钟后过期。 + 渠道投递会在聊天中显示命令文本；仅在可信群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。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 approvals](/zh-CN/tools/exec-approvals)。 + 参见 [Exec 审批](/zh-CN/tools/exec-approvals)。 ## 错误回复控制 -当智能体遇到投递或提供商错误时，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 配置键相同）。 @@ -829,56 +829,56 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## 故障排除 - + - - 如果 `requireMention=false`，Telegram privacy mode 必须允许完整可见性。 + - 如果 `requireMention=false`，Telegram 隐私模式必须允许完整可见性。 - BotFather：`/setprivacy` -> Disable - - 然后将 Bot 从群组移除并重新添加 - - 当配置预期接收未提及 Bot 的群组消息时，`openclaw channels status` 会给出警告。 - - `openclaw channels status --probe` 可以检查显式数字群组 ID；通配符 `"*"` 无法探测成员资格。 + - 然后移除机器人并重新加入群组 + - 当配置预期接收未提及机器人的群组消息时，`openclaw channels status` 会发出警告。 + - `openclaw channels status --probe` 可以检查明确的数字群组 ID；通配符 `"*"` 无法探测成员资格。 - 快速会话测试：`/activation always`。 - + - - 当存在 `channels.telegram.groups` 时，群组必须被列出（或包含 `"*"`） - - 验证 Bot 是否在群组中 - - 查看日志：`openclaw logs --follow` 以了解跳过原因 + - 当 `channels.telegram.groups` 存在时，群组必须列在其中（或包含 `"*"`） + - 验证机器人在群组中的成员资格 + - 查看日志：`openclaw logs --follow`，了解跳过原因 - + - 授权你的发送者身份（配对和/或数字 `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 可达性存在问题 - - `getMe returned 401` 表示已配置 Bot token 的 Telegram 身份验证失败。 - - 在 BotFather 中重新复制或重新生成 Bot token，然后更新默认账号的 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts..botToken` 或 `TELEGRAM_BOT_TOKEN`。 - - 启动期间的 `deleteWebhook 401 Unauthorized` 也是身份验证失败；将其当作“没有 webhook 存在”只会把同一个错误 token 故障推迟到后续 API 调用。 - - 如果 `deleteWebhook` 在轮询启动期间因瞬时网络错误失败，OpenClaw 会继续进入长轮询，而不是再次发起预轮询控制平面调用。仍处于活动状态的 webhook 会表现为 `getUpdates` 冲突；随后 OpenClaw 会重建 Telegram 传输并重试 webhook 清理。 - - 成功完成启动 `getMe` 探测后，OpenClaw 会将该 Bot 身份复用于 grammY 轮询启动，因此运行器不需要在首次 `getUpdates` 前再次调用 `getMe`。 + - `getMe returned 401` 是配置的机器人 token 发生 Telegram 认证失败。 + - 在 BotFather 中重新复制或重新生成机器人 token，然后更新默认账号的 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts..botToken` 或 `TELEGRAM_BOT_TOKEN`。 + - 启动期间的 `deleteWebhook 401 Unauthorized` 也是认证失败；将其当作“没有 webhook 存在”只会把相同的错误 token 失败推迟到后续 API 调用。 - - 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 现在会将这些作为可恢复的网络错误重试。 - - 如果 Telegram 套接字按较短的固定周期回收，请检查 `channels.telegram.timeoutSeconds` 是否过低；bot 客户端会将配置值钳制到不低于出站请求和 `getUpdates` 请求保护值，但旧版本在该值低于这些保护值时，可能会在每次轮询或回复时中止。 - - 如果日志包含 `Polling stall detected`，默认情况下，OpenClaw 会在 120 秒内没有完成长轮询存活性检测后重启轮询并重建 Telegram 传输。 - - 当正在运行的轮询账号在启动宽限期后尚未完成 `getUpdates`、正在运行的 webhook 账号在启动宽限期后尚未完成 `setWebhook`，或上一次成功的轮询传输活动已过期时，`openclaw channels status --probe` 和 `openclaw doctor` 会发出警告。 - - 仅当长时间运行的 `getUpdates` 调用健康，但你的主机仍报告误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。持续停滞通常指向主机与 `api.telegram.org` 之间的 proxy、DNS、IPv6 或 TLS 出站问题。 - - Telegram 还会遵循 Bot API 传输的进程 proxy 环境变量，包括 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 及其小写变体。`NO_PROXY` / `no_proxy` 仍可绕过 `api.telegram.org`。 - - 如果服务环境通过 `OPENCLAW_PROXY_URL` 配置了 OpenClaw 托管 proxy，且不存在标准 proxy 环境变量，Telegram 也会将该 URL 用于 Bot API 传输。 - - 在直连出站/TLS 不稳定的 VPS 主机上，通过 `channels.telegram.proxy` 路由 Telegram API 调用： + - 在轮询启动期间，OpenClaw 会为 grammY 复用启动时成功的 `getMe` 探测，因此运行器不需要在第一次 `getUpdates` 前再执行第二次 `getMe`。 + - 如果 `deleteWebhook` 在轮询启动期间因暂时性网络错误失败，OpenClaw 会继续进入长轮询，而不是再发起一次预轮询控制平面调用。仍处于活动状态的网络钩子会表现为 `getUpdates` 冲突；随后 OpenClaw 会重建 Telegram 传输层并重试网络钩子清理。 + - 如果 Telegram 套接字按较短的固定周期回收，请检查 `channels.telegram.timeoutSeconds` 是否过低；bot 客户端会将低于出站和 `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 channels: @@ -886,8 +886,8 @@ channels: proxy: socks5://:@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: @@ -896,7 +896,7 @@ channels: autoSelectFamily: false ``` - - 默认情况下，Telegram 媒体下载已允许 RFC 2544 基准测试范围答案（`198.18.0.0/15`）。如果可信的 fake-IP 或透明 proxy 在媒体下载期间将 `api.telegram.org` 重写为其他 private/internal/special-use 地址，你可以选择启用仅限 Telegram 的绕过： + - 默认情况下，Telegram 媒体下载已允许 RFC 2544 基准测试范围解析结果（`198.18.0.0/15`）。如果可信的假 IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写到其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过： ```yaml channels: @@ -905,22 +905,20 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - 同一选择启用项也可按账号设置在 + - 同一选择性启用项也可按账号配置在 `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`。 - - 如果你的 proxy 将 Telegram 媒体主机解析为 `198.18.x.x`，先保持危险标志关闭。Telegram 媒体默认已经允许 RFC 2544 基准测试范围。 + - 如果你的代理将 Telegram 媒体主机解析到 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已允许 RFC 2544 基准测试范围。 `channels.telegram.network.dangerouslyAllowPrivateNetwork` 会削弱 Telegram - 媒体 SSRF 保护。仅在可信的、由操作员控制的 proxy - 环境中使用它，例如 Clash、Mihomo 或 Surge fake-IP 路由，并且这些环境会合成 RFC 2544 基准测试 - 范围之外的私有或特殊用途答案。正常公共互联网 Telegram 访问应保持关闭。 + 媒体 SSRF 防护。仅在可信、由运维方控制的代理环境中使用它，例如 Clash、Mihomo 或 Surge 假 IP 路由，并且它们会合成 RFC 2544 基准测试范围之外的私有或特殊用途解析结果。对于普通公共互联网 Telegram 访问，请保持关闭。 - - 环境覆盖（临时）： + - 环境变量覆盖（临时）： - `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 @@ -936,34 +934,34 @@ dig +short api.telegram.org AAAA 主要参考：[配置参考 - Telegram](/zh-CN/gateway/config-channels#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` +- 线程/回复：`replyToMode`、`dm.threadReplies`、`direct.*.threadReplies` - 流式传输：`streaming`（预览）、`streaming.preview.toolProgress`、`blockStreaming` - 格式化/投递：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix` - 媒体/网络：`mediaMaxMb`、`timeoutSeconds`、`pollingStallThresholdMs`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy` - 自定义 API 根地址：`apiRoot`（仅 Bot API 根地址；不要包含 `/bot`） -- webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost` -- actions/能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker` -- reactions：`reactionNotifications`、`reactionLevel` +- 网络钩子：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost` +- 操作/能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker` +- 表情回应：`reactionNotifications`、`reactionLevel` - 错误：`errorPolicy`、`errorCooldownMs` -- 写入/历史：`configWrites`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` +- 写入/历史记录：`configWrites`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` -多账号优先级：配置两个或更多账号 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.*` 值。 ## 相关内容 - 将 Telegram 用户与 Gateway 网关配对。 + 将 Telegram 用户配对到 Gateway 网关。 群组和话题允许列表行为。