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

> top_p deprecated 不表示 Opus 模型已经退役。先找到最终请求中的旧采样字段：原生 Messages 用 top_p，Bedrock Converse 用 inferenceConfig.topP；省略正确位置的参数后，再验证同一任务是否恢复。

- URL: https://blog.laozhang.ai/zh/posts/claude-code-top-p-deprecated
- Published: 2026-04-17
- Updated: 2026-10-07
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: Claude Code
- Tags: Claude Code, Opus 4.7, top_p deprecated, Anthropic, 故障排查

---
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 参数弃用说明](https://platform.claude.com/docs/zh-CN/about-claude/model-deprecations)、[AWS Opus 4.7 模型说明](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-opus-4-7.html)

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

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

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

| 看到的症状 | 先检查什么 | 应采取的动作 |
| --- | --- | --- |
| HTTP 400，正文指出 `top_p` 或其他采样字段 | 实际模型、接口，以及发送前的请求结构 | 在该接口的采样参数位置省略不支持的字段 |
| Python 报 `TypeError: ... unexpected keyword argument ...`，没有 HTTP 响应 | SDK 调用函数的参数列表 | 从函数调用中去掉已不接受的参数；这一步发生在 HTTP 请求之前 |
| 上传的配置里没有 `top_p`，运行时仍报错 | 配置合并、模型适配器、代理及工具调用路径 | 找出重新注入参数的代码，不能只继续修改原配置 |
| 明确提示客户端版本低于模型要求 | 实际执行的客户端和该模型当前要求 | 按版本错误处理，完成后用原任务验证 |
| 401、403、模型不存在，或错误指向思考、消息、工具字段 | 对应接口的认证、模型和功能规则 | 转入相应排查，不用删采样参数包治所有错误 |

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

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

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

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

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

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

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

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

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

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

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

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

![分别清理 Messages 顶层和 Converse 参数，同时保留消息、工具与业务同名字段的示意。](https://blog.laozhang.ai/posts/zh/claude-code-top-p-deprecated/img/removed-params-board.webp)

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

Bedrock 对 Opus 4.7 的说明更直接：这些采样参数不受支持，应省略。与此同时，Converse 的通用参数类型仍然列出 `temperature` 和 `topP`，因为该接口服务于多种模型。**通用接口有这个字段，不等于 Opus 4.7 支持它。** SDK 类型提示也不能替代模型说明。[AWS 模型说明](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-opus-4-7.html)、[Converse InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_InferenceConfiguration.html)

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

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

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

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

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

```python
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")
```

在本地副本上运行：

```bash
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`、消息和工具配置；它们不是完整可发送请求。

清理前：

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

清理后：

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

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

如果你用的是 Bedrock 原生模型调用，模型请求正文则使用 `top_p`、`temperature`、`top_k` 等原生命名，不能按 Converse 的路径清理。保留该接口需要的版本字段和其他有效配置，也不要把 Anthropic 直连接口的整份请求照搬过去。[AWS Opus 4.7 调用说明及示例](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-opus-4-7.html)

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

这时继续追踪运行时构造过程。AWS 的文档处理示例项目曾收到一个可说明问题的报告：上传配置中没有 `top_p`，但 agentic 路径经 Strands 调用 `ConverseStream` 仍报参数弃用。维护者随后说明，该示例项目的 `0.5.10` 版本修复了模型识别和采样字段省略逻辑。[AWS 示例项目 issue #304](https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws/issues/304)

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

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

![保持同一后端、清理旧参数并重跑原任务的流程示意图](https://blog.laozhang.ai/posts/zh/claude-code-top-p-deprecated/img/cleanup-flow.webp)

先做离线结构检查，再验证原任务。本文的示例已做离线 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 文档](https://platform.claude.com/docs/en/build-with-claude/effort)

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

## 常见问题

### `top_p deprecated` 一定是 Claude Code 的 bug 吗？

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

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

按 Opus 4.7 的当前文档，优先省略。原生 API 明确拒绝非默认采样值，Bedrock 明确不支持这些采样控制；不能凭旧默认值推定某个数字或 `null` 在你的接口上安全。确认序列化后字段确实缺席。[Anthropic 弃用说明](https://platform.claude.com/docs/zh-CN/about-claude/model-deprecations)、[AWS 模型说明](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-opus-4-7.html)

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

参数弃用本身不是换模型的理由。官方状态表仍将 4.7 和 4.6 列为 active；先按实际模型清理请求。如果不得不临时换模型，要重新确认功能、输出和路由条件，不能把换模型成功当成原请求已修好。[模型状态与参数弃用](https://platform.claude.com/docs/zh-CN/about-claude/model-deprecations)

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

SDK 可能为其他模型保留字段，通用接口类型也可能覆盖多种模型。类型允许构造请求，不等于当前模型接受该参数。另一方面，若 SDK 已移除对应函数参数，错误可能在发出 HTTP 请求前发生；应把客户端 `TypeError` 与服务端 400 分开处理。[官方 SDK 说明](https://platform.claude.com/docs/zh-CN/about-claude/model-deprecations)

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

不能这样保证。Opus 4.7 上应按对应接口省略不支持的采样参数；effort 调整工作投入和 token 使用倾向，不提供确定性保证。需要稳定交付时，使用清楚的输出约束、结构检查和任务验收，而不是把 effort 当成另一个随机性数值。[AWS 采样说明](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-opus-4-7.html)、[effort 文档](https://platform.claude.com/docs/en/build-with-claude/effort)

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-10-07。

- [Anthropic 参数弃用说明](https://platform.claude.com/docs/zh-CN/about-claude/model-deprecations) (platform.claude.com)
- [AWS Opus 4.7 模型说明](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-opus-4-7.html) (docs.aws.amazon.com)
- [Claude Code 模型配置文档](https://code.claude.com/docs/en/model-config) (code.claude.com)
- [Anthropic Messages 参数说明](https://platform.claude.com/docs/es/build-with-claude/working-with-messages) (platform.claude.com)
- [Converse InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_InferenceConfiguration.html) (docs.aws.amazon.com)
- [AWS 示例项目 issue #304](https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws/issues/304) (github.com)
- [Anthropic effort 文档](https://platform.claude.com/docs/en/build-with-claude/effort) (platform.claude.com)