子 Agent 该用多大力气想？从 Claude Code 2.1.316 的 CLAUDE_CODE_SUBAGENT_EFFORT，聊多 Agent 编码的 effort 分层

Twinkle Model — Sun, 01 Nov 2026 07:04:47 +0000

短版摘要（供短帖渠道使用）
10 月 31 日发布的 Claude Code 2.1.316 新增了 CLAUDE_CODE_SUBAGENT_EFFORT：当没有其他设置指定时，子 Agent 用这个档位运行，而不再默认继承主会话的 effort。这看起来是个小开关，但对多 Agent 编码的成本影响很大：主会话开 xhigh 做规划，搜索、读代码、跑测试的子 Agent 往往用 medium 甚至 low 就够了。本文梳理 effort 的完整优先级（环境变量 > 会话内选择 > 启动参数 > 设置文件 > 模型默认），子 Agent frontmatter 怎么写，以及一套“主会话高、子任务低、审查单独拉高”的分层配置。

用 Claude Code 跑稍微大一点的任务，你会发现真正花 token 的往往不是主会话，而是它派出去的一堆子 Agent：搜代码的、读文档的、跑测试的、做审查的。过去它们默认继承主会话的 effort，你为了让主会话规划得更好开了 xhigh，结果十几个只是在 grep 文件的子 Agent 也跟着“深度思考”。

10 月 31 日的 Claude Code 2.1.316 给了一个直接的解法。下面我把这次更新、effort 的解析规则和我自己在用的分层配置一起讲清楚。

一、2.1.316 改了什么

按官方 changelog，和 effort 相关的有三条：

新增 CLAUDE_CODE_SUBAGENT_EFFORT：当没有任何其他来源为子 Agent 指定档位时，子 Agent 用它，而不是继承主会话的档位。
新增 CLAUDE_CODE_DISABLE_ULTRATHINK：关掉 ultrathink 关键字。团队里有人习惯在提示词里随手写 ultrathink，这个开关可以防止成本被意外拉高。
VS Code 扩展里，ultrathink 现在会以 xhigh 档位运行当前这一轮，和终端行为一致。

同一版本还给 Claude apps gateway 加了两项管理能力：pooled_budget（一个组共享的月度预算，叠加在每个成员自己的限额之上）和 managed.policy_mode: layered（所有匹配的策略按顺序叠加生效，而不是只取第一条）。另外 changelog 再次提醒：Opus 4.8 的 fast mode 已于 10 月 30 日弃用，11 月 30 日移除，之后这类请求直接报错、不会回落到普通 Opus 4.8。

这几条放在一起看，方向很明确：Anthropic 在把“这次调用该花多少推理”变成可以按层级、按团队管理的配置项。

二、effort 到底是怎么决定的

先说 effort 本身。官方设置文档对几个档位的描述是：

档位	官方定位
`low`	推理最少，适合范围小、对延迟敏感、不太考验智力的任务
`medium`	为成本敏感的工作减少 token，可以牺牲一些智力
`high`	在 token 用量和智力之间平衡
`xhigh`	更深的推理，更高的 token 开销
`max`	最高档，可在部分入口使用，但不能写进 `effortLevel` 设置

不同模型的默认值不一样：支持 effort 的模型默认 high，但 Opus 5.5、Sonnet 5.5、Haiku 5.5 默认 medium，Opus 4.7 默认 xhigh。如果你设置的档位模型不支持，会回落到它支持的最高档，比如 xhigh 在 Opus 4.6 上按 high 跑。

主会话的档位按下面的顺序取第一个生效的：

环境变量 CLAUDE_CODE_EFFORT_LEVEL；
会话内的选择（/effort、/model 里的滑块）；
启动参数 --effort；
设置文件里的 modelSettings 或 effortLevel；
模型默认值（或组织为默认模型设的默认档位）。

子 Agent 多了几层。结合子 Agent 文档和这次的 changelog，我整理成下图：

有两个容易踩的坑：

CLAUDE_CODE_EFFORT_LEVEL 会盖过一切，包括子 Agent frontmatter 里的 effort。很多人在 shell 配置里 export 了这个变量图省事，结果给审查 Agent 写的 effort: xhigh 完全不生效。想要分层，就别用这个环境变量设全局档位，改用设置文件。
上限永远在。maxEffortLevel 或组织级的 effort 上限，会同时限制主会话、skill 和子 Agent。frontmatter 写得再高，也会被压回上限以内。

三、一套分层配置

我的原则很简单：规划和审查要想得深，执行和检索要跑得快。

第一步，在项目的 .claude/settings.json 里给主会话设默认档位，不用环境变量：

