Claude Code fallbackModelで過負荷に備える

Claude Code fallbackModelは何を解決する設定か

primaryモデルが過負荷、利用不可、あるいはリトライ不能なサーバーエラーを返したとき、Claude Codeはリクエストを失敗させる代わりに別のモデルへ切り替えられます。この仕組みがfallbackModelです。

未設定の場合は、同じモデルでリトライしたあとにサーバーのエラーがそのまま表に出ます。人が再試行するか、モデルを切り替えるまで止まります。

切り替わるのは、モデル側が応えられなかったケースだけです。次のエラーは対象外で、通常のリトライとエラー処理に従います。

• 認証エラー
• 課金エラー
• レート制限
• リクエストサイズ超過
• 通信エラー
• 組織のポリシーチェックによる拒否(Inference hooksによる拒否は、内容への判断なので別のモデルへ送り直しません)

429の見分け方はClaude rate limitエラーの対処で扱っています。fallbackModelはエラーが起きたあとの自動復帰で、同記事は起きているエラーの正体を切り分ける記事です。

Claude Code fallbackModelはどう設定するか

claude --help(v2.1.287)には、フラグが次のように載っています。

--fallback-model <model>   Enable automatic fallback to specified
                           model(s) when the default model is
                           overloaded or not available. Accepts a
                           comma-separated list to try each in
                           order. Re-tries the primary at the start
                           of each user turn.

最後の一文が、ターンごとにprimaryへ戻る挙動の根拠です。1セッションだけ試すなら、カンマ区切りで並べます。

claude --fallback-model sonnet,haiku

セッションをまたいで効かせるには、settings.jsonに配列でfallbackModelを書きます。スコープはAny fileで、ユーザー・プロジェクト・ローカル・管理のどの設定ファイルにも置けます。

