Claude Code effort level 设置：各模型实测默认档与不生效排查

Claude Code 里的 effort（官方中文文档叫"effort 级别"）决定 Claude 在一个请求上花多少功夫：想多深、读多少文件、调多少次工具、推进到哪一步才回来问你。它不换模型，同一个 Opus 5.5 开 low 还是开 max，回答你的都是 Opus 5.5。默认档取决于模型：截至 2026 年 11 月 2 日，Opus 5.5、Sonnet 5.5、Haiku 5.5 默认 medium，Opus 4.7 默认 xhigh，其他支持 effort 的模型默认 high。所以用 Opus 5.5 时底部状态栏显示 medium，是出厂设定，不是被悄悄降了档。

要改，先在 Claude Code 里运行 /effort status，看当前会话实际在用哪一档，再按想要的范围设置。只改这一次会话，就在 /effort 滑块里选好后按 s，或者启动时加 --effort high；想让某个模型以后一直用这一档，运行 /effort high，它会写进 ~/.claude/settings.json 的 modelSettings。max 是例外：交互里选它只对当前会话有效，settings 文件也不接受，要长期用 max 只能在启动前 export CLAUDE_CODE_EFFORT_LEVEL=max。这个环境变量优先级最高，设了它，/effort 和 --effort 都改不动档位。

文中标为"实测"的数值，是本站 2026 年 11 月 2 日在 macOS 上用 Claude Code 2.1.316 测得的：请求发往一个只记录请求内容、不调用真实模型的本地端点，记下每种设置下请求里 output_config.effort 的值。所以这些结果说明 Claude Code 发出了哪一档，不说明模型怎么回答、用了多少 token；其余内容来自 Anthropic 的 Claude Code 文档和博客。

Claude Code 的 effort 是什么：管做多少事，不管用哪个模型

effort 不只是"思考时间"。Anthropic 在博客文章 Choosing a Claude model and effort level in Claude Code 里说，effort 控制 Claude 对一个请求总共做多少工作：读多少文件、用多少工具、在多步任务里推进多远才回来确认。档位高，它会多读文件、多跑测试、多复查一遍；档位低，它更愿意先问你要上下文，而不是自己花 token 去摸索。Claude Code 模型配置文档 把 effort 描述为对自适应推理（adaptive reasoning）的控制，模型按任务复杂度决定每一步要不要想、想多少，所以它不是一个硬性的 token 上限，Anthropic 也说高档位在简单任务上一般不会刻意多花。

同一个档位名，在不同模型上不是同一个量。文档写明 effort 的刻度按模型分别校准：Opus 5.5 默认 medium，比 Opus 5 的默认 high 低一档，但在 Anthropic 自己的测试里，Opus 5.5 开 medium 在编程和知识工作评测上持平或超过 Opus 5 开 high，而且同一档下 Opus 5.5 每轮想得更多。从 Opus 5 换到 Opus 5.5 时，文档建议从 medium 起步，不要把旧模型上的档位原样搬过来。

结果不理想时，先分清是能力不够，还是活没干完。Anthropic 给的判断方法是：Claude 已经拿到全部相关上下文、明显尽力了还是做错，就换更强的模型；如果是漏看了文件、没跑测试、重构做到一半就收手，就提高 effort。纠结 Sonnet 5.5 开高档还是 Opus 5.5 开 medium 的，可以看 Sonnet 5.5 和 Opus 5.5 怎么选：半价未必更省，里面讲了为什么 Sonnet 开到 xhigh、max 往往比不上 Opus 低一档；要换到 Fable 之前想先算成本，看 Claude Fable 5.1 与 Opus 5：API 价格与任务成本怎么算。

各模型默认哪一档：5.5 系列是 medium，Opus 4.7 是 xhigh

什么都不设时，Claude Code 用模型自己的默认档：5.5 系列三个模型是 medium，Opus 4.7 是 xhigh，其余支持 effort 的模型都是 high。下表前两列来自 Claude Code 模型配置文档，最后一列是 2026 年 11 月 2 日的实测：在隔离的配置目录里运行 claude -p "Reply with OK" --model <模型 ID>，不加任何设置，记录请求里的 effort。七个模型的实测值都和文档一致，请求里同时带着 thinking: {"type":"adaptive"}。

表外的 Fable 5、Sonnet 5、Opus 4.8 同样支持全部五档、默认 high；Sonnet 4.6 和 Opus 4.6 一样没有 xhigh；文档没有列出的模型不支持 effort。如果你设了模型不支持的档位，Claude Code 会退到它支持的、不高于你所设的最高一档：实测在 Opus 4.6 上用 --effort xhigh，请求里发的是 high，终端没有任何提示。另外，组织管理员可以给组织默认模型指定一个默认 effort，用那个模型时它会取代上表的默认档。

