思考

一次性给出答案的模型必须在第一次尝试时就把所有事情做对：没有草稿、没有检查、没有中途改变方向。对于证明、棘手的 bug 或长时间的智能体任务，第一种方法往往不是最好的。

思考消除了这一限制。当思考处于活动状态时，Claude 会在回答之前用自己的语言逐步解决问题：它会重述所问的内容、尝试各种方法、检查中间结果，并放弃站不住脚的路径。这些推理会在响应之前以 thinking 内容块的形式到达，Claude 会利用它们来生成最终答案。这就是为什么思考能提升复杂任务的表现，例如数学、编码、分析和长时间运行的智能体工作，在这些任务中，答案的质量取决于那些否则会被压缩到响应本身或被跳过的中间工作。

思考是有成本的：Claude 用于推理的令牌会作为输出令牌计费，即使思考文本没有返回给您，并且它们与响应文本一起计入 max_tokens。本页介绍思考在整个 API 层面的行为：开启思考、读取其输出，以及管理它与工具、流式传输、缓存和上下文窗口的交互。



思考如何工作

Claude 是否对给定请求进行思考以及思考的深度，取决于您的思考配置和请求的复杂性。

以下是思考在响应中的样子：一个或多个 thinking 内容块在 text 块之前到达。思考块仍然是生成的内容，就像它后面的 text 块一样，但它与规范响应是分开的。每个思考块还带有一个 signature 字段，这是完整推理的加密副本，您需要在多轮对话和工具使用对话中原封不动地传回（参见思考加密）：

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me break this down. The question has two parts, so I'll start with the simpler one and use its result to constrain the second...",
      "signature": "WaUjzkypQ2mUEVM36O2Txu...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

您并不总是能看到这些文本，而且您看到的永远不是原始的思维链：思考块中的文本是 Claude 推理的摘要。思考配置上的 display 字段控制是否返回该摘要："summarized" 会返回它，而 "omitted"（最新模型上的默认值）会返回 thinking 字段为空的思考块。无论哪种方式，该块的计费方式相同，在多轮对话中的传回方式也相同；有关每个模型的默认值和详细信息，请参见控制思考显示。

如果 Claude 使用工具，思考也可以出现在工具调用之间；参见思考与工具使用。有关完整的响应格式，请参见 Messages API 参考。



配置思考

在当前模型上，思考默认开启或只需一个参数即可开启。每个模型接受哪种配置以及默认值是什么，都列在故障排除页面的按模型配置表中。

在 Claude Opus 5、Claude Sonnet 5、Claude Fable 5、Claude Mythos 5 和 Claude Mythos Preview 上，思考已经开启：无需配置。在这些模型上，大多数开发者首先需要的是看到思考文本，因为 display 在这些模型上默认为 "omitted"。通过 thinking: {"type": "adaptive", "display": "summarized"} 选择启用，这正是下面的请求，只需替换模型字符串。

在 Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6 上，思考是关闭的，直到您在请求中设置 thinking: {type: "adaptive"}。以下示例就是这样做的，同时设置 display: "summarized" 以便思考文本可见，并使用宽裕的 max_tokens：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
)

for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

运行该示例会打印摘要思考，然后是答案：

Thinking: Use Euclidean algorithm.
1071 = 2*462 + 147
462 = 3*147 + 21
147 = 7*21 + 0
GCD = 21

Response: ## Finding GCD of 1071 and 462

I'll use the **Euclidean algorithm**, repeatedly dividing and taking remainders...

思考令牌计入 max_tokens，因此请将其设置得足够高，为思考和响应文本都留出空间。参见引导页面上的成本控制以及思考与上下文窗口。



关闭思考

在 Claude Sonnet 5 上，思考默认开启，您可以将其关闭：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "Summarize this article in one sentence."}],
)

Claude Opus 5 也默认开启思考，并在 effort 为 high 或更低时接受 thinking: {type: "disabled"}。在 xhigh 或 max effort 下，思考无法关闭：将 thinking: {type: "disabled"} 与这些 effort 级别组合的请求会返回 400 错误。此限制适用于 Claude Opus 5 及更高版本的模型，并在每个请求上强制执行。在禁用思考的情况下，Claude Opus 5 偶尔会以纯文本形式发出工具调用，或在其可见输出中包含内部 XML 标签；有关提示方面的缓解措施，请参见在禁用思考的情况下运行。

