OpenClaw gateway circuit breakers for flaky upstream tools: failure thresholds, half-open probes, metrics hooks, coordination with HTTP 429 Retry-After and token throttles, read-timeout diagnostics, health monitoring, and macOS rehearsal on cloud Mac mini

エージェントゲートウェイはモデル、ベクター保存、専用HTTPツールに扇状にリクエストを分岐させます。上流のどれかが振れたとき、素朴な再試行は、すでに病みついた依存先へ到達回数を掛け算し障害を増幅します。2026 年、本番の OpenClaw では指数バックオフに加え、誤差予算を超えたところで サーキットブレーカー（閉→開→半開）を扱い、全負荷を受け入れる前に小さなプローブを挟みます。本稿は実用閾値、半開の拍、Prometheus へ出すべき系列、429 と Retry-After の手繋ぎ、テナント毎のトークン予算との合流、リード・タイムアウト診断と人工ヘルスが、健全部と誤解されない条件を定義します。合わせて 429/Retry-After 対応、トークン制限、読取タイムアウト、可用性モニタ へ。

コスト観点：専用 Mac mini（MacHTML 約 16.9 米ドル/日）で挙動を週内リハに載せるのは、回復中の上流に半開嵐をもう一発食らわせるインシデント対策として安い、という位置付けです。

ブレーカー無し再試行が壊す理由

再試行は一過性壊れを仮定します。上流が持続的に悪化—ロック渋滞、期限切れ証明書、地域的パケット喪失—のとき、各再試行は最も息苦しい地点へ負荷を足します。ゲートは一台の手で6本ツール等を同時起動し得、各3回・200ms 間隔の再送なら1ジェスチャで 18 失敗呼出が列びます。サーキットブレーカーは、冷却が終わるまで繰返し失敗を高速な局所失敗にまとめ替え、被害を上限制御します。

OpenClaw は同期HTTPとストリーミング行路が混在するため、ブレーカの粒度は「依存1件」—プロセス全体ではない。揺らぐ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 試行。開条件は (A) 連続 5 回の輸送系失敗、または (B) 窓内サンプルの 60% 超 が 5xx。連鎖は全黒化を早察知、比率は部分悪化を拾います。

ストリーム行路は分類を誤らないこと。トークン配信後の中間リセットは課金紛争で、本来ブレーク不要の可能性。「ヘッダ未到」カラムと「40%到達ところで断流」カラムを分け持つ。

半開プローブと同時実行

半開は最も危険：プローブ過多は、避けたはずの轟音群を再燃。依存毎 250ms あたり 1 飛行、ジッタ 50ms まで。完全閉まりにはワーカーが異なる2連続成功を要請。ホスト 12 台なら、各が独自に刺さないよう小さな Redis 室かリーダ選出で直列化。

Prometheus / SLO

最低限 breaker_state ゲージ、breaker_transitions_total（from/to ラベル）、breaker_rejections_total（開中の即拒否）、breaker_probe_latency_ms ヒスト（25ms〜2s 桶）。既存の要求遅延ヒストと重ね、遷移前に遅延が上がっていなかったか可視化。

ラベルは低基数（依存名/地域/環境）。SLO 火元と合わせ、再試行方針が本当の障害か配分枠を延ばしただけかを分ける補助系列を置くと、事後検証が楽。

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

HTTP 429 / Retry-After

上流が 429 かつ Retry-After: 120 なら、冷却基準はそちら。半開再突を先に起こすローカ窓があっても、開猶予を少なくとも 120 秒 延す。breaker_retry_after_skips_total など専用系列で「配分枠延長回数」を切り、二値失敗にせよ、と切り分け。詳は 429 手引。

トークン枠とスロットル

枠は支出を、ブレークは体調を。シグナル交換：モデル A で開いたら、A 固定の計画に対する有効枠を減算し、B へ。ユーザに見える枠を確定失敗へ燃やすのを避ける。部分ストリーム二重徴収を避ける具体配線は 枠/スロットル稿 参照。

タイムアウトと分類

厳密リード枠越えだけを理由に、正当な重いツールで開かない。 context deadline exceeded と相手先RSTを区別。分類法は 読取タイムアウト稿。半開プローブの猶予は、本番 P99+余裕% に合せる。

合否とゲージ

合否路は定位置カナリア、ブレークは生トラ。両方。緑合否に騙されうる：稀行路が欠片化したとき。一方短期スパイクはカナリア逃れでも遮断。 死活 とブレーク計が 3 分 食い違い続けたらアラート通知を。

比較

方式	主目的	用いる信号	ユーザーへの見え方
サーキット	上流保護	5xx率、連鎖失敗	手早い失敗＋次の行動提示
スロットル	予算保護	毎分トークン、階層	安価モデルへ
待ち列	山をなだめる	深さ/滞留	遅延増、非致命

macOS リハ

launchctl タイマで、保存済み 10RPS/5 分 再送＋ 503 注入。Linux 仮想と違い keepalive 初期値等が違い得る。クラウド Mac で半開猶予が「Linux 前提のTCPユーザ時間アウト」と矛盾しないか。

展開手順

1. 各上流に固有名/ラベル。
2. 遷移が 15s 内にGrafana へ。
3. 429 手引通り再試行ヘッダ解析、から半開自動化。
4. 本番P99+40%でプローブ読枠。
5. 二依存同時に開かせ、隔離性。
6. エラーコード上書き、ユーザに落ちにくい。
7. 週1のミニ+LaunchAgent。
8. 枠/冷却同時飢餓を点検。

Q&A

GraphQL と REST は1本？

分片違いなら分割。1本化は局所欠陥隠し。

半開を本路と同じプール？

UA/ヘッダ専用でSLO から分離可能に。

WebSocket？

メッセ層失敗。初回pingTOで開くのは、Wi-Fi移動利用者にフラップ。

弾力ゲートは、式だけでなく、演習課題。MacHTML クラウド Mac mini（週 約16.9 米ドル/日）を借り、LaunchAgent 直注入と半開時計と、実スクレイプ負荷の感触を、本参前に macOS 上で揃えられます。