Claude Codeのモデル設定｜役割ごとに変える3か所と優先順位

「定義ファイルに軽いモデルを指定した。それなのに、ワーカー役はメインの会話と同じモデルで動き続けている」。Claude Codeで役ごとにモデルを分けようとすると、この行き止まりに当たります。

原因は、指定を書ける場所が環境変数・エージェント定義ファイル・実行時オプションの3か所に分かれている点にあります。しかも重なったときの順序は1本ではなく、メインの会話用とサブエージェント用の2本が並んで走っています。書いた場所が間違っているのではなく、書いた場所より強い指定がどこかに残っている、という形でつまずきます。

この記事は、どこに何を書けば反映されるのかを公式ドキュメントに沿って並べ直します。検証したのはclaude-opus-5・Claude Code v2.1.x系・macOS 15の組み合わせで、検証日は2026-08-03です。

進行役は3人です。若葉さんが言葉の意味から、高梨課長が自分の手で動かす側から聞き、鈴木さん（本誌監修）が答えます。

01Claude Codeのモデル設定は、AIエージェントのどこに効くんですか？

若葉さん

若葉さんの発言

モデル設定というと、どのAIを使うかを1つ選ぶ話ではないんですか。

鈴木さん

鈴木さんの発言

1つではないんです。撮影の現場に近いと思っています。全体を見て指示を出す人と、割り振られた作業を受け持つ人がいて、同じ人でなければいけない理由はありませんよね。

Claude Codeは、1つのセッションの中に2つの役を持ちます。利用者と直接やり取りするメインの会話と、そこから作業を任されるサブエージェントです。本記事では前者をディレクター役、後者をワーカー役と呼びます。

モデル設定とは、この2つの役へそれぞれどのモデルを充てるかの指定です。下書きを作るような判断の要る作業と、表記ゆれを見るような機械的な作業を、同じモデルで受け持たなければならない理由はありません。役ごとに分けられるのは、その理由のなさを設定へ落とせるからです。

ただし、指定を書ける場所は3か所に分かれています。環境変数、エージェント定義ファイル、実行時オプションです。同じ役に対して複数の場所から指定が届いたときは、決まった順序で上書きされます。

02モデル設定を書ける3か所は、エージェントのどれを動かすんですか？

3か所の違いは、何を動かすかと、その指定がいつまで残るかの2点に出ます。

書き始める前に確かめることが2つあります。1つはバージョンです。本記事はv2.1.196以降の挙動を基準にしています。CLAUDE_CODE_SUBAGENT_MODELにinheritを指定したときの扱いが、このバージョンの前後で変わるためです。claude -vで確認します。

もう1つは、どの階層のsettings.jsonを編集するかです。settings.jsonは管理設定・コマンドライン引数・ローカル・プロジェクト・ユーザーの5階層に分かれます。同じキーはこの順で上書きされるので、チームで共有したいのか手元に留めたいのかで書く場所を選びます。

03環境変数でモデル設定を変えると、サブエージェントは全員そろうんですか？

高梨課長

高梨課長の発言

環境変数なら1行で済みますよね。これで役ごとに分けられますか。

鈴木さん

鈴木さんの発言

そこが分かれ道です。環境変数は全員に配る通達に近くて、宛名を書き分ける欄がありません。分けたいときは、その通達を出さないほうを選びます。

環境変数は2種類あり、受け持つ相手が違います。

ANTHROPIC_MODELは、メインの会話（ディレクター役）のモデルを指定します。settings.jsonのmodelキーより優先されますが、セッション限定の上書きなのでsettings.json自体は書き換わりません（出典: Claude Code公式ドキュメント）。

CLAUDE_CODE_SUBAGENT_MODELは、委譲されるサブエージェント（ワーカー役）の全員へ一律で適用されます。個々の定義ファイルがmodel: opusと書いていても、この環境変数のほうが優先されます。

export ANTHROPIC_MODEL=claude-opus-5
export CLAUDE_CODE_SUBAGENT_MODEL=claude-haiku-5
claude

その場だけ試すならexport、チームへ配るならsettings.jsonのenvキーに書きます。envの値は、起動するセッションと、そこから生成するサブプロセスの両方へ渡ります。

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

inheritという値の扱いは、バージョンの前後で反転します。v2.1.196以降は未設定と同じ扱いになり、次は呼び出しごとの指定へ、その次は定義ファイルのmodelフィールドへ進みます。v2.1.195以前は逆に、メインの会話のモデルへ強制する値でした。

04定義ファイルのモデル設定で、AIエージェントの役割ごとに割り当てられるんですか？

割り当てを役ごとに変える本体は、ここです。サブエージェント定義ファイルのmodelフロントマターには、sonnet・opus・haiku・fableのエイリアスを書きます。claude-opus-5のような完全なモデルIDでも指定できます。省略するとinherit扱いになり、メインの会話と同じモデルを使います（出典: Claude Code公式ドキュメント）。

役ごとに変えるとは、下書きを作るwriterには判断力の要るモデルを指定し、フォーマットの機械的な確認だけを行うbulk-checkerには軽いモデルを指定する、ということです。

---
name: writer
description: 記事の下書きを作成する
model: sonnet
---

---
name: bulk-checker
description: 表記ゆれなど機械的な確認だけを行う
model: haiku
---

組み込みの調査役Exploreは、v2.1.198以降メインの会話のモデルを引き継ぎます（Claude API利用時は上限がOpus。出典: Claude Code公式ドキュメント）。調査役だけ軽いモデルへ固定したいなら、同名のExplore定義を自分で作りmodel: haikuを書けば上書きできます。

---
name: Explore
description: コードベースの調査に使う
model: haiku
---

