Claude Code 报 top_p deprecated？别先换渠道，先按 Opus 4.7 的新请求规则排

Claude Code 报 top_p deprecated 时，先确认真正发送请求的客户端、实际模型和后端接口，再到请求构造处省略旧采样字段。不要只把 top_p 改成 1，也不要删掉一处配置就认定请求已经干净：适配器、插件或代理可能在发送前重新补上它。

对 Opus 4.7，Anthropic 原生 API 的当前规则是：temperature、top_p、top_k 的非默认值会触发 400，官方建议省略这些参数。Bedrock 的 Opus 4.7 模型说明则明确不支持这三种采样控制。处理时按自己的接口省略字段，不猜 0、1、null 或旧教程中的默认值是否能通过。Anthropic 参数弃用说明、AWS Opus 4.7 模型说明

修复的成功标准也很具体：保持原模型、原后端和原任务，检查最终请求不再携带不支持的采样参数，然后确认正常输出和工具调用恢复。换了模型后能运行，可以作为临时方案，但不能证明原来的请求已经修好。

先选分支：你落在哪条路径上？

先看完整错误，再决定改哪一层。deprecated 是弃用，retired 是退役；两者不能混为一谈。截至 2026 年 10 月 6 日，官方模型状态表仍将 Opus 4.7 和 Opus 4.6 列为 active。参数被弃用，不等于模型不可用，也不证明你的账户或所用云平台一定有访问权限。模型生命周期说明

这里的 Python 分支来自官方弃用文档：Python SDK v1 及更高版本的相关接口已移除这些采样参数，继续传入可能直接产生 TypeError。这是文档描述的客户端行为，不能从中推定你机器上安装了哪个 SDK，也不能把它当成服务端返回的 400。官方 SDK 兼容说明

如果 Claude Code 本体太旧，或者你根本没走在受支持路径上

先记录你实际使用的客户端和版本。终端 Claude Code、编辑器中的调用、Agent SDK，以及包在它们外面的脚本，可能不是同一套发送路径；界面里出现 Claude Code，也不足以证明旧字段由 Claude Code 本体发出。

不要再把 v2.1.111+ 当作所有当前模型的统一支持下限。那是本文早期版本里的历史信息，模型支持要求会继续变化。只有错误明确指向客户端版本，或当前模型文档说明你的版本不受支持时，才把更新客户端作为相应处理；采样参数 400 本身不能推出“升级一定解决”。当前支持情况以 Claude Code 模型配置文档和你所用模型的要求为准。

更新之前保留失败任务和错误信息；更新之后确认实际调用的确实是新版本，再重跑原任务。不要同时换模型、后端和代理，否则很难区分是客户端修好了请求，还是另一个变化绕开了故障。

如果你的 provider / alias 路径和你以为的不一样

opus 是别名，不能当成永久不变的模型 ID。Claude Code 的别名映射随平台和版本变化；“Anthropic 上必定是 4.7，所有云平台都是 4.6”已经不能作为当前判断。确认本次请求的真实模型名称、云平台模型标识或部署名称，再查那一个模型的规则。Claude Code 模型选择与别名

记录下面三项，往往比继续改参数数字更有用：

• 谁发送：终端客户端、SDK、插件，还是独立代理服务。
• 发到哪里：Anthropic Messages、Bedrock 的原生模型调用、Bedrock Converse，或第三方兼容接口。
• 发给谁：实际模型 ID、推理配置标识或部署名称，不能只写界面标签 opus。

模型选择也有持久化区别。当前 Claude Code 文档说明，/model 中按 Enter 选择或直接指定名称，会保存用户默认模型；选择器中的 s 用于仅本次会话。启动时的 --model、环境设置和配置默认值又可能参与选择。排障前先确认哪一个值正在生效，别把一次测试选择误当成毫无影响的操作。模型配置文档

如果中间有兼容代理，客户端准备发送的结构和代理转发给上游的结构都值得看。错误响应通常只能告诉你哪一类字段被拒绝；究竟是谁加的，需要比较各个构造或转换位置。检查时记录模型、接口、参数路径和字段是否存在即可，不必把密钥、完整对话或客户数据写进日志。

Opus 4.7 到底改了什么，为什么 top_p 现在直接 400

以前 SDK 能接收或接口能使用的参数，不代表换模型后仍然有效。原生 API 对 Opus 4.7 及后续模型、Mythos Preview 的说明是：非默认的 temperature、top_p、top_k 返回 400，并建议省略参数、通过提示词表达输出要求。这里要保留“非默认值”这个条件，不能改写成“只要字段出现就一定返回 400”。Anthropic Messages 参数说明

