最近Codex这波热度是真的高尤其是“反代Codex”这个话题讨论度直接拉满。我一开始还没太当回事直到连续几天看到群里有人刷出同一行报错——cc switch local proxy failed while handling codex endpoint /responses——才意识到大量用户的卡点并不在“会不会写代码”而是卡在“客户端到底怎么才能接到我自己的模型服务”这一步上。今天这篇就把负责人亲自下场讲的那套思路结合我自己实际配通的经验从头到尾完整过一遍。不管你之前完全没用过Codex还是已经装上了但一直报错连不上这篇都能让你把这事彻底搞定。我会先把反代的基本原理讲明白再给两条可落地的路线一条适合目标服务本身兼容OpenAI接口的情况一条适合接DeepSeek这类只支持Chat Completions接口的服务。每条都配了实操步骤、配置示例和报错排查方法。1. 先把Codex和反代这件事的来龙去脉理清楚1.1 Codex是什么默认的请求链路长什么样Codex是OpenAI推出的命令行AI编程智能体。它跟普通的AI聊天助手不太一样你在终端里给它一个任务它会自动去读取当前项目的文件结构、定位相关代码、生成修改方案甚至可以自己执行命令、改完代码之后做验证整个工作流非常接近一个真实工程师的操作方式。它有自己的CLI工具安装之后通过codex exec或者交互式codex命令使用。使用前提是你得有一个能访问OpenAI服务的身份凭证官方支持两种一种是ChatGPT账号登录通过codex login完成另一种是OpenAI API Key通过环境变量注入。在不做任何配置的情况下Codex客户端的请求链路是这样的Codex CLI - https://api.openai.com/v1/responses - OpenAI官方模型也就是说Codex默认把所有请求发到OpenAI自己的API上用的是OpenAI新的Responses API协议。这个链路本身没什么问题问题在于很多人的实际场景根本不是“我要用OpenAI官方模型”而是“我想让Codex这个好用的外壳接上我自己买的第三方模型服务”。1.2 反代解决的真实痛点以及它的边界所谓“反代Codex”本质上就是在Codex客户端和真实的模型服务之间插入一个本地代理。这个代理接收Codex发出来的请求把请求转给目标模型服务比如DeepSeek再把响应原样传回来。对于Codex客户端来说它觉得自己在跟OpenAI官方API说话其实背后真正干活的是你指定的那个服务。实际使用中大家反代Codex的动机主要有几类。第一是想接国内模型比如DeepSeek、Kimi、通义这类这些模型在代码理解和中文表达上有自己的优势而且调用成本更低。第二是想把多个模型统一管理通过一个中转网关做负载均衡不同项目用不同模型。第三是想用自己已有的API渠道不想再单独开一份OpenAI的订阅或Key。但这里要特别说清楚一个边界反代是API转发不是网络通道。它的作用是把你本地的请求指向另一个服务地址它解决的是“接口地址不匹配”“服务商不兼容”“Key分散管理”这些问题。如果你的诉求是“网络链路本身不稳定”那反代帮不了你底层网络能不能访问到目标服务这是前提条件。2. 两条主流反代路线协议直通与协议转换2.1 路线一目标服务本身兼容Responses API直接Nginx透传如果你要接的目标服务本身已经支持OpenAI的Responses API那反代这件事会非常简单本质上就是一层透明的流量中转。你完全不需要写任何业务代码装一个Nginx配一段反向代理规则就够了。比如你把本地8080端口收到的所有请求转发到目标服务地址上并注入访问凭证。具体配置如下server { listen 8080; location / { proxy_pass https://your-upstream-endpoint.com; proxy_set_header Authorization Bearer sk-your-key; proxy_http_version 1.1; proxy_set_header Connection ; proxy_buffering off; } }这里两个细节很关键。第一个是proxy_buffering off必须加上因为Codex和模型的交互大量依赖流式响应也就是SSEServer-Sent Events。如果Nginx开了缓冲它会等上游响应攒够了再一次性吐给客户端Codex那边就会表现为“长时间没有反应然后突然全部输出”甚至直接报连接中断。第二个是Connection 要设置成空因为流式响应需要长连接不能让Nginx主动去关掉上游的连接。这种直通方式的优势是延迟极低几乎没有额外的性能损耗而且调试简单上游返回什么Codex就收到什么问题定位很直接。缺点也很明显前提是目标服务必须完整实现Responses API目前除了OpenAI官方的兼容端点之外很多模型服务商并没有提供这个接口你直接转发过去对方会回一个404。2.2 路线二目标服务只兼容Chat Completions需要加一层中转网关现在很多模型服务商包括DeepSeek对外提供的是OpenAI兼容的Chat Completions API也就是/v1/chat/completions这个接口。但Codex默认用的是/v1/responses接口。这两个协议有明显区别需要先搞清楚。打个比方Responses API像一份完整的项目文件夹里面有任务要求、原始材料、中间草稿、批注修改最后还有一份结果摘要结构非常规范。而Chat Completions API更像一条聊天记录一问一答你发消息过去它回消息过来结构简单直接。Codex默认想收的是“项目文件夹”但DeepSeek们只提供“聊天记录”所以中间就必须有一个人来做转换。这个转换工作可以自己写也可以用现成的网关工具。目前在社区里比较常见的选择是各类开源API网关比如new-api、one-api这类。它们本来是用来管理和分发各种大模型API的支持把上游的OpenAI格式接口转换成下游各种非标准协议也支持把Chat Completions协议暴露成一个更完整的接口。你在网关里配置好DeepSeek的渠道再把Codex的base_url指到网关地址网关就会自动完成协议转换。用网关的好处是配置界面化不需要写代码而且一次配好之后后续添加新模型、切换模型都非常方便。缺点是中间多了一层服务会带来几毫秒到几十毫秒不等的额外延迟而且网关本身也是一个需要维护的进程。2.3 自写Node代理实现协议转换核心代码思路如果你不想部署一个完整的网关只想在本地跑一个轻量代理完全可以自己写一个Node脚本。先看最简单的透明转发版本它做的事情就是“换个地址、换个鉴权头把流原样透传”。const http require(http); const https require(https); const PORT 8080; const UPSTREAM_HOST your-upstream.example.com; const UPSTREAM_TOKEN process.env.UPSTREAM_TOKEN || ; http.createServer((req, res) { const upstreamReq https.request({ host: UPSTREAM_HOST, path: req.url, method: req.method, headers: { Content-Type: application/json, Authorization: Bearer ${UPSTREAM_TOKEN}, ...req.headers, }, }, upstreamRes { res.writeHead(upstreamRes.statusCode, { Content-Type: upstreamRes.headers[content-type] || application/json, }); upstreamRes.pipe(res); }); req.pipe(upstreamReq); upstreamReq.on(error, err { res.writeHead(502); res.end(JSON.stringify({ error: err.message })); }); }).listen(PORT, () { console.log(proxy listening on ${PORT}); });这一段代码只适合“上游也支持相同API路径”的场景比如上游也是Responses API兼容服务。如果你的上游是DeepSeek这种只支持/v1/chat/completions的那么最简单的办法是在代理层做路径重写把/v1/responses重写成/v1/chat/completions。const upstreamPath req.url.startsWith(/v1/responses) ? /v1/chat/completions req.url.slice(/v1/responses.length) : req.url;但只重写路径还不够请求体的格式也得跟着变。Responses API的请求体长这样{ model: gpt-5.4-ms, instructions: 你是一个代码审查助手仔细阅读项目代码并找出潜在问题。, input: 请检查src/utils.ts这个文件的错误处理逻辑 }而Chat Completions的请求体长这样{ model: deepseek-chat, messages: [ {role: system, content: 你是一个代码审查助手仔细阅读项目代码并找出潜在问题。}, {role: user, content: 请检查src/utils.ts这个文件的错误处理逻辑} ] }所以在代理里需要做一次映射把instructions塞到messages的第一条system消息里把input塞到user消息里。响应方向也一样Chat Completions返回的是choices[0].message.content需要转成Responses API期望的output结构。完整做下来代码量并不小还要处理流式SSE事件的格式转换。所以我的实际建议是如果你只是想快速用起来优先考虑现成网关自己写代理适合对协议非常熟悉、需要深度定制的场景。3. 从零到一安装Codex并一步步配通第三方模型3.1 安装Codex客户端与登录鉴权先把最基础的安装走一遍。Codex可以通过npm全局安装前提是你本机已经有Node.js环境建议Node.js版本在18以上。安装命令很简单npm install -g openai/codex装完之后验证一下版本codex --version如果提示找不到命令大概率是npm的全局bin目录没有加到PATH里。Windows上常见于npm安装路径带空格的情况macOS/Linux上一般是nvm版本管理导致的路径问题。安装完成之后先选一种鉴权方式。如果你要用OpenAI官方服务直接运行codex login浏览器会跳出来完成OAuth登录。如果你要用第三方模型服务不需要登录ChatGPT只需要在环境变量里设好API Key并在config.toml里把它指定给对应的env_key字段。3.2 理解config.toml里每个关键字段Codex的配置文件在用户目录下的.codex文件夹里Windows上一般是C:\Users\你的用户名\.codex\config.tomlmacOS/Linux上一般是~/.codex/config.toml。第一次运行Codex时它会自动创建一个默认配置你也可以手动创建。一个典型的反代配置长这样model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek via Local Proxy base_url http://127.0.0.1:8080/v1 env_key DEEPSEEK_API_KEY wire_api chat逐行解释一下每个字段的含义。model是你要用的模型名称这个名称会被原样传到上游服务所以必须填上游服务实际支持的模型名比如DeepSeek就填deepseek-chat而不是填gpt-5之类的OpenAI型号。model_provider是一个逻辑名字用来引用下面定义的provider配置可以随便起但最好见名知义。[model_providers.deepseek]定义一个名为deepseek的provider配置块。name只是显示用的别名不影响功能。base_url是代理服务的基础地址注意末尾要带/v1。Codex会在这个地址后面拼接具体的API路径比如/v1/responses或/v1/chat/completions。如果这里漏掉/v1你会在日志里看到路径变成/responses或/chat/completions大概率直接404。env_key是环境变量名Codex在发起请求时会从环境变量里读取这个变量的值作为Authorization: Bearer xxx。比如上面配了DEEPSEEK_API_KEY那你运行Codex之前就要先导出这个环境变量。wire_api是协议类型有两个可选值responses和chat。官方默认是responses但如果你走的是本地代理或网关做协议转换而且上游最终消费的是Chat Completions格式那么这里建议配成chat。具体配哪个取决于你的代理是否处理了协议转换如果代理层已经做了完整的转换你在这里配responses也没问题如果代理只做透明转发那就要让Codex自己用Chat Completions协议发请求配chat。3.3 实操让Codex接到DeepSeek网关中转版现在以“Codex接DeepSeek”为例走一遍完整流程。这个方案我实测比较稳适合大多数人的需求。第一步准备好DeepSeek的API Key。到DeepSeek开放平台创建一个Key记下来后面要用。第二步部署一个网关。以new-api为例官方文档提供了Docker Compose的一键部署方式跑起来之后在管理后台创建一个渠道类型选择OpenAI兼容模型填deepseek-chatBaseURL填DeepSeek的API地址即https://api.deepseek.comKey填上一步创建的DeepSeek Key。保存之后网关会分配一个本地的访问地址比如http://127.0.0.1:3000。第三步修改Codex配置文件。编辑~/.codex/config.toml填上这一段model deepseek-chat model_provider ds-gateway [model_providers.ds-gateway] name DeepSeek Gateway base_url http://127.0.0.1:3000/v1 env_key DEEPSEEK_API_KEY wire_api chat注意这里的base_url指向的是本地网关而不是DeepSeek的官方地址。网关会负责把OpenAI格式的请求转换并转发到DeepSeek。第四步导出环境变量并启动export DEEPSEEK_API_KEYsk-1122334455 codex exec 请检查当前目录下代码的异常处理逻辑如果一切正常Codex会读取当前项目文件按照你的指令进行分析和操作。至此一个完整的反代链路就通了。3.4 实操通过本地Node代理完成直通含完整代码另一种选择是不用网关直接在本地写一个极简Node代理把Codex的请求转发到上游。我这里给出一个更完整的版本支持基本的流式返回和透传适合上游本身已经是OpenAI兼容格式的情况。const http require(http); const https require(https); const PORT 8080; const UPSTREAM_HOST api.deepseek.com; const UPSTREAM_TOKEN process.env.UPSTREAM_TOKEN || ; http.createServer((req, res) { const upstreamReq https.request({ host: UPSTREAM_HOST, path: req.url, method: req.method, headers: { Content-Type: application/json, Authorization: Bearer ${UPSTREAM_TOKEN}, }, }, upstreamRes { res.writeHead(upstreamRes.statusCode, { Content-Type: upstreamRes.headers[content-type] || application/json, Cache-Control: no-cache, Connection: keep-alive, }); upstreamRes.pipe(res); }); req.pipe(upstreamReq); req.on(error, () { if (!res.headersSent) { res.writeHead(502); } res.end(); }); upstreamReq.on(error, () { if (!res.headersSent) { res.writeHead(502); } res.end(); }); }).listen(PORT, () { console.log(local proxy listening at http://127.0.0.1:${PORT}); });把这个脚本保存为proxy.js运行export UPSTREAM_TOKENsk-yours node proxy.js如果上游只支持/v1/chat/completions而你希望Codex用responses协议来发请求那就要在代理里加路径重写和请求体转换这部分的逻辑相对复杂建议直接走网关路线比自写适配层省心很多。我自己第一次尝试自写适配层时光处理SSE流格式就花了两个小时后来换成网关五分钟就通了。4. 高频报错与避坑实录4.1 出现cc switch local proxy failed该怎么查这个报错是最近社区里问得最多的一个完整信息一般是cc switch local proxy failed while handling codex endpoint /responses。触发场景通常是你在config.toml里配置了model_provider指向一个本地代理地址然后在codex exec启动时客户端尝试访问这个本地代理但连接失败了。排查思路从最外到最内走一遍。第一步确认代理服务到底有没有启动。很多人配好了配置文件却忘了先启动本地代理脚本或者忘了启动网关容器Codex一上来连本地端口就直接拒绝连接。在终端里手动访问一下确认curl http://127.0.0.1:8080/v1/responses如果报Connection refused那说明本地服务没起来先去跑代理。第二步确认端口是否匹配。config.toml里base_url写的端口必须和代理监听端口一致。你代理监听8080配置里写成了9090那连接失败是必然的。第三步确认路径前缀。前面说过base_url末尾要带/v1如果你漏掉了客户端会请求http://127.0.0.1:8080/responses而不是/v1/responses代理返回404Codex同样会把这个当成“proxy failed”。还有一个容易被忽略的点Codex在启动时有自己的健康检查逻辑它会尝试访问本地代理的某个端点如果代理转发时把上游的鉴权错误直接返回来比如401或403Codex会认为代理不可用。这种时候先单独调试上游确保直接用curl访问上游API是通的再回头排查代理链路。4.2 其他常见报错速查表把这段时间大家问得多的问题整理成一张表方便你直接对照排查。报错信息常见原因解决办法codex auth token is unavailable没有配置有效的API Key或未完成登录检查环境变量是否设了env_key指定的变量或重新执行codex loginmodel not supportedmodel字段填的模型名在上游不存在改成上游服务真实支持的模型名比如DeepSeek填deepseek-chatWindows安装未完成Node版本过低、npm缓存异常、网络下载中断升级Node到18执行npm cache clean --force后重装404 Not Foundbase_url路径不对或上游没有对应API路径确认base_url以/v1结尾确认上游支持/v1/chat/completions或/v1/responses401 Unauthorized鉴权头不对或API Key无效检查环境变量是否真的导出了KeyKey是否复制完整500 Internal Server Error上游服务异常或请求体格式转换错误查看代理/网关日志确认目标服务状态这里单独说一下model not supported这件事。Codex的配置里model字段不只是显示用它会直接影响客户端的行为客户端甚至会根据模型名称决定启用哪些工具调用能力。如果你填了一个上游不认识的模型名上游返回错误Codex的报错会特别绕。最直接的解法就是把model填成上游确切支持的名称不要想当然填OpenAI的模型名。4.3 几个平时没人细说的细节最后分享几个我在实际配置中踩过之后才意识到的问题这些细节官方文档基本不会写。第一个是环境变量的作用时机。config.toml里的env_key是在Codex进程启动时读取一次所以你改了环境变量之后必须重启Codex进程否则它拿到的还是旧值。很多人在一个终端里改了export DEEPSEEK_API_KEY...但在另一个终端里运行Codex结果永远鉴权失败就是因为这个。第二个是token缓存问题。如果你之前用codex login登录过ChatGPT账号之后又改成API Key方式首次请求时Codex可能会优先走已缓存的token而缓存凭证已经失效出现auth token is unavailable。解决办法是运行codex logout清掉旧凭证或者直接删掉~/.codex/auth.json目录下的缓存文件再试。第三个是流式输出抖动问题。如果你发现Codex输出内容断断续续或者偶尔报连接中断但重试之后又能成功多半是代理层没有正确透传SSE流。在Nginx里要加proxy_buffering off在Node代理里不要用res.end()提前切断流整个过程中不要对响应内容做buffer直接把上游的流pipe给客户端就行。第四个是“本地代理网关”组合的趣事。很多人一开始很排斥“套娃”觉得代码里再加一层网关很蠢但实际操作下来Codex加网关接DeepSeek反而是最稳的组合。因为网关把协议转换、token管理、模型路由、错误归一化都处理好了Codex那端只需要一份很干净的配置。追求极简没有错但在“能不能稳定跑通”这件事上多一点工程冗余反而更省心。我自己实际配下来最大的体会是反代Codex这件事90%的工作量都在理解协议差异上。一旦弄懂了responses和chat是两种不同的对话协议弄懂了base_url路径拼接规则剩下的事情就是填配置。如果你照着这篇文章配了一遍还是没通建议按第4章的排查顺序走一遍尤其是先确认本地代理到底起没起、端口通不通这两个问题占了所有报错的一大半。最后再提醒一个细节配置文件改完之后务必备份一份原始的config.toml改坏了随时能还原别问我怎么知道的。