Claude Code の fallbackModel: 3段フェイルオーバー設定 (2026)

4 ステップで 3 段フェイルオーバーを設定する

Anthropic が 529 overloaded_error を返すと、未設定の Claude Code セッションは同じモデルを再試行し、そのままエラーを返します。フォールバックチェーンは、その行き止まりをダウンシフトに変えます。Opus が過負荷なら Sonnet で再試行し、それも利用不可なら Haiku です。

設定全体はひとつの配列です。

{
  "model": "opus",
  "fallbackModel": ["sonnet", "haiku"]
}

これが 3 段チェーンです。opus がプライマリで、sonnet と haiku がフォールバックです。以降のガイドでは、この配列だけでは自明でない部分を扱います。実際にどのエラーで発動するのか、なぜ 429 では発動しないのか、チームをまたいでチェーンがどう振る舞うのか、そして単一アカウントのチェーンが役に立たなくなる境界はどこか、です。

この設定でできること (そしてできないこと)

フォールバックチェーンは用途の狭いツールです。作り込む前にその境界を正確に押さえておく価値があります。これが直す障害は、これが直さない 2 つの障害とよく似て見えるからです。

フォールバックチェーンがしてくれること。

• 一時的な Anthropic の過負荷 (529 overloaded_error) を、ターンを失わずに乗り切る。
• 特定のモデルが利用不可のときも動き続ける。例えば settings でピン留めしていたモデルがすでに廃止された場合など。
• 意図的に能力をダウンシフトする。Opus で始めた難しいタスクを、まったく完了しないのではなく Sonnet で完了させる。

フォールバックチェーンがしないこと。

• 429 レート制限や利用上限を回避する。これらはクォータの問題であり、チェーン内のどのモデルも同じアカウントのクォータから引きます。
• 別のプロバイダーへフェイルオーバーする。チェーン要素は 1 アカウント上の Claude モデルに解決されるため、Anthropic 全体の障害はチェーンごと落とします。
• プライマリモデルを恒久的に変更する。切り替えはターン単位で、次のメッセージは再びプライマリから始まります。

繰り返し悩まされているのが「過負荷」ではなく「利用上限に到達」なら、フォールバックチェーンは間違った処方です。別記事の Claude Code で rate limit reached を、過負荷そのものの API レベル版については Claude API error 529 を参照してください。

判断の枠組み: いつこの設定を使うか (使わないべきか)

使うべきとき

• 無人またはスクリプト化された文脈 (CI、長時間のエージェント実行、夜間ジョブ) で Claude Code を動かしていて、ターン途中の 529 がなければジョブ全体を中断させてしまう場合。
• 有料 API や上位ティアを使っていて、通常の中断がクォータではなく過負荷である場合。
• そのターンが完了することと引き換えに、ターンの残りで品質のダウンシフトを許容できる場合。

使わないべきとき

• 中断が 429 や「usage limit reached」の場合。ここではチェーンは何もしません。代わりにクォータかキャッシュを直してください (トークン最適化 がテコです)。
• 再現性のために毎ターンを特定モデルで走らせる必要がある場合。実行途中で Haiku へ静かにダウンシフトすると、後続ステップが依存する出力品質を変えてしまうことがあります。
• プロバイダーレベルの回復力が必要な場合。1 アカウントは自分自身へフェイルオーバーできません。それにはゲートウェイが必要です (後述)。

打ち切りルール

過負荷時に自動バックアップを 1 つ入れたいだけなら、要素を 1 つ追加してそこで止めます。"fallbackModel": ["sonnet"] です。3 段チェーンが意味を持つのは、Opus と同時に Sonnet も高負荷になると見込むときだけで、それが起きるのはほぼ広域のプラットフォーム障害の最中です。

システム要件

3 つのエイリアスと、今日の Anthropic API での解決先。

