消息行为
入站和出站 Telegram 消息如何被路由、预览、确认和投递。
运行时行为¶
- Telegram 消息处理在网关进程内运行。
- 路由是确定性的:Telegram 入站消息会回复到 Telegram(模型不会选择渠道)。
- 入站消息被规范化为共享渠道信封,包含回复元数据、媒体占位符,以及网关已观察到的回复的持久化回复链上下文。
- 群组会话按群组 ID 隔离。论坛主题追加
:topic:<threadId>。 - 当机器人加入允许的群组或超级群组时,它会发布一条基于可用房间元数据的介绍:群组标题、描述和置顶消息。Telegram Bot API 无法读取机器人加入之前的群组消息,因此介绍绝不会声称使用了先前的聊天历史。介绍默认启用,从不在私聊中运行,并可通过
channels.telegram.joinIntro: false禁用,或通过channels.telegram.accounts.<accountId>.joinIntro按账户覆盖。有关每个房间一次的行为和不可信内容处理,请参阅 群组加入介绍。 - DM 消息可以携带
message_thread_id;OpenClaw 会保留它用于回复。DM 主题会话仅在 TelegramgetMe报告该机器人的has_topics_enabled: true时拆分;否则 DM 保持扁平会话。 - 长轮询在隔离的工作进程中运行。更新被保存到持久队列,并按每个聊天和主题的顺序处理。
- 多账户启动会限制并发
getMe检查,以便大型机器人集群不会一次性展开所有账户检查。 - 每个网关进程都会保护长轮询,使得同一时间只有一个活动轮询器可以使用一个机器人 token。持续的
getUpdates409 冲突指向另一个 OpenClaw 网关、脚本或外部轮询器正在使用同一 token。 - 轮询看门狗会在 120 秒内没有完成的
getUpdates存活信号后重启。 - Telegram Bot API 不支持已读回执(
sendReadReceipts不适用)。
升级后,旧的非版本化回复缓存条目被视为缓存未命中。 它们的回复链上下文可能不可用,直到这些消息再次被观察到。 版本 1 缓存条目、保留的群组历史和会话转录仍然受支持。 转录去重使用记录的消息标识; 无标记的助手回复可能同时出现在回复上下文和转录中。
Note
升级说明:Telegram 的默认预览在 2026.8.1 中更改。 当 channels.telegram.streaming 未设置时,Telegram 在轮次期间保留一个可编辑的状态草稿(代理的当前状态及其工具行),并将最终答案作为普通消息发送。它之前会将答案文本本身流式传输到预览中。没有配置会失效,也不需要 doctor --fix;若要保留之前的行为,请设置:
Note
channels.telegram.dm.threadReplies 和 channels.telegram.direct.<chatId>.threadReplies 已移除。如果升级后配置中仍有这些键,请运行 openclaw doctor --fix。DM 主题路由现在遵循 Telegram getMe.has_topics_enabled(由 BotFather 线程模式控制):启用主题的机器人在 Telegram 发送 message_thread_id 时使用线程范围的 DM 会话;其他 DM 保持扁平会话。
对 replyToMode、streaming 和 textChunkLimit 的更改会在不重新连接 Telegram 的情况下应用于下一个组装的轮次,包括账户覆盖。
活动轮次保留其捕获的投递设置。
入站文本批处理¶
Telegram 默认将同一发送者的快速文本消息批处理为一个代理轮次。普通文本等待 300ms 静默窗口;至少 4000 个字符的非转发消息允许最多 1500ms,以应对可能的长粘贴延续。
- 短文本和长文本共享一个批次,因此简短介绍、长粘贴和简短后续可能作为一个轮次到达。消息 ID 不需要连续。
- 批次按机器人账户、发送者、聊天和主题保持隔离。回复元数据和源消息 ID 会被保留。
messages.inbound.byChannel.telegram覆盖messages.inbound.debounceMs,后者覆盖 300ms 普通文本默认值。显式0禁用普通突发批处理,但保留自动长粘贴组装。- 控制命令绕过批处理并立即分发。停止/中止命令会取消其目标对话中待处理的文本。
- 转发消息使用单独的 1 秒收集窗口,但共享发送者的分发队列,因此不能超越更早的文本。Telegram 将多消息转发中的每条消息作为其自己的更新投递,通常在稍后的轮询中,因此窗口会等待足够长的时间,让突发的其余部分到达。因此,单个转发大约在其到达后一秒开始其轮次。如果同一发送者的另一个转发已经排在对话的入口通道上,收集会等待它,受现有 5 秒批次截止时间限制。
入站照片相册使用 500ms 静默窗口。当同一相册的另一成员已经排在对话的入口通道上时,OpenClaw 会在刷新前等待它,保持时间从第一个缓冲成员起限制为 20 秒。这些窗口覆盖 Telegram 投递间隙;只要匹配成员仍在这些界限内排队,本地处理延迟不会拆分相册或转发突发。
普通文本批次限制为 12 条消息和 50,000 个字符。其收集截止时间是从第一条消息起 7.5 秒,或配置的静默窗口(如果更长)。批次刷新后到达的消息无法加入该批次。此启发式方法不保证 Telegram 将每个粘贴片段一起投递。有关热重载行为,请参阅 入站防抖。
消息行为¶
实时流式预览(消息编辑)
OpenClaw 在直接聊天、群组和主题中实时流式传输部分回复:发送一条预览消息,然后反复 `editMessageText`,并在原地最终确定。携带写入者权限的预览编辑,例如最终确定,会在每个排队的 Telegram 请求之前重新检查活动写入者,因此被替换的轮次无法从该路径发送过期编辑。
-
channels.telegram.streaming为off | partial | block | progress(默认值:progress);设置mode: "partial"可将回答文本流式传输到预览中,而不是状态草稿 - 短暂的初始回答预览会经过防抖,如果运行仍活跃,则在有限延迟后生成 -progress会保留一条可编辑的状态草稿;当回答活动在工具进度之前出现时,显示稳定的状态标签;完成时清除它,并将最终回答作为普通消息发送。默认情况下草稿保持精简:状态标题、评论、计划里程碑和审批请求。中间工具失败和非零命令退出会被隐藏;最终任务错误仍使用正常错误投递。streaming.progress.toolProgress: true会添加滚动工具日志,包括工具失败。 -streaming.preview.toolProgress控制工具/进度更新是否在partial和block模式下复用同一条已编辑的预览消息(当预览流式传输启用时,默认值为true) -streaming.preview.commandText控制这些行内的命令/执行详情:status(默认值,仅工具标签)或raw(显式命令文本) - 已完成的助手前言默认会更新状态标题;新前言会保留之前的可读状态,直到其完成 -streaming.progress.commentary(默认值:false)将这些前言显示为交错的评论行,而不是标题;评论仍显示在计划步骤旁边 - 成功的后台进程轮询和内部等待不会进入进度日志;失败仍遵循所选的工具进度策略,并且/verbose会保留诊断摘要 - 旧版channels.telegram.streamMode、布尔型streaming值以及已弃用的原生草稿预览键会被检测到;运行openclaw doctor --fix以迁移它们工具进度行是工具运行期间显示的简短状态更新(命令执行、文件读取、计划更新、补丁摘要、app-server 模式下的 Codex 前言/评论)。`partial` 和 `block` 预览默认显示它们;`progress` 草稿仅在 `streaming.progress.toolProgress: true` 时显示它们。压缩状态遵循相同设置,并在压缩一开始就出现,包括在首次模型输出之前。 在默认 `progress` 模式下,`/verbose on` 会发送独立的工具摘要,`/verbose full` 还会发送已完成的工具输出。显式的 `toolProgress: false` 优先于 `/verbose`;`streaming.mode: "off"` 也会抑制这些诊断信息。 保留回答预览编辑,但隐藏工具进度行: ```json { "channels": { "telegram": { "streaming": { "mode": "partial", "preview": { "toolProgress": false } } } } } ``` 保持工具进度可见,但隐藏命令/执行文本: ```json { "channels": { "telegram": { "streaming": { "mode": "partial", "preview": { "commandText": "status" } } } } } ``` `progress` 模式可以显示工具日志,而无需将最终回答编辑到该消息中。通过 `toolProgress: true` 启用,并将命令文本策略放在 `streaming.progress` 下: ```json { "channels": { "telegram": { "streaming": { "mode": "progress", "progress": { "toolProgress": true, "commandText": "status" } } } } } ``` `streaming.mode: "off"` 会禁用预览编辑,并抑制通用工具/进度信息,而不是将其作为独立状态消息发送;审批提示、媒体和错误仍通过正常最终投递路由。`streaming.preview.toolProgress: false` 仅保留回答预览编辑。Note
选中的引用回复是例外。当
replyToMode为first、all或batched,且入站消息包含选中的引用文本时,OpenClaw 会通过 Telegram 的原生引用回复路径发送最终回答,并跳过该轮次的草稿预览。没有选中引用文本的当前消息回复仍会流式传输。当启用回复线程时,它们的预览会携带自动引用摘录,并在原地最终化时保留这些摘录。当工具进度可见性比原生引用回复更重要时,设置replyToMode: "off"。若要保留原生引用回复并隐藏工具进度行,请在progress模式下使用streaming.progress.toolProgress: false,或在partial和block模式下使用streaming.preview.toolProgress: false。对于纯文本回复:短预览会原地进行最终编辑;拆分为多条消息的长最终回复会复用预览作为第一个块,然后仅发送剩余部分;
progress模式的最终回复会清除状态草稿并使用正常最终投递;如果在确认完成之前最终编辑失败,OpenClaw 会回退到正常最终投递并清理过期预览。对于复杂回复(媒体负载),OpenClaw 始终回退到正常最终投递并清理预览。预览流式传输和块流式传输互斥。显式的非
off预览模式会覆盖继承的agents.defaults.blockStreamingDefault: "on";显式的streaming.block.enabled: true会覆盖预览。对于普通单代理轮次,当修改回复的插件钩子阻止预览时,已完成的回答块会改用正常钩子投递,除非通过agents.defaults.blockStreamingDefault: "off"全局显式禁用块流式传输,或通过streaming.block.enabled: false针对 Telegram 禁用。已配置的多代理群线程轮次不使用此强制回退;与其他无法使用预览的轮次一样,它们保留已配置的块投递策略。
推理:/reasoning stream 在生成过程中将推理内容流式输出到实时预览中,并在最终交付后删除该推理预览(使用 /reasoning on 可保持其可见)。最终答案发送时不包含推理文本。
原生命令与自定义命令
Telegram 的命令菜单在启动时通过 `setMyCommands` 注册。`commands.native: "auto"` 可为 Telegram 启用原生命令。
添加自定义命令菜单条目:
{
channels: {
telegram: {
customCommands: [
{ command: "backup", description: "Git backup" },
{ command: "generate", description: "Create an image" },
],
},
},
}
规则:名称会被规范化(去除开头的 `/`;转为小写);有效模式为 `a-z`、`0-9`、`_`,长度 1-32;自定义命令不能覆盖原生命令;冲突/重复项会被跳过并记录日志。
当 Telegram 菜单限制需要裁剪时,已配置的自定义命令会优先保留,除非被省略的按技能条目被替换为带前导 `/skill` 的回退项。
自定义命令仅为菜单条目——它们不会自动实现行为。插件/技能命令即使未显示在 Telegram 菜单中,输入时仍可正常工作。如果禁用了原生命令,内置命令会被移除;自定义/插件命令若已配置仍可能注册。
常见设置故障:
- `setMyCommands failed` 并带有 `BOT_COMMANDS_TOO_MUCH`,在一次裁剪重试后仍出现,表示菜单仍然溢出;请减少插件/技能/自定义命令,或禁用 `channels.telegram.commands.native`。
- `apiRoot must be the Bot API root` 表示 `channels.telegram.apiRoot` 包含了完整的 `/bot<TOKEN>` 端点。在启动 Telegram 之前,运行 `openclaw doctor --fix` 移除该后缀。运行时请求使用修复后的根地址;自定义代理路径仍然受支持。
- `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-pairing-commands-device-pair-plugin}
安装后:
1. `/pair` 生成一个设置代码
2. 在 iOS 应用中粘贴该代码
3. `/pair pending` 列出待处理的请求(包括角色/作用域)
4. 批准:`/pair approve <requestId>`、`/pair approve`(仅当只有一个待处理请求时),或 `/pair approve latest`
如果设备以更改后的认证详情(角色、作用域、公钥)重试,之前的待处理请求会被新的 `requestId` 取代;请在批准前重新运行 `/pair pending`。
更多详情:[配对](../pairing.md#pair-via-telegram)。
回复线程标记
生成输出中的显式回复线程标记:
[[reply_to_current]]— 回复触发消息[[reply_to:<id>]]— 回复特定消息 ID
channels.telegram.replyToMode:off(默认)、first、all。
当回复线程已启用且原始文本/标题可用时,OpenClaw 会自动添加原生引用摘录。Telegram 将原生引用文本限制在 1024 个 UTF-16 代码单元;较长的消息会从开头开始引用,若 Telegram 拒绝该引用,则回退为普通回复。
off 仅禁用隐式回复线程;显式的 [[reply_to_*]] 标记仍会被执行。
在部分流式模式下,针对不同消息的最终回复会替换预览,而不是就地编辑。Telegram 不允许通过编辑来更改消息的回复目标。
确认反应
`ackReaction` 在 OpenClaw 处理入站消息时发送一个确认表情符号。`messages.ackReactionScope` 决定*何时*发送。
**表情符号解析顺序:**
- `channels.telegram.accounts.<accountId>.ackReaction`
- `channels.telegram.ackReaction`
- `messages.ackReaction`
- 代理身份表情符号回退(`agents.entries.*.identity.emoji`,否则为 "👀")
Telegram 期望一个 unicode 表情符号(例如 "👀");使用 `""` 可禁用某个频道或账户的反应。
**作用域(`messages.ackReactionScope`,默认 `"group-mentions"`;没有 Telegram 账户或 Telegram 频道的覆盖设置):**
`all`(私聊 + 群组,包括环境房间事件),`direct`(仅私聊),`group-all`(除环境房间事件外的所有群组消息,不包含私聊),`group-mentions`(群组中机器人被提及时;**不含私聊** — 默认),`off` / `none`(禁用)。
Note
默认作用域(group-mentions)不会在私聊或环境房间事件中触发确认反应。对于私聊,请使用 direct 或 all;只有 all 会确认环境房间事件。更改遵循热重载,并应用于后续消息。每个组装好的轮次都会保留其捕获的值。
保留的群组历史
Telegram 群组和论坛主题使用近期自动上下文窗口,外加显式历史读取。当 `requireMention: true` 时,被允许但未被提及的消息会被记录,而不会启动代理轮次。之后某个寻址到代理的轮次会收到近期上下文,代理在需要更早的讨论时可以使用 `message(action="read")`。
- `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit` 限制自动观察消息窗口的大小(默认 50,硬上限 200)。`0` 会禁用自动历史注入,但不会禁用记录或显式读取。JSON 整数最大值(`9007199254740991`)会选择默认的 50 条消息。
- 自动上下文在应用主题和发送者权限之前,会检查一个有界的近期切片。当其他主题或被排除的发送者主导该切片时,繁忙的群组提供的消息可能少于配置的数量。代理可以通过显式历史读取翻看更早的消息。
- 历史读取保持在已授权的账户、聊天和主题范围内。它们使用 Telegram 消息 ID 进行引用和分页;省略主题不得将主题范围内的读取扩展到整个群组。
- 代理读取默认每页 50 条消息,最多 100 条。使用 `before` 搭配返回的 `oldestMessageId` 读取更旧的消息,使用 `after` 读取更新的消息,或使用 `messageId` 进行精确定位。这些读取需要代理已认证的当前群组/主题;它们不会获取 Telegram 服务器历史记录。
- `/new` 和 `/reset` 重置自动会话上下文,而不是保留的对话。显式历史读取可以检索被允许的早期讨论。
- 现有的 SQLite 插件状态表拥有保留的群组消息。成功持久化的记录在 Gateway 重启后仍然存在,不会被消息数量逐出。私聊缓存行为仍然是有界的。
- 首次使用时,现有的群组缓存记录会原子地移入保留存储。没有历史准入来源(provenance)的遗留记录,包括内嵌的回复祖先,在现有的深度和可见性限制内仍可作为显式回复上下文使用;它们不会被当作经过验证的对话存档。
- 历史记录只包含 OpenClaw 收到并被允许记录的消息。它无法恢复该功能之前被逐出的消息、Telegram 未投递的消息,或机器人加入之前的消息。媒体引用不保证附件字节会无限期可用。
无需单独的观察设置。保持 Telegram 群组可见性 启用,以便机器人接收普通消息。启用历史记录不会更改显式 requireMention: false 激活。
!!! warning
较旧的 OpenClaw 版本会应用不同的缓存和插件配额规则。不要针对扩展的保留历史记录运行它们。降级需要兼容的更新前备份;此功能不会添加数据库版本围栏。
限制与 CLI 目标
- `channels.telegram.textChunkLimit` 默认值为 4000;`streaming.chunkMode="newline"` 优先使用段落边界(空行),然后再按长度拆分。
- `channels.telegram.mediaMaxMb`(默认 100)限制入站和出站媒体大小。
- 同一聊天或主题中的入站相册会按到达顺序到达代理,排在较早相册后面的相册会在较早相册仍在处理期间保持其投递声明有效。
- 当入站附件无法下载且消息继续传递到代理时,其正文会包含 `[media unavailable: ...]` 通知。超大通知会包含有效大小限制;部分相册会包含失败附件数和总附件数。即使其单独的聊天警告被抑制,这也适用于已准入的频道帖子。
- 自动群组上下文使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`(默认 50);`0` 禁用自动窗口,而不是保留历史记录。
- 当网关已观察到父消息时,回复/引用/转发的补充上下文会归一化为一个选定的对话上下文窗口;已观察消息缓存位于 OpenClaw SQLite 插件状态中。要导入六月前的缓存边车,请[通过 `2026.9.5` 升级](../../install/updating.md#upgrading-very-old-versions)并先运行其 Doctor。Telegram 每个更新仅包含一个浅层 `reply_to_message`,因此早于缓存的回复链仅限于该负载。
- Telegram 允许列表主要控制谁可以触发代理,而不是完整的补充上下文脱敏边界。
- DM 历史记录:`channels.telegram.dmHistoryLimit`、`channels.telegram.dms["<user_id>"].historyLimit`。自动观察到的 DM 上下文默认为 10 条消息,上限为 200;`0` 禁用该额外上下文,JSON 整数最大值会选择默认值。
- 这些频道/账户/DM 字段还控制嵌入会话转录在**用户轮次**中的修剪,而不是观察到的消息。该独立限制器将 `0` 视为不修剪,并保留其现有的淘汰缓冲。Doctor 会保留有效的已保存限制,包括 JSON 整数最大值,因此不会静默更改转录上下文。
CLI 和 message-tool 发送目标接受数字聊天 ID、用户名或论坛主题目标:
openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"
openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"
投票使用 `openclaw message poll` 并支持论坛主题:
openclaw message poll --channel telegram --target 123456789 \
--poll-question "Ship it?" --poll-option "Yes" --poll-option "No"
openclaw message poll --channel telegram --target -1001234567890:topic:42 \
--poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \
--poll-duration-seconds 300 --poll-public
仅限 Telegram 的投票标志:`--poll-duration-seconds`(5-604800;最多七天)、`--poll-anonymous`、`--poll-public`、`--thread-id`(或 `:topic:` 目标)。`--poll-option` 可重复 2-12 次(Telegram 的选项上限)。
Telegram 发送还支持带有 `buttons` 块的 `--presentation`,用于内联键盘(当 `channels.telegram.capabilities.inlineButtons` 允许时)、`--pin` 或 `--delivery '{"pin":true}'` 以在机器人可以在该聊天中固定时请求固定投递,以及 `--force-document` 以将出站图像、GIF 和视频作为文档发送,而不是压缩/动画/视频上传。
操作门控:`channels.telegram.actions.sendMessage=false` 禁用所有出站消息,包括投票;`channels.telegram.actions.poll=false` 禁用投票创建,同时保持常规发送启用。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw