Effort

"Effort"（努力程度）参数让您可以控制 Claude 在响应请求时花费的令牌数量。您可以通过单个模型在响应完整性和令牌效率之间进行权衡。effort 参数在所有受支持的模型上均可用，无需 beta 标头。



Effort 的工作原理

默认情况下，Claude 使用 high（高）effort，根据需要花费尽可能多的令牌以获得出色的结果。您可以将 effort 级别提高到 max 以获得绝对最高的能力，或降低级别以更保守地使用令牌，在接受一定能力降低的同时优化速度和成本。

effort 参数会影响响应中的所有令牌，包括：

• 文本响应和解释
• 工具调用和函数参数
• 思考（当激活时）

这种方法有两个主要优势：

1. 它不需要启用思考。
2. 它可以影响所有令牌消耗，包括工具调用。例如，较低的 effort 意味着 Claude 会进行更少的工具调用。这为效率控制提供了更大的灵活度。



Effort 级别

xhigh 是较新的级别；某些支持 max 的模型不支持 xhigh。



Claude Sonnet 5 的推荐 effort 级别

Claude Sonnet 5 在 Claude API 和 Claude Code 上默认使用 high effort。

• High effort（默认）： 适用于质量比速度或成本更重要的复杂推理、编码和智能体任务。
• Xhigh effort： 适用于最困难的编码和智能体任务。请参阅为 Claude Sonnet 5 编写提示。
• Medium effort： 从默认级别降级以节省成本。与 high effort 下的 Claude Sonnet 4.6 相当。
• Low effort： 适用于高吞吐量或对延迟敏感的工作负载。适用于优先考虑更快响应时间的聊天和非编码用例。
• Max effort： 适用于需要绝对最高能力且对令牌消耗没有限制的任务。



Claude Sonnet 4.6 的推荐 effort 级别

Sonnet 4.6 默认使用 high effort。使用 Sonnet 4.6 时请显式设置 effort，以避免意外的延迟：

• Medium effort（推荐默认值）：对大多数应用而言，在速度、成本和性能之间达到最佳平衡。适用于智能体编码、工具密集型工作流和代码生成。
• Low effort： 适用于高吞吐量或对延迟敏感的工作负载。适用于优先考虑更快响应时间的聊天和非编码用例。
• High effort： 适用于质量比速度或成本更重要的复杂推理和任务。
• Max effort： 适用于需要绝对最高能力且对令牌消耗没有限制的任务。



Claude Opus 4.7 的推荐 effort 级别

对于编码和智能体用例，从 xhigh 开始，对于大多数对智能要求较高的工作负载，将 high 作为最低级别。对于成本敏感的工作负载，降级到 medium；仅当您的评估显示在 xhigh 下仍有可衡量的提升空间时，才升级到 max。

API 默认值为 high。要使用 xhigh，请显式设置 effort；您传递的值会覆盖默认值。

Claude Opus 4.7 对 effort 级别的遵循也比 Claude Opus 4.6 更严格，尤其是在 low 和 medium 级别。在较低的 effort 级别下，模型会将其工作范围限定在所要求的内容上，而不会做超出要求的事情。如果您在使用 Claude Opus 4.7 处理复杂问题时观察到推理较浅，请提高 effort 而不是通过提示来绕过。如果您必须为了延迟而保持较低的 effort，请添加针对性的指导，例如"此任务涉及多步推理。请在回答前仔细思考。"

在 xhigh 或 max effort 下运行 Claude Opus 4.7 时，请设置较大的 max_tokens，以便模型有足够的空间在子智能体和工具调用之间进行思考和行动。从 64k 令牌开始并据此调整是一个合理的默认值。



Claude Opus 4.8 的推荐 effort 级别

Claude Opus 4.7 的指南同样适用于 Claude Opus 4.8。对于编码和智能体用例，从 xhigh 开始，对于大多数其他对智能要求较高的工作负载使用 high，仅当您通过评估确认较低级别能够保持质量时，才降级到 medium 或 low。

API 默认值为 high。显式设置 effort 以使用不同的级别；您传递的值会覆盖默认值。

在 xhigh 或 max effort 下运行 Claude Opus 4.8 时，请设置较大的 max_tokens，以便模型有足够的空间在子智能体和工具调用之间进行思考和行动。从 64k 令牌开始并据此调整是一个合理的默认值。



Claude Opus 5 的推荐 effort 级别

Claude Opus 5 支持全部五个 effort 级别。从默认的 high 开始，并根据您的评估进行调整：对于要求较高的编码和智能体工作，升级到 xhigh；当任务值得不受限制地消耗令牌时，升级到 max；在您的评估显示质量能够保持的情况下，可以大量使用 low 和 medium 作为控制令牌成本和响应时间的主要手段。如果您沿用了早期模型的 effort 设置，请在您的评估上重新进行 effort 扫描，而不是直接复用。

Effort 控制的是思考量，而非可见的响应长度：在 Claude Opus 5 上，更改 effort 并不能可靠地缩短响应，因此请改为通过提示控制长度。