この表の 2 点が、まともなチェーン設計を左右します。Sonnet 5 は 2026 年 8 月 31 日まで導入価格 $2 / $10 per MTok で提供されるため、中段ティアは今のところ定価より安いです。そして Haiku 4.5 のコンテキストウィンドウは 200K で、Opus と Sonnet が持つ 1M ではありません。したがって 200K を超える長いセッションは Haiku ティアに収まりません。これを踏まえてチェーンの順序を決めてください。Haiku は品質だけでなく容量の理由からも最後の手段です。

ステップバイステップの設定

ステップ 1: プライマリモデルとバージョンを確認する

claude --version
claude   # then run /status inside the session

/status はアクティブなモデルを表示します。opus が Opus 4.8 に、sonnet が Sonnet 5 に解決されていない場合は、まず claude update を実行してください。期待される結果: バージョンが 2.1.197 以上で、認識可能なプライマリモデルが表示される。

ステップ 2: フラグでチェーンを 1 セッションだけ試す

何かを恒久化する前に、CLI フラグでチェーンを試します。フラグはカンマ区切りのリストを受け付け、保存済みの設定を上書きするため、実験に最も安全な方法です。

claude --model opus --fallback-model sonnet,haiku

期待される結果: セッションは Opus で始まります。実際に過負荷が起きない限りフォールバックは見えず、起きた時点で Claude Code が切り替え先のモデル名を示す通知を出力します。

ステップ 3: チェーンを settings.json に恒久化する

フラグが期待どおり動いたら、設定へ移して全セッションが継承するようにします。エイリアスでも完全なモデル ID でも構いません。完全な ID はバージョンをピン留めし、エイリアスの変更に耐えます。

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

期待される結果: 新しいセッションは、フラグ不要で 2 モデルのフォールバックチェーン付きの Opus で始まります。--fallback-model フラグは、それを付けて起動したセッションでは依然として優先されます。

ステップ 4: ハッピーパスではなく発動条件を検証する

本物の 529 をオンデマンドで作り出すことはできないので、障害を待つ代わりに、推論できる部分を検証します。各要素が到達可能なモデルに解決されることを確認し、何が発動させないのかを理解していることを確認してください。チェーンが読み込まれたかどうかをエラー任せにしないこと。Claude Code は起動時に fallbackModel を検証しません (v2.1.208 で確認済み) ので、不正な値は例外を投げずに静かに無視されます。この最後の点、つまり何が発動させないのかが、ほとんどの設定ミスが隠れる場所なので、独立した節を設けます。

何がフォールバックを発動させるか (そして何が発動させないか)

これは頭に叩き込むべき表です。フォールバックは可用性の失敗で発動し、それ以外のすべてでは沈黙します。

つまずくのは 429 の行です。レート制限はクォータを使い切ったことを意味し、チェーン内のどのモデルも同じアカウントに課金されるため、Opus から Haiku へ切り替えても余裕は生まれません。Claude Code はこれを知っていて、429 にフォールバックを消費するのを拒みます。障害中に一度もフォールバックが発動しないとログに出るなら、その障害が実は 429 でないか確認してください。

同じロジックをフローにするとこうなります。

flowchart TD
    A[Model request] --> B{Response}
    B -->|529 / unavailable / non-retryable 5xx| C{More models in chain?}
    B -->|429 / auth / billing / size| D[Normal retry, then surface error]
    B -->|success| E[Return result for this turn]
    C -->|yes| F[Switch to next model, show notice]
    C -->|no| D
    F --> A
    E --> G[Next message tries primary first again]

チェーンの順序を選ぶ

配列の順序は Claude Code が試す順序なので、配列は集合ではなく優先順位リストです。何を最適化するかに応じて、2 つのデフォルトがほとんどのケースをカバーします。

能力優先 (opus プライマリの下での ["sonnet", "haiku"]) は可用性が許す限り品質を高く保ち、より大きい 2 モデルが同時に過負荷になったときだけ Haiku に落ちます。ダウンシフトが真の最後の手段であるインタラクティブな作業に使います。

