Claude 会话推理可中途换挡

Anthropic 在 11 月 12 日为 Claude API 增加了一项颇有实用价值的 Beta 功能：开发者现在可以在同一段会话中途调整 effort，不必重开会话，也不必修改请求最外层的配置。简单说，一段对话可以先用低档快速处理日常问题，遇到复杂分析、代码迁移或多工具任务时，再把 Claude 的推理投入调高。(platform.claude.com)

Per-message effort 是一种按消息改变 Claude 推理投入的控制机制。 它通过会话历史中的 system 消息设置新的 effort，让后续回复使用不同的推理强度，同时尽量保持此前会话前缀和提示缓存不变。

这项更新听起来只是“多了一个参数位置”，但它实际解决的是长会话 Agent 中一个长期存在的工程矛盾：任务难度一直在变化，模型的推理预算却往往只能在会话开始时一次性决定。

effort 不是控制回答字数，而是控制整个回答过程

Effort 是 Claude 用来平衡能力、延迟和 Token 消耗的推理强度设置。 它影响的不只是最终输出了多少文字，还会影响模型是否进行深入思考、调用多少次工具、如何组织工具参数，以及是否对结果进行更多检查。

Anthropic 的官方 effort 文档目前列出了 5 个等级，但并非所有 Claude 模型都支持全部等级：

| Effort 等级 | 核心定位 | 典型场景 | 主要代价 | |---|---|---|---| | low | 最少推理投入，优先速度和成本 | 分类、抽取、改格式、简单问答 | 更容易跳过搜索、验证或边界检查 | | medium | 能力、延迟与成本的平衡档 | 日常开发、明确的工具任务、普通 Agent | 复杂问题可能不够深入 | | high | 为复杂任务投入更多 Token | 调试、知识工作、多步骤分析 | 延迟和输出 Token 通常更高 | | xhigh | 面向长时间、高复杂度任务 | 长程 Coding Agent、深度研究 | Token 消耗明显增加，收益依任务而定 | | max | 不限制推理投入，追求模型能力上限 | 数学、科学探索、关键决策验证 | 最慢、最贵，并可能出现收益递减 |

Effort 调低并不等于让 Claude 少写几段。 Anthropic 明确区分了“回答长度”和“推理投入”：如果希望回答更短，仍然应该在提示词中直接要求简洁；如果希望 Claude 少思考、少调用工具或减少检查步骤，才应该降低 effort。(platform.claude.com)

这也是 effort 和传统 max_tokens 的区别。max_tokens 是输出总量的硬上限，thinking 和最终回答都可能占用这个额度；effort 则决定 Claude 在这个上限内愿意投入多少工作。高 effort 配上过小的 max_tokens，效果类似让一个人认真做题，却在答到一半时强制收卷。

新功能真正改变的是“会话粒度”

过去的 effort 更像会话的固定挡位，现在它开始变成会话中的状态变量。 开发者可以在消息序列中加入一条内容为空的 system 消息，并在其中通过 output_config.effort 指定新等级。

根据 Anthropic 的按消息调节 effort 文档，启用该能力需要满足三个条件：

1. 在 messages 中加入 role 为 system、内容为空的消息；
2. 在这条消息的 output_config.effort 中设置目标等级；
3. 携带 mid-conversation-output-config-2026-07-01 Beta 标识，并保持顶层 effort 不变。

本文不展开 API 调用代码，因为真正需要理解的不是字段怎么拼，而是它在会话历史中的生效规则。

新 effort 不会回头改写已经生成的内容。 如果调节消息紧跟在一条包含新输入的用户消息后面，Claude 对这条用户消息的回复就会使用新等级；如果它被放在助手回复之后，则会从下一条包含新输入的用户消息开始生效。(platform.claude.com)

工具调用场景还有一个容易踩坑的细节：只包含 tool_result 的用户消息不算“新的用户输入”。这意味着，正在进行的工具循环不会因为中途插入 effort 设置而突然换挡，新等级通常要等到下一次真正的用户任务才会生效。

新的 effort 一旦生效，就会持续影响后续回复，直到会话中出现另一条 effort 调节消息。开发者还需要原样保留这条消息的位置，不能在后续请求中随意移动或删除，否则可能破坏模型保存的 thinking 状态。

保住提示缓存，才是这次更新的核心价值

这次更新最有价值的地方不是能换挡，而是换挡时不必把整段会话重新计算一遍。 在长对话和 Agent 工作流里，系统提示词、工具定义、历史消息和背景资料可能已经达到数万甚至数十万 Token；如果每次调整顶层 effort 都导致缓存前缀变化，节省下来的推理成本很可能又被重复输入抵消。

Anthropic 的中途 system message 机制采用“只在会话尾部追加配置”的思路。此前已经进入缓存的前缀保持不变，新的 effort 只从插入位置开始影响后续内容，因此请求仍有机会读取原有的 prompt cache。(platform.claude.com)

| 调节方式 | 控制精度 | 对缓存的影响 | 是否容易审计 | 适合场景 | |---|---|---|---|---| | 修改顶层 effort | 整个请求级别 | 官方建议视为重新开始缓存 | 较清晰 | 不依赖长会话缓存的独立任务 | | Per-message effort | 从指定消息开始持续生效 | 保留此前缓存前缀 | 最清晰，设置会留在历史中 | 长会话、Coding Agent、客服 Agent | | 在提示词里写“仔细思考” | 依赖模型理解 | 通常不会改变此前前缀 | 较难量化 | 临时强调单次任务，但不要求硬控制 | | 自动任务路由 | 应用自行判断并设置 | 取决于实现方式 | 需要额外日志 | 大规模、多类型生产流量 |