Sonnet 5.5 有一处要留意：它只在 Claude Code 里默认 medium，直接调用 Claude API、不传 output_config.effort 时，Sonnet 5.5 默认是 high（Opus 5.5 和 Haiku 5.5 在 API 上仍是 medium）。Sonnet 5.5 各档的成本和升级时的变化，见 Claude Sonnet 5.5 对比 Sonnet 5：分档成本与五项破坏性变更。

low 到 max 怎么选：先用默认档，再按工作类型调

大多数编程任务用模型的默认档就合适。Anthropic 的建议是先用默认档，再按你平时做的工作类型整体调高或调低，把它当成一项长期偏好，而不是每个任务都调一次。下表的"适合"一列来自 Claude Code 文档的档位说明。

max、xhigh、high 的差别不是"越高越好"。Anthropic 在 Opus 5.5 和 Fable 5.1 上的测试显示，档位越高，Claude 测的边界情况越多、回答前复查的工作越多，也会更多地自己拿主意；档位低时，它更早交回一个起点，适合你每一步都要审阅、再指挥下一步的工作方式。所以准备让它长时间独立干活时，high 或 xhigh 比较合适；max 留给最难、又不需要你中途介入的任务，而且要接受它可能过度思考。在 Opus 4.6、Sonnet 4.6 上选 xhigh 等于 high，想往上只能直接选 max。

档位越高，同一个任务通常读得更多、跑得更多，订阅的 5 小时和每周额度、API 费用都会跟着多用；想知道 token 具体花在了哪里，看 Claude Code 用量查看与 Token 审计：5 小时和每周额度、缓存与 MCP。

怎么设置 effort：每种方法管多久、谁压过谁

设置方法按持续多久来选，多个来源同时存在时，Claude Code 按固定顺序取第一个生效的：环境变量 CLAUDE_CODE_EFFORT_LEVEL 最先，其次是会话里用 /effort 或 /model 选的档位，再次是启动参数 --effort，然后是 settings 文件里保存的档位，最后才是模型默认档。排在前面的来源存在时，后面的设置不会报错，只是不起作用，这是"设了没反应"最常见的原因。

交互里用 /effort 设置时，提示文字会告诉你这次设置是保存了还是只管本次。2026 年 11 月 2 日在终端里用 Opus 5.5、全新配置实测：运行 /effort high，提示 Set effort level to high (saved as your default for new sessions): Comprehensive implementation with extensive testing and documentation，~/.claude/settings.json 里多出 "modelSettings": {"claude-opus-5-5": {"effortLevel": "high"}}，底部状态栏变成 ● high；接着运行 /effort max，提示是 Set effort level to max (this session only): Maximum capability with deepest reasoning. May use excessive tokens resulting in long response times or overthinking. Use sparingly for the hardest tasks.，括号里写明只管本次会话，settings.json 没有变化，仍是 high，状态栏变成 ◈ max，下一条消息按 max 发出。

要手动改，或者一次给几个模型都设好，直接编辑 ~/.claude/settings.json。键名用模型的规范名，Claude Code 会把别名、带日期后缀和带 [1m] 的 ID 都对到同一条（需要 v2.1.251 以上）：

{
  "modelSettings": {
    "claude-opus-5-5": { "effortLevel": "high" },
    "claude-sonnet-5-5": { "effortLevel": "high" }
  }
}

谁压过谁，下面是同一天的实测结果。条件都是 claude -p 加隔离的配置目录，只测了用户 settings，项目 settings 和 managed settings 没有测。

skill 和 subagent 也能有自己的档位：在它们的 markdown 文件 frontmatter 里写 effort，skill 那一轮、subagent 运行期间就按这个档位跑，不管你启动、保存或选择的是哪一档（subagent 的调用方式可以再覆盖它）。例外有两个：设了 CLAUDE_CODE_EFFORT_LEVEL 时以环境变量为准，maxEffortLevel 或组织上限也照样限制它们。另外，通过 Remote Control 在手机或浏览器上选的档位只对当前会话有效（v2.1.234 以上）。

设了不生效、又变回 medium：症状、原因和改法

档位"自己变回去"，多半是三个原因之一：用户 settings 里旧的顶层 effortLevel 对 Opus 5.5 不算数；max 本来就不会被保存；shell 里的 CLAUDE_CODE_EFFORT_LEVEL 压过了你后来做的每一次设置。按症状对照下表找原因，再用对应的改法。

如果你看到的是"medium 就是降智"这类说法，先回到上一节的模型默认档：Opus 5.5 的 medium 是按模型校准过的默认，和 Opus 5 时代的 medium 不是一回事。真觉得不够，按工作类型把它保存成 high，比每次启动都加 max 更省额度。

怎么确认当前会话实际在跑哪一档：先跑 /effort status

最直接的检查是在 Claude Code 提示符下运行 /effort status，括号里的就是这个会话正在发送的档位；底部状态栏和会话标题显示的是你设置的档位，正在进行的那一轮可能还没换过来。按下面的顺序查，能找到是哪个来源在决定档位：

1. 看底部状态栏和会话标题。启动和改档时状态栏会短暂显示，例如 Opus 5.5 全新配置下是 ◐ medium · /effort；标题里的 "with low effort" 这类字样也来自你的设置。
2. 运行 /effort status。实测全新配置下输出 Effort level: auto (currently medium)：auto 表示你没给这个模型选过档位，括号里的 medium 是实际发送的默认档；如果只显示 Effort level: auto、没有括号，说明 Claude Code 一个档位都没发，由 API 的默认值决定。
3. 在启动 Claude Code 的同一个终端里运行 echo $CLAUDE_CODE_EFFORT_LEVEL。有输出，就是它在决定档位，前两步看到什么都以它为准。
4. 打开 ~/.claude/settings.json，看 modelSettings 下有没有当前模型的条目，顶层有没有 effortLevel 或 maxEffortLevel；再看当前项目里的 .claude/settings.json 和 .claude/settings.local.json。
5. 如果你通过自建网关或代理使用 Claude Code，可以在网关的请求日志里直接看请求体的 output_config.effort，这和前面实测记录的是同一个字段。

ultracode、ultrathink 和 auto：三个不是档位的词

这三个词都出现在 effort 相关的命令里，但没有一个是第六个档位：ultracode 是一个功能开关，ultrathink 只影响一轮对话，auto 是"不指定档位"的意思。它们的行为随版本改过几次，网上较早的说法很多已经不对。

ultracode 是开关，不是比 max 更高的一档

文档写明 ultracode 是 Claude Code 的一项设置，不是模型的 effort 档位：打开后，Claude 会为较大的任务编排动态工作流（dynamic workflows），用的是会话当前的档位。用 /effort ultracode 打开、/effort ultracode off 关闭，或者在 /effort 滑块里按 Tab 切换再按 Enter；要长期打开，在 settings 里写 "ultracode": true。从 v2.1.284 起，开关 ultracode 不会改变 effort 档位；在那之前，打开它会把会话设成 xhigh，改选其他档位又会把它关掉，较早的教程描述的是这种旧行为。

启动参数 --effort ultracode 是例外，它会同时打开 ultracode 并把档位设为 xhigh。2026 年 11 月 2 日实测，Opus 5.5 加这个参数，请求发的是 xhigh；换成不支持 xhigh 的 Opus 4.6，发的是 high，这和文档一致：模型没有 xhigh 或关闭了工作流时，ultracode 用不了，会话以模型和上限允许的最高档（最多到 xhigh）启动。effortLevel 设置和 CLAUDE_CODE_EFFORT_LEVEL 都不接受 ultracode 这个值。

ultrathink 只提高这一轮，"think hard" 没有作用

在提示里任何位置写上 ultrathink，只对这一轮要求更深的推理，不改会话的档位。在终端的输入框里输入时（需要 v2.1.311 以上），它还能把这一轮直接提到 xhigh，能提的时候这个词会显示成彩虹色。实测会话档位是 medium 时，输入 ultrathink about this and reply with OK 的那一轮按 xhigh 发出，下一轮普通消息又回到 medium，状态栏一直显示 medium。

用 claude -p 非交互运行时表现不同：-p "ultrathink: reply with OK" 的请求仍是 medium，Claude Code 只在上下文里加了一句 The user included the keyword "ultrathink", requesting deeper reasoning on this turn. Reason as thoroughly as the task warrants.。而 "think"、"think hard"、"think more" 不是关键词，实测 -p "think hard: reply with OK" 除了提示文字本身，请求和普通提示完全一样。如果 ultrathink 不变彩虹色，文档给的原因有：CLAUDE_CODE_EFFORT_LEVEL 设得低于 xhigh、maxEffortLevel 或组织上限低于 xhigh、当前模型不是 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 5.1；在 Amazon Bedrock 这类提不了档的环境里，直接设 effort 档位。

/effort auto 和环境变量 auto 不是一回事

