1. 为什么要在本地命令行工具里接自建网关把 Codex CLI 或者 Claude Code 这类命令行 AI 编程助手接到自建网关上是最近不少团队在折腾的一件事。动机很直接官方接口按量计费团队里几个人同时用账单跑得比预期快另外有些内部代码不方便直接走外部通道想在自己可控的网关层做一层转发、审计和限流。于是就有了“自建网关 本地 CLI 工具”这套组合。但真动手之后你会发现这件事的坑比想象中多。核心矛盾在于这些 CLI 工具默认是奔着官方接口去的它们的base_url拼接逻辑、鉴权头、请求体字段、流式响应格式都是按官方那套约定写死的。你换一个自建网关哪怕网关本身兼容官方协议也可能在某个细节上对不上表现就是各种奇怪的报错——401、404、400或者更隐蔽的请求发出去了返回也是 200但 CLI 里就是不出内容。这篇内容就是把这套踩坑过程完整梳理一遍。适合两类人看一是已经在自己搭网关、想让团队用上 CLI 工具的开发者二是刚开始接触这类工具、想搞清楚base_url到底该怎么配的人。我会把协议层面的差异、配置项的写法、排查思路都讲清楚尽量让你少走弯路。先说结论性的判断接自建网关能不能成八成取决于你的网关是否严格实现了官方那套 API 协议而不是取决于 CLI 工具本身。CLI 工具这边能调的参数其实很有限真正要下功夫的是网关侧的兼容性。2. 先搞清楚 base_url 的拼接规则2.1 base_url 不是“填个域名”那么简单很多人第一次配的时候直觉上会把base_url填成https://your-gateway.com然后期待工具自动补上/v1/chat/completions之类的路径。这个直觉在部分工具上成立在另一部分上会直接 404。原因在于不同 CLI 工具对base_url的处理方式不一样。有的工具会把你给的地址当作“根”然后自己拼/v1/messages或/v1/chat/completions有的工具则要求你把完整路径都给出来它不再做任何拼接。你如果按前者的习惯填了根域名却在用后者的工具那请求就会打到https://your-gateway.com本身网关自然不知道怎么处理。我实测下来比较稳妥的做法是先确认你用的工具属于哪一类再决定 base_url 填到哪一层。判断方法很简单看它的官方文档里 base_url 的示例值。如果示例是https://api.example.com那它大概率会自己拼路径如果示例是https://api.example.com/v1那它可能只拼最后一段如果示例直接给到/v1/chat/completions那你就得填全。2.2 尾斜杠是个隐形杀手还有一个特别容易被忽略的点base_url 结尾的斜杠。https://gw.example.com/v1和https://gw.example.com/v1/在字符串拼接时结果完全不同。前者拼出来是/v1/chat/completions后者可能拼成/v1//chat/completions多了一个斜杠。有些网关对重复斜杠是宽容的会做归一化有些网关则严格匹配路由多一个斜杠就是 404。我踩过一次这个坑排查了快一个小时最后发现就是配置里手滑多打了个斜杠。所以建议是配置完之后先用 curl 手动打一次确认路径正确再让 CLI 工具去跑。这样能把“配置问题”和“工具问题”分开。2.3 路径前缀与网关路由的对应关系自建网关通常会在前面挂一层反向代理比如 Nginx 或者网关框架自带的路由。这时候 base_url 里的路径前缀必须和网关实际暴露的路由前缀一致。举个例子你的网关内部把处理逻辑挂在/api/llm/v1/chat/completions但对外只暴露了/v1/chat/completions那 base_url 就应该填对外暴露的那个。反过来如果你在网关里做了路径重写把/v1/*重写成/api/llm/v1/*那 base_url 填/v1就行重写逻辑在网关侧完成。这里的关键是base_url 填的是“客户端视角看到的地址”不是“网关内部真实的地址”。很多人配错就是因为把内部路由当成了对外地址。3. 协议差异才是真正的深水区3.1 鉴权头的命名和格式官方接口的鉴权方式不同厂商不一样。有的用Authorization: Bearer token有的用x-api-key: token还有的用自定义头。你的自建网关如果只实现了其中一种而 CLI 工具默认发的是另一种那就会 401。我遇到过的典型情况是CLI 工具默认发Authorization: Bearer但网关只认x-api-key。这时候有两个解法一是在网关侧同时接受两种头做兼容二是在 CLI 工具的配置里看能不能自定义鉴权头。多数工具支持配置 API key但头名称是写死的所以更现实的做法是在网关侧做兼容。提示网关侧做鉴权头兼容时注意不要同时接受空值。有些实现会在两个头都缺失时放行这是安全隐患。3.2 请求体字段的细微差别请求体这块表面上大家都用 JSON字段名看起来也差不多但细节差异能让你调半天。比如有的接口用max_tokens有的用max_output_tokens有的接口messages里 role 只认user/assistant/system多一个tool就报错有的接口对temperature的取值范围要求是 0 到 1你传 2 就直接 400。这些差异在官方文档里可能写得很清楚但自建网关如果只是“大致兼容”就容易在这些边界上翻车。我的建议是在网关侧做一层字段映射和校验把 CLI 工具发过来的请求体转换成你后端真正能处理的格式。这样 CLI 工具不用改网关也能稳定工作。3.3 流式响应的格式对齐流式响应是坑最多的地方。官方接口的流式格式通常是 SSE每行以data:开头最后以data: [DONE]结束。但不同厂商在细节上有差异有的会在每个 chunk 里带id和model字段有的不带有的把delta放在choices[0].delta.content有的放在choices[0].text结束标记有的是[DONE]有的是空行有的干脆不断开连接。CLI 工具在解析流式响应时是按官方格式写的解析器。如果你的网关返回的格式和官方有出入解析器可能直接卡住表现就是“请求发出去了界面一直转圈不出字”。我实测下来最稳的做法是网关侧严格按官方 SSE 格式输出包括data:前缀、[DONE]结束标记、以及 chunk 内的字段结构。哪怕你后端用的是另一套协议也在网关层做转换别让 CLI 工具去适配。4. 实操从零配通一条链路4.1 环境准备与工具安装假设你已经在本地或内网搭好了一个网关它对外暴露的地址是https://gw.internal.example.com并且实现了/v1/chat/completions和/v1/messages两个端点。现在要做的是让 CLI 工具走这个网关。第一步确认 CLI 工具的版本。不同版本对 base_url 的支持程度不一样老版本可能根本不支持自定义 base_url。升级到较新的版本通常配置项会更完整。第二步找到配置文件。Codex CLI 和 Claude Code 的配置位置不太一样有的在用户目录下的隐藏文件夹里有的支持环境变量。优先用环境变量因为改起来方便也容易在不同终端会话里切换。第三步准备好你的网关 API key。这个 key 是网关侧签发的不是官方平台的 key。别搞混了。4.2 配置项的写法与验证配置的核心就三项base_url、api_key、model。写法上环境变量通常长这样export OPENAI_BASE_URLhttps://gw.internal.example.com/v1 export OPENAI_API_KEYyour-gateway-key export OPENAI_MODELyour-model-name注意这里的 base_url 带了/v1因为多数工具会在这个基础上拼/chat/completions。如果你的工具要求填完整路径那就把/chat/completions也加上。配完之后别急着在 CLI 里跑。先用 curl 验证curl -sS https://gw.internal.example.com/v1/chat/completions \ -H Authorization: Bearer your-gateway-key \ -H Content-Type: application/json \ -d { model: your-model-name, messages: [{role: user, content: ping}], stream: false }如果这一步返回正常说明网关和鉴权都没问题问题就缩小到 CLI 工具本身了。如果这一步就报错那先解决网关侧的问题别在 CLI 上浪费时间。4.3 流式请求的单独验证非流式通了之后再单独验证流式curl -sS -N https://gw.internal.example.com/v1/chat/completions \ -H Authorization: Bearer your-gateway-key \ -H Content-Type: application/json \ -d { model: your-model-name, messages: [{role: user, content: count to 3}], stream: true }-N参数是关闭 curl 的缓冲让你能实时看到 SSE 数据。正常的话你应该能看到一行行data: {...}往外冒最后以data: [DONE]结束。如果这里卡住不出数据或者格式不对那就是网关的流式实现有问题。注意有些网关在流式模式下会先把整个响应缓冲完再一次性发出这在 curl 里看起来“正常”但 CLI 工具会认为流式失效因为它期待的是逐块到达。验证时留意数据是不是“一次性涌出来”的。5. 常见报错与排查速查5.1 401 与 403鉴权问题401 通常是 key 不对或头名称不对403 则可能是 key 有效但权限不足。排查顺序确认 key 是网关签发的不是官方平台的确认头名称和网关要求的一致确认 key 没有过期或被禁用确认网关侧对该 key 开放了目标模型的权限。我遇到过一种情况key 是对的头也对但网关侧配置了 IP 白名单而 CLI 工具走的出口 IP 不在白名单里。这种就是 403排查时容易忽略。5.2 404路径拼接问题404 基本都是路径不对。按这个顺序查base_url 是否带了正确的路径前缀尾斜杠是否多余网关路由是否真的暴露了该路径反向代理是否做了路径重写重写规则是否正确。一个快速定位的方法是在网关侧打开访问日志看 CLI 工具实际请求的完整 URL 是什么。对比你期望的 URL差异一目了然。5.3 400请求体字段问题400 通常是请求体里有网关不认的字段或者字段值超范围。排查时把 CLI 工具发出的原始请求体抓出来看和网关期望的格式对比。抓包可以用网关侧的日志也可以在本地用代理工具。常见的不匹配包括max_tokens超限、temperature超范围、messages里 role 不合法、缺少必填字段。这些在网关侧做一层校验和默认值填充能省很多事。5.4 200 但无内容流式格式问题这是最隐蔽的一类。请求成功状态码 200但 CLI 界面不出字。原因通常是流式响应的格式和 CLI 解析器不匹配。排查方法用 curl 看原始 SSE 数据确认格式对比官方格式看字段名、前缀、结束标记是否一致检查是否有额外的空行或非标准字符。我踩过一次网关返回的 SSE 里每个 chunk 前面多了一个空格导致解析器认不出来。这种问题只能靠对比原始数据发现。报错类型常见原因排查重点401key 错误、头名称不对确认 key 来源和头名称403权限不足、IP 限制检查网关权限配置和白名单404路径拼接错误对比实际请求 URL 和期望 URL400请求体字段不匹配抓原始请求体对比格式200 无内容流式格式不匹配用 curl 看原始 SSE 数据6. 几个容易忽略的细节6.1 超时设置CLI 工具通常有默认超时比如 30 秒或 60 秒。如果你的网关后面接的模型响应比较慢或者流式输出间隔较长可能会触发超时。表现是请求中途断开CLI 报超时错误。解法是在 CLI 工具侧调大超时或者在网关侧做心跳定期发送空 chunk 保持连接。后者更稳但需要网关支持。6.2 并发与限流团队多人同时用的时候网关侧的限流策略要配好。如果限流太严CLI 工具会频繁收到 429体验很差。如果限流太松后端模型可能扛不住。建议按 key 或按用户做限流并且给 CLI 工具配置重试逻辑。6.3 日志与审计自建网关的一个好处就是能做日志和审计。建议把每次请求的 key、模型、token 用量、耗时都记下来。这样既能排查问题也能做成本核算。注意日志里不要记录完整的请求体避免敏感代码泄露。6.4 模型名称的映射CLI 工具里填的模型名称和网关后端实际调用的模型名称可能不是一回事。网关侧需要做一层映射。比如 CLI 填gpt-4网关映射到内部的my-llm-v2。这层映射要配清楚否则会报“模型不存在”。7. 我个人的几条实操心得第一先通 curl再通 CLI。这是最省时间的排查顺序。curl 通了说明网关没问题问题在 CLI 配置curl 不通说明网关有问题别在 CLI 上瞎调。第二base_url 的路径前缀宁多勿少。如果拿不准工具会不会自己拼路径就先把完整路径填上跑通了再试着去掉后缀看工具是否兼容。反过来先填短的容易 404排查起来更麻烦。第三流式格式一定要严格对齐官方。这是最容易出隐蔽问题的地方。网关侧做格式转换时别自作聪明改字段名或省略字段按官方格式一比一输出最稳。第四保留一份可用的 curl 命令。每次改配置或升级工具后先用这份 curl 验证网关能快速排除网关侧的变化。第五网关侧的日志要能看到原始请求。包括请求头、请求体、响应状态。这样出问题时你能第一时间定位是客户端发错了还是网关处理错了。这套东西配通之后团队用起来还是很顺的。CLI 工具的体验基本和直连官方一致但成本可控内部代码也不出内网。后面如果要做多模型路由、按团队分账网关层也有足够的扩展空间。