跳转至

传输

长轮询是默认方式。当有 HTTPS 入站可用时，Webhook 模式是替代方式。

长轮询与 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 路径。其他 Gateway 保留路径在你更新 webhookPath、webhookUrl 和反向代理映射时，可以继续通过旧版监听器接收回调；在设置 legacyWebhook: false 之前，请验证投递。禁用旧版转发后，保留路径会产生可操作的启动错误。使用 openclaw channels status --probe 验证 热重载 是否已应用路由变更。

在长轮询模式下，OpenClaw 会在更新提交到持久入站队列后保存其重启位置。失败的处理程序仍可从该队列重试。

Webhook 路由在 Gateway HTTP 端口（默认 18789）上可用。将 webhookUrl 的反向代理指向该端口和 webhookPath。OpenClaw 会在每次 Webhook 启动时（包括重启后）向 Telegram 注册已配置的公共 URL；它会保持该 URL 不变，因为它无法推断外部代理的上游。Telegram 的 secret 请求头仍是认证边界，因此该路由不需要 Gateway bearer token。

当省略 legacyWebhook 时，Webhook 模式会保留位于 127.0.0.1:8787 的先前转发端点，因此现有回调和反向代理可继续工作。两个端口使用相同的 Gateway 路由处理程序和 Telegram secret 验证。若要仅使用 Gateway 端口，请移动反向代理上游，验证传入消息，然后设置 legacyWebhook: false。删除该设置会恢复默认监听器。

旧版端口保留其未认证的 /healthz 响应（200、纯文本 ok）以及账户本地的 secret 失败速率限制。健康检查匹配是精确的：查询字符串、尾部斜杠、大小写变化和编码变体都不是健康检查。HEAD 返回相同状态但不带响应体。标准 Gateway 端口保留其自身的探测和响应头行为。

升级后，运行 openclaw doctor --fix。Doctor 会备份配置，并将旧的 webhookPort 和 webhookHost 设置迁移为 legacyWebhook: { port, host }，保留仅 host 设置且端口为 8787。显式端点对象会覆盖默认值；省略对象中的 host 时使用 127.0.0.1。现有的 legacyWebhook: false 设置在迁移期间保持禁用。

命名账户继承通道的 legacyWebhook 设置。账户级别的 false 会禁用该账户的旧版端点，即使通道配置指定了端点。显式账户端点会覆盖继承的 false。只要另一个账户仍在使用该端点，共享的旧版套接字就会保持打开。

单独安装的 Telegram 插件也支持 2026.9.6 host，该 host 早于 Gateway 拥有的转发监听器。在该 host 上，插件为每个账户保留一个直接监听器，具有相同的 Telegram 请求处理程序和准入保证。账户必须使用不同的旧版端点；共享旧版端口需要更新的 host。Gateway 路由和 legacyWebhook: false 仍然可用。Doctor 会将此兼容性指导作为警告打印，因为该 host 不显示信息性通道说明。当插件声明的最低 host 包含 Gateway 拥有的旧版监听器时，可以移除该适配器。

当 webhook secret 不同时，账户可以共享一个 Gateway 路由。匹配多个账户的请求会被拒绝；在将流量迁移到 Gateway 端口之前，请分配不同的 secret 或路径。迁移后的旧版端点会为先前在各自显式端口上共享 secret 和路径的账户保留账户选择。

Webhook 模式会验证请求防护、Telegram secret token 和 JSON 主体，然后在返回空 200 之前将更新提交到其持久入站队列。成功的持久采纳包含 x-openclaw-delivery-accepted: durable；健康、路由、认证、验证和存储错误响应会省略此请求头。反向代理和 host 控制器可以要求该请求头，以区分 OpenClaw 采纳和通用的空 200，而无需从响应时序推断接受。

持久写入后，OpenClaw 通过核心通道入站排空机制认领并处理更新（每聊天/每主题车道，在回合采纳时完成，采纳前停滞超时）。缓慢的 agent 回合不会持有 Telegram 的投递 ACK。

入站确认边界

Telegram 确认由持久队列准入控制，而不是由插件钩子或 agent 回合完成控制。Webhook 模式使用上述边界；长轮询使用以下顺序：

  1. 轮询工作进程接收一个 Telegram 更新并等待。
  2. OpenClaw 以事务方式将原始更新入队到 state/openclaw.sqlite 中账户范围的 channel_ingress_events 队列。
  3. 入队成功后，OpenClaw 安排持久化重启偏移量并确认工作进程，使轮询可以继续。
  4. 共享排空机制单独处理已入队的更新。如果准入失败，OpenClaw 会拒绝工作进程确认，而不是静默推进。

offset queued 表示重启偏移量写入已安排，但未提交。如果该写入完成前发生崩溃，Telegram 可能会重新投递一个已入队的更新。队列仅在其待处理行、已完成墓碑或失败行仍然存在时拒绝相同的传输事件 ID。这是有界重放去重，而不是精确一次处理。参见 持久入站与重放去重。

重放限制

两种传输在接收更新之前都会记录账户的机器人身份，即使没有轮询偏移。替换已知机器人时，会在替换开始前清除其旧的入站行。同一机器人重启和令牌轮换会保留排队工作和重放保护，没有已知先前身份的旧版队列也是如此。如果身份准备失败，账户启动会停止并出现错误，要求你重启账户；中断的重置会保留先前身份以便重试。

对于每个 Telegram 账户队列，已完成的墓碑和失败行最多保留 30 天，并且每类上限为 1,000 条。先达到哪个限制，该类的保留即结束。完成时会清除入站负载和元数据，同时保留事件身份。

在副作用之后、队列完成之前发生的崩溃可能会重复该副作用。参见传输保留、至少一次副作用和入站死信。

文档中说明的持久性边界是 SQLite 事务成功完成，而不是单独的逐事件 fsync 保证。请使用持久状态目录；删除它会同时丢失排队更新和已保存的轮询偏移。

关闭

长轮询和 webhook 账户即使在其 15 秒入站关闭宽限期过期后，也会等待已接受的重放提交或回滚。已接受的群组介绍会在账户关闭完成前，通过其现有的 60 秒代理轮次预算以及随后的去重提交继续跟踪。在介绍被接受之前取消会阻止其开始。普通处理程序和机器人关闭宽限期保持不变。

插件钩子

没有插件钩子可以将 Telegram 的传输确认延迟到插件拥有的持久化完成：

  • message_received 是对已接受入站轮次的即发即忘观察。
  • before_dispatch 是正常模型分发前的条件声明。
  • before_agent_run 是模型提交前的门控，仅当模型轮次到达该阶段时运行。

它们均不会将原始更新作为持久化边界接收。参见消息和投递钩子和钩子目录。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw