1. 为什么要在 Codex 里接入 DeepSeekCodex CLI 是 OpenAI 推出的命令行编程助手默认走的是 OpenAI 官方模型。但实际用下来官方额度和调用成本对高频使用者并不友好尤其是需要长时间跑重构、批量生成测试用例的场景token 消耗非常快。DeepSeek 的 API 在代码任务上的表现这两年进步明显价格又比官方低不少所以把 Codex 的后端切到 DeepSeek是很多开发者会考虑的一条路。这个教程要解决的问题很具体让 Codex CLI 不再调用 OpenAI 官方接口而是把请求转发到 DeepSeek 的 API 上同时保留 Codex 原有的交互体验。适合两类人看一是已经在用 Codex、想降低调用成本的开发者二是刚装好 Codex、想直接接第三方模型的新手。整个过程不复杂核心就是改一个config.toml文件但里面有几个坑比如配置项被忽略、401 报错、模型名写错导致 400这些我都会在下面拆开讲。需要提前说明的是Codex 的配置格式在不同版本之间有过调整网上很多老教程里的字段已经失效了。我下面给的方案基于当前主流版本的配置逻辑如果你用的是很旧的版本建议先升级再操作。2. 接入前的准备工作2.1 确认 Codex 已经正确安装第一步永远是确认 Codex 本身能跑起来。在终端里执行codex --version如果能看到版本号说明安装没问题。如果提示 command not found那得先解决安装。Codex 的安装方式主要有两种通过 npm 全局安装或者下载官方提供的安装包。npm 方式相对省事npm install -g openai/codex装完之后再跑一次codex --version验证。这里有个细节如果你之前装过旧版本建议先卸载再装避免残留的旧配置干扰。卸载命令是npm uninstall -g openai/codex。还有一种情况是 Windows 用户用 PowerShell 装完之后新开的终端里找不到命令这通常是 PATH 没刷新。关掉终端重新开一个基本就能解决实在不行重启一次。2.2 拿到 DeepSeek 的 API KeyDeepSeek 的 API Key 需要到它的开放平台申请。注册登录之后在控制台里创建一个新的 API Key复制出来保存好。这个 Key 的格式一般是sk-开头的一长串字符。注意API Key 只在创建时完整显示一次关掉页面就看不到了。一定要当场复制到安全的地方比如密码管理器。如果丢了只能重新创建一个。创建好之后建议先在终端里用 curl 测一下这个 Key 能不能用别等到配好 Codex 才发现 Key 是错的curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的key \ -d { model: deepseek-chat, messages: [{role: user, content: hi}] }如果返回正常的 JSON 内容说明 Key 有效。如果返回 401那就是 Key 有问题先解决这个再往下走。这一步能帮你排除掉后面一大半的报错。2.3 搞清楚 Codex 的配置文件在哪Codex 的配置文件叫config.toml位置在用户目录下的.codex文件夹里。不同系统的路径不一样系统配置文件路径WindowsC:\Users\你的用户名\.codex\config.tomlmacOS/Users/你的用户名/.codex/config.tomlLinux/home/你的用户名/.codex/config.toml如果这个文件不存在手动创建一个就行。文件夹.codex如果也没有一并创建。Windows 下路径里的用户名如果是中文一般不影响但偶尔会有编码问题后面排查部分会讲。3. 核心配置config.toml 怎么写3.1 最小可用配置结构Codex 接入第三方模型的核心是在config.toml里定义一个自定义的 model provider然后把默认模型指向它。下面是一个可以直接抄的最小配置model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat逐行解释一下。model指定默认使用的模型名这里写deepseek-chat对应 DeepSeek 的对话模型。model_provider指向下面定义的 provider 名字两边要一致。[model_providers.deepseek]这一段是定义 provider。base_url是 DeepSeek 的 API 地址注意这里不要带/v1或者/chat/completions这种后缀Codex 会自己拼接。env_key指定从哪个环境变量读取 API Key这样 Key 就不用明文写在配置文件里安全一些。wire_api指定通信协议DeepSeek 兼容 OpenAI 的 chat 格式所以写chat。3.2 API Key 的环境变量设置配置文件里写了env_key DEEPSEEK_API_KEY那系统里就得有这个环境变量。设置方法按系统来Windows PowerShell临时当前窗口有效$env:DEEPSEEK_API_KEY sk-你的keyWindows 永久设置用系统设置里的环境变量界面或者命令行setx DEEPSEEK_API_KEY sk-你的keymacOS / Linux写到 shell 配置里echo export DEEPSEEK_API_KEYsk-你的key ~/.zshrc source ~/.zshrc提示setx设置完之后要新开一个终端才生效当前窗口读不到。这是很多人配完发现还是 401 的原因之一。3.3 关于 wire_api 的选择这里要单独说一下wire_api。Codex 支持两种协议chat和responses。chat对应的是传统的/chat/completions接口responses对应的是 OpenAI 新的 Responses API。DeepSeek 目前兼容的是 chat 格式所以必须写chat。如果你手贱写了responses会遇到类似这样的报错local proxy failed while handling codex endpoint /responses这个报错的意思就是 Codex 按 Responses 协议去请求但 DeepSeek 那边没有对应的接口直接失败了。所以记住接 DeepSeek 就用chat。4. 完整实操流程4.1 第一步备份原配置动手改之前先把原来的config.toml备份一份。这不是多此一举改坏了能快速回滚cp ~/.codex/config.toml ~/.codex/config.toml.bakWindows 下用文件管理器复制一份或者Copy-Item $env:USERPROFILE\.codex\config.toml $env:USERPROFILE\.codex\config.toml.bak4.2 第二步写入配置用任意文本编辑器打开config.toml把前面那段配置写进去。如果文件里已经有其他内容注意不要重复定义model和model_providerTOML 里重复的键会报错。一个常见的完整配置长这样model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat保存退出。4.3 第三步验证配置是否生效新开一个终端先确认环境变量在echo $DEEPSEEK_API_KEYWindows PowerShellecho $env:DEEPSEEK_API_KEY能打印出 Key 就对了。然后启动 Codexcodex进去之后随便问一个问题比如让它写个快排。如果正常返回说明接入成功。如果报错看下一节的排查部分。4.4 第四步确认走的是 DeepSeek怎么确认请求真的发到 DeepSeek 而不是 OpenAI最直接的办法是去 DeepSeek 控制台看用量统计调用一次之后刷新能看到 token 消耗记录就说明通了。另一个办法是故意把 Key 改错如果报 401 且错误信息里提到 DeepSeek 的域名也能侧面证明请求路由对了。5. 常见报错与排查5.1 401 UnauthorizedKey 不对最常见的报错长这样unexpected status 401 Unauthorized: incorrect api key provided: sk-svcac****这个基本就是 Key 的问题。排查顺序第一确认环境变量里的 Key 和 DeepSeek 控制台里的一致注意别多复制了空格或者换行。第二确认环境变量真的被读到了用echo命令验证。第三确认 Key 没有过期或者被删除。还有一种隐蔽情况你设置了环境变量但 Codex 是从另一个终端启动的那个终端没有继承到变量。解决办法就是所有操作在同一个新终端里做。5.2 400 报错模型名或上下文问题api error: 400 this models maximum context length is 1048576 tokens这个报错说明请求的上下文超了。DeepSeek 的模型上下文窗口虽然大但也不是无限的。如果你在 Codex 里让它读一个巨大的代码库很容易超。解决办法是缩小范围别一次性喂太多文件。另一种 400 是模型名写错了。比如你写了deepseek而不是deepseek-chat或者写了个不存在的模型名。DeepSeek 目前常用的模型名是deepseek-chat和deepseek-reasoner前者是通用对话后者是推理模型。按需选。5.3 配置项被忽略的警告codex is ignoring 1 unrecognized configuration setting. check for typos or deprecated settings.这个警告的意思是配置文件里有个字段 Codex 不认识。比如老教程里常见的mcp_servers.node_repl.type在新版本里可能已经改了结构。这种警告一般不影响主流程但最好清理掉避免以后出问题。处理办法就是找到那个字段查一下当前版本的文档看它现在叫什么或者直接删掉。5.4 配置文件加载失败chatgpt 无法加载 config.toml因此此对话串无法继续这种报错通常是 TOML 语法错误。TOML 对格式比较敏感少个引号、多个逗号都会导致解析失败。排查办法是用在线的 TOML 校验工具过一遍或者把配置精简到最小可用版本再一点点加回去。Windows 下如果用户名是中文路径里带中文偶尔会有编码问题。可以试着把.codex文件夹挪到一个纯英文路径下然后用环境变量CODEX_HOME指过去。5.5 常见问题速查表报错关键词可能原因解决办法401 UnauthorizedKey 错误或未读到检查环境变量重新设置400 context length上下文超限减少输入文件数量400 model not found模型名写错改用 deepseek-chatunrecognized setting配置字段过时删除或更新该字段无法加载 config.tomlTOML 语法错误用校验工具检查/responses 失败wire_api 写错改成 chat6. 实操心得与避坑建议6.1 关于成本控制DeepSeek 虽然便宜但 Codex 这种工具很容易在后台跑大量请求。建议在 DeepSeek 控制台设置一个用量提醒或者限额避免某次误操作跑飞了。我自己就遇到过一次让它重构整个项目结果一口气消耗了不少额度。6.2 关于模型选择deepseek-chat适合日常编码问答响应快。deepseek-reasoner适合复杂逻辑推理但速度慢一些而且对上下文长度更敏感。日常用 chat 就够了遇到难题再切 reasoner。6.3 关于配置的持久性环境变量这种方式重启终端或者重启电脑之后可能会丢。如果想让配置长期有效Windows 用setxmacOS/Linux 写进 shell 配置文件。别图省事每次手动 export迟早会忘。6.4 关于版本更新Codex 更新比较频繁配置格式可能会变。升级之后如果突然不能用了第一件事就是回来看config.toml的字段有没有过时。养成升级前备份配置的习惯。6.5 一个容易被忽略的细节base_url结尾不要带斜杠。写https://api.deepseek.com是对的写https://api.deepseek.com/有时候会导致拼接出双斜杠虽然多数情况下服务器能处理但少数情况下会 404。这种细节平时不起眼出问题的时候能查半天。我个人在实际操作中的体会是接第三方模型这件事难点从来不在配置本身而在于报错信息不够直观。401 和 400 这两个错误覆盖了八成的问题把 Key 和模型名这两个点确认清楚基本就能跑通。剩下的就是根据实际使用情况微调模型和上下文策略了。