OpenClaw 网关断路器：上游工具抖动、失败阈值、半开探测、指标钩子、与 HTTP 429 Retry-After 及令牌节流协同、读超时诊断、健康监控与云 Mac mini 上的 macOS 演练

智能体网关会把流量扇出到模型、向量库与定制 HTTP 工具；任何上游抖动时，朴素重试都会把请求成倍砸向已生病的依赖，在 2026 年的生产 OpenClaw 集群里，工程团队普遍把指数退避与断路器并用：先在有限错误预算内从闭合切换到开路，再以受控的半开探测恢复流量。本文给出可操作的阈值、半开节奏、应导出的 Prometheus 指标、如何让断路器尊重带 Retry-After 的 429、如何与每租户令牌预算协同，以及读超时挂起诊断与合成健康检查如何避免“断路器开着却误以为业务健康”的错觉。请同时阅读 《提供商 429 与 Retry-After》、《令牌预算与工具节流》、《网关读超时挂起诊断》 与 《网关健康监控》，让重试、预算、超时与探针讲述同一套故事。

成本视角：在专用 Mac mini 上复现网关行为，MacHTML 云主机约 $16.9/天，通常低于一次半开风暴把正在恢复的上游再次打穿的事故成本。

断路器不是替代码“藏错误”，而是把系统性故障与偶发抖动区分开。建议以 30 秒滑动窗口记录至少 20 次采样，再评估 60% 的 5xx 占比或 5 次连续传输失败作为开路触发条件；半开阶段把探测频率限制为每依赖每 250ms 最多一次，并要求跨线程的连续成功才完全闭合。Prometheus 侧至少导出状态 gauge、状态迁移计数、开路期间的快速失败计数，以及 25ms 到 2s 桶的探测耗时直方图。

与令牌节流的协同要点：断路器保护上游健康，节流保护预算；当某模型提供商断路器开路时，应在编排层下调仍指向该提供商的计划权重，避免把用户可见的调用额度浪费在注定失败的链路上。遇到 429 且 Retry-After: 120 时，应把冷却计时至少延长 120 秒，并单独计数“因 Retry-After 跳过半开”的次数，便于区分配额型停顿与硬故障。

读超时不要把“慢工具”误判为“死连接”：结合 context deadline exceeded 与连接重置信号分类，再为半开探测设置贴近生产 P99 再加 40% 余量的读期限。健康探针与断路器 gauge 若连续 3 分钟不一致，应触发人工核对，避免合成路由全绿而真实流量已大量被开路拒绝。

在 macOS 上用 LaunchAgent 以 10 RPS 重放五分钟抓包流量，再注入合成 503，可验证半开定时器与 Linux 容器默认 TCP 行为的差异。把演练脚本纳入每周值更清单，并把 Prometheus 抓取间隔与生产对齐（常见 15 秒 业务指标、关键 SLO 信号 5 秒），能显著降低“只在笔记本上通过”的风险。

变更管理方面，应为每个上游依赖使用稳定的断路器键，标签包含区域与凭证指纹，避免无关工具被同一条开路状态误伤。发布前在变更单附上本次调整的阈值表与回滚开关位置；灰度期间对比拒绝率与 p95 延迟，确认快速失败没有推高客户端重试风暴。若网关同时暴露 GraphQL 与 REST，请拆分断路器以免局部故障被掩盖。

团队若跨时区协作，可把半开探测流量打上专用头部或用户代理，便于在日志平台过滤出“非用户请求”。遇到 WebSocket 类工具，请在消息级单独计数，避免首次 ping 超时就抖动开路。最后，把云 Mac 演练产出的时间线截图与指标面板链接附在事故复盘模板里，让下一次讨论有共同参照。

指标命名建议固定前缀如 openclaw_breaker_，标签只保留低基数维度（依赖名、区域、环境），不要把用户 id 或会话 token 写进标签。导出 breaker_state 时可用 0/1/2 表示闭合、半开、开路，同时在 Grafana 配好颜色阈值，避免值班同学误读。若使用直方图，请限制桶上界在 2 秒以内并丢弃极端长尾样本，以免拉低聚合可读性。

与发布系统的衔接：在蓝绿或滚动发布期间，短暂上升的错误率可能触发断路器，应把发布窗口与半开冷却对齐，或在发布脚本里临时提高阈值并记录审计字段。对多租户网关，可为不同租户设置独立错误预算，防止单一租户异常流量拖垮共享依赖。若采用 Redis 作为半开协调单元，请为键设置合理 TTL，并在故障演练中验证 Redis 分区时网关仍能安全失败。

面向代理团队的文档应包含“断路器开路时客户端可见错误码表”，让上层规划器能切换到备用工具或降级模型，而不是把异常直接抛给终端用户。对关键依赖，建议保留人工强制半开的开关，并在操作手册写明前置检查项。演练结束后，请把 Prometheus 查询截图与阈值调整合并请求关联，形成可追溯的变更链。

