命令字典
Slash 命令、CLI 子命令、Hook 事件、启动参数的字典与演进史。
Slash 命令、CLI 子命令、Hook 事件、启动参数的字典与演进史。
为当前会话设置处理难度级别（low/medium/high/xhigh/max）
--effort <level>claude --effort high--effort 是 Claude Code CLI 的启动 flag，用于为当前会话设置模型的处理力度（effort level）——控制模型在生成回复（包括文本、工具调用、以及思考过程）时愿意花费多少 token。
根据官方文档（code.claude.com/docs/en/cli-reference），该 flag 的作用是"为当前会话设置 effort level"，并且会"覆盖（override）modelSettings 和 effortLevel 设置，仅对本次会话生效，不会持久化"。
接受的值包括：low、medium、high、xhigh、max，以及一个特殊值 ultracode（官方文档说明 ultracode 相当于开启 xhigh effort 并叠加 ultracode 工作流，需要 Claude Code v2.1.203 或更高版本）。
默认值取决于所用模型，并非固定值。据 code.claude.com/docs/en/model-config 页面：
模型的默认 effort：除 Opus 5.5 默认
medium、Opus 4.7 默认xhigh外，其余支持 effort 的模型默认都是high。
claude --effort high
对应的环境变量和 settings.json 字段：
export CLAUDE_CODE_EFFORT_LEVEL=high
{
"effortLevel": "high"
}
会话内也可以用 /effort 命令临时调整，无需重启：
| 配置方式 | 作用范围 | 接受值 | 备注 |
|---|---|---|---|
--effort <value> | 仅当前会话，不持久化 | low/medium/high/xhigh/max/ultracode | 覆盖 modelSettings 与 effortLevel 设置 |
CLAUDE_CODE_EFFORT_LEVEL 环境变量 | 进程/shell 会话级 | level 名称或 auto | auto 表示不强制指定，跟随模型默认 |
effortLevel（settings.json） | 持久化默认值，对没有单独保存 level 的模型生效 | low/medium/high/xhigh（不接受 max） | 可写在 user/project/local/managed 设置文件中 |
maxEffortLevel（settings.json） | 对全部或单个模型设置 effort 上限 | 同上 | 用于限制用户能拉到多高的 level |
/effort <value>（会话内命令） | 当前会话，可实时切换 | 同 --effort | 需确认缓存提示后，在本轮下一次请求生效 |
| 约束 | 原因 / 出处 |
|---|---|
effortLevel 设置本身不接受 max | 官方文档明确写出："max 不被 effortLevel 或 modelSettings 中的对应键接受" |
| 并非所有模型都支持全部 5 档 | 官方文档列出各模型的默认档位不同（如 Opus 5.5 默认 medium、Opus 4.7 默认 xhigh），说明支持范围因模型而异 |
ultracode 值需要较新版本 | 官方文档标注该值"需要 Claude Code v2.1.203 或更高版本" |
--effort 设置不持久化 | 官方文档明确说明该 flag 只作用于"本次会话"，不写回配置文件 |
maxEffortLevel 可对用户可选范围加盖 | 该设置用途即"对每个模型或全局设置 effort 上限"，管理员可用它限制成本 |
以下场景摘自官方文档（settings-reference / model-config）中各档位的"何时使用"说明：
low：留给"简短、范围明确、对延迟敏感、且对智能要求不高"的任务，例如简单清理、格式修正。medium：在能接受一定智能损失的前提下降低 token 消耗，适合成本敏感的常规工作。high：在 token 消耗与智能之间取得平衡，是多数模型的默认档位。xhigh：用更高的 token 开销换取更深的推理，适合复杂编码与长链路 agentic 任务。max：面向最需要能力上限的高难度任务，但官方提示"可能出现收益递减，容易过度思考（overthinking）"，建议先测试再大范围采用。ultracode：让 Claude Code 为每个实质性任务自动规划动态 workflow，并以 xhigh 逐条消息推理。--effort 以为永久生效，结果下次启动又变回默认：官方文档明确该 flag "不会持久化"，只对当前会话有效；要长期生效需写入 effortLevel（settings.json）或导出 CLAUDE_CODE_EFFORT_LEVEL。effortLevel 里写 max 不生效：官方文档指出 effortLevel 和 modelSettings 这两个键都不接受 max 作为值，只有 --effort、/effort、CLAUDE_CODE_EFFORT_LEVEL 才能设到 max。--effort max 与 CLAUDE_CODE_EFFORT_LEVEL=max 被忽略、实际生效档位仍是 medium 的情况；该 issue 最终被维护者标记为"not planned / duplicate"关闭，说明该行为已被视为已知问题归档处理，而非官方承诺的行为，具体表现可能随版本变化，升级或改动前建议自行验证当前版本的实际生效档位。