痛点与目标
一 把 Webhook URL 复制进每台 Mac,泄露面与防火墙例外线性膨胀。二 逐行日志推送导致卡片刷屏,真正失败原因被淹没。三 令牌轮换时若无单一责任点,易出现半旧半新双写或静默丢通知。
对照:单网关 vs 每节点直连
| 维度 | 推荐:单网关 + 队列 | 不推荐:每节点直连 Webex |
|---|---|---|
| 密钥轮换 | 改一处秘密文件并重载网关 | 需滚动 N 台主机与流水线密钥注入 |
| 出站策略 | 白名单单一目标主机名即可 | 池内每台都要放行同一域名 |
| 消息一致性 | 统一模板、去重、失败摘要长度裁剪 | 格式分叉、重复卡片概率高 |
落地步骤清单
- 在 Webex 目标空间创建 Incoming Webhook,复制 HTTPS URL,不在聊天中粘贴全文。
- 将 URL 写入网关主机
/etc/openclaw/secrets.d/webex/build-status.url(示例路径),权限0440,进程用户加入专用组。 - 各 MeshMac 节点在任务进入终态时向队列投递 JSON:
workflow、state、branch、短commit、run_url、mesh_node_id、provider_run_id、失败时的两行以内摘录。 - 网关消费队列:按
provider_run_id与状态迁移去重后拼装markdown,Content-Type: application/json发出POST。 - 在网关执行
curl探针验证 TLS 与代理;与 网关限流与会话并发 对齐超时,避免慢响应拖死消费者。 - 对
429、503启用下文退避;对400、401先修负载再考虑重试。 - 轮换:新建 Webhook → 更新秘密文件 → 重载 → 发探测消息 → 删除旧集成(与 密钥与节点最小权限 同一运维节奏)。
可引用基线:① 失败摘要控制在约三百汉字内并附 run_url。② 去重窗口建议十五分钟量级(按队列延迟调整)。③ 出站重试最多五次带抖动。
Webhook 配置
在 Webex 客户端或控制中心为目标空间添加 Incoming Webhook,记下一次性 URL。网关侧使用 application/json,正文至少包含 markdown 或兼容字段的纯文本摘要;避免把整份日志贴进 JSON,否则易触发负载限制并返回 400。与 共享构建 Webhook 通知 相同,仅网关进程读取该 URL,构建节点只认识队列地址。
- 测试与生产使用不同 Webhook,避免沙箱流水线刷屏业务空间。
- 调试日志只打印
webexapis.com主机名与 token 片段末四位。
最小权限
Incoming Webhook 的 URL 路径即等同密码的凭据:任何持有者可向空间发帖。文件权限建议 0440、目录 0750;交互式开发者账号与 CI 运行用户不应加入能读取该文件的组。若另需 Bot Token 调用 REST(线程回复等),分文件存放并与 Webhook 隔离审计。更多分区做法见 多节点负载与故障转移步骤 中的责任划分表。
重试退避
仅对可恢复错误重试:429、502、503、504。若响应头含 Retry-After,优先按该秒数休眠;否则采用指数退避(例如从约一秒起倍增)并加全抖动,总尝试不超过五次。不要对 400 与 401 盲目循环重发,以免放大封禁风险。队列侧合并策略可对照 任务队列与重试步骤。
常见 4xx/5xx 处理
| HTTP | 含义与处理要点 |
|---|---|
400 | JSON 非法、缺必填字段或正文过长;缩短 markdown,仅保留节点名、分支、结论与链接。 |
401 | URL 令牌失效或空间策略变更;轮换 Webhook,勿在同一请求上无限重试。 |
404 | 集成被删或 URL 抄错分段;用控制台核对并换新 URL。 |
429 | 触顶限流;遵守 Retry-After,否则退避并降低并发发帖。 |
502/503/504 | 上游或边缘短暂不可用;有界退避重试并记录关联 provider_run_id。 |
多节点协作价值
池化多台 MeshMac 后,价值在于并行吞吐而非「多份通知管道」。把 Webex 出站收敛到单网关,队列里仍保留各节点的 mesh_node_id,团队即可在一张卡片上对比环境差异与同一 Pull Request 在不同机器上的终态;审计上也能明确「谁最后对外的帖子负责」。这与企业 IM 的单一真相源习惯一致,后续接入变更日历或 on-call 轮值也更自然。
排错速查
| 现象 | 优先检查 |
|---|---|
| CI 绿但空间无消息 | 网关日志是否出现出站 POST 与 2xx;本机最小 JSON 探针;代理是否放行 webexapis.com。 |
| 仅部分节点无卡片 | 该节点是否仍直连 Webex 或使用了过期环境变量;强制只写队列。 |
| 间歇重复卡片 | 缺冪等:为 provider_run_id 加终态去重后再调用 Webhook。 |
| 突然全部 401 | 是否批量轮换却只更新了一半主机;确认仅网关持密。 |
下一步(公开页)
把通知管道收敛到网关,池化节点只管构建
公开页可对比套餐与节点区域,帮助中心含远程访问与并发建议;OpenClaw 专栏汇总多 IM 对照 HowTo。