1. 从 404 说起Codex CLI 撞上 Chat Completions 后端你刚把 Codex CLI 的 base_url 指向公司内网的推理集群回车一敲屏幕上蹦出来一行红字ERROR: 404 Not Found - Unknown endpoint: POST /v1/responses密钥没问题网络没问题防火墙也没拦。问题出在协议层Codex CLI 发出去的是 Responses API 请求POST /v1/responses而你的后端只认 Chat CompletionsPOST /v1/chat/completions。两边都没错只是说的不是同一种话。Responses API 是 OpenAI 新一代的模型调用接口它把输入输出组织成类型化的 Item——message、function_call、reasoning、refusal 各自独立还支持服务端状态续接。Chat Completions 则是老一代的 messages 数组role 和 content 捆在一个对象里无状态多轮对话靠客户端自己攒历史。Codex CLI、Claude Code 这类新一代 Agent 工具正在全面转向 Responses API而 DeepSeek 私有化部署、Ollama、旧版 vLLM 这些后端仍然只说 Chat Completions。两头都在长中间的断层就越拉越宽。协议转换代理就是架在断层上的桥。它接收 Responses 格式的请求翻译成 Chat Completions 发给后端再把后端的响应回译成 Responses 格式返回给客户端。本文聚焦两套经过实测的转换代理——responses-proxyRust和 completion-to-responseGo给出可复制的配置文件、TaoToken 统一 Key 与 Base URL 的填写位置并演示一次完整请求验证协议转换是否生效。适合正在用 Codex CLI 接非 OpenAI 后端、或者准备把 Agent 工具接入统一网关的开发者。先花五分钟确认一件事你的后端到底支不支持 Responses API。截至 2026 年 9 月的官方文档实况是vLLM 最新版的 OpenAI-Compatible Server 文档已经包含 Responses API 章节DeepSeek 官方 API 侧栏也出现了 Using the Responses API 指南入口。如果你的后端已经原生支持那就不需要代理直接改 base_url 就行。但只要你的基础设施里还有一份旧版 vLLM 或者一个 Ollama这座桥就仍然值得架。2. TaoToken 统一 Key 与 Base URL 的前置准备在部署代理之前先把上游的接入信息准备好。TaoToken 提供统一的 API Key 和 Base URL你可以用它来对接多个模型后端省去在每个代理配置里分别填不同厂商密钥的麻烦。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数。你需要先在控制台创建一个 API Key这个 Key 就是后面配置里provider.api-key要填的值。如果你还没有 Key可以到 API Keys 页面生成一个。这里要区分两把不同的“钥匙”。第一把是代理自己的门禁钥匙配置在auth.keys里用来防止局域网里其他人白嫖你的代理第二把是后端的钥匙配置在provider.api-key里是真正用来调用上游模型服务的凭证。新手最容易犯的错误就是把这两把钥匙搞混——把 TaoToken 的 Key 填到auth.keys里结果代理启动后所有请求都被拒。TaoToken 的 Base URL 填写位置在provider.base-url字段。注意 responses-proxy 的base-url只写到域名或域名加路径前缀代理会自动拼接/chat/completions。如果你用的是 completion-to-response它的-url参数要求完整端点路径需要写成https://taotoken.net/api/v1/chat/completions这种形式。这个差异后面会反复提到先记在心里。模型名也需要提前确认。Codex CLI 默认请求的模型名是gpt-5.5而 TaoToken 侧实际可用的模型 ID 可能是deepseek-v4-pro或其他名称。你需要在代理的models段做一层映射把客户端请求的模型名翻译成后端认识的模型名。不翻译的话后端直接返回 404 model not found。如果你打算长期用 Codex CLI 做编码任务可以考虑 TaoToken 的 Coding Plan它针对编码场景做了优化。如果只是想先验证协议转换是否跑通用按量计费的 API Key 就够了。模型对话页面可以帮你快速确认某个模型 ID 是否可用省得在代理配置里反复试错。准备好这些信息后就可以进入实际部署环节了。下面先讲 responses-proxy 的完整部署流程再讲 completion-to-response 的轻量方案。3. responses-proxy 部署与 config.yaml 可复制配置responses-proxy 是一个 Rust 实现的协议转换代理支持 HTTP SSE 和 WebSocket 两种传输方式功能比较完整。它的设计特点是类型化边界进入代理的请求必须能反序列化为官方 Responses API 请求体出向和回向的 Chat 报文也都使用官方 Chat Completions 结构。协议不合就报错不会悄悄吞掉字段。对生产环境来说这种 fail-fast 比静默降级安全得多。先装 Rust 工具链然后克隆代码# 安装 RustLinux/macOS curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh # 获取代码 git clone https://github.com/CallOrRet/responses-proxy.git cd responses-proxy # 编译并启动 cargo run # 输出Listening on 0.0.0.0:3000默认监听0.0.0.0:3000。这里有个运维要点0.0.0.0意味着局域网可达如果不配鉴权就等于裸奔。另外截至 2026 年 9 月这个仓库的 Releases 区还是空的README 的 Quick Start 也只给了cargo run一条路所以需要本地编译。接下来是核心的config.yaml。下面这份配置可以直接复制修改关键位置我都标了注释# responses-proxy 配置文件 server: listen: 0.0.0.0:3000 # 监听地址 timeout: 600 # 全局请求超时秒 log-level: info # trace|debug|info|warn|error auth: keys: [] # 非空即启用鉴权请求需带 Authorization: Bearer key # /health 永远开放不受鉴权影响 cors: allow-origins: [] # 空 允许任意来源生产请白名单化 models: gpt-5.5: # 客户端请求的模型名Codex 默认 model: deepseek-v4-pro # 实际下发到后端的模型名 provider: api-key: $TAOTOKEN_API_KEY # 支持 $VAR 环境变量引用 base-url: https://taotoken.net/api # 代理实际请求 {base-url}/chat/completions timeout: 60 # provider 级超时覆盖 server.timeout codex-auto-review: # codex review 命令会请求这个模型名 model: deepseek-v4-flash provider: api-key: $TAOTOKEN_API_KEY base-url: https://taotoken.net/api allowed-tool-types: - function # 默认值不在白名单内的工具类型会被丢弃这份配置里有三个细节值得单独说。第一base-url只到域名或路径前缀代理会自动拼/chat/completions你不需要也不应该自己拼/v1/chat/completions。第二model键做了模型名翻译Codex CLI 硬编码请求gpt-5.5而 TaoToken 侧实际模型是deepseek-v4-pro不翻译后端直接 404。第三auth.keys和provider.api-key是两把不同的钥匙前者是代理门禁后者是后端凭证。启动时用--config指定配置文件路径cargo run -- --config /path/to/config.yaml如果排查转换问题把log-level调到debug或者用RUST_LOGdebug环境变量覆盖。日志里能看到每个请求的翻译过程和 Rewrite 规则的执行结果。responses-proxy 还有一个杀手锏是四阶段 JSON Rewrite。它允许你在协议翻译管线的四个固定时点执行字段级改写response-in解析后、chat-out发往上游前、chat-in收到响应后、response-out返回客户端前。操作符有 reset、rename、remove、replace 四种。比如老后端只认max_tokens不认max_completion_tokens就可以在chat-out阶段做一次 renamerewrite: - at: chat-out rename: max_completion_tokens: max_tokens这个机制解决的是“后端不认识某个字段”的最后一公里问题。配置是严格校验的未知字段、空 stage、非法正则都会让代理启动即失败这是好事能提前暴露配置错误。4. completion-to-response 轻量方案与 Codex CLI 集成completion-to-response 是一个 Go 实现的单二进制转换代理纯标准库零外部依赖。它的优势是五分钟就能跑通适合快速验证链路。需要注意的是这个项目已于 2026 年 8 月 16 日被所有者归档转为只读状态。归档不等于不能用但意味着 Issue 无人处理、安全补丁不再更新、下游 API 变更无人适配。获取二进制的方式是直接从 Releases 下载# Linux x86_64 curl -L -o completion-to-response \ https://github.com/NoahStepheno/completion-to-response/releases/latest/download/completion-to-response-linux-amd64 chmod x completion-to-response下载后建议立即计算 checksum 并记录确保未来重建环境时二进制完全一致。这是归档项目与活跃项目在运维上最大的差别。启动命令如下./completion-to-response \ -url https://taotoken.net/api/v1/chat/completions \ -model deepseek-v4-pro \ -port 8080 \ -timeout 600s注意这里和 responses-proxy 的两处心智差异-url要给完整端点路径含/v1/chat/completions不指定端口时默认监听 8080 而非 3000。-timeout默认是 30 秒对推理模型来说太短了思考模式动辄超过一分钟会被中途掐断接推理后端请显式调大。CLI 参数全表如下参数说明默认值-url后端 Chat Completions 端点必填—-model覆盖所有请求的模型名-default-model客户端未指定模型时的回退gpt-4o-port监听端口8080-key后端 API Key回退用优先透传客户端 Authorization-timeout后端请求超时30s-log日志写文件而非 stderrAPI Key 采用双通道设计优先透传客户端的Authorization: Bearer key-key仅在客户端没带头时兜底。生产建议只留透传密钥不落盘。接下来是 Codex CLI 的集成配置。在~/.codex/config.toml里加一行openai_base_url http://localhost:3000/v1这行配置写进用户级配置文件后Codex 的所有请求都会经过代理。这里有个关键事实openai_base_url是官方配置键但它在项目级.codex/config.toml里会被忽略必须写在用户级~/.codex/config.toml。我试过把openai_base_url写进项目级配置自测一切“正常”没报错但请求根本没走代理直到在网关日志里看到直连流量才反应过来。配置层级对照配置层级位置provider 相关键用户级~/.codex/config.toml生效项目级项目/.codex/config.toml被忽略完成集成后用codex起一个会话同时在代理端把日志切到 debug确认看到POST /v1/responses进入且 warmup 请求被正确处理即为集成成功。如果你用的是其他支持自定义 Base URL 的 Responses 客户端把地址指向代理即可。端口是两个方案最常见的混用事故点responses-proxy 默认 3000completion-to-response 默认 8080。客户端报 Connection refused 时第一反应应该是核对端口与路径。5. 验证请求与常见报错排查部署完成后用 curl 三连验证链路是否通# ① 健康检查无鉴权 curl http://localhost:3000/health # ② 列出已配置模型 curl http://localhost:3000/v1/models # ③ 发送一个真实的 Responses 请求 curl http://localhost:3000/v1/responses \ -H Content-Type: application/json \ -d { model: gpt-5.5, input: What is 22? Reply with just the number. }第③步若返回带object: response、output 数组、usage.input_tokens 的 JSON链路即通。验证时故意用错模型名确认代理报错信息友好也是压测前的好习惯。下面是一张常见错误速查表对照真实报错定位问题症状根因处置404 Unknown endpoint /v1/responses后端不支持 Responses部署代理或升级后端401 Unauthorizedauth.keys 与 provider.api-key 混淆检查两把钥匙的填写位置local proxy failed / Connection refused端口混用rp3000c2r8080请求 404 model模型名未映射models 段配置 model: 下游名reading choices 报错响应格式不符合预期检查后端是否返回标准 Chat 格式OAuth 相关报错客户端走了官方鉴权流程确认 base_url 已指向代理长推理被掐断c2r 默认 -timeout 30s显式 -timeout 600s字段被后端拒绝400新字段名老后端不认chat-out renameCodex 工具失效工具类型不在白名单allowed-tool-types 放开续接报错代理重启丢状态持久化或优雅降级关于 401 报错再展开说一下。如果你在auth.keys里配了值客户端请求必须带Authorization: Bearer key头。如果你把 TaoToken 的 Key 填到了auth.keys里而provider.api-key留空代理会用自己的门禁钥匙去请求后端后端当然不认。正确的做法是auth.keys填你自己生成的代理访问密钥provider.api-key填 TaoToken 的 Key。关于reading choices报错这通常出现在后端返回的不是标准 Chat Completions 格式时。有些私有化网关会在响应里加额外的包装层导致代理解析choices字段失败。这时候需要检查后端的实际响应体必要时在代理侧做响应改写。关于 OAuth 报错如果你看到客户端尝试走 OAuth 流程说明 base_url 没有生效客户端还在往官方端点发请求。回到 Codex CLI 集成那节确认openai_base_url写在了用户级配置文件里。流式场景下验证方法是把事件序列与拼接结果同时对拍。completion-to-response 的 README 给出了完整的九段事件序列response.created→response.in_progress→response.output_item.added→response.content_part.added→response.output_text.delta(×N) →response.output_text.done→response.content_part.done→response.output_item.done→response.completed。任何缺段或乱序都会现形。另外别忘了端到端体验指标代理多加了一跳首字延迟会同步叠加验收时应对比“直连后端”与“经代理”两组数据。6. 选型建议与接入路径两套方案各有适用场景。responses-proxy 功能完整支持 WebSocket、推理内容映射、工具调用往返、多模型路由、会话续接和鉴权项目活跃Apache-2.0 许可。completion-to-response 轻量单二进制即跑五分钟出结果但已归档不支持 WebSocket 和推理内容映射默认超时偏短。选型建议很直接生产环境用 responses-proxy快速验证用 completion-to-response。先跑通 completion-to-response 验证链路再迁移到 responses-proxy 固化生产这是比较稳妥的实操路径。如果你需要多协议网关同时支持 OpenAI、Anthropic、Responses可以评估 cmc-proxy 等备选方案但建议先核实仓库的维护状态和 Release 资产。长期来看代理是桥不是终点。vLLM 最新版已经原生支持 Responses APIDeepSeek 官方也有 Responses 指南。如果你的后端可以升级优先推动升级能省掉整套代理运维。代理的价值在于存量旧版集群和私有化部署场景。接入路径上如果你还没有 TaoToken 的 Key先到 API Keys 页面生成一个。想快速确认模型 ID 是否可用用模型对话页面试一下。准备长期用 Codex CLI 做编码任务的话Coding Plan 针对编码场景做了优化。接入文档里有完整的 Base URL 和鉴权说明配置代理时对照填写即可。最后给一份部署检查清单按顺序过一遍能避开大部分坑后端版本已确认是否原生支持 Responses API端口与路径核对rp 的 base-url 不含路径c2r 的 -url 含完整路径超时已按后端特性调整推理后端 ≥ 600sauth.keys 非空CORS 收敛为白名单工具类型白名单覆盖业务所需归档依赖已完成 fork checksum 固化流式事件九段序列与 output_text 拼接对拍通过refusal 结构化保真验证通过。协议转换代理的本质是翻译加记忆加事件重排。字段映射、previous_response_id 状态代管、流式事件链重排三者缺一不可。这决定了它注定不是正则脚本而是带状态的服务。理解这一点后面排查任何转换问题都有了方向。