Claude Fable 5、Claude Mythos 5 和 Claude Mythos Preview 会拒绝 thinking: {type: "disabled"}：在这些模型上无法关闭思考。

如果您的模型仅支持扩展思考（参见按模型配置表），请改用 type: "enabled" 和 budget_tokens 值进行配置；扩展思考页面介绍了该配置。如果任何思考配置返回 400 错误，思考故障排除会将每条错误消息与其修复方法对应起来。



读取思考输出



控制思考显示

思考配置上的 display 字段控制思考内容在 API 响应中的返回方式。display 在两种模式下都有效：可以与 type: "adaptive" 或 type: "enabled" 一起设置。它接受两个值：

• "summarized"：思考块包含摘要思考文本，即 Claude 推理的可读摘要。这是 Claude Opus 4.6、Claude Sonnet 4.6 及更早模型上的默认值。
• "omitted"：返回的思考块的 thinking 字段为空。signature 字段仍然携带加密的完整思考，以保证多轮对话的连续性（参见思考加密）。这是 Claude Fable 5、Claude Mythos 5、Claude Opus 5、Claude Sonnet 5、Claude Opus 4.8、Claude Opus 4.7 和 Claude Mythos Preview 上的默认值。

当您的应用程序不向用户展示思考内容时，请设置 display: "omitted"。主要好处是流式传输时更快的首个文本令牌时间：服务器完全跳过思考令牌的流式传输，只传递签名，因此最终文本响应会更早开始流式传输。

使用 display: "omitted" 时，响应包含 thinking 字段为空的 thinking 块：

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EosnCkYICxIMMb3LzNrMu..."
    },
    {
      "type": "text",
      "text": "The answer is 12,231."
    }
  ]
}

使用省略思考时请注意以下几点：

• 您仍然需要为完整的思考令牌付费。省略减少的是延迟，而不是成本。
• 如果您在多轮对话中传回思考块，请原封不动地传回。服务器会解密 signature 以重建原始思考用于提示构建（参见保留思考块）。您在往返传递的省略块的 thinking 字段中放置的任何文本都会被忽略。
• display 与 thinking.type: "disabled" 一起使用是无效的（没有可显示的内容）。
• 使用 thinking.type: "adaptive" 时，如果模型对简单请求跳过思考，则无论 display 如何都不会产生思考块。
• 使用 display: "omitted" 进行流式传输时，不会发出 thinking_delta 事件；有关事件序列，请参见流式传输思考。

在 Ruby SDK 中，请将此字段设置为 display_:（带尾部下划线）以避免遮蔽 Ruby 的 Kernel#display；线路字段仍然是 display。



摘要思考

当 display 为 "summarized" 时，您收到的思考文本是 Claude 完整思考过程的摘要，而不是原始的思维链。摘要思考在防止滥用的同时提供了思考的全部智能优势。没有任何 display 设置会返回原始思维链。

使用摘要思考时请注意以下几点：

• 您需要为原始请求生成的完整思考令牌付费，而不是摘要令牌。计费的输出令牌数量与您在响应中看到的令牌数量不匹配。
• 在 Claude Opus 4.6、Claude Sonnet 4.6 及更早模型上，思考输出的前几行更加详细，提供了对提示工程特别有帮助的详细推理。Claude Mythos Preview 从第一个令牌开始就进行摘要，因此其思考块不会显示这种详细的前言。
• 摘要以最小的额外延迟保留了 Claude 思考过程的关键思想，从而实现可流式传输的用户体验。
• 摘要由与您在请求中指定的模型不同的模型处理。思考模型看不到摘要输出。
• 随着 Anthropic 不断改进思考功能，摘要行为可能会发生变化。



流式传输思考

思考可与流式传输配合使用。思考块以 content_block_delta 事件内的 thinking_delta 事件形式流式传输，随后在该块的 content_block_stop 之前有一个单独的 signature_delta 事件。文本块随后照常流式传输。

以下示例使用自适应思考流式传输响应，在思考和文本增量到达时打印它们：

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

