中文 English

Claude Code 一升级就全模型 400：别急着换 Key，可能是网关没跟上新版协议

发布时间: 2026-05-29
Claude Code AI Agent 故障排查 Anthropic API OpenAI兼容接口 模型网关 开发工具

先说结论

这次故障的表象非常吓人：Claude Code 更新之后，不管访问哪个模型，都会立刻报 API Error: 400 invalid params, chat content has invalid message role: system (2013)。如果只看错误，很容易怀疑 API Key 失效、模型下线、余额不足、代理坏了、环境变量乱了，甚至怀疑所有模型同时挂掉。真正的根因不是这些，而是新版 Claude Code 发出的请求结构和某些 Anthropic-compatible 模型网关之间出现了兼容断层：网关把不该出现在 chat content 中的 system role 当成非法消息拒绝了。

最小可用修复也很朴素：先用最小 prompt 复现，再对相邻版本做二分式验证。最终确认 2.1.150 能正常返回，2.1.154 和 2.1.156 会复现 400，于是把全局 Claude Code 固定回 2.1.150。这不是“玄学回滚”，而是基于证据找到最后一个已知可用版本。

这篇文章记录一次 Claude Code 本地环境排障。它不是一个复杂到需要改源码的问题，但很有代表性：AI Agent 工具链越来越依赖模型网关、兼容协议、环境变量、版本更新和本地 provider 切换；当其中一层发生协议细节变化时，终端里看到的却往往只是一句抽象的 400。

为了避免泄露任何隐私信息，本文不会出现真实内网地址、真实用户名、真实 token、真实私有 provider 名称、真实本机路径或私有服务域名。所有配置片段都使用 <PLACEHOLDER>、<MODEL_GATEWAY>、<MODEL_NAME> 等占位符表示。文章重点是分享排障方法，而不是公开某个具体环境。

Claude Code 升级后触发兼容网关错误的抽象题图

图 1：本文自制题图。错误看起来发生在模型侧，真正需要追的是 Claude Code、Anthropic API 语义和兼容网关之间的消息格式。

1. 问题背景：现在的 Claude Code 很少是“单机直连模型”

很多人第一次用 Claude Code 时，脑子里的结构很简单：终端里输入 claude，Claude Code 调 Anthropic，模型返回结果。这个理解在直连官方模型时大体成立，但在真实开发环境里，链路经常更复杂。

常见结构可能是这样的：

  1. Claude Code 作为本地 CLI，负责读项目、执行命令、管理会话和组织模型请求。
  2. 环境变量或 settings 文件里配置 ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、默认模型名等。
  3. 请求不一定直连 Anthropic 官方服务，而是进入一个 Anthropic-compatible endpoint。
  4. 这个 endpoint 背后可能再转发到其他模型厂商、企业 token 平台、统一模型网关或 OpenAI-compatible 转换层。
  5. 最终模型返回内容，再由兼容层包装成 Claude Code 能理解的格式。

这类架构的好处很明显：可以统一鉴权、统一模型列表、统一计费、按团队做 provider 切换，也可以让不原生支持 Anthropic Messages API 的模型通过兼容层接入 Claude Code。坏处也同样明显：当 Claude Code 版本升级、Anthropic API 语义变化、兼容层实现滞后、模型返回结构略有差异时，故障会变得很像“所有模型都坏了”。

这次就是这种情况。用户看到的是“访问任何模型都报错”，但真正坏掉的不是所有模型，而是当前选中的兼容入口无法接受新版 Claude Code 发出的某种消息结构。

2. 问题表现：一句最小 prompt 也 400

最初的错误信息是：

API Error: 400 invalid params, chat content has invalid message role: system (2013)

这个错误有几个特点。

第一，它是 400，不是 401、403、429 或 5xx。400 通常表示请求参数不符合服务端期望，而不是鉴权失败、额度不足、限流或服务端崩溃。

第二，它明确提到了 invalid message role: system。这说明服务端已经解析到了请求体里的消息角色，并且认为 system 出现在了不允许的位置。

第三，它在“任何模型”上都出现。这个现象很容易误导人。很多人会把它理解成“所有模型都不支持”，但从工程角度看，更可能是同一条上游请求在进入模型之前就被统一网关拒绝了。也就是说，错误可能发生在模型路由之前，而不是模型推理阶段。

