1. 痛みの核: 429とタイムアウトは別の失敗モード
(1) 429はクォータ意味論: RPM/TPM、組織同時実行、エッジのレート制限など。タイムアウトを盲信して伸ばすと、同一バケットを叩き続け悪化させがち。(2) タイムアウトは経路意味論: DNS、TLS、リバースプロキシのアイドル、コールド起動の遅延。接続タイマと読み取りタイマを分離して観測する。(3) チャネル沈黙: モデルが返さない場合もあれば、返したのにACKや再試行が壊れている場合もある。ログでモデル・Gateway・チャネルのどこに原因があるかを割り当てる。
運用では「ユーザーから見えない失敗」を一つのラベルで扱いがちだが、HTTPステータスと経過時間をペアで記録すると、再発パターンが読みやすくなる。特にストリーミング有無はタイムアウト分布を大きく変えるため、インシデント票の必須項目に含める価値がある。
2. マルチプロバイダルーティング行列
この表は「勝ちベンダー」を決めるためではなく、障害の隔離のため。プライマリはコストと品質、バックアップは生存性。キー輪番の所有者、ブレーカ閾値の承認者、バッチ自動化と決して同じクォータを共有してはいけないチャネルを文書化する。
| 戦略 | 効くとき | リスク |
|---|---|---|
| プライマリ/バックアップBase URL | 同一のOpenAI互換面で複リージョン・複ベンダー | コストとログの断片化。照合用にリクエストIDを残す |
| モデルエイリアスの段階的ダウングレード | ピーク時は可用性を品質より優先 | 文体のブレ。必要ならシステムプロンプトで明示 |
| サーキットブレーカ窓 | 429/5xx連打後のスラッシング停止 | 誤設定でバックアップ枠を一瞬で枯らす |
| チャネル別ルーティング | 公開サポートと社内ツールを経路分離 | 運用複雑度。ルーティング表を単一の正とする |
3. オンコール五段階ルンブック
- 証拠の固定: UTC窓、チャネル、モデル名、ストリーミング有無。ステータスコードとログ抜粋を保存。
- 層状プローブ:
openclaw status、Gatewayヘルス、続いてBase URLへの最小curl（本番秘密をチャットに貼らない）。 - 429とタイムアウトの分離: 429はクォータ/バックオフ、タイムアウトはネットワーク/プロキシ/読み取り上限。混在時はまず同時実行を下げる。
- フェイルオーバー設定: 再試行上限、ジッター付き指数バックオフ、ブレーカ復帰間隔、バックアップの日次予算上限。
- ポストモーテム一行: 根本原因（クォータ、DNS、プロキシ、キー輪番、launchd環境）を分類しログ時刻へリンク。
4. 引用可能な閾値
ベンダーSLAと自社テレメトリに置き換えて運用してください:
- 同一モデルが10分以内に5回以上連続で429を記録しバックアップがあるなら経路を切り替え、クォータ方針の担当へエスカレーション。プライマリを無限再試行しない。
- 読み取りタイムアウトの中央値が60秒を超えTLS/DNSエラーが混ざるなら、コンテキスト長より先にプロキシアイドルとエグレスを疑う。
- リモートMacのlaunchd Gatewayでシェルexportとplistの
EnvironmentVariablesが食い違う場合は第一級の失敗モード。変更のたびにスモークメッセージを流す。
5. 再試行とバックオフのパラメータ
| シナリオ | 推奨 | 避ける |
|---|---|---|
| Retry-After付き429 | ヘッダを尊重。無い場合は2秒開始、上限は60秒付近まで | 200ms固定ループでハードBANを誘発 |
| 散発的5xx | 上限3回程度の再試行にジッター | 429処理と同一の無限ループを共有 |
| 接続タイムアウト | DNS/TLS/プロキシを先に直し、接続と読み取りを独立設定 | 握手失敗を隠すためだけに300秒へ一括延長 |
6. openclawログの層状読解
ログレビューを四層に分ける。(A) 起動と設定。期待したBase URLとキー接頭辞が載ったか。(B) HTTPエグレス。ステータスと上流トレースID。(C) ツール/MCP。遅いツールが壁時計を支配していないか。(D) チャネル書き戻し。ACK失敗や再試行枯渇。多くの「ランダム沈黙」は一度層を分けると一箇所に収束する。
| 信号 | 疑う先 | アクション |
|---|---|---|
| 特定モデル欄への429集中 | クォータ層または同時実行 | 同時実行削減、バックアップ切替、小型モデルへ |
| TLSハンドシェイクタイムアウト | エグレスまたはミドルボックス | 経路変更、時刻確認、不良プロキシ除去 |
| モデルHTTP 200だがチャネルが空 | フォーマットまたはACK経路 | チャネルデバッグとGateway送出ログを突き合わせ |
7. リモートMac Gatewayチェックリスト（launchd固有）
launchdはログインシェルより狭い環境を継承する。APIキーやOPENCLAW_*に触れるアップグレードは二段階: plist更新、ジョブリロード、非対話プローブで検証。リモートデスクトップはコロケと異なり、Wi-Fi省電力、VPN切断、ディスプレイスリープが常駐デーモンを止めうる。
| 確認 | 理由 |
|---|---|
| plist EnvironmentVariables | アップグレード後も対話シェルのexportと一致させる |
| UserName / WorkingDirectory | ユーザーまたはワークスペース違いで静かな権限失敗 |
| ログローテとディスク | 満杯ディスクは不可解なハングに見える |
| 関連アップグレード記事 | アップグレードと無応答Gatewayの記事とスモーク手順をセットで |
8. FAQ
Q: バックアップモデルの品質が落ちると利用者には何が見える？ 劣化モードであることをシステムプロンプトで明示し、クォータ回復後に戻し、切替イベントをログに残す。
Q: 国内回線で海外キーが常にタイムアウトする リンク品質の問題でOpenClawの論理以前。Gatewayを到達可能なリージョンへ置くかベンダー地域を変える。
Q: アップグレード直後に突然401 アップグレード記事に沿い、キー接頭辞とstate-dir移行を並行設定編集の前に完了させる。
9. 事例: 午後の停滞はRPMであって「チャネル」ではなかった
あるチームはリモートMacでGatewayを運用。利用者はメッセージチャネルを責めたが、ログは14–16時に429が密集しRetry-Afterが伸びていた。根本原因は自動化と人間トラフィックが同一RPM層を共有していたこと。対策: ハートビート系は小型モデルと別キー、主チャットは本鍵、90秒ブレーカでバックアップへ。停止時間は時間単位から分単位へ縮んだ。
第二の型はツール遅延をモデル遅延と誤認すること。遅いMCP一発がread timeoutを食い切り空白メッセージになる。ツールtimeoutとモデルtimeoutを分離すると体験が安定する。
GitHubウェブフックの記事と併読すると、HTTP意味論（401/403/429）は署名失敗と同じく証拠連鎖で捉える姿勢が身につく。
ルンブックは英雄頼みに勝つ。深夜3時でも同じ手順を踏めること。文書化された閾値は、専用Apple Siliconを借りるべきタイミングの判断も早くする。
同一MacでローカルLLMも動かすとメモリとWi-Fi競合でタイムアウト再現が難しくなる。専用リモートノードが変数を減らす。
フェイルオーバースクリプトはステージングで429とタイムアウトを合成し、一ループでバックアップ予算を枯らさないか検証する。
マルチエージェント並列はRPM天井を隠す。各呼び出しは200でも集計で429。「一部の部屋だけ無言」はグローバル同時実行予算とダッシュボードで潰す。
モデルスタックを叩く全自動ジョブを一覧化し、周期とキーを載せないと金曜午後は幽霊狩りになる。
運用チームが「とりあえず再起動」に頼る背景には、429とタイムアウトが混ざったログを一塊りで読んでしまい、どのレイヤが飽和しているかを切り分けられないことが多い。本稿の層状ログの考え方は、まずモデルHTTP、次にGatewayプロセス、さらにチャネル書き戻しという順で証拠を固定し、最後にlaunchd環境の齟齬を疑うという単純ながら強い手順である。
マルチプロバイダ構成では、プライマリとバックアップで課金単位やレート制限の粒度が異なる。同じモデル名でもベンダー側のエイリアス解決が違えば、実効RPMは想定を下回る。ルーティング表に実モデルID、キー所有者、バースト許容、日次上限を併記し、変更時はレビュー必須にすると、夜間インシデントでの迷走が減る。
リモートMac上のGatewayは、開発者の手元Macと違い、画面スリープや省電力Wi-Fiが挙動に直結する。常時稼働ノードとして契約する場合は、OSの電源設定とネットワーク安定性をSLOに含め、タイムアウト閾値を移動中のラップトップではなく据え置きサーバ基準で再設計する必要がある。
ツールやMCP呼び出しがモデル推論時間を食いつぶす典型例では、単一のread timeoutが両方を覆ってしまう。ツール側に短い個別上限を設け、モデル本体にはやや長めの上限を残す二段構えにすると、空白メッセージの再現性が上がり、ログ上でも責務が分離される。
観測の最低限セットに加え、バックアップルートへの切替イベントを構造化ログに残すと、ポストモーテムが速い。誰が承認し、どの閾値を超えたか、いつプライマリへ戻したかを一文で追えるようにしておくと、コンプライアンス観点でも説明しやすい。
ステージングで429とタイムアウトを意図的に注入し、リトライループがバックアップの日次枠を一晩で枯らさないかを検証する。本番初出しのフェイルオーバーポリシーは、紙の閾値だけではなく、負荷試験のトレースを添えてドキュメント化すると説得力が増す。
マルチエージェントや並列サブタスクでは、個々のHTTPが200でも集計RPMが429に達し、一部の部屋だけ返らない現象になる。グローバル同時実行数とキュー深度をダッシュボード化し、チャネル別ではなくモデルキー別に集計すると真相に近づく。
最後に、OpenClawのアップグレードやデバイス認証変更は、モデルAPIとは独立した401系の嵐を招きうる。本稿のHTTP系対策と併せ、upgrade記事のチェックリストを同じインシデントフォルダに置くと、夜間の判断が速くなる。
10. 観測の最低限
少なくとも追う: モデル別429率、端到端p95遅延、フェイルオーバー切替回数、チャネルACK失敗率、Gateway再起動回数。五つが同時に悪化ならクォータか地域上流障害。ACKだけが悪化ならチャネル層を疑う。
| 症状 | 最初に見る | 緩和 |
|---|---|---|
| 一チャネルだけ遅い | チャネルAPI上限とウェブフック遅延 | スロットル、キュー、接続モード変更 |
| 全チャネルが遅い | モデルエグレスまたはGateway CPU | フェイルオーバー、ノード拡張、レート制限 |
| アップグレード直後のスパイク | 環境と認証のドリフト | doctor、チェックリスト、ロールバック |
APMが無くても、定時ヘルス取得とgrep集計をインシデント窓に揃えれば足りる。攻撃面ハードニングと併せ、デバッグエンドポイントを公開しない。証拠経路が攻撃面になる。
11. 締め: フェイルオーバーは規律であって運ではない
(1) 限界: 単一キー、単一リージョン、バックオフ無しはいずれ429とテール遅延に当たる。スリープするラップトップの下でGatewayを動かすとタイムアウトが増幅する。
(2) リモートApple Siliconの理由: 電源が安定し、環境面が明快で、24/7 Gatewayとキュー再試行に向く。
(3) MACGPU: デスクトップと自動化・会議を切り離したい場合、MACGPUはログイン不要でプランへ辿れるリモートMac容量の試用導線を用意している。下のCTAから。
(4) 最終ゲート: ステージングで一つの失敗モードがバックアップ予算を一晩で枯らさないと証明するまで、フェイルオーバーポリシーを本番へ出さない。