当网关同时承载同步 HTTP 与流式模型响应时，应为两类路由维护独立计数器，并把半开探测流量路由到影子集群或低权重上游，避免探测本身制造额外负载。对跨地域部署，可在断路器键中加入区域后缀，防止一个区域的抖动触发全球开路。若使用 Envoy 或 nginx 作为边缘，请确认重试次数与网关断路器策略一致，避免边缘与内核重复放大重试。请把以上策略写进值更手册并季度复审，同时保留演练录像链接，便于审计与培训复用，降低知识孤岛风险并提升协同效率与稳定性。

没有断路器时，重试如何伤生产

重试往往假设故障是瞬态。当上游进入持续失败（锁竞争、证书过期、地域性丢包），每次重试都在最窒息的地方堆负荷。网关在单轮对话里可能并行呼出六个工具；若每工具 200ms 间隔重试三次，一次用户手势就堆出 18 次失败调用。断路器把连番失败转成本地快速错误，在冷却期结束前不再向上游补刀。

OpenClaw 常混合同步 HTTP 与流式模型，断路器必须按依赖而非按进程切分：CRM 搜索 API 不稳，不应连坐同一池里健康的计算工具，除非争的是同一类套接字。用“供应方+区域+凭据指纹”作键，避免误绑。

闭合、开路、半开

闭合：全量通过，正常计测。过阈则开路：后续快速失败，代理能把“依赖不可用”读懂并换路。经一段通常由历史 p95 恢复时间推得的休眠，进入半开，只放少量探针。探针成串则合闸；再败则把冷却加倍再开。

enum BreakerState { Closed, Open, HalfOpen }

func (b *Breaker) Allow(now time.Time) bool {
  switch b.state {
  case Open:
    if now.Sub(b.openedAt) < b.cooldown { return false }
    b.state = HalfOpen
    b.probeBudget = 1
    return true
  case HalfOpen:
    return b.probeBudget > 0
  default:
    return true
  }
}

阈值与滑动窗

由真实流量定标。HTTP 工具常从 30 秒窗、至少 20 次样本起评；触发可为连续 5 次传输失败，或窗内 5xx 超 60%。连击计数抓全断，比例计数抓局部坏流。流式路由要分辨：发完 token 后中途 reset 也许只是账单争议，应单独统计“头未到”和“流在 40% 处被掐”。

半开探针

半开最险：探针一多就是二次惊群。每依赖 250ms 最多 1 个在途，抖动 50ms，要跨工作线程的两次连续成功才完全合闸。12 个 worker 时应用 Redis/选主令各主机别各扎一针。

指标

至少输出 breaker_state 按依赖、breaker_transitions_total、开路即拒的 breaker_rejections_total、25ms~2s 桶的 breaker_probe_latency_ms。与请求直方图叠看，能判断是不是先慢后断。低基数标签，别塞用户 id。

# HELP breaker_state 0=closed 1=half_open 2=open
breaker_state{dep="crm_search"} 2
breaker_rejections_total{dep="crm_search"} 184

429 与 Retry-After

若上游 429 且 Retry-After:120，这条冷却优先：至少把开路计时再延 120 秒，并计 breaker_retry_after_skips_total 以区分“配额停”和“真挂”。详文见 429 专稿。

令牌与限流

令牌管花多少，断路管病不病。A 方断路开，应下调仍绑 A 的计划的等效预算，好让编排转 B，别把用户可见额度烧在必败链上。见 令牌/限流，避免断流双计。

读超时

别因“又慢又正规的大任务”越读限就判死；分清 context deadline exceeded 与对端 reset。挂起诊断 帮半开探针设贴近 P99+40% 余量的读期限。

健康对表

合成打固定金丝雀，断路看真实混流，两条线都要。绿康也可能骗：鲜有人走到的分片坏了。断路也许只是尖峰。若 健康面板 与表头 3 分钟谈不拢，该叫人。

对照

机制	主目标	信号	用户侧
断路	护上游	5xx、连击	快错+可执行提示
限流	护预算	分·档	改走便宜模型
排队	削峰	深、龄	慢、少硬 5xx

macOS

用 launchctl 10 RPS 跑 5 分钟抓包，再注 503。与 Linux 容器比，keepalive 缺省与 TCP 用户态超时略异，上云 Mac 合一下半开时钟。

检查

1. 一依赖一键，Prom/Grafana 标签齐。
2. 15s 内能看到迁态。
3. 接好 429 解析再开半开自动探。
4. 探针读期≈P99+40%。
5. 两依赖同开，验证隔离。
6. 写清代理可见错误号。
7. 周周 Mac mini+Launch 剧本。
8. 看冷却期与令牌别同时饿死预算。

问

GraphQL+REST 共用一个？

分片不同要劈开，一罩遮羞局部挂。

探走主池？

可单配 UA/头，好从 SLO 里剔。

WebSocket？

分消息，别首 ping 就踢，防 Wi-Fi 换网抖。

要韧网关，式子与排演都重要。MacHTML 租 Mac mini 约 16.9 美元/天，在真 mac 网里测 Launch/半开/抓取，再上生产。