Codex报错排查：Responses API切换与配置避坑指南

最近是不是被 Codex 的报错刷屏了我先说结论Codex 服务已经彻底只认 Responses API任何试图走 Chat/Completions 的请求都会被打回来。这篇内容是我把近期遇到的 Codex 常见报错、连带的配置问题、还有社区里高频提问整理成的一份排障记录主要是帮正在用 Codex CLI 写自动化编码任务的开发者快速判断是端点配错、模型名不对、还是本地转发层出了问题。我自己的感觉是这次 Responses API 的切换牵扯面比想象中广因为它连带着影响的不只是官方客户端还有大量第三方配置切换工具、本地转发服务、以及老教程里残留的 base_url 写法。接下来我按“报错原因 → 修正方法 → 完整排查流程 → 高频问题速查”一条条讲清楚。1. 先把报错复现出来Responses API 和 Chat/Completions 到底差在哪1.1 我实际遇到的报错长什么样先说最常见的堵脸报错长这样Error: Chat/Completions are not supported by Codex. Please use the Responses API.这个报错的触发时机通常是你在 Codex CLI 里刚敲下第一条消息或者刚启动会话它直接给你红字拒绝。还有一类是配置层面更隐蔽的报错像下面这种cc switch local proxy failed while handling codex endpoint /responses.这个“local proxy”是报错原文里的术语它指的是 cc-switch 这类工具在本地启动的 API 转发服务不是网络工具别混淆。它说明请求已经走到了本地转发层但转发服务在处理/responses端点时挂了。官方 GitHub 上还有一类 JSON 报错也很常见{detail:the gpt-5.6-sol model is not supported when using codex with a...}这一眼看上去是模型名不被支持但本质上往往不是模型名拼错而是你的请求没有真正到达支持 Codex 模型的正确端点或者供应商那一侧根本没有把模型映射到 Responses API 的处理逻辑里。区分这三类报错很重要第一类说明你配置的 base_url 或者请求路径还在走 Chat/Completions第二类说明本地转发层和 Codex 之间的协议不匹配第三类说明模型名与供应商支持的列表对不上。修复手段不太一样。1.2 为什么会有这个限制Responses API 到底比 Chat 多了什么很多人不理解OpenAI 为什么非要锁死 Chat/Completions我打一个比方Chat Completions 像一个“单轮问答接线员”你问一句它答一句所有历史记录都堆在一个 messages 数组里没有真正的任务状态管理。但 Codex 不是单轮问答它是一个编码代理要连续做多步推理中间要读文件、改文件、执行命令、根据报错调整方案、再继续下一轮。这些事情需要一种能表达“任务状态”的接口。Responses API 就是冲这个来的。它对推理过程有独立的结构化表示对工具调用有完整生命周期对上下文管理也有更明确的协议。Codex 在这种接口上才能高效地跑完一次 agent 编码任务。所以 OpenAI 在 Codex 这条链路上直接禁掉了 Chat/Completions这是产品设计上的强制约束不是 bug你改任何参数都没法绕过这个方向。另外一个容易忽略的点很多第三方供应商为了兼容老客户端只实现了/v1/chat/completions端点。你想把 Codex 接到这类供应商上它当然不支持因为 Codex 要发的是/v1/responses。报错信息里虽然写的是“model not supported”但实际问题是协议端点根本不匹配。要解决就得在供应商兼容层上做文章而不是死磕模型名。2. 最直接的修法把端点从 /chat/completions 切到 /responses2.1 官方 Codex CLI 的正确配置如果你用的是官方 Codex CLI配置文件路径在~/.codex/config.toml。我直接给一份能跑的参考配置model gpt-5-codex model_provider openai [model_providers.openai] name openai base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api responses注意看base_url只写到https://api.openai.com/v1不要在后面拼/chat/completions也不要画蛇添足拼/v1/responses。Codex CLI 自己会根据wire_api responses去拼接最终请求路径。如果你照着老教程把 base_url 写成了https://api.openai.com/v1/chat/completions启动就会直接吃到开头那个“Chat/Completions are not supported”的报错。env_key的意思是Codex CLI 会从环境变量OPENAI_API_KEY里读取密钥。设置方式按平台来# macOS / Linux export OPENAI_API_KEYsk-你的密钥 codex # Windows PowerShell 临时设置 $env:OPENAI_API_KEYsk-你的密钥 codex如果你希望长期生效macOS / Linux 把 export 那行写进~/.zshrc或~/.bashrcWindows 去“系统属性 → 环境变量”里新增用户变量。这一步看着基础但很多人报auth token is unavailable就是环境变量没被 Codex 读到。2.2 第三方模型接入时模型名的坑热词里频繁出现“codex 接入 deepseek”这类场景本质上是想用非官方模型跑 Codex 的 agent 工作流。问题在于第三方模型供应商有没有真正支持 Responses 协议。我建议动手之前先用 curl 直接打一下供应商的/responses端点做一次最朴素的连通性验证curl https://api.openai.com/v1/responses \ -H Authorization: Bearer $OPENAI_API_KEY \ -H Content-Type: application/json \ -d {model:gpt-5-codex,input:test}如果这个请求能正常返回说明你的 base_url、密钥、模型名都基本没问题接下来排查 Codex CLI 侧的配置。如果这一步直接 404说明供应商根本没实现 Responses 端点如果 400说明模型名白名单里没有你填的名字如果 401密钥无效或者没权限访问该模型。有些供应商提供兼容层会在文档里明确告诉你把 base_url 填成它们统一的入口地址然后在 Codex 里指定它们兼容的模型名。这时候 config.toml 里的model_provider要新加一个 provider不能还挂在 openai 上model deepseek-chat model_provider deepseek [model_providers.deepseek] name deepseek base_url https://你供应商提供的兼容地址/v1 env_key DEEPSEEK_API_KEY wire_api chat这里wire_api chat是关键变量。它允许 Codex CLI 用 Chat/Completions 协议去和供应商通信兼容那些没实现 Responses 的供应商。但我要提醒一句把 wire_api 设成 chat本质上是降级使用Codex 的 agent 能力会打折官方文档也不推荐在正式编码任务里长期这么干。它更适合你只是想快速验证连通性的场景。3. 进阶排查cc-switch 这类配置切换工具的隐藏坑3.1 local proxy failed 是怎么冒出来的cc-switch 是社区里一个比较流行的 Codex 配置切换工具它解决的核心痛点是你同时有多个 API 供应商的配置手动改~/.codex/config.toml太容易出错它就在本地拉起一个转发层按你选中的配置把 Codex 的请求转发到对应供应商。问题恰恰出在这个转发层上。当你看到cc switch local proxy failed while handling codex endpoint /responses.说明 Codex CLI 已经把请求发到本地转发层但转发层没能成功转发到目标供应商或者转发层本身不支持/responses这个路径。我自己遇到过三种情况第一种配置里填的本地转发地址不对。cc-switch 会在本机某个端口起服务如果配置文件里的 host 写成了127.0.0.1但服务实际只监听了 IPv6 的::1请求就打不进去。第二种转发层版本太老。老版本只实现了 chat/completions 转发逻辑拿到 Codex 发来的/responses请求后直接不知道怎么处理然后返回一个异常状态给 Codex CLI。第三种配置文件里的 base_url 被写成了转发服务的完整路径比如http://127.0.0.1:9090/chat/completions这个尾巴导致转发服务在解析 endpoint 时错乱。3.2 我能跑通的 cc-switch 配置清单如果你一定要用 cc-switch我的建议是先备份原配置cp ~/.codex/config.toml ~/.codex/config.toml.bak然后按下面这种思路检查base_url 必须是供应商的 API 根路径只到/v1尾巴千万不要写/chat/completions或/responses。如果 cc-switch 提供了本地转发模式先确认本地转发服务进程真的起来了端口能通。Linux / macOS 用lsof -i :端口号Windows 用netstat -ano | findstr 端口号查。切换完供应商后新开一个 Codex 会话不要在一个已经建立的会话里热切换配置Codex CLI 启动时读一次配置不会动态重新加载。遇到转发失败的报错先去 cc-switch 自己的日志目录看日志别一头扎进 Codex 的日志里。Codex 只能告诉你转发层没处理成功具体原因要看转发层那一侧的记录。另外cc-switch 切换配置后经常会伴随auth token is unavailable。原因很简单它把 config.toml 里的env_key换成了新供应商的变量名但你的环境变量里还没设置这个新变量或者设置的值是空的。切换完配置后记得重新确认当前 shell 环境里的 API 密钥变量是否已经生效。4. 围绕 Codex 报错的高频连带问题排查记录4.1 auth token is unavailable 的三种场景这个报错我见过太多人踩了先说结论它八成不是 Codex 出 bug而是认证信息来源没对上。第一种场景你根本没设置 API keyCodex CLI 默认尝试走 ChatGPT 登录态但本地没有有效的会话 token于是报错。第二种场景你设置了OPENAI_API_KEY但 Codex CLI 启动时没读到这个变量在 macOS 上尤其常见因为图形界面启动的应用读不到 shell 里 export 的环境变量你需要在终端里手动启动 codex 才行。第三种场景环境变量名和 config.toml 里的env_key对不上比如 config 里写的是OPENAI_API_KEY你实际设的是OPENAI_KEY。排查命令很简单# macOS / Linux echo $OPENAI_API_KEY printenv | grep OPENAI # Windows PowerShell echo $env:OPENAI_API_KEY如果确认环境变量没问题再看一眼 config.toml 里env_key拼写再不行就把登录态清掉重新登一次codex login实际上最省心的做法是要么走 API key要么走 ChatGPT 登录态不要两套混着来混着来的时候 Codex 的认证优先级有时候会让你困惑。4.2 “正在重新连接”与超时类问题Codex 的 TUI 界面卡在“正在重新连接”是很烦人的场景。它背后的机制是Codex CLI 和本地服务之间有一条长连接请求响应时间过长或者本地服务进程异常界面就会不断尝试重连。常见的原因有三类。第一类模型本身响应慢尤其是高峰期或者你喂给它的上下文特别长响应时间超过了连接层的容忍阈值。第二类本地网络抖动Codex 对请求超时比较敏感网络质量差就会出现反复重连。第三类Codex 本地服务进程崩了但界面进程还活着它就会一直尝试重连到那个已经不存在的本地端口。处理办法我按优先级排先把 TUI 退出关掉所有 codex 相关进程再重新启动再看日志日志位置在~/.codex/log/codex-tui.log最后用 debug 模式跑一次看完整请求链路RUST_LOGdebug codex如果日志里能看到明确的 5xx 或限流信息那就是服务端或供应商的问题这时候等待一段时间再试同时检查自己是不是在很长的上下文中反复重试同一个任务该新开会话就新开会话别在一个会话里无限堆上下文。4.3 Windows 桌面版安装失败热词里有一批人卡在 Windows 安装环节报错类似 “codex windows installation 未完成”。这和 Responses API 报错是两回事但既然大家都在排查 Codex 问题我简要说一下。Windows 桌面版安装失败大概率是权限或者依赖缺失。先确认你是不是以管理员身份运行的终端再检查杀毒软件有没有拦截安装脚本这种情况在安装器需要静默释放文件时特别常见。如果你不想折腾桌面版直接用 npm 装命令行版更省事npm install -g openai/codex命令行版和桌面版的核心功能一致配置文件路径也是~/.codex/config.toml不会影响你接下来按文章里的方式排查 API 报错。5. 完整实操流程从报错出现到正常跑通5.1 五分钟排查路径不管你遇到的是哪一种报错我建议统一按下面这个顺序排查不要跳步第一步把报错原文完整复制下来不要只看第一行。Chat/Completions 不支持、local proxy failed、model not supported 这三类报错第一行长得差不多完整信息差别很大。第二步打开~/.codex/config.toml先看base_url。如果它包含/chat/completions直接改掉改成供应商的 API 根路径通常是https://xxx/v1。第三步看model字段。官方 Codex 模型在供应商的白名单里是否存在。接第三方供应商时先拿 curl 验证模型名是否可用别在 Codex CLI 里反复试错。第四步检查环境变量是否就位。用前面提到的方法确认 API 密钥能正常读到尤其是用了 cc-switch 这类工具切换过配置之后。第五步排查本地转发层的状态。如果你没有主动配置过任何本地转发服务跳过这步如果你在用 cc-switch确认转发进程在跑、端口能通、它自己日志里没有异常。第六步重启 Codex CLI。新开一个终端窗口重新跑codex进入会话输入一句话测试是否恢复。5.2 一次真实报错的完整复盘有一个案例我记得很清楚读者的 config.toml 里 base_url 写的是https://api.openai.com/v1/chat/completionsmodel 写的是gpt-5-codex启动后第一轮对话直接报 Chat/Completions 不支持。他的第一反应是怀疑模型名不对把 model 改成了 gpt-4o结果报错变成了 model not found。这个案例很典型因为问题的根源只有一个base_url 带上了/chat/completions尾巴导致 Codex 无论指定什么模型最终请求都发到了一个错误端点。改法就是把 base_url 改回https://api.openai.com/v1model 改回gpt-5-codex问题消失。另一个案例是 cc-switch 用户。他配置了一个第三方供应商启动 Codex 后一直报 local proxy failed。排查过程是先确认了 config.toml 里 base_url 正确指向供应商根路径再用 curl 直接请求供应商的/responses端点发现供应商返回 404。到这里就明白了问题不在 cc-switch 配置而是目标供应商根本没有实现 Responses 端点。他换了另一个支持 Responses 格式的供应商之后一切正常。这两个案例合并成一句话先验证供应商端点能力再排查工具配置最后回到 Codex 自己。6. 常见问题速查表与避坑清单我把这段时间高频出现的问题整理成一张速查表方便你直接对号入座报错特征可能原因快速处理方式Chat/Completions are not supportedbase_url 写错带上了 /chat/completions 尾巴修正 base_url 为 API 根路径如 https://api.openai.com/v1local proxy failed while handling codex endpoint /responsescc-switch 等本地转发层不兼容 Responses 端点或转发进程异常检查转发进程与端口更新转发工具版本或直接绕过转发层model not supported / model not found模型名不在供应商白名单或供应商不支持 Responses 协议用 curl 先验证模型名确认供应商端点能力auth token is unavailable环境变量未设置 / 变量名不匹配 / 登录态过期检查 env_key重新 export必要时 codex login一直显示正在重新连接请求响应超时或本地服务进程异常退出 TUI全清 codex 进程RUST_LOGdebug 查看日志Windows 安装未完成权限不足或安装脚本被拦截以管理员身份运行终端或用 npm 安装命令行版最后再分享一个我踩了很多次才养成的习惯每次要动 Codex 配置文件之前先备份再改改完只动一个变量。这个习惯在这次 Responses API 切换风波里救了我很多次因为很多报错是多重配置叠加出来的如果一次改好几个地方出问题了你根本不知道是哪一步导致的。Codex 的报错排查本质上就是一条链路config.toml → 环境变量 → 本地转发 → 供应商端点。从前往后逐层验证每层都用最小的请求去测试绝大多数问题都能在五分钟内定位。你现在遇到的报错大概率也只是这条链路上某个环节没对上按着上面的清单过一遍就行。