1. Webhook 和 Polling 的核心区别
Polling 是你的程序主动去平台服务器问：“有没有新消息？”；Webhook 是平台服务器主动把新消息推送到你的 HTTPS 地址。
Polling: Agent Gateway -> Platform API -> pull updates Webhook: Platform Server -> your HTTPS endpoint -> Agent Gateway
两者最终都能把消息交给 Agent，区别在于谁主动发起连接，以及你是否需要一个公网可访问的回调地址。
2. 选型对比
| 维度 | Polling | Webhook |
|---|---|---|
| 公网地址 | 不需要 | 需要 HTTPS 回调地址 |
| 部署难度 | 低，本机也能跑 | 中，需要证书和反向代理 |
| 延迟 | 取决于轮询间隔 | 通常更低 |
| 可靠性 | 进程自己控制重试 | 平台推送失败需要处理重试 |
| 扩展性 | 小规模够用 | 适合高并发和多实例 |
| 适用场景 | 个人助手、小团队、内网环境 | 公开服务、高并发、生产平台 |
3. Agent Gateway 场景里的特殊考虑
传统 Bot 回复通常很快，但 Agent 可能会进行多轮推理、检索记忆、调用工具、生成文件或请求外部 API。因此接入模式不仅要看消息到达，还要看平台的超时机制。
- 长任务应先返回“处理中”，再异步发送最终结果。
- Webhook 需要尽快返回 HTTP 200，避免平台反复重试。
- Polling 可以把消息消费节奏掌握在 Gateway 自己手里。
- 公开服务要做幂等处理，避免同一条消息被重复执行。
经验：Agent 工具调用越复杂，越要重视队列、幂等和超时兜底，而不只是选择 Webhook 或 Polling。
调试 Webhook 常用工具
Webhook 调试经常需要检查请求体、签名、时间戳和回调响应。
4. 实际怎么选
如果你只是给自己或小团队搭一个 Agent 助手，优先选 Polling。它部署快、问题少，不需要域名和证书。如果你要面向公开用户、要稳定低延迟、要多实例扩展，再考虑 Webhook。
| 需求 | 推荐 | 原因 |
|---|---|---|
| 本机调试 Bot | Polling | 无需公网回调地址 |
| 内网部署 Agent | Polling | 平台无法访问内网 Webhook |
| 公开 SaaS Bot | Webhook | 低延迟，易扩展 |
| 消息量很大 | Webhook + 队列 | 便于削峰和并发处理 |
5. 常见坑
- 同时开启两种模式：Telegram 场景里，Webhook 和 Polling 同时存在容易导致消息收不到。
- Webhook 处理太慢：平台认为请求失败，可能重复推送同一事件。
- 没有幂等：重复事件触发重复工具调用，尤其危险。
- 没有限流：公开 Bot 被刷消息后，模型额度迅速消耗。