Claude Codeサブエージェントのモデル指定と配分 — modelフィールドと環境変数の優先順位

サブエージェントのモデル指定は、定義ファイルのmodelフィールドに書くのが基本です。haiku / sonnet / opusのエイリアスかモデルID、または会話のモデルを引き継ぐinheritを指定できます。全体の既定値を変えたいときは環境変数CLAUDE_CODE_SUBAGENT_MODELを使いますが、優先順位は定義のmodelより下です。

なぜ全サブエージェントを同じモデルで動かすと損をするのか

サブエージェントは呼び出すたびに新しいコンテキストウィンドウを持つ独立したエージェントです。既定では呼び出し元の会話と同じモデルを引き継ぎます。何も設定しなければ、コードを探索するだけの軽い調査タスクも、最終成果物の品質を判定するタスクも、同じモデルで動きます。

Claude Codeのコスト削減ガイドはこの点について具体的な指針を示しています。「Sonnetはほとんどのコーディング作業をうまくこなし、Opusより安い。Opusは複雑なアーキテクチャ判断や多段階の推論に取っておく」としたうえで、「単純なサブエージェントのタスクには、サブエージェント設定でmodel: haikuを指定する」ことを推奨しています。モデルはmodelフィールド1つで役割ごとに変えられます。変えない構成のままだと、単純作業に高いモデルの単価を払い続けるか、判断が必要な作業を安いモデルに任せて精度を落とすか、どちらかに寄ります。

サブエージェントのmodelフィールドが決める割り当ての仕組み

サブエージェント定義のmodelフィールドには、sonnet / opus / haiku / fableのエイリアス、claude-opus-5のようなフルのモデルID、または呼び出し元の会話と同じモデルを使うinheritを指定できます。Claude Codeはサブエージェントを起動するとき、次の順でモデルを解決します。

環境変数は3番目、つまり既定値にすぎません。Claude Code v2.1.251より前は、この変数が最優先で、呼び出しごとの指定もmodel: inheritも上書きしていました。古いブログ記事や社内メモの「環境変数が最強」という説明は、この版より前の挙動です。

環境変数にエイリアスを入れた場合、会話が同じファミリーのモデルで進んでいても、エイリアスが指す版へ解決されます。フロントマターのopusが、会話のモデルがOpus系のときにその会話のモデルそのものへ解決されるのとは扱いが逆です。

ただしCLAUDE_CODE_SUBAGENT_MODELを設定しただけでは、組み込みのExplore・Planのモデルは変わりません。この2つを変えるには後述のCLAUDE_CODE_SUBAGENT_MODEL_FORCEが必要です。

組織のavailableModels許可リストで特定のモデルが禁止されている場合は、この解決結果がさらに置き換わります。エイリアス指定(opusなど)が禁止されていれば許可リスト内で最新のバージョンに差し替わります。それ以外の値が禁止されている場合、差し替えが働かないプロバイダーの場合、許可リストにそのファミリーのバージョンが1つもない場合は、会話のモデルで動きます。ただしCLAUDE_CODE_SUBAGENT_MODELを設定していれば、会話のモデルへ落ちる前にそのモデルを同じ規則で試します。インタラクティブセッションでは、どちらのモデルへ差し替えたかが警告として表示されます。

コンテキストが分離されることもモデル選びに影響する

サブエージェントは新しく起動するたびに、会話履歴もこれまで読んだファイルも引き継がない、まっさらなコンテキストウィンドウから始まります。呼び出し元のClaudeが依頼内容を要約した委任メッセージを組み立て、サブエージェントはその要約だけを頼りに作業します。例外は現在の会話をまるごと引き継ぐフォークで、これは通常のサブエージェントと違いモデルも呼び出し元と同じものを使います。

この仕組みは、モデルの選び方にもう1つの制約を加えます。通常のサブエージェントは会話の文脈を持たないぶん、委任メッセージの意図を正しく汲み取る力がそのまま結果の質を左右します。曖昧さを含む依頼(「よしなに直しておいて」に近い粒度の指示)を低コストなモデルに渡すと、文脈が無い状態で誤読するリスクが会話のモデルより上がります。指示が具体的で完結しているタスク(特定のログを検索する、決まったフォーマットで抽出する)ほど低コストなモデルへ安心して渡せます。この線引きは、価格だけでなくコンテキスト分離の性質からも導けます。