{
  "effortLevel": "xhigh"
}

第二步，给子 Agent 一个偏低的兜底档位。CLAUDE_CODE_SUBAGENT_EFFORT 是环境变量，可以放进启动脚本或 CI 的环境里：

# 主会话按 settings.json 用 xhigh；没写 effort 的子 Agent 一律 medium
export CLAUDE_CODE_SUBAGENT_EFFORT=medium
# 防止有人在提示词里写 ultrathink 把单轮拉到 xhigh
export CLAUDE_CODE_DISABLE_ULTRATHINK=1
claude

第三步，对少数确实需要深度推理的子 Agent，在 frontmatter 里单独拉高。比如 .claude/agents/reviewer.md：

---
name: reviewer
description: 在合并前审查改动，关注并发、安全和边界条件
tools: Read, Grep, Glob, Bash
model: opus
effort: xhigh
maxTurns: 30
---
你是代码审查者。只读不写，逐条列出问题、给出位置和修复建议。

而检索类的子 Agent 可以更激进：

---
name: code-searcher
description: 在仓库里定位函数、调用点和配置，返回文件路径与行号
tools: Read, Grep, Glob
model: haiku
effort: low
omitClaudeMd: true
---
只返回找到的位置和一句话说明，不要分析。

这里 omitClaudeMd: true（v2.1.271 起支持）让它启动时不加载 CLAUDE.md，对只需要委派提示词的检索任务，能再省一截上下文。

这样配下来，一个典型任务的结构是：主会话 xhigh 做拆解，大量检索和执行子 Agent 用 low 或 medium，最后一个 xhigh 的审查 Agent 把关。比起“全员 xhigh”，省下来的主要是那些本来就不需要深思的子任务的推理 token。具体能省多少取决于任务形态，建议你用自己的仓库跑几次、对比账单再定档位，别直接套我的配置。

四、接第三方网关时要注意什么

不少团队是通过自建网关或兼容 Anthropic 协议的中转来跑 Claude Code 的，配置方式是设置 ANTHROPIC_BASE_URL。以 Twinkle Model 为例（换成官方地址或你自己的网关同样适用）：

export ANTHROPIC_BASE_URL="https://big-model.smart-agi.com"
export ANTHROPIC_AUTH_TOKEN="YOUR_KEY"
export CLAUDE_CODE_SUBAGENT_EFFORT=medium
claude

effort 是随请求发给模型的参数，经过网关时有两点值得自查：

网关是否原样透传 effort 相关字段。如果中间层丢掉了这个参数，所有请求都会按模型默认档位跑，你的分层配置等于没配。最简单的验证方法是同一个问题分别用 low 和 xhigh 各跑一次，对比返回的输出 token 数，差距明显就说明透传正常。
按子 Agent 做成本归因。Claude Code 的 hooks 能拿到子 Agent 的 agent_type（也就是 frontmatter 的 name）。在 hook 里把 agent_type、档位和 token 用量记到日志，月底就能回答“哪个子 Agent 最费钱”，而不是只看一个总账单。

五、我的看法

CLAUDE_CODE_SUBAGENT_EFFORT 本身只是一个环境变量，但它反映的是多 Agent 系统里一个很朴素的事实：不同角色需要的思考深度差得很远，默认继承是最贵的默认值。这个需求在社区里早就有人提过（GitHub issue #43083 讨论的就是给子 Agent 单独配 effort），先有了 frontmatter 的逐个配置，这次又补上了全局兜底。

我的建议是：把 effort 当成和 model、tools 一样的子 Agent 一等配置来设计，而不是事后调参。主会话的档位决定计划质量，子 Agent 的档位决定账单。

参考来源

Claude Code changelog（2.1.316，2026-10-31）：https://code.claude.com/docs/en/changelog
Claude Code 文档，Model configuration（effort 解析顺序与默认值）：https://code.claude.com/docs/en/model-config
Claude Code 文档，All settings（effortLevel 各档位说明）：https://code.claude.com/docs/en/settings-reference
Claude Code 文档，Create custom subagents（frontmatter 字段）：https://code.claude.com/docs/en/sub-agents
GitHub issue，Feature: configurable reasoning effort level for subagents：https://github.com/anthropics/claude-code/issues/43083

作者说明：我在运营一个 API 中转站 Twinkle Model（https://big-model.smart-agi.com），源头中转：GPT 1折、国产模型 1折、满血 Claude，主打低价、稳定。文中的网关地址只是示例，用官方接口或自建网关同样适用。各模型价格见模型广场：https://big-model.smart-agi.com/model-plaza 。