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

> Opus 5.5、Sonnet 5.5 在 Claude Code 里默认 medium，不算降档。/effort 按模型保存，max 只管本次会话，环境变量优先级最高。

- URL: https://blog.laozhang.ai/zh/posts/claude-code-effort-level
- Published: 2026-11-02
- Updated: 2026-11-02
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: Claude Code
- Tags: Claude Code, effort, Opus 5.5, Sonnet 5.5, settings.json, ultrathink

---
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](https://claude.com/blog/claude-model-and-effort-level-in-claude-code) 里说，effort 控制 Claude 对一个请求总共做多少工作：读多少文件、用多少工具、在多步任务里推进多远才回来确认。档位高，它会多读文件、多跑测试、多复查一遍；档位低，它更愿意先问你要上下文，而不是自己花 token 去摸索。[Claude Code 模型配置文档](https://code.claude.com/docs/en/model-config) 把 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 怎么选：半价未必更省](https://blog.laozhang.ai/zh/posts/claude-sonnet-5-5-vs-opus-5-5)，里面讲了为什么 Sonnet 开到 `xhigh`、`max` 往往比不上 Opus 低一档；要换到 Fable 之前想先算成本，看 [Claude Fable 5.1 与 Opus 5：API 价格与任务成本怎么算](https://blog.laozhang.ai/zh/posts/claude-fable-5-1-migration-pricing-cache-effort)。

## 各模型默认哪一档：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"}`。

| 模型 | 可用档位 | 文档写的默认档 | 11 月 2 日实测发送 |
| --- | --- | --- | --- |
| Opus 5.5 | `low`、`medium`、`high`、`xhigh`、`max` | `medium` | `medium` |
| Sonnet 5.5 | `low`、`medium`、`high`、`xhigh`、`max` | `medium` | `medium` |
| Haiku 5.5 | `low`、`medium`、`high`、`xhigh`、`max` | `medium` | `medium` |
| Fable 5.1 | `low`、`medium`、`high`、`xhigh`、`max` | `high` | `high` |
| Opus 5 | `low`、`medium`、`high`、`xhigh`、`max` | `high` | `high` |
| Opus 4.7 | `low`、`medium`、`high`、`xhigh`、`max` | `xhigh` | `xhigh` |
| Opus 4.6 | `low`、`medium`、`high`、`max`，没有 `xhigh` | `high` | `high` |

表外的 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：分档成本与五项破坏性变更](https://blog.laozhang.ai/zh/posts/claude-sonnet-5-5)。

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

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

| 档位 | 适合什么工作 | 代价 |
| --- | --- | --- |
| `low` | 你会逐条审阅结果的快速来回，比如头脑风暴、写初稿、改个名字这样的小改动 | 回得最快、花得最少，但它更少主动核对，下一步要靠你把关 |
| `medium` | Opus 5.5、Sonnet 5.5、Haiku 5.5 的默认；范围清楚的日常开发，比如实现一个新功能 | 在默认 `high` 的模型上调到 `medium` 能省 token，会让出一部分能力 |
| `high` | 需要核实、容易出边界情况的工作，比如在现有代码库里修 bug；多数模型的默认 | 比 `medium` 多读、多测，用量更高 |
| `xhigh` | 需要更深推理的任务；Opus 4.7 的默认 | token 花费更高；Opus 4.6、Sonnet 4.6 没有这一档，会按 `high` 跑 |
| `max` | 希望 Claude 不用你插手、自己啃完的难题，比如找安全漏洞 | 文档提醒它可能收益递减、容易过度思考，建议先试再大面积用；交互里设置只对当前会话有效 |

`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](https://blog.laozhang.ai/zh/posts/claude-code-usage-limit-issues)。

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

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

![Claude Code 决定 effort 档位的五个来源按优先级排列，右侧是 /effort 滑块里 Enter、s 和 max 分别管多久](https://blog.laozhang.ai/posts/zh/claude-code-effort-level/img/effort-priority-order.webp)

| 方法 | 持续多久 | 优先级和限制 |
| --- | --- | --- |
| 环境变量 `CLAUDE_CODE_EFFORT_LEVEL=<档位>` | 从这个 shell 启动的每个会话 | 第 1，连 skill、subagent 自带的 effort 也压过；唯一能长期固定 `max` 的方法 |
| `/effort <档位>`，或 `/effort` 滑块里按 `Enter` | `low` 到 `xhigh`：保存为当前模型的默认，以后的会话都用；`max`：只当前会话 | 第 2；在 `-p`、Agent SDK 和远程会话里只对当前会话 |
| `/effort` 滑块或 `/model` 里按 `s` | 只当前会话，需要 v2.1.257 以上 | 第 2 |
| `/model` 选择器里用左右方向键调滑块 | 和 `/effort` 一样，`Enter` 保存，`s` 只当前会话 | 第 2；最迟从你的下一条消息开始生效 |
| 启动参数 `claude --effort <档位>` | 这一次启动的会话 | 第 3，压过 settings，会被环境变量和会话里的选择压过 |
| settings 里的 `modelSettings`，按模型写 | 长期 | 第 4；只接受 `low` 到 `xhigh`，不接受 `max` |
| settings 顶层 `effortLevel` | 长期 | 第 4；在用户 settings 里只对 Opus 5、Fable 5.1 及更早的模型有效，在项目、local、managed 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 以上）：

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

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

| 设置 | 模型 | 请求里发出的 effort |
| --- | --- | --- |
| `--effort low` | Opus 5.5 | `low` |
| `--effort max` | Opus 5.5 | `max` |
| `--effort xhigh` | Opus 4.6 | `high`，没有提示 |
| `CLAUDE_CODE_EFFORT_LEVEL=low` 加 `--effort high` | Opus 5.5 | `low`，环境变量胜出 |
| `CLAUDE_CODE_EFFORT_LEVEL=max` | Opus 5.5 | `max` |
| `CLAUDE_CODE_EFFORT_LEVEL=auto` | Opus 5.5 | 请求里没有 effort 字段 |
| 用户 settings 顶层 `"effortLevel": "high"` | Opus 5.5 | `medium`，顶层键被忽略 |
| 用户 settings 顶层 `"effortLevel": "max"` | Opus 5 | `high`，`max` 被忽略，`-p` 输出里没有提示 |
| `modelSettings` 里给 `claude-opus-5-5` 设 `high` | Opus 5.5 | `high` |
| 同一个 settings 文件 | Sonnet 5.5 | `medium`，按模型保存，不影响别的模型 |
| 同一个 settings 文件，再加 `--effort low` | Opus 5.5 | `low`，启动参数胜出 |

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` 压过了你后来做的每一次设置。按症状对照下表找原因，再用对应的改法。

![effort 设了不生效的四种常见情况：症状、原因和改法对照](https://blog.laozhang.ai/posts/zh/claude-code-effort-level/img/effort-not-sticking-fixes.webp)

| 症状 | 原因 | 改法 |
| --- | --- | --- |
| `~/.claude/settings.json` 里写了 `"effortLevel": "high"`，Opus 5.5 还是 `medium` | 顶层 `effortLevel` 是 v2.1.251 之前 `/effort` 写的旧格式，在用户 settings 里只对 Opus 5、Fable 5.1 及更早的模型有效，Opus 5.5 和之后的模型忽略它 | 在 Opus 5.5 下运行 `/effort high`，或在 `modelSettings` 里给 `claude-opus-5-5` 写一条 |
| 设成 `max`，下次打开又回到 `medium` 或 `high` | 交互里选的 `max` 只对当前会话有效；`effortLevel` 和 `modelSettings` 都不接受 `max`，写了会被忽略，`-p` 模式下也没有提示 | 每次启动加 `--effort max`，或在 shell 配置里 `export CLAUDE_CODE_EFFORT_LEVEL=max` |
| 给 Opus 5.5 设了 `high`，切到 Sonnet 5.5 又是 `medium` | 档位按模型分别保存 | 切到 Sonnet 5.5 后再设一次，或在 `modelSettings` 里同时写两个模型 |
| `/effort`、`--effort` 怎么改都没反应 | shell 里设了 `CLAUDE_CODE_EFFORT_LEVEL`，它排第一 | `unset CLAUDE_CODE_EFFORT_LEVEL`，并检查 `~/.zshrc` 等 shell 配置文件里有没有 export 它 |
| 只在某个仓库里档位不对 | 项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 写了顶层 `effortLevel`，它对所有模型生效，而且优先级高于你保存在用户 settings 里的档位 | 改项目里的设置，或在会话里用 `/effort` 临时覆盖 |
| 选了 `max` 或 `xhigh`，实际只有 `high` | 设了 `maxEffortLevel` 上限或组织的 effort 上限；或者模型是 Opus 4.6、Sonnet 4.6，没有 `xhigh` | 调整上限（组织上限要找管理员），或直接选模型支持的档位 |
| `/effort` 已经确认，Claude 还在按旧档位干活 | 新档位从你发出的下一条消息开始生效，正在进行的这一轮不变 | 在它工作时输入一句 `keep going` 按回车排队，它处理完当前工具调用就按新档位继续 |
| 模型被自动切换（fallback）后，档位和新模型的默认档不一样 | 自动切换后沿用被拦下那一轮的档位，例如 Opus 5.5 的 `medium` 切到 Opus 4.8 仍是 `medium` | 运行 `/effort status` 确认，再用 `/effort` 设成想要的档位 |
| 启动时出现 `Warning: Unknown --effort value 'banana' — ignoring it and using the default effort. Valid values: low, medium, high, xhigh, max.` | `--effort` 的值拼错了，实测在 Opus 5.5 上这时按默认档 `medium` 发送 | 只用 `low`、`medium`、`high`、`xhigh`、`max`，或 `ultracode` |

如果你看到的是"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：

```json
{
  "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 解决](https://blog.laozhang.ai/zh/posts/claude-code-thinking-type-enabled-or-disabled)；如果你希望 Claude Code 不发 effort、让对端用自己的默认值，启动前设 `CLAUDE_CODE_EFFORT_LEVEL=auto`。

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-11-02。

- [Choosing a Claude model and effort level in Claude Code](https://claude.com/blog/claude-model-and-effort-level-in-claude-code) (claude.com)
- [Claude Code 模型配置文档](https://code.claude.com/docs/en/model-config) (code.claude.com)