Claude Code自身の組み込みサブエージェントも役割で分けている

役割ごとにモデルを変えるという発想は、Claude Codeが自分の組み込みサブエージェントですでに実践している設計です。公式ドキュメントが挙げる組み込みサブエージェントのモデル割り当てを並べると、役割の重さと単価の対応がはっきり見えます。

ここで注目すべきは、claude-code-guide(製品の使い方に関する質問応答)とstatusline-setup(設定ファイルを組み立てる定型タスク)には、会話のモデルに関係なく固定でHaikuとSonnetが割り当てられている点です。どちらも「求められる判断の幅が最初から決まっているタスク」で、会話がOpusで進んでいても、この2つまで高いモデルへ引き上げる必要はありません。一方、ExploreとPlanのような調査系は会話のモデルを継承します。Explore側はClaude APIでOpusを上限にキャップしているため、会話がFable 5.1で進んでいても、後述の強制設定を入れない限りExploreはその単価で動きません。会話がSonnetやHaikuなら、ExploreはそのSonnetやHaikuのままです。

ユーザー定義のサブエージェントでも同じ考え方が使えます。Exploreという名前でユーザー・プロジェクトのサブエージェントを定義すれば組み込みのExploreを上書きでき、model: haikuと明示すれば調査を常に低コストなモデルへ固定できます。

Opus/Sonnet/Haikuの価格差を役割にどう対応させるか

公式の料金表を並べると、モデル間の単価差は次のとおりになります。

単価の差を実感するには、並列で走らせる本数を掛けるのが早道です。1本あたり入力10万・出力1万トークンのサブエージェントを10本走らせたとき、合計は入力100万・出力10万トークンになります。次の金額は、この想定にキャッシュ割引を考慮せず、上の表の単価を掛けただけの試算です。

Opusの出力単価はHaikuの4〜5倍(Opus 5.5は4倍、Opus 5は5倍)、Fableは10倍にあたります。サブエージェントを並列で何本も走らせる構成では、この単価差が呼び出し回数の分だけ積み上がります。公式ガイドも単純なサブエージェントのタスクにはmodel: haikuを挙げています。ただしHaikuはコンテキストウィンドウが20万トークンとほかの現行モデルの5分の1しかない点には注意が要ります。大きなログファイルや長いソースツリーを丸ごと読ませるサブエージェントにHaikuを割り当てると、単価では得をしても、入力が20万トークンの枠に収まらない場合があります。表のとおりHaikuはeffortにも非対応なので、後述するeffortによる代替も使えません。

Fable 5.1は表のなかで単価が最も高いモデルです。そのため、大量に並列起動するfan-out型のサブエージェントではなく、長時間・高難度の推論をこなす少数のサブエージェントに絞って使うのが料金表の裏づけと整合します。

品質ゲートと調査タスクで割り当てを変える設計原則

ここまでの事実を組み合わせると、役割ごとに割り当てを変える原則が見えてきます。

• 判断や最終チェックを担うサブエージェント(レビュー・採点・統合): 誤りの見落としがそのまま成果物の品質に直結するため、model: opusのように上位モデルへ固定するか、inheritで会話のモデルをそのまま使います。判断の重いタスクには単価より正確さを優先する構成です
• 調査・下読み・単純な抽出を担うサブエージェント: claude-code-guideと同じ考え方で、model: haikuかmodel: sonnetに軽くします。ただし対象がHaikuの20万トークン枠に収まるかは事前に確認します
• 並列で多数起動するfan-outタスク: 1本あたりの単価が呼び出し数倍になる構成なので、Opus・Fableは避け、Sonnet以下に寄せます

effortフィールドを使えば、モデルを変えずに同じ効果を部分的に得ることもできます。サブエージェント定義にeffort: lowのように指定すると、そのサブエージェントが動いている間だけ会話全体のeffortレベルを上書きできます。上書きできるのはセッションのレベルまでで、CLAUDE_CODE_EFFORT_LEVEL環境変数には勝てません。maxEffortLevelや組織のeffort上限も、サブエージェントの動くレベルを制限します。またこの代替はモデルによって対応状況が違い、Haiku 4.5はeffortに非対応です。Haikuを割り当てたサブエージェントでは、この代替案自体が使えません。単純作業をモデルごと下げるか、モデルは据え置いてeffortだけ下げるかは、対象タスクがモデルの知識差よりも思考量の差で困っているかどうかで選び分けます。呼び出し単位で変えたいときは、Agentツールのeffortパラメータが使えます。