为了排除项目上下文、历史会话、工具调用、系统 prompt、MCP、长上下文压缩等干扰，我做的第一件事是最小复现：

claude -p "只回复 OK"

结果仍然返回同样的 400。这一步很重要。它说明问题不是某个项目里的 CLAUDE.md 写坏了，不是某次会话历史污染，也不是复杂工具调用触发了兼容问题。只要 Claude Code 用当前全局配置发出一次最简单的请求，就会失败。

从表层错误追到真正拒绝请求的位置

图 2：不要停在第一行 400。要确认请求经过了 CLI、API 语义层、兼容网关和模型后端中的哪一层。

3. 第一轮排查：先不要猜，先确认“谁在拒绝”

排这种问题时，我不建议第一反应就是换 Key、换模型或重装 Claude Code。因为这些动作都很大，而且会把现场证据冲掉。更稳的顺序是：先确认当前版本、当前 provider、当前环境变量和最小请求行为。

3.1 看 Claude Code 版本

先确认当前版本：

claude --version

现场版本是 2.1.156。用户也提到“可能和最近更新了 Claude 版本有关”。这条信息很有价值，因为它把时间线拉出来了：如果更新前能用，更新后全模型 400，那版本变化就必须被当作一级嫌疑，而不是背景噪声。

3.2 看当前是否直连官方服务

接着看 Claude Code 的 settings。脱敏后结构大概类似：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://<MODEL_GATEWAY>/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "<TOKEN>",
    "ANTHROPIC_MODEL": "<MODEL_NAME>",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "<MODEL_NAME>",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "<MODEL_NAME>",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "<MODEL_NAME>"
  }
}

这个信息直接改变排障方向。当前 Claude Code 并不是单纯直连 Anthropic 官方服务，而是通过一个兼容入口访问后端模型。既然如此，错误就可能来自三类地方：

  1. Claude Code 新版本构造了新的请求格式。
  2. Anthropic Messages API 本身对 system 的位置有明确语义。
  3. 兼容网关没有正确适配新版请求，或者把 Anthropic 请求错误转换成了 Chat Completions 风格的消息数组。

3.3 看 provider 列表，确认是不是所有路径都坏

本地还使用了 provider 切换工具。查看 provider 列表后可以看到多个 Claude provider：有当前选中的兼容入口，也有其他候选入口。脱敏后可以理解为：

Current: <Provider A>  -> https://<MODEL_GATEWAY_A>/anthropic
Other:   <Provider B>  -> https://<MODEL_GATEWAY_B>/anthropic
Other:   <Provider C>  -> https://<MODEL_GATEWAY_C>/anthropic

于是我没有立刻修改全局配置，而是用“临时启动”的方式分别测试不同 provider：

cc-switch start claude <PROVIDER_ID> -- -p "只回复 OK"

结果很有意思：

  1. 当前 provider 失败，报同样的 invalid message role: system。
  2. 另一个同类兼容入口也失败。
  3. 某个不同 provider 能正常返回 OK。

这一步说明：不是本机所有 Claude Code 请求都不能用，也不是终端网络完全坏了。故障集中在某些 Anthropic-compatible 网关路径上。

4. 关键背景：Anthropic 的 system 不是普通 messages 里的 role

理解这个错误，需要先理解 Anthropic Messages API 和 OpenAI Chat Completions 在系统提示上的差异。

在很多 OpenAI-compatible Chat Completions 接口里，常见写法是把系统提示放进 messages 数组：

{
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello"}
  ]
}

但 Anthropic Messages API 的语义不完全一样。Anthropic 的 messages 通常是用户和助手轮次，系统提示是请求顶层的 system 参数，而不是 messages 数组里的一条 role=system 消息。公开文档里也能看到 system 作为独立字段出现，而 messages 示例主要使用 user / assistant 角色。

这就带来一个兼容层风险：如果某个网关内部用 OpenAI Chat Completions 的模型来承接 Anthropic Messages API，它必须正确做双向转换。也就是说：

  1. Claude Code 发送 Anthropic 风格请求。
  2. 网关读取顶层 system、messages、tools、thinking、metadata 等字段。
  3. 网关按后端模型需要，把它转换成对应协议。
  4. 后端返回后，再转换回 Claude Code 期待的 Anthropic 风格响应。