API 默认值为 high。显式设置 effort 以使用不同的级别；您传递的值会覆盖默认值。

在 Claude Opus 5 上，xhigh 或 max effort 下无法禁用思考：在这些级别下设置 thinking: {"type": "disabled"} 的请求会返回 400 错误。请参阅 Effort 与思考。

在 xhigh 或 max effort 下运行 Claude Opus 5 时，请设置较大的 max_tokens，以便模型有足够的空间在子智能体和工具调用之间进行思考和行动。从 64k 令牌开始并据此调整是一个合理的默认值。



Claude Fable 5 的推荐 effort 级别

Effort 是在 Claude Fable 5 上权衡智能、延迟和成本的主要控制手段。对于大多数任务，从默认的 high 开始，对于对能力最敏感的工作负载使用 xhigh，对于常规工作降级到 medium 或 low。Claude Fable 5 上较低的 effort 设置仍然表现良好，通常超过先前模型在 xhigh 下的表现。在 high 和 xhigh 下，请设置较大的 max_tokens：它是总输出（思考加响应文本）的硬性限制。请参阅成本控制。

如果任务完成但耗时超过必要时间，或者您希望获得更快、更具交互性的工作方式，请降低 effort。同样的建议也适用于 Claude Mythos 5。有关更完整的指南，请参阅为 Claude Fable 5 编写提示。



基本用法

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

for block in response.content:
    if block.type == "text":
        print(block.text)



何时调整 effort 参数

• 当您需要绝对最高能力且没有任何限制时，使用 max effort：最彻底的推理和最深入的分析。在 Claude 4.6 及更高版本的模型以及 Claude Mythos Preview 上可用。
• 对于需要扩展探索的高级编码和复杂智能体工作（如重复工具调用和详细搜索），使用 xhigh effort。在 Claude Fable 5、Claude Mythos 5、Claude Opus 5、Claude Opus 4.8、Claude Opus 4.7 和 Claude Sonnet 5 上可用。
• 对于复杂推理、细致分析、困难的编码问题，或任何质量比速度或成本更重要的任务，使用 high effort（默认值）。
• 当您希望获得稳定的性能而不需要 high effort 的全部令牌消耗时，使用 medium effort 作为平衡选项。
• 当您优化速度（因为 Claude 用更少的令牌回答）或成本时，使用 low effort。例如，简单的分类任务、快速查询，或边际质量提升不足以证明额外延迟或花费合理性的高吞吐量用例。



Effort 与工具使用

使用工具时，effort 参数会同时影响工具调用周围的解释和工具调用本身。较低的 effort 级别倾向于：

• 将多个操作合并为更少的工具调用
• 进行更少的工具调用
• 直接采取行动而不加前言
• 完成后使用简洁的确认消息

较高的 effort 级别可能会：

• 进行更多的工具调用
• 在采取行动前解释计划
• 提供详细的变更摘要
• 包含更全面的代码注释



Effort 与思考

thinking 参数控制 Claude 是否在回答前在思考块中进行思考；effort 参数控制 Claude 在整个响应中投入的工作量，在自适应模式下，这包括思考的频率和深度。不要将 adaptive 作为 effort 的值传递：adaptive 是一种思考模式，而不是一个努力程度级别。

在较高的 effort 级别下，Claude 会对大多数请求进行思考，且思考时间更长；在较低级别下，对于较简单的问题，它可以完全跳过思考。有关这两种控制方式如何协同工作的完整指南，请参阅思考与 effort。

在 Claude Opus 4.5（唯一支持 effort 的仅扩展思考模型）上，它与 budget_tokens 协同工作：为您的任务设置 effort 级别，然后根据任务所需的推理深度设置思考令牌预算。

有关各模型的思考可用性，请参阅各模型配置表。无论是否启用思考，effort 都可以正常工作；请参阅 Effort 的工作原理。



在对话中途更改 effort

output_config.effort 是请求级别的设置：每个请求都携带自己的值，因此要在对话的后续部分以不同的 effort 级别运行，请在下一个请求中设置新值。effort 级别适用于整个请求。由于 effort 会影响渲染的提示，在请求之间更改它不会保留早期轮次的缓存前缀；如果您在长会话中依赖提示缓存，请在开始时选择一个 effort 级别并保持不变。



最佳实践

1. 显式设置 effort： API 默认为 high，但正确的起点取决于您的模型和工作负载。
2. 对速度敏感或简单的任务使用 low： 当延迟很重要或任务较为简单时，low effort 可以显著减少响应时间和成本。
3. 测试您的用例： effort 级别的影响因任务类型而异。在部署之前，请在您的特定用例上评估性能。
4. 考虑动态 effort： 根据任务复杂度调整 effort。简单查询可能适合 low effort，而智能体编码和复杂推理则受益于 high effort。在单个对话中变更之前，请参阅下一条。
5. 在缓存的对话中保持 effort 不变： 在请求之间更改 effort 值会使提示缓存失效，因此请在不同工作负载之间变更 effort，而不是在依赖缓存命中的对话内部变更。请参阅思考与提示缓存。



后续步骤