传输
Long polling is the default. Webhook mode is the alternative when an HTTPS ingress is available.
长轮询与 Webhook¶
长轮询与 Webhook 对比
默认使用长轮询。若要使用 Webhook 模式,请设置 channels.telegram.webhookUrl 和 channels.telegram.webhookSecret;可选设置 webhookPath(默认 /telegram-webhook)和 webhookCertPath(用于直接使用 IP 或无域名场景的自签名证书 PEM)。
Gateway 保留 /health、/healthz、/ready、/readyz、/startup 和 /startupz 用于健康检查,包括带查询参数的变体。/api/channels 命名空间同样需要 Gateway 身份验证(包括编码形式),并且无法接收 Telegram 的直接回调。请为 Gateway 入口选择 /telegram-webhook 或其他路由。精确的 /healthz 路径仍保留给旧版监听器的健康检查,不能用作 Telegram Webhook 路径。在更新 webhookPath、webhookUrl 和反向代理映射期间,其他 Gateway 保留路径可以通过显式的 legacyWebhook 端点继续接收回调。如果没有显式端点,保留路径会产生一条可操作的启动错误。使用 openclaw channels status --probe 验证热重载是否已应用路由更改。
在长轮询模式下,OpenClaw 在更新提交到持久化入口队列后保存其重启位置。失败的处理程序仍可从该队列重试。
Webhook 路由在 Gateway HTTP 端口(默认 18789)上可用。将公共 HTTPS 入口指向该端口与 webhookPath。OpenClaw 在每次 Webhook 启动时(包括重启后)按原样注册配置的 webhookUrl。配置的 gateway.publicOrigin 不会取代由运维管理的回调或反向代理映射。Telegram 的 secret 请求头仍是身份验证边界,因此该路由不需要 Gateway bearer token。
新安装不会打开旧版转发端口。升级期间,Doctor 会将现有的隐式 127.0.0.1:8787 端点保留为显式的 legacyWebhook 固定配置,除非 webhookUrl 与配置的 gateway.publicOrigin 加上该账户可用的 webhookPath 匹配。该比较包含路径和查询参数;OpenClaw 无法从任意现有回调 URL 推断 Gateway 目的地。要移除固定配置,请暴露一条可用的 Gateway Webhook 路由,将 webhookUrl 设置为其公共 URL,并移除 legacyWebhook;OpenClaw 会在释放旧监听器之前注册该 URL。或者,将现有回调的反向代理上游移动到 Gateway 端口,验证传入消息,并设置 legacyWebhook: false 以保留其公共 URL。删除该设置绝不会恢复隐式监听器。
在进程内账户重载期间,Gateway 会保持之前的监听器可重试,直到 Telegram 接受替换 URL 的 setWebhook。收到更新并不表示切换已完成。完整的 Gateway 重启会关闭旧进程的套接字;在替代进程启动并注册其路由期间,Telegram 会重试待投递的消息。
Doctor 会将固定配置及其 meta.migrations.webhookListeners 完成记录一起保存。移除固定配置时请保留该记录,以便后续 Doctor 运行和更新保持其移除状态。有关包含的配置源和只读配置源,请参阅 Webhook 迁移。
旧版端口保留其未经验证的 /healthz 响应(200,纯文本 ok)以及账户本地的 secret 验证失败速率限制。健康检查匹配是精确的:查询字符串、尾部斜杠、大小写变化和编码变体均不被视为健康检查。HEAD 返回相同的状态但不包含响应体。规范的 Gateway 端口保持其自身的健康检查与响应头行为。
升级后,运行 openclaw doctor --fix。Doctor 会备份配置,并将旧的 webhookPort 和 webhookHost 设置迁移为 legacyWebhook: { port, host },仅含 host 的设置保留端口 8787。显式端点对象会覆盖默认值;省略 host 时使用 127.0.0.1。现有的 legacyWebhook: false 设置在迁移期间保持禁用状态。
命名账户继承所属 channel 的 legacyWebhook 设置。账户级别的 false 会禁用该账户的旧版端点,即使 channel 配置中指定了端点也是如此。显式的账户端点会覆盖继承的 false。只要还有其他账户在使用该端点,共享的旧版套接字就会保持打开状态。两个端口使用相同的 Gateway 路由处理器和 Telegram secret 验证。
单独安装的 Telegram 插件需要 OpenClaw 2026.9.8 或更高版本,其 Doctor 可以在新运行时启动前保留被省略的端点。在手动替换插件之前,请先升级 OpenClaw。较旧版本的主机会拒绝不兼容的软件包,并保留其当前插件。Gateway 拥有所有显式配置的转发监听器;Telegram 不再打开单独的账户自有服务器。
当账户的 webhook secret 不同时,它们可以共享一条 Gateway 路由。与多个账户匹配的请求会被拒绝;在将流量迁移到 Gateway 端口之前,请为账户分配不同的 secret 或路径。迁移后的旧版端点会为之前在单独显式端口上共享 secret 和路径的账户保留账户选择逻辑。
Webhook 模式会验证请求防护、Telegram secret token 和 JSON 请求体,然后在返回空 200 响应之前将更新提交到其持久化入口队列。成功的持久化采纳包含 x-openclaw-delivery-accepted: durable 响应头;健康检查、路由、身份验证、验证和存储错误响应则不包含此响应头。反向代理和主机控制器可通过要求此响应头来区分 OpenClaw 的采纳与普通的空 200 响应,而无需根据响应时机推断是否被采纳。
在持久化写入之后,OpenClaw 通过核心 channel 入口排空机制认领并处理更新(按聊天/按话题的独立通道,在回合采纳时完成,并设有回合采纳前的停滞超时)。缓慢的 agent 回合不会拖住 Telegram 的投递确认。
入站确认边界¶
Telegram 确认受持久化队列准入控制,而不是受插件钩子或代理轮次完成控制。Webhook 模式使用上文描述的边界;长轮询使用以下顺序:
- 轮询工作进程接收一个 Telegram 更新并等待。
- OpenClaw 以事务方式将原始更新入队到
state/openclaw.sqlite中按账户划分的channel_ingress_events队列。 - 入队成功后,OpenClaw 安排持久化重启偏移量并向工作进程发送确认,使轮询可以继续。
- 共享排空进程单独处理已入队的更新。如果准入失败,OpenClaw 会拒绝工作进程确认,而不是静默推进。
offset queued 表示重启偏移量写入已被安排,但尚未提交。如果该写入完成前发生崩溃,Telegram 可能会重新投递一个已经入队的更新。只有当同一传输事件 ID 的待处理行、已完成墓碑或失败行仍然存在时,队列才会拒绝该传输事件 ID。这是有界重放去重,而不是恰好一次处理。参见 持久化入站与重放去重。
重放限制¶
两种传输方式在接受更新之前都会记录账户的 bot 身份,即使没有轮询偏移量也是如此。替换已知 bot 时,会在替换开始前清除其旧的入站行。同一 bot 的重启和 Token 轮换会保留已入队的工作和重放保护;没有已知先前身份的旧队列也是如此。如果身份准备失败,账户启动会停止并出现错误,要求你重启账户;被中断的重置会保留先前身份以便重试。
对于每个 Telegram 账户队列,已完成墓碑和失败行最多保留 30 天,并且每类上限为 1,000 条。先达到哪个限制,哪一类就结束保留。完成操作会清除入站负载和元数据,同时保留事件身份。
在产生副作用之后、队列完成之前发生的崩溃,可能会重复该副作用。参见 传输保留、至少一次副作用 以及 入站死信。
文档中描述的持久性边界是 SQLite 事务成功完成,而不是单独的逐事件 fsync 保证。请使用持久化状态目录;删除它会同时丢失已入队的更新和已保存的轮询偏移量。
关闭¶
长轮询和 Webhook 账户即使在 15 秒入站关闭宽限期过期后,也会等待已准入的重放提交或回滚。已接受的群组介绍会在账户关闭完成之前,继续通过其现有的 60 秒代理轮次预算以及随后的去重提交进行跟踪。在介绍被接受之前取消会阻止其开始。普通处理程序和 bot 的关闭宽限期保持不变。
插件钩子¶
没有任何插件钩子能够将 Telegram 的传输确认延迟到插件拥有的持久化完成:
message_received是对已接受入站轮次的即发即忘观察。before_dispatch是正常模型分发之前的条件声明。before_agent_run是模型提交前的门控,并且仅在模型轮次到达该阶段时运行。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw