Codex CLI 接入 DeepSeek 配置指南：解决 /responses 报错

最近在不少技术讨论区里看到同一个配置问题Codex CLI 装好了第一件事不是问它能干什么而是问怎么让 Codex 接上 DeepSeek 的模型。有人想用 DeepSeek_v4-Flash 这类模型降低日常编码助手的成本有人只是不想把代码上下文全部交给默认服务还有人纯粹是团队内部统一使用 DeepSeek 的接口。但实际动手时很多人卡在同一个地方执行模型切换时终端冒出一条和 codex endpoint/responses相关的本地转发失败报错然后就没有然后了。这个报错的字面意思是本地转发层在处理 Codex 发出的/responses请求时失败。表面看是网络问题其实是两层东西没对上Codex 默认用 Responses API 格式而 DeepSeek 这类第三方服务通常走的是 Chat Completions。这篇文章把这件事讲透从底层差异、配置步骤、报错排查到长期使用边界一次说清楚。需要先说明一点我下面提到的 DeepSeek_v4-Flash是在很多讨论里出现的模型标识之一。无论它在你所在的模型平台里叫deepseek-v4-flash、deepseek-chat还是deepseek-reasoner接入 Codex 的逻辑都一样。模型名属于动态信息落地前以服务商控制台里实际看到的为准。1. 先搞清楚 Codex 接入 DeepSeek 这件事卡在哪1.1 Codex CLI 默认只连一个端点所有自定义都围绕它展开Codex CLI 并不是一个只能连官方模型的封闭工具。从代码仓库和官方文档能看到它支持通过model_provider定义自定义模型源。你可以自己指定一个base_url告诉 Codex 把请求发到哪里还可以指定一个env_key告诉 Codex 从哪个环境变量里读 API Key。这套机制存在的意义就是让不同模型后端以统一方式接入。但这里有个隐藏约束Codex 的请求格式不是随便定的。它默认走 Responses API也就是端点为/responses的接口。OpenAI 自己的模型很自然支持这个格式但第三方模型服务未必。很多服务商提供的是 OpenAI 兼容的/chat/completions接口两者请求体和返回结构都不一样。所以接入第三方模型的关键不是“能不能连”而是“用哪种协议连”。Codex 的配置文件里有一个wire_api字段取值通常是responses或chat。如果后端服务支持 Responses API就填responses如果只提供 Chat Completions就填chat。大部分 DeepSeek 类服务只能走chat。这个字段就是很多报错的源头。你把wire_api留成了默认值但后端根本不提供/responses本地转发层自然会失败。先记住这一点后面排查会容易很多。1.2 DeepSeek_v4-Flash 这类模型的接入路径从使用路径看接入第三方模型通常有三条路如果服务商官方提供 OpenAI 兼容端点直接改base_url走/chat/completions。如果服务商提供的是 Responses API那wire_api保持responses就行。如果服务商什么都不兼容那需要自建一个转换层把 Codex 的请求格式转成后端能识别的格式。绝大部分 DeepSeek 接入场景属于第一种。你只需要确认三件事接口地址、API Key、模型标识。比如常见配置里接口基础地址可以是https://api.deepseek.com/v1鉴权用 Bearer Token模型标识在服务商控制台里看。这里有一点需要提醒很多讨论里出现“一键配置”的说法说的是配置好之后每次启动只需要一条命令而不是指安装过程全程自动。真正的一键是你把 provider、model、API Key 都固化在配置文件里之后打开终端输入命令就直接进入编码会话。后面我会演示怎么固化。1.3 为什么 /responses 是最大分水岭Responses API 和 Chat Completions API 的区别不只是路径不同。Responses API 引入了input、instructions、tools等更结构化的字段Chat Completions 则是更通用的messages数组。Codex 在处理多轮对话、工具调用、代码执行时会依赖这些结构差异。如果后端只支持 Chat Completions但你配置成 Responses常见的表现是请求发出去对方返回 404或者返回一个结构不对的 JSON本地转发层解析失败于是报出类似failed while handling codex endpoint /responses这类错误。反过来如果后端支持 Responses API但你配置成 Chat Completions通常也能用只是可能丢掉 Codex 特有的一些功能和元数据。所以最稳妥的做法是优先看服务商文档确认它支持哪种接口如果文档没有明确说支持 Responses那就走 Chat Completions。2. 动手前先把这几件事确认了能避开一半报错2.1 安装 Codex CLI 并确认入口命令写命令前先说明Codex CLI 的安装方式会随版本变化这里只给最常见路径。通常可以通过 npm 全局安装Node.js 环境是前置条件。如果你本机已经装过 Codex先跑一下版本命令确认和当前文档或配置示例的字段兼容。Node.js 版本太旧可能导致安装或运行异常版本太新也可能遇到某个依赖还没适配。遇到奇怪问题先看看官方仓库的要求再检查 Node 版本。安装完成后确认入口命令。有的版本是codex有的场景里会看到cc作为别名。启动前先用codex --version或codex --help验证命令可以正常调用。这一步看起来多余但能排除 PATH 没配好、安装中断这类基础问题。如果你本机还装了cc-switch这类配置切换工具要注意它和官方 CLI 是两个东西。很多人把cc switch当成官方命令其实它可能是第三方工具提供的入口。报错信息里出现的cc switch local ... failed while handling codex endpoint /responses通常就是这类工具在切换模型时本地转发层处理请求失败。这不意味着官方 Codex 有问题而是你用的切换工具/网关层需要单独看日志。2.2 API Key、Base URL、模型标识三件套在动配置文件之前先把三样东西找齐API Key在模型服务商的控制台创建注意别提交到 Git 仓库。Base URL服务商给的 API 基础地址常见是https://api.deepseek.com/v1这类格式。有的服务商文档写https://api.deepseek.com实际取 v1 路径时要在后面拼接。这里一定要以服务商文档为准。模型标识也就是model字段。不要只看宣传材料里的名字要去服务商控制台或接口文档里确认确切的模型名。模型标识最容易出错。你听说某个模型叫 DeepSeek_v4-Flash但接口里可能真的不叫这个名字也可能是新上线的模型某个时段没有开放。配置后如果报model not found大概率是模型标识写错了。2.3 先跑通一次接口探测再动 Codex 配置这个习惯可以帮你省掉大量排查时间。在改 Codex 之前先用 curl 直连服务商接口确认 Base URL、API Key、模型标识三者能组合出一个成功的请求。比如用 Chat Completions 接口做一个最小请求curl https://api.deepseek.com/v1/chat/completions \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -H Content-Type: application/json \ -d {model: deepseek-chat, messages: [{role: user, content: hello}]}如果返回正常的 JSON 结果说明 API Key、Base URL、模型名都正确。如果返回 401先检查 Key返回 404检查 Base URL 和模型名返回 400检查请求体格式。这一步能把“Codex 配置问题”和“上游接口问题”彻底分开。很多人直接改 Codex 配置报错后以为是 Codex 的锅实际上 curl 上来就是 404。先做接口探测后面的排查思路会清晰很多。3. 手把手配置 config.toml跑通第一次对话3.1 配置文件在哪里Codex CLI 的配置文件一般放在用户目录下的.codex文件夹里。macOS/Linux 是~/.codex/config.tomlWindows 通常是%USERPROFILE%\.codex\config.toml。不同版本可能支持--config参数指定其他路径但默认位置基本一致。配置文件是 TOML 格式大小写和缩进没有 Python 那么严格但要保证字段名正确。改之前最好先备份一份原始配置。如果你用第三方工具管理配置也要注意工具生成的配置和官方配置的字段可能不互通不要混着写。3.2 一个可用的 model_provider 示例下面是一个接入 DeepSeek 类服务的常见配置结构# 全局默认模型 model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat解释一下每个字段的作用model默认使用的模型标识要和服务商接口里的实际模型名一致。model_provider默认使用的 provider 名称对应后面[model_providers.deepseek]这一节的名字。base_url接口基础地址。Codex 会把请求拼到这个地址上具体拼到什么路径取决于wire_api。比如wire_api chat时可能请求{base_url}/chat/completions所以基础地址一般写到/v1这一层。env_key告诉 Codex 从哪个环境变量读取 API Key。这里的名字可以自己定但一般建议写成和你环境变量一致的名字。wire_api