博客 · 2026-11-06

Claude Code 子 agent 的 effort：有子 agent 的仓库里一半指定了模型却没写 effort

从 2.1.317 起，换了模型的子 agent 不再跟随会话的 effort 级别。我们读了 1,346 个公开仓库的 10,413 个子 agent 文件：指定模型的那些里 82% 没写 effort。优先级在 2.1.314 上实测。

概述

如果一个 Claude Code 子 agent 写了自己的 model，也给它写一行 effort。

原因很简单。从 2.1.317（11 月 3 日）开始，跑在和主会话不同模型上的子 agent，不再跟随你用 /effort 选的级别。它改用那个模型自己保存的级别，没保存过就用那个模型的默认值。所以你把会话调到 high，那个写了 model: opus 的审查子 agent 还是按 Opus 的默认值在跑。

这样写的子 agent 有多少？我们读了 5,864 个活跃公开仓库里的子 agent 文件。其中 1,346 个仓库至少有一个。指定了模型的子 agent 文件里，82% 没写 effort；有子 agent 的仓库里，一半至少有一个这样的。

一个月里，子 agent 的 effort 相关设置改了 5 次：

版本	日期	改动
2.1.292	10 月 6 日	Agent 工具加了 `effort` 参数，Claude 可以按你要求的级别启动某一个子 agent
2.1.296	10 月 9 日	子 agent 的 frontmatter 加了 `autoCompactWindow`，可以比主会话更早压缩上下文
2.1.312	10 月 27 日	子 agent 的 `autoCompactWindow` 可以把 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 设的窗口再压低，之前不起作用
2.1.316	10 月 31 日	加了 `CLAUDE_CODE_SUBAGENT_EFFORT`，在别处都没指定时决定子 agent 的级别
2.1.317	11 月 3 日	换了模型的子 agent 用那个模型保存的级别或默认值，不再用会话的

怎么测的

优先级实测。 在一个空项目里定义一个只跑一条 Bash 命令的子 agent，再配一个 PreToolUse 钩子，记下 Claude Code 传给钩子的 effort 字段。在 Claude Code 2.1.314 上运行 claude -p --model haiku --effort low，让 Claude 启动这个子 agent。四种情况：
- 子 agent 写 effort: high：跑在 high。
- 同上，再在环境变量里设 CLAUDE_CODE_EFFORT_LEVEL=medium：跑在 medium。
- 子 agent 不写 effort，模型继承主会话：跑在 low，也就是会话的级别。
- 子 agent 写 model: sonnet，不写 effort：跑在 low。这正是 2.1.317 改掉的行为。我们没有测 2.1.316 及以后的版本，所以下面的新规则来自 CHANGELOG 和文档。
仓库样本。 和我们的钩子、项目设置调查同一批：5,864 个公开仓库，5 星以上，10 月 7 日以后有推送，排除 fork，截至 2026 年 11 月 6 日。我们按抽样时的提交下载了每一个 .claude/agents/*.md，共 10,413 个文件，分布在 1,346 个仓库（23.0%），把 frontmatter 当 YAML 读。其中 9,317 个文件的 frontmatter 我们的解析器能读。
根本加载不了的文件。 文档列出了几种 frontmatter 问题，Claude Code 遇到时会跳过这个文件，而且不告诉你。我们逐条检查；YAML 错误这一条，我们把自己解析器读不了的文件交给 claude plugin validate 再判一次，因为 Claude Code 的解析器更宽松：470 个里它只标出 30 个。

测试结果

子 agent 的 effort 级别从哪来

按文档，从高到低：

环境变量 CLAUDE_CODE_EFFORT_LEVEL
Claude 启动这个子 agent 时传的 effort
子 agent frontmatter 里的 effort
以上都没有：和主会话同一个模型，用你会话的级别；换了模型，用那个模型保存的级别或默认值

2.1.316 加的 CLAUDE_CODE_SUBAGENT_EFFORT 在别处都没指定时决定级别。它写在 CHANGELOG 里，环境变量文档里还没有，所以在换了模型的情况下它和第 4 条谁先谁后，文档没说。

9,317 个子 agent 文件写了什么

字段	文件占比
写了 `model`	57.5%（sonnet 24.9%、opus 14.3%、inherit 6.7%、haiku 5.2%、完整模型 ID 4.7%、fable 1.2%）
写了 `effort`	10.3%（high 4.3%、medium 3.6%、low 1.2%、xhigh 0.8%、max 0.2%）
写了 `tools`	63.9%；其余的拿到子 agent 能用的全部工具
写了 `autoCompactWindow`	3 个文件，在同一个仓库

先猜一下：4,736 个指定了具体模型的文件里，有几个写了该想多深？846 个。剩下 3,890 个，也就是 82.1%，没写 effort。从 2.1.317 起，只要你的会话用的是别的模型系列，它们就按所指定模型自己的级别跑。在 Opus 会话里，model: opus 的子 agent 仍然跟着你的级别，因为这个别名会解析成你正在用的那个模型。

按仓库算（1,346 个有子 agent 的仓库）

	仓库数
至少一个子 agent 指定了模型	781（58.0%）
至少一个指定了模型、没写 effort	682（50.7%）
至少一个写了 effort	165（12.3%）
至少一个没写 `tools`	417（31.0%）
至少一个子 agent 文件会被 Claude Code 悄悄跳过	55（4.1%）

根本加载不了的文件

196 个文件（1.9%）有文档列出的问题：没有 name（77 个）、有 name 没有 description（64 个）、Claude Code 解析不了的 YAML（30 个）、开头的 --- 不在第一行（15 个）、名字不合法（10 个）。另有 611 个文件完全没有 frontmatter，Claude Code 会把它们当成文档；这些大多看起来就是 README 和笔记。

该忽略什么

暂时不用管 autoCompactWindow。我们的样本里只有 3 个文件用了它，而且文档和 CHANGELOG 对它和 CLAUDE_CODE_AUTO_COMPACT_WINDOW 怎么配合说法相反：子 agent 文档说以环境变量为准，2.1.312 却说这个字段现在可以把它压低。真要设的话写纯整数，比如 200000。文档提醒过，frontmatter 里写 200k 会被读成 200，然后被忽略。

多出来的键。color、type、priority、version 这类字段在很多文件里都有。Claude Code 只读它支持的字段，这些不碍事。

局限

实测用的是旧版本。 我们测的是 2.1.314。2.1.316 和 2.1.317 的规则来自 CHANGELOG 和文档，不是我们跑出来的。
会话用的是 Haiku。 模型能接受哪些级别因模型而异，Haiku 会话不一定能体现每个级别。
只静态读了文件。 我们数的是 frontmatter 里写了什么，没有跑仓库里的子 agent。
是样本。 5 星以上的活跃仓库，截至 2026 年 11 月 6 日，按代码搜索的相关度选出来，不是随机样本。

自己复现

计数在 subagent-effort-2026-11.json 里，不含仓库名和文件内容。想查自己的子 agent：在它运行时跑 /tasks，或者打开 .claude/agents/，找写了 model 却没有 effort 的那些。

同一批仓库的钩子，见 Claude Code 钩子出错时会放行。

Claude Code 子 agent 的 effort：有子 agent 的仓库里一半指定了模型却没写 effort

概述

怎么测的

测试结果

推荐

该忽略什么

局限

自己复现

来源