From b4bb36ca9060926b695fd39ec5af4de0f617dc6d Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 30 Apr 2026 15:20:23 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/telegram.md | 383 ++++++++++++++++---------------- docs/zh-CN/concepts/messages.md | 88 ++++---- 2 files changed, 237 insertions(+), 234 deletions(-) diff --git a/docs/zh-CN/channels/telegram.md b/docs/zh-CN/channels/telegram.md index b0151d3cd..b4a27c9e1 100644 --- a/docs/zh-CN/channels/telegram.md +++ b/docs/zh-CN/channels/telegram.md @@ -1,25 +1,25 @@ --- read_when: - - 处理 Telegram 功能或网页钩子 + - 处理 Telegram 功能或 Webhook summary: Telegram 机器人支持状态、功能和配置 title: Telegram x-i18n: - generated_at: "2026-04-30T12:42:10Z" + generated_at: "2026-04-30T15:18:33Z" model: gpt-5.5 provider: openai - source_hash: 5df2a27a801183b2817beca228c41c04f855ef08720f6c7505b49eae22ea303d + source_hash: d18ca6c7ab39d7d34848c562857661501d8364329f6e5a266213aa23846047dd source_path: channels/telegram.md workflow: 16 --- -可用于 bot 私信和群组的生产级配置，基于 grammY。长轮询是默认模式；webhook 模式可选。 +可用于生产环境中的 bot 私信和群组，基于 grammY。长轮询是默认模式；webhook 模式是可选的。 Telegram 的默认私信策略是配对。 - 跨渠道诊断和修复手册。 + 跨渠道诊断和修复操作手册。 完整的渠道配置模式和示例。 @@ -30,9 +30,9 @@ x-i18n: - 打开 Telegram 并与 **@BotFather** 聊天（确认 handle 正好是 `@BotFather`）。 + 打开 Telegram 并与 **@BotFather** 聊天（确认账号名完全是 `@BotFather`）。 - 运行 `/newbot`，按提示操作，并保存 token。 + 运行 `/newbot`，按照提示操作，并保存 token。 @@ -51,12 +51,12 @@ x-i18n: } ``` - 环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账户）。 + 环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账号）。 Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置 token，然后启动 Gateway 网关。 - + ```bash openclaw gateway @@ -64,20 +64,20 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - 配对代码会在 1 小时后过期。 + 配对码会在 1 小时后过期。 - 将 bot 添加到你的群组，然后设置 `channels.telegram.groups` 和 `groupPolicy` 以匹配你的访问模型。 + 将 bot 添加到你的群组，然后设置 `channels.telegram.groups` 和 `groupPolicy`，使其与你的访问模型匹配。 -Token 解析顺序与账户相关。实际使用中，配置值优先于环境变量回退，且 `TELEGRAM_BOT_TOKEN` 仅适用于默认账户。 +token 解析顺序是账号感知的。实际使用中，配置值优先于环境变量回退，并且 `TELEGRAM_BOT_TOKEN` 只适用于默认账号。 -## Telegram 侧设置 +## Telegram 端设置 @@ -88,14 +88,14 @@ Token 解析顺序与账户相关。实际使用中，配置值优先于环境 - 通过 `/setprivacy` 禁用隐私模式，或 - 将 bot 设为群组管理员。 - 切换隐私模式时，请在每个群组中移除并重新添加 bot，以便 Telegram 应用更改。 + 切换隐私模式时，请在每个群组中移除并重新添加 bot，以便 Telegram 应用该变更。 管理员状态在 Telegram 群组设置中控制。 - 管理员 bot 会接收所有群组消息，这对常驻群组行为很有用。 + 管理员 bot 会接收所有群组消息，这对始终在线的群组行为很有用。 @@ -118,27 +118,27 @@ 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` 会被视为安全边界：账户级 `allowFrom: ["*"]` 条目不会让该账户公开，除非合并后的有效账户 allowlist 仍包含显式通配符。 - `dmPolicy: "allowlist"` 与空的 `allowFrom` 会阻止所有私信，并会被配置校验拒绝。 - 设置流程只要求数字用户 ID。 - 如果你已升级且配置中包含 `@username` allowlist 条目，请运行 `openclaw doctor --fix` 解析它们（尽力而为；需要 Telegram bot token）。 - 如果你之前依赖配对存储 allowlist 文件，`openclaw doctor --fix` 可以在 allowlist 流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 尚无显式 ID 时）。 + 在多账号配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：账号级 `allowFrom: ["*"]` 条目不会让该账号公开，除非合并后的有效账号允许列表仍包含显式通配符。 + `dmPolicy: "allowlist"` 搭配空的 `allowFrom` 会阻止所有私信，并会被配置验证拒绝。 + 设置只会要求数字用户 ID。 + 如果你升级后配置中包含 `@username` 允许列表条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram bot token）。 + 如果你之前依赖配对存储允许列表文件，`openclaw doctor --fix` 可以在允许列表流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 还没有显式 ID 时）。 - 对于单所有者 bot，优先使用带显式数字 `allowFrom` ID 的 `dmPolicy: "allowlist"`，以便在配置中持久化访问策略（而不是依赖之前的配对批准）。 + 对于单一所有者 bot，建议使用 `dmPolicy: "allowlist"` 并配置显式数字 `allowFrom` ID，以便将访问策略持久保存在配置中（而不是依赖之前的配对批准）。 - 常见误解：私信配对批准并不意味着“此发送者在所有地方都已授权”。 - 配对授予私信访问权限。如果还没有命令所有者，第一个被批准的配对还会设置 `commands.ownerAllowFrom`，使仅所有者命令和 exec 批准拥有显式操作员账户。 - 群组发送者授权仍来自显式配置 allowlist。 - 如果你想要“我授权一次后私信和群组命令都能工作”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:`。 + 常见困惑：私信配对批准并不表示“此发送者在任何地方都已授权”。 + 配对会授予私信访问权限。如果尚未存在命令所有者，第一个获批配对还会设置 `commands.ownerAllowFrom`，让仅所有者命令和 exec 批准拥有显式操作员账号。 + 群组发送者授权仍来自显式配置允许列表。 + 如果你想要“我授权一次后，私信和群组命令都可用”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，确保 `commands.ownerAllowFrom` 包含 `telegram:`。 ### 查找你的 Telegram 用户 ID - 更安全（无第三方 bot）： + 更安全（不使用第三方 bot）： - 1. 私信你的 bot。 + 1. 给你的 bot 发送私信。 2. 运行 `openclaw logs --follow`。 3. 读取 `from.id`。 @@ -152,14 +152,14 @@ curl "https://api.telegram.org/bot/getUpdates" - - 两个控制项会共同生效： + + 两个控制项会一起生效： 1. **允许哪些群组**（`channels.telegram.groups`） - 没有 `groups` 配置： - 使用 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查 - - 使用 `groupPolicy: "allowlist"`（默认）：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`） - - 已配置 `groups`：作为 allowlist（显式 ID 或 `"*"`） + - 使用 `groupPolicy: "allowlist"`（默认）：在你添加 `groups` 条目（或 `"*"`）之前，群组会被阻止 + - 已配置 `groups`：作为允许列表生效（显式 ID 或 `"*"`） 2. **群组中允许哪些发送者**（`channels.telegram.groupPolicy`） - `open` @@ -168,13 +168,13 @@ curl "https://api.telegram.org/bot/getUpdates" `groupAllowFrom` 用于群组发送者过滤。如果未设置，Telegram 会回退到 `allowFrom`。 `groupAllowFrom` 条目应为数字 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被规范化）。 - 不要将 Telegram 群组或超级群组 chat ID 放入 `groupAllowFrom`。负数 chat ID 应放在 `channels.telegram.groups` 下。 - 非数字条目会被忽略，不用于发送者授权。 - 安全边界（`2026.2.25+`）：群组发送者鉴权**不会**继承私信配对存储批准。 - 配对仅适用于私信。对于群组，请设置 `groupAllowFrom` 或每群组/每话题的 `allowFrom`。 - 如果未设置 `groupAllowFrom`，Telegram 会回退到配置 `allowFrom`，而不是配对存储。 - 单所有者 bot 的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。 - 运行时注意事项：如果完全缺失 `channels.telegram`，除非显式设置了 `channels.defaults.groupPolicy`，运行时默认会以故障关闭方式使用 `groupPolicy="allowlist"`。 + 不要把 Telegram 群组或超级群组聊天 ID 放在 `groupAllowFrom` 中。负数聊天 ID 应放在 `channels.telegram.groups` 下。 + 非数字条目会被发送者授权忽略。 + 安全边界（`2026.2.25+`）：群组发送者认证**不会**继承私信配对存储批准。 + 配对仅限私信。对于群组，请设置 `groupAllowFrom` 或每群组/每话题的 `allowFrom`。 + 如果未设置 `groupAllowFrom`，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。 + 单一所有者 bot 的实用模式：在 `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 { @@ -211,11 +211,11 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - 常见错误：`groupAllowFrom` 不是 Telegram 群组 allowlist。 + 常见错误：`groupAllowFrom` 不是 Telegram 群组允许列表。 - - 将像 `-1001234567890` 这样的负数 Telegram 群组或超级群组 chat ID 放在 `channels.telegram.groups` 下。 - - 当你想限制允许群组内哪些人可以触发 bot 时，将像 `8734062810` 这样的 Telegram 用户 ID 放在 `groupAllowFrom` 下。 - - 仅当你希望允许群组中的任何成员都能与 bot 对话时，才使用 `groupAllowFrom: ["*"]`。 + - 将类似 `-1001234567890` 的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。 + - 当你想限制允许群组中哪些人可以触发 bot 时，将类似 `8734062810` 的 Telegram 用户 ID 放在 `groupAllowFrom` 下。 + - 仅在你希望允许群组中的任何成员都能与 bot 对话时，使用 `groupAllowFrom: ["*"]`。 @@ -252,7 +252,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 获取群组 chat ID： + 获取群组聊天 ID： - 将群组消息转发给 `@userinfobot` / `@getidsbot` - 或从 `openclaw logs --follow` 读取 `chat.id` @@ -264,19 +264,19 @@ curl "https://api.telegram.org/bot/getUpdates" ## 运行时行为 - Telegram 由 Gateway 网关进程拥有。 -- 路由是确定性的：Telegram 入站会回复到 Telegram（模型不会选择渠道）。 -- 入站消息会规范化为共享渠道信封，并带有回复元数据和媒体占位符。 -- 群组会话按群组 ID 隔离。论坛话题会追加 `:topic:`，以保持话题隔离。 -- 私信消息可以携带 `message_thread_id`；OpenClaw 会使用线程感知的会话键进行路由，并保留线程 ID 以用于回复。 +- 路由是确定性的：Telegram 入站消息会回复到 Telegram（模型不会选择渠道）。 +- 入站消息会规范化为共享渠道信封，其中包含回复元数据和媒体占位符。 +- 群组会话按群组 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`；支持按账户覆盖。 +- 长轮询在每个 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`） - - `progress` 在 Telegram 上映射到 `partial`（与跨渠道命名兼容） + - 在 Telegram 上，`progress` 映射到 `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,20 +306,20 @@ 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`。 - 对于仅文本回复： + 对于纯文本回复： - - 简短私信/群组/topic 预览：OpenClaw 保留同一条预览消息，并在原处执行最终编辑 - - 早于约一分钟的预览：OpenClaw 会将完成后的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间 + - 短私信/群组/话题预览：OpenClaw 保留同一条预览消息，并在原处执行最终编辑 + - 超过约一分钟的预览：OpenClaw 将完成后的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间 - 对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常的最终投递，然后清理预览消息。 + 对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常的最终送达方式，然后清理预览消息。 - 预览流式传输独立于分块流式传输。当 Telegram 明确启用分块流式传输时，OpenClaw 会跳过预览流，以避免重复流式传输。 + 预览流式传输与分块流式传输是分开的。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 仅限 Telegram 的推理流： - - `/reasoning stream` 会在生成期间将推理发送到实时预览 + - `/reasoning stream` 在生成时将推理发送到实时预览 - 最终答案发送时不包含推理文本 @@ -340,7 +340,7 @@ curl "https://api.telegram.org/bot/getUpdates" 原生命令默认值： - - `commands.native: "auto"` 会为 Telegram 启用原生命令 + - `commands.native: "auto"` 为 Telegram 启用原生命令 添加自定义命令菜单项： @@ -359,7 +359,7 @@ curl "https://api.telegram.org/bot/getUpdates" 规则： - - 名称会被规范化（去除开头的 `/`，转为小写） + - 名称会被规范化（去除开头的 `/`，转换为小写） - 有效模式：`a-z`、`0-9`、`_`，长度 `1..32` - 自定义命令不能覆盖原生命令 - 冲突/重复项会被跳过并记录日志 @@ -367,32 +367,32 @@ curl "https://api.telegram.org/bot/getUpdates" 注意： - 自定义命令只是菜单项；它们不会自动实现行为 - - 即使未显示在 Telegram 菜单中，插件/Skills 命令在输入时仍然可以工作 + - 插件/skill 命令即使未显示在 Telegram 菜单中，在输入时仍可工作 如果禁用原生命令，内置命令会被移除。自定义/插件命令在配置后仍可注册。 常见设置失败： - - `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 被阻止。 + - `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` 并带有网络/抓取错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。 ### 设备配对命令（`device-pair` 插件） 安装 `device-pair` 插件后： 1. `/pair` 生成设置代码 - 2. 将代码粘贴到 iOS 应用中 + 2. 在 iOS 应用中粘贴代码 3. `/pair pending` 列出待处理请求（包括角色/作用域） 4. 批准请求： - - `/pair approve ` 用于明确批准 - - `/pair approve` 用于只有一个待处理请求的情况 + - `/pair approve ` 用于显式批准 + - 只有一个待处理请求时使用 `/pair approve` - `/pair approve latest` 用于最近的请求 - 设置代码携带短期有效的 bootstrap token。内置 bootstrap handoff 会将主节点 token 保持在 `scopes: []`；任何移交的 operator token 都会被限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。Bootstrap 作用域检查带有角色前缀，因此该 operator allowlist 只满足 operator 请求；非 operator 角色仍需要其自身角色前缀下的作用域。 + 设置代码携带一个短期有效的 bootstrap 令牌。内置 bootstrap 交接会将主节点令牌保持在 `scopes: []`；任何被交接的 operator 令牌都限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write` 内。Bootstrap 作用域检查带有角色前缀，因此该 operator 允许列表只满足 operator 请求；非 operator 角色仍需要其自身角色前缀下的作用域。 - 如果设备使用变更后的认证详细信息重试（例如角色/作用域/公钥），之前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。 + 如果设备使用更改后的认证详细信息（例如角色/作用域/公钥）重试，先前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。 更多详情：[配对](/zh-CN/channels/pairing#pair-via-telegram-recommended-for-ios)。 @@ -413,7 +413,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 按账户覆盖： + 按账号覆盖： ```json5 { @@ -464,7 +464,7 @@ curl "https://api.telegram.org/bot/getUpdates" - + Telegram 工具操作包括： - `sendMessage`（`to`、`content`、可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`） @@ -473,7 +473,7 @@ curl "https://api.telegram.org/bot/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`）。 门控控制： @@ -482,15 +482,15 @@ 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) - Telegram 支持在生成输出中使用显式回复线程标签： + Telegram 支持在生成的输出中使用显式回复线程标签： - `[[reply_to_current]]` 回复触发消息 - `[[reply_to:]]` 回复特定 Telegram 消息 ID @@ -501,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.` - 常规 topic（`threadId=1`）特殊情况： + 常规话题（`threadId=1`）特殊情况： - 消息发送会省略 `message_thread_id`（Telegram 会拒绝 `sendMessage(...thread_id=1)`） - - 输入状态操作仍会包含 `message_thread_id` + - 输入状态操作仍包含 `message_thread_id` - Topic 继承：topic 条目会继承群组设置，除非被覆盖（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。 - `agentId` 仅属于 topic，不会从群组默认值继承。 + 话题继承：话题条目会继承群组设置，除非被覆盖（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。 + `agentId` 仅限话题，不会从群组默认值继承。 - **按 topic 的智能体路由**：每个 topic 都可以通过在 topic 配置中设置 `agentId` 路由到不同智能体。这让每个 topic 都拥有独立的工作区、记忆和会话。示例： + **按话题进行智能体路由**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同智能体。这让每个话题都有自己的隔离工作区、记忆和会话。示例： ```json5 { @@ -543,13 +543,13 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 然后每个 topic 都有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3` + 然后每个话题都有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3` - **持久 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 话题绑定**：论坛话题可以通过顶层 typed ACP bindings（`bindings[]`，其中 `type: "acp"`、`match.channel: "telegram"`、`peer.kind: "group"`，并使用话题限定 ID，例如 `-1001234567890:topic:42`）固定 ACP harness 会话。目前作用域限于群组/超级群组中的论坛话题。参见 [ACP 智能体](/zh-CN/tools/acp-agents)。 - **从聊天发起线程绑定的 ACP spawn**：`/acp spawn --thread here|auto` 会将当前 topic 绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在 topic 内置顶 spawn 确认消息。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。 + **从聊天发起线程绑定的 ACP spawn**：`/acp spawn --thread here|auto` 将当前话题绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在话题内置顶 spawn 确认。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。 - 模板上下文会暴露 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天会保留私信路由，但使用线程感知的会话键。 + 模板上下文公开 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天会保留私信路由，但使用感知线程的会话键。 @@ -559,8 +559,8 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram 区分语音留言和音频文件。 - 默认：音频文件行为 - - 在智能体回复中使用标签 `[[audio_as_voice]]` 强制作为语音留言发送 - - 入站语音留言转录会在智能体上下文中被框定为机器生成的、不受信任文本；提及检测仍然使用原始转录，因此受提及门控的语音消息会继续工作。 + - 在智能体回复中使用标签 `[[audio_as_voice]]` 以强制发送语音留言 + - 入站语音留言转录会在智能体上下文中被框定为机器生成的非可信文本；提及检测仍使用原始转录，因此受提及门控的语音消息会继续工作。 消息操作示例： @@ -612,7 +612,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - 贴纸会被描述一次（在可能时）并缓存，以减少重复的视觉调用。 + 贴纸会被描述一次（如果可行），并缓存以减少重复的视觉调用。 启用贴纸操作： @@ -639,7 +639,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 搜索已缓存贴纸： + 搜索缓存的贴纸： ```json5 { @@ -653,7 +653,7 @@ curl "https://api.telegram.org/bot/getUpdates" - Telegram 反应会作为 `message_reaction` 更新到达（独立于消息载荷）。 + Telegram 反应以 `message_reaction` 更新的形式到达（与消息载荷分开）。 启用后，OpenClaw 会将如下系统事件加入队列： @@ -666,30 +666,30 @@ curl "https://api.telegram.org/bot/getUpdates" 注意： - - `own` 表示仅用户对机器人发送消息的表态回应（通过已发送消息缓存尽力实现）。 - - 表态回应事件仍遵循 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。 - - Telegram 不会在表态回应更新中提供话题 ID。 + - `own` 表示仅用户对机器人发送消息的回应（通过已发送消息缓存尽力而为）。 + - 回应事件仍遵守 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。 + - Telegram 不会在回应更新中提供 thread ID。 - 非论坛群组会路由到群聊会话 - - 论坛群组会路由到群组通用话题会话（`:topic:1`），而不是确切的原始话题 + - 论坛群组会路由到群组常规话题会话（`: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 表情符号（例如 "👀"）。 - - 使用 `""` 可禁用某个渠道或账号的表态回应。 + - Telegram 需要 unicode emoji（例如 “👀”）。 + - 使用 `""` 可为某个渠道或账号禁用回应。 @@ -716,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。 + Webhook 模式会在向 Telegram 返回 `200` 之前验证请求防护、Telegram secret token 和 JSON body。 + 随后 OpenClaw 会通过长轮询所用的同一套按聊天/按话题机器人通道路异步处理更新，因此较慢的智能体回合不会占用 Telegram 的投递 ACK。 - `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.chunkMode="newline"` 会在按长度拆分之前优先使用段落边界（空行）。 + - `channels.telegram.mediaMaxMb`（默认 100）限制传入和传出的 Telegram 媒体大小。 + - `channels.telegram.timeoutSeconds` 覆盖 Telegram API 客户端超时（如未设置，则使用 grammY 默认值）。长轮询机器人客户端会将低于 45 秒 `getUpdates` 请求防护的配置值钳制住，避免空闲轮询在 30 秒轮询窗口完成前被中止。 + - `channels.telegram.pollingStallThresholdMs` 默认值为 `120000`；仅在出现误报轮询停滞重启时，才在 `30000` 到 `600000` 之间调整。 - 群组上下文历史使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（默认 50）；`0` 表示禁用。 - - 回复/引用/转发补充上下文目前会按收到的内容传递。 - - Telegram 允许列表主要控制谁能触发智能体，而不是完整的补充上下文脱敏边界。 + - 回复/引用/转发的补充上下文目前会按收到的内容传递。 + - Telegram 允许列表主要限制谁可以触发智能体，而不是完整的补充上下文脱敏边界。 - 私信历史控制： - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - `channels.telegram.retry` 配置适用于 Telegram 发送辅助函数（CLI/工具/动作）中可恢复的出站 API 错误。入站最终回复投递也会对 Telegram 预连接失败使用有界安全发送重试，但不会重试可能导致可见消息重复的模糊发送后网络信封。 + - `channels.telegram.retry` 配置适用于 Telegram 发送辅助工具（CLI/工具/动作）中的可恢复出站 API 错误。传入最终回复投递也会对 Telegram 预连接失败使用有界安全发送重试，但不会重试可能重复显示消息的模糊发送后网络信封。 CLI 发送目标可以是数字聊天 ID 或用户名： @@ -756,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` @@ -765,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 支持在审批者私信中执行审批，也可以选择在原始聊天或话题中发布提示。审批者必须是数字 Telegram 用户 ID。 + + 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)。 ## 错误回复控制 -当智能体遇到投递或提供商错误时，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` | 数字（毫秒） | `60000` | 向同一聊天发送错误回复之间的最小间隔。防止故障期间出现错误刷屏。 | -支持按账号、按群组、按话题覆盖（继承方式与其他 Telegram 配置键相同）。 +支持按账号、按群组和按话题覆盖（继承方式与其他 Telegram 配置键相同）。 ```json5 { @@ -827,13 +827,13 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## 故障排除 - + - 如果 `requireMention=false`，Telegram 隐私模式必须允许完整可见性。 - - BotFather：`/setprivacy` -> 禁用 + - BotFather：`/setprivacy` -> Disable - 然后将机器人从群组移除并重新添加 - 当配置期望未提及的群组消息时，`openclaw channels status` 会发出警告。 - - `openclaw channels status --probe` 可以检查显式数字群组 ID；通配符 `"*"` 无法探测成员资格。 + - `openclaw channels status --probe` 可以检查显式数字群组 ID；通配符 `"*"` 无法进行成员探测。 - 快速会话测试：`/activation always`。 @@ -841,39 +841,40 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - 当 `channels.telegram.groups` 存在时，群组必须被列出（或包含 `"*"`） - - 验证机器人在群组中的成员资格 - - 查看日志：使用 `openclaw logs --follow` 查看跳过原因 + - 验证机器人的群组成员身份 + - 查看日志：`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 的传输回退重试一次。持续的网络/抓取错误通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性存在问题 - + - - `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 为空时，轮询会继续，因为清理条件已满足。 + - `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 时，轮询会继续，因为清理已满足。 - - 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 现在会将这些作为可恢复的网络错误重试。 + - 如果 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 调用： ```yaml @@ -892,9 +893,7 @@ channels: autoSelectFamily: false ``` - - 默认已允许 Telegram 媒体下载使用 RFC 2544 基准范围应答（`198.18.0.0/15`）。 - 如果受信任的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写为其他 - 私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过： + - 默认已允许 Telegram 媒体下载使用 RFC 2544 基准范围答案（`198.18.0.0/15`）。如果可信的 fake-IP 或透明 proxy 在媒体下载期间将 `api.telegram.org` 重写为其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过： ```yaml channels: @@ -903,22 +902,22 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - 同样的可选启用项也可按账号配置在 - `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`。 - - 如果你的代理将 Telegram 媒体主机解析为 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已允许 RFC 2544 - 基准范围。 + - 同一选择也可按账号在 `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` 启用。 + - 如果你的 proxy 将 Telegram 媒体主机解析到 `198.18.x.x`，请先关闭危险标志。Telegram 媒体默认已经允许 RFC 2544 基准范围。 `channels.telegram.network.dangerouslyAllowPrivateNetwork` 会削弱 Telegram - 媒体 SSRF 防护。仅在受信任且由操作方控制的代理环境中使用它，例如 Clash、Mihomo 或 Surge fake-IP 路由，并且它们会合成超出 RFC 2544 基准 - 范围的私有或特殊用途应答。正常公共互联网 Telegram 访问请保持关闭。 + 媒体 SSRF 防护。仅在可信的操作员控制 proxy + 环境中使用它，例如 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 @@ -934,48 +933,48 @@ dig +short api.telegram.org AAAA 主要参考：[配置参考 - Telegram](/zh-CN/gateway/config-channels#telegram)。 - + -- 启动/凭证：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向常规文件；符号链接会被拒绝） +- 启动/auth：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向普通文件；符号链接会被拒绝） - 访问控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`、`groups.*.topics.*`、顶层 `bindings[]`（`type: "acp"`） -- 执行审批：`execApprovals`、`accounts.*.execApprovals` -- 命令/菜单：`commands.native`、`commands.nativeSkills`、`customCommands` -- 话题串/回复：`replyToMode` +- exec 审批：`execApprovals`、`accounts.*.execApprovals` +- 命令/menu：`commands.native`、`commands.nativeSkills`、`customCommands` +- 线程/replies：`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`） +- 自定义 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` +- 写入/history：`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 allowlist 行为。 - + 将入站消息路由到智能体。 - - 威胁模型与加固。 + + 威胁模型和加固。 - - 将群组和话题映射到智能体。 + + 将群组和 topic 映射到智能体。 - + 跨渠道诊断。 diff --git a/docs/zh-CN/concepts/messages.md b/docs/zh-CN/concepts/messages.md index f9ceb6c9b..6b50e4235 100644 --- a/docs/zh-CN/concepts/messages.md +++ b/docs/zh-CN/concepts/messages.md @@ -1,22 +1,22 @@ --- read_when: - 说明入站消息如何变成回复 - - 说明会话、排队模式或流式传输行为 + - 澄清会话、排队模式或流式传输行为 - 记录推理可见性及其使用影响 -summary: 消息流、会话、队列处理与推理可见性 +summary: 消息流、会话、排队和推理可见性 title: 消息 x-i18n: - generated_at: "2026-04-30T00:29:50Z" + generated_at: "2026-04-30T15:18:53Z" model: gpt-5.5 provider: openai - source_hash: dcfcc995995516b627993755b255a779c681b4976d2d724c0c11e87875e37b1e + source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9 source_path: concepts/messages.md workflow: 16 --- -OpenClaw 通过会话解析、排队、流式传输、工具执行和推理可见性组成的管道处理入站消息。本页说明从入站消息到回复的路径。 +OpenClaw 通过会话解析、排队、流式传输、工具执行和推理可见性组成的流水线处理入站消息。本页映射从入站消息到回复的路径。 -## 消息流（高层级） +## 消息流程（高层） ``` Inbound message @@ -26,21 +26,21 @@ Inbound message -> outbound replies (channel limits + chunking) ``` -关键调节项位于配置中： +关键旋钮位于配置中： - `messages.*` 用于前缀、排队和群组行为。 - `agents.defaults.*` 用于分块流式传输和分块默认值。 -- 渠道覆盖项（`channels.whatsapp.*`、`channels.telegram.*` 等）用于上限和流式传输开关。 +- 渠道覆盖项（`channels.whatsapp.*`、`channels.telegram.*` 等）用于上限和流式开关。 -完整 schema 见 [配置](/zh-CN/gateway/configuration)。 +完整架构见[配置](/zh-CN/gateway/configuration)。 ## 入站去重 -渠道可能会在重连后重新投递同一条消息。OpenClaw 会保留一个短期缓存，以渠道/账号/对端/会话/消息 ID 作为键，这样重复投递就不会触发另一次智能体运行。 +渠道可能会在重新连接后重新投递同一条消息。OpenClaw 会保留一个短生命周期缓存，以渠道/账号/对等方/会话/消息 ID 为键，避免重复投递触发另一次智能体运行。 ## 入站防抖 -来自**同一发送者**的快速连续消息可以通过 `messages.inbound` 合并到单个智能体轮次中。防抖按渠道 + 对话划分作用域，并使用最新消息进行回复串接/ID 关联。 +来自**同一发送者**的快速连续消息可以通过 `messages.inbound` 批处理为单个智能体轮次。防抖按渠道 + 对话限定作用域，并使用最新消息进行回复串联/ID 关联。 配置（全局默认值 + 按渠道覆盖）： @@ -59,20 +59,20 @@ Inbound message } ``` -说明： +注意： -- 防抖适用于**纯文本**消息；媒体/附件会立即刷新。 -- 控制命令会绕过防抖，因此它们保持独立，**但**当某个渠道明确选择加入同一发送者私信合并时除外（例如 [BlueBubbles `coalesceSameSenderDms`](/zh-CN/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)），此时私信命令会在防抖窗口内等待，以便拆分发送的载荷可以加入同一个智能体轮次。 +- 防抖适用于**仅文本**消息；媒体/附件会立即刷新。 +- 控制命令会绕过防抖，因此它们保持独立，**除非**某个渠道明确选择加入同发送者私信合并（例如 [BlueBubbles `coalesceSameSenderDms`](/zh-CN/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)），此时私信命令会在防抖窗口内等待，以便拆分发送的载荷可以加入同一个智能体轮次。 ## 会话和设备 会话由 Gateway 网关拥有，而不是由客户端拥有。 -- 直接聊天会折叠到智能体主会话键。 +- 直接聊天会折叠到智能体主会话键中。 - 群组/渠道会获得自己的会话键。 - 会话存储和转录记录位于 Gateway 网关主机上。 -多个设备/渠道可以映射到同一个会话，但历史记录不会完整同步回每个客户端。建议：长对话使用一个主设备，以避免上下文分歧。控制 UI 和 TUI 始终显示由 Gateway 网关支持的会话转录记录，因此它们是真实来源。 +多个设备/渠道可以映射到同一个会话，但历史不会完整同步回每个客户端。建议：长对话使用一个主设备，以避免上下文分叉。Control UI 和 TUI 始终显示由 Gateway 网关支持的会话转录记录，因此它们是真实来源。 详情：[会话管理](/zh-CN/concepts/session)。 @@ -80,48 +80,50 @@ Inbound message 工具结果 `content` 是模型可见的结果。工具结果 `details` 是用于 UI 渲染、诊断、媒体投递和插件的运行时元数据。 -OpenClaw 会明确保持该边界： +OpenClaw 明确保持这条边界： - `toolResult.details` 会在提供商重放和压缩输入之前被剥离。 - 持久化的会话转录记录只保留有界的 `details`；过大的元数据会替换为标记了 `persistedDetailsTruncated: true` 的紧凑摘要。 -- 插件和工具应将模型必须读取的文本放入 `content`，而不只是放入 `details`。 +- 插件和工具应将模型必须读取的文本放在 `content` 中，而不只是放在 `details` 中。 ## 入站正文和历史上下文 -OpenClaw 将**提示词正文**与**命令正文**分开： +OpenClaw 将**提示正文**与**命令正文**分开： -- `Body`：发送给智能体的提示文本。这可能包括渠道信封和可选历史包装器。 +- `BodyForAgent`：当前消息面向主模型的文本。渠道插件应让它聚焦于发送者当前承载提示的文本。 +- `Body`：旧版提示回退。这可能包含渠道信封和可选的历史包装器，但当 `BodyForAgent` 可用时，当前渠道不应依赖它作为主模型输入。 - `CommandBody`：用于指令/命令解析的原始用户文本。 - `RawBody`：`CommandBody` 的旧版别名（为兼容性保留）。 -当某个渠道提供历史记录时，它会使用共享包装器： +当渠道提供历史时，它使用共享包装器： - `[Chat messages since your last reply - for context]` - `[Current message - respond to this]` -对于**非直接聊天**（群组/渠道/房间），**当前消息正文**会加上发送者标签前缀（与历史条目使用的样式相同）。这能让智能体提示词中的实时消息和排队/历史消息保持一致。 +对于**非直接聊天**（群组/渠道/房间），**当前消息正文**会加上发送者标签前缀（与历史条目使用相同样式）。这让实时消息和排队/历史消息在智能体提示中保持一致。 -历史缓冲区是**仅待处理**的：它们包含没有触发运行的群组消息（例如受提及门控的消息），并且**排除**已经在会话转录记录中的消息。 +历史缓冲区是**仅待处理**的：它们包含未触发运行的群组消息（例如受提及门控的消息），并**排除**已经在会话转录记录中的消息。 -指令剥离只适用于**当前消息**部分，因此历史记录保持完整。包装历史记录的渠道应将 `CommandBody`（或 `RawBody`）设置为原始消息文本，并将 `Body` 保持为组合后的提示词。历史缓冲区可通过 `messages.groupChat.historyLimit`（全局默认值）以及按渠道覆盖项配置，例如 `channels.slack.historyLimit` 或 `channels.telegram.accounts..historyLimit`（设为 `0` 可禁用）。 +指令剥离只应用于**当前消息**部分，因此历史保持完整。包装历史的渠道应将 `CommandBody`（或 `RawBody`）设置为原始消息文本，并将 `Body` 保持为组合提示。结构化历史、回复、转发和渠道元数据会在提示组装期间渲染为用户角色的不可信上下文块。 +历史缓冲区可通过 `messages.groupChat.historyLimit`（全局默认值）和按渠道覆盖项配置，例如 `channels.slack.historyLimit` 或 `channels.telegram.accounts..historyLimit`（设置为 `0` 可禁用）。 ## 排队和跟进 -如果已有运行处于活动状态，入站消息可以被排队、引导进当前运行，或收集到一个跟进轮次中。 +如果已有运行处于活跃状态，入站消息可以被排队、引导到当前运行中，或收集到跟进轮次中。 - 通过 `messages.queue`（以及 `messages.queue.byChannel`）配置。 -- 默认模式是 `steer`，当引导回退到排队跟进投递时，会使用 500ms 的跟进防抖。 +- 默认模式是 `steer`，当引导回退到排队跟进投递时，使用 500ms 跟进防抖。 - 模式：`steer`、`followup`、`collect`、`steer-backlog`、`interrupt`，以及旧版一次一个的 `queue` 模式。 -详情：[命令队列](/zh-CN/concepts/queue) 和 [Steering queue](/zh-CN/concepts/queue-steering)。 +详情：[命令队列](/zh-CN/concepts/queue)和 [Steering queue](/zh-CN/concepts/queue-steering)。 ## 渠道运行所有权 -渠道插件可以在消息进入会话队列前保留顺序、防抖输入，并应用传输背压。它们不应围绕智能体轮次本身施加单独的超时。一旦消息被路由到某个会话，长时间运行的工作就由会话、工具和运行时生命周期管理，这样所有渠道都能一致地报告并从缓慢轮次中恢复。 +渠道插件可以在消息进入会话队列之前保留顺序、对输入做防抖，并应用传输背压。它们不应围绕智能体轮次本身施加单独的超时。一旦消息被路由到某个会话，长时间运行的工作就由会话、工具和运行时生命周期治理，使所有渠道都能以一致方式报告并从慢轮次中恢复。 ## 流式传输、分块和批处理 -分块流式传输会在模型生成文本块时发送部分回复。分块会遵守渠道文本限制，并避免拆分围栏代码。 +分块流式传输会在模型生成文本块时发送部分回复。分块遵守渠道文本限制，并避免拆分围栏代码。 关键设置： @@ -129,43 +131,45 @@ OpenClaw 将**提示词正文**与**命令正文**分开： - `agents.defaults.blockStreamingBreak`（`text_end|message_end`） - `agents.defaults.blockStreamingChunk`（`minChars|maxChars|breakPreference`） - `agents.defaults.blockStreamingCoalesce`（基于空闲的批处理） -- `agents.defaults.humanDelay`（分块回复之间类似人类的停顿） +- `agents.defaults.humanDelay`（块回复之间类似人类的暂停） - 渠道覆盖项：`*.blockStreaming` 和 `*.blockStreamingCoalesce`（非 Telegram 渠道需要显式设置 `*.blockStreaming: true`） 详情：[流式传输 + 分块](/zh-CN/concepts/streaming)。 -## 推理可见性和 token +## 推理可见性和令牌 -OpenClaw 可以显示或隐藏模型推理： +OpenClaw 可以公开或隐藏模型推理： - `/reasoning on|off|stream` 控制可见性。 -- 推理内容由模型生成时，仍会计入 token 使用量。 +- 当模型生成推理内容时，它仍会计入令牌用量。 - Telegram 支持将推理流式传输到草稿气泡中。 -详情：[思考 + 推理指令](/zh-CN/tools/thinking) 和 [Token 使用](/zh-CN/reference/token-use)。 +详情：[思考 + 推理指令](/zh-CN/tools/thinking)和[令牌使用](/zh-CN/reference/token-use)。 -## 前缀、串接和回复 +## 前缀、串联和回复 出站消息格式集中在 `messages` 中： - `messages.responsePrefix`、`channels..responsePrefix` 和 `channels..accounts..responsePrefix`（出站前缀级联），以及 `channels.whatsapp.messagePrefix`（WhatsApp 入站前缀） -- 通过 `replyToMode` 和按渠道默认值进行回复串接 +- 通过 `replyToMode` 和按渠道默认值进行回复串联 -详情：[配置](/zh-CN/gateway/config-agents#messages) 和渠道文档。 +详情：[配置](/zh-CN/gateway/config-agents#messages)和渠道文档。 ## 静默回复 -确切的静默 token `NO_REPLY` / `no_reply` 表示“不要投递用户可见的回复”。当某个轮次还有待处理的工具媒体（例如生成的 TTS 音频）时，OpenClaw 会剥离静默文本，但仍会投递媒体附件。OpenClaw 会按对话类型解析该行为： +精确的静默令牌 `NO_REPLY` / `no_reply` 表示“不要投递用户可见回复”。 +当一个轮次还有待处理工具媒体（例如生成的 TTS 音频）时，OpenClaw 会剥离静默文本，但仍会投递媒体附件。 +OpenClaw 按对话类型解析该行为： -- 直接对话默认不允许静默，并会将单独的静默回复重写为简短的可见兜底回复。 +- 直接对话默认不允许静默，并会将纯静默回复改写为简短的可见回退。 - 群组/渠道默认允许静默。 - 内部编排默认允许静默。 -OpenClaw 还会对发生在非直接聊天中任何助手回复之前的内部运行器失败使用静默回复，因此群组/渠道不会看到 Gateway 网关错误样板文本。直接聊天默认显示紧凑的失败文案；只有当 `/verbose` 为 `on` 或 `full` 时，才会显示原始运行器详情。 +OpenClaw 还会对在非直接聊天中任何助手回复之前发生的内部运行器失败使用静默回复，因此群组/渠道不会看到 Gateway 网关错误样板文本。直接聊天默认显示紧凑失败文案；只有当 `/verbose` 为 `on` 或 `full` 时，才会显示原始运行器详情。 -默认值位于 `agents.defaults.silentReply` 和 `agents.defaults.silentReplyRewrite` 下；`surfaces..silentReply` 和 `surfaces..silentReplyRewrite` 可以按 surface 覆盖它们。 +默认值位于 `agents.defaults.silentReply` 和 `agents.defaults.silentReplyRewrite` 下；`surfaces..silentReply` 和 `surfaces..silentReplyRewrite` 可以按表面覆盖它们。 -当父会话有一个或多个待处理的已生成子智能体运行时，单独的静默回复会在所有 surface 上被丢弃而不是被重写，因此父会话会保持安静，直到子完成事件投递真正的回复。 +当父会话有一个或多个待处理的已生成子智能体运行时，纯静默回复会在所有表面上被丢弃，而不是被改写，因此父会话会保持安静，直到子完成事件投递真正的回复。 ## 相关