设置 display: "omitted" 时，思考块打开，一个单独的 signature_delta 到达，然后该块关闭，没有任何 thinking_delta 事件。文本流式传输随即开始：

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":"","signature":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":"EosnCkYICxIMMb3LzNrMu..."}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}

有关一般流式传输机制，请参见流式传输消息。



思考与 effort

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

有关每个 effort 级别对思考行为的影响，请参见引导思考页面上的按级别思考行为表；Effort 页面记录了该参数本身，包括每个模型支持哪些级别。在 Claude Opus 4.5（唯一支持 effort 的仅扩展思考模型）上，effort 与 budget_tokens 组合使用；参见预算规则和调优。

这两个控制项以这种方式分离后，请选择与您的目标相匹配的那个：

• **降低启用思考的工作负载的成本或延迟：**首先降低 effort。它会缩减整个响应，包括思考。
• **Claude 思考得太少或太浅：**提高 effort，或参见引导页面上的引导 Claude 思考的频率。
• **您需要完全关闭思考：**在允许的模型上使用 thinking: {type: "disabled"}（参见按模型配置表）。
• **您需要对支出设置硬性上限：**使用 max_tokens。Effort 是软性指导；max_tokens 是严格限制。



思考与工具使用

思考可与工具使用配合使用，让 Claude 能够推理工具选择并处理工具结果。有两个约束：

1. 工具选择限制（手动模式）：使用手动扩展思考（thinking: {type: "enabled"}）的工具使用仅支持 tool_choice: {"type": "auto"}（默认值）或 tool_choice: {"type": "none"}。使用 tool_choice: {"type": "any"} 或 tool_choice: {"type": "tool", "name": "..."} 会导致错误，因为这些选项强制使用工具，这与手动扩展思考不兼容。自适应思考（包括在默认开启思考的模型上）支持强制工具使用。
2. 保留思考块：当您返回工具结果时，必须将助手消息中的思考块完整且未经修改地传回 API。参见保留思考块。

**一个工具使用循环是一个助手轮次。**从模型的角度来看，助手轮次在 Claude 完成其完整响应之前不会结束，这可能包括多个工具调用和结果。整个序列是一个单独的助手轮次：

User: "What's the weather in Paris?"
Assistant: [thinking] + [tool_use: get_weather]
User: [tool_result: "20°C, sunny"]
Assistant: [text: "The weather in Paris is 20°C and sunny"]

整个轮次在单一思考模式下运行：您不能在轮次中间切换思考，包括在工具使用循环期间。在扩展（手动）模式下，API 还强制要求启用思考的请求的最后一个助手轮次以思考块开头。自适应模式放宽了这一点：没有任何助手轮次需要以思考块开头。

**轮次中途的冲突会优雅降级。**如果您在轮次中途切换思考（例如，在发送工具调用和返回其结果之间），API 不会报错。相反，它会静默地为该请求禁用思考。为了保持模型质量，API 可能会剥离会造成无效轮次结构的思考块，或者在对话历史与启用思考不兼容时禁用思考。要确认思考是否处于活动状态，请检查响应中是否存在 thinking 块。

**在轮次之间切换，而不是在轮次内部切换。**在每个轮次开始时规划您的思考策略。完成助手轮次，然后为下一个轮次更改思考配置：

User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
Assistant: [text: "It's sunny"]
User: "What about tomorrow?"
Assistant: [thinking] + [text: "..."] (thinking enabled - new turn)

请注意，切换思考模式也会使提示缓存失效；参见思考与提示缓存。



保留思考块

当 Claude 调用工具时，它会暂停构建其响应以等待外部信息。当您返回工具结果时，Claude 会继续构建同一个响应，因此其先前的推理必须仍然存在。请将每个 thinking 块完整且未经修改地传回 API，连同它所伴随的 tool_use 块。这很重要，原因有二：

1. 推理连续性：思考块捕获了导致工具请求的逐步推理。包含它们可以让 Claude 从中断的地方继续推理。
2. 上下文维护：工具结果在 API 结构中显示为用户消息，但它们是一个连续推理流的一部分。保留思考块可以在 API 调用之间维持该流程。

简而言之：

• **必需：**在工具使用轮次内，传回思考块。
• **推荐：**跨轮次，传回所有内容。
• **允许：**在工具使用之外，省略先前轮次的思考。

