CLAUDE_CODE_SUBAGENT_MODELとは — サブエージェントのモデルを固定する環境変数
CLAUDE_CODE_SUBAGENT_MODELはサブエージェント・teammate・workflowエージェントの既定モデルを指定する環境変数です。優先順位、Haiku固定によるコスト最適化、強制適用の設定を解説します。
CLAUDE_CODE_SUBAGENT_MODEL は、サブエージェント・Agent Teamsのteammate・workflowエージェントが、ほかの方法でモデルを指定されなかったときに使う既定モデルを決める環境変数です。エイリアス(haikuなど)かフルモデルIDを設定すると、指定を持たないすべての委任先セッションがその値に揃います。単独では組み込みのExplore/Planサブエージェントには効かず、それらまで固定したい場合は別の変数を追加で立てる必要があります。
CLAUDE_CODE_SUBAGENT_MODELが効く範囲
対象になるのは3種類の実行単位です。Agentツールで起動するカスタムのサブエージェント、Agent Teamsのteammate、ダイナミックワークフローの各ステージを担うworkflowエージェントの3つです。これらはいずれも独立したセッションとしてそれぞれモデルを選ぶ必要があり、CLAUDE_CODE_SUBAGENT_MODELはその「何も指定がないときの既定値」を1箇所で決める役割を持ちます。
値にはsonnet・opus・haiku・fableのようなエイリアス、またはclaude-opus-5のようなフルモデルIDを使えます。inheritを設定するのは、変数を未設定のままにするのと同じ扱いです。
モデル解決の優先順位
サブエージェントがどのモデルで動くかは、次の順で最初に該当したものが採用されます。
| 優先度 | 決定要素 | 備考 |
|---|---|---|
| 1 | 決定要素呼び出し時にClaudeが渡すmodelパラメーター | 備考Agentツール呼び出し単位の指定 |
| 2 | 決定要素サブエージェント定義のmodelフロントマター | 備考inheritならメイン会話のモデルを使う |
| 3 | 決定要素CLAUDE_CODE_SUBAGENT_MODEL | 備考エイリアスかモデルIDを設定している場合のみ |
| 4 | 決定要素メイン会話の現在のモデル | 備考何も指定がない場合の最終フォールバック |
Agent Teamsのteammateも4段階ですが、2番目が「spawnプロンプトでの明示指定」に置き換わります。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パラメーターやサブエージェント定義側のmodelフロントマターが既にあるサブエージェントは、環境変数より優先されるため対象から外れます。個別にmodel: opusと書かれた高精度用のサブエージェントはそのまま高精度モデルで動き続け、指定を持たないものだけがHaikuに揃う、という混在した状態になります。
コスト最適化の効果を全サブエージェントに及ぼしたい場合は、次に説明するCLAUDE_CODE_SUBAGENT_MODEL_FORCEと組み合わせる必要があります。
全サブエージェントに強制適用する
CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1を追加で設定すると、サブエージェント定義や呼び出し時の指定が何を名指ししていても、組み込みのExplore・Plan定義を含めたすべてがCLAUDE_CODE_SUBAGENT_MODELのモデルで動くようになります。
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_CODE_SUBAGENT_MODELを設定しても、優先順位表のとおり呼び出し時の指定や定義側のmodelフロントマターが先に評価されるため、想定どおりHaikuに揃っているかは見た目では分かりにくいことがあります。実際に動いているモデルを確認するには/tasksコマンドを実行します。各サブエージェントの行にそのとき動いているモデル名が表示され、定義や呼び出し元がeffortレベルを設定している場合はモデル名に続けてeffortの値も表示されます。設定を変えたあとにコストが想定どおり下がっているかを検証する際は、ログや請求額を待つより先に/tasksで実行中のモデルを目視で確認する方が早く気づけます。
まとめ
CLAUDE_CODE_SUBAGENT_MODELは、サブエージェント・teammate・workflowエージェントの「指定漏れを埋める既定モデル」を1箇所で決める環境変数です。v2.1.251以降は呼び出し時の指定とサブエージェント定義のフロントマターの方が優先されるため、Haikuへの固定でコストを抑えたい場合は、個別指定のないサブエージェントにしか効かないことをまず理解しておく必要があります。組み込みのExplore・Planを含めて全面的に固定したいならCLAUDE_CODE_SUBAGENT_MODEL_FORCEを併用します。サブエージェントの基本設計はClaude Code Sub-agents完全ガイド、Agent Teamsでのコスト管理はAgent Teamsのコスト管理、モデルとeffortをその場で切り替える方法はClaude Codeの/modelにまとめています。環境変数全体の一覧はClaude Code環境変数リファレンスを参照してください。