定義ファイルそのものの書き方はAGIM-210で、役の分け方の考え方はAGIM-209で扱っています。本記事は「モデルをどこに書けば反映されるか」に絞ります。

05同じ名前のサブエージェントが並んだら、どの定義のモデル設定が採られるんですか？

置き場所にも順位があります。同名のサブエージェントが複数あるときは、上位の場所にある定義のmodelフィールドが採用されます。

06実行時オプションのモデル設定は、そのセッションのエージェントだけ変わるんですか？

--modelは、セッション開始時にメインの会話のモデルを指定するフラグです。settings.jsonのmodelキーとANTHROPIC_MODELの両方より優先されます（出典: Claude Code公式ドキュメント）。起動のたびに切り替えたいときに使います。

claude --model claude-opus-5

すでに起動しているセッションを切り替えるには/modelを使います。settings.jsonのmodelキーを直接書き換えても、反映されるのは次に起動したときです。いま開いているセッションで試したい場合は/modelのほうが早く分かります。

/model sonnet

--agentsフラグは、ワーカー役の定義をコマンドラインからJSONで渡します。ファイルに保存されない一時的な定義で、置き場所の順位は管理設定に次ぐ2位です。そのため、同名の定義ファイルより先に読まれます。

claude --agents '{
  "writer": {
    "description": "記事の下書きを作成する",
    "model": "sonnet"
  }
}'

名前の似た--fallback-modelは、役割分担の設定ではありません。主モデルが混雑または提供終了で使えないときの代替先を、カンマ区切りで指定する機能です。目的の違うものとして区別しておきます。

07Claude Codeのモデル設定が重なったとき、AIエージェントではどちらが勝つんですか？

高梨課長

高梨課長の発言

結局、どれが勝つんでしょうか。順番を1本覚えれば済みますか。

鈴木さん

鈴木さんの発言

1本では足りないんです。列が2本あります。同じ駅名でも路線が違えば行き先が変わるのと同じで、どちらの列の話をしているかを先に決めます。

優先順位は1本ではありません。メインの会話用とサブエージェント用の2本があり、混同すると役ごとに割り当てたはずの設定が崩れます。

役ごとに割り当てを変えたいなら、CLAUDE_CODE_SUBAGENT_MODELは設定しません。設定した瞬間に順位1が全ワーカーを同じモデルへそろえてしまい、定義ファイルに書いたmodelフィールド、つまり順位3が効かなくなります。環境変数を外した状態で、定義ファイル側だけに書くのが基本形です。

08組織でモデルが制限されていると、AI導入したエージェントのモデル設定は黙って戻るんですか？

戻ります。組織がavailableModelsでモデルを制限している場合、順位1〜3のどれで指定しても、許可リストの外にあるモデルは無視されます。その結果、優先順位は順位4のメインの会話のモデルまで下がります。

やっかいなのは、エラーが出ないことです。指定を書いた側の画面では何も起きず、動いた結果だけがいつもと同じになります。ワーカー役が期待どおりに動かないとき、設定の書き方より先にこの制限を疑う理由が、ここにあります。

09モデル設定が反映されないAIエージェントは、どこから疑えばいいんですか？

高梨課長

高梨課長の発言

直したのに変わらない、というときは何から見ればいいですか。

鈴木さん

鈴木さんの発言

近いところからではなく、上から見ます。強い指定ほど静かに効いているので、手元のファイルを何度直しても表に出てこないんです。

見どころは大きく4つあります。順番に潰すと切り分けが早くなります。

はじめに疑うのは、環境変数の残留です。シェルやCIに以前設定したCLAUDE_CODE_SUBAGENT_MODELが残っていると、定義ファイルのmodelをいくら直しても表に出ません。echo $CLAUDE_CODE_SUBAGENT_MODELで空かどうかを見てから、定義ファイルを疑います。

次が再起動漏れです。settings.jsonのmodelキーは起動時にしか読み込まれません。編集してそのまま同じセッションで試すと反映されず、「効かない」と誤診しがちです。いま確かめたいなら/modelを使います。

3つ目は同名定義の競合です。.claude/agents/と~/.claude/agents/に同じ名前のサブエージェントを置くと、プロジェクト側が優先されます。Exploreを上書きするつもりで別の階層に置くと、標準の挙動のまま変わりません。

最後が無言のフォールバックです。前章のとおり、許可リストから外れたモデルを指定してもエラーは出ず、メインの会話のモデルへ戻ります。ワーカー役の様子がおかしいときは、まずこの制限を疑います。

10割り当てたモデル設定で動いているかは、AI社員の運用でどう確かめるんですか？

確かめ方は2つあります。

1つは、Git commit trailerを見る方法です。コミット時のトレーラーに、動いていたモデル名が残ります（出典: Claude Code公式ドキュメント）。書式はCo-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>のようになり、過去のコミットを見返せば当時のモデルを追えます。メインの会話がどれで動いていたかを、あとから追う用途に向きます。

もう1つは、--debug apiでAPIリクエストを見る方法です。--debugはapiのようなカテゴリでログを絞り込めます。メインの会話とサブエージェントは別々のAPIリクエストになるため、ディレクター役とワーカー役がそれぞれどのモデルへ送っているかを個別に追えます。

判定そのものは単純です。ワーカー役に指定したモデル名がリクエストに出ていれば、反映されています。メインの会話と同じモデル名しか出てこなければ、優先順位のどこかで上書きされています。

11よくある質問

12まとめ｜今日やる3つのこと

役は2つ、書ける場所は3か所、そして順序は2本。この3つの数え方を分けて持つと、どこを直せばよいかが見えるようになります。効いたかどうかは、設定ファイルではなく動いた記録の側から確かめます。