Claude Code effortLevel 配置不生效的原因与正确设置

概述

在 ~/.claude/settings.json 里写了 "effortLevel": "max"，重启后却发现推理档位并没有变成 max，看起来"配置没生效"。

这其实不是配置项写错了——effortLevel 确实是 Claude Code 支持的合法配置项。真正的原因在于：max 这一档属于"仅当前会话有效"的级别，无法通过 settings.json 的 effortLevel 字段持久化。本文梳理 effort 级别的取值、各配置入口的优先级，以及让 max 真正持久生效的正确做法。

问题现象

用户的 settings.json 大致如下：

{
  "env": {},
  "permissions": {
    "defaultMode": "bypassPermissions"
  },
  "effortLevel": "max"
}

预期：每次启动 Claude Code 都以 max 推理档位运行。 实际：effortLevel 看起来被忽略，档位没有变成 max。

根本原因：max 不通过 settings.json 持久化

effortLevel 用来控制模型的推理/思考强度（reasoning effort）。它的取值会因模型而异：

模型	支持的级别
Opus 4.8 / Opus 4.7	low、medium、high、xhigh、max
Opus 4.6 / Sonnet 4.6	low、medium、high、max

关键区别在于持久化行为：

• low / medium / high / xhigh：写在 settings.json 的 effortLevel 字段里，会跨会话持久化。
• max：属于仅当前会话有效的级别，单靠 settings.json 的 effortLevel 字段无法持久化——这正是"看起来没生效"的原因。

换句话说，如果你想持久化的目标是 high 或更低，写 effortLevel 是可以的；但目标是 max，就必须换一个能持久化它的入口。

各配置入口与优先级

effort 级别可以从多个位置设置，优先级从高到低如下：

方式	位置 / 形式	优先级
环境变量	CLAUDE_CODE_EFFORT_LEVEL	最高
设置文件	~/.claude/settings.json（用户级）或项目级 .claude/settings.json 的 effortLevel	中
命令行标志	claude --effort <level>	较低
斜杠命令	/effort <level>（仅当前会话）	当前会话
模型默认值	模型内置默认	最低

由此得到结论：用优先级最高的环境变量 CLAUDE_CODE_EFFORT_LEVEL，既能覆盖其它入口，又能让 max 持久生效。

正确设置：用环境变量持久化 max

在 settings.json 的 env 块里加入 CLAUDE_CODE_EFFORT_LEVEL：

{
  "env": {
    "CLAUDE_CODE_EFFORT_LEVEL": "max"
  },
  "permissions": {
    "defaultMode": "bypassPermissions"
  },
  "effortLevel": "max"
}

说明：

• env 里的 CLAUDE_CODE_EFFORT_LEVEL 优先级最高，会覆盖顶层的 effortLevel。
• 顶层那个 effortLevel: "max" 此时是冗余的，留着无妨，想干净也可以删掉。
• 环境变量的改动需要重启 Claude Code 会话（退出重进）才会被加载。
• 重进后可用 /effort 命令确认当前档位是否为 max。

也可以在 shell 层面直接设置环境变量（等价做法）：

# macOS / Linux
export CLAUDE_CODE_EFFORT_LEVEL=max

# Windows PowerShell（当前会话）
$env:CLAUDE_CODE_EFFORT_LEVEL = "max"

其它配置入口速查

除了写文件，还有几种即时/启动期的设置方式：

# 启动时指定
claude --effort xhigh

# 会话内实时切换
/effort xhigh

# 写入 settings.json 持久化（适用于 high 及以下）
# ~/.claude/settings.json -> { "effortLevel": "high" }

与"扩展思考"配置区分

effort 级别和扩展思考（Extended Thinking）是两套独立配置，不要混淆：

{
  "alwaysThinkingEnabled": true,
  "showThinkingSummaries": true
}

如需完全关闭思考，可用环境变量：

{
  "env": {
    "CLAUDE_CODE_DISABLE_THINKING": "1"
  }
}

另外需要澄清的是：旧的 MAX_THINKING_TOKENS 是固定思考预算时代的 API，不用于 Claude Code 的 effort 级别配置。Opus 4.7 及更新版本已改为自适应推理，不再依赖这一变量。

总结

• effortLevel 是合法配置项，但 max 是"仅当前会话有效"的级别，写在 settings.json 的 effortLevel 字段里无法持久化，于是表现为"没生效"。
• 想持久化 max，应使用优先级最高的环境变量 CLAUDE_CODE_EFFORT_LEVEL，在 settings.json 的 env 块中设置。
• 配置优先级：环境变量 > settings.json > --effort 标志 > /effort 斜杠命令 > 模型默认。
• env 改动需重启会话生效，事后用 /effort 验证当前档位。
• effort 级别与扩展思考（alwaysThinkingEnabled 等）是两套独立配置；MAX_THINKING_TOKENS 与新版 effort 机制无关。

延伸思考：当某个配置"语法正确却不生效"时，先确认该取值是否支持持久化、以及是否存在更高优先级的入口覆盖它，往往比反复检查拼写更快定位问题。