迁移到 Claude Opus 5.5：不兼容改动与 400 报错排查

Claude Opus 5.5 的模型 ID 是 claude-opus-5-5。把 Opus 5 的代码迁过来，除了换模型字符串，还要处理 Anthropic 标为不兼容的四项请求改动：thinking 不能再关闭；强制工具调用直接返回 HTTP 400；thinking 块绑定产生它的模型和对话；computer use 要换成新的 computer_toolset_20260801 工具。经 Router One 调用时，把改好的请求发到 POST https://api.router.one/v1/messages（或 /v1/chat/completions），写上 "model": "claude-opus-5-5" 和显式的 max_tokens；实时单价见 Claude Opus 5.5 模型页。

旧代码原封不动打到 Opus 5.5，会拿到下面四条报错之一（原文摘自 Anthropic 的 What's new in Claude Opus 5.5）：

"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
tool_choice: type "tool" and "any" are not supported for this model.
'claude-opus-5-5' does not support tool types: computer_20251124.

对 Opus 5.5 的请求，Router One 会兜住前三条：把旧式 thinking 取值改写为自适应思考，去掉 temperature、top_p 和 top_k，把强制的 tool_choice 降为 auto，并把 Chat Completions 的 reasoning_effort 映射到 output_config.effort。代码还是要改：直连 Anthropic，或经过原样转发请求的网关，这些 400 照样出现；而且被兜住的请求并不等于你本来想发的请求——「关闭」thinking 的请求照样在思考、照样按 thinking token 计费，被降级的工具选择也可能换来一段纯文本回答。

第一次接入 Opus 5.5？先看 Claude Opus 5.5 API 接入指南；本文讲迁移与排障。

迁移清单

完整清单见 Anthropic 的 迁移指南。下面这些决定了 Opus 5 及更早的代码还能不能跑；第 5、6 项主要卡的是从 Opus 4.6 或更早版本带过来的代码。

1. 模型 ID。 发 claude-opus-5-5；普通 HTTP 客户端也可以直接发目录 ID anthropic/claude-opus-5.5。claude-opus-5.5、anthropic/claude-opus-5-5 以及任何 -thinking 变体都会被拒绝。
2. thinking 设置。 删掉 {"type": "disabled"} 和 {"type": "enabled", "budget_tokens": N}。不传 thinking，或传 {"type": "adaptive"}。
3. 思考强度。 设置 output_config.effort：默认值从 Opus 5 的 high 降到了 medium。
4. 工具选择。 把 any 和 tool（Chat Completions 上是 "required" 或指定函数）换成 auto，给工具加 "strict": true，并在提示词里写明什么时候用它。strict 工具要走 /v1/messages：Chat Completions 的协议转换不转发 strict。
5. 采样参数。 删掉非默认值的 temperature、top_p 和 top_k。
6. 预填（prefill）。 messages 不要以 assistant 回合结尾。
7. Computer use。 用 computer_toolset_20260801 替换 computer_20251124，并改写 agent 循环。
8. 内容块。 按 type 读取内容块，不要写 content[0].text；每个 assistant 回合都原样回传。
9. max_tokens。 thinking 也占用它：每个请求都显式传，并留足余量。
10. 拒答。 处理 stop_reason: "refusal"，在自己的代码里换模型重试。
11. 计费。 截至 2026-09-24 的套餐接口，Pro、Max、Ultra 的任何档位都没有列出 claude-opus-5-5，所以 Opus 5.5 的调用按 token 从钱包余额扣费；Claude Opus 5 仍在三个套餐的「高级模型」档。2026-09-24 的目录里，aws/ 与 vertex/ 渠道 ID 也只到 Opus 5。

一个能通过的原生 Messages 请求：

curl https://api.router.one/v1/messages \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 16000,
    "stream": true,
    "output_config": {"effort": "medium"},
    "messages": [{"role": "user", "content": "检查这段 diff 里有没有破坏 API 兼容的改动：..."}]
  }'

Chat Completions 上的写法，用 reasoning_effort 代替思考强度字段：

curl https://api.router.one/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 16000,
    "stream": true,
    "reasoning_effort": "medium",
    "messages": [{"role": "user", "content": "检查这段 diff 里有没有破坏 API 兼容的改动：..."}]
  }'

不兼容改动一：thinking 始终开启

