FALLBACK_FOR_ALL_PRIMARY_MODELSとは — 0やfalseでも有効になる罠
FALLBACK_FOR_ALL_PRIMARY_MODELSは0やfalseを含むどんな値でも同じ効果になる環境変数です。対象範囲とfallbackModelとの関係、元に戻す手順をまとめます。
FALLBACK_FOR_ALL_PRIMARY_MODELSは、フォールバックモデルを設定していないときに、過負荷エラーへのリトライを打ち切る対象を全モデルに広げる環境変数です。1を入れても0を入れても結果は同じで、変数を設定したという事実だけで有効になります。既定でどこまで打ち切りが及ぶか、fallbackModelのチェーンとどう役割が分かれるか、元に戻すときにハマりやすい点を扱います。
そもそも「過負荷エラーへのリトライ打ち切り」とは何か
Claude Codeがモデルへ送るリクエストは、モデル側の混雑によってoverloaded_errorのようなエラーで拒否されることがあります。通常はこのエラーに対して自動でリトライしますが、同じモデルで過負荷が繰り返されたとき、Claude Codeはリトライを続けるか早めに諦めるかを内部の条件で切り替えています。FALLBACK_FOR_ALL_PRIMARY_MODELSが操作するのは、この「早めに諦める」判定が及ぶモデルの範囲です。過負荷エラー自体の見分け方やレート制限との違いはClaude rate limitエラーの対処で扱っています。
設定すると何が変わるか — 打ち切りの範囲が全モデルに広がる
Claude Codeは、過負荷エラーが繰り返し起きたモデルへのリトライを、ある条件下で早めに打ち切ります。この変数を設定していない既定の状態では、打ち切りの対象はOpus・Fable・Mythos系のモデルに限られます。しかも対象になるのは、Claude Codeへの認証がAPIキーかサードパーティープロバイダー経由のときだけです。Claudeのサブスクリプション認証で使っている場合、公式ドキュメントの記述はこの限定に触れていません。
FALLBACK_FOR_ALL_PRIMARY_MODELSを設定すると、この打ち切りの対象がOpus系だけでなく全モデルに広がります。公式ドキュメントは設定時の記述で認証形態を限定していないため、既定の場合と違い、認証方法を問わず適用されると読むのが素直です。ただし前提条件は変わりません。この打ち切りが働くのは、あなたがfallbackModelのチェーンを設定していないときだけです。
なぜ既定の対象がOpus・Fable・Mythos系に限られるのか、公式ドキュメントはその理由まで説明していません。上位モデルほど混雑しやすく、リトライを続けさせるコストが大きいという事情はありえますが、これは推測の域を出ません。断定できるのは、この変数を設定することでSonnetやHaikuを含む全モデルへ同じ打ち切りルールを揃えられる、という挙動そのものです。
| 状態 | 打ち切りの対象モデル | 認証条件 |
|---|---|---|
| 既定(未設定) | 打ち切りの対象モデルOpus・Fable・Mythos系のみ | 認証条件APIキーまたはサードパーティープロバイダー経由 |
FALLBACK_FOR_ALL_PRIMARY_MODELS設定時 | 打ち切りの対象モデル全モデル | 認証条件条件の記述なし |
Claudeのサブスクリプション認証だけで使っている場合は少し注意が必要です。公式ドキュメントが認証形態を明記しているのは既定(未設定)の挙動についてだけで、サブスクリプション認証時に打ち切りがどう働くかは記述されていません。挙動を確かめたいなら、推測で判断せず、フォールバック未設定のままこの変数を設定し、過負荷が続くセッションで実際の反応を確認するのが確実です。
名前とは裏腹に「値」でなく「設定の有無」だけを見る
Claude Codeのオン・オフ系変数の多くは、大文字小文字を問わず1かtrueで有効、0かfalseで無効という標準的な真偽値として読まれます。FALLBACK_FOR_ALL_PRIMARY_MODELSはこの標準から外れます。空でない値を入れた時点で有効になり、0やfalseを入れても止まりません。
変数名のFOR_ALL_PRIMARY_MODELSという響きから、「オンにするかどうかを選べる設定」を想像しがちです。しかし実装が見ているのは中身の値ではなく、変数がそこに存在するかどうかだけです。
同じ罠を持つ変数が他に5つある
公式ドキュメントは、値でなく設定の有無だけを見る変数として6つを名指ししています。FALLBACK_FOR_ALL_PRIMARY_MODELSのほかの5つは次のとおりです。
DISABLE_TELEMETRY— テレメトリの停止CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC— 非必須通信を丸ごと停止DISABLE_ERROR_REPORTING— クラッシュ報告の停止CLAUDE_CODE_TMUX_TRUECOLOR— tmux上での24bitカラー表示の許可IS_DEMO— デモモードの有効化
いずれも空でない値を入れた時点で有効になり、0やfalseでも止まりません。
一方で、名前が似ていても標準的な真偽値として読まれる変数もあります。DO_NOT_TRACKは1で有効、0のままなら無効という通常の解釈です。数値として解釈されるFORCE_HYPERLINKはさらに別系統で、文字列でなく数値として値を読むため0が明示的に無効化として働きます。同じ「オン・オフ」の見た目でも変数ごとに解釈のルールが違うため、値を変える前に対象の変数がどちらの系統かを確認したほうが確実です。
この6つに共通するのは、変数名だけを見ても「値でなく有無で判定される」ことが読み取れない点です。DISABLE_TELEMETRYやDISABLE_ERROR_REPORTINGのように動詞が名前に含まれる変数は、まだ「設定した時点で何かを止める」という直感が働きます。ですがFALLBACK_FOR_ALL_PRIMARY_MODELSのように名詞の羅列に近い名前だと、値による調整を期待してしまいやすく、6つの中でもとくに誤操作を招きやすい形をしています。
fallbackModel設定済みならこの変数は関与しない
FALLBACK_FOR_ALL_PRIMARY_MODELSという名前は、複数のモデルへ自動でフォールバックする機能そのものを連想させます。しかし実際にモデルを切り替える仕組みはfallbackModelというまったく別の設定が担っています。
Claude Code v2.1.160以降、fallbackModelのチェーンを設定していれば挙動が変わります。過負荷エラーが繰り返し起きたとき、どのプライマリモデルからでも設定済みのフォールバック先へ自動で切り替わるようになりました。この切り替えが働く場合、FALLBACK_FOR_ALL_PRIMARY_MODELSは関与しません。公式ドキュメントも「この変数はフォールバックモデルへの切り替えに影響しない」と明記しています。
つまりこの変数が意味を持つのは、fallbackModelを設定していない場面に限られます。フォールバック先が無い状態で過負荷が続いたとき、Claude Codeにリトライを続けさせるか、早めに打ち切ってエラーを返させるかを切り替えるのがこの変数の役割です。モデルを切り替える機能だと誤解したまま設定しても、期待した自動復帰は起きません。
紛らわしい仕組みがもう1つあります。Fable系のモデルとOpus 5には、安全性の分類器がリクエストを検出したときに別モデルへ切り替える、公式ドキュメントが「automatic model fallback」と呼ぶ機構があります。これはセキュリティやバイオロジー関連のリクエストを対象にした別系統の仕組みで、過負荷エラーとは発動条件も対象モデルも異なります。FALLBACK_FOR_ALL_PRIMARY_MODELSはこちらにも関与しません。
設定方法と、元に戻すときの注意
シェルの環境変数として渡すか、設定ファイルのenvキーに書きます。
export FALLBACK_FOR_ALL_PRIMARY_MODELS=1
claude個人の全プロジェクトに反映させたいなら~/.claude/settings.json、プロジェクト単位で固定したいなら.claude/settings.jsonのenvキーに書きます。
{
"env": {
"FALLBACK_FOR_ALL_PRIMARY_MODELS": "1"
}
}元に戻すときは、値を書き換えるのではなく変数そのものを削除します。シェルならunset FALLBACK_FOR_ALL_PRIMARY_MODELS、設定ファイルなら該当行ごと消します。設定ファイルのenvキーは値を追加はできても、キーを消すだけではシェル側で設定した値までは打ち消せません。空文字列を入れて打ち消す方法は、公式ドキュメントではプロバイダー選択系の変数について明記されているものの、この変数については同じ扱いになるという記述がありません。シェルで設定している場合は、設定ファイル側の対処に頼らずunsetで確実に消すのが安全です。
シェルの環境変数はClaude Code起動時に読み込まれるため、unsetしても反映されるのは次回の起動からです。一方、設定ファイルのenvキーはファイルを保存した時点で実行中のセッションにも再読み込みされます。動かしたまま様子を見たい場合は設定ファイル側を、確実に反映させたい場合はいったんセッションを終了する方法を選ぶことになります。
設定ファイルと組織の管理設定(managed settings)の両方に同じ変数が書かれている場合、シェルより設定ファイルの値が優先され、設定ファイルの中でも優先度の高いファイルの値が採用されます。管理設定側で配布されている変数は、手元の設定ファイルを消しても上書きされません。管理者に確認するのが確実です。
組織全体で自動化パイプラインの挙動を揃えたい場合は、個々の開発者のシェル設定に頼らず、管理設定のenvブロックに書いて配布します。
{
"env": {
"FALLBACK_FOR_ALL_PRIMARY_MODELS": "1"
}
}この方法なら、CI/CDで動かすジョブごとに環境変数を用意し直す必要がなく、組織内のどの自動化ワークフローでも同じ打ち切りルールで動作します。
使う場面の目安
| 状況 | 設定する意味 |
|---|---|
fallbackModelのチェーンを設定済み | 設定する意味ほぼ無い。過負荷時の切り替えはすでにfallbackModelが担う |
| フォールバック未設定 + 自動化パイプラインで早期に失敗を検知したい | 設定する意味効果あり。全モデルで打ち切りが早まり、ハングより先にエラーとして検知できる |
| フォールバック未設定 + 対話的な開発セッションでの通常利用 | 設定する意味基本不要。Opus系の打ち切りだけで足りることが多い |
| Opus系以外のモデルでも早期打ち切りを揃えたい | 設定する意味効果あり。既定ではOpus・Fable・Mythos系に限られる範囲を全モデルへ広げられる |
この変数だけを単独で調べて設定するより、既定の対象範囲とfallbackModelとの関係を合わせて把握してから設定するほうが、意図しない挙動変化に気づきやすくなります。環境変数全体の一覧はClaude Code環境変数リファレンスにまとめています。
まとめ
FALLBACK_FOR_ALL_PRIMARY_MODELSは、フォールバックモデルが未設定のときに、過負荷エラーへのリトライ打ち切りを全モデルへ広げる環境変数です。1はもちろん0やfalseを入れても有効なままで、元に戻すには変数そのものを削除する必要があります。同じ「値でなく設定の有無だけを見る」挙動はDISABLE_TELEMETRYなど5つの変数にも共通します。名前から連想しやすい「モデルを自動で切り替える機能」はfallbackModelが別途担っており、fallbackModelのチェーンを設定済みの環境ではこの変数は関与しません。値を書き換えて挙動を確かめようとする前に、この2点を思い出せば無駄な検証を避けられます。