只要其中一步把 system prompt 错放到了某个 chat content 的 message role 里，或者新版 Claude Code 的请求里多了兼容层没覆盖的内容块，就可能触发类似错误。

这也是为什么错误文本里会出现“chat content”这种不像纯 Anthropic 官方错误的措辞。它更像是后端兼容网关或下游模型服务在校验 Chat 消息格式时给出的拒绝。

5. 第二轮排查：用版本探针找回归窗口

既然用户怀疑最近更新版本，我就需要验证这个怀疑，而不是只说“可能是”。验证方式很简单：用 npx 临时运行不同版本的 Claude Code，仍然使用同样的最小 prompt 和同样的当前配置。

测试命令类似：

npx -y @anthropic-ai/claude-code@2.1.154 -p "只回复 OK" --model <MODEL_NAME>
npx -y @anthropic-ai/claude-code@2.1.150 -p "只回复 OK" --model <MODEL_NAME>

结果如下：

2.1.156 -> 400 invalid message role: system
2.1.154 -> 400 invalid message role: system
2.1.150 -> OK

这一步把问题从“最近更新可能有关”变成了“版本区间内存在可复现的兼容变化”。虽然我没有继续逐个测试 2.1.151、2.1.152、2.1.153，但对恢复生产可用性来说，已经足够确认最后一个已知可用版本是 2.1.150。

用相邻版本探针定位回归窗口

图 3：最小 prompt + 相邻版本测试，比盲目重装或换 Key 更可靠。

这里有一个排障原则值得强调：回滚不是逃避，前提是你知道自己为什么回滚、回滚到哪里、以及如何验证。

如果只是随便装一个旧版本，确实是玄学。但如果你已经证明当前版本失败、相邻旧版本失败、更早版本成功，那么固定到最后一个已知可用版本就是合理的止血动作。

6. 根因判断：新版 Claude Code 与兼容网关的协议适配断层

把所有证据串起来，可以得到比较清晰的根因判断：

Claude Code 在 2.1.154 到 2.1.156 这个区间内，对发往 Anthropic-compatible endpoint 的请求结构或消息组织方式发生了变化。当前使用的某些兼容网关没有完整适配这种变化，导致网关或下游 chat 校验层把 system role 视为非法消息角色并返回 400。模型本身未必有机会参与推理，请求在进入后端模型前就被拒绝了。

这个结论不是从源码直接证明的，而是从现场证据推出来的：

  1. 最小 prompt 也失败，排除项目上下文污染。
  2. 当前请求通过 ANTHROPIC_BASE_URL 进入兼容网关，不是简单直连。
  3. 不同 provider 行为不同，说明不是 Claude Code 全局网络不可用。
  4. 2.1.150 成功，2.1.154 / 2.1.156 失败，说明版本变化是必要条件之一。
  5. 错误内容指向消息 role 校验，而不是鉴权、余额、限流或模型不存在。

这里我刻意使用“兼容断层”这个词，而不是简单说“Claude Code 有 bug”或“网关有 bug”。因为从工程角度看，兼容问题经常不是单方错误。Claude Code 可以合法更新请求结构；兼容网关也需要跟随官方 API 语义演进。真正的问题是双方之间缺少足够严格的兼容测试，尤其是针对 system prompt、tools、thinking、streaming、content block 等 Agent 场景里的复杂字段。

7. 修复过程：固定最后一个已知可用版本

确认 2.1.150 可用后，修复动作很简单：

npm install -g @anthropic-ai/claude-code@2.1.150

安装完成后做三次验证。

第一，确认版本：

claude --version

期望输出：

2.1.150 (Claude Code)

第二，用显式模型最小 prompt 验证：

claude -p "只回复 OK" --model <MODEL_NAME>

期望输出：

OK

第三，不带 --model，验证默认模型路径也正常：

claude -p "只回复 OK"

期望输出：

OK

为什么要做第三步？因为真实使用时，用户往往不会每次都显式指定模型。如果只验证 --model 成功，而默认 provider、默认 haiku/sonnet/opus 映射仍然错误，那么一打开交互式 Claude Code 还是可能失败。