{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

--fallback-modelフラグはfallbackModel設定より優先されます。各エントリはモデル名かエイリアスで、"default"はその時点のデフォルトモデルに展開されます。

Claude Codeは起動時にチェーンを確認も表示もしません。/statusにも出ません。切り替わったときの通知が、フォールバックが設定されている最初の可視サインです。チェーンを設定していない場合の過負荷リトライ停止を全モデルに広げる環境変数はFALLBACK_FOR_ALL_PRIMARY_MODELSにあります。チェーンへの切り替え自体には影響しません。

発動してからターンが終わるまでに何が起きるか

流れは次の4段階です。

切り替えには代償があります。モデルごとにプロンプトキャッシュが別なので、フォールバック先のモデルではそのターンのキャッシュが効かず、会話履歴の全体を読み直します。

コンパクション中は例外があります。チェーンはコンパクションにも適用されますが、primaryよりコンテキストウィンドウが小さいモデルには切り替わりません。要約する前に会話の一部が切れてしまうためです。候補が全てprimaryより小さいときは、元のエラーがそのまま表示されるので、再試行します。

サブエージェントにも同じチェーンが効きます。サブエージェントのリクエストがチェーンの対象になる失敗をすると、設定したモデルを順に試し、受理したモデルでそのまま作業を続けます。セッション側のモデルは変わりません。v2.1.247より前は、対象の失敗でサブエージェントが終了していました。

チェーンを設計するときの落とし穴

チェーンは重複除去後に最大3モデルまでで、超えたエントリは無視されます。4つ目以降に書いたモデルは、どの条件でも試されません。

もう1つの落とし穴は設定ファイル間の扱いです。permissions.allowのような配列は設定の5階層をまたいで結合されますが、fallbackModelは結合されません。順序に意味があるため、最高優先度のファイルが定義した値が丸ごと採用されます。

プロジェクト設定が["claude-sonnet-5"]、ユーザー設定が["claude-haiku-4-5"]なら、チェーンは["claude-sonnet-5"]だけです。組織で標準チェーンを配るなら、管理設定側にまとめて書きます。

managed-settings.d/のドロップインを使う場合は、managed-settings.jsonを先に、続いてディレクトリ内の*.jsonをアルファベット順に読みます。後から読まれたファイルのfallbackModelが、先のチェーンを丸ごと置き換えます。10-や20-のような数字の接頭辞で順序を制御できます。

Claude Codeを組み込んだアプリがCLAUDE_CODE_PROVIDER_MANAGED_BY_HOSTを設定している場合は、そのアプリのモデル設定が、あらゆる管理設定ソースのmodel・fallbackModel・modelPicker・modelOverridesより優先されます。管理設定にfallbackModelを書いても反映されません。availableModelsの許可リストは、アプリ側が独自のリストを持たない限り有効なままです。

availableModelsとの関係は競合ではなく、前段のフィルターです。許可リスト外のエントリが先に落ちてからフォールバックの処理に入るため、組織が許可モデルを縛っていれば、フォールバック先もその範囲に収まります。許可リストに通る管理設定の書き方は別記事にあります。

過負荷のフォールバックと、安全分類器のフォールバックはどう違うか

名前が似たもう1つの仕組みがあります。Fable 5.1・Fable 5・Opus 5.5・Sonnet 5.5・Opus 5は安全分類器つきで動き、サイバーセキュリティやバイオロジー関連の内容が検出されると、フラグが立った分類に応じたモデルへ再実行されます。

切り替え先は、拒否したモデルで決まります。

バイオロジーが拒否で終わるのは、Sonnet 5.5とOpus 5に切り替え先がないためです。Opus 5は独自の分類器を持っています。Fable 5.1・Fable 5・Opus 5.5でバイオロジーが続くと、最初のフラグでOpus 5へ移り、以降のフラグはそこで拒否になります。

フォールバック先はavailableModelsと照合され、ブロックされていれば切り替わらず、通常の拒否として表示されます。カテゴリごとの切り替えには、v2.1.219以降が必要です。それより前は、フラグが立ったFable 5のリクエストが全て、プロバイダーのデフォルトOpusで再実行されていました。

切り替え後の努力レベル

内容ベースのフォールバックでは、フラグが立ったリクエストの努力レベル(effort)が引き継がれます。たとえばOpus 5.5の既定はmediumです。Opus 4.8の既定はhighですが、Opus 5.5から切り替わった後はmediumのままです。

次の場合は別のレベルが適用されます。

• フォールバック先に当てはまるレベルを設定ファイルで指定している、または組織が既定を決めている
• 自分で努力レベルを選ぶ、/modelでモデルを選ぶ、後でセッションを再開する
• スキルのeffortフロントマターが、そのリクエストにレベルを指定していた(そのターンだけ適用され、以降はフォールバック先の既定の解決順に従う)

最初のリクエストから起きる理由

内容ベースのフォールバックは、何も変わったことを送っていない最初のリクエストでも起きえます。最初のリクエストにはCLAUDE.mdの内容やgit statusといった作業ディレクトリの文脈が含まれるためです。セキュリティやバイオロジー系の資料が入ったリポジトリでは、その文脈だけで分類器が反応します。

原因がカスタマイズにあるかは、claude --safe-modeで起動して切り分けます。CLAUDE.md・スキル・MCPサーバー・フックなどを無効にする起動オプションです。git statusとディレクトリ名はカスタマイズではないので、そのまま送られます。

ペネトレーションテスト、CTF、バイオロジー隣接のコードベースは、最初のリクエストから頻繁に切り替わります。アカウントへのフラグ立てではなく、その領域に対する想定内のルーティングです。「なぜモデルが変わるのか」を調べるときは、まず2系統のどちらの通知かを見分けるところから始まります。

自動で切り替えず、都度選ぶ設定

/configの「Switch models when a message is flagged」をオフにするか、switchModelsOnFlagをfalseにすると、フラグが立ったリクエストでセッションが一時停止します。選べるのは、フォールバック先へ切り替えるか、プロンプトを編集して同じモデルで再試行するかの2つです。

一時停止のプロンプトが出ない場合があります。

• 切り替え先がないとき(Opus 5・Sonnet 5.5のバイオロジー)は、拒否で終わる
• 非対話モードや、プロンプトを表示できないSDK連携では、フラグが立ったリクエストはターンが拒否で終わる
• 切り替え先がavailableModelsでブロックされているときも、拒否で終わる
• 両方のモデルが同じリクエストにフラグを立てたときは、プロンプトを編集して再試行するか、新しいセッションを始める
• モバイルアプリのクラウドセッションでは、編集して再試行する操作に対応していない

CIでは、switchModelsOnFlagをオフにすると、可用性ベースのfallbackModelが正常に働いていても、サイバー関連のフラグでターンが拒否のまま終わります。オンのままなら、切り替え先があるカテゴリは自動で切り替わります。

切り替わらないエラーの見分け方

「Output blocked by content filtering policy」は、APIの出力フィルターが応答を止めたエラーです。Claude Codeはこのエラーを受け取った時点でリクエストを終え、リトライも、ストリーミングなしの再送も、フォールバックモデルへの切り替えもしません。v2.1.285より前は、ブロックされたリクエストを再送して数分間リトライすることがありました。

組織のポリシーチェックによる拒否も、同じくフォールバック先へ再送されません。拒否の理由がモデルでなくリクエストの内容にあるためです。v2.1.239より前は、拒否されたリクエストが再送されることがありました。

切り替わらないことが、そのままエラーの種類を絞る手がかりになります。モデル側の障害なら切り替わり、内容やポリシーが理由なら切り替わりません。

Bedrock・Agent Platform・Foundryで効かせるには

可用性ベースのチェーンでは、BedrockやGoogle CloudのAgent Platformが、アカウントで呼び出せないモデルを拒否したときも切り替えが起きます。Claude Codeはそれを、認証エラーでなくモデルが使えない状態として扱います。

内容ベースのフォールバックは、プロバイダーごとにモデルIDが違うため、Claude Codeが関わる各モデルを識別できたときだけ動きます。識別の手がかりは次のとおりです。

• Fable 5.1・Fable 5は、モデルIDにclaude-fable-5を含む、ANTHROPIC_DEFAULT_FABLE_MODELの値と一致する、modelOverridesでマップされている、のいずれか
• Opus 5.5・Sonnet 5.5・Opus 5は、プロバイダーのモデルID、またはmodelOverridesのマッピング
• Opusが切り替え先になる場合は、拒否したモデルにかかわらず、デプロイ内でOpusを解決できる必要がある(ANTHROPIC_DEFAULT_OPUS_MODELを設定するか、プロバイダーの一覧にOpus 4.8のエントリを残す)

Opusを解決できないと、Sonnet 5.5を含む全てのモデルで内容ベースのフォールバックがオフのままになり、フラグが立ったリクエストは拒否で終わります。Sonnet 5.5では、Sonnet 5の切り替え先をANTHROPIC_DEFAULT_SONNET_MODELか、プロバイダーの一覧にあるSonnet 5のエントリで用意します。

利用形態別の効き方

運用では、用途ごとのチェーンを管理設定にまとめるか、CIのジョブにだけ--fallback-modelを付ける構成があります。後者はフラグがファイルの値より優先される性質を使うので、設定ファイルを触らずに済みます。

回答の質が落ちたように見えるとき

エラーが出ていないのに回答の質が落ちたように見えるときは、まずトランスクリプトの切り替え通知を探します。Claude Codeはモデルのバージョンを黙って変えません。変わる場合は、設定済みのチェーンが可用性エラーで働いたとき、BedrockやAgent Platformの起動時チェックで既定のモデルが使えなかったとき、安全分類器のフォールバックが働いたときのいずれかで、どれも通知が出ます。

まとめ

fallbackModelは過負荷や利用不可に備える1ターン限りの保険で、チェーンは最大3モデルまで、複数の設定ファイルでは1つだけが採用されます。モデルが変わったときは、通知の後に次のターンでprimaryへ戻るか、セッションが固定されたままかを見れば、2系統のどちらかを判別できます。