2026 年、macOS 上の OpenClaw ゲートウェイでプレミアムモデルを 1 つだけ設定している運用者は多い—そのまま Anthropic の HTTP 429、OpenAI の 503、地域障害で唯一の API キーが使えなくなると本番が止まる。モデルフェイルオーバーと明示的なプロバイダルーティングは、その硬い停止を境界のある劣化へ変える：文書化された副モデル連鎖、互換ツールスキーマ、Retry-After を尊重するリトライ予算。このチュートリアルでは ~/.openclaw/openclaw.json で連鎖を表現し、シークレットを git 外に置き、LaunchAgent 本番 plist を触る前に openclaw doctor で検証する手順を示す。429 リトライ規律、JSON と環境プロファイル、上流サーキットブレーカー、doctor 診断と併用し、ルーティング・スロットル・可観測性を揃えてください。
フェイルオーバー意思決定マトリクス、コピー可能な設定スケルトン、数値ガードレール（ホットパス最大 3 プロバイダ、試行あたり上限 30 秒、ターン全体 120 秒）、および MacHTML 公開料金で 1 日約 $16.9 の Apple Silicon Mac mini 上で回せるステージングチェックリストが手元に残ります。
フェイルオーバーが必要な症状
チャンネルが「考え中…」のまま、ログにはプロバイダエラーが連発。ゲートウェイが単一ベンダーへリトライを使い切り、ターン途中でツール呼び出しが止まる。検証済み副ルートではなく深夜 2 時に手動で API キーを差し替え、財務が想定外の請求を見る—いずれもルーティングがボトルネックという信号です。
フェイルオーバーは「常に最安モデル」ではありません。顧客向けはプレミアム、内部 HTML/CSS 監査はミドル、クラウド API 全停止時は破壊的操作のない Ollama 要約のみ—各層を文書化しプローブします。
フェイルオーバー連鎖の設計原則
ホットパスは短く：最大 3 プロバイダ。HTML/CSS エージェントと同じツールスキーマで週次プローブ。本番でファイル編集が必須なら write 不可モデルへはフォールオープンせず、読み取り専用要約へ劣化。ターンごとに correlation id とプロバイダラベルをログし、コスト尖りを財務が追跡できるようにします。
同一ハードウェアでも staging と production の連鎖は分離。ステージング JSON の typo が本番を実験的ローカルモデルへ落とさないようにします。
openclaw.json ルーティング骨格
ルーティングは git 管理 HTML の外に置く。実務的にはプロバイダ名を openclaw.json、API キーを ~/.openclaw/.env（chmod 600）に分離。プライマリモデル ID、順序付きフォールバック、プロバイダ別タイムアウト、任意のコスト上限を文書化します。
{
"agents": {
"default": {
"model": {
"primary": "anthropic/claude-sonnet-4-20250514",
"fallbacks": [
"openai/gpt-4.1",
"google/gemini-2.5-pro"
]
},
"providers": {
"anthropic": { "timeoutMs": 30000 },
"openai": { "timeoutMs": 30000 },
"google": { "timeoutMs": 45000 }
}
}
}
}スニペットは構造の参考です—OpenClaw バージョンでフィールド名は変わるため、貼り付け前にリリースノートと diff してください。編集後は openclaw doctor と、プロバイダごとの 1 行合成チャットを実行します。
プロバイダ選定マトリクス
| 層 | 用途 | リスク |
|---|---|---|
| プライマリ（プレミアム） | 顧客向け Slack/Telegram ターン | ローンチ時のクォータ枯渇 |
| セカンダリ（ミドル） | 内部監査・非緊急修正 | プライマリとのツールスキーマ乖離 |
| ローカル（Ollama） | クラウド API 停止時の読み取り専用要約 | クラウド推論深度に届かない |
| 無効 | 障害時の破壊的ツール禁止 | 「とりあえず有効化」圧力 |
429・503 と Retry-After の協調
フェイルオーバーはレート制限遵守の代わりにはなりません。プライマリが 429 のとき、文書化上限（チャットでよく 30 秒）まで Retry-After を守り、その後副プロバイダへ進めます。503 嵐ではゲートウェイサーキットブレーカーと組み合わせ、劣化エンドポイントを叩き続けないでください。macOS タイマーに合わせたバックオフ表は 429 専記事 を参照。
ターン全体は 120 秒 付近で上限を設け、Slack スレッドがハングに見えないようにします。5 プロバイダをループせず、人が読める劣化メッセージを返します。
モデル間のツールスキーマ互換
連鎖の全モデルはゲートウェイが公開する同一 JSON ツール定義を受け付ける必要があります。browser を拒否する副モデルは HTML/CSS パイプラインを途中で壊します。本番フォールバックに入れる前、ステージングで各プロバイダに「読み取り・パッチ書き込み・ディレクトリ一覧」の 3 固定ツール呼び出しを実行してください。
副がビジョン非対応でプライマリが画像を使う場合、フェイルオーバー前に画像パートを除去するか、ビジョン対応の副へだけ画像タスクをルーティングします。
doctor プローブと合成チャット
ルーティング変更後、openclaw doctor --json を変更チケットに添付。各フォールバックを強制する合成メッセージを送る：ステージングでプライマリキーを一時無効化し、副が 10 秒 以内に応答することを確認、キー復旧後再起動なしでプライマリ復帰を検証。ターンごとのプロバイダラベルをゲートウェイログで確認します。
プローブは staging/本番プロファイル と揃え、開発用ノートブックで本番シークレットを使ってフォールバックを試さないでください。
ステージング展開チェックリスト
- 現行
openclaw.jsonと.envのフィンガープリント（秘密値なし）を git 無視領域へエクスポート。 - 副プロバイダキーを別請求アラートで追加。
- ステージングゲートウェイポートでプロバイダごとにツール呼び出しスモーク。
- プライマリキー無効化で障害を模擬し、SLA 内フォールバックを確認。
- ステージング指標が 24 時間 クリーンなら LaunchAgent plist を昇格。
- ロールバック手順を文書化：JSON 1 ファイル復元 +
launchctl kickstart。
FAQ
フェイルオーバー先も同じツール定義？
はい—連鎖に入れる前に全プロバイダでツール呼び出しをテスト。
フェイルオーバーで 429 は自動解決？
副に独立クォータがある場合のみ。それ以外はバックオフが依然必要。
doctor の頻度は？
ルーティングまたはシークレット変更のたび、本番は週次 cron も推奨。
MacHTML の Apple Silicon Mac mini レンタルなら、経営層と同じ WebKit/Node ビルドでルーティング検証ができ—Linux コンテナによる macOS 近似ではありません。SSH で合成チャット、Keychain プロンプト時は VNC。アイドル電力はおおよそ 6–12 W、1 週間のフェイルオーバー演習は、全チャンネルが「provider error」と答える一夜停止より安いことが多いです。
公開料金は 1 日約 $16.9。演習後はインスタンス停止即可、ルーティング表は git に残り 36 か月 の CapEx は積み上がりません。
実機 macOS で OpenClaw モデルフェイルオーバーを演習
本番 LaunchAgent 昇格前に、クラウド Mac mini でプロバイダ連鎖・429 フォールバック・doctor プローブを検証してください。