自建网关接入 Codex CLI 与 Claude Code：base_url 与协议踩坑全解析

1. 为什么自建网关接入 CLI 工具总在 base_url 上翻车

把 Codex CLI 或者 Claude Code 这类命令行 AI 编程助手接到自建网关，听起来就是把base_url一改、api_key一填的事。但真正动过手的人都知道，这一步能卡掉大半天。我自己前前后后配过五六套不同的网关环境，从最简单的反向代理到带鉴权、带路由、带协议转换的中间层，几乎每一种都在base_url和协议细节上踩过坑。

先说清楚这篇要解决什么问题。Codex CLI 和 Claude Code 本质上都是客户端，它们默认会去请求官方托管的接口地址。而自建网关的核心价值在于：把请求收敛到自己可控的入口，做统一鉴权、日志审计、多模型路由、成本统计，或者在内网环境下隔离外部依赖。一旦你决定走自建网关，客户端发出的每一个请求——包括路径、请求头、请求体格式、流式响应的解析方式——都必须和网关的预期严丝合缝地对上，否则就是各种 404、401、400 甚至"请求发出去了但一直转圈"。

这里最容易出问题的就是base_url。很多人以为它就是一个"域名前缀"，填个https://gateway.example.com就完事。实际上base_url的语义在不同工具里差别很大：有的工具会自己在后面拼/v1/messages，有的会拼/v1/chat/completions，还有的会拼/v1/responses。你填的base_url到底该不该带/v1，取决于工具内部拼接逻辑，填错一层就是 404。

另一个高频翻车点是协议。Codex CLI 走的是 OpenAI 风格的接口协议，Claude Code 走的是 Anthropic 风格的接口协议，两者在请求体结构、鉴权头字段、流式事件格式上都不一样。如果你的网关只支持其中一种，另一种接上去就会报格式错误。很多人图省事，用一个"兼容层"网关同时接两种协议，结果发现流式输出时事件类型对不上，客户端直接卡死或者只吐一半内容。

这篇内容适合三类人看：第一类是自己搭了网关、想把 CLI 工具接进来的开发者；第二类是运维或平台同学，要给团队统一提供 AI 编程助手的入口；第三类是纯粹被base_url和协议问题折磨过、想搞清楚底层逻辑的人。我会把踩坑的完整链路、每个参数的来龙去脉、以及实测可用的配置方式都摊开讲，尽量让你少走我走过的弯路。

提示：本文讨论的所有网关均为自建、内网或私有部署场景，不涉及任何第三方托管服务的具体配置。所有示例域名、路径均为虚构代称，请根据自己实际环境替换。

2. base_url 的拼接逻辑：多一层少一层都是 404

2.1 客户端到底在 base_url 后面拼了什么

要搞清楚base_url怎么填，第一步是弄明白客户端内部到底怎么拼路径。我一开始也懒得看，直接凭感觉填，结果连续 404 了七八次才回头去翻源码和抓包。结论是：不同工具、不同版本，拼接规则不一样，而且有些工具会在文档里写得含糊其辞。

以 Codex CLI 为例，它默认请求的是 OpenAI 风格的接口。当你设置base_url后，它通常会在后面拼接/v1/responses或/v1/chat/completions（取决于具体调用模式）。也就是说，如果你填的base_url是https://gateway.example.com/v1，最终请求路径可能变成https://gateway.example.com/v1/v1/responses，多了一层/v1，网关自然找不到路由。

Claude Code 这边则是 Anthropic 风格，默认拼接的是/v1/messages。同样地，如果你在base_url里已经带了/v1，就会变成/v1/v1/messages。

我实测下来最稳妥的做法是：先抓包，再填值。具体操作是先把base_url指向一个本地能打印请求日志的临时服务（比如用一个最简单的 HTTP 服务把收到的路径和请求头打出来），然后运行一次 CLI 工具，看它实际请求的完整路径是什么。拿到真实路径后，再反推base_url应该填到哪一层。

下面这张表是我实测几种常见填法和最终请求路径的对应关系，供你对照：