コスト優先 (sonnet プライマリ、["haiku"] フォールバック) は Opus にはまったく手を伸ばしません。スループットと予測可能な支出が天井より重要な CI やエージェントループで使います。ここには ハイブリッドルーティング の論拠が当てはまります。ほとんどのターンは Opus を必要としないので、背の高いチェーンを持つためだけに Opus をプライマリにするのは、よくあるケースで無駄に金を使うことになります。

両方の好みを上回る制約がひとつあり、見落としやすいです。コンテキストウィンドウです。Haiku 4.5 は 200K ウィンドウで、Opus 4.8 と Sonnet 5 が提供する 1M に対して小さいです。すでに 200K を超えて育ったセッションは Haiku ティアにまったく着地できないので、長コンテキストの作業では、どこに置いても Haiku は実質的にチェーンから欠落します。セッションが日常的に大きくなるなら、チェーンを 1M ウィンドウのティアに保ち、Opus と Sonnet が同時に障害を起こしたときはコンテキストを静かに切り詰めるのではなくターンを失敗させる、と割り切ってください。

切り替えはどう見えるか

フォールバックは決して静かではありません。発動すると、Claude Code は切り替え先のモデル名をトランスクリプトに通知として出力します。切り替えはターンにスコープされているため、Haiku に静かに落ち着くセッションではなく、次の過負荷でその通知が再び見えます。対照的に、設定ミスは静かです。不正な fallbackModel 値は警告なしに無視される (v2.1.208 で確認済み) ため、壊れたチェーンは、過負荷が隙間を見つけるまで動作中のチェーンとまったく同じに見えます。チェーンが実際に生きているか確認するには、起動時エラーを探すのではなく、次に述べるように JSON 実行の modelUsage フィールドから監査してください。

JSON を出力する非対話実行 (-p / --print) では、プレーンテキストの通知が抑制されます。したがって、プライマリがターンを処理したと決めつけるのではなく、結果メッセージの modelUsage フィールドから実際に応答したモデルを読んでください。それが、チェーンがどれだけの頻度で何かを捕まえ、どのティアが負荷を吸収したかを事後に監査する信頼できる方法です。実際の障害ウィンドウ全体でチェーンが一度も捕捉を示さないなら、その障害が 429 でなかったか再確認してください。どのチェーンも 429 はカバーしません。

設定中によくあるエラー (と修正)

マージしない挙動は強調に値します。ほとんどの配列設定の動きと逆だからです。ユーザー設定で慎重に 3 段チェーンをチューニングしても、リポジトリが独自の単一モデル fallbackModel を持つ .claude/settings.json を同梱していれば、リポジトリが完全に勝ち、あなたのチェーンは警告なしに落とされます。優先順位はマネージド設定、次にコマンドラインフラグ、次にプロジェクトローカル、次にプロジェクト、次にユーザーの順です。実際に使いたいチェーンは、任意のセッションが読み込む中で最優先のファイルに置いてください。

チーム / 複数開発者の構成

開発者 1 人なら、~/.claude/settings.json の fallbackModel で十分です。チームをまたぐと、興味深い問いは誰がチェーンを所有し、個人が上書きできるかどうかです。

チーム固有の相互作用が 2 つ重要です。第一に、開発者が実行できるモデルを制限するために availableModels も使う場合、その許可リストの外にあるフォールバック要素はチェーン読み込み時に落とされるので、強制されたチェーンと許可リストは一致していなければなりません。第二に、フォールバックチェーンはマージしないため、コミットされたプロジェクトチェーンは、そのリポジトリ内で各開発者の個人チェーンを完全に置き換えます。これは CI や共有エージェントでは通常望ましい挙動ですが、個人チェーンをチューニングした開発者はそのリポジトリで作業する間、それを静かに失うことを意味します。プロジェクトチェーンを文書化し、設計どおり上書きされた「消えた」フォールバックを誰もデバッグしないようにしてください。

