Effort

effort（努力程度）参数让您可以控制 Claude 在响应请求时花费多少令牌。您可以使用单一模型在响应的全面性与令牌效率之间进行权衡。顶层 effort 参数在所有受支持的模型上均可使用，无需 beta 标头。按消息设置的 effort 目前处于 beta 阶段。

设置 effort 级别

在请求中设置 output_config.effort。以下示例以 medium effort 运行一个请求并打印响应文本。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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 的工作原理

大多数 Claude 模型默认使用 high effort，会花费所需的尽可能多的令牌以获得出色的结果；Claude Opus 5.5 和 Claude Haiku 5.5 默认为 medium。您可以将 effort 级别提高到 max 以获得绝对最高的能力，也可以降低它以更节省令牌使用，在接受一定能力下降的同时优化速度和成本。

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

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

由于 effort 适用于每个输出令牌，因此无论是否启用思考，它都能发挥作用。较低的 effort 也意味着更少、更简洁的工具调用。

effort 级别

并非所有支持 max 的模型都支持 xhigh。

以下针对各模型的建议在与此表不同之处优先于此表。

Claude Fable 5.1 的推荐 effort 级别

Claude Fable 5.1 支持全部五个 effort 级别。从默认值 high 开始。对于对能力最敏感的智能体和编码工作，可提升到 xhigh 或 max；对于常规或对延迟敏感的工作，一旦您的评估表明质量得以保持，可降低到 medium 或 low。在 high 及以上级别，请设置较大的 max_tokens。它是总输出（思考加响应文本）的硬性上限。同样的建议也适用于 Claude Mythos 5.1。请参阅为 Claude Fable 5.1 编写提示。

Claude Fable 5.1 还支持通过按消息设置的 output_config 在对话中途更改 effort，这样可以保留提示缓存。

Claude Fable 5 的推荐 effort 级别

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

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

Claude Opus 5.5 的推荐 effort 级别

Claude Opus 5.5 支持全部五个 effort 级别，且默认值为 medium（Claude Opus 5 及更早的 Opus 模型默认为 high，因此省略 effort 的请求会比在 Claude Opus 5 上低一个级别运行）。自适应思考始终开启且无法关闭，因此 effort 是控制模型推理量以及请求成本的主要方式。请在您自己的评估上进行 effort 扫描，而不是沿用早期模型的设置，并在较高级别下设置较大的 max_tokens：它是总输出（思考加响应文本）的硬性上限。设置了 thinking: {"type": "disabled"} 的请求在任何 effort 级别下都会返回 400 错误。Claude Opus 5.5 还支持通过按消息设置的 output_config 在对话中途更改 effort，这样可以保留提示缓存。请参阅为 Claude Opus 5.5 编写提示。

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 Opus 5 还支持通过按消息设置的 output_config 在对话中途更改 effort，这样可以保留提示缓存。在 Amazon Bedrock 上，Claude Opus 5 不支持按消息设置 effort。

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 4.7 的推荐 effort 级别

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

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

与 Claude Opus 4.6 相比，Claude Opus 4.7 也更严格地遵循 effort 级别，尤其是在 low 和 medium 级别。在较低的 effort 级别下，模型会将工作范围限定在所要求的内容上，而不是做超出要求的事情。如果您在使用 Claude Opus 4.7 处理复杂问题时观察到推理较浅，请提高 effort，而不是通过提示来绕过。如果出于延迟考虑必须保持较低的 effort，请添加有针对性的指导，例如"This task involves multistep reasoning. Think carefully before responding."

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

Claude Sonnet 5.5 的推荐 effort 级别

Claude Sonnet 5.5 支持全部五个 effort 级别，在 Claude API 上默认值为 high。它的级别经过重新校准，因此同一级别产生的思考量与 Claude Sonnet 5 上相同级别并不相同。请在您的评估上重新进行 effort 扫描，而不是沿用您在 Claude Sonnet 5 上使用的设置。除非您的工作负载是智能体型或对延迟敏感，否则请从 high 开始。对于智能体编码和多步骤工具使用，对于规格明确的任务从 medium 开始，对于更难或更长的任务则改用 high。对于聊天和其他对延迟敏感的工作，从 medium 或 low 开始。仅在您的评估显示质量有所提升时才使用 xhigh 或 max。设置 max_tokens 时请为思考和回复留出空间。即使不返回思考内容，思考也会计入 max_tokens。对于智能体编码，请将 max_tokens 设置为模型的最大值 128,000，并对响应进行流式传输。

要关闭前置思考，请发送 thinking: {"type": "between_tools"} 而不是 "disabled"。这是 Claude Sonnet 5.5 上最低的思考设置，适用于 low、medium 和 high effort。在 xhigh 或 max 下，使用它的请求会返回 400 错误，因此在这些级别请使用自适应思考：省略 thinking 字段或发送 thinking: {"type": "adaptive"}。请参阅无预先思考运行。

Claude Sonnet 5.5 还支持通过按消息设置的 output_config 在对话中途更改 effort，这样可以保留提示缓存。使用 between_tools 时，effort 无法在对话中途更改：与当前生效级别不同的按消息 output_config.effort 会返回 400 错误。要按轮次改变 effort，请使用自适应思考。请参阅为 Claude Sonnet 5.5 编写提示。

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 Haiku 5.5 的推荐 effort 级别

