Claude Code fallbackModelで過負荷に備える
primaryモデルが過負荷や利用不可になったときに自動で切り替えるfallbackModelの設定方法と、発動条件・チェーンの上限・content-based fallbackとの違いを扱います。
Claude Code fallbackModelは何を解決する設定か
primaryモデルが過負荷、利用不可、あるいはリトライ可能でないサーバーエラーを返したとき、Claude Codeはリクエストを失敗させる代わりに別のモデルへ自動で切り替えられます。この仕組みがfallbackModelです。認証エラー・課金エラー・レート制限・リクエストサイズ超過・通信エラーは対象外で、それぞれ通常のリトライとエラー処理に従います。切り替わるのは「本当にモデル側が応えられなかった」ケースに限られる、という線引きがまず重要です。
障害対応の実務では、Opusが混雑する時間帯にSonnetへ自動で逃がす、といった構成がよく使われます。CI/CDのように人が張り付いていない自動化ワークフローほど、この設定の有無で成功率が変わります。
Claude Code fallbackModelはどう設定するか
1セッションだけ試すなら--fallback-modelフラグにカンマ区切りで並べます。
claude --fallback-model sonnet,haikuセッションをまたいで恒常的に効かせるには、settings.jsonに配列でfallbackModelを設定します。
{
"fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}--fallback-modelフラグはfallbackModel設定より優先されます。各エントリはモデル名かエイリアスを受け付け、"default"と書くとその時点のデフォルトモデルに展開されます。Claude Codeは起動時にチェーンの中身を確認や表示せず、/statusにも出しません。実際に切り替わったときの通知が、フォールバックが設定されている最初の可視サインになります。
Claude Code fallbackModelはどんなときに発動するか
切り替えが起きるのは、primaryモデルが過負荷・利用不可・その他のリトライ不能なサーバーエラーを返したときだけです。切り替えはその1ターン限りで、次のメッセージでは再びprimaryモデルから試されます。セッション全体をフォールバック先に固定したいわけではない、という設計です。
リクエストが失敗すると、Claude Codeはチェーンのエントリを順番に試し、最初に受理されたモデルを使います。廃止されたモデルがsettings.jsonにピン留めされているような「到達できないエントリ」も、同じ仕組みで次のエントリへ流れます。実行前に、Claude Codeは2種類のエントリを取り除きます。
- 許可リスト外のエントリ:
availableModelsで許可されていないモデルは、チェーンを読み込んだ時点で除外されます - コンテキストウィンドウが小さいエントリ: コンパクション中のフォールバックでは、primaryより小さいコンテキストウィンドウのモデルには切り替わりません。要約する前に会話の一部が切れてしまうためです。フォールバック候補が全てprimaryより小さい場合、コンパクションは元のエラーをそのまま表示し、ユーザーは再試行することになります
Claude Code fallbackModelのチェーンで気をつける点
Claude Codeは重複除去後、チェーンを最大3モデルまでに制限し、それを超えるエントリは無視します。4つ目以降を書いても効かないため、優先順位の高い2〜3モデルに絞って設計するのが実務的です。
もう1点、fallbackModelは配列設定でありながら、設定の5階層をまたぐpermissions.allowのようなマージ対象外です。ユーザー設定・プロジェクト設定・管理設定にそれぞれfallbackModelが書かれていても、値は結合されず、最高優先度のファイルが定義した1つのチェーンだけが採用されます。組織で標準チェーンを配りたい場合は、管理設定側にまとめて書く必要があります。managed-settings.d/のドロップインディレクトリを使っている場合も同様で、アルファベット順で後から読まれるファイルのfallbackModelが、先に読まれたファイルのチェーンをまるごと置き換えます。
Claude Codeを組み込んだプラットフォーム(CLAUDE_CODE_PROVIDER_MANAGED_BY_HOSTを設定するホスト)上で動かしている場合は事情が変わります。ホスト側のモデル設定が、あらゆる管理設定ソースのmodel・fallbackModel・modelOverridesより優先されるため、fallbackModelを管理設定に書いても無視されます。IDE統合やSaaS組み込みでフォールバックが効かないときは、まずホスト側がこのフラグを立てていないか確認してください。
Claude Code fallbackModelとcontent-based fallbackはどう違うか
fallbackModelが扱うのは可用性の問題(混雑・エラー)ですが、Fable 5とOpus 5には別系統の自動フォールバックがあります。セキュリティやバイオロジー関連のコンテンツを安全分類器が検出したときに、対象モデルを切り替える仕組みです。
- Fable 5: バイオロジー関連の検出はOpus 5へ、サイバーセキュリティ関連の検出はOpus 4.8へ再実行されます
- Opus 5: サイバーセキュリティ関連の検出はOpus 4.8へ再実行されますが、バイオロジー関連の検出はOpus 5自身が独自の分類器を持つためフォールバック先が無く、拒否で終わります
このcontent-based fallbackが起きた後は、セッションはそのままフォールバック先のモデルで継続します。元のモデルに戻すには/modelで手動切り替えが必要です。フォールバック先のモデルもavailableModelsと照合され、ブロックされていればフォールバックせず通常の拒否エラーとして扱われます。切り替えを自動でなく都度確認したい場合は、/configで「Switch models when a message is flagged」をオフにするか、switchModelsOnFlag設定をfalseにします。オフラインの場合、フラグが立ったリクエストはその場で一時停止し、フォールバック先へ切り替えるか、プロンプトを編集して同じモデルで再試行するかを選べます。
ペネトレーションテストやCTF、バイオロジー隣接のコードベースを扱うチームでは、最初のリクエストからこのcontent-based fallbackが頻発します。これはアカウントへのフラグ立てではなく、その領域に対する想定内のルーティングです。fallbackModelの過負荷対応と混同すると、「なぜモデルが勝手に変わるのか」の原因調査で無駄な時間を使うことになります。
自動化ワークフローで運用するときにもう1つ意識したいのが、content-based fallbackの一時停止プロンプトが出せない実行環境の扱いです。非対話モード(-pフラグ)やプロンプトを表示できないSDK連携では、フラグが立ったリクエストは一時停止せず、その場で拒否としてターンを終えます。CI/CDのように人が確認できない環境でswitchModelsOnFlagをオフのままにしていると、可用性ベースのfallbackModelは正常に機能していても、content-based fallback側で予期しない失敗が増えることがあります。自動化パイプラインではswitchModelsOnFlagをオンのままにしておき、2系統のフォールバックがどちらも自動で完結する状態を保つのが安全です。
Claude Code fallbackModelはどう使い分けるべきか
| 利用形態 | 設定のおすすめ度 | 理由 |
|---|---|---|
| CI/CDの自動実行 | 設定のおすすめ度◎ | 理由人が張り付いていないため、過負荷での失敗をそのまま止めるより自動復帰の価値が大きい |
| 対話的な開発セッション | 設定のおすすめ度○ | 理由過負荷の頻度次第。混雑しやすい時間帯に開発するチームほど恩恵が大きい |
| セキュリティ研究・バイオロジー系のコードベース | 設定のおすすめ度△ | 理由content-based fallbackが別途頻発するため、fallbackModelだけ整えても体感は変わりにくい |
| 単発の軽い質問セッション | 設定のおすすめ度△ | 理由過負荷に遭遇する確率自体が低く、設定の手間に見合わないことが多い |
429エラーやoverloaded_errorそのものの見分け方、フォールバックが効かないケースの切り分けはClaude rate limitエラーの対処で扱っています。fallbackModelはエラーが起きた後の自動復帰、rate limit記事は起きているエラーの正体の見分け方、と役割が分かれています。
よくある質問
fallbackModelとavailableModelsを両方設定するとどちらが優先されますか
競合はしません。availableModelsはチェーンを読み込む段階のフィルターとして先に効き、許可リスト外のエントリはチェーンから除外されてから通常のフォールバック処理に入ります。組織で許可モデルを縛っている場合、フォールバック先も自動的にその範囲内に収まります。
フォールバックが起きたことはどこで確認できますか
セッション中に出る通知メッセージが唯一の可視サインです。/statusはチェーンの中身も切り替わったかどうかも表示しません。ログとして残したい場合は、通知が出た会話の該当箇所を確認する運用になります。
Bedrock・Google Cloud's Agent Platform・Foundryでもfallbackモデルは動きますか
可用性ベースのfallbackModelチェーンはプロバイダーを問わず設定できます。一方でcontent-based fallbackは、Bedrock・Google CloudのAgent Platform・Microsoft Foundryではモデルidがプロバイダー固有のため、Claude Codeが両方のモデルを識別できたときだけ自動で動きます。識別できない場合は自動切り替えせず、拒否メッセージで止まります。
フォールバックしたモデルはいつ元に戻りますか
可用性ベースのfallbackModelはそのターンだけの切り替えで、次のメッセージからは自動的にprimaryモデルへ戻ります。content-based fallbackは逆に、切り替わった後もセッションはそのモデルのまま継続し、戻すには/modelでの手動操作が必要です。この違いを取り違えると、想定外にモデルが固定されたままになります。
まとめ
fallbackModelは過負荷・利用不可・非リトライ系エラーに限定した1ターンだけの自動切り替えで、--fallback-modelフラグかsettings.jsonの配列で設定します。チェーンは重複除去後3モデルまで、availableModelsとの重ね掛けやコンテキストウィンドウの縮小回避といった除外ルールがある点、そしてFable 5/Opus 5のcontent-based fallbackとは別物である点を押さえておけば、自動化ワークフローの安定性を上げつつ、想定外のモデル切り替えに戸惑う場面を減らせます。