工具	base_url 填法	实际请求路径	结果
Codex CLI	https://gw.example.com	https://gw.example.com/v1/responses	正常
Codex CLI	https://gw.example.com/v1	https://gw.example.com/v1/v1/responses	404
Claude Code	https://gw.example.com	https://gw.example.com/v1/messages	正常
Claude Code	https://gw.example.com/v1	https://gw.example.com/v1/v1/messages	404
Claude Code	https://gw.example.com/api	https://gw.example.com/api/v1/messages	取决于网关路由

注意：上表是常见版本的实测结果，不同版本可能有差异。核心原则是"base_url 只填到域名或网关路由前缀，不要带协议版本号"，除非你的网关明确要求带。

2.2 网关侧的路由设计：怎么接住客户端的拼接

理解了客户端怎么拼，网关侧的路由就好设计了。我的建议是网关不要假设客户端会拼什么，而是把常见路径都显式注册一遍。比如同时注册/v1/responses、/v1/chat/completions、/v1/messages三个路由，分别转发到对应的后端处理逻辑。这样无论客户端拼哪一层，都能被接住。

如果你用的是 Nginx 做反向代理，一个常见的坑是proxy_pass结尾有没有斜杠。带斜杠和不带斜杠，转发后的路径完全不一样。比如：

location /v1/ { proxy_pass https://backend.example.com/; }

这种写法会把/v1/messages转发成https://backend.example.com/messages，把/v1前缀吃掉。而如果写成proxy_pass https://backend.example.com（不带结尾斜杠），则会保留完整路径转发成https://backend.example.com/v1/messages。这个细节我在第一次配的时候完全没注意，导致后端一直收到缺前缀的路径，排查了半天才发现是 Nginx 的斜杠问题。

2.3 一个可复用的 base_url 排查流程

踩了多次坑之后，我总结出一套固定的排查流程，基本能在十分钟内定位问题：

1. 确认客户端版本：不同版本的拼接逻辑可能不同，先--version看一眼。
2. 本地抓包：把base_url指向本地临时服务，打印完整请求路径和请求头。
3. 对照网关路由：看网关注册了哪些路径，和实际请求路径是否匹配。
4. 检查代理层：如果中间有 Nginx 或其他反向代理，检查proxy_pass的斜杠和路径重写规则。
5. 逐层验证：先用curl直接打网关，确认网关本身能通，再让客户端打网关。

这套流程的核心思路是把"客户端到网关"和"网关到后端"两段分开验证，不要混在一起调。很多人一上来就端到端测，结果不知道问题出在哪一段，来回改配置反而越改越乱。

3. 协议差异：OpenAI 风格和 Anthropic 风格到底差在哪

3.1 请求体结构：一个用 messages，一个也用 messages 但字段不同

很多人以为 OpenAI 和 Anthropic 的接口都是messages数组，应该差不多。实际用起来才发现，字段名、嵌套结构、必填项都不一样。

OpenAI 风格的请求体大致是这样：

{ "model": "gpt-4o", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello"} ], "stream": true }

Anthropic 风格的请求体则是这样：

{ "model": "claude-3-5-sonnet", "system": "You are a helpful assistant.", "messages": [ {"role": "user", "content": "Hello"} ], "max_tokens": 1024, "stream": true }

几个关键差异：Anthropic 的system是顶层字段，不是放在messages里的；Anthropic必须指定max_tokens，不指定直接报错；OpenAI 的system是作为messages里的一条消息。如果你的网关只做简单转发，不做协议转换，那客户端发什么格式，后端就得支持什么格式。如果后端只支持一种，另一种就会 400。

我遇到过一个典型场景：网关后端接的是一个只支持 OpenAI 格式的推理服务，但团队里有人用 Claude Code，发出来的是 Anthropic 格式。结果就是请求体里system字段位置不对、缺max_tokens，后端直接拒绝。解决办法是在网关层加一个协议转换中间件，把 Anthropic 格式转成 OpenAI 格式再转发。

3.2 鉴权头：x-api-key 和 Authorization 不能混

鉴权头是另一个高频翻车点。OpenAI 风格用的是Authorization: Bearer <token>，Anthropic 风格用的是x-api-key: <token>。有些网关只检查其中一种，另一种就直接 401。

更麻烦的是，有些客户端在设置api_key后，会同时带上两种头，或者带一种但格式不对。我见过一个案例：客户端配置里填了 key，但网关日志显示收到的Authorization头是空的，只有x-api-key有值。原因是这个客户端版本对 Anthropic 协议只发x-api-key，而网关只认Authorization。最后是在网关侧同时兼容两种头才解决。

我的建议是：网关侧对鉴权头做兼容处理，两种都认。具体逻辑是优先读Authorization，如果没有再读x-api-key，两者取到任意一个有效 token 就放行。这样无论客户端发哪种，都能正常工作。

3.3 流式响应：SSE 事件格式的坑最深

流式响应是协议差异里最隐蔽、最难排查的部分。两种协议都用 SSE（Server-Sent Events），但事件格式不一样。

OpenAI 风格的流式响应大致是：

data: {"choices":[{"delta":{"content":"Hello"}}]} data: [DONE]

Anthropic 风格的流式响应则是：

event: content_block_delta data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Hello"}} event: message_stop data: {"type":"message_stop"}

差异很明显：Anthropic 有event:行，事件类型在type字段里；OpenAI 没有event:行，结束标志是[DONE]。如果网关做协议转换时只转data不转event，或者结束标志没对上，客户端就会一直等，表现为"输出到一半卡住"或者"一直转圈不出内容"。

我踩过最坑的一次是：网关把 Anthropic 的流式响应转成 OpenAI 格式时，忘了把message_stop转成[DONE]。结果 Claude Code 收到流结束后还在等[DONE]，界面一直显示加载中，实际上后端早就返回完了。这种问题抓包一看就清楚，但不抓包的话很难想到是结束标志的问题。

提示：调试流式响应时，建议在网关侧把原始 SSE 流完整打印出来，逐行对比客户端期望的格式。不要只看"有没有返回内容"，要看"结束标志对不对"。

4. 网关选型与配置：几种常见方案的实测对比

4.1 直接反向代理：最简单但最不灵活

最省事的方案是用 Nginx 或 Caddy 做纯反向代理，把客户端的请求原样转发到后端。这种方案适合"后端本身就支持客户端协议"的场景，比如后端就是一个兼容 OpenAI 协议的服务，客户端也是 OpenAI 风格，那直接转发就行。

优点是配置简单、性能好、没有额外依赖。缺点是没有任何协议转换能力，一旦客户端和后端协议不一致，就无能为力。而且鉴权、日志、限流这些都得靠 Nginx 自己配，稍微复杂一点的需求就要写 Lua 或者上 OpenResty。

我用这种方案接过一次纯 OpenAI 风格的场景，配置大概是这样：

location /v1/ { proxy_pass https://backend.example.com; proxy_set_header Authorization $http_authorization; proxy_set_header x-api-key $http_x_api_key; proxy_buffering off; proxy_cache off; }

关键是proxy_buffering off，流式响应必须关掉缓冲，否则客户端会等到整个响应结束才收到内容，流式就失去意义了。

4.2 带协议转换的中间层：灵活但要多写代码

如果客户端和后端协议不一致，就需要一个中间层做转换。我一般用 Python 的 FastAPI 或者 Node.js 的 Express 写一个轻量服务，接收客户端请求，转换成后端格式，再把响应转回来。

这种方案的核心工作量在流式转换上。因为流式响应是逐块到达的，你不能等整个响应收完再转换，必须边收边转边发。实现时要注意几点：一是保持 SSE 的data:前缀和空行分隔；二是正确处理结束标志；三是转换过程中如果出错，要能优雅地结束流而不是直接断开。

我写过一个 Anthropic 转 OpenAI 的中间层，核心逻辑大概是：收到 Anthropic 请求后，把system字段提到messages开头，补上默认max_tokens，把x-api-key转成Authorization；响应侧则把content_block_delta转成choices[].delta.content，把message_stop转成[DONE]。这套逻辑跑通之后，Claude Code 就能正常走 OpenAI 后端了。

4.3 几种方案的成本与适用场景对比

方案	配置复杂度	协议转换	适用场景	维护成本
纯反向代理	低	不支持	客户端后端协议一致	低
中间层转换	中高	支持	协议不一致、需统一入口	中
网关框架	中	插件支持	多模型、多租户、需审计	中高
自研服务	高	完全可控	特殊需求、深度定制	高

选型时我的经验是：先用最简单的方案跑通，再按需加复杂度。很多人一上来就上重型网关框架，结果配置项一大堆，光搞清楚每个插件干嘛的就花了两天，最后发现其实一个 Nginx 加几行配置就够了。反过来，如果你的场景确实需要多模型路由、按用户限流、成本统计，那早点上框架反而省事。

5. 实测踩坑链路：从 404 到流式卡死的完整排查

5.1 第一坑：base_url 多带了一层 /v1

最开始我把base_url填成了https://gw.example.com/v1，心想"接口都是 /v1 开头的，带上肯定没错"。结果客户端请求的是/v1/v1/messages，网关返回 404。当时第一反应是网关路由没配好，查了半天路由配置，最后抓包才发现是路径多了一层。

这个坑的本质是没有搞清楚 base_url 的语义边界。base_url 是"基础地址"，客户端会在这个基础上拼具体路径。你把版本号也塞进 base_url，就等于让客户端拼出重复的版本号。正确做法是 base_url 只填到域名或网关前缀，版本号交给客户端拼。

5.2 第二坑：鉴权头对不上导致 401

路径修好之后，紧接着就是 401。网关日志显示请求进来了，但鉴权失败。抓包一看，客户端发的是x-api-key，而网关只检查Authorization。这个问题的根源是客户端协议风格和网关鉴权逻辑不匹配。

解决办法有两种：一是改客户端配置，让它发Authorization（但有些客户端不支持改）；二是在网关侧兼容两种头。我选了第二种，因为改网关比改客户端可控。兼容逻辑很简单：先读Authorization，读不到再读x-api-key，任意一个有有效值就放行。

5.3 第三坑：请求体缺 max_tokens 被后端拒绝

鉴权过了之后，后端返回 400，提示缺max_tokens。这是因为 Claude Code 发的是 Anthropic 格式，而我的后端是 OpenAI 风格，OpenAI 风格里max_tokens是可选的，但 Anthropic 格式里是必填的。中间层转换时如果没补这个字段，后端就会因为请求体不符合预期而拒绝。

这个坑提醒我：协议转换不能只转"看起来不一样"的字段，还要补全"对方必填但自己可选"的字段。Anthropic 的max_tokens、system位置，OpenAI 的messages结构，这些都要在转换时处理到位。

5.4 第四坑：流式响应结束标志没转导致卡死

最隐蔽的是流式卡死。前面都通了，内容也能出来，但输出到一半就停住，界面一直转圈。抓包发现后端已经发完了message_stop，但中间层没把它转成[DONE]，客户端一直在等结束标志。

这个问题的排查难度在于：内容出来了，容易以为已经通了，不会想到是结束标志的问题。我的经验是，调试流式响应时一定要把完整的 SSE 流打出来，逐行看结束标志对不对。OpenAI 的结束标志是data: [DONE]，Anthropic 的是event: message_stop，转换时必须一一对应。

5.5 排查链路总结：分层验证是王道

把这四个坑串起来看，排查链路其实很清晰：先验证路径（404），再验证鉴权（401），再验证请求体（400），最后验证流式（卡死）。每一层验证通过再进下一层，不要跳步。

我后来固定用一套分层验证方法：第一步用curl直接打网关，确认网关本身能通；第二步用curl模拟客户端请求体，确认后端能处理；第三步才让真实客户端接入。这样每层的问题都能单独定位，不会互相干扰。

6. 配置模板与可复用的参数清单

6.1 客户端侧配置要点

Codex CLI 和 Claude Code 的配置方式不太一样，但核心参数就几个：base_url、api_key、model。下面是我实测可用的配置思路（具体字段名以你使用的版本为准）：

对于 Codex CLI，通常通过环境变量或配置文件设置：

export OPENAI_BASE_URL="https://gw.example.com" export OPENAI_API_KEY="your-token"

对于 Claude Code，类似地：

export ANTHROPIC_BASE_URL="https://gw.example.com" export ANTHROPIC_API_KEY="your-token"

关键点是base_url 不带版本号，api_key 填网关认可的 token。如果网关做了鉴权头兼容，两种头都能过。

6.2 网关侧路由与转发清单

网关侧我建议按这张清单逐项检查：

检查项	说明	常见错误
路由注册	注册 /v1/messages、/v1/responses 等	只注册了一种
鉴权兼容	同时认 Authorization 和 x-api-key	只认一种
流式缓冲	关闭 proxy_buffering	开着导致流式失效
超时设置	流式请求超时要够长	默认超时太短导致中断
路径重写	注意 proxy_pass 斜杠	多斜杠或少斜杠
请求体透传	保持原始 JSON 结构	中间件误改字段

6.3 一个最小可用的中间层转换逻辑

如果你需要做协议转换，下面是一个简化的转换逻辑示意（Python 伪代码，仅表达思路）：

def anthropic_to_openai(req): messages = [] if "system" in req: messages.append({"role": "system", "content": req["system"]}) messages.extend(req["messages"]) return { "model": req["model"], "messages": messages, "max_tokens": req.get("max_tokens", 4096), "stream": req.get("stream", False) } def openai_stream_to_anthropic(chunk): # 把 OpenAI 的 delta 转成 Anthropic 的 content_block_delta if chunk == "[DONE]": return "event: message_stop\ndata: {\"type\":\"message_stop\"}\n\n" content = chunk["choices"][0]["delta"].get("content", "") return f"event: content_block_delta\ndata: {{\"type\":\"content_block_delta\",\"delta\":{{\"type\":\"text_delta\",\"text\":\"{content}\"}}}}\n\n"

这段逻辑的核心是请求侧补全字段、响应侧对齐事件格式。实际生产环境还要处理错误、超时、并发等问题，但思路是一致的。

7. 几个只有踩过才知道的细节

7.1 模型名映射不能想当然

客户端配置里填的模型名，和后端实际支持的模型名往往不一样。比如客户端填claude-3-5-sonnet，后端可能只认claude-3-5-sonnet-20241022这种带日期的完整名。如果网关不做映射，请求就会因为模型名不匹配而失败。

我的做法是在网关侧维护一张映射表，把客户端常用的简写映射到后端支持的完整名。这样客户端不用改，后端也不用改，映射逻辑集中在网关。

7.2 超时设置要区分流式和非流式

流式请求的耗时可能很长，尤其是生成长文本时。如果网关或反向代理的超时设置太短，流式响应会在中途被切断，表现为"输出到一半停了"。我一般把流式请求的超时设到 300 秒以上，非流式请求可以短一些。

Nginx 里对应的配置是proxy_read_timeout和proxy_send_timeout，默认 60 秒，流式场景下明显不够。

7.3 日志要打全，但别打敏感信息

调试阶段日志越全越好，请求路径、请求头、请求体、响应状态都打出来。但要注意别把 api_key 完整打进日志，尤其是生产环境。我的做法是日志里只打 key 的前几位和后几位，中间用星号代替，既能定位问题又不泄露。

7.4 版本升级后要重新验证

CLI 工具升级后，拼接逻辑、协议细节都可能变。我遇到过升级后 base_url 拼接规则变了，原来能用的配置突然 404。所以每次升级后，建议重新跑一遍分层验证流程，别假设"以前能用现在也能用"。

8. 写在最后的一点个人体会

这套东西我前后折腾了大概两周，从最开始的一头雾水到后来能快速定位问题，最大的感受是：base_url 和协议问题本质上不是"配置问题"，而是"理解问题"。你只要真正搞清楚了客户端怎么拼路径、怎么发请求、怎么解析响应，剩下的就是按图索骥。

我现在的习惯是，接任何新工具之前，先花十分钟抓个包，把请求路径、请求头、请求体、响应格式都看一遍，再动手配。这十分钟能省掉后面几个小时的瞎猜。另外，分层验证真的能救命，别嫌麻烦，路径、鉴权、请求体、流式一层层过，每层都确认没问题再往下走。

如果你也在接自建网关，遇到卡住的地方，先别急着改配置，先抓包看看实际请求长什么样。大部分问题，抓包一看就明白了。