diff --git a/docs/zh-CN/channels/telegram.md b/docs/zh-CN/channels/telegram.md index 1d876a468..b0151d3cd 100644 --- a/docs/zh-CN/channels/telegram.md +++ b/docs/zh-CN/channels/telegram.md @@ -1,18 +1,18 @@ --- read_when: - - 开发 Telegram 功能或网络钩子 -summary: Telegram 机器人支持状态、能力和配置 + - 处理 Telegram 功能或网页钩子 +summary: Telegram 机器人支持状态、功能和配置 title: Telegram x-i18n: - generated_at: "2026-04-29T14:46:33Z" + generated_at: "2026-04-30T12:42:10Z" model: gpt-5.5 provider: openai - source_hash: 1ffc0c1a6bb94fbab81ede0f08b0e3a165f06c599d4d06d4b9e70c8ba41121f7 + source_hash: 5df2a27a801183b2817beca228c41c04f855ef08720f6c7505b49eae22ea303d source_path: channels/telegram.md workflow: 16 --- -可通过 grammY 用于生产环境中的 bot 私信和群组。默认模式是长轮询；webhook 模式为可选。 +可用于 bot 私信和群组的生产级配置，基于 grammY。长轮询是默认模式；webhook 模式可选。 @@ -30,7 +30,7 @@ x-i18n: - 打开 Telegram 并与 **@BotFather** 对话（确认账号名完全是 `@BotFather`）。 + 打开 Telegram 并与 **@BotFather** 聊天（确认 handle 正好是 `@BotFather`）。 运行 `/newbot`，按提示操作，并保存 token。 @@ -52,7 +52,7 @@ x-i18n: ``` 环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账户）。 - Telegram **不**使用 `openclaw channels login telegram`；请在配置或环境变量中配置 token，然后启动 Gateway 网关。 + Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置 token，然后启动 Gateway 网关。 @@ -64,7 +64,7 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - 配对码会在 1 小时后过期。 + 配对代码会在 1 小时后过期。 @@ -74,14 +74,14 @@ openclaw pairing approve telegram -token 解析顺序是账户感知的。实际上，配置值优先于环境变量回退，并且 `TELEGRAM_BOT_TOKEN` 仅适用于默认账户。 +Token 解析顺序与账户相关。实际使用中，配置值优先于环境变量回退，且 `TELEGRAM_BOT_TOKEN` 仅适用于默认账户。 -## Telegram 端设置 +## Telegram 侧设置 - Telegram bot 默认启用**隐私模式**，这会限制它们能接收的群组消息。 + Telegram bot 默认使用**隐私模式**，这会限制它们接收的群组消息。 如果 bot 必须看到所有群组消息，可以： @@ -95,13 +95,13 @@ token 解析顺序是账户感知的。实际上，配置值优先于环境变 管理员状态在 Telegram 群组设置中控制。 - 管理员 bot 会接收所有群组消息，这对始终开启的群组行为很有用。 + 管理员 bot 会接收所有群组消息，这对常驻群组行为很有用。 - - `/setjoingroups` 用于允许或拒绝添加到群组 + - `/setjoingroups` 用于允许/拒绝添加到群组 - `/setprivacy` 用于群组可见性行为 @@ -118,21 +118,21 @@ token 解析顺序是账户感知的。实际上，配置值优先于环境变 - `open`（要求 `allowFrom` 包含 `"*"`） - `disabled` - `dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 会让任何找到或猜到 bot 用户名的 Telegram 账户都能向 bot 发送命令。仅应将它用于有意公开且工具严格受限的 bot；单所有者 bot 应使用带有数字用户 ID 的 `allowlist`。 + `dmPolicy: "open"` 与 `allowFrom: ["*"]` 会让任何找到或猜到 bot 用户名的 Telegram 账户都能命令该 bot。仅应将其用于有严格受限工具的、有意公开的 bot；单所有者 bot 应使用带数字用户 ID 的 `allowlist`。 `channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。`telegram:` / `tg:` 前缀会被接受并规范化。 - 在多账户配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：除非合并后的有效账户 allowlist 仍包含显式通配符，否则账户级 `allowFrom: ["*"]` 条目不会让该账户公开。 - `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: ["*"]` 条目不会让该账户公开，除非合并后的有效账户 allowlist 仍包含显式通配符。 + `dmPolicy: "allowlist"` 与空的 `allowFrom` 会阻止所有私信，并会被配置校验拒绝。 + 设置流程只要求数字用户 ID。 + 如果你已升级且配置中包含 `@username` allowlist 条目，请运行 `openclaw doctor --fix` 解析它们（尽力而为；需要 Telegram bot token）。 + 如果你之前依赖配对存储 allowlist 文件，`openclaw doctor --fix` 可以在 allowlist 流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 尚无显式 ID 时）。 - 对于单所有者 bot，优先使用带有显式数字 `allowFrom` ID 的 `dmPolicy: "allowlist"`，以便在配置中保持访问策略持久（而不是依赖之前的配对批准）。 + 对于单所有者 bot，优先使用带显式数字 `allowFrom` ID 的 `dmPolicy: "allowlist"`，以便在配置中持久化访问策略（而不是依赖之前的配对批准）。 - 常见混淆：私信配对批准并不表示“此发送者在所有地方都已授权”。 - 配对授予私信访问权限。如果还没有命令所有者，第一次批准的配对也会设置 `commands.ownerAllowFrom`，以便仅所有者命令和 exec 批准拥有显式操作员账户。 + 常见误解：私信配对批准并不意味着“此发送者在所有地方都已授权”。 + 配对授予私信访问权限。如果还没有命令所有者，第一个被批准的配对还会设置 `commands.ownerAllowFrom`，使仅所有者命令和 exec 批准拥有显式操作员账户。 群组发送者授权仍来自显式配置 allowlist。 - 如果你希望“我授权一次后，私信和群组命令都能工作”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:`。 + 如果你想要“我授权一次后私信和群组命令都能工作”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:`。 ### 查找你的 Telegram 用户 ID @@ -148,16 +148,16 @@ token 解析顺序是账户感知的。实际上，配置值优先于环境变 curl "https://api.telegram.org/bot/getUpdates" ``` - 第三方方法（隐私较低）：`@userinfobot` 或 `@getidsbot`。 + 第三方方法（隐私性较低）：`@userinfobot` 或 `@getidsbot`。 - 两个控制项会一起生效： + 两个控制项会共同生效： 1. **允许哪些群组**（`channels.telegram.groups`） - 没有 `groups` 配置： - - 使用 `groupPolicy: "open"`：任何群组都能通过群组 ID 检查 + - 使用 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查 - 使用 `groupPolicy: "allowlist"`（默认）：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`） - 已配置 `groups`：作为 allowlist（显式 ID 或 `"*"`） @@ -168,15 +168,15 @@ curl "https://api.telegram.org/bot/getUpdates" `groupAllowFrom` 用于群组发送者过滤。如果未设置，Telegram 会回退到 `allowFrom`。 `groupAllowFrom` 条目应为数字 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被规范化）。 - 不要将 Telegram 群组或超级群组 chat ID 放入 `groupAllowFrom`。负数 chat ID 属于 `channels.telegram.groups`。 - 非数字条目会被发送者授权忽略。 + 不要将 Telegram 群组或超级群组 chat ID 放入 `groupAllowFrom`。负数 chat ID 应放在 `channels.telegram.groups` 下。 + 非数字条目会被忽略，不用于发送者授权。 安全边界（`2026.2.25+`）：群组发送者鉴权**不会**继承私信配对存储批准。 配对仅适用于私信。对于群组，请设置 `groupAllowFrom` 或每群组/每话题的 `allowFrom`。 - 如果未设置 `groupAllowFrom`，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。 + 如果未设置 `groupAllowFrom`，Telegram 会回退到配置 `allowFrom`，而不是配对存储。 单所有者 bot 的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。 - 运行时说明：如果完全缺少 `channels.telegram`，除非显式设置了 `channels.defaults.groupPolicy`，否则运行时默认采用故障关闭的 `groupPolicy="allowlist"`。 + 运行时注意事项：如果完全缺失 `channels.telegram`，除非显式设置了 `channels.defaults.groupPolicy`，运行时默认会以故障关闭方式使用 `groupPolicy="allowlist"`。 - 示例：允许一个特定群组中的任意成员： + 示例：允许一个特定群组中的任何成员： ```json5 { @@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 示例：只允许一个特定群组内的特定用户： + 示例：只允许一个特定群组中的特定用户： ```json5 { @@ -214,8 +214,8 @@ curl "https://api.telegram.org/bot/getUpdates" 常见错误：`groupAllowFrom` 不是 Telegram 群组 allowlist。 - 将像 `-1001234567890` 这样的负数 Telegram 群组或超级群组 chat ID 放在 `channels.telegram.groups` 下。 - - 当你想限制已允许群组内哪些人可以触发 bot 时，将像 `8734062810` 这样的 Telegram 用户 ID 放在 `groupAllowFrom` 下。 - - 仅当你希望已允许群组中的任何成员都能与 bot 对话时，才使用 `groupAllowFrom: ["*"]`。 + - 当你想限制允许群组内哪些人可以触发 bot 时，将像 `8734062810` 这样的 Telegram 用户 ID 放在 `groupAllowFrom` 下。 + - 仅当你希望允许群组中的任何成员都能与 bot 对话时，才使用 `groupAllowFrom: ["*"]`。 @@ -227,7 +227,7 @@ curl "https://api.telegram.org/bot/getUpdates" 提及可以来自： - 原生 `@botusername` 提及，或 - - 以下位置的提及模式： + - 以下位置中的提及模式： - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` @@ -236,9 +236,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `/activation always` - `/activation mention` - 这些只更新会话状态。使用配置实现持久化。 + 这些只会更新会话状态。使用配置实现持久化。 - 持久配置示例： + 持久化配置示例： ```json5 { @@ -255,7 +255,7 @@ curl "https://api.telegram.org/bot/getUpdates" 获取群组 chat 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 用于回复。 -- 长轮询使用 grammY runner，并按 chat/线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。 -- 长轮询在每个 Gateway 网关进程内受到保护，因此同一时间只有一个活动 poller 可以使用一个 bot token。如果你仍然看到 `getUpdates` 409 冲突，可能是另一个 OpenClaw Gateway 网关、脚本或外部 poller 正在使用同一个 token。 -- 默认情况下，长轮询 watchdog 会在 120 秒内没有完成 `getUpdates` 活性检查后触发重启。仅当你的部署在长时间运行工作期间仍出现误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持每账户覆盖。 +- 群组会话按群组 ID 隔离。论坛话题会追加 `:topic:`，以保持话题隔离。 +- 私信消息可以携带 `message_thread_id`；OpenClaw 会使用线程感知的会话键进行路由，并保留线程 ID 以用于回复。 +- 长轮询使用 grammY runner，并按每个聊天/每个线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。 +- 每个 Gateway 网关进程内都会保护长轮询，确保同一时间只有一个活跃 poller 能使用一个 bot token。如果你仍看到 `getUpdates` 409 冲突，另一个 OpenClaw Gateway 网关、脚本或外部 poller 很可能正在使用同一 token。 +- 默认情况下，长轮询 watchdog 会在 120 秒没有完成的 `getUpdates` 存活信号后触发重启。仅当你的部署在长时间运行工作期间仍出现误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账户覆盖。 - Telegram Bot API 不支持已读回执（`sendReadReceipts` 不适用）。 ## 功能参考 - + OpenClaw 可以实时流式传输部分回复： - 直接聊天：预览消息 + `editMessageText` @@ -285,11 +285,11 @@ curl "https://api.telegram.org/bot/getUpdates" 要求： - `channels.telegram.streaming` 为 `off | partial | block | progress`（默认：`partial`） - - 在 Telegram 上，`progress` 映射为 `partial`（兼容跨渠道命名） + - `progress` 在 Telegram 上映射到 `partial`（与跨渠道命名兼容） - `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑的预览消息（默认：预览流式传输启用时为 `true`） - - 会检测旧版 `channels.telegram.streamMode` 和布尔值 `streaming`；运行 `openclaw doctor --fix` 将它们迁移到 `channels.telegram.streaming.mode` + - 旧版 `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,18 +306,16 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 仅当你需要只交付最终内容时，才使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，并且通用工具/进度杂音会被抑制，而不是作为独立的“Working...”消息发送。批准提示、媒体载荷和错误仍通过正常最终交付路由。仅当你想保留答案预览编辑，同时隐藏工具进度状态行时，才使用 `streaming.preview.toolProgress: false`。 + 仅当你想要只交付最终消息时，才使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，通用工具/进度闲聊会被抑制，而不是作为独立的 “Working...” 消息发送。批准提示、媒体载荷和错误仍会通过正常最终交付路由。仅当你只想保留答案预览编辑，同时隐藏工具进度状态行时，才使用 `streaming.preview.toolProgress: false`。 - 对于纯文本回复： + 对于仅文本回复： - - 简短的私信/群组/主题预览：OpenClaw 保留同一条预览消息，并在原位执行最终编辑 - - 早于约一分钟的预览：OpenClaw 会将完成的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间 + - 简短私信/群组/topic 预览：OpenClaw 保留同一条预览消息，并在原处执行最终编辑 + - 早于约一分钟的预览：OpenClaw 会将完成后的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间 对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常的最终投递，然后清理预览消息。 - 预览流式传输独立于分块流式传输。当为 Telegram 明确启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 - - 如果原生草稿传输不可用或被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。 + 预览流式传输独立于分块流式传输。当 Telegram 明确启用分块流式传输时，OpenClaw 会跳过预览流，以避免重复流式传输。 仅限 Telegram 的推理流： @@ -361,7 +359,7 @@ curl "https://api.telegram.org/bot/getUpdates" 规则： - - 名称会被规范化（去掉开头的 `/`，转换为小写） + - 名称会被规范化（去除开头的 `/`，转为小写） - 有效模式：`a-z`、`0-9`、`_`，长度 `1..32` - 自定义命令不能覆盖原生命令 - 冲突/重复项会被跳过并记录日志 @@ -369,39 +367,39 @@ curl "https://api.telegram.org/bot/getUpdates" 注意： - 自定义命令只是菜单项；它们不会自动实现行为 - - 插件/Skills 命令即使未显示在 Telegram 菜单中，输入时仍然可以工作 + - 即使未显示在 Telegram 菜单中，插件/Skills 命令在输入时仍然可以工作 - 如果禁用原生命令，内置命令会被移除。自定义/插件命令在配置后仍可能注册。 + 如果禁用原生命令，内置命令会被移除。自定义/插件命令在配置后仍可注册。 常见设置失败： - - `setMyCommands failed` 并带有 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 菜单在裁剪后仍然溢出；减少插件/Skills/自定义命令，或禁用 `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 菜单在裁剪后仍然超出限制；减少插件/Skills/自定义命令，或禁用 `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 拒绝了配置的 bot token。请使用当前 BotFather token 更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。 + - `setMyCommands failed` 且包含网络/fetch 错误，通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。 ### 设备配对命令（`device-pair` 插件） 安装 `device-pair` 插件后： 1. `/pair` 生成设置代码 - 2. 在 iOS app 中粘贴代码 - 3. `/pair pending` 列出待处理请求（包括角色/范围） + 2. 将代码粘贴到 iOS 应用中 + 3. `/pair pending` 列出待处理请求（包括角色/作用域） 4. 批准请求： - - `/pair approve ` 用于显式批准 - - 只有一个待处理请求时使用 `/pair approve` + - `/pair approve ` 用于明确批准 + - `/pair approve` 用于只有一个待处理请求的情况 - `/pair approve latest` 用于最近的请求 - 设置代码携带一个短期有效的 bootstrap 令牌。内置 bootstrap 交接会将主节点令牌保持在 `scopes: []`；任何被交接的操作员令牌仍限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write` 内。Bootstrap 范围检查带有角色前缀，因此该操作员 allowlist 只满足操作员请求；非操作员角色仍需要其自身角色前缀下的范围。 + 设置代码携带短期有效的 bootstrap token。内置 bootstrap handoff 会将主节点 token 保持在 `scopes: []`；任何移交的 operator token 都会被限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。Bootstrap 作用域检查带有角色前缀，因此该 operator allowlist 只满足 operator 请求；非 operator 角色仍需要其自身角色前缀下的作用域。 - 如果设备用已更改的认证详细信息重试（例如角色/范围/公钥），先前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。 + 如果设备使用变更后的认证详细信息重试（例如角色/作用域/公钥），之前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。 更多详情：[配对](/zh-CN/channels/pairing#pair-via-telegram-recommended-for-ios)。 - 配置内联键盘范围： + 配置内联键盘作用域： ```json5 { @@ -433,7 +431,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 范围： + 作用域： - `off` - `dm` @@ -443,7 +441,7 @@ curl "https://api.telegram.org/bot/getUpdates" 旧版 `capabilities: ["inlineButtons"]` 会映射到 `inlineButtons: "all"`。 - 消息动作示例： + 消息操作示例： ```json5 { @@ -461,33 +459,33 @@ 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`）。 门控控制： - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - - `channels.telegram.actions.sticker`（默认：已禁用） + - `channels.telegram.actions.sticker`（默认：禁用） 注意：`edit` 和 `topic-create` 目前默认启用，并且没有单独的 `channels.telegram.actions.*` 开关。 - 运行时发送使用活动的配置/密钥快照（启动/重载），因此动作路径不会在每次发送时执行临时 SecretRef 重新解析。 + 运行时发送使用活动配置/密钥快照（启动/重载），因此操作路径不会在每次发送时执行临时 SecretRef 重新解析。 - 移除回应的语义：[/tools/reactions](/zh-CN/tools/reactions) + 反应移除语义：[/tools/reactions](/zh-CN/tools/reactions) @@ -503,29 +501,29 @@ 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_*]]` 标签仍会被遵循。 + 注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会生效。 - + 论坛超级群组： - - 主题会话键追加 `:topic:` - - 回复和输入状态会定向到主题线程 - - 主题配置路径： + - topic 会话键会追加 `:topic:` + - 回复和输入状态会指向 topic 线程 + - topic 配置路径： `channels.telegram.groups..topics.` - General 主题（`threadId=1`）特例： + 常规 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,26 +543,26 @@ curl "https://api.telegram.org/bot/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 智能体](/zh-CN/tools/acp-agents)。 + **持久 ACP topic 绑定**：论坛 topic 可以通过顶层类型化 ACP 绑定（`bindings[]`，其中 `type: "acp"`、`match.channel: "telegram"`、`peer.kind: "group"`，以及类似 `-1001234567890:topic:42` 的 topic 限定 id）固定 ACP harness 会话。目前作用域限制在群组/超级群组中的论坛 topic。参见 [ACP Agents](/zh-CN/tools/acp-agents)。 - **从聊天生成线程绑定的 ACP**：`/acp spawn --thread here|auto` 会将当前主题绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在主题内固定生成确认消息。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。 + **从聊天发起线程绑定的 ACP spawn**：`/acp spawn --thread here|auto` 会将当前 topic 绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在 topic 内置顶 spawn 确认消息。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。 - 模板上下文公开 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天保持私信路由，但使用感知线程的会话键。 + 模板上下文会暴露 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天会保留私信路由，但使用线程感知的会话键。 ### 音频消息 - Telegram 区分语音便笺和音频文件。 + Telegram 区分语音留言和音频文件。 - 默认：音频文件行为 - - 在智能体回复中使用标签 `[[audio_as_voice]]` 可强制按语音便笺发送 - - 入站语音便笺转录会在智能体上下文中被框定为机器生成的、不受信任的文本；提及检测仍使用原始转录，因此由提及门控的语音消息会继续工作。 + - 在智能体回复中使用标签 `[[audio_as_voice]]` 强制作为语音留言发送 + - 入站语音留言转录会在智能体上下文中被框定为机器生成的、不受信任文本；提及检测仍然使用原始转录，因此受提及门控的语音消息会继续工作。 - 消息动作示例： + 消息操作示例： ```json5 { @@ -578,9 +576,9 @@ curl "https://api.telegram.org/bot/getUpdates" ### 视频消息 - Telegram 区分视频文件和视频便笺。 + Telegram 区分视频文件和视频留言。 - 消息动作示例： + 消息操作示例： ```json5 { @@ -592,7 +590,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 视频便笺不支持说明；提供的消息文本会单独发送。 + 视频留言不支持标题；提供的消息文本会单独发送。 ### 贴纸 @@ -614,9 +612,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - 贴纸会被描述一次（在可行时），并被缓存以减少重复视觉调用。 + 贴纸会被描述一次（在可能时）并缓存，以减少重复的视觉调用。 - 启用贴纸动作： + 启用贴纸操作： ```json5 { @@ -630,7 +628,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 发送贴纸动作： + 发送贴纸操作： ```json5 { @@ -654,31 +652,31 @@ curl "https://api.telegram.org/bot/getUpdates" - - Telegram 回应会以 `message_reaction` 更新到达（与消息载荷分开）。 + + 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`。 - + `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。 解析顺序： @@ -686,17 +684,17 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - 智能体身份表情符号兜底（`agents.list[].identity.emoji`，否则为 "👀"） + - 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"） 注意事项： - Telegram 期望 unicode 表情符号（例如 "👀"）。 - - 使用 `""` 可为某个渠道或账号禁用回应。 + - 使用 `""` 可禁用某个渠道或账号的表态回应。 - 默认启用渠道配置写入（`configWrites !== false`）。 + 渠道配置写入默认启用（`configWrites !== false`）。 Telegram 触发的写入包括： @@ -718,28 +716,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"`。 + 本地监听器绑定到 `127.0.0.1:8787`。对于公网入口，可以在本地端口前放置反向代理，或有意设置 `webhookHost: "0.0.0.0"`。 Webhook 模式会先验证请求保护、Telegram secret token 和 JSON 正文，然后再向 Telegram 返回 `200`。 - OpenClaw 随后会通过长轮询使用的同一套按聊天/按话题机器人通道异步处理更新，因此缓慢的智能体轮次不会阻塞 Telegram 的投递 ACK。 + OpenClaw 随后会通过与长轮询相同的按聊天/按话题机器人通道异步处理该更新，因此较慢的智能体轮次不会占用 Telegram 的投递 ACK。 - `channels.telegram.textChunkLimit` 默认值为 4000。 - - `channels.telegram.chunkMode="newline"` 在按长度拆分前优先使用段落边界（空行）。 + - `channels.telegram.chunkMode="newline"` 会优先按段落边界（空行）拆分，再按长度拆分。 - `channels.telegram.mediaMaxMb`（默认 100）限制入站和出站 Telegram 媒体大小。 - - `channels.telegram.timeoutSeconds` 覆盖 Telegram API 客户端超时（如果未设置，则应用 grammY 默认值）。 - - `channels.telegram.pollingStallThresholdMs` 默认值为 `120000`；仅针对误报的轮询停滞重启，在 `30000` 到 `600000` 之间调整。 + - `channels.telegram.timeoutSeconds` 覆盖 Telegram API 客户端超时时间（未设置时使用 grammY 默认值）。 + - `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` 配置应用于 Telegram 发送辅助工具（CLI/工具/操作），用于可恢复的出站 API 错误。入站最终回复投递也会对 Telegram 预连接失败使用有界的安全发送重试，但不会重试可能重复可见消息的、语义不明确的发送后网络信封。 + - `channels.telegram.retry` 配置适用于 Telegram 发送辅助函数（CLI/工具/动作）中可恢复的出站 API 错误。入站最终回复投递也会对 Telegram 预连接失败使用有界安全发送重试，但不会重试可能导致可见消息重复的模糊发送后网络信封。 CLI 发送目标可以是数字聊天 ID 或用户名： @@ -758,7 +756,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - 仅限 Telegram 的投票标志： + 仅 Telegram 使用的投票标志： - `--poll-duration-seconds`（5-600） - `--poll-anonymous` @@ -767,48 +765,48 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ Telegram 发送还支持： - - 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带 `buttons` 块的 `--presentation` 来创建内联键盘 + - 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带 `buttons` 块的 `--presentation` 来发送内联键盘 - 当机器人可以在该聊天中置顶时，使用 `--pin` 或 `--delivery '{"pin":true}'` 请求置顶投递 - - 使用 `--force-document` 将出站图片和 GIF 作为文档发送，而不是压缩照片或动画媒体上传 + - 使用 `--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 投票创建，同时保留常规发送启用状态 - - Telegram 支持在审批人私信中进行 exec 审批，也可以选择在原始聊天或话题中发布提示。审批人必须是数字 Telegram 用户 ID。 + + Telegram 支持在审批者私信中执行审批，也可以选择在原始聊天或话题中发布提示。审批者必须是数字 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` 中的数字所有者 ID） + - `channels.telegram.execApprovals.target`：`dm`（默认）| `channel` | `both` - `agentFilter`、`sessionFilter` - `channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制谁可以和机器人对话，以及机器人将普通回复发送到哪里。它们不会让某人成为 exec 审批人。当还没有命令所有者时，首次获批的私信配对会引导生成 `commands.ownerAllowFrom`，因此单所有者设置仍可工作，而无需在 `execApprovals.approvers` 下重复 ID。 + `channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制谁可以与机器人对话，以及机器人在哪里发送普通回复。它们不会让某人成为执行审批者。当尚不存在命令所有者时，第一次获批准的私信配对会引导生成 `commands.ownerAllowFrom`，因此单所有者设置仍然无需在 `execApprovals.approvers` 下重复 ID 即可工作。 - 渠道投递会在聊天中显示命令文本；仅在可信群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。Exec 审批默认在 30 分钟后过期。 + 渠道投递会在聊天中显示命令文本；仅在可信群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。执行审批默认在 30 分钟后过期。 - 内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。带有 `plugin:` 前缀的审批 ID 会通过插件审批解析；其他 ID 会先通过 exec 审批解析。 + 内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。带 `plugin:` 前缀的审批 ID 会通过插件审批解析；其他 ID 会先通过执行审批解析。 - 参见 [Exec 审批](/zh-CN/tools/exec-approvals)。 + 参见 [执行审批](/zh-CN/tools/exec-approvals)。 ## 错误回复控制 -当智能体遇到投递或提供商错误时，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 { @@ -829,53 +827,53 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## 故障排除 - + - 如果 `requireMention=false`，Telegram 隐私模式必须允许完整可见性。 - - BotFather：`/setprivacy` -> Disable - - 然后将机器人从群组中移除并重新添加 + - BotFather：`/setprivacy` -> 禁用 + - 然后将机器人从群组移除并重新添加 - 当配置期望未提及的群组消息时，`openclaw channels status` 会发出警告。 - - `openclaw channels status --probe` 可以检查显式数字群组 ID；通配符 `"*"` 无法探测成员身份。 + - `openclaw channels status --probe` 可以检查显式数字群组 ID；通配符 `"*"` 无法探测成员资格。 - 快速会话测试：`/activation always`。 - - 当 `channels.telegram.groups` 存在时，群组必须列出（或包含 `"*"`） - - 验证机器人在群组中的成员身份 - - 查看日志：`openclaw logs --follow`，了解跳过原因 + - 当 `channels.telegram.groups` 存在时，群组必须被列出（或包含 `"*"`） + - 验证机器人在群组中的成员资格 + - 查看日志：使用 `openclaw logs --follow` 查看跳过原因 - 授权你的发送者身份（配对和/或数字 `allowFrom`） - - 即使群组策略是 `open`，命令授权仍然适用 - - `setMyCommands failed` 并带有 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目太多；减少插件/skill/自定义命令，或禁用原生菜单 - - 启动时的 `deleteMyCommands` / `setMyCommands` 调用是有界的，并会在请求超时时通过 Telegram 的传输回退重试一次。持续的网络/fetch 错误通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性存在问题 + - 即使群组策略为 `open`，命令授权仍然适用 + - `setMyCommands failed` 并带有 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生命令菜单 + - `deleteMyCommands` / `setMyCommands` 启动调用是有界的，并会在请求超时时通过 Telegram 的传输回退重试一次。持续的网络/fetch 错误通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性问题 - + - - `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 调用。 - - 如果 `deleteWebhook` 在轮询启动期间因瞬时网络错误失败，OpenClaw 会检查 `getWebhookInfo`；当 Telegram 报告空 webhook URL 时，轮询会继续，因为清理已经满足。 + - `getMe returned 401` 是配置的机器人令牌发生 Telegram 身份验证失败。 + - 在 BotFather 中重新复制或重新生成机器人令牌，然后更新默认账号的 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts..botToken` 或 `TELEGRAM_BOT_TOKEN`。 + - 启动期间出现 `deleteWebhook 401 Unauthorized` 也是身份验证失败；将其视为“没有 webhook 存在”只会把同一个错误令牌失败延后到后续 API 调用。 + - 如果轮询启动期间 `deleteWebhook` 因临时网络错误失败，OpenClaw 会检查 `getWebhookInfo`；当 Telegram 报告 webhook URL 为空时，轮询会继续，因为清理条件已满足。 - - Node 22+ + 自定义 fetch/proxy 可能会在 AbortSignal 类型不匹配时触发立即中止行为。 - - 一些主机会先把 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出站可能导致 Telegram API 间歇性失败。 - - 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些作为可恢复的网络错误重试。 - - 如果日志包含 `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 现在会将这些错误作为可恢复网络错误重试。 + - 如果日志包含 `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 @@ -894,7 +892,9 @@ channels: autoSelectFamily: false ``` - - RFC 2544 基准范围答案（`198.18.0.0/15`）默认已经允许用于 Telegram 媒体下载。如果受信任的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写为其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过： + - 默认已允许 Telegram 媒体下载使用 RFC 2544 基准范围应答（`198.18.0.0/15`）。 + 如果受信任的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写为其他 + 私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过： ```yaml channels: @@ -903,18 +903,22 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - 同一选择性启用也可按账号设置在 `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`。 - - 如果你的代理将 Telegram 媒体主机解析为 `198.18.x.x`，请先关闭危险标志。Telegram 媒体默认已允许 RFC 2544 基准范围。 + - 同样的可选启用项也可按账号配置在 + `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`。 + - 如果你的代理将 Telegram 媒体主机解析为 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已允许 RFC 2544 + 基准范围。 - `channels.telegram.network.dangerouslyAllowPrivateNetwork` 会削弱 Telegram 媒体 SSRF 防护。仅在受信任、由操作员控制的代理环境中使用，例如 Clash、Mihomo 或 Surge fake-IP 路由，并且它们会合成 RFC 2544 基准范围之外的私有或特殊用途答案。正常公共互联网 Telegram 访问请保持关闭。 + `channels.telegram.network.dangerouslyAllowPrivateNetwork` 会削弱 Telegram + 媒体 SSRF 防护。仅在受信任且由操作方控制的代理环境中使用它，例如 Clash、Mihomo 或 Surge fake-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 @@ -932,35 +936,35 @@ dig +short api.telegram.org AAAA -- 启动/认证：`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` +- 话题串/回复：`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`） - webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost` - 操作/能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - reactions：`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 网关。 - 群组和 topic 允许列表行为。 + 群组和话题允许列表行为。 将入站消息路由到智能体。 @@ -969,7 +973,7 @@ dig +short api.telegram.org AAAA 威胁模型与加固。 - 将群组和 topic 映射到智能体。 + 将群组和话题映射到智能体。 跨渠道诊断。