实战 Claude 的 effort 参数：让智能体“按需用力“省 token（含 Opus 4.8 更新）

TL;DR

effort 参数最早随 Claude Opus 4.5（2025 年 11 月）引入，用来控制模型“思考多努力”；在 2026 年 5 月 28 日发布的 Claude Opus 4.8 中，它进一步成熟——effort 控制被带到了 claude.ai 界面，模型也更擅长在长程任务里自我纠错。本文给应用开发者一套可直接套用的思路：用低 effort 跑批量、简单、对延迟敏感的任务，用高 effort 跑复杂推理与长程智能体任务，并通过实测对比成本与质量来挑档位。下面给出可运行的 Python 代码与一套压测脚本骨架。

为什么 effort 值得你关心

对智能体类应用，真正吃成本的往往是模型"想得太多"——在不需要深思的子任务上也输出长篇推理。effort 参数的意义就是把"用多少力"变成一个你能显式控制的旋钮：简单任务调低，省 token、降延迟；难任务调高，换质量。

官方数据给了很实在的参照：在 Opus 4.5 上，medium effort 能在追平此前最强模型表现的同时少用约 76% 的 token。Opus 4.8 延续了这套机制，并在 agentic coding、computer-use（浏览器智能体）等基准上进一步提升——这些能力在高 effort 下最能发挥，但并非每个调用都需要。

注意：参数的确切字段名与取值范围请以你所用 SDK 版本的官方文档为准，下面代码以通用调用形态示意，落地时按文档校正字段名。

实战一：按任务类型分配 effort

核心思路是写一个路由函数，根据任务复杂度选择档位。

importanthropic client=anthropic.Anthropic()# 读取环境变量 ANTHROPIC_API_KEYMODEL="claude-opus-4-8"# effort 起于 4.5，本文用当前最新的 Opus 4.8defclassify_effort(task:str)->str:"""极简启发式：实际可换成一个轻量分类模型或规则集。"""cheap_signals=["格式化","抽取字段","翻译一句","分类","yes/no"]ifany(sintaskforsincheap_signals)orlen(task)<80:return"low"ifany(sintaskforsin["重构","调试","多步","规划","证明"]):return"high"return"medium"defrun(task:str,effort:str|None=None)->str:effort=effortorclassify_effort(task)resp=client.messages.create(model=MODEL,max_tokens=2048,# 若 SDK 暴露的是 thinking/effort 配置，请按文档替换下面这行extra_body={"effort":effort},messages=[{"role":"user","content":task}],)returnresp.content[0].textprint(run("把这段地址抽取成 JSON：北京市海淀区中关村大街1号"))# → lowprint(run("帮我重构这个有竞态条件的多线程下载器并解释每步"))# → high

实战二：用一次压测挑出"够用就好"的档位

不要凭感觉选 effort。对你自己的真实任务集跑一轮对比，看质量是否真的随 effort 提升、提升是否值回 token。

importtime,jsondefbenchmark(tasks:list[str],efforts=("low","medium","high")):rows=[]fortintasks:foreinefforts:t0=time.time()out=run(t,effort=e)rows.append({"task":t[:40],"effort":e,"latency_s":round(time.time()-t0,2),"out_chars":len(out),})print(json.dumps(rows,ensure_ascii=False,indent=2))returnrows# 评分可接入你已有的自动判分（如单测通过率、字段抽取准确率）benchmark(["把这句翻译成英文：今天发布了新模型","为给定函数写出能覆盖边界条件的单元测试"])

判定规则很简单：如果某任务在 low 和 high 下的下游指标几乎一致，就固定用 low；只有当高档位带来可量化的质量提升时，才为它多付 token。

实战三：在智能体循环里动态升档

长程智能体里更聪明的做法，是默认低档跑，只有在遇到失败或不确定时才临时升档重试。

defagent_step(task:str,max_retries:int=1)->str:out=run(task,effort="low")attempt=0whileneeds_more_thinking(out)andattempt<max_retries:out=run(task,effort="high")# 升档重试attempt+=1returnoutdefneeds_more_thinking(out:str)->bool:# 替换成你的真实校验：JSON 是否合法、测试是否通过、是否含"我不确定"return"我不确定"inoutorlen(out)<5

这套"先省后补"的策略，能在绝大多数简单步骤上吃到低成本，只在真正困难的步骤上花算力，往往是性价比最高的组合。

落地清单

先把任务分成廉价/普通/困难三类并默认走低档；再用真实任务集压测，只为带来可量化质量提升的步骤升档；最后在智能体循环里加"失败再升档重试"。务必以官方文档核对 effort 字段名与取值，再上生产。

参考资料

• Anthropic, Introducing Claude Opus 4.8: https://www.anthropic.com/news/claude-opus-4-8
• Anthropic, Effort (Claude API Docs): https://platform.claude.com/docs/en/build-with-claude/effort