Claude Media
FALLBACK_FOR_ALL_PRIMARY_MODELSとは — 0やfalseでも有効になる罠
Claude CodeTips

FALLBACK_FOR_ALL_PRIMARY_MODELSとは — 0やfalseでも有効になる罠

FALLBACK_FOR_ALL_PRIMARY_MODELSは0やfalseを含むどんな値でも同じ効果になる環境変数です。対象範囲とfallbackModelとの関係、元に戻す手順をまとめます。

読了目安 約12分

FALLBACK_FOR_ALL_PRIMARY_MODELSは、フォールバックモデルを設定していないときに、過負荷エラーへのリトライ打ち切りを全モデルに広げる環境変数です。1を入れても0を入れても結果は同じで、変数が空でないという事実だけで有効になります。モデルを切り替える機能ではない点と、元に戻すときの落とし穴を中心に扱います。

「過負荷エラーへのリトライ打ち切り」とは何か

Claude Codeがモデルへ送るリクエストは、モデル側の混雑で過負荷(529)の応答を返されることがあります。通常、Claude Codeは一時的な失敗を指数バックオフで最大10回まで再試行してから、エラーを表示します。

この変数が操作するのは、同じ過負荷が繰り返されたときにリトライを続けず打ち切る挙動が、どのモデルに及ぶかです。過負荷エラー自体の見分け方やレート制限との違いはClaude rate limitエラーの対処で扱っています。

設定すると、打ち切りの対象が全モデルになる

打ち切りの範囲は、変数を設定するかどうかで次のように変わります。

くらべる

打ち切りの及ぶ範囲

限定的

変数を設定しない既定

Opus・Fable・Mythosと認識されるモデルだけが対象です。認証はAPIキーかサードパーティープロバイダーに限られ、Claudeのサブスクリプション認証では働きません。

全モデル

変数を設定した場合

SonnetやHaikuを含む全モデルで、過負荷の繰り返しに対するリトライが打ち切られます。変数の説明は認証の種類を限定していません。

前提は変わりません。この打ち切りが働くのは、fallbackModelのチェーンを設定していないときだけです。なぜ既定がOpus・Fable・Mythosに限られるのか、理由は公式の説明にありません。

サブスクリプション認証での反応が気になるなら、フォールバック未設定のまま変数を設定し、過負荷が続くセッションで試すのが確実です。

0やfalseでも止まらない

Claude Codeのオン・オフ系変数の多くは、1・true・yes・onで有効、0・false・no・offで無効という標準の真偽値として読まれます。FALLBACK_FOR_ALL_PRIMARY_MODELSはこの標準から外れます。

名前のFOR_ALL_PRIMARY_MODELSから「オンにするかどうかを選べる設定」を想像しがちですが、見ているのは中身の値でなく、空でない値が入っているかどうかです。

同じ読まれ方をする変数は他に5つある

公式の環境変数リファレンスは、設定の有無だけを見る変数として6つを挙げています。残りの5つは次のとおりです。

  • DISABLE_TELEMETRY(テレメトリの停止)
  • CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC(非必須通信の停止)
  • DISABLE_ERROR_REPORTING(クラッシュ報告の停止)
  • CLAUDE_CODE_TMUX_TRUECOLOR(tmux上での24bitカラー表示)
  • IS_DEMO(デモモード)

名前が似ていても読み方が違う変数があります。DO_NOT_TRACKは標準の真偽値として読まれ、0ならテレメトリは有効のままです。FORCE_HYPERLINKは数値として読まれるため、falseやnoを入れるとハイパーリンクが有効になります。

DISABLE_TELEMETRYのように動詞を含む名前は、設定しただけで何かが止まると読めます。一方FALLBACK_FOR_ALL_PRIMARY_MODELSは名詞の並びに近く、値で調整できる設定に見えやすい名前です。

この変数はモデルを切り替えない

名前からは、複数のモデルへ自動でフォールバックする機能そのものを連想します。しかし切り替えを担うのは、別の設定であるfallbackModelです。

くらべる

過負荷のときに何が起きるか

切り替える

fallbackModelを設定済み

v2.1.160以降は、どのプライマリモデルで過負荷が繰り返されても、チェーンの次のモデルへ切り替わります。この変数は切り替えに影響せず、設定しても意味がありません。

打ち切る

fallbackModelが未設定

同じモデルをリトライし、最後はサーバーのエラーを表示します。この変数の出番はここで、リトライを続けるか早めに打ち切るかを全モデルで揃えます。

モデルを切り替える機能だと誤解して設定しても、期待した自動復帰は起きません。

fallbackModelのチェーンの仕様

自動復帰が欲しいなら、使うのはチェーンの方です。仕様はモデル設定のページに次のように載っています。

  • チェーンは最大3モデルで、重複を除いた後の超過分は無視されます
  • 切り替えは現在のターンだけで、次のメッセージではプライマリモデルを先に試します
  • 切り替わったターンは、フォールバック先でプロンプトキャッシュが冷えた状態になります
  • availableModelsの許可リストにないモデルは、チェーンを読む時点で外されます
  • /statusにチェーンは表示されず、切り替え時の通知が最初に見える手がかりです
  • 圧縮(compaction)やサブエージェントにも適用されます
  • プライマリよりコンテキストウィンドウの小さいモデルへは切り替わりません。そこで要約すると会話の一部が先に切れてしまうためで、候補がすべて小さければ元のエラーが出ます