修复策略：先止血，再等待兼容层跟进

图 4：如果能换 provider，可以临时切换；如果必须走同一个网关，固定最后一个已知可用版本是最小可逆修复。

8. 为什么我没有优先改配置或换 API Key

这类问题最容易出现几个错误动作。

8.1 盲目换 Key

如果是 401、403，或者错误明确写 authentication、permission、quota，那么换 Key 或检查额度很合理。但这次是 400 invalid params，并且错误明确指向 message role。换 Key 只会让变量变多，不会改变请求体结构。

8.2 盲目换模型名

“所有模型都报错”不代表所有模型坏了。如果同一个 provider 下所有模型都通过同一个网关校验，请求在网关层就被拒绝，那么换模型名没有意义。更有效的是换 provider 路径，或者换 Claude Code 版本。

8.3 盲目清空会话

最小 claude -p 已经可以复现，说明不需要先清历史会话。清会话是有成本的，尤其是在复杂 Agent 工具里，历史会话可能包含重要上下文。没有证据不要动它。

8.4 盲目升级到最新

很多软件问题可以通过升级解决，但这次问题本来就是“升级后出现”。在兼容网关还没适配前，继续追最新版本只会重复踩坑。固定可用版本反而更稳。

9. 可复用排障清单

以后再遇到 Claude Code 或类似 Agent CLI 的“全模型不可用”，可以按这个顺序查。

9.1 先分类错误码

400 -> 优先看请求格式、参数、协议兼容
401/403 -> 优先看鉴权、Key、权限、账号状态
404 -> 优先看 endpoint、模型名、路径
429 -> 优先看限流、额度、并发
5xx -> 优先看服务端、网关、上游模型稳定性

这不是绝对规则，但能帮助你避免第一步就走偏。

9.2 做最小 prompt

claude -p "只回复 OK"

如果最小 prompt 都失败，优先查全局配置、provider、版本和网络，不要先查项目 prompt。

9.3 确认当前版本

claude --version

记录版本号，不要只说“最新版”。技术排障里，“最新版”没有诊断价值，具体版本号才有。

9.4 确认是否使用兼容网关

查看 settings 或环境变量中是否存在：

ANTHROPIC_BASE_URL
ANTHROPIC_MODEL
ANTHROPIC_DEFAULT_SONNET_MODEL
ANTHROPIC_DEFAULT_HAIKU_MODEL
ANTHROPIC_DEFAULT_OPUS_MODEL

如果有自定义 ANTHROPIC_BASE_URL，就要把兼容层纳入排查范围。

9.5 横向测试 provider

如果本地有 provider 切换工具，不要一上来切全局。先临时启动不同 provider：

cc-switch start claude <PROVIDER_ID> -- -p "只回复 OK"

如果 A 失败、B 成功，说明 CLI 本身不是完全坏掉，问题更可能在某条 provider 链路。

9.6 纵向测试版本

npx -y @anthropic-ai/claude-code@<VERSION> -p "只回复 OK"

找到最后一个已知可用版本，再决定是否固定。

9.7 最后才动全局配置

只有当你已经知道“哪个 provider / 哪个版本 / 哪个 endpoint 可用”时，再改全局配置。改完之后必须复测默认调用。

10. 对模型网关维护者的建议

如果你维护的是企业内部模型网关、token 平台或 Anthropic-compatible endpoint，这类问题值得专门加回归测试。

建议至少覆盖这些场景：

  1. 顶层 system 参数，而不是只测 messages.role=system。
  2. 多轮 user / assistant 消息。
  3. 空 system、长 system、带换行的 system。
  4. tools / tool use / tool result。
  5. streaming 和非 streaming。
  6. thinking / reasoning 字段，尤其是不同客户端可能使用不同开关。
  7. Claude Code CLI 的最新版本和至少一个固定旧版本。
  8. 错误返回格式，确保客户端能看到有用信息。

最小测试可以非常简单：

claude -p "reply exactly: OK"

但只有这个还不够。Agent 客户端的真实请求通常比普通 chat 更复杂，系统提示、工具定义、权限上下文和会话元数据都会进入请求。兼容层不能只用 curl 测一个 messages 数组就宣布“兼容 Anthropic”。

