定时节拍 · Inbound Webhook · CI 回调与幂等闭环清单
许多小团队已经跑通 OpenClaw Gateway，却暂时不想或不能接入 Slack、Telegram 等 IM 通道，又希望用定时巡检、外部系统 Webhook、CI 流水线终态来驱动自动化。本文给出三类触发方式的适用边界、鉴权与幂等选型矩阵，以及六步可复现 Runbook；文末附生产向参数锚点与 FAQ，便于直接写进工单与值班手册。
聊天通道至少提供了「谁在说、在哪个线程」这一层天然上下文；一旦完全改为 HTTP 与定时触发，若缺少统一契约，排障会退化成在海量日志里猜来源。上线前建议逐项对照以下痛点：
重复投递与副作用翻倍：上游 CI 或 Webhook 中间层常因超时重试而重复 POST；若没有幂等键与去重窗口，同一条流水线可能被当成多次成功终态。
鉴权形同虚设：仅依赖「URL 保密」会在日志与代理层泄露后全线失守；应至少升级到共享密钥头、HMAC 或 mTLS 之一。
节拍与维护窗口冲突：在常驻节点上做系统补丁时，若 cron 仍全速触发，会出现半初始化状态下的危险写操作。
跨区时钟与顺序假设错误：多地区节点各自触发时，不能默认「先收到的就是先发生的」，需要事件时间与单调序号。
可观测字段不足：没有 request id、上游 job id、幂等键三段式字段时，几乎无法把失败请求与业务工单对齐。
把触发方式当成产品需求来选：延迟敏感度、是否需要强一致、是否能容忍几分钟级漂移，将直接决定你用固定节拍、Inbound Webhook 还是 CI 回调。
| 触发类型 | 典型场景 | 优势 | 主要风险 |
|---|---|---|---|
| 定时节拍（cron / launchd / systemd timer） | 巡检、日报汇总、清理临时文件 | 实现简单、可预测负载 | 与真实事件脱节；维护窗口需显式暂停 |
| Inbound Webhook | 工单系统、内部审批、监控告警 HTTP 出口 | 近实时、与业务事件对齐 | 重复投递、伪造来源、TLS 与代理链路复杂 |
| CI 终态回调 | 构建成功后的镜像签名、发布闸门 | 与版本产物强绑定 | 平台重试策略不透明；payload 版本漂移 |
组合建议
对「必须发生一次」的副作用（写库、发版、改外部状态），优先使用 Webhook 或 CI 回调 + 幂等存储；定时节拍更适合只读聚合与健康探测。若 Gateway 暴露在公网，务必前置反向代理并收敛监听面，具体 TLS 与端口自检可参考站内 OpenClaw 安装与 Gateway 排障清单。
以下步骤按「先验证、再放量」顺序排列，可直接粘贴到团队 wiki；变量名可按你们的密钥管理方案替换。
冻结触发契约：为每种事件定义 JSON 字段集：event_time、source、job_id、idempotency_key、payload_version；拒绝未携带版本号的未知字段。
在边缘层做鉴权：在反向代理或 API 网关校验 Authorization 共享密钥或 HMAC 签名，并配置 IP 允许列表；Gateway 进程本身只信任内网入口。
接入幂等存储：以 idempotency_key 为主键写入短期 TTL（如 24～72h）的去重表；重复请求返回同一业务响应码，避免上游疯狂重试。
为定时任务加「维护闸门」：用文件标记或 etcd 键表示维护中；脚本首行检查闸门，命中则只写心跳日志并退出。
打通观测三件套：为每条入站请求生成 request_id，回写到响应头；结构化日志必须包含 job_id 与幂等键摘要（可哈希后落盘）。
做一次故障演练：人为重复 POST 三次、拉断上游 30 秒、再恢复；验证无副作用翻倍与告警路由正确。
curl -sS -X POST "https://gateway.example.internal/hooks/ci" \
-H "Authorization: Bearer ${HOOK_SECRET}" \
-H "X-Idempotency-Key: ${CI_JOB_ID}-${CI_CONCLUSION}" \
-H "X-Request-Id: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"payload_version":1,"job_id":"'"${CI_JOB_ID}"'","conclusion":"success"}'
没有银弹：内网-only 与公网入口的威胁模型不同。下面给出常见组合的取舍，便于评审会上快速对齐。
| 方案 | 适用边界 | 必须配置的参数 |
|---|---|---|
| 共享密钥 + TLS | 内网或零信任隧道已就绪 | 定期轮换密钥；响应中不回显密钥 |
| HMAC 请求签名 | 公网 Webhook、多上游 | 时间戳窗（如 ±300s）；常量时间比较 |
| mTLS | 企业 CI 与自建控制面 | 证书轮换与吊销列表；短 TTL leaf |
幂等键设计提示。建议格式为 {source}:{stable_id}，避免把毫秒时间戳单独当主键，否则重试时极易失效。
不要在日志里打印完整密钥或令牌。只保留前缀与哈希摘要，否则任一日志平台泄露都会变成二次事故面。
下列数值来自常见生产实践的收敛区间，用于自检清单而非单一厂商承诺；请按你们 SLA 调整。
完全自建调度与常驻节点当然可行，但要长期扛住跨区网络抖动、系统升级与磁盘健康度，会迅速吃掉工程带宽；本地开发机休眠或断网时，定时与 Webhook 更容易出现「半成功」状态。把 Gateway 与触发入口固定在 VpsMesh 始终在线的 Mac Mini 云端节点上，通常能用更稳定的出口 IP、可控的维护窗口与硬件级隔离，把非 IM 自动化从实验脚本推进到可值班的生产闭环。
可以。关键是把触发面收敛为少数受控入口，并为每条请求配置幂等键与可观测字段。需要先把 Gateway 装稳时，可先对照 安装与 doctor 排障清单 完成基线，再开放 Webhook。
重复投递与未校验来源。至少使用共享密钥或 HMAC，并在边缘层做 IP 限制；幂等表命中时应返回与首次一致的业务语义，避免上游指数退避失控。若要评估节点与出口稳定性，可先浏览 价格页 了解可按地区扩展的套餐。
维护窗口与定时节拍错峰、时钟同步、跨区回调超时加长。更多远程开发与 SSH 基线可查阅 帮助中心 的可公开文档。