大多数关于 Extended Thinking 的中文资料还在教thinking: {type: enabled, budget_tokens: 10000}。这套写法在Claude Opus 4.7 上直接报错——Anthropic 在 4.6/4.7 这一代把 thinking 接口换了。本文按 2026-05 的实际 API 行为给出三个模型上 thinking 的正确用法、effort 选型、interleaved thinking 在 tool 循环里的关键回填动作以及最容易踩的几个坑。一、半年里 thinking 接口换了一次写法如果你的代码库里还有这样的调用responseclient.messages.create(modelclaude-opus-4-7,# 改成 4.7max_tokens16000,thinking{type:enabled,budget_tokens:10000},# 这行会报错messages[...])把 model 切到 Opus 4.7 之后整个请求会失败。原因是 thinking 接口从显式预算切到了adaptive effort——4.7 已经不再接受老写法。模型老写法 (type: enabledbudget_tokens)新写法 (type: adaptiveeffort)Opus 4.7❌ 不再接受✅ 唯一支持的方式Opus 4.6⚠️ 仍可用但 deprecated✅ 推荐Sonnet 4.6⚠️ 仍可用但 deprecated✅ 推荐Sonnet 4.6 tool 间思考需interleaved-thinking-2025-05-14beta headeradaptive 自动启用也就是说把 Opus 4.7 接进现有 agent 链路时第一步是改 thinking 配置不只是改模型 ID。二、adaptive thinking 是什么老写法让你告诉模型最多花 10000 token 思考。问题是简单问题被强制思考浪费 token复杂问题如果设小了又思考不够adaptive 把这个判断权交给模型由 effort 控制激进程度effort行为适用low简单问题常常完全跳过思考低成本、低延迟medium平衡只在必要时思考一般生产任务high默认几乎总会先思考生产环境推理任务max仅 Opus 4.6/4.7最大思考强度AIME 级数学、长链路 agentAnthropic 内部评测adaptive 的 token 利用率在大量任务上优于固定 budget——因为它不会在简单题上浪费推理也不会在难题上提前收手。三、完整调用代码Opus 4.7唯一支持 adaptiveimportanthropic clientanthropic.Anthropic(api_keysk-你的密钥,base_urlhttps://gw.claudeapi.com)responseclient.messages.create(modelclaude-opus-4-7,max_tokens16000,thinking{type:adaptive},output_config{effort:high},messages[{role:user,content:证明模 4 余 3 的素数有无穷多个。}])forblockinresponse.content:ifblock.typethinking:print(f[思考]{block.thinking[:200]}...)elifblock.typetext:print(f[答案]{block.text})content是按顺序排列的 block 数组先 thinking block推理摘要再 text block最终答案。Sonnet 4.6responseclient.messages.create(modelclaude-sonnet-4-6,max_tokens16000,thinking{type:adaptive},output_config{effort:medium},# Sonnet 不支持 maxmessages[{role:user,content:...}])Sonnet 4.6 上effort: max不被接受——max是 Opus 系列独占的。日常生产用medium关键推理才上high。Opus 4.6两种写法都能用但建议改responseclient.messages.create(modelclaude-opus-4-6,max_tokens16000,thinking{type:adaptive},output_config{effort:high},messages[...])Node.js / TypeScriptimportAnthropicfromanthropic-ai/sdk;constclientnewAnthropic({apiKey:sk-你的密钥});constresponseawaitclient.messages.create({model:claude-opus-4-7,max_tokens:16000,thinking:{type:adaptive},output_config:{effort:high},messages:[{role:user,content:你的复杂推理任务}],});for(constblockofresponse.content){if(block.typethinking)console.log([思考],block.thinking);elseif(block.typetext)console.log([答案],block.text);}四、interleaved thinkingtool 循环里的关键变化Extended Thinking 在 agent 场景下真正强大的地方是允许模型在每次 tool 调用后再思考一轮——也就是 interleaved thinking。老写法在 Sonnet 4.6 上要手动加 beta headerclientanthropic.Anthropic(default_headers{anthropic-beta:interleaved-thinking-2025-05-14})Opus 4.7 和 4.6 的 adaptive 模式下interleaved thinking 默认就开不需要任何 beta header。这是迁移到 4.7 的隐藏收益——agent 链路不再需要管 thinking 旗子。完整 tool-use 循环关键点上一轮的 thinking block 必须原样回填weather_tool{name:get_weather,description:获取指定城市的实时天气,input_schema:{type:object,properties:{city:{type:string}},required:[city]}}# 第一轮模型先思考再决定调 toolresponse_1client.messages.create(modelclaude-opus-4-7,max_tokens8000,thinking{type:adaptive},output_config{effort:high},tools[weather_tool],messages[{role:user,content:巴黎现在适合穿什么给出具体建议。}])# 第二轮把 thinking tool_use block 原样回填加 tool_resultthinking_blocknext(bforbinresponse_1.contentifb.typethinking)tool_use_blocknext(bforbinresponse_1.contentifb.typetool_use)response_2client.messages.create(modelclaude-opus-4-7,max_tokens8000,thinking{type:adaptive},output_config{effort:high},tools[weather_tool],messages[{role:user,content:巴黎现在适合穿什么给出具体建议。},{role:assistant,content:[thinking_block,tool_use_block]# ← 关键},{role:user,content:[{type:tool_result,tool_use_id:tool_use_block.id,content:巴黎 22°C晴微风。}]}])没回填 thinking block 的后果模型失忆把刚才的推理过程丢掉第二轮决策质量明显下降。这是接 agent 链路时最常踩的坑。五、effort 选型到底用哪一档按业务任务类型选不要默认 high任务推荐 effort模型备注简单分类、信息抽取low或不开 thinkingHaiku 4.5 / Sonnet 4.6开 thinking 反而加成本与延迟常规问答、文档生成mediumSonnet 4.6性价比甜点代码 review、PR 分析medium或highSonnet 4.6 / Opus 4.6多步推理但不至于 max复杂算法、架构设计highOpus 4.7需要长链条思考AIME 级数学、最难的 debugmaxOpus 4.7 / 4.6极限场景单次成本明显上升经验法则开 thinking 之前先用普通模式跑一遍。普通模式答得不错就不开如果有明显问题漏约束、逻辑跳步、答非所问再上 thinking。盲目默认 high 是企业 AI 账单失控的常见成因之一。六、容易踩的坑坑 1thinking 与 prompt caching 的隐藏耦合prompt caching 的 cache key 包含 thinking 配置。这意味着# 第一次建缓存client.messages.create(thinking{type:adaptive},output_config{effort:medium},system[{type:text,text:LONG_SYSTEM,cache_control:{type:ephemeral}}],)# 第二次把 effort 改成 high → 缓存失效重新计费client.messages.create(thinking{type:adaptive},output_config{effort:high},# 改了system[{type:text,text:LONG_SYSTEM,cache_control:{type:ephemeral}}],)实战建议同一条工作流内 effort 固定不要在 A/B 测试时改 effort 又指望 cache 命中。坑 2thinking block 不会跨轮保留模型每次返回 thinking block但下一轮请求时这些 block 默认不在上下文里——除非像第四节那样手动回填。多轮对话忽略这点模型会反复重新思考已经想过的事。坑 3thinking 计费是全过程不是可见摘要拿到的block.thinking是思考摘要——计费按完整内部思考过程可能是摘要的 3-5 倍。看起来 200 字的 thinking block背后可能消耗了 5000 token。月底账单和屏幕估算的不一样原因常在这里。坑 4thinking 与几个采样参数互斥开启 thinking 时不能用temperature≠ 1 或top_ktop_p 0.95forced tool usetool_choice指定具体工具名response prefill用 assistant 消息预填模型回复迁移时要先拿掉这些参数。七、迁移 checklist从老代码到 adaptive代码层把thinking: {type: enabled, budget_tokens: N}改成thinking: {type: adaptive}加output_config: {effort: ...}按选型表选档移除interleaved-thinking-2025-05-14beta headeradaptive 自动开检查temperature、top_k、tool_choice、prefill 是否与 thinking 冲突工程层多轮对话的 thinking block 回填逻辑prompt caching 的 effort 一致性账单告警把 thinking token 与可见输出 token 分开监控测试层同一 prompt 在 effort: low / medium / high 三档下跑一遍记录质量与 token 消耗agent 链路tool_result 回填后第二轮 thinking 是否仍然合理八、小结做对一件事就够了默认用 adaptive按任务类型选 effort不要一上来就 high。Opus 4.7 的 adaptive thinking 是过去半年 Anthropic 在 thinking 接口上做得最值得迁移的改动——既减少了 boilerplate不再要 beta header又把 token 利用率交给了模型自己判断。但代价是老代码必须改写迁移 checklist 跑一遍才能稳。完整模型定价与控制台见 claudeapi.com。官方文档Adaptive Thinking · Extended Thinking。
Claude Extended Thinking 实战：Opus 4.7 已经废弃 budget_tokens，新写法和迁移避坑全梳理
大多数关于 Extended Thinking 的中文资料还在教thinking: {type: enabled, budget_tokens: 10000}。这套写法在Claude Opus 4.7 上直接报错——Anthropic 在 4.6/4.7 这一代把 thinking 接口换了。本文按 2026-05 的实际 API 行为给出三个模型上 thinking 的正确用法、effort 选型、interleaved thinking 在 tool 循环里的关键回填动作以及最容易踩的几个坑。一、半年里 thinking 接口换了一次写法如果你的代码库里还有这样的调用responseclient.messages.create(modelclaude-opus-4-7,# 改成 4.7max_tokens16000,thinking{type:enabled,budget_tokens:10000},# 这行会报错messages[...])把 model 切到 Opus 4.7 之后整个请求会失败。原因是 thinking 接口从显式预算切到了adaptive effort——4.7 已经不再接受老写法。模型老写法 (type: enabledbudget_tokens)新写法 (type: adaptiveeffort)Opus 4.7❌ 不再接受✅ 唯一支持的方式Opus 4.6⚠️ 仍可用但 deprecated✅ 推荐Sonnet 4.6⚠️ 仍可用但 deprecated✅ 推荐Sonnet 4.6 tool 间思考需interleaved-thinking-2025-05-14beta headeradaptive 自动启用也就是说把 Opus 4.7 接进现有 agent 链路时第一步是改 thinking 配置不只是改模型 ID。二、adaptive thinking 是什么老写法让你告诉模型最多花 10000 token 思考。问题是简单问题被强制思考浪费 token复杂问题如果设小了又思考不够adaptive 把这个判断权交给模型由 effort 控制激进程度effort行为适用low简单问题常常完全跳过思考低成本、低延迟medium平衡只在必要时思考一般生产任务high默认几乎总会先思考生产环境推理任务max仅 Opus 4.6/4.7最大思考强度AIME 级数学、长链路 agentAnthropic 内部评测adaptive 的 token 利用率在大量任务上优于固定 budget——因为它不会在简单题上浪费推理也不会在难题上提前收手。三、完整调用代码Opus 4.7唯一支持 adaptiveimportanthropic clientanthropic.Anthropic(api_keysk-你的密钥,base_urlhttps://gw.claudeapi.com)responseclient.messages.create(modelclaude-opus-4-7,max_tokens16000,thinking{type:adaptive},output_config{effort:high},messages[{role:user,content:证明模 4 余 3 的素数有无穷多个。}])forblockinresponse.content:ifblock.typethinking:print(f[思考]{block.thinking[:200]}...)elifblock.typetext:print(f[答案]{block.text})content是按顺序排列的 block 数组先 thinking block推理摘要再 text block最终答案。Sonnet 4.6responseclient.messages.create(modelclaude-sonnet-4-6,max_tokens16000,thinking{type:adaptive},output_config{effort:medium},# Sonnet 不支持 maxmessages[{role:user,content:...}])Sonnet 4.6 上effort: max不被接受——max是 Opus 系列独占的。日常生产用medium关键推理才上high。Opus 4.6两种写法都能用但建议改responseclient.messages.create(modelclaude-opus-4-6,max_tokens16000,thinking{type:adaptive},output_config{effort:high},messages[...])Node.js / TypeScriptimportAnthropicfromanthropic-ai/sdk;constclientnewAnthropic({apiKey:sk-你的密钥});constresponseawaitclient.messages.create({model:claude-opus-4-7,max_tokens:16000,thinking:{type:adaptive},output_config:{effort:high},messages:[{role:user,content:你的复杂推理任务}],});for(constblockofresponse.content){if(block.typethinking)console.log([思考],block.thinking);elseif(block.typetext)console.log([答案],block.text);}四、interleaved thinkingtool 循环里的关键变化Extended Thinking 在 agent 场景下真正强大的地方是允许模型在每次 tool 调用后再思考一轮——也就是 interleaved thinking。老写法在 Sonnet 4.6 上要手动加 beta headerclientanthropic.Anthropic(default_headers{anthropic-beta:interleaved-thinking-2025-05-14})Opus 4.7 和 4.6 的 adaptive 模式下interleaved thinking 默认就开不需要任何 beta header。这是迁移到 4.7 的隐藏收益——agent 链路不再需要管 thinking 旗子。完整 tool-use 循环关键点上一轮的 thinking block 必须原样回填weather_tool{name:get_weather,description:获取指定城市的实时天气,input_schema:{type:object,properties:{city:{type:string}},required:[city]}}# 第一轮模型先思考再决定调 toolresponse_1client.messages.create(modelclaude-opus-4-7,max_tokens8000,thinking{type:adaptive},output_config{effort:high},tools[weather_tool],messages[{role:user,content:巴黎现在适合穿什么给出具体建议。}])# 第二轮把 thinking tool_use block 原样回填加 tool_resultthinking_blocknext(bforbinresponse_1.contentifb.typethinking)tool_use_blocknext(bforbinresponse_1.contentifb.typetool_use)response_2client.messages.create(modelclaude-opus-4-7,max_tokens8000,thinking{type:adaptive},output_config{effort:high},tools[weather_tool],messages[{role:user,content:巴黎现在适合穿什么给出具体建议。},{role:assistant,content:[thinking_block,tool_use_block]# ← 关键},{role:user,content:[{type:tool_result,tool_use_id:tool_use_block.id,content:巴黎 22°C晴微风。}]}])没回填 thinking block 的后果模型失忆把刚才的推理过程丢掉第二轮决策质量明显下降。这是接 agent 链路时最常踩的坑。五、effort 选型到底用哪一档按业务任务类型选不要默认 high任务推荐 effort模型备注简单分类、信息抽取low或不开 thinkingHaiku 4.5 / Sonnet 4.6开 thinking 反而加成本与延迟常规问答、文档生成mediumSonnet 4.6性价比甜点代码 review、PR 分析medium或highSonnet 4.6 / Opus 4.6多步推理但不至于 max复杂算法、架构设计highOpus 4.7需要长链条思考AIME 级数学、最难的 debugmaxOpus 4.7 / 4.6极限场景单次成本明显上升经验法则开 thinking 之前先用普通模式跑一遍。普通模式答得不错就不开如果有明显问题漏约束、逻辑跳步、答非所问再上 thinking。盲目默认 high 是企业 AI 账单失控的常见成因之一。六、容易踩的坑坑 1thinking 与 prompt caching 的隐藏耦合prompt caching 的 cache key 包含 thinking 配置。这意味着# 第一次建缓存client.messages.create(thinking{type:adaptive},output_config{effort:medium},system[{type:text,text:LONG_SYSTEM,cache_control:{type:ephemeral}}],)# 第二次把 effort 改成 high → 缓存失效重新计费client.messages.create(thinking{type:adaptive},output_config{effort:high},# 改了system[{type:text,text:LONG_SYSTEM,cache_control:{type:ephemeral}}],)实战建议同一条工作流内 effort 固定不要在 A/B 测试时改 effort 又指望 cache 命中。坑 2thinking block 不会跨轮保留模型每次返回 thinking block但下一轮请求时这些 block 默认不在上下文里——除非像第四节那样手动回填。多轮对话忽略这点模型会反复重新思考已经想过的事。坑 3thinking 计费是全过程不是可见摘要拿到的block.thinking是思考摘要——计费按完整内部思考过程可能是摘要的 3-5 倍。看起来 200 字的 thinking block背后可能消耗了 5000 token。月底账单和屏幕估算的不一样原因常在这里。坑 4thinking 与几个采样参数互斥开启 thinking 时不能用temperature≠ 1 或top_ktop_p 0.95forced tool usetool_choice指定具体工具名response prefill用 assistant 消息预填模型回复迁移时要先拿掉这些参数。七、迁移 checklist从老代码到 adaptive代码层把thinking: {type: enabled, budget_tokens: N}改成thinking: {type: adaptive}加output_config: {effort: ...}按选型表选档移除interleaved-thinking-2025-05-14beta headeradaptive 自动开检查temperature、top_k、tool_choice、prefill 是否与 thinking 冲突工程层多轮对话的 thinking block 回填逻辑prompt caching 的 effort 一致性账单告警把 thinking token 与可见输出 token 分开监控测试层同一 prompt 在 effort: low / medium / high 三档下跑一遍记录质量与 token 消耗agent 链路tool_result 回填后第二轮 thinking 是否仍然合理八、小结做对一件事就够了默认用 adaptive按任务类型选 effort不要一上来就 high。Opus 4.7 的 adaptive thinking 是过去半年 Anthropic 在 thinking 接口上做得最值得迁移的改动——既减少了 boilerplate不再要 beta header又把 token 利用率交给了模型自己判断。但代价是老代码必须改写迁移 checklist 跑一遍才能稳。完整模型定价与控制台见 claudeapi.com。官方文档Adaptive Thinking · Extended Thinking。
