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/半開/抓取，再上生產。