您不需要自己修剪旧的思考。在多轮对话中传回所有思考块，API 会自动过滤它们，保留维持模型推理所需的块，并且仅对实际展示给 Claude 的块计费输入令牌。保留哪些先前轮次的块因模型而异；参见按模型的思考块保留。要覆盖默认值，请使用 clear_thinking_20251015 上下文编辑策略。

在最新的助手消息中，连续 thinking 块的序列必须与模型在原始请求中生成的内容相匹配：您不能重新排列、编辑或部分删除它们。这包括 redacted_thinking 块。

有关包含每个 SDK 代码的完整两轮演练，请参见工具和多轮工作流中的思考。它定义了一个工具，接收思考加工具使用的响应，并将助手轮次与工具结果一起回传。



交错思考

交错思考让 Claude 能够在工具调用之间进行思考，在对每个工具结果采取行动之前对其进行推理。通过交错思考，Claude 可以：

• 在决定下一步做什么之前，对工具调用的结果进行推理
• 将多个工具调用与中间的推理步骤链接起来
• 基于中间结果做出更细致的决策

使用自适应思考时，交错思考在每个支持自适应思考的模型上都是自动的；不需要 beta 标头。在 Claude Fable 5、Claude Mythos 5、Claude Mythos Preview、Claude Opus 5、Claude Opus 4.8 和 Claude Opus 4.7 上，工具调用之间的推理始终出现在思考块中。Claude Haiku 4.5 不支持交错思考。在使用手动扩展思考的模型上，交错需要 beta 标头，并且会改变思考预算的计算方式；手动模式下的交错思考介绍了按模型的规则和特定于平台的标头行为。

使用交错思考时，思考分配可以跨越整个助手轮次，而不是单个响应。交错思考仅支持通过 Messages API 使用的工具。

有关展示交错思考在双工具工作流中改变了什么的实例对比，请参见交错思考如何改变流程。



按模型的思考块保留

先前助手轮次的思考块是否默认保留在上下文中取决于模型：

• **保留所有先前轮次：**Claude Opus 4.5 及更高版本的 Opus 模型、Claude Sonnet 4.6 及更高版本的 Sonnet 模型、Claude Fable 5、Claude Mythos 5 和 Claude Mythos Preview。
• **仅保留最后一个轮次：**更早的 Opus 和 Sonnet 模型，以及直到 Claude Haiku 4.5 的所有 Haiku 模型。当您传回较旧的思考块时，API 会自动剥离它们；您不需要自己删除它们。

保留带来两个好处：

• 缓存优化：保留的思考块在工具使用期间可以实现缓存命中，因为它们与工具结果一起传回，并在整个助手轮次中增量缓存，从而在多步骤工作流中节省令牌。
• 不影响智能：保留思考块对模型性能没有负面影响。

代价是上下文使用：在保留所有轮次的模型上，长对话会消耗更多的上下文空间，因为保留的思考块与任何其他对话历史一样计为输入（参见思考与上下文窗口）。这两种机制下的行为都是自动的；不需要代码更改或 beta 标头，您应该按照保留思考块中的描述继续传回完整、未经修改的思考块。要在任一方向上覆盖默认值，请使用思考块清除。

**在对话中途切换模型。**当您在任意两个模型之间切换时，例如在分类器拒绝回退之后，请从先前的助手轮次中剥离 thinking 和 redacted_thinking 块。思考块与生成它们的模型绑定。其他模型会静默忽略它们而不是拒绝请求，但被忽略的块仍然会增加输入令牌。



思考与提示缓存

提示缓存与思考在几个特定方面存在交互。以下规则在两种思考模式下都适用。

**配置更改会使缓存失效。**思考配置和解析后的 effort 级别会被渲染到提示本身中，因此更改其中任何一项都会开始一个新的缓存前缀。在 adaptive、enabled 和 disabled 之间切换、更改 budget_tokens 以及更改 effort 值都会使缓存断点失效：消息级断点总是未命中，工具和系统提示断点也可能未命中，具体取决于模型在何处渲染配置。请将任何思考或 effort 更改视为重新开始缓存。保持相同配置的连续请求会保留缓存，并且将参数显式设置为其默认值等同于省略它。引导思考页面上有一个带有使用量输出的实例演示。