CI でエージェントを走らせるチームにとって妥当な、コミット済みプロジェクトチェーンの例。

{
  "model": "sonnet",
  "fallbackModel": ["haiku"],
  "availableModels": ["sonnet", "haiku"]
}

これは CI をより安い Sonnet ティアに保ち、過負荷時に Haiku へフォールバックし、誰かが CI ジョブを静かに Opus へ切り替えるのを禁じます。

応用: ゲートウェイ経由のプロバイダー横断フェイルオーバー

フォールバックチェーンには硬い天井があります。その中のすべてのモデルは同じ Anthropic アカウント上に存在します。Anthropic 自体が広域障害を起こすと、3 つのティアが同時に過負荷になり、試すべきものがチェーンに残りません。3 時間を超えた 2026 年 3 月 18 日の障害は、同一アカウントのチェーンではカバーできない失敗の形です。

プロバイダーレベルの回復力には、Claude Code の上のレイヤーが必要です。ANTHROPIC_BASE_URL で Claude Code をゲートウェイに向ければ、(あなたの 1 アカウントではなく) ゲートウェイがリクエストの着地先を決めます。ANTHROPIC_BASE_URL はリクエストの行き先を変えるだけで、どのモデルが答えるかは変えないので、その下では fallbackModel チェーンがモデルレベルのフェイルオーバーとして依然機能し、ゲートウェイがその上にプロバイダーレベルのフェイルオーバーを加えます。

ofox のような集約ゲートウェイは、多数のプロバイダーを前面に置く OpenAI 互換かつ Anthropic 互換のエンドポイントをひとつ公開します。そのため、Anthropic 全体が利用不可のとき、チェーンは Claude モデルから非 Claude モデルへ渡れます。これはネイティブの fallbackModel チェーンには物理的にできないことです。トレードオフは、2 つ目のホップを信頼することになり、ルーティングを settings.json ではなくゲートウェイ側で構成する点です。その設定の Claude Code 側については Claude Code + ofox 設定ガイド を、同じルーティングのコスト主導版については ハイブリッドモデルルーティング を参照してください。

代替案の前にひとつ区別を。Claude Code には文字どおり「自動モデルフォールバック」と呼ばれる機能もあり、それはこれではありません。その仕組みは Fable 5 に固有です。セーフティ分類器がリクエスト (多くはサイバーセキュリティや生物学の作業) にフラグを立てると、Claude Code はそれを Opus で再実行し通知を出します。過負荷や fallbackModel チェーンとは無関係です。設定していない Fable 5 セッションでフォールバックを見たら、それは分類器です。claude --safe-mode を実行するとローカルのカスタマイズ (CLAUDE.md、スキル、フック、MCP) が無効になるので、それらが引き金かどうかを切り分けられますが、セーフモードでも git ステータスやディレクトリ名などは送られるため、リポジトリの内容自体がその状態でも分類器を発動させ得ます。

フェイルオーバーを扱う代替案

fallbackModel は組み込みで依存ゼロの選択肢であり、モデルレベルの過負荷回復力にはまずこれを選ぶべきです。それ以上が必要なとき、以下がその上のレイヤーです。

• ofox は複数プロバイダーを前面に置く単一の Anthropic 互換エンドポイントを公開するので、Anthropic 全体の障害時にフェイルオーバーが Claude から別モデルのファミリーへ渡れます。1 ベンダーに留まることよりプロバイダーレベルの回復力が重要なときに最適です。
• LiteLLM はプロバイダー横断の独自の再試行とフォールバックリストを持つオープンソースのプロキシです。ルーティングレイヤーを自前でホストしたく、すでにインフラを運用しているときに最適です。
• OpenRouter は特定モデルの自動プロバイダーフォールバックを備えたアグリゲーターです。最小限の設定で幅広いモデルカタログを求めるときに最適です。
• Portkey は構成可能なフォールバックと負荷分散ポリシーを備えたゲートウェイです。静的なリストではなくルーティングルールを、加えて可観測性を求めるときに最適です。

4 つとも Claude Code の上に位置し、fallbackModel チェーンを置き換えるのではなく補完します。安価な CLI 内モデルフェイルオーバーにはチェーンを残し、プロバイダーレベルのケースにはゲートウェイを加えてください。

FAQ

Claude Code の fallbackModel とは何ですか?

settings.json のキー、そして --fallback-model という CLI フラグで、プライマリが過負荷または利用不可のときに Claude Code が順に試すバックアップモデルを列挙します。指定できるのは最大 3 つです。切り替えは現在のターン中だけ有効で、次のメッセージではまず再びプライマリから試します。

529 エラーが発生したとき Claude Code は自動でフォールバックしますか?

fallbackModel を設定している場合に限ります。529 は overloaded_error で、切り替えを発動させる条件のひとつです。何も設定していなければ、Claude Code は同じモデルをバックオフ付きで再試行し、その後エラーを返します。

fallbackModel はレート制限 (429) エラーに役立ちますか?

いいえ。認証、課金、レート制限 (429)、リクエストサイズ、トランスポートのエラーでは切り替えは一切起きません。429 は自分のクォータを使い切ったことを意味し、チェーン内のどのモデルも同じアカウントに課金されるため、ティアを切り替えても余裕は増えません。

Claude Code はフォールバックモデルをいくつ使えますか?

3 つです。チェーンは重複除去後、最大 3 に制限され、追加要素は無視されます。よくあるチェーンは opus、次に sonnet、次に haiku です。

Claude Code でフォールバックモデルを設定するには?

1 セッションだけなら claude --fallback-model sonnet,haiku で起動します。恒久化するには settings.json に fallbackModel 配列を追加します。例えば ["claude-sonnet-5", "claude-haiku-4-5"] です。フラグは設定に勝ちます。

フォールバックモデルはセッション全体で有効なままですか?

いいえ。切り替えは現在のターンにのみ適用されるので、一時的な過負荷でセッションが下位ティアに固定されることはありません。

fallbackModel と自動モデルフォールバックの違いは何ですか?

fallbackModel (フォールバックモデルチェーン) は可用性を対象とし、過負荷や利用不可で発動します。自動モデルフォールバックは Fable 5 固有の別の仕組みで、セーフティ分類器がフラグの立ったリクエストを Opus に再ルーティングします。両者は fallback という単語を共有しているだけです。

Claude Code は Anthropic 以外のモデルへフォールバックできますか?

fallbackModel 経由ではできません。各要素は同一アカウント上の Claude モデルに解決されるため、Anthropic 全体の障害はチェーン全体を一緒に落とします。プロバイダー横断のフェイルオーバーには、複数プロバイダーを前面に置くゲートウェイが必要です。

この更新のために確認した情報源

• Claude Code モデル設定ドキュメント、Fallback model chains の節 (2026-07-15 確認): https://code.claude.com/docs/en/model-config
• Claude Code 設定リファレンス、fallbackModel キー (2026-07-15 確認): https://code.claude.com/docs/en/settings
• Anthropic API エラーリファレンス、529 overloaded_error (2026-07-15 確認): https://platform.claude.com/docs/en/api/errors
• Anthropic モデル概要、Opus 4.8 / Sonnet 5 / Haiku 4.5 の価格とコンテキストウィンドウ (2026-07-15 確認): https://platform.claude.com/docs/en/about-claude/models/overview
• Claude Code v2.1.208 での実地検証 (2026-07-15): 不正およびタイプミスした fallbackModel 値は起動時エラーなしで受け入れられ静かにスキップされる。応答したモデルは --print JSON 出力の modelUsage フィールドから確認した。