model: opusと書いたのに別のモデルで動くときの切り分け

役割ごとにmodelを書き分けても、意図しないモデルで動いているように見えることがあります。原因は次の3つに絞れます。

CLAUDE_CODE_SUBAGENT_MODEL_FORCEを1にできるのはv2.1.257以降です。強制下でも、フォークと、model: inheritを指定したスキルのサブエージェントは会話のモデルのままです。設定した覚えのないまま有効になっていると、定義と実際のモデルが食い違う原因不明の挙動に見えます。

残る2つは、組織の許可リストで指定モデルが弾かれたケース(前述の差し替え規則)と、フロントマターにmodelを書かずに会話のモデルを継承しているケースです。どれに当たるかは、実行中のサブエージェントの行にモデル名が出る/tasksで確認できます。行にモデル名が出るのはv2.1.242〜v2.1.243以降です(docsはv2.1.242、changelogはv2.1.243の項目として記載)。定義かフォーク元のスキルにeffortがあればその値も並びます。

/tasks

対話セッションでは、差し替えが起きたとき、要求したモデルと実際に動くモデルを名指しする警告が出ます。警告が無いのに食い違うなら、疑う先は強制設定か継承です。

claude agentsはサブエージェントの一覧ではない

名前が近いので混同しやすいのですが、CLIのclaude agentsはサブエージェントの定義を表示するコマンドではありません。v2.1.285のヘルプを、空の設定ディレクトリで実行した出力は次のとおりです。

claude --version
claude agents --help

2.1.285 (Claude Code)
Usage: claude agents [options]
 
Manage background agents

説明は「Manage background agents」で、--model <model>や--effort <level>のオプションは、エージェントビューから起動するセッションの既定値を指します。サブエージェントのモデル配分とは別の話です。定義をコマンドラインから一時的に渡すなら、トップレベルの--agentsフラグを使います。ヘルプの例は'{"reviewer": {"description": "Reviews code", "prompt": "You are a code reviewer"}}'という形のJSONです。

claude --advisorはサブエージェントのモデルを決めるフラグではない

claude --advisor opus --subagents haikuのように、2つのモデル指定を並べて検索されることがあります。CLIリファレンスのフラグ一覧に載っているのは--advisor <model>で、--subagentsというフラグはありません。

--advisorはサーバー側のadvisorツールを、指定したモデルで有効にするフラグです。サブエージェントの割り当てとは別の仕組みなので、サブエージェントをHaikuにしたいなら、定義のmodel: haikuかCLAUDE_CODE_SUBAGENT_MODEL=haikuで指定します。--agentsでJSON定義を渡す場合も、その中にmodelを書けば同じ扱いです。

export CLAUDE_CODE_SUBAGENT_MODEL=haiku
claude --advisor opus

この2行は、モデル指定のないサブエージェントの既定をHaikuにしつつ、advisorにはOpusを使う例です。定義にmodelを書いたサブエージェントは、環境変数ではなく定義の値で動きます。

まとめ

配分の設計は、最終出力の正しさに直結する役割から上位モデルを固定し、残りを安いモデルへ下げていく順が安全です。逆に「まずHaikuで揃えて足りない役割だけ引き上げる」と、精度不足に気づくまで判断の重いタスクが安いモデルで動き続けます。設計を入れたあとは、強制設定が入っていないかを/tasksで確かめれば、配分が反映されているかを裏付けられます。

サブエージェントの切り方そのものの設計はClaude Code Sub-agents完全ガイドに、モデル自体の使い分けの一般論はClaudeモデル比較に、全サブエージェントを一律で固定する環境変数の詳細はCLAUDE_CODE_SUBAGENT_MODELとはにあります。ノードごとにモデルを選ぶ考え方は、Claude CodeでLangGraphエージェントを実装する場面にも通じます。