Claude Code SUBAGENT_MODEL 还会强制覆盖吗

2.1.251 起环境变量只提供默认子代理模型,不再强制覆盖所有小弟;代理定义里的模型字段和单次指定会优先生效,升级后评审代理可能突然变贵。

Claude Code SUBAGENT_MODEL 还会强制覆盖吗

claude code CLAUDE_CODE_SUBAGENT_MODEL 还会强制吗:2.1.251 之前,这个环境变量会盖过子代理自己的选择。Changelog 改成:它只设置 default subagent model,不再 override everything。agent 定义里的 model:,以及 spawn 时显式指定的模型,优先于这个变量。

作者CodePass 技术编辑

新的优先级

从高到低可以记成:这一次 spawn 指定的模型 → 该 agent 文件 frontmatter 的 model:CLAUDE_CODE_SUBAGENT_MODEL → 产品内置默认。

组织在 shell 或托管 settings 里统一导出这个变量,本意是「所有小弟用便宜模型」。升级后,仓库里写了 model: opus 的评审代理会按文件走,不再被环境变量按回去。这是预期,不是回归。

主会话的 /model 不在这张表里。主会话默认仍看 ANTHROPIC_DEFAULT_MODEL 或套餐默认,见 默认模型

怎样验证已经按新规则

  1. 升到 2.1.251+。
  2. 导出 CLAUDE_CODE_SUBAGENT_MODEL 为一个便宜模型。
  3. 准备一个 agent 定义,frontmatter 写另一个 model:
  4. 让主会话按名字拉起它,看实际请求的模型是文件里的还是环境变量。

只要文件胜出,就是新行为。旧客户端会无视文件,只听环境变量。嵌套深度和 fork 默认是另一套,见 嵌套子代理

项目 settings 不能再偷改路径

同版本规定:项目级 .claude/settings.jsonenv 不能再设置 CLAUDE_CONFIG_DIRCLAUDE_CODE_TMPDIR,以及 TMPDIR / TMP / TEMP。这些要写在 shell、用户设置或托管设置。想靠项目文件把子代理的配置目录指到别处,现在不成。

ANTHROPIC_CUSTOM_HEADERS 若来自托管或项目设置,并且带了凭证、租户、路由或 API 行为头(例如 AuthorizationHost),要先批准才生效。和子代理模型不是同一开关,但常一起出现在「项目里塞环境变量」的习惯里。

团队升级时怎么迁

仍要强制所有子代理用同一个便宜模型:从每个 agent 文件里删掉 model:,只留环境变量。要让评审走 Opus、实现走 Sonnet:写在各自文件里,环境变量只当漏写时的底。

无人值守队友窗里,「把 auto 设成默认」的一次性提示在 2.1.251 不再出现,避免误按。那是权限模式提示,和模型环境变量无关,但同一周升级时容易一起撞见。

参考资料