**思考块与工具结果一起缓存。**在工具使用循环期间，当您发出包含工具结果的后续请求时会发生缓存。此时，先前的对话历史（包括其思考块）可以被缓存，并且从缓存读取时，这些缓存的思考块在您的使用量指标中计为输入令牌。这是自动发生的，即使没有显式的 cache_control 标记，并且对于常规思考和交错思考的行为相同。代价是：您在响应中再也看不到的思考块在从缓存读取时仍然会计入输入令牌使用量。

先前的块是否在上下文中完全取决于模型。保留默认值决定了这一点。在保留所有轮次的模型上，先前轮次的思考块保持缓存并留在上下文中。在仅保留最后一个轮次的模型上，一旦您发送的用户消息不是工具结果，所有先前的思考块都会从上下文中剥离。在这些模型上，像这样的对话：

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]

会被当作思考块从未存在过一样处理：

User: ["What's the weather in Paris?"],
Assistant: [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [text block 2],
User: [Text response, cache=True]

在保留所有轮次的模型上，相同的请求会将 thinking_block_1 和 thinking_block_2 保留在上下文和缓存中。

**降级会从可缓存的历史中剥离思考。**如果思考在轮次中途被禁用，并且您在当前工具使用轮次中传递了思考内容，则思考内容会被剥离，并且该请求的思考保持禁用状态（参见优雅降级）。交错思考会放大缓存失效的影响，因为思考块可能出现在多个工具调用之间。



思考与上下文窗口

max_tokens（包括 Claude 在当前轮次中生成的所有思考）作为严格限制强制执行。在 Claude 4.5 及更新的模型上，如果输入令牌加上 max_tokens 超过上下文窗口大小，API 会接受该请求；如果生成随后达到上下文窗口限制，它会以 stop_reason: "model_context_window_exceeded" 停止，而不是返回错误。在更早的模型上，API 会返回验证错误。参见处理停止原因。

思考如何计入窗口取决于它是何时生成的：

• 当前轮次的思考始终计入 max_tokens，作为输出令牌计费，并在生成它的轮次中占用上下文窗口空间。
• 先前轮次的思考取决于保留默认值。在保留所有先前轮次的模型上，先前的思考块保留在上下文中，计入窗口，并像对话历史的其余部分一样作为输入令牌计费。在仅保留最后一个轮次的模型上，当您传回较旧的思考块时，API 会自动剥离它们，因此它们不会消耗窗口空间或输入令牌。

实践中：

• 在保留所有轮次的模型上，请像对待普通对话历史一样为思考预算上下文窗口，因为它确实如此。长时间的智能体会话会在上下文中累积思考；如果需要回收空间，请使用思考块清除。
• 在仅保留最后一个轮次的模型上，思考只是每轮次的成本：每个轮次的思考计入该轮次的 max_tokens，然后从窗口中移除。

以下图表说明了仅保留最后一个轮次（剥离）的机制。第一个图展示了多轮对话：每个轮次的思考块在输出中生成，但不会带入后续轮次的输入。

第二个图展示了相同机制下的工具使用：思考在助手轮次期间与其工具结果一起保留在上下文中，然后在下一个用户轮次中移除。

使用令牌计数 API 为您的特定用例获取准确的计数，尤其是对于包含思考的多轮对话。



思考加密

完整的思考内容经过加密，并在每个思考块的 signature 字段中返回。当您传回思考块时，API 使用该签名来验证思考块是由 Claude 生成的。

使用签名时请注意以下几点：

• 只有在将工具与思考一起使用时，才严格需要传回思考块。否则，您可以省略先前轮次的思考块。如果您确实传回它们，API 是保留还是剥离它们取决于模型（参见按模型的思考块保留）；使用上下文编辑来配置这一点。
• 传回思考块时，请完全按照收到的内容传回所有内容，以保持一致性并避免潜在问题。
• 在流式传输响应时，签名作为 content_block_delta 事件内的 signature_delta 到达，就在 content_block_stop 事件之前。
• 在 Claude 4 及更高版本的模型中，signature 值比以前的模型长得多。
• signature 字段是不透明的：不要解释或解析它。
• signature 值在各平台之间兼容（Claude API、Amazon Bedrock 和 Google Cloud）。在一个平台上生成的值可以在另一个平台上使用。



经过编辑的思考块

除了常规的 thinking 块之外，当 Claude 的部分推理因安全原因被编辑时，API 可能会返回 redacted_thinking 块。redacted_thinking 块在 data 字段中包含加密的思考内容，没有可读文本：

{
  "type": "redacted_thinking",
  "data": "..."
}

data 字段是不透明且加密的。与常规思考块上的 signature 字段一样，在使用工具继续多轮对话时，请将 redacted_thinking 块原封不动地传回 API。



Claude Fable 5 和 Claude Mythos 5 上的思考输出

在 Claude Fable 5 和 Claude Mythos 5 上，永远不会返回原始思维链；您收到的块是常规的 thinking 块，而不是 redacted_thinking，并且 display 设置的工作方式与其他模型相同（摘要文本，或在省略时为空的 thinking 字段，这是此处的默认值）。有关思考块的响应形状，请参见 Messages API 参考。

在同一模型上继续对话时，请将每个思考块完全按照收到的内容传回 API，包括 thinking 字段为空的块。不要编辑或重建它们。读取摘要文本用于显示是可以的：API 拒绝的是返回内容被修改的块，而不是您读取过的块。放置在空的省略 thinking 字段中的文本会被忽略而不是被拒绝。

有关在对话中途切换模型时思考块会发生什么，请参见按模型的思考块保留。

有两个例外，在回退额度中有介绍：

• 回退额度重试必须原封不动地回传被拒绝的请求体。
• 来自输出中途回退的 fallback 块保留在它们出现的位置。

要了解模型的推理，请阅读本页描述的 thinking 块，而不是在响应文本中提示要求推理。在 Claude Fable 5 上，试图将模型的内部推理作为响应文本的一部分引出的请求可能会被拒绝，并返回 stop_details.category: "reasoning_extraction"。有关字段参考和处理指南，请参见拒绝类别。



限制与功能兼容性

采样参数。 在 Claude Fable 5、Claude Mythos 5、Claude Mythos Preview、Claude Opus 5、Claude Opus 4.8、Claude Opus 4.7 和 Claude Sonnet 5 上，无论是否使用思考，非默认的 temperature、top_p 或 top_k 值在每个请求上都会返回 400 错误。在较旧的模型上，该限制仅在思考开启时适用：temperature 和 top_k 与思考不兼容，而 top_p 允许使用 0.95 到 1 之间的值。

响应预填充和强制工具使用。 思考开启时，您无法预填充助手响应。强制工具使用（tool_choice: {"type": "any"} 或 {"type": "tool", ...}）与手动扩展思考不兼容，但可与自适应思考配合使用；请参阅思考与工具使用。

输出限制。 Claude Fable 5、Claude Mythos 5、Claude Mythos Preview、Claude Opus 5、Claude Opus 4.8、Claude Opus 4.7、Claude Sonnet 5、Claude Opus 4.6 和 Claude Sonnet 4.6 支持每个请求最多 128k 输出令牌。Claude Haiku 4.5、Claude Sonnet 4.5 和 Claude Opus 4.5 支持最多 64k。在 Message Batches API 上，output-300k-2026-03-24 beta 标头可将 Claude Opus 5、Claude Opus 4.8、Claude Opus 4.7、Claude Sonnet 5、Claude Opus 4.6 和 Claude Sonnet 4.6 的限制提高到 300k。有关旧版模型的限制，请参阅模型概述。

长请求。 当 max_tokens 大于 21,333 时，SDK 要求使用流式传输（streaming），以避免长时间运行的请求出现 HTTP 超时。这是客户端验证，而非 API 限制。如果您不需要增量处理事件，请使用 .stream() 配合 .get_final_message()（Python）或 .finalMessage()（TypeScript）来获取完整的 Message 对象，而无需处理单个事件；请参阅流式传输消息。思考激活时，预计响应时间会更长，因为生成思考块会增加处理时间。对于每个请求的思考量超过大约 32k 令牌的工作负载，请使用批处理以避免网络问题：此类请求的运行时间可能长到足以触发系统超时和打开连接限制。



后续步骤