Claude API 上线的 effort 调节功能，核心就是开发者可以直接通过 effort 参数控制模型思考深度、推理投入的 token 数量，在同一个模型上灵活切换响应精细度和调用成本、响应速度，不用更换模型就能适配不同业务场景。简单来说，你想要模型深度思考、仔细推导，就调高 effort 等级；想要快速返回简短回答、节省 token 开销，就调低 effort 等级。
一、effort 参数等级说明
一共提供 5 个等级，不同等级对应的模型行为不一样：
| 等级 | 模型表现 | 适用场景 |
|---|---|---|
| max | 最大思考深度，不限制思考 token 长度，尽可能完整推演 | 复杂数学推理、长篇逻辑分析、方案深度论证 |
| xhigh | 比 high 更强的深度探索，推理范围更广 | 多步骤复杂任务、多方案对比分析 |
| high | 大部分模型默认等级，复杂问题会进行深度推理 | 通用复杂业务，代码编写、长文分析 |
| medium | 中等推理，简单问题会跳过思考 | 普通问答、常规内容总结，Opus5.5、Haiku5.5 默认值 |
| low | 最小化思考，优先保证响应速度 | 简单查询、短指令、高频轻量接口调用 |
二、支持 API 与设置方式
- Messages API：在请求体output_config里配置effort字段，顶层 effort 正式可用，不需要 beta 请求头；单条消息单独设置 effort 目前还处于 beta 测试阶段，使用时需要带上对应的 beta 头部。
- Managed Agents：可以在 agent 模型对象中设置 effort，也可以在会话级别覆盖修改 effort 参数，不填参数时会自动使用该模型默认 effort 等级。
三、接入使用步骤
- 确认使用支持 effort 参数的最新 Claude 模型，旧版本模型不一定全部支持全部 effort 等级。
- 在 API 请求体增加output_config配置项，填入想要的 effort 等级字符串。
- 发送请求，模型就会按照指定 effort 等级控制思考深度。
- 对话中途想切换 effort（beta 功能）：发送一条空内容的 system 消息，在这条消息内写入新的 output_config.effort。
示例简易请求片段：
{
"model": "claude-fable-5-1",
"max_tokens": 4096,
"output_config": {"effort": "high"},
"messages": [...]
}
四、使用注意事项
- effort 越高，模型消耗 token 越多，接口费用更高，延迟也会增加。
- 不是固定强制开启思考，每个等级下，模型会自主判断当前请求是否需要启动思考；工具调用链路里，处理工具返回结果的后续请求可能会跳过思考。
- 部分模型不支持 max、xhigh 等级，传入不支持等级会直接报错。
五、总结
effort 调节功能把模型推理深度做成可配置项，不用切换不同大模型，只用一个模型，通过参数就能平衡推理质量、响应速度与调用成本，是控制 Claude 自适应思考能力的推荐方式，适合开发多场景 AI 接口服务。
【相关 FAQ】
问题 1：Claude API effort 调节功能有几个等级？
回答 1：Claude API effort 调节功能一共有 low、medium、high、xhigh、max 五个等级，不同等级对应不同的思考深度和 token 消耗。
问题 2：Claude API effort 参数是正式功能还是 beta 功能？
回答 2：顶层全局 effort 参数已经正式上线，不需要 beta 请求头；而对话内单条消息单独修改 effort 属于 beta 功能，需要配置对应的 beta 头部才能使用。
问题 3：设置 Claude API effort 为 low 会有什么效果？
回答 3：effort 设置为 low 时，Claude 会最小化思考环节，优先提升响应速度，简单问题直接跳过推理，适合高频、简短查询类场景，能够减少 token 消耗。
【参考资料】
[2026-07-01]（Per-message effort - Claude Platform Docs）Anthropic Claude 官方文档
[未知]（Effort - Claude Platform Docs）Anthropic Claude 官方文档
[未知]（Steering thinking - Claude Platform Docs）Anthropic Claude 官方文档
【免责声明】
本文内容仅基于 Claude 官方公开文档整理，供技术学习参考。API 功能、参数、可用模型、计费规则可能随时调整，实际开发请以 Anthropic Claude 平台最新官方文档为准。本内容不构成任何技术落地承诺与商业建议。