CLAUDE_CODE_SUBAGENT_MODEL は、サブエージェントのモデルを指定する環境変数です。
これまでは全部を上書きしていました。 Claude Code 2.1.251 で、エージェント定義側が勝つように変わりました。
手元で4通り試したら、はっきり分かれました。
エージェントの model: 指定 環境変数 実際に動いたモデル
─────────────────────────────────────────────────
sonnet なし claude-sonnet-5
sonnet haiku claude-sonnet-5 ← 定義が勝つ
（なし） なし claude-opus-5
（なし） haiku claude-haiku-4-5 ← 環境変数が効く
検証環境: Windows 10 / Claude Code 2.1.251 / 測定は 2026-08-29 時点
何が変わったか
changelog にこう書かれています。
CLAUDE_CODE_SUBAGENT_MODEL: everything を override ではなく、default subagent model を set するように changed。agent definition のmodel:と explicit per-spawn model が now take precedence
（すべてを上書きするのではなく、サブエージェントの既定モデルを設定するように変更した。エージェント定義のmodel:と、起動ごとの明示指定が優先されるようになった）
「上書き」から「既定値」に変わったということです。
4通り測った
エージェント自身に「あなたが動いているモデルIDは何ですか」と聞かせ、返ってきた ID を記録しました。
使ったエージェント
-
model: sonnetを明示しているもの -
model:を書いていないもの
条件
# 環境変数なし
claude -p "（エージェントを起動してモデルIDを聞く）"
# 環境変数あり
CLAUDE_CODE_SUBAGENT_MODEL=haiku claude -p "（同じ）"
結果
エージェントの model:
|
環境変数 | 動いたモデル |
|---|---|---|
sonnet |
なし | claude-sonnet-5 |
sonnet |
haiku |
claude-sonnet-5（定義が勝つ） |
| なし | なし | claude-opus-5[1m] |
| なし | haiku |
claude-haiku-4-5-20251001（環境変数が効く） |
model: sonnet を持つエージェントは、環境変数を無視しました。 changelog の記述どおりです。
そして**model: を書いていないエージェントは、環境変数に従いました。** 何も指定しなければ、親セッションと同じモデル（この環境では Opus 5）で動きます。
手元では286本中21本が影響を受けない
自分の環境を数えました。
~/.claude/agents/ : 286 本
model: を指定 : 21 本（すべて sonnet）
指定なし : 265 本
環境変数で全部を Haiku に落としても、21本は Sonnet のまま動きます。
この21本が何かを見ると、意味がありました。独立レビューを担当するエージェントが並んでいます。
code-reviewer
qa-coverage-bva-reviewer
qa-coverage-dedup-reviewer
qa-coverage-dt-reviewer
demo-qa-reviewer
playwright-test-generator
...
レビューする側のモデルを固定したかったから model: を書いたわけです。変更後の挙動は、その意図に合っています。
何が困るか
環境変数でコストを絞っていた人は、挙動が変わります。
# 「サブエージェントは全部 Haiku で動かす」つもりだった
export CLAUDE_CODE_SUBAGENT_MODEL=haiku
変更前は本当に全部 Haiku になっていました。変更後は model: を書いたものだけ例外になります。
手元の例で言えば、265本は Haiku、21本は Sonnet という混在になります。コストの見積もりが変わります。
逆に言えば、モデルを固定したいエージェントには model: を書いておけばよいということでもあります。環境変数に消されなくなりました。
確認のしかた
自分の環境で何本が影響を受けるかは、すぐ数えられます。
# エージェント定義の総数
ls ~/.claude/agents/*.md | wc -l
# model: を指定しているもの（環境変数の影響を受けない）
grep -l "^model:" ~/.claude/agents/*.md | wc -l
# どのモデルを指定しているか
grep -h "^model:" ~/.claude/agents/*.md | sort | uniq -c
実際にどのモデルで動いたかを確かめるなら、エージェントに聞くのが早いです。
claude -p "（エージェント名）を起動して、そのエージェント自身に
『あなたが動いているモデルIDは何ですか』と聞いて、返ってきたIDを報告して"
ただし自己申告なので、疑わしいときは別の方法で裏を取ってください。 私は以前、ツールの一覧をモデルに聞いて実際には使えないものまで並んだことがあります。今回はモデルIDが4条件できれいに分かれたので、そのまま採用しています。
まとめ
- Claude Code 2.1.251 で
CLAUDE_CODE_SUBAGENT_MODELが「上書き」から「既定値」に変わった -
エージェント定義の
model:があれば、そちらが勝つ。 4条件で実測して確認した -
model:を書いていないエージェントは、これまでどおり環境変数に従う - 何も指定しなければ、親セッションと同じモデルで動く
- 環境変数でコストを絞っていた人は、混在が起きる。 手元では 286本中21本が例外になった
- 逆に、固定したいエージェントには
model:を書けば消されなくなった
「環境変数で全部を統一する」が効かなくなったので、どこにモデルを書いてあるかを一度確認しておくと、後で驚かずに済みます。
参考
- Claude Code changelog — 2.1.251 の項
- 検証環境: Windows 10 / Claude Code 2.1.251 / 測定は 2026-08-29 時点
関連記事
- /model を1度でも押すと ANTHROPIC_DEFAULT_MODEL は効きません — 同じくモデル指定の優先順位の話
- Claude Code の設定でハマる箇所まとめ — 設定と既定値の確認まわり
JQITのエンジニアの95%以上は未経験からの採用です。
よければコーポレートサイトにも遊びに来てください。
エンジニア採用も行っています。もしご興味あれば覗いてみてください。
▶ 採用サイト