Claude Haiku 5.5 支持全部五个 effort 级别，在 Claude API 和 Claude Code 中默认值为 medium。effort 是控制模型思考量的主要方式，并由此影响质量、延迟和成本。对于大多数工作（包括智能体编码），从 medium 开始。对于聊天、简短的工具任务以及简单的高吞吐量请求，使用最便宜、最快的级别 low。在较长的智能体提示中，模型在 low 下更有可能跳过搜索、过早停止或跳过检查。对于知识工作、较长的智能体任务和严格的指令遵循，使用 high。仅在您的评估显示质量有所提升时才使用 xhigh 或 max，并在性能、成本和速度方面将其与 Claude Sonnet 5.5 进行比较。思考默认开启并计入 max_tokens，因此请为其留出空间。请参阅为 Claude Haiku 5.5 编写提示。

要减少思考，请降低 effort 级别。您也可以在 high 或更低的 effort 下发送 thinking: {"type": "disabled"}。在 xhigh 或 max 下，它会返回 400 错误，因此在这些级别请使用自适应思考：省略 thinking 字段或发送 thinking: {"type": "adaptive"}。

在 Claude API 和 Google Cloud 上，Claude Haiku 5.5 还支持通过按消息设置的 output_config 在对话中途更改 effort，这样可以保留提示缓存。使用 thinking: {"type": "disabled"} 时，effort 无法在对话中途更改：与当前生效级别不同的按消息 output_config.effort 会返回 400 错误。要按轮次改变 effort，请使用自适应思考。

effort 与工具使用

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

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

较高的 effort 级别可能会：

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

effort 与思考

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

在较高的努力程度下，Claude 更容易进行思考，且思考时间更长。在工具使用循环中，仅处理工具结果的后续请求在任何级别下仍可能跳过思考。在较低的级别下，Claude 对于较简单的问题可能会完全跳过思考。有关这两种控制方式如何协同工作的完整指导，请参阅思考与努力程度。

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

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

在对话中途更改 effort

您可以通过两种方式以不同的 effort 级别运行对话的后续轮次。在 Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Opus 5、Claude Sonnet 5.5 和 Claude Haiku 5.5 上，使用按消息的 effort 更改，这样可以保留提示缓存。在其他模型上，在下一个请求中设置新的顶层值，这会使缓存重新开始。

按消息设置的 effort（beta）

按消息设置 effort 目前处于 beta 阶段。在 Claude API 和 Google Cloud 上，它适用于 Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Opus 5、Claude Sonnet 5.5 和 Claude Haiku 5.5。在 Amazon Bedrock 上，它适用于 Claude Fable 5.1、Claude Mythos 5.1 和 Claude Opus 5.5。它需要 beta 标头 mid-conversation-output-config-2026-07-01。使用 Amazon Bedrock InvokeModel API 时，它适用于 Claude Fable 5.1 和 Claude Opus 5.5，并且您需要改为在请求体的 anthropic_beta 数组中发送该值。

如果没有该 beta 值，按消息设置的 output_config 会返回 400 错误：messages.N.output_config: Extra inputs are not permitted，其中 N 是 system 消息在 messages 中的索引。带有该 beta 值时，不支持按消息设置 effort 的模型（包括 Claude Fable 5）会返回 400 错误：output_config.effort requires a model that supports per-turn effort; this model does not。在 Amazon Bedrock 上，这些模型以及 Claude Opus 5 会改为返回 Extra inputs are not permitted 错误。在使用 thinking: {"type": "between_tools"} 的 Claude Sonnet 5.5 上，以及使用 thinking: {"type": "disabled"} 的 Claude Haiku 5.5 上，effort 无法在对话中途更改：与当前生效级别不同的按消息 output_config.effort 会返回 400 错误。要按轮次改变 effort，请使用自适应思考。

添加一条 role: "system" 消息，其 content 为空，并在 output_config.effort 中设置新级别。新级别从下一个 user 轮次开始生效，并一直保持到后续消息更改它为止。该消息之前的所有内容保持不变，因此缓存的前缀仍然匹配。

以下示例从 high 开始，然后在一个常规的后续问题中降低到 low：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=4096,
    output_config={"effort": "high"},
    messages=[
        {
            "role": "user",
            "content": "Plan a migration from SQLite to PostgreSQL in three short steps.",
        },
        {
            "role": "assistant",
            "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.",
        },
        # 仅含 effort 的系统消息：新级别从下一个用户轮次起生效。
        {"role": "system", "content": [], "output_config": {"effort": "low"}},
        {"role": "user", "content": "Summarize the plan in one sentence."},
    ],
    betas=["mid-conversation-output-config-2026-07-01"],
)

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

仅包含 effort 的系统消息不携带任何文本，因此对话中途系统消息的放置规则不适用。它可以出现在 messages 中的任何位置，包括作为第一个条目，或位于 assistant 轮次与下一个 user 轮次之间。取值为级别名称（low、medium、high、xhigh 和 max）。

在 Claude Fable 5.1 上，请优先使用这种形式，而不是在请求之间更改顶层值。顶层更改会重新开始缓存，并且对模型的引导也不太可靠：模型之前的回复是在先前级别下编写的，它倾向于与这些回复保持一致。

在下一个请求中设置顶层 effort

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

最佳实践

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

后续步骤

Compatibility