网关对 Claude Code 的契约:十件会让它卡住或静默出错的事

Guide 网关对 Claude Code 的契约 claude-opus-5-5claude-sonnet-5-5 Lazu

Molly 整理 · Lazu 团队

先说结论:把 Claude Code 的 ANTHROPIC_BASE_URL 指向自己的网关时,光实现 Anthropic Messages 接口的文档字段还不够。在 Claude Code 2.1.257 到 2.1.317 的迭代里,客户端新增了一整套自愈与状态管理逻辑——什么时候自动压缩上下文、什么时候去掉不兼容的字段重发、什么时候停止重试、怎么按模型名记 /effort 档位。这些判断大多依赖状态码、响应头和报错原文里的精确字面量。

2026 年 11 月初,我们把 Lazu 的请求链路逐行对照 Claude Code 的行为做了一次审计,发现有十处地方虽然网关逻辑「自洽」,却会让 Claude Code 卡住重试、自动压缩失效,或者在多轮工具调用里静默丢掉 thinking 与缓存。相关修复已在 v0.7.273(#179、#180、#181)及后续补丁(#208)上线。

这篇把十个真实踩过的坑和修法整理成一份清单。无论你是在自托管 Lazu、维护自己的网关,还是排查 Claude Code 接第三方接口时的怪现象,都可以直接对照检查。

一张表看十个坑 #

编号 场景 网关常见做法 Claude Code 的实际表现 正确做法
1 余额或 Key 预算耗尽 一律回 429 insufficient_quota 当成限流退避重试 10 次,卡住约 3 分钟才报错 /v1/messages 回 402 billing_error 并带 x-should-retry: false
2 上下文超出窗口上限 改写成网关统一模板文案 认不出超长,不触发自动 /compact,直接中断 保留或重渲染 prompt is too long: N tokens > M maximum
3 上游拒绝 context_management 或某个 anthropic-beta 改写成泛化的 400 bad_request 不知道该删哪个字段或 beta,无法自愈重发 保留字段路径 Extra inputs are not permitted 与具体 beta 名
4 SSE 保活 : PING 发出后上游报错或超时 直接往流里写裸 JSON 200 流被截断,客户端收不到结构化错误 已提交流头后统一写 event: error 标准帧
5 多渠道或多 Key 池轮询选路 每一轮独立随机分流 跨账号后 thinking 签名失效 400 或静默丢失,缓存每轮重算 按 (用户, 会话 ID, 模型) 做会话到渠道与 Key 的亲和
6 原生流式响应经固定结构体反序列化再写出 DTO 未建模字段被过滤 diagnostics、stop_details 与新 usage 子字段静默丢失 原生 Messages 流透传上游原始帧,只补缺失用量与模型名
7 thinking 配置经三字段结构体归一化 未知子键在重序列化时丢失 block_binding、between_tools 等新控制项失效 保留 thinking 对象中 DTO 未建模的原始键值
8 响应里的 model 原样回上游渠道内部名 返回带日期、前缀或圆点的 ID 反复触发压缩,或把新模型误判成不支持 /effort message_start.message.model 与非流响应统一回写客户端请求名
9 后台标题任务发顶层 output_format;跨协议桥接遇截图 当成未知字段拒 400;整轮历史因单张工具图失败 会话标题与 hook 静默失败;读过一次图片后整场会话报错 同时解析顶层 output_format;非视觉模型桥接时剥离工具结果图并写警告头
10 删掉不支持的 speed;跨协议调推理模型工具 静默删字段;在 Chat 上误注 reasoning_effort: "none" 以为跑在 fast 实际是标准档;gpt-6.1-sol 等报 400 删字段必写 X-Lazu-Warning;无 none 档的 GPT-6 工具请求改走 Responses

1. 余额耗尽回 429:一次欠费卡住 181 秒 #

很多兼容 OpenAI 的网关把账户余额不足、项目预算触顶、Key 额度用完统一映射成 HTTP 429(insufficient_quota)。Codex 看到 429 配 insufficient_quota 会立刻停下,但 Claude Code 把没有明确禁止重试标记的 429 一律当成速率限制(Rate Limit),按指数退避连续重试。

我们在 Claude Code 2.1.317 上实测:一个余额为 0 的账户发出一句请求,客户端连发 11 次请求、耗时 181 秒,最后才把充值提示打印出来。

修法(#180):

  1. 按协议区分余额与预算类错误的状态码:在 /v1/messages 上照 Anthropic 官方行为返回 HTTP 402(billing_error),在 OpenAI 与 Gemini 协议上保留 429(insufficient_quota)。
  2. 在所有充值前不可能自愈的错误出口(网关预检、转发器、流尚未开始前的错误写出器)统一加上响应头:
HTTP/1.1 402 Payment Required
x-should-retry: false
Content-Type: application/json

上线后再测同一场景,请求从 11 次 / 181 秒 降到 1 次 / 0.4 秒,客户端立即停下并显示余额提示。

2. 改写超长报错原文:自动压缩彻底失效 #

从 2.1.285 起,Claude Code 在自定义网关后默认按 1M 上下文窗口计算,并在会话接近或超过真实渠道上限时靠自动压缩(Auto-compact)续命。问题在于,它识别「上下文超长」靠的不是你自定义的错误码,而是匹配 Anthropic 标准文案:

prompt is too long: 214530 tokens > 200000 maximum

Lazu 原本有两处好心办坏事:

  • 网关前置上下文检查在超限时返回 400 protocol_bridge_unsupported,文案写的是 "estimated input tokens N exceed channel context limit M";
  • 上游真的返回 "prompt is too long"(或 Bedrock 后端返回 "Input is too long")时,错误目录把它统一替换成了对人类友好的模板句 "The input exceeds this model's context window..."。

结果就是:长度判断完全正确,但 Claude Code 认不出这是超长错误,直接放弃自动压缩并把错误抛给用户。

修法(#181): 无论拒绝来自网关前置估算、上游同步 400 还是流内错误,只要归类为 context_length_exceeded,一律提取实际的 token 数与上限,按 prompt is too long: N tokens > M maximum 格式重渲染。既不裸透传上游内部信息,又让客户端稳定触发自动压缩。

3. 吞掉被拒字段名与 Beta 名:客户端没法「去掉重发」 #

从 2.1.275 到 2.1.314,Claude Code 陆续默认带上了 context_management 和一串新的 anthropic-beta 头(如 effort-2025-11-24、compact-2026-09-04、inline-tools-2026-09-15)。考虑到自定义网关背后的上游未必同步支持所有新特性,Claude Code 做了一套很实用的降级机制:如果网关返回的 400 写明了哪个字段或哪个 beta 不被接受,客户端就把它从本次会话里摘掉,立刻重发。

前提是网关不能把报错糊成一团。如果网关把上游的校验错误统一洗成 "The request body is malformed" 或 "Upstream rejected a beta feature",客户端拿不到字段路径和 beta 名字,自愈逻辑就一步也走不动。

修法(#181): 从上游拒绝信息中提取受控的字段路径与 beta 标识符,按标准句式重渲染:

  • 多余字段:<field>: Extra inputs are not permitted
  • 不支持的 beta:Unexpected value(s) '<name>' for the 'anthropic-beta' header

4. 保活 : PING 之后的报错写成了裸 JSON #

长上下文预填(Prefill)在几十万 token 无缓存时很容易超过 15 秒。为了防止中间网络断开,Lazu 每 15 秒向流式连接写一行 SSE 注释 : PING。

隐患出在顺序上:第一行 : PING 发出的那一刻,HTTP 响应头 200 OK 和 Content-Type: text/event-stream 就已经提交给客户端了。 如果第 25 秒上游返回 400,或者第 90 秒触发首字节超时,错误处理函数如果没检查响应头是否已写出,直接调 c.JSON(...) 往连接里塞一段裸 JSON,客户端收到的就是几行 : PING 后面跟一行不带 data: 前缀的非法文本,随后断流。

修法(#181): 在 /v1/messages 流式路径上,一旦响应已经开始写出,任何后续错误都封装成合法的 Anthropic SSE 错误事件帧再结束流:

event: error
data: {"type":"error","error":{"type":"api_error","message":"..."}}

5. 多渠道轮询打散会话:thinking 签名报错与缓存重算 #

单个请求无状态转发在聊天时代没问题,但对编程 Agent 有严重副作用。Claude 5.x 系列的 thinking 块签名、Prompt Cache 前缀以及服务端会话状态都绑定在生成它们的上游账号上:

  • 同一场会话如果第 1 轮落在渠道 A,第 2 轮按权重随机落到渠道 B(或同一渠道池里的另一把上游 Key),claude-haiku-5-5 等模型会因为 thinking 签名与账号不匹配直接回 400;
  • claude-sonnet-5-5 在部分跨账号场景下不会报错,而是静默丢弃上一轮的 thinking 上下文;
  • 本该按缓存读取计价的几十万 token 系统提示词与代码树,每一轮都要重新付一次缓存写入或全额输入费用。

修法(#179): 引入会话到渠道与上游 Key 的亲和路由(session_affinity)。网关从 Claude Code 的 X-Claude-Code-Session-Id(以及 Codex、OpenCode、Goose 等各自的会话头)提取会话标识,按 (用户, 会话 ID, 解析后模型) 在 Redis 中记录上一轮成功响应的渠道与具体 Key,有效期 1 小时并在每次命中时续期。只有在该渠道被禁用、进入熔断退避或协议规划无法无损承载当前请求时,路由器才会平滑切到备选渠道,并在成功后把会话迁移过去。

6. 流式帧经 DTO 重序列化:新响应字段被悄悄抹平 #

非流式响应大家通常原样转发字节流,但流式响应往往为了统计 token 用量,把每一个 SSE data: 帧反序列化进 Go 的 ClaudeResponse 结构体,改完再 json.Marshal 写回客户端。

只要结构体字段是静态列举的,Anthropic 每次在流事件里新增字段——比如缓存诊断 diagnostics、stop_details、响应侧的 context_management、或者 usage 下新出的细分计数——都会在重序列化时被无声抹掉。测试全绿,对话看似正常,但客户端依赖的诊断与停止原因全没了。

修法(#181): 原生 /v1/messages 流不再把整帧结构体反序列化后再编码,而是直接转发上游原始帧字节;只在 message_start 上按需修正 message.model,并在上游缺失 token 统计时做最小补齐。

7. thinking 子键在归一化时丢失 #

同类问题也出在请求侧的 thinking 对象上。如果网关用只含 {type, budget_tokens, display} 三个字段的结构体去接 thinking,再写回请求体,像 block_binding 这类新增控制键就会在经过网关时消失,而 thinking.type: "between_tools" 也可能被旧规则误改。

修法(#181): 在归一化 thinking 时保留未知原始键值,只修改明确需要受控的预算或兼容开关,不替客户端删减新协议字段。

8. 响应里的 model 和请求名不一致:反复压缩与 /effort 失灵 #

网关做渠道转发时,上游经常返回带日期后缀的名字(如 claude-sonnet-5-5-20260929)、带厂商前缀的名字(anthropic/...),或者客户端请求时带了 -thinking 后缀而网关发给上游时剥掉了它。

在 Claude Code 2.1.301 到 2.1.314 里,客户端会拿响应里的 model 去查上下文窗口表和推理档位支持表:

  • 响应模型名对不上时,上下文比例算错,可能触发反复压缩;
  • 带前缀或圆点的模型 ID 会让客户端误判该模型不支持 /effort,把用户设好的推理档位锁死。

修法(#181): 无论渠道是否配置了模型映射表,/v1/messages 的非流响应 model 与流式首帧 message_start.message.model 一律回写客户端请求时填写的模型名。

9. 后台结构化输出拼写差异与工具结果里的截图 #

当你用 Claude Code 跨协议接 GPT 或 DeepSeek 模型时,有两个高频边角案例最容易在半途打断会话:

  1. 后台请求的结构化输出拼写: 会话自动起标题、记忆召回和 prompt hook 请求可能使用顶层 output_format,而正文接口文档主推 output_config.format。如果协议解码器只认后者,并遵守「未知字段拒绝而非静默丢弃」的原则,所有后台标题请求都会回 400。
  2. 工具返回里的截图: 用户在会话第 3 轮让 Claude Code 读了一张报错截图,tool_result 里就会留下一块图片内容。如果第 10 轮切到一个纯文本编码模型,整场会话后续每一轮都会因为历史里那张旧图片被上游拒绝。

修法(#181): 解码器将顶层 output_format 作为 output_config.format 的等价入口解析进中间表示(IR),并把请求体里的 diagnostics 视为提示性字段;当目标模型目录声明不支持图像输入时,桥接器只将 tool_result 中的图片替换成明确说明文字,同时在响应头写下 X-Lazu-Warning: omitted:tool_result_image(用户主动发送的图片仍按原规则严格校验,绝不静默吞掉)。

10. 静默删参数,以及在无 none 档的 GPT-6 上硬塞 reasoning_effort #

最后两件事关乎网关的边界感:做不到的事要直说,替客户端补默认值得看准模型能力。

  • 删掉的字段要留痕: 渠道没开极速模式(speed: "fast")时,如果网关直接删掉 speed 转发,用户以为自己跑在 fast 档,实际拿到标准速度却毫不知情。现在凡是渠道策略剥离的字段,Lazu 都会在响应头标出 X-Lazu-Warning: field_dropped:speed(#181)。
  • GPT-6 家族的工具与推理分流: 用 Claude Code 调 GPT-6 系列模型时,OpenAI 的 /v1/chat/completions 接口拒绝在开启推理的同时调用函数工具。其中 gpt-6-luna、gpt-6-sol 支持传 reasoning_effort: "none" 关闭推理,但 gpt-6.1-sol、gpt-6.2-sol、gpt-6-astra 等纯推理型号最低只接受 "low",网关一旦在 Chat 路径上替它注入 "none" 就会立刻撞上 400。修法是让协议规划器读取目录中的推理开关(CanDisableReasoning):凡是渠道支持 /v1/responses 的,Claude Code 发往纯推理 GPT-6 模型的工具调用一律改走原生支持「推理 + 工具并行」的 Responses 接口,不再往 Chat Completions 上硬挤(#208)。

小结:把网关当成协议契约来写 #

复盘这十个问题,背后其实只有三条简单的工程准则:

  1. 客户端用来做控制流判断的信号(402、x-should-retry、超长与字段校验句式、event: error、message.model)也是协议契约的一部分,不能为了报错文案「好看」就随手改写。
  2. 原生路径尽量做零损耗字节转发,跨协议桥接坚持「不能等价转换就前置明确拒绝,有损降级必写 X-Lazu-Warning」,详见仓库里的架构文档 docs/protocol-conversion-architecture.md。
  3. Agent 流量是有状态的会话,不是孤立的单轮问答,选路器必须尊重 thinking 签名与缓存前缀所在的账号边界。

上面的全部代码与单测都在开源仓库 lazu-ai/lazu 中。如果你想直接用已经调好这套契约的托管环境,拿一把 Key 就能把 Claude Code 接上 claude-opus-5-5、claude-sonnet-5-5 或跨协议模型:

export ANTHROPIC_BASE_URL=https://api.lazu.ai
export ANTHROPIC_AUTH_TOKEN=sk-lazu-...
claude
相关文章
2026-11-18OpenCode 接入第三方模型:一把 Key 切换 Claude、GPT 与 DeepSeek 2026-09-30国内怎么用 Claude API:直连、支付宝充值与价格 2026-09-30Claude Code 接入第三方 API:用 Lazu 配置 Opus、Sonnet、Haiku 5.5

拿一个 Key 试试

免费开始