Bedrock 对 Opus 4.7 的说明更直接：这些采样参数不受支持，应省略。与此同时，Converse 的通用参数类型仍然列出 temperature 和 topP，因为该接口服务于多种模型。通用接口有这个字段，不等于 Opus 4.7 支持它。 SDK 类型提示也不能替代模型说明。AWS 模型说明、Converse InferenceConfiguration

省略意味着序列化后的请求里没有这个字段。把 Python 值改成 None、把 JSON 改成 null，或用另一个数字替换，不一定得到相同结果。是否省略应在发送前的实际请求中确认。

如果是 wrapper、插件或配置层还在偷偷注入旧参数

修复应落在模型和接口已经确定、即将序列化或发送请求的位置。如果只在较早的配置文件里删字段，后面的默认配置合并仍可能把它加回来。另一方面，也不能把整个 JSON 中所有叫 top_p 或 temperature 的属性递归删除：工具输入结构、业务数据和消息内容中的同名字段，可能正是用户要处理的数据。

原生 Messages：只清理请求顶层的采样字段

下面是 Anthropic 原生 Messages 的离线处理示例，限定模型为 claude-opus-4-7。它不导入 SDK，也不发送请求，只从标准输入读取 JSON、清理顶层字段并输出结果。保存为 omit_sampling.py：

import json
import sys

request = json.load(sys.stdin)
if not isinstance(request, dict):
    raise SystemExit("输入必须是一个原生 Messages 请求对象")
if request.get("model") != "claude-opus-4-7":
    raise SystemExit("模型不匹配：请先确认实际模型及其参数规则")

for name in ("top_p", "temperature", "top_k"):
    request.pop(name, None)

json.dump(request, sys.stdout, ensure_ascii=False, indent=2)
sys.stdout.write("\n")

在本地副本上运行：

python3 omit_sampling.py < request.json > request-clean.json

这段代码适合检查你自己的原生请求构造器，不是让你替换 Claude Code 内部请求。接入现有程序时，应在后续默认值合并完成后执行同样的顶层清理；如果后面还有适配器，仍需确认它没有再次注入。不要把原生示例直接套到 OpenAI 兼容接口或云平台的完整调用对象上。

比如原生请求顶层的 top_p 应被移除，tools[0].input_schema.properties.top_p 则应保留。messages、system、tools、原本适用的 max_tokens、stop_sequences 和优先级设置也不因采样参数错误而删除。采样清理只解决采样字段；其他字段是否可用，仍按实际模型和接口分别判断。

Bedrock Converse：清理 inferenceConfig，不要改错字段名

Converse 使用驼峰字段 inferenceConfig.topP，不是原生 Messages 的顶层 top_p。下面两段是同一个 Opus 4.7 Converse 请求中的局部配置，省略了外层 modelId、消息和工具配置；它们不是完整可发送请求。

清理前：

{
  "inferenceConfig": {
    "maxTokens": 2048,
    "stopSequences": ["END_REPORT"],
    "temperature": 0.2,
    "topP": 0.9
  }
}

清理后：

{
  "inferenceConfig": {
    "maxTokens": 2048,
    "stopSequences": ["END_REPORT"]
  }
}

这里保留了输出上限和停止序列，仅省略 Opus 4.7 不支持的采样控制。2048 和 END_REPORT 是示例原有值，不是推荐所有任务采用的配置。确认适配器在最终的 inferenceConfig 中没有再加入 temperature 或 topP；对于模型专用扩展字段，也应按实际发送结构检查 top_k 等原生采样参数。Converse 通用字段定义

如果你用的是 Bedrock 原生模型调用，模型请求正文则使用 top_p、temperature、top_k 等原生命名，不能按 Converse 的路径清理。保留该接口需要的版本字段和其他有效配置，也不要把 Anthropic 直连接口的整份请求照搬过去。AWS Opus 4.7 调用说明及示例

配置里没有字段，为什么仍然报错？

这时继续追踪运行时构造过程。AWS 的文档处理示例项目曾收到一个可说明问题的报告：上传配置中没有 top_p，但 agentic 路径经 Strands 调用 ConverseStream 仍报参数弃用。维护者随后说明，该示例项目的 0.5.10 版本修复了模型识别和采样字段省略逻辑。AWS 示例项目 issue #304