Opus 5.5 每个请求都在跑自适应思考。不传 thinking 与传 {"type": "adaptive"} 等价；disabled 返回 400 invalid_request_error，带 budget_tokens 的 enabled 也一样。思考深度只剩 output_config.effort 一个旋钮，可选 low、medium、high、xhigh、max（effort 文档）。Opus 5 在思考强度 high 及以下时接受 disabled，所以在它上面跑得好好的代码，到这里就报错了。

改之前，在 Opus 5 上：

{
  "model": "claude-opus-5",
  "max_tokens": 16000,
  "thinking": {"type": "disabled"},
  "messages": [{"role": "user", "content": "用五条要点总结这份更新日志。"}]
}

改之后——thinking 保持开启，由思考强度决定想多少：

{
  "model": "claude-opus-5-5",
  "max_tokens": 16000,
  "output_config": {"effort": "low"},
  "messages": [{"role": "user", "content": "用五条要点总结这份更新日志。"}]
}

如果当初关 thinking 是为了不让推理文字出现在响应里，现在的默认行为已经做到了：thinking 块返回时是空的（display: "omitted"），不过这些 token 仍按输出计费。

经 Router One 时。 对 Opus 5.5，网关会把 {"type": "disabled"} 改写为自适应思考，请求没设思考强度时补上 output_config.effort: "low"；把 {"type": "enabled", "budget_tokens": N}（或单独出现的 budget_tokens）也改写为自适应思考——/v1/messages 与 /v1/chat/completions 都这样处理。预算本身不再生效：没设思考强度的 enabled 请求按默认的 medium 运行。请求能通过，但模型照样在思考，thinking 照样按输出计费，所以思考强度还是自己定。

不兼容改动二：强制工具调用返回 400

Opus 5.5 的 tool_choice 只接受 {"type": "auto"}（默认）和 {"type": "none"}。any 和 tool 返回：

tool_choice: type "tool" and "any" are not supported for this model.

改之前：

{
  "model": "claude-opus-5",
  "max_tokens": 16000,
  "tools": [{
    "name": "get_weather",
    "description": "Current weather for a city",
    "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
  }],
  "tool_choice": {"type": "tool", "name": "get_weather"},
  "messages": [{"role": "user", "content": "上海现在天气怎么样？"}]
}

改之后——auto、strict 工具，再把要求写进提示词：

{
  "model": "claude-opus-5-5",
  "max_tokens": 16000,
  "tools": [{
    "name": "get_weather",
    "description": "Current weather for a city",
    "strict": true,
    "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"], "additionalProperties": false}
  }],
  "tool_choice": {"type": "auto"},
  "messages": [{"role": "user", "content": "上海现在天气怎么样？请使用 get_weather 工具。"}]
}

Strict tool use 保证工具输入合法、工具名有效，但不保证一定调用。要的是 JSON 而不是一个动作时，用 structured outputs 代替强制工具：

{
  "model": "claude-opus-5-5",
  "max_tokens": 16000,
  "output_config": {
    "effort": "low",
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}, "summary": {"type": "string"}},
        "required": ["city", "summary"],
        "additionalProperties": false
      }
    }
  },
  "messages": [{"role": "user", "content": "从下面这段文字里提取城市名和一句话摘要：..."}]
}

经 Router One 时。 对 Opus 5.5，网关会把 tool_choice 的 any 和 tool（Chat Completions 上的 "required" 和指定函数）降为 auto：不会 400，但模型可以直接用文字作答。读取工具调用之前，先确认 stop_reason 是 "tool_use"（Chat Completions 上确认消息里带 tool_calls）。strict 工具和 output_config.format 都要走 /v1/messages：Chat Completions 的协议转换不转发 strict，它的 response_format 对 Claude 系列 ID 也不是拿到 JSON 的可靠办法。

不兼容改动三：thinking 块绑定所在对话

每个 thinking 块都带一个签名，绑定写出它的模型，以及排在它前面的全部请求内容。所以在工具循环里，每个 assistant 回合都要原样回传，空的 thinking 块和 redacted_thinking 块也要带上。出现下面两条报错，说明历史被改过：