fallbackModelは設定ファイルの配列で、--fallback-modelフラグを付けた1セッションだけは、フラグが設定ファイルの値より優先されます。Claude Code v2.1.289の--helpでは、このフラグは次のように出ます。

claude --help
--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.

一時的に試すなら、claude --fallback-model sonnet,haikuのようにカンマ区切りで渡します。各エントリにはモデル名かエイリアスを書け、"default"は既定のモデルに展開されます。設定ファイルの配列も、同じ書き方です。

名前が似たもう1つの機構

Fable系のモデル、Opus 5.5、Sonnet 5.5、Opus 5には、安全性の分類器が検出したときに別モデルへ再実行する「automatic model fallback」もあります。サイバーセキュリティやバイオロジー関連のリクエストが対象で、過負荷とは発動条件が別です。

違いは継続期間にも出ます。チェーンの切り替えは1ターンで元に戻りますが、分類器による切り替え後は、/modelで戻すまでセッションがフォールバック先で続きます。この変数はどちらにも関与しません。

元に戻すときの落とし穴

設定はシェルの環境変数か、設定ファイルのenvキーで行います。

export FALLBACK_FOR_ALL_PRIMARY_MODELS=1
claude

個人の全プロジェクトに反映するなら~/.claude/settings.json、プロジェクト単位なら.claude/settings.jsonのenvキーに書きます。

{
  "env": {
    "FALLBACK_FOR_ALL_PRIMARY_MODELS": "1"
  }
}

元に戻すときは、値を書き換えず変数そのものを消します。ここで効くのが、シェルと設定ファイルの優先関係です。

手順

無効に戻す手順

  1. 1

    変数を設定している場所を洗い出す

    シェルのexport、~/.claude/settings.json、.claude/settings.json、組織の管理設定の4か所を確認します。同じ変数が複数に書かれていると、1か所だけ消しても有効なままです。

  2. 2

    シェルでは unset する

    unset FALLBACK_FOR_ALL_PRIMARY_MODELSで消します。シェルの環境変数はClaude Codeの起動時に読まれるため、反映は次回の起動からです。

  3. 3

    設定ファイルでは該当行を消す

    envの値は、シェルで同じ変数をexportしていても、設定ファイルの値で上書きされます。シェル側だけunsetしても、設定ファイルに行が残っていれば有効のままです。

  4. 4

    起動し直す

    設定ファイルのenvは、保存して中身が変わると実行中のセッションにも再適用されます。ただし公式は、設定ファイルでは変数を設定できても取り除けないと説明しているので、消した後はclaudeを起動し直します。

空にして打ち消す方法もあります。環境変数リファレンスの冒頭の注記は、設定の有無だけを見る変数を「unsetするか空にする」ことで無効にできると説明しています。設定ファイル側なら"FALLBACK_FOR_ALL_PRIMARY_MODELS": ""と空文字列を入れる形です。設定リファレンスには、シェルのexportを打ち消すには空文字列を設定するとあり、サブプロセスには空の値が引き継がれます。

同じ変数が複数の設定ファイルにあれば、優先度の高いファイルの値が採用されます。なおfallbackModelのチェーンは設定ファイル間でマージされず、最も優先度の高いファイルの配列がそのまま使われます。管理設定で配布されている変数は、手元の設定ファイルを消しても上書きされないので、管理者への確認が要ります。例外として、Claude Desktopアプリやセルフホスト環境のランナーがセッションを始めた場合は、起動時の環境が優先され、設定ファイル側のenvは無視されます。

組織全体で自動化の挙動を揃えるなら、個々のシェル設定に頼らず、管理設定のenvブロックに書いて配布します。

{
  "env": {
    "FALLBACK_FOR_ALL_PRIMARY_MODELS": "1"
  }
}

設定するかどうかの切り分け

fallbackModelのチェーンを設定済みなら、この変数は不要です。

チェーンを置かずに打ち切りの範囲だけ揃えたいときが、この変数の使いどころです。Sonnetなど、既定では打ち切りの対象外のモデルで、過負荷が繰り返されたらリトライせずエラーを返させたい場合にあたります。

打ち切られたあとに表示されるのは、API Error: Repeated 529 Overloaded errorsのようなエラーです。529は利用上限とは別物で、クォータには数えられません。容量はモデルごとに管理されているため、/modelでほかのモデルへ切り替えれば作業を続けられます。

Opusが混んでいるときは、Opus is experiencing high load, please use /model to switch to Sonnetという案内も出ます。Fableでは、メッセージにFableの名前が入ります。自動で切り替えたいなら、前節のチェーンを設定しておきます。

無人実行向けのCLAUDE_CODE_RETRY_WATCHDOGは、429と529を無制限にリトライする変数で、方向が逆です。環境変数の両方の行は互いに言及していないため、併用したときの優先関係は公式の行から読み取れません。環境変数全体の一覧はClaude Code環境変数リファレンスにあります。

まとめ

この変数は過負荷のリトライを打ち切る範囲を全モデルに広げるだけで、モデルは切り替えません。自動復帰が目的ならfallbackModelを使い、変数を消したいときは0でなくunsetと、設定ファイル側の行の削除が必要です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →