Claude Code effort 档位怎么设：子 Agent 与 ultrathink

Claude Code 的 effort 档位决定模型每一步想多深：档位低，回得快、费的 token 少；档位高，会多测边界情况、多验证几遍再交活。10 月 31 日发布的 2.1.316 加了 CLAUDE_CODE_SUBAGENT_EFFORT 和 CLAUDE_CODE_DISABLE_ULTRATHINK 两个环境变量，子 Agent 从这一版起可以不再跟着主会话的档位走。下面按 Anthropic 官方文档和 CHANGELOG（2026-11-01 北京时间查阅）把主会话、子 Agent、Skill 和 ultrathink 四处的档位设置理一遍，每一步都附了可以直接改的配置。

前置条件

• Claude Code 升到 2.1.316 或更新：claude update，再用 claude --version 确认。只想用 Skill/子 Agent 的 effort 字段，老一些的版本也行；调用时临时传档位要 2.1.292 起，maxEffortLevel 要 2.1.267 起。
• 模型要支持 effort。Fable 5.1/5、Opus 5.5、Sonnet 5.5、Haiku 5.5、Opus 5、Sonnet 5、Opus 4.8、Opus 4.7 都有 low 到 max 五档；Opus 4.6 和 Sonnet 4.6 没有 xhigh，设了会按 high 跑。
• 知道自己的 ~/.claude/settings.json 和项目里 .claude/agents/ 在哪。

第一步：先看清现在跑在哪一档

在会话里输入 /effort status，会打印当前档位。默认值按模型不同：Opus 5.5、Sonnet 5.5、Haiku 5.5 默认 medium，Opus 4.7 默认 xhigh，其余支持 effort 的模型默认 high。

从 Opus 5 换到 Opus 5.5 的人要留意：官方说 Opus 5.5 在 medium 下的编码和知识类评测，已经追平或超过 Opus 5 在 high 下的成绩，而且同一档位下 Opus 5.5 每轮想得更多。所以别把原来的 high 原样搬过去，先从 medium 起步。

第二步：给主会话定档

最常用的是 /effort：不带参数会弹出滑块，左右键选档；直接写 /effort high 也行。确认方式决定它管多久：在滑块里按 Enter，或者直接敲 /effort 档位，会按模型存进用户设置的 modelSettings，以后的会话都用这一档；按 s 只管当前会话（2.1.257 起）。max 例外，除非用环境变量设，否则只在当前会话生效。想清掉某个模型存下的档位，用 /effort auto。

几处来源同时设了档位时，Claude Code 按下面的顺序取第一个：

还有一种情况：想让 API 用它自己的默认档，可以在启动前 export CLAUDE_CODE_EFFORT_LEVEL=auto（写 unset 效果相同），这时 Claude Code 不发送档位，/effort status 显示 Effort level: auto。如果后面还跟着「currently 某档」，说明仍在发送档位，多半是设了低于 max 的 maxEffortLevel。

改档位不会打断正在跑的回合，新档位从你下一条消息开始算。Claude 还在干活时，可以发一句 keep going 排进队列，等手上的工具调用结束，后面的活就按新档位跑。

第三步：给子 Agent 和 Skill 单独定档

派出去搜代码、跑测试的子 Agent，多数用不着主会话那么高的档位。最省事的做法是在定义文件的 frontmatter 里写 effort：

---
name: test-runner
description: 跑测试并汇总失败用例
tools: Read, Grep, Glob, Bash
model: haiku
effort: low
---

只运行测试命令，汇总失败的用例和报错位置，不要修改代码。

这个字段在子 Agent 运行期间覆盖会话档位。你在对话里让 Claude「用 high 跑这个子 Agent」时，它会在这次调用里传 effort 参数，覆盖 frontmatter，子 Agent 被恢复后也保持这一档（2.1.292 起；fork 出来的子 Agent 不支持）。/tasks 里每个子 Agent 那一行会写出它的模型和单独设的档位。

2.1.316 新加的 CLAUDE_CODE_SUBAGENT_EFFORT 是兜底：调用和定义文件都没写档位时，子 Agent 按它跑，不再继承主会话。主会话常开 high 的人，可以这样启动：

export CLAUDE_CODE_SUBAGENT_EFFORT=low
claude

Skill 也有 effort 字段，作用范围是触发它的这一回合剩下的部分；Skill 写了 context: fork 时，这个值改成设定 fork 出来的子 Agent 的档位。Skill 正文里还能用 ${CLAUDE_EFFORT} 读到当前档位，按档位调整给模型的指令。

检索、跑测试这类子 Agent 开 low，主会话保留原档位，省下的额度留给需要推理的那几步。

第四步：封顶，以及关掉 ultrathink

在提示词里写 ultrathink，只把这一回合往深里想，不改会话档位。2.1.311 起，终端里这个词显示成彩虹色时，说明这一回合会升到 xhigh。如果脚本或模板里会带上这个词，又不希望它改变档位，可以设 CLAUDE_CODE_DISABLE_ULTRATHINK=1 把关键词关掉（2.1.316）。

想给所有档位设个上限，用 maxEffortLevel。下面的写法把所有模型封在 medium，Sonnet 4.6 单独放开：

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": { "maxEffortLevel": "max" }
  }
}

超过上限的档位一律按上限跑，/effort、--effort、环境变量、Skill 和子 Agent 的 frontmatter 都管得住。这个限制由 Claude Code 在每次请求前自己执行，Bedrock、Agent Platform、Foundry 上同样有效。企业版管理员还能按角色给每个模型设上限，两层都存在时取更低的那个。

常见坑

• shell 里残留 CLAUDE_CODE_EFFORT_LEVEL：它排在所有设置前面，子 Agent 的 effort 字段和调用参数也压不过它。发现子 Agent 档位怎么改都不变，先 echo $CLAUDE_CODE_EFFORT_LEVEL。
• 旧的顶层 effortLevel 对 Opus 5.5 不生效：用户设置里那个顶层键是 /effort 按模型存档之前的老写法，Opus 5.5 和之后的新模型会无视它，从自己的默认档起步。要定档就用 /effort 重新选一次。
• 设置文件里写 max 无效：modelSettings 和 effortLevel 都不接受 max，长期用 max 只能走环境变量。
• 安全分类触发换模型后档位不变：Opus 5.5 上的请求被分类器拦下、自动改用 Opus 4.8 重跑时，会话保留原来的档位。比如原本是 medium，换过去还是 medium，虽然 Opus 4.8 默认是 high。想换档，用 /effort status 看一眼再改。
• ultrathink 没变彩虹：常见原因是词被引号、括号或路径包住，或者 CLAUDE_CODE_EFFORT_LEVEL、maxEffortLevel 把档位压在 xhigh 以下。Bedrock 上这个词升不了档，直接设档位。

完成标准

• /effort status 显示的档位和你预期的一致。
• 派一个子 Agent 后，/tasks 里它那一行显示你给它设的档位。
• 设了 maxEffortLevel 后，/effort 滑块里不再出现高于上限的档位。
• 设了 CLAUDE_CODE_DISABLE_ULTRATHINK=1 后，输入 ultrathink 不再变色。

最后

先把 /effort status 跑一遍，再给最常用的那个子 Agent 加一行 effort: low。子 Agent 的 tools、model 和作用域还没配过的，看站内这篇 Claude Code 子 Agent 配置教程。