1. 为什么要在 Codex 里接 DeepSeek而不是继续用默认模型Codex CLI 是 OpenAI 推出的命令行编程助手默认走的是官方模型通道。但实际用下来很多人会遇到两个绕不开的问题一是官方额度消耗快、成本不低二是某些场景下响应速度受网络和排队影响写代码的节奏会被打断。DeepSeek 的 API 在代码补全、长上下文理解上表现相当能打价格又便宜一大截所以把 Codex 的请求转发到 DeepSeek 上成了不少开发者的选择。这个教程要解决的问题很具体让 Codex CLI 通过配置把请求指向 DeepSeek 的 API 端点同时处理好模型名映射、认证方式、配置文件格式这几个最容易翻车的环节。适合已经装好 Codex、手里有 DeepSeek API Key、想省点成本或者想用 DeepSeek 模型写代码的人。哪怕你之前没碰过 config.toml跟着走也能配通。需要先说明一点Codex 的配置体系在不同版本之间有过调整网上流传的很多写法已经失效。我下面讲的是基于当前主流版本实测可用的方案核心思路是改~/.codex/config.toml把 provider 指向 DeepSeek 的兼容端点。整个过程不复杂但细节坑不少尤其是模型名和认证头这两块配错了就是 401 或者 400。2. 动手前的环境确认与 API Key 准备2.1 确认 Codex CLI 装好且能跑起来第一步不是急着改配置而是先确认 Codex 本身是通的。打开终端执行codex --version能打印出版本号说明安装没问题。如果提示 command not found那得先装。安装方式取决于你的系统常见的是通过 npm 全局安装npm install -g openai/codex装完之后再跑一次codex --version验证。这里有个细节如果你之前装过旧版本建议先卸载再装避免新旧配置文件格式冲突。我遇到过有人升级后旧配置残留导致 Codex 启动时报 “ignoring 1 unrecognized configuration setting”就是配置文件里有当前版本不认识的字段。2.2 拿到 DeepSeek 的 API Key 和端点地址DeepSeek 的 API Key 在它的开放平台控制台里创建格式通常是sk-开头的一长串字符。创建的时候注意两点一是 Key 只在创建时完整显示一次复制好存到安全的地方二是确认账户里有余额或者免费额度否则请求会返回余额不足的错误。端点地址这块要留意DeepSeek 提供的是 OpenAI 兼容接口基础地址一般是https://api.deepseek.com对话补全的路径是/chat/completions。有些教程里写的是带/v1的版本两种在多数情况下都能用但配置时最好以官方文档当前给出的为准。我实测下来基础地址填https://api.deepseek.com就够了Codex 会自己拼接路径。提示API Key 千万不要直接写进会提交到 Git 的配置文件里。下面会讲怎么用环境变量隔离这是基本的安全习惯。2.3 搞清楚 Codex 的配置文件到底在哪Codex 的配置文件默认在用户主目录下的.codex文件夹里文件名是config.toml。不同系统路径不一样系统配置文件路径WindowsC:\Users\你的用户名\.codex\config.tomlmacOS/Users/你的用户名/.codex/config.tomlLinux/home/你的用户名/.codex/config.toml如果这个文件不存在手动创建一个就行。注意 Windows 下路径里的用户名如果是中文一般不影响但极少数情况下某些工具对中文路径处理有问题遇到诡异报错时可以先把配置挪到纯英文路径下测试。热词里出现的 “chatgpt 无法加载 config.toml” 这类问题十有八九是文件路径不对或者 TOML 语法写错了后面会专门讲排查。3. config.toml 的核心字段逐个拆解3.1 model 与 model_provider 的对应关系配置文件里最关键的几个字段是model、model_provider以及model_providers下面的具体定义。很多人配不通就是因为没搞清这几个字段的联动关系。model指定你要调用的模型名比如deepseek-chat或deepseek-coder。model_provider指定用哪个 provider这个值必须和model_providers里定义的某个键名一致。举个例子你在model_providers下定义了一个叫deepseek的 provider那model_provider就得填deepseek。名字对不上Codex 就找不到对应的端点直接报错。一个最小可用的配置长这样model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY这里env_key填的是环境变量的名字不是 Key 本身。Codex 运行时会去读这个环境变量拿真正的 Key。这样做的好处是配置文件可以随便分享Key 不会泄露。3.2 base_url 到底该不该带 /v1这是被问得最多的一个问题。DeepSeek 的兼容接口base_url填https://api.deepseek.com和https://api.deepseek.com/v1在多数版本下都能工作因为 Codex 内部会处理路径拼接。但如果你遇到 404 或者路径重复的问题可以两个都试一下。我的建议是先用不带/v1的跑不通再换带/v1的。判断依据很简单看报错信息里请求的完整 URL 是什么。如果 URL 里出现了/v1/v1/chat/completions这种重复那就是 base_url 多带了/v1。3.3 认证方式env_key 与自定义 header标准做法是用env_key指向环境变量。但有些场景下你可能想直接指定认证头或者 DeepSeek 的认证格式和默认的不一样。Codex 支持通过http_headers自定义请求头[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY绝大多数情况下env_key就够了Codex 会自动把 Key 放进Authorization: Bearer key头里。DeepSeek 接受的正是这种格式。如果你手动配了http_headers又配了env_key可能会冲突导致认证头重复或者格式错误反而触发 401。注意热词里那个 “unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****” 是典型的 Key 无效或没读到。先检查环境变量有没有 export 成功再检查 Key 有没有复制完整前后有没有多余空格。3.4 那些容易被忽略的可选字段除了核心字段还有几个可选配置值得了解。wire_api指定通信协议DeepSeek 兼容的是chat类型。query_params可以附加查询参数一般用不上。request_max_retries控制重试次数网络不稳的时候调大一点有用。还有一个坑不同版本的 Codex 对字段名的要求不一样。有的版本用base_url有的老版本用baseURL或者api_base。如果你照着某篇教程配了却报 “unrecognized configuration setting”大概率就是字段名对不上当前版本。解决办法是看 Codex 启动时的警告信息它会告诉你哪个字段被忽略了。4. 完整配置流程与验证步骤4.1 设置环境变量先把 API Key 写进环境变量。Linux 和 macOS 下export DEEPSEEK_API_KEYsk-你的真实keyWindows PowerShell 下$env:DEEPSEEK_API_KEYsk-你的真实key这只是当前会话生效。要永久生效Linux/macOS 写进~/.bashrc或~/.zshrcWindows 用系统环境变量设置界面添加。设置完记得新开一个终端或者 source 一下配置文件否则当前终端读不到。验证环境变量有没有生效echo $DEEPSEEK_API_KEYWindows 下用echo $env:DEEPSEEK_API_KEY。能打印出你的 Key 就对了。这一步没做对后面全是 401。4.2 写入 config.toml把前面那段配置写进config.toml。如果文件里已经有其他内容注意 TOML 的语法[model_providers.deepseek]这种表头下面的字段都属于这个表直到下一个表头出现。别把字段写到错误的表下面去了。一个更完整的配置示例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保存文件。这里有个实操心得改完配置后先用一个最简单的命令测试别一上来就跑复杂任务。比如让 Codex 解释一段代码看它能不能正常返回。4.3 跑通第一个请求在终端里进入一个项目目录执行codex 用一句话解释什么是递归如果配置正确你会看到 DeepSeek 返回的回答。第一次跑可能会慢一点因为要建立连接。如果卡住不动多半是网络或者端点地址的问题。成功返回后可以再测一个稍微复杂点的比如让它读一个文件并解释codex 读一下当前目录的 README.md总结它的内容这一步能验证 Codex 的工具调用和 DeepSeek 的上下文理解是否配合正常。4.4 怎么确认请求真的走了 DeepSeek有个简单的验证方法看返回内容的风格和速度。DeepSeek 和默认模型在措辞上有差异。更可靠的办法是看 Codex 的日志输出启动时加 verbose 参数能看到实际请求的端点。另一个办法是临时把 API Key 改成一个错误的如果报 401说明请求确实发到了 DeepSeek 的端点因为如果是默认端点报错信息会不一样。验证完记得改回来。5. 高频报错的原因定位与修复5.1 401 认证失败Key 没读到或格式不对401 是最常见的错误。热词里 “incorrect api key provided” 就是典型。排查顺序确认环境变量名和配置里的env_key完全一致大小写敏感。确认环境变量在当前终端会话里能 echo 出来。确认 Key 没有多余空格复制的时候容易带上首尾空白。确认 Key 没有过期或被禁用。如果这四步都对了还报 401那可能是 Codex 版本问题某些版本读取环境变量的逻辑有 bug可以尝试直接在配置里用api_key字段不推荐但能验证问题。5.2 400 上下文超限模型选择与 token 控制热词里 “this models maximum context length is 1048576 tokens” 这个报错说明你选的模型上下文窗口和实际请求不匹配。DeepSeek 不同模型的上下文长度不一样deepseek-chat和deepseek-coder的限制可能有差异。如果你喂了超长内容就会触发这个错误。解决办法有两个一是换上下文更长的模型二是控制输入长度比如让 Codex 只读关键文件而不是整个项目。Codex 本身有文件读取的策略可以在配置里限制它一次读多少。5.3 配置字段被忽略版本差异导致的字段名不匹配“codex is ignoring 1 unrecognized configuration setting” 这个警告意思是配置文件里有个字段当前版本不认识。常见原因是字段名拼写错误或者用了已废弃的字段名。比如老版本用mcp_servers.node_repl.type新版本可能改成了别的写法。处理办法先看警告信息里具体是哪个字段然后查当前版本文档确认正确写法。如果这个字段不是必需的直接删掉也能消除警告。别小看这个警告有时候它会导致整个配置块被跳过表现为配置明明写了却不生效。5.4 端点路径错误404 与重复路径如果报 404先看请求的完整 URL。常见的是 base_url 和 Codex 内部拼接逻辑冲突导致路径重复或缺失。比如 base_url 填了https://api.deepseek.com/v1Codex 又拼了个/v1变成/v1/v1/...。修复方法就是调整 base_url去掉多余的路径段。用 curl 手动测一下端点是否可达curl https://api.deepseek.com/chat/completions \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -H Content-Type: application/json \ -d {model:deepseek-chat,messages:[{role:user,content:hi}]}这个命令能通说明 Key 和端点都没问题问题就在 Codex 配置上。6. 让配置更稳的几个进阶技巧6.1 用 profile 管理多套配置如果你既想用 DeepSeek又想保留默认模型可以用 Codex 的 profile 功能。在 config.toml 里定义多个 profile启动时用--profile参数切换[profiles.deepseek] model deepseek-chat model_provider deepseek [profiles.default] model gpt-4这样不用每次改配置文件切换成本低很多。6.2 控制请求重试与超时网络不稳的时候默认的重试策略可能不够。可以在 provider 配置里加[model_providers.deepseek] request_max_retries 3重试次数别设太大否则一个失败请求会卡很久。配合合理的超时设置体验会好很多。6.3 把配置纳入版本管理时的脱敏处理如果你想把 config.toml 分享给团队或者提交到仓库务必确保里面没有明文 Key。用env_key的方式天然就是脱敏的。如果用了api_key字段提交前一定要删掉或者用占位符替换。我个人的习惯是在仓库里放一个config.toml.example里面用YOUR_API_KEY_HERE占位真正的 config.toml 加进.gitignore。这样新人 clone 下来照着 example 改就行不会误提交敏感信息。6.4 遇到诡异问题时的最小化排查法配置这东西出问题的时候别急着大改。先把配置精简到最小可用状态只保留 model、model_provider、base_url、env_key 四个字段跑通了再逐步加回其他字段。这样能快速定位是哪个字段导致的冲突。另外Codex 的版本更新比较频繁遇到问题时先确认自己用的是不是最新版。有时候你踩的坑新版本已经修了。反过来有时候最新版引入了新问题回退到上一个稳定版反而更省事。我的建议是固定用一个验证过能用的版本别盲目追新。7. 实际使用中的几点体会配通只是第一步真正用起来还有几个细节值得注意。DeepSeek 在代码生成上的风格和默认模型有差异有时候它给的代码更简洁但注释少一些需要你在 prompt 里明确要求。另外长对话场景下要注意上下文累积DeepSeek 的计费是按 token 算的聊太久成本也会上去适时开新会话是个好习惯。还有一点Codex 的工具调用能力比如读文件、执行命令和底层模型是解耦的换成 DeepSeek 后这些功能照常可用但模型对工具返回结果的理解可能有细微差别。如果发现它读文件后理解偏了可以在 prompt 里把要求说得更具体。最后分享一个小技巧把常用的配置和启动命令写成一个 shell 脚本或者 alias比如alias codex-dsDEEPSEEK_API_KEYxxx codex --profile deepseek这样每次用的时候不用手动设环境变量省事不少。当然 Key 还是别硬编码在脚本里用系统环境变量更稳妥。