最近我在做一个小项目，需要把 OpenAI Codex CLI 的请求统一走到自己开发的“OpenAI 兼容网关”上做日志审计。一切配置好之后，codex启动却直接炸了——报错信息写着cc switch local proxy failed while handling codex endpoint /responses，我在终端里盯着这行错误看了很久，第一反应是：网关没起？端口不对？权限不够？但反复确认后全都没问题。
后来我把 Codex 的源码翻了一遍，定位到这是官方代码里一处 URL 拼接分支的错误，属于典型的“官方 bug”。我顺手写了一个开源小工具，专门诊断和修复这类自定义 provider 的配置路径问题。这篇文章把完整的排查过程、根因分析、工具实现思路和避坑清单都放出来，给同样在用 Codex CLI 做自定义 API 端点、本地网关对接、或者想自己给 Codex 提 PR 的人参考。不管基础深浅，照着这篇的思路，你也能把这类“疑似网络问题”的 CLI 报错，一步步拆到代码层面。
1. 先说定位：这个bug到底错在哪
1.1 bug现场完整还原
我先把复现条件交代清楚。我的环境是 Ubuntu 24.04 LTS，Codex CLI 用的是当时官方最新版，本机在127.0.0.1:8080起了一个自研的 OpenAI 兼容网关，只实现了/v1/responses和/v1/chat/completions两个端点，用于记录所有 AI 请求的入参和出参。模型名、端口这些都不是特殊配置，属于非常常见的自建网关场景。
Codex 的自定义 provider 配置写在家目录的~/.codex/config.toml里，大致长这样：
model = "gpt-5" # 替换成你实际使用的模型名 model_provider = "local-gateway" [model_providers.local-gateway] name = "local-gateway" base_url = "http://127.0.0.1:8080" wire_api = "responses"上报配置完成之后运行codex，输入第一句提示词，终端大概安静几秒到十几秒，然后直接抛出一段错误：
Error: cc switch local proxy failed while handling codex endpoint /responses. provider: local-gateway这个错误最迷惑人的地方在于，它把责任甩给了 “local proxy”，字面意思是“本地代理失败”。我第一反应是先检查网关是不是没起来，用curl http://127.0.0.1:8080/v1/responses测了一下，发现返回了正常的鉴权错误，说明网关是活着的。然后又检查了端口绑定、证书、环境变量，全都没问题。
更奇怪的是，我把wire_api从"responses"改成"chat"，同样的 base_url，同样的网关，居然能正常跑通。也就是说，问题不是“网络不通”，也不是“网关坏了”，而是和responses这个协议端点强相关。到这里，基本可以确定不是本地环境的问题，而是 Codex 官方代码在处理自定义 provider 时出现了缺陷。
1.2 从报错文本本身拆线索
吃瓜要吃到根上。我先把报错文本逐词拆开看，这段错误信息其实给了三个关键线索：
cc switch：这个“cc”不是某个未知组件，而是 Codex 内部负责配置切换的一段逻辑，从源码路径来看就是 config switch 相关模块。local proxy failed：这里的 proxy 指的不是传统意义上的网络代理，而是“本地服务端点”。官方在报错文案里直接用了 proxy 这个词，非常容易把用户带偏到网络排查上去。while handling codex endpoint /responses：这是整句话里最值钱的线索——Codex 在启动或对话前，会先向某个地址发起/responses请求，而这步失败了。
综合之后可以断定：这是 Codex 在初始化自定义 provider 时，向/responses端点发出请求但没能正确到达，最后统一包装成了 “local proxy failed”。也就是说，问题发生在请求被真正发出之前或之中的某个环节，不是目标服务的问题。
我顺手把这个报错在社区讨论区搜了一圈，发现确实有人遇到过同类问题，但大多数人提的 workaround 都是“别用自定义 provider”，或者“把 wire_api 改成 chat”。这些办法能绕过问题，但没有解决根本。作为长期用 Codex 做二次开发的人，不想每次都用 workaround 续命，就决定自己从源码层面挖到底。
1.3 影响范围与初步定级
把现象总结一下，这次 bug 的影响面其实不小。凡是走“自定义 provider + responses 协议”路线的用户，基本都会中招。常见的使用场景包括：企业内部的 AI 网关、带了审计或限流功能的中间层、自建隐私环境、以及像我这样为了日志分析做本地转发的开发者。
问题的级别我定为“功能性缺陷”而不是“安全事件”：它不泄露数据，也不破坏配置，但会让依赖自定义 provider 的整个工作流瘫痪，而且报错信息误导性强，消耗排查时间。对团队协作来说，这甚至可能让一整天的工作阻塞，完全不值得为了绕开它去改掉自己的架构设计。
2. 一步步排查：如何把锅从“网络”甩回“代码”
2.1 排查工具选型：我为什么选“echo服务 + 源码断点”
排查这类 CLI 报错，最忌讳的就是瞎改配置。我建议按照“抓请求 → 看路径 → 读源码”的顺序来，而不是反过来乱试。
先说抓请求。Codex 是 Rust 写的，直接开RUST_LOG=debug输出的日志对协议细节覆盖不够，我要的是“它到底往哪个 URL 发了什么请求”。最简单的办法并不需要 Wireshark 这类重型工具：在本地起一个 echo 服务，监听 8080 端口，把收到的所有请求的 method、path、headers 原样打出来。这样 Codex 一发请求，就能在 echo 服务这边看到原始 URL 和请求内容，完全不用去猜。
# echo_server.py：一个用于观察请求的极简HTTP服务 from http.server import BaseHTTPRequestHandler, HTTPServer import sys class Handler(BaseHTTPRequestHandler): def do_GET(self): self._log_request("GET") self.send_response(204) self.end_headers() def do_POST(self): length = int(self.headers.get("Content-Length", 0)) body = self.rfile.read(length)[:200] self._log_request("POST", body) self.send_response(204) self.end_headers() def _log_request(self, method, body=b""): sys.stdout.write("== %s %s ==\n" % (method, self.path)) sys.stdout.write("Headers: %r\n" % dict(self.headers.items())) sys.stdout.write("Body-head: %r\n\n" % body) sys.stdout.flush() if __name__ == "__main__": HTTPServer(("127.0.0.1", 8080), Handler).serve_forever()然后把 Codex 的配置简化到只保留一个 provider，排除掉多 provider 互相影响的可能，再跑一次codex。echo 服务给出的结果非常有价值：它收到的请求路径是POST /responses，而不是我在网关里实现的POST /v1/responses。
这一下就锁定了问题方向：Codex 在构造自定义 provider 的请求路径时，直接把 base_url 替换成了http://127.0.0.1:8080，然后在这个基础上追加了/responses，但漏掉了标准 endpoint 里的/v1前缀。也就是说，它实际请求的是http://127.0.0.1:8080/responses，而正确地址应该是http://127.0.0.1:8080/v1/responses。
2.2 对照组试验：排除干扰项
为了确认这不是网关实现的问题，我做了一组对照试验，结果如下表：
| 配置组合 | 请求实际路径 | 是否成功 |
|---|---|---|
| 自定义 provider + wire_api=responses | /responses | 失败 |
| 自定义 provider + wire_api=chat | /v1/chat/completions | 成功 |
| 官方 provider + wire_api=responses | /v1/responses | 成功 |
| 自定义 provider + base_url 手动写成 /v1 结尾 | /v1/responses | 成功 |
这个表格直接破案：只要 base_url 末尾不带/v1，responses 协议就会缺前缀；但 chat 协议又神奇地没问题。原因其实很好理解：Codex 在构造请求时，对 chat 协议走了另一个分支，那个分支里做了/v1的拼接，而 responses 协议的分支里没有。同一套环境里，只有“自定义 provider + responses”这个组合恰好落入了有缺陷的分支。
看到这个逻辑之后，手头其实已经有一条立竿见影的临时绕法了：把配置里的base_url从http://127.0.0.1:8080改成http://127.0.0.1:8080/v1，再运行 Codex，立即正常。这个绕法我本地验证了好几轮，完全稳定。
但绕法只是能干活，谈不上“修好了 bug”。Codex 自带更新机制，升级之后配置文件还是那套，我总不能每次升级都祈祷官方改掉这个分支。要想让所有同类用户受益，只能在源码层面找到那行代码，把修复方案做成一个可持续使用的工具或补丁。
2.3 源码定位：罪魁祸首是一处 URL 拼接分支
Codex CLI 本身是开源的，直接在 GitHub 仓库里搜responses和base_url相关逻辑。顺着wire_api的匹配点，找到了构造请求地址的关键函数，大致逻辑如下（简化后便于理解）：
# 根据 Codex 源码还原出的伪代码，用于展示根因 # 已知变量：provider_config, wire_api if provider_config.name == "openai" or provider_config.name == "openai-custom": # 官方 provider 走这里，host 和 path 都写死，自然没问题 request_url = "https://api.openai.com/v1/" + wire_api else: # 自定义 provider 走这里 # 注意：base_url 直接拼上 wire_api，没有自动补 /v1 request_url = provider_config.base_url + "/" + wire_api问题就在 else 分支里：base_url + "/" + wire_api这个写法把完整路径交给用户来控制。Base URL 的标准格式应该是http://host:port/v1，这样拼出来才是http://host:port/v1/responses。但很多用户（包括我）都习惯把base_url写成服务根地址http://host:port，因为之前用 chat 协议时它都能正确补前缀。于是 responses 协议下就把/v1弄丢了。
为什么官方自测没发现？我猜是官方测试矩阵里，自定义 provider 只覆盖了 chat 协议的用例，responses + 自定义 base_url 的组合没在回归测试里。这属于典型的“测试盲区”，也说明这类 CLI 工具的配置路径组合，比表面看起来要复杂得多。
确认官方仓库最新代码里依然存在这个分支问题之后，我决定按“修复工具 + 官方 PR”两条线走。PR 慢慢等，工具先上线救火。
3. 修复方案落地：从“改一行配置”到“开源小工具”
3.1 修复思路对比：绕法、改源码、外置工具怎么选
面对这个 bug，当时有三条路线摆在面前：
- 手动改配置：把 base_url 末尾补上
/v1。零成本，但对所有踩坑的人都要重复同样操作，且没有解决上游代码缺陷。 - 本地改源码重新编译：能彻底修，可 Codex CLI 升级后就失效，还要维护 fork，成本太高。
- 做一个外置诊断/修复工具：不改 Codex 本体，通过扫描配置文件识别缺陷组合，自动修正 base_url，再跑冒烟测试验证。既兼容新旧版本，又可以做成开源项目让社区一起用。
我选了第三条。核心原因很实在：它能立刻让所有受影响的人无痛解决问题，而不需要等官方发布修复、也不需要用户学会改 TOML 语法。工具的作用是“把坏事拦在门外”，就算官方以后修好了，这工具在旧版本上也有存在价值。
3.2 工具架构与核心实现
我给它取了个朴素的名字：codex-provider-fix，用 Python 3 写的。选 Python 而不是 Shell 的原因是 TOML 解析、错误处理、跨平台路径操作都更顺手，分发给开发者用也几乎没有门槛。
工具的核心流程分五步：
- 读取
~/.codex/config.toml，用tomllib（Python 3.11 内置）解析所有model_providers。 - 遍历每个自定义 provider，检查
wire_api和base_url的组合：如果wire_api是responses且base_url不以/v1结尾，就判定为需要修复。 - 自动修正：在 base_url 末尾补上
/v1，同时保留原配置备份到config.toml.bak。 - 修改后启动一个内置的本地冒烟测试——直接向修正后的地址发一个最小请求，检查链路是否已经打通。
- 提供
--rollback参数：一行命令恢复备份，让不喜欢自动修改的人随时退回原状。
关键代码片段如下。这里有个非常容易踩的坑：Python 的tomllib只负责读，不能写回 TOML 文件，所以需要额外装一个tomli_w，很多新手在这里被卡住。
import tomllib import pathlib import shutil import tomli_w def fix_provider_base_url(toml_path: pathlib.Path) -> int: with open(toml_path, "rb") as f: data = tomllib.load(f) fixed = 0 providers = data.get("model_providers", {}) for name, prov in providers.items(): if prov.get("wire_api") != "responses": continue base_url = prov.get("base_url", "") if base_url and not base_url.rstrip("/").endswith("/v1"): prov["base_url"] = base_url.rstrip("/") + "/v1" fixed += 1 if fixed: shutil.copy2(toml_path, str(toml_path) + ".bak") with open(toml_path, "wb") as f: tomli_w.dump(data, f) return fixed这里有一个值得说的细节：修正时我特意用base_url.rstrip("/") + "/v1"，而不是简单的字符串追加。因为如果用户原本写了http://127.0.0.1:8080/，直接追加会变成http://127.0.0.1:8080//v1，有些网关框架会正常处理，有些则会路由失败。这种“看似无关紧要的斜杠”恰恰是配置类 bug 最常见的隐藏来源。
3.3 冒烟测试：让修复结果可验证
工具里我加入了一个轻量的冒烟测试模块：向修复后的 base_url 发一个 POST 请求到/v1/responses路径，请求体只是最简结构，不传真实业务数据。判定逻辑很简单：
- 如果响应是
4xx，说明服务端处理了请求，链路是通的。 - 如果响应是
5xx或直接拒绝连接，说明修复方向不对，可能是网关本身没有实现该端点。 - 如果响应是
2xx，说明你的自定义网关刚好也实现了对该端点的完整处理，这就是最理想的状态。
这个设计把“配置是否正确”和“后端是否支持”两件事分开了。很多用户一看到 5xx 就以为是工具改错了，其实不是，工具只负责让 Codex 发出的请求走到标准路径上，后端支不支持是另一回事。我在 README 里专门用加粗字写了这条说明，实测下来能减少大半误解。
3.4 开源发布与后续反馈
工具我发布在 GitHub 上，用的 MIT 协议，README 里包含：bug 背景、原理说明、一键使用方式、回滚方式、以及完整的伴生测试脚本。发布之后，我把修好的逻辑还提给了官方一个 PR，核心改动就是给 responses 分支补上/v1前缀，改动量很小，但问题很典型。
后续有一些使用者反馈，大多集中在“Windows 路径问题”和“网关不支持/v1前缀”这两类，我都加进了 FAQ。最有意思的一个反馈是：有人把 base_url 指向了一个仅支持 chat 协议的本地服务，但wire_api却写了responses，我的工具不仅会补/v1，还会给出一个提示，告诉用户两种协议不匹配。这算是工具超出预期的价值——它不只是补丁，还是一个 provider 配置的“体检表”。
4. 常见问题与排查技巧实录
4.1 用了工具还是报错？先看这几个检查点
折腾过一段时间后，我总结了一份排查清单，先讲最常见的原因。
第一，确认网关真的在监听你配置的端口。很多人以为“服务没报错”就是启动了，其实后端可能根本没监听，或者监听在 IPv6 的::1而不是 IPv4 的127.0.0.1。排查命令很直接：
ss -lntp | grep 8080第二，检查环境变量是否覆盖了配置文件。Codex 读取配置的优先级里，环境变量高于配置文件，如果你设置过OPENAI_BASE_URL或者 Codex 专用的 base URL 变量，那么即使配置文件里写的地址是对的，实际生效的也可能是环境变量。我遇到过不止一次，用户排查半天最后发现是 shell profile 里一个残留变量在作祟。
第三，检查 wire_api 和网关实现是否匹配。你的网关如果只实现了 chat 协议，那就老老实实用wire_api = "chat"，强行用 responses 协议一定会失败，这不是 Codex 的 bug，是配置和部署不匹配。
第四，检查自定义证书和鉴权头。如果你的网关用了自签名证书，或者要求额外的Authorization头，Codex 的 provider 配置里必须显式声明相关字段，否则请求会在 TLS 握手阶段就失败，代码层看到的也只有一句笼统的 “proxy failed”，很容易被带偏。
4.2 手动排查速查表
如果没有我的工具，或者你在排查其他类似 CLI 工具，下面这张速查表可以直接照用：
| 现象 | 可能原因 | 验证手段 | 解法 |
|---|---|---|---|
| 报错含 “local proxy failed”，但网关正常 | URL 路径拼接缺陷 | echo 服务观察请求路径 | base_url 补 /v1 |
| 连接拒绝 | 网关未启动或端口不对 | ss / netstat | 启动网关或改端口 |
| TLS 握手失败 | 自签名证书未被信任 | 抓包或服务端日志 | 配置证书相关字段 |
| 请求通了但一直 401/403 | 鉴权头缺失 | 网关日志 | 补充 API Key 配置 |
| chat 协议正常，responses 异常 | 网关只实现了 chat | 文档核对 | 换 wire_api 或升级网关 |
这张表的核心思想是：每一个“现象”都要对应一个明确的“验证手段”，不要凭感觉去猜。CLI 工具报错时最怕的多半不是问题本身，而是被错误文案带偏方向。
4.3 给开源贡献者的几点经验
最后这部分，写给想给 Codex 或其他开源 CLI 工具提 PR、做周边工具的人。
第一，提 issue 前先最小复现。我的习惯是把配置文件缩到最小、把环境变量清空、把影响面隔离到单一变量。如果一个现象只能用一堆复杂配置才能复现，那说明你自己还没定位清楚，官方也无法快速响应。
第二，排查时保留证据。echo 服务打出的请求路径、对照组试验表、最小复现仓库，这些都要留住，既方便自己复盘，也能让维护者一眼看明白问题在哪。我在提 PR 时附上了 echo 服务的输出截图和对照组结果，维护者理解问题几乎没花时间。
第三，不要指望官方立刻修复。开源项目再活跃，一个边缘配置的 bug 也排不进高优先级队列。外置修复工具的价值就在于“不等上游”，先让生态里的用户不卡住。等官方修复发布后，这类工具还可以转型成配置校验器，继续发挥余热。
我个人在这次踩坑里最大的体会是：命令行工具的报错文案，真的只是“给你一个排查起点”，而不是“问题的结论”。“local proxy failed” 这六个字一度把我引向网络排查的死胡同，但真正的问题藏在一行 URL 拼接代码里。以后我遇到任何类似的“连接不上”“代理失败”报错，都会先起一个 echo 服务器之类的东西，看一眼工具到底在请求什么地址，再谈后面的网络问题。这个习惯帮我省下的时间，远比当时写修复工具花的那个周末多。
我也建议每个深度使用 Codex CLI 或其他 AI 编码工具的开发者，都花几分钟看看自己的 provider 配置，确认 base_url、wire_api、环境变量这些“小东西”是否自洽。很多时候让你卡住一天的，不是模型能力不行，而是配置声明的路径和代码逻辑里的路径差了那么一个/v1。
