CLAUDE_CODE_SUBAGENT_MODELとは — サブエージェントのモデルを固定する環境変数

CLAUDE_CODE_SUBAGENT_MODEL は、サブエージェント・Agent Teamsのteammate・workflowエージェントが、ほかの方法でモデルを指定されなかったときに使う既定モデルを決める環境変数です。エイリアス(haikuなど)かフルモデルIDを設定すると、指定を持たないすべての委任先セッションがその値に揃います。単独では組み込みのExplore/Planサブエージェントには効かず、それらまで固定したい場合は別の変数を追加で立てる必要があります。

CLAUDE_CODE_SUBAGENT_MODELが効く範囲

これらはいずれも独立したセッションとしてそれぞれモデルを選ぶ必要があり、CLAUDE_CODE_SUBAGENT_MODELは「何も指定がないときの既定値」を1箇所で決める役割を持ちます。対象は次の3種類です。

値にはsonnet・opus・haiku・fableのようなエイリアス、またはclaude-opus-5のようなフルモデルIDを使えます。inheritを設定するのは、変数を未設定のままにするのと同じ扱いです。メイン会話と同じファミリーのエイリアス(Opusで動く会話でのopusなど)は、メイン会話が使っている正確なモデルに解決されます。

モデル解決の優先順位

サブエージェントがどのモデルで動くかは、次の順で最初に該当したものが採用されます。

Agent Teamsのteammateも4段階ですが、1番目が「spawnプロンプトでの明示指定」に置き換わります。2番目は、サブエージェント定義から起動したteammateならその定義のmodelです。3番目がCLAUDE_CODE_SUBAGENT_MODELである点は同じです。workflowエージェントも同じ優先順位に従い、スクリプトがステージに名前を渡していればそれが「呼び出し時の指定」として最優先になります。

v2.1.251で優先順位が入れ替わった

現在の優先順位は「明示指定 → 定義のフロントマター → 環境変数 → メイン会話」の順ですが、これはv2.1.251で決まった形です。それより前のバージョンではCLAUDE_CODE_SUBAGENT_MODELが最優先で、呼び出し時のmodelパラメーターやサブエージェント定義のmodel: inheritさえも上書きしていました。

つまり旧バージョンでは、この変数を設定した瞬間に「特定のサブエージェントだけメイン会話と同じ強力なモデルで動かしたい」という個別のinherit指定が意味を失っていました。優先順位の逆転は、環境変数という粗い設定より、個々のサブエージェント定義や呼び出し時の指定という細かい単位の意思を優先する方向への変更です。環境変数はあくまで「指定漏れを埋める既定値」という位置付けに整理されたことになります。

設定のしかた

シェルの環境変数として渡す方法が基本です。

export CLAUDE_CODE_SUBAGENT_MODEL=haiku
claude

チームで既定値を共有したいならsettings.jsonのenvキーに書きます。

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  }
}

プロジェクト直下の.claude/settings.jsonに書けば、そのリポジトリでClaude Codeを起動する全員に同じ既定値が適用されます。管理設定に書けば、ユーザー設定やプロジェクト設定の同じ変数より優先して配布できます。ただしモデル解決順の3番目という位置付けは変わらず、呼び出し時の指定や定義側のmodelが先に評価されます。

コスト最適化のためのHaiku固定

サブエージェントは、コードベースの探索やファイルの一覧化のように、必ずしも最上位モデルの推論力を必要としないタスクを大量にこなす場面が多くあります。個々のサブエージェント定義にmodel: haikuを書き込んで回るかわりに、CLAUDE_CODE_SUBAGENT_MODEL=haikuを1箇所に設定しておけば、モデル指定を持たないすべてのサブエージェント・teammate・workflowエージェントがHaikuで動くようになります。

ただしこの設定は、modelを持つサブエージェントには効きません。混在する構成の挙動は後述の比較にまとめています。役割ごとにどのモデルを割り当てるかの判断軸はClaude Codeサブエージェントのモデル配分設計にあります。

コスト最適化の効果を全サブエージェントに及ぼしたい場合は、次に説明するCLAUDE_CODE_SUBAGENT_MODEL_FORCEと組み合わせる必要があります。

全サブエージェントに強制適用する

CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1を追加で設定すると、優先順位を飛び越えてCLAUDE_CODE_SUBAGENT_MODELがサブエージェント(組み込みのExplore・Planを含む)に適用されます。

export CLAUDE_CODE_SUBAGENT_MODEL=haiku
export CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1
claude

この強制はv2.1.257以降で使えます。例外は2つだけで、/subtaskによるフォーク(現在の会話を分岐させる実行)と、model: inheritで動くスキルのサブエージェント実行は、強制の対象外のままメイン会話のモデルで動きます。

強制適用はコストの上限をはっきりさせたいCIパイプラインや、無人実行のバッチ処理で有効です。逆に、精査が必要なレビュー系のサブエージェントを個別に高精度モデルへ固定している構成では、強制適用をオンにするとその意図ごと上書きされる点に注意が必要です。

メイン会話のモデルを決める変数とは別物