不过，提示缓存不会因为有了 per-message effort 就自动生效。应用仍然需要启用 prompt caching，并满足可缓存内容长度等条件；否则缓存读取 Token 仍然可能是 0。这项功能解决的是“换挡会不会破坏缓存前缀”，不是替开发者自动设计缓存策略。

最适合它的不是聊天，而是多阶段 Agent

动态 effort 对普通闲聊的价值有限，但对任务阶段明显变化的 Agent 很有用。 一段真实工作流通常不会从头到尾保持相同难度，因此始终使用 high 或 max，本质上是在用复杂推理的成本处理大量简单步骤。

例如，一个代码 Agent 可能先读取目录、搜索文件名和整理依赖关系，这些步骤通常不需要最深推理；进入数据库迁移设计、并发问题定位或安全审查后，任务复杂度才真正上升。更合理的方案是让前半段运行在 low 或 medium，在关键决策点切到 high 或 xhigh。

一个企业客服 Agent 也可能先处理订单查询、地址修改和政策检索，只有遇到退款争议、多个规则冲突或高价值客户投诉时，才提高 effort。这样做不是让便宜模型接简单任务、昂贵模型接复杂任务，而是让同一个模型在同一段上下文中调整资源投入，避免模型切换导致能力、语气和上下文理解发生变化。

研究型 Agent 则可以在资料抓取和去重阶段使用较低 effort，在证据冲突分析、结论综合和风险检查阶段提高 effort。对于包含数十轮工具调用的长任务，这种阶段式控制比“整段会话全程 max”更接近真实的计算资源调度。

这还不是自动推理路由

Per-message effort 是一个可编程旋钮，不是 Claude 自动判断任务难度的调度器。 Anthropic 提供的是会话内改变设置的通道，什么时候升档、什么时候降档，仍然需要应用自己决定。

这一区别很重要。开发者可以基于用户意图、任务类型、文件规模、工具调用次数或风险等级写规则，也可以用一个较轻量的分类步骤判断任务复杂度，但 Anthropic 并没有承诺 Claude 会自动选择最经济的 effort。

从产品角度看，这既是优点也是缺点。优点是行为可控，生产系统可以明确记录“为何这一轮使用 high”；缺点是团队必须自己建立评测集，测量不同 effort 下的准确率、P95 延迟、工具调用次数和平均输出 Token，而不是简单相信档位越高结果越好。

Anthropic 自己也反复建议开发者做 effort sweep：使用一组固定测试任务，在各等级运行并比较效果，找到质量开始明显下降之前的最低档。尤其是更换 Claude 模型后，相同名称的 effort 不一定代表相同推理量，旧模型上的 high 不能直接等价迁移到新模型的 high。

Beta 阶段仍有明确限制

这项能力目前还不能被当成无条件可用的标准功能。 截至 2026 年 11 月 12 日，它仍需要 Beta 标识，主要面向 Messages API，Managed Agents 暂不支持；不同云平台和模型的支持范围也不完全相同。(platform.claude.com)

官方可用性列表显示，Claude API 当前支持的模型包括 Claude Fable 5.2、Fable 5.1、Mythos 5.2、Mythos 5.1、Opus 5.5、Opus 5、Sonnet 5.5 和 Haiku 5.5，但部分第三方云环境只开放其中一部分模型。开发者不应只检查模型是否支持 effort，还要确认目标平台是否支持“会话中途改变 effort”。

错误处理也需要提前覆盖：

• 没有携带 Beta 标识时，消息级 output_config 会返回 HTTP 400；
• 模型不支持 per-message effort 时，同样会返回 HTTP 400；
• Claude Sonnet 5.5 使用 between_tools thinking 模式时，不能中途更改 effort；
• Claude Haiku 5.5 关闭 thinking 时，也不能中途更改 effort；
• 要逐轮改变这两类模型的 effort，通常需要保持 adaptive thinking。

这些限制说明，effort、thinking 和工具循环不是三个互不相关的开关。它们共同决定 Claude 在一轮任务中如何分配推理资源，配置组合不兼容时，API 会直接拒绝请求，而不是静默降级。

OpenAI Hub 观点：这是 Agent 成本控制从“选模型”走向“调算力”

动态 effort 的方向是对的，而且比单纯再发布一个更快模型更贴近生产需求。 过去团队优化大模型成本，主要依赖模型路由：简单任务交给小模型，复杂任务交给大模型；问题是模型切换会改变输出风格、工具能力和上下文理解，维护成本并不低。

会话内 effort 提供了另一条路线：模型不变，上下文不变，只改变它在当前阶段愿意投入多少推理和工具资源。这更像服务器的动态 CPU 调频，而不是处理到一半更换整台服务器。

但它也不是成本优化的万能按钮。真正有效的生产策略仍然需要任务分级、提示缓存、模型路由和评测体系配合。简单任务长期跑在 high 是浪费，困难任务一律拉到 max 也可能只是增加 Token，而没有带来可测量的质量提升。

对开发者来说，最值得马上做的不是把所有会话改成动态 effort，而是选出一条真实的长工作流，记录各阶段的准确率、延迟、输出 Token、缓存命中量和工具调用次数，再判断哪些阶段值得升档。只有当这些数字能被持续观测，effort 才是资源调度工具，而不只是又一个看起来很高级的参数。

参考来源

• IT之家：Claude API 新增调节 effort 能力 —— 介绍此次 Beta 更新的主要功能、设置方式与生效时机。
• Pydantic AI GitHub Issue：会话中途改变推理 effort —— 讨论 Anthropic per-message effort 的缓存行为、支持模型和框架适配问题。
• Anthropic Skills GitHub：Claude API 能力说明 —— Anthropic 官方 GitHub 仓库中的 Claude API 功能与兼容性资料。