网关对 Claude Code 的契约:十件会让它卡住或静默出错的事
- 一张表看十个坑
- 1. 余额耗尽回 429:一次欠费卡住 181 秒
- 2. 改写超长报错原文:自动压缩彻底失效
- 3. 吞掉被拒字段名与 Beta 名:客户端没法「去掉重发」
- 4. 保活 : PING 之后的报错写成了裸 JSON
- 5. 多渠道轮询打散会话:thinking 签名报错与缓存重算
- 6. 流式帧经 DTO 重序列化:新响应字段被悄悄抹平
- 7. thinking 子键在归一化时丢失
- 8. 响应里的 model 和请求名不一致:反复压缩与 /effort 失灵
- 9. 后台结构化输出拼写差异与工具结果里的截图
- 10. 静默删参数,以及在无 none 档的 GPT-6 上硬塞 reasoning_effort
- 小结:把网关当成协议契约来写
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):
- 按协议区分余额与预算类错误的状态码:在
/v1/messages上照 Anthropic 官方行为返回 HTTP402(billing_error),在 OpenAI 与 Gemini 协议上保留429(insufficient_quota)。 - 在所有充值前不可能自愈的错误出口(网关预检、转发器、流尚未开始前的错误写出器)统一加上响应头:
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 模型时,有两个高频边角案例最容易在半途打断会话:
- 后台请求的结构化输出拼写: 会话自动起标题、记忆召回和 prompt hook 请求可能使用顶层
output_format,而正文接口文档主推output_config.format。如果协议解码器只认后者,并遵守「未知字段拒绝而非静默丢弃」的原则,所有后台标题请求都会回400。 - 工具返回里的截图: 用户在会话第 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)。
小结:把网关当成协议契约来写 #
复盘这十个问题,背后其实只有三条简单的工程准则:
- 客户端用来做控制流判断的信号(402、
x-should-retry、超长与字段校验句式、event: error、message.model)也是协议契约的一部分,不能为了报错文案「好看」就随手改写。 - 原生路径尽量做零损耗字节转发,跨协议桥接坚持「不能等价转换就前置明确拒绝,有损降级必写
X-Lazu-Warning」,详见仓库里的架构文档docs/protocol-conversion-architecture.md。 - 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