セッション全体のモデルを切り替えるANTHROPIC_MODEL環境変数や--modelフラグ、/modelコマンドとCLAUDE_CODE_SUBAGENT_MODELは、名前は似ていますが対象がまったく違います。ANTHROPIC_MODELはメイン会話そのものが動くモデルを決め、CLAUDE_CODE_SUBAGENT_MODELはメイン会話から見て「配下」にあたるサブエージェント・teammate・workflowエージェントだけを対象にします。/model opusでメイン会話をOpusに切り替えても、CLAUDE_CODE_SUBAGENT_MODEL=haikuを設定していればサブエージェント側はHaikuのままです。両者は独立した設定で、片方を変えてももう片方には影響しません。

モデルに紐づくもう1つの設定である拡張思考(extended thinking)は、この独立関係とは違う継承ルールを持ちます。サブエージェントはv2.1.198以降、メイン会話で拡張思考がオンならサブエージェント側もオン、オフならオフという形で自動的に継承し、サブエージェント単位で個別にオン/オフを切り替える設定はありません。Agent Teamsのteammateも同様にリーダーのeffortレベル(推論の労力設定)をそのまま引き継ぎます。つまりCLAUDE_CODE_SUBAGENT_MODELでモデルだけを切り替えても、拡張思考やeffortレベルはメイン会話の設定に従い続けます。

組織の許可リスト(availableModels)で弾かれたとき

組織がavailableModelsでモデルの許可リストを設定している環境では、CLAUDE_CODE_SUBAGENT_MODELが指した値もこの許可リストの対象になります。許可リストに含まれないモデルを指定した場合、sonnetやopusのようなファミリーエイリアスならAnthropic APIやClaude Platform on AWS上で許可リスト内の最新版に自動的に置き換わり、対話セッションでは置き換え前後のモデル名を示す警告が表示されます。エイリアスでない具体的なモデルIDが許可リスト外だった場合は、メイン会話が継承するモデルにフォールバックします。

コストを抑える目的でHaikuに固定したつもりが、組織の許可リストにHaikuが含まれていない構成では、この置き換えルールによって意図しない上位モデルへ戻ることがあります。許可リストを運用している組織でCLAUDE_CODE_SUBAGENT_MODELを設定する場合は、指定したモデルが許可リストに実際に含まれているかを先に確認しておく必要があります。

手元のclaudeで確認できること(v2.1.285)

v2.1.285のclaude --versionとclaude --helpを実行して、モデル関連の入口を確認しました。

claude --version
claude --help | grep -n -i "SUBAGENT_MODEL"

1行目は2.1.285 (Claude Code)と表示されます。2行目のgrepは0件で、--helpの出力にこの環境変数は載っていません。--helpにあるのはメイン会話用の--model <model>(説明は「aliasで最新モデルを、またはフルネームを指定」)と、--fallback-model(既定モデルが過負荷や利用不可のとき、カンマ区切りで順に試す)、--agents(JSONでカスタムエージェントを定義)などです。

--helpにはサブエージェント専用の既定モデルを渡すフラグが載っていないため、環境変数かsettings.jsonのenvで渡します。claude --model haikuはメイン会話のモデルを変えるもので、優先順位の3番目には入りません。上位3段に何も無い委任先は4番目のフォールバックでメイン会話と同じHaikuになり、定義や呼び出し時の指定には負けます。

設定したのにモデルが揃わないときの切り分け

Haikuに固定したのにサブエージェントがHaikuで動かないときは、優先順位の上から順に当たると原因が絞れます。

• 定義か呼び出し時の指定が先に決めている: プロジェクトやユーザーのagents/配下でmodel:を検索します
• 動いているのが組み込みのExplore・Plan: /tasksの行で確認し、揃えるならCLAUDE_CODE_SUBAGENT_MODEL_FORCEを足します
• 組織のavailableModelsにHaikuが無い: 管理設定の許可リストを確認します。置き換わると対話セッションに警告が出ます

いずれも実際にどれが効いているかは次の/tasksで見て確定します。

実際にどのモデルで動いたかを確認する

CLAUDE_CODE_SUBAGENT_MODELを設定しても、上の優先順位のとおり呼び出し時の指定や定義側のmodelフロントマターが先に評価されるため、想定どおりHaikuに揃っているかは見た目では分かりにくいことがあります。実際に動いているモデルを確認するには/tasksコマンドを実行します。各サブエージェントの行にそのとき動いているモデル名が表示され、定義や呼び出し元がeffortレベルを設定している場合はモデル名に続けてeffortの値も表示されます。設定を変えたあとにコストが想定どおり下がっているかを検証する際は、ログや請求額を待つより先に/tasksで実行中のモデルを目視で確認する方が早く気づけます。

まとめ

CIや無人バッチのように上限を確実に決めたい場面ではFORCEの併用、対話で役割ごとに使い分ける構成では定義側のmodel:を残す、という選び分けになります。サブエージェントの基本設計はClaude Code Sub-agents完全ガイド、Agent Teamsでのコスト管理はAgent Teamsのコスト管理、モデルとeffortをその場で切り替える方法はClaude Codeの/model、環境変数全体はClaude Code環境変数リファレンスにあります。