Claude Codeのフォールバックモデル設定(fallbackModel)について調査してみた
こんにちは、つくぼし(tsukuboshi0755)です！
Claude Codeを使っていると、モデルの過負荷で一時的にリクエストに失敗することがあります。
特にOpusなどの高性能モデルを常用していると、アクセス集中時にリクエストが通らず作業を中断せざるを得ないことがあります。
そこで本記事では、Claude CodeのfallbackModel設定を使ってモデル利用不可時に自動で別モデルに切り替える方法について紹介します！
fallbackModelとは
fallbackModelは、Claude Codeのプライマリモデルが過負荷・利用不可・非リトライ可能なサーバーエラーを返した際に、自動的に別のモデルに切り替える機能です。
フォールバックは現在のターンのみに適用されます。
次のターンでは再びプライマリモデルから試行されるため、一時的な問題が解消されていればプライマリモデルでの処理が継続されます。
フォールバックが発火する条件
以下の条件でフォールバックが発火します。
- プライマリモデルが過負荷の場合
- プライマリモデルが利用不可の場合
- 非リトライ可能なサーバーエラーが発生した場合
フォールバックが発火しない条件
以下のエラーではフォールバックは発火しません。
通常のリトライ処理やエラーハンドリングで対処されます。
- 認証エラー
- 課金エラー
- レートリミットエラー（HTTP 429）
- リクエストサイズエラー
- トランスポートエラー
設定方法
fallbackModelは2つの方法で設定できます。
settings.jsonでの設定（永続的）
settings.jsonにfallbackModelキーを追加し、フォールバック先のモデルを配列で指定します。
{
"fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}
この設定はセッションをまたいで有効になります。
settings.jsonの配置場所は以下の5箇所があり、上から順に優先度が高くなります。
| 優先度 | ファイル | スコープ |
|---|---|---|
| 1 | --fallback-modelフラグ |
セッション単位 |
| 2 | Managed settings | 組織管理 |
| 3 | .claude/settings.local.json |
プロジェクト（ローカル） |
| 4 | .claude/settings.json |
プロジェクト |
| 5 | ~/.claude/settings.json |
ユーザー |
注意点として、fallbackModelは設定ファイル間でマージされません。
最も優先度の高いファイルの設定がそのままチェーン全体として使用されます。
CLIフラグでの設定（セッション単位）
--fallback-modelフラグを使用すると、単一セッションのみに適用されるフォールバック設定を指定できます。
claude --fallback-model sonnet,haiku
カンマ区切りで複数のモデルを指定でき、指定した順にフォールバックが試行されます。
このフラグはsettings.jsonのfallbackModel設定より優先されます。
指定可能な値
フォールバック先のモデルとして、以下の形式が使用できます。
- モデル名（
claude-sonnet-5、claude-opus-4-8など） - モデルエイリアス（
opus、sonnet、haiku、fable、best、default） - 特殊キーワード
defaultはアカウントのデフォルトモデルに展開される
フォールバックチェーンの制約
フォールバックチェーンにはいくつかの制約があります。
最大3モデルまで
チェーンに指定できるモデルは最大3つです。
4つ以上指定した場合、余分なエントリは無視されます。
重複の自動除去
チェーン内の重複モデルは自動的に除去されます。
availableModelsとの連携
availableModels（利用可能モデルの制限設定）が設定されている場合、availableModelsに含まれないモデルはフォールバックチェーンから自動的に除外されます。
compaction時の制約
コンテキストのcompaction（圧縮）処理中は、プライマリモデルよりもコンテキストウィンドウが小さいモデルにはフォールバックしません。
compaction中にコンテキストウィンドウの小さいモデルへ切り替えると、会話履歴を保持できない可能性があるためです。
API の fallbacks パラメータとの違い
Claude CodeのfallbackModel設定と、Claude APIのfallbacksパラメータは名前こそ似ていますが、仕組みは異なります。
| 観点 | Claude Code fallbackModel |
Claude API fallbacks |
|---|---|---|
| レイヤー | CLIハーネスレベル | Messages APIレベル |
| トリガー | モデルの過負荷/利用不可 | 安全性分類器による拒否 |
| 主な用途 | 可用性の確保 | コンテンツ安全性のルーティング |
| 対象モデル | 任意のモデル | Fable 5のrefusal時のフォールバック |
| 設定方法 | settings.json / CLIフラグ | APIリクエストパラメータ + betaヘッダー |
APIのfallbacksパラメータは、Claude Fable 5が安全性分類器によってリクエストを拒否（stop_reason: "refusal"）した際に、別モデルで同じリクエストを自動リトライする機能です。
一方、Claude CodeのfallbackModelはモデル自体が利用できない場合のフォールバックであり、用途が異なります。
参考資料
最後に
今回は、Claude Codeのフォールバックモデル設定（fallbackModel）について紹介しました。
fallbackModelを設定しておくことで、プライマリモデルが一時的に利用できない場合でも作業を中断せずに済みます。
特にOpusなどの高性能モデルを常用している場合は、SonnetやHaikuをフォールバック先として設定しておくと、可用性を高められるためおすすめです。
なお、フォールバックは現在のターンのみに適用されるため、プライマリモデルが復旧すれば自動的に元のモデルに戻ります。
「フォールバックモデルに固定されてしまうのでは」という心配は不要です。
以上、つくぼし(tsukuboshi0755)でした！