`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified
messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

第一条说明代码重建或过滤了 assistant 回合；第二条说明两次请求之间 system 提示词、tools 或更早的消息变了。对 2026 年 8 月 31 日及之后创建的账户，Anthropic 默认执行这项前缀校验；经网关调用时无从判断适用哪种账户规则，请按校验已开启处理，历史只追加（append-only）。补救办法：带上 beta 头 thinking-binding-controls-2026-08-01 并设置 prefix_mismatch_behavior: "drop_block"，或者从历史里删掉全部 thinking 和 redacted_thinking 块后重试一次（thinking 排障）。

默认 display 下的一个 assistant 回合——原样回传即可：

{
  "role": "assistant",
  "content": [
    {"type": "thinking", "thinking": "", "signature": "EqQBCkYIBxgCKkA..."},
    {"type": "tool_use", "id": "toolu_01A", "name": "get_weather", "input": {"city": "Shanghai"}}
  ]
}

用 Anthropic Python SDK 写一个守住上面所有规则的工具循环：

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.router.one",
    api_key="sk-your-api-key",
)

tools = [{
    "name": "get_weather",
    "description": "Current weather for a city",
    "strict": True,
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
        "additionalProperties": False,
    },
}]
messages = [{"role": "user", "content": "上海现在天气怎么样？请使用 get_weather 工具。"}]

while True:
    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=16000,
        output_config={"effort": "medium"},
        tools=tools,
        messages=messages,
    )
    # assistant 回合原样追加，thinking 块也一起带上。
    messages.append({"role": "assistant", "content": response.content})
    if response.stop_reason != "tool_use":
        break
    results = [
        {"type": "tool_result", "tool_use_id": block.id, "content": "小雨，18 度"}
        for block in response.content
        if block.type == "tool_use"
    ]
    messages.append({"role": "user", "content": results})

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

经 Router One 时。 /v1/messages 会把你回传的 thinking 块原样转发；例外是上游故障后请求被换到同一模型的另一条线路重试，这次重试会去掉这些块，不报错，但这一轮丢掉了之前的推理。Chat Completions 的协议转换会把 thinking 放进 reasoning_content 返回，但下一轮不会回放：工具循环照样能跑，只是没有了之前的推理。多轮工具循环请走 /v1/messages。

不兼容改动四：computer use 改用 toolset

在 Claude API 和 Google Cloud 上，Opus 5.5 会拒绝旧版 computer 工具，报错开头为：

'claude-opus-5-5' does not support tool types: computer_20251124.

改之前——需带 beta 头 anthropic-beta: computer-use-2025-11-24：

{
  "tools": [{"type": "computer_20251124", "name": "computer", "display_width_px": 1024, "display_height_px": 768}]
}

改之后——不需要 beta 头，工具条目也不写名字和显示尺寸：

{
  "tools": [{"type": "computer_toolset_20260801"}]
}

agent 循环也要跟着改：动作名从 input.action 改放到每个 tool_use 块的 name 里；一个回合可能有多个这样的块；回传的每个结果都要带 toolset_name。toolset 不接受 "strict": true。

经 Router One 时。 /v1/messages 原样透传工具定义，所以 toolset 能通过，computer_20251124 会被拒绝。Chat Completions 只承载 function 工具，所以 computer use 必须走 /v1/messages。

三条会卡住旧代码的老规则

思考预算。 {"type": "enabled", "budget_tokens": N} 在 Claude 4.7 及之后的模型上（包括 Opus 5）都返回 400；Anthropic 把它归在从 Opus 4.6 或更早版本带过来的代码里。按不兼容改动一的写法替换：

{
  "model": "claude-opus-4-6",
  "max_tokens": 16000,
  "thinking": {"type": "enabled", "budget_tokens": 10000},
  "messages": [{"role": "user", "content": "用五条要点总结这份更新日志。"}]
}

采样参数。 Opus 4.7 及之后的 Opus 模型（包括 Opus 5）遇到非默认值的 temperature、top_p 或 top_k 都会返回 400，受影响的是从 Opus 4.6 或更早版本带过来的代码，以及默认就带 temperature 的 OpenAI 风格客户端。Router One 会为 Opus 5.5 去掉这些参数，但代码里也请删掉。

预填（prefill）。 messages 以 assistant 回合结尾时，Opus 5.5 会拒绝（Anthropic 把这一条归在从 Opus 4.5 或更早版本迁移的部分）。格式要求写进 system 提示词，或改用 output_config.format。Router One 也不改写预填，所以请直接从代码里去掉，不要依赖某条线路对它的处理方式。

不报错、却会打破预期的行为变化

默认思考强度是 medium。 Opus 5 默认 high。如果你的效果依赖旧默认值，就显式设置 "output_config": {"effort": "high"}，再拿 medium 对比成本和质量。在 /v1/messages 上，Router One 原样透传 output_config.effort；在 /v1/chat/completions 上，它会为 Opus 5.5 把 reasoning_effort 映射过去，none 和 minimal 都按 low 处理。

每轮思考更多。 同样的思考强度下，Opus 5.5 想得比 Opus 5 多，thinking 也占用 max_tokens。Anthropic 建议 xhigh 或 max 从 64k 起步；Opus 5.5 提示词指南 也提到，长时间的 agentic 编码回合用 128,000（模型输出上限）效果不错。长任务请用流式（流式输出指南）。经 Router One 时，每个请求都显式传 max_tokens，钱包余额也留得宽裕些：余额不够覆盖一次请求的预扣估算时，网关会调低 max_tokens，长回答可能因此被截断。把生产流量切过去之前，先按你选定的思考强度测一遍单次请求成本；Opus 5.5 vs Opus 5 对比页会并排显示两者在 Router One 上的实时单价。

工具调用之间的说明文字进了 thinking 块。 Opus 5.5 在两次工具调用之间写的简短进度说明，现在以 thinking 块返回，默认 display: "omitted" 下是空的。想展示它，就设 thinking: {"type": "adaptive", "display": "summarized"}（或设 "updates" 并带上 beta 头 thinking-display-updates-2026-08-18），然后渲染非空的 thinking 块（thinking display）。Router One 的 /v1/messages 原样透传 thinking.display 和 anthropic-beta；/v1/chat/completions 不转发 anthropic-beta，所以 updates 只能走 /v1/messages。

拒答变成了一种停止原因。 拒答返回 HTTP 200，带 stop_reason: "refusal" 和 stop_details.category；在 "cyber" 之外新增了 "bio" 和 "reasoning_extraction"，后者针对要求模型复述内部推理的提示词。Anthropic 建议配置 fallback，可以用 beta 版的服务端参数 fallbacks、Anthropic SDK 的 middleware，或者自己重试。经 Router One 时不要发 fallbacks：钱包计费会在请求到达模型之前以 HTTP 400 拒绝它。Router One 也不会把 Opus 5.5 的请求换成别的模型回答，所以重试写在你自己的代码里；reasoning_extraction 类拒答原样返回、不重试，Anthropic 的服务端 fallback 也是这样处理的：

response = client.messages.create(
    model="claude-opus-5-5", max_tokens=16000, messages=messages
)
if (
    response.stop_reason == "refusal"
    and response.stop_details.category != "reasoning_extraction"
):
    response = client.messages.create(
        model="claude-opus-5", max_tokens=16000, messages=messages
    )

换模型时 messages 里的 thinking 块照样带上（见下一节）；什么情况下值得换模型重试，见生产环境的 fallback 策略。

对话中途换模型

thinking 块只有产生它的模型和固定的几个模型读得懂；目标模型读不懂的块，API 会静默丢弃，也不计费。Opus 5.5 能读 Opus 5 以及更早的 Opus、Sonnet、Haiku 模型的 thinking 块，所以把 Opus 5 的对话升到 Opus 5.5，推理能接上。截至 2026-09-24，Router One 目录里没有别的 Claude ID 能读 Opus 5.5 的 thinking 块，从 Opus 5.5 降回 Opus 5 或 Sonnet 5，对话能继续，但之前的推理没了；Opus 5.5 也读不了 Claude Fable 5 的 thinking 块。一段对话尽量只用一个模型，要换就在任务边界换，不要在工具循环中途换。

如果 Router One 在上游故障后重试 Opus 5.5 的请求，也只在 Opus 5.5 上重试；400 从不重试，也不会换别的模型回答。所以指定了模型 ID 的请求，Dashboard → Logs 里出现换模型，一定是你的代码换的（每请求可观测）。

Opus 5.5 400 报错速查

对 Opus 5.5，Router One 会兜住两条 thinking 行、tool_choice 行和采样参数行对应的请求，所以这几条报错只在直连 Anthropic、或经过原样转发请求的网关时出现。其余上游 400 在非流式 /v1/messages 上通常保留 Anthropic 的报错原文；在流式 /v1/messages 和 /v1/chat/completions 上，以请求字段开头的参数校验报错（如 thinking 签名报错）现在也会原样返回，其他 400（包括 computer 工具报错）则统一返回通用提示 invalid request (upstream rejected with status 400)。与 Opus 5.5 无关的通用状态码见 API 错误码速查，各模型系列的端点规则见 API 兼容性事实页。

客户端与 SDK（截至 2026-09-24）

客户端会不会出问题，取决于它的代码有没有按名字认出 Opus 5.5。下表描述的是各项目截至 2026-09-24 的代码本身，不是 Router One 的行为；经 Router One 时多数情况已经不会报 400（见上文），但换个地方调用，这些改法仍然必要。

编程工具

SDK 与框架

Claude Code 里的模型固定、套餐配额和 1M 窗口，见 Claude Code 默认 Opus 5.5 之后。

常见问题

为什么我的 Opus 5 代码在 Claude Opus 5.5 上返回 400？ Opus 5 接受、Opus 5.5 拒绝的有四样：设为 disabled 的 thinking，any 或 tool 的 tool_choice，computer_20251124 工具，以及对话前缀变化后回放的 thinking 块。对应改成 output_config.effort、tool_choice auto、computer_toolset_20260801 工具集，历史只追加。

我的 Opus 5 代码发的是 thinking disabled，现在该发什么？ 不传 thinking，或传 type 为 adaptive；想让思考最轻，就把 output_config.effort 设为 low。Opus 5.5 关不掉思考。默认 display 下，响应里 thinking 块的文字本来就是空的，但这些 token 仍按输出计费。

Router One 会帮我把这些报错处理掉吗？ 对 Opus 5.5，旧式 thinking 取值会改写为自适应思考，temperature、top_p 和 top_k 会被去掉，强制的 tool_choice 降为 auto，reasoning_effort 映射到 output_config.effort。预填、旧版 computer 工具和被改过的 thinking 块网关不改写，Anthropic 的 API 会拒绝它们。代码还是要改，这样在哪里调用都符合你的本意。

现在怎么让 Opus 5.5 调用指定的工具？ 没法强制。在 /v1/messages 上用 tool_choice auto 加 strict 工具（Chat Completions 的协议转换不转发 strict），在提示词里写明什么时候用这个工具，读取工具调用前先确认 stop_reason 是 tool_use。要的是 JSON 而不是一个动作，就在 /v1/messages 上用 output_config.format。

Claude Opus 5.5 还能传 temperature 或 top_p 吗？ 只能用默认值：非默认值在 Opus 4.7 及之后的 Opus 模型上都返回 400，Opus 5.5 也不例外。Router One 会为 Opus 5.5 去掉它们，但代码里也请删掉，并留意会自行添加 temperature 的客户端，比如 Aider。

报错「The block is bound to a different conversation」是什么意思？ 回放的 thinking 块和它的上下文对不上了：system 提示词、tools 或更早的消息被改过。历史请只追加；要继续这次请求，可以带上 beta 头 thinking-binding-controls-2026-08-01 并把 prefix_mismatch_behavior 设为 drop_block，或者删掉全部 thinking 和 redacted_thinking 块后重试一次。

Opus 5.5 拒答时，代码该怎么处理？ 拒答是 HTTP 200，带 stop_reason refusal 和 stop_details.category。在自己的代码里换模型重试，例如 claude-opus-5；reasoning_extraction 类拒答除外。不要发 Anthropic 的 fallbacks 参数，钱包计费会以 HTTP 400 拒绝它；指定 claude-opus-5-5 的请求，Router One 从不换别的模型回答。

同一段对话能在 Opus 5.5 和 Opus 5 之间切换吗？ 能，但推理只能单向接上：Opus 5.5 能读 Opus 5 的 thinking 块，Opus 5 读不了 Opus 5.5 的，API 会静默丢弃这些块、不计费。要换就在任务边界换。

下一步

• 第一个请求：Claude Opus 5.5 API 接入指南，讲模型 ID、端点与 SDK 配置。
• Claude Code：Claude Code 默认 Opus 5.5 之后，讲模型固定、套餐与 1M 上下文窗口；全新安装见 Claude Code 配置指南。
• 实时规格与单价：Opus 5.5 vs Opus 5、Opus 5.5 vs Claude Sonnet 5、Opus 5.5 vs GPT-6 Sol。
• 在价格页确认套餐覆盖范围；给迁移用的 Key 设一个 maxSpend 上限：花费不会超过这个上限，其他 Key 照常可用（按 Key 成本追踪）。中国大陆可直连 api.router.one，无需 VPN。