<!-- Lazu · 网关对 Claude Code 的契约：十件会让它卡住或静默出错的事 · https://lazu.ai/zh/blog/claude-code-gateway-contract -->

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

2026-11-18 · 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](https://github.com/lazu-ai/lazu/pull/179)、[#180](https://github.com/lazu-ai/lazu/pull/180)、[#181](https://github.com/lazu-ai/lazu/pull/181)）及后续补丁（[#208](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/180)）：**

1. 按协议区分余额与预算类错误的状态码：在 `/v1/messages` 上照 Anthropic 官方行为返回 HTTP `402`（`billing_error`），在 OpenAI 与 Gemini 协议上保留 `429`（`insufficient_quota`）。
2. 在所有充值前不可能自愈的错误出口（网关预检、转发器、流尚未开始前的错误写出器）统一加上响应头：

```http
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 标准文案：

```text
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](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/181)）：** 在 `/v1/messages` 流式路径上，一旦响应已经开始写出，任何后续错误都封装成合法的 Anthropic SSE 错误事件帧再结束流：

```text
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](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/181)）：** 原生 `/v1/messages` 流不再把整帧结构体反序列化后再编码，而是直接转发上游原始帧字节；只在 `message_start` 上按需修正 `message.model`，并在上游缺失 token 统计时做最小补齐。

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

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

**修法（[#181](https://github.com/lazu-ai/lazu/pull/181)）：** 在归一化 `thinking` 时保留未知原始键值，只修改明确需要受控的预算或兼容开关，不替客户端删减新协议字段。

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

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

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

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

**修法（[#181](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/208)）。

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

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

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

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

```bash
export ANTHROPIC_BASE_URL=https://api.lazu.ai
export ANTHROPIC_AUTH_TOKEN=sk-lazu-...
claude
```