/effort auto 只是清掉你给当前模型保存的档位，Claude Code 仍然会发送模型默认档。实测在 Opus 5.5 上运行 /effort auto 后，提示 Effort level set to auto，settings.json 里 claude-opus-5-5 的条目变成 {}，下一条消息按 medium 发出，/effort status 显示 Effort level: auto (currently medium)。其他模型的条目和顶层 effortLevel 不受影响。

真正"什么都不发"，要在启动前 export CLAUDE_CODE_EFFORT_LEVEL=auto（写 unset 效果相同）。实测这样启动后，请求里完全没有 effort 字段，由 API 端的默认值决定；按文档说明，这时状态栏和会话标题也不显示档位。有一个例外：设了低于 max 的 maxEffortLevel 时，Claude Code 仍会发送模型默认档并压到上限以内，/effort status 会显示 auto (currently <档位>)；v2.1.304 之前，即使没发送档位，它也会错误地显示 auto (currently high)。

给团队或单个模型设上限：maxEffortLevel

要限制别人能用的最高档，用 maxEffortLevel，不要用 effortLevel。在 managed settings 里写 effortLevel 只是给了一个起始档，用户仍可以用 /effort 或 --effort 改掉；maxEffortLevel 则会把任何更高的档位压到上限，包括 /effort、/model、--effort、环境变量、skill 和 subagent 的 frontmatter，以及模型自己的默认档。它由 Claude Code 在每次请求前本地执行，所以在 Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 上同样有效，需要 v2.1.267 以上。

上限可以写在任何一层 settings 里，多层都设时取最低的那个，所以在一层设的上限，别的层抬不高；值写 "max" 等于不设上限。下面这个例子把所有模型限制在 medium，单独放开 Sonnet 4.6：

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

2026 年 11 月 2 日实测：设 "maxEffortLevel": "high" 后用 --effort max 启动 Opus 5.5，请求发的是 high，标准错误输出里有一句 Effort 'max' exceeds the cap for claude-opus-5-5 set by your settings or organization; using 'high'.；同样的上限下改用 CLAUDE_CODE_EFFORT_LEVEL=xhigh，请求也是 high，但 -p 输出里没有任何提示。高于上限的档位不会出现在 /effort 滑块里。Claude Enterprise 的组织管理员还可以按自定义角色、按模型设 effort 上限（v2.1.195 以上），和 maxEffortLevel 同时存在时取较低的一个。

Claude Code effort 设置的其他问题

切换 effort 有快捷键吗？

有。在 /effort 滑块里用左右方向键一次移一档（v2.1.284 以上），Enter 保存，s 只用于本次会话，Tab 切换 ultracode，Esc 取消；在 /model 选择器里，左右方向键调的也是 effort 滑块。截至 2026 年 11 月 2 日，滑块界面显示 Faster … Smarter 和 low medium high xhigh max 五档，左右键可以在键位设置里改绑（effortSlider:decreaseEffort、effortSlider:increaseEffort 等），Enter 和 Esc 不能改。

报错 Effort 'xhigh' isn't available 怎么办？

完整报错是 API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0)，意思是你关掉了扩展思考，又用了高于 high 的档位，而 Opus 5 这类模型不接受这个组合。改法二选一：把档位降到 high 或以下；或者重新打开思考，去掉 MAX_THINKING_TOKENS=0，或删掉 settings 里的 "alwaysThinkingEnabled": false。根据 Claude Code 报错文档，v2.1.242 之前显示的是 API 原文 API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.，从 v2.1.251 起，Claude Code 对已知不接受这个组合的模型会自动改发 high。

关掉 adaptive thinking 还能解决"降智"吗？

在 5.5 系列和 Fable 上不能。截至 2026 年 11 月 2 日的 Claude Code 文档写明，Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 模型无法关闭思考，设置 alwaysThinkingEnabled: false 或 MAX_THINKING_TOKENS=0 对它们没有作用；CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING 也只对 Opus 4.6 和 Sonnet 4.6 有效，Fable、Sonnet 5 及以后、Haiku 5.5、Opus 4.7 及以后一律使用自适应推理。在这些模型上，effort 就是控制思考多少的那个开关。

通过第三方网关用 Claude Code，也会发送 effort 吗？

会。2026 年 11 月 2 日的测试本身就是把 ANTHROPIC_BASE_URL 指向自定义端点做的，Claude Code 2.1.316 在请求里带上了 output_config.effort 和 thinking: {"type":"adaptive"}。如果网关后面的模型因为 adaptive 报 400，看 Claude Code 400 thinking type should be enabled or disabled 解决；如果你希望 Claude Code 不发 effort、让对端用自己的默认值，启动前设 CLAUDE_CODE_EFFORT_LEVEL=auto。