11. Q&A

Q1：为什么错误说 system role，但你说 Anthropic 里 system 是顶层字段？

正因为 Anthropic Messages API 和 OpenAI Chat Completions 的系统提示语义不一样，兼容层才容易在这里出错。Claude Code 发出的可能是合法的 Anthropic 风格请求，但网关内部转换时把 system 放到了某个后端 chat content 里，或者没有正确处理新版请求结构，于是下游校验层报了 invalid message role: system。

Q2：这是不是说明 Claude Code 2.1.156 一定有 bug？

不能这么下结论。现场证据只能证明：在这个兼容网关路径上，2.1.156 会失败，2.1.150 能成功。它可能是 Claude Code 请求结构变化，也可能是网关只适配了旧结构，还可能是双方边界条件没有覆盖。对用户来说，先恢复可用；对网关维护者来说，再做协议级修复。

Q3：为什么不直接换到能用的 provider？

如果业务上不依赖当前 provider，切换 provider 是最快 workaround。但有些环境里，当前 provider 可能承担统一鉴权、额度、审计、成本控制或特定模型接入，不能随便换。本文选择固定 2.1.150，是因为它能在保持当前 provider 的前提下恢复可用。

Q4：固定旧版本会不会有风险？

会。旧版本可能缺少新功能、修复或安全改进。所以固定版本应该被视为临时止血，不是长期答案。长期应由兼容网关适配新版 Claude Code，或者切换到已经适配的 provider。固定版本时，建议把原因写进团队文档，避免别人随手升级又踩同一个坑。

Q5：我怎么防止 npm 自动装回最新版？

如果你是全局安装，可以明确安装版本：

npm install -g @anthropic-ai/claude-code@2.1.150

如果是团队环境，可以在安装脚本、镜像构建脚本或开发机 bootstrap 脚本里固定版本，并在升级前跑最小 prompt 回归测试。

Q6：如果我没有 provider 切换工具怎么办？

直接看 ~/.claude/settings.json、shell 环境变量和启动脚本。重点找 ANTHROPIC_BASE_URL。如果它不是官方默认入口，而是某个自定义地址，就把它当成兼容网关处理。然后用不同 Claude Code 版本做纵向测试。

Q7：是不是所有 Anthropic-compatible endpoint 都会遇到？

不是。现场测试里就有其他 provider 能正常返回 OK。问题取决于具体网关如何实现请求转换、它支持到哪一版客户端行为、以及后端模型服务的消息 role 校验规则。

12. 复盘：这次真正有用的不是“降级”，而是证据链

最终修复只是一行命令：

npm install -g @anthropic-ai/claude-code@2.1.150

但这篇文章想强调的不是“遇事就降级”。真正有价值的是这条证据链：

  1. 最小 prompt 复现，排除项目和会话因素。
  2. 确认当前 Claude Code 版本，建立时间线。
  3. 检查 ANTHROPIC_BASE_URL，确认请求经过兼容网关。
  4. 横向测试 provider，证明不是所有路径都坏。
  5. 纵向测试版本，找到最后一个已知可用版本。
  6. 固定版本并复测显式模型和默认模型。

AI Agent 工具链越强，链路就越长。以后类似问题会越来越多：表面是模型报错，实际可能是网关；表面是网关报错，实际可能是客户端版本；表面是客户端版本，实际可能是某个协议字段的语义差异。

遇到这类问题时，最重要的不是马上改，而是先把“错误发生在哪一层”钉住。只要层次钉住了，修复往往并不复杂。

参考资料

  1. Anthropic Messages API 文档：https://docs.anthropic.com/en/api/messages
  2. Claude Code settings 文档：https://docs.anthropic.com/en/docs/claude-code/settings
  3. Claude Code release notes：https://docs.anthropic.com/en/release-notes/claude-code
  4. @anthropic-ai/claude-code npm 包：https://www.npmjs.com/package/@anthropic-ai/claude-code
  5. MiniMax 文生图 API 参考，本文题图使用本地 CLI 调用生成：https://platform.minimaxi.com/docs/api-reference/image-generation-t2i