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: 不再是覆蓋所有設定，而是設定預設的子代理模型。agent definition 的model:與每次啟動時的明確指定現在具有優先權
（不再把所有內容都覆蓋掉，而是改為設定子代理的預設模型。代理定義中的model:，以及每次啟動時的明確指定，現在都會優先）
也就是從「覆蓋」變成了「預設值」。
4 種組合都測試了
我讓代理自己回答「你目前運行的模型 ID 是什麼」，並把回傳的 ID 記錄下來。
使用的代理
- 明確寫了
model: sonnet的代理 - 沒有寫
model:的代理
條件
# 沒有環境變數
claude -p "（啟動代理並詢問模型 ID）"
# 有環境變數
CLAUDE_CODE_SUBAGENT_MODEL=haiku claude -p "（同樣的事情）"結果
代理的 model:環境變數實際運行的模型sonnet無claude-sonnet-5``sonnet``haikuclaude-sonnet-5（定義優先）無無claude-opus-5[1m]無haikuclaude-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 在 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 只要按過一次，ANTHROPIC_DEFAULT_MODEL 就不會生效 — 同樣是模型指定優先順序的話題
- Claude Code 設定中容易踩雷的地方整理 — 關於設定與預設值的確認
JQIT 的工程師有 95% 以上都是從零經驗錄用。
如果有興趣，也歡迎來公司網站看看。
▶ 公司網站
我們也在招募工程師。如果有興趣，歡迎點進來看看。
▶ 招募網站
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