这份报告说明“配置干净”不能证明“最终请求干净”；它不证明所有 Claude Code 报错都由同一个问题引起。0.5.10 也是该示例项目的版本，不是 Claude Code 的统一修复版本。

修好以后怎么验证，什么时候 fallback 才算合理

先做离线结构检查，再验证原任务。本文的示例已做离线 JSON、语法和合成数据检查，没有执行真实 SDK 客户端或 API 调用；因此不能把示例通过写成某个账户上的恢复结果。

1. 检查最终字段。 原生 Messages 确认顶层采样字段缺席；Opus 4.7 Converse 确认 inferenceConfig.topP、inferenceConfig.temperature 缺席，并检查适配器是否在模型专用扩展中继续注入采样参数。
2. 检查必要内容保留。 对比清理前后的消息、工具定义、业务数据、输出上限、停止序列和适用的优先级设置。工具结构里的同名属性不能因清理而消失。
3. 在已获授权的原调用路径重跑。 固定客户端、实际模型、后端和任务，观察原来的采样错误是否消失。真实调用可能消耗额度，离线检查本身不需要密钥。
4. 检查完整任务结果。 接口不再返回该 400，只说明越过了原来的校验。还要看输出是否符合要求、工具是否正常执行并返回，以及调用方是否拿到了最终结果。

如果错误仍指向同一个采样字段，优先确认后面的构造器是否又补回了它，以及修复是否只覆盖普通请求而漏了工具或代理分支。如果错误换成思考配置、消息格式、工具结构或权限问题，就按新的明确错误继续处理；不要为了消掉错误连同必要功能一起删掉。

工具链暂时改不动时，可以在自己的最终请求构造处做有明确模型和接口条件的省略处理。改用另一个模型或后端则是另一种临时选择：先核对它是否支持所需功能、工具和输出要求，确认质量及费用可接受，再使用。它与原路径修复应分别记录，不能拿新路径成功代替原模型验证。

删掉采样参数后，怎样保持输出可用？

把需要的结果写清楚：输出格式、必须覆盖的信息、可接受的长度、工具使用条件和完成标准。比如代码任务要求“只修改指定模块、保留公开接口，并给出验证结果”，比寻找一个与旧 top_p 等价的数字更能表达任务意图。

output_config.effort 可在支持它的模型和接口上调节工作投入、回答的详尽程度及 token 使用倾向，但它不是核采样概率，也不是 top_p 的数字替代品。提高 effort 不保证复刻旧输出，降低它也不等于降低随机性；它还是行为控制信号，而非严格 token 预算。Anthropic effort 文档

因此，不必为了修复采样字段就自动开启新的思考模式、把输出预算拉到 64K，或声称输出从此确定一致。先保留原任务中仍受支持的控制和验收标准，恢复请求后再按实际输出调整。

常见问题

top_p deprecated 一定是 Claude Code 的 bug 吗？

不一定。它表明当前调用遇到了采样参数兼容问题，但字段可能来自客户端、插件、适配器或代理。定位发送前的实际字段及注入位置，才能判断谁需要修复；只看界面名称或错误字符串还不够。

把 top_p 改成 1，或者传 null，可以解决吗？

按 Opus 4.7 的当前文档，优先省略。原生 API 明确拒绝非默认采样值，Bedrock 明确不支持这些采样控制；不能凭旧默认值推定某个数字或 null 在你的接口上安全。确认序列化后字段确实缺席。Anthropic 弃用说明、AWS 模型说明

采样参数弃用，是不是应该立即从 Opus 4.7 切回 4.6？

参数弃用本身不是换模型的理由。官方状态表仍将 4.7 和 4.6 列为 active；先按实际模型清理请求。如果不得不临时换模型，要重新确认功能、输出和路由条件，不能把换模型成功当成原请求已修好。模型状态与参数弃用

SDK 里还看得到 top_p，为什么模型不接受？

SDK 可能为其他模型保留字段，通用接口类型也可能覆盖多种模型。类型允许构造请求，不等于当前模型接受该参数。另一方面，若 SDK 已移除对应函数参数，错误可能在发出 HTTP 请求前发生；应把客户端 TypeError 与服务端 400 分开处理。官方 SDK 说明

用 effort 或 temperature 为 0，能保证每次输出一样吗？

不能这样保证。Opus 4.7 上应按对应接口省略不支持的采样参数；effort 调整工作投入和 token 使用倾向，不提供确定性保证。需要稳定交付时，使用清楚的输出约束、结构检查和任务验收，而不是把 effort 当成另一个随机性数值。AWS 采样说明、effort 文档