1. 为什么要把 Codex 接到 DeepSeek 上先把话说在前头Codex 本身是个命令行里的编码助手默认走的是官方后端。但官方后端有两个现实问题一是额度有限、用着用着就限流二是网络链路偶尔抽风写代码写到一半卡住体验非常割裂。DeepSeek 的 API 兼容 OpenAI 的接口格式价格又便宜上下文窗口还大把它接进 Codex 当后端等于给 Codex 换了个更耐用、更省钱的发动机。这个教程适合三类人一是已经在用 Codex CLI、想换成 DeepSeek 后端的老用户二是刚装好 Codex、还没跑通第一条命令的新手三是被config.toml报错、401 报错、模型不识别这类问题卡住、到处搜解决方案的人。我会把配置文件怎么写、模型怎么映射、常见报错怎么排查全部拆开讲清楚你照着抄基本就能跑起来。需要提前说明的是Codex 的配置体系在不同版本之间有过调整网上很多老教程里的字段已经废弃了。我下面给的方案是基于当前主流版本的常见实践如果你用的是特别老的版本个别字段名可能对不上以你本地codex --version的输出为准。2. 动手前的环境准备与依赖确认2.1 确认 Codex 装好了、版本对得上第一步永远是确认工具本身没问题。打开终端敲codex --version能打印出版本号说明 CLI 已经装好。如果提示command not found那得先装。安装方式取决于你的系统常见的是通过包管理器或者官方提供的安装脚本。装完之后再跑一次版本命令确认。这里有个坑要提醒Codex 的配置目录默认在用户主目录下的.codex文件夹里。Windows 上是C:\Users\你的用户名\.codex\macOS 和 Linux 上是~/.codex/。热词里出现的c:\users\丁子洋.codex\config.toml就是典型的 Windows 路径。注意那个路径里用户名和.codex之间少了个反斜杠这其实是很多人复制路径时踩的坑正确路径应该是C:\Users\丁子洋\.codex\config.toml。路径写错配置文件根本不会被加载你会以为配置没生效其实是文件放错地方了。2.2 拿到 DeepSeek 的 API Key去 DeepSeek 的开放平台注册账号在控制台里创建一个 API Key。这个 Key 一般以sk-开头创建后只显示一次务必当场复制保存。热词里那个sk-svcac****就是典型的 Key 片段。关于 Key 有几个实操要点不要提交到 Git。Key 泄露等于别人拿你的钱跑推理见过太多人把 Key 硬编码进代码然后推到公开仓库第二天账单爆炸。建议用环境变量管理。虽然 Codex 的配置文件里可以直接写 Key但更稳妥的做法是写进环境变量配置文件里引用变量名。区分不同环境的 Key。如果你同时有测试和生产用途建两个 Key方便出问题时单独吊销。2.3 确认 DeepSeek 的接口地址和模型名DeepSeek 的 API 基础地址通常是https://api.deepseek.com兼容 OpenAI 的/v1/chat/completions格式。模型名常见的有deepseek-chat和deepseek-reasoner两个前者是通用对话模型后者是带推理链的模型。你在配置里填的模型名必须和官方文档里列出的完全一致写错了就会报模型不存在。提示模型名是大小写敏感的DeepSeek-Chat和deepseek-chat在有些网关看来是两个东西别想当然。3. config.toml 与 models.json 到底怎么配3.1 先搞清楚这两个文件的分工很多人一上来就懵到底改config.toml还是models.json我用一句话说清楚config.toml管的是全局行为比如默认用哪个模型、走哪个 provider、认证信息放哪、有哪些全局开关。models.json管的是模型清单也就是告诉 Codex 有哪些模型可选、每个模型对应哪个后端、上下文窗口多大、支持哪些能力。打个比方config.toml是公司组织架构图models.json是员工花名册。组织架构决定谁向谁汇报花名册决定每个人叫什么、干什么活。两个文件配合起来Codex 才知道我要调用 deepseek-chat 这个模型它归 deepseek 这个 provider 管认证用这个 Key。3.2 config.toml 的完整写法下面是一份可以直接参考的config.toml模板。注意字段名以你本地版本为准我这里给的是常见结构# 默认使用的模型 model deepseek-chat # 默认的 provider model_provider deepseek # 关闭不必要的遥测减少干扰 disable_response_storage true [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat逐行解释一下为什么这么写model指定默认模型这里填deepseek-chat。如果你更看重推理能力可以换成deepseek-reasoner。model_provider指向下面定义的 provider 名字必须和[model_providers.deepseek]里的deepseek一致不一致就找不到。base_url是接口根地址注意不要带/v1也不要带/chat/completionsCodex 会自己拼路径。这是新手最容易写错的地方多写一段路径就会 404。env_key指定从哪个环境变量读 Key。这样配置文件里不出现明文 Key安全得多。wire_api指定通信协议DeepSeek 兼容 OpenAI 的 chat 格式所以填chat。设置环境变量# macOS / Linux export DEEPSEEK_API_KEYsk-你的key # Windows PowerShell $env:DEEPSEEK_API_KEYsk-你的key想永久生效macOS/Linux 写进~/.bashrc或~/.zshrcWindows 用系统环境变量设置界面添加。3.3 models.json 的模型清单写法models.json是一个 JSON 数组每个元素描述一个模型。参考结构{ models: [ { id: deepseek-chat, name: DeepSeek Chat, provider: deepseek, context_window: 65536, max_output_tokens: 8192, supports_tools: true }, { id: deepseek-reasoner, name: DeepSeek Reasoner, provider: deepseek, context_window: 65536, max_output_tokens: 8192, supports_tools: false } ] }关键字段说明字段作用注意事项id模型唯一标识必须和 API 实际模型名一致name显示名称随便起方便自己认provider归属的 provider必须和 config.toml 里定义的一致context_window上下文窗口大小填错会导致长文本被截断或报错max_output_tokens单次最大输出别超过模型实际上限supports_tools是否支持工具调用reasoner 类模型常不支持填错会报错注意context_window这个值填小了浪费模型能力填大了会触发maximum context length报错。热词里那个this models maximum context length is 1048576 tokens就是上下文超限的典型报错说明你请求的内容超过了模型窗口。填之前一定查官方文档确认。3.4 两个文件放哪、怎么被加载config.toml和models.json都放在.codex目录下。Codex 启动时会自动读取。如果你改了配置但没生效先确认文件位置对不对再确认文件名有没有拼错——config.toml不是config.yaml也不是config.json。热词里有个codex is ignoring 1 unrecognized configuration setting的警告意思是 Codex 读到了配置但有个字段它不认识直接忽略了。这通常是因为你抄了老版本的字段名或者字段拼写有误。比如mcp_servers.node_repl.type is ignored就是典型的废弃字段警告。遇到这种警告不用慌先确认这个字段是不是你需要的不需要就删掉需要就查当前版本文档找对应字段。4. 完整实操流程与验证步骤4.1 从零到跑通的第一条命令假设你已经装好 Codex、拿到 Key、写好两个配置文件接下来按顺序验证确认环境变量生效。在终端里echo $DEEPSEEK_API_KEYWindows 用echo %DEEPSEEK_API_KEY%能打印出 Key 就对了。打印不出来说明环境变量没设好或者当前终端没重新加载。确认配置文件语法正确。TOML 对格式敏感多一个引号、少一个括号都会解析失败。可以用在线 TOML 校验工具过一遍或者直接启动 Codex 看有没有解析报错。启动 Codex。在终端里直接敲codex进入交互界面。发一条测试消息。比如输入用 Python 写一个快速排序看它能不能正常返回。如果返回了代码说明链路通了。确认走的是 DeepSeek。可以在提问时观察响应速度、返回风格或者临时把 Key 改错看是否报 401以此确认请求确实打到了 DeepSeek。4.2 参数选择背后的计算逻辑为什么context_window要填具体数值而不是随便填因为 Codex 在发送请求前会做一次 token 预算。它会估算当前对话历史加新输入的总 token 数如果超过context_window就会触发截断或报错。举个例子DeepSeek 某模型窗口是 64K token。你一段代码文件可能就占几千 token加上对话历史很容易逼近上限。如果你把context_window填成 128K但模型实际只支持 64KCodex 就不会主动截断结果请求发出去被服务端拒绝报maximum context length错误。所以这个值必须填模型真实支持的值宁可填小一点让 Codex 提前帮你截断也不要填大导致请求失败。max_output_tokens同理。填太大模型可能生成到一半被截断填太小回答不完整。一般填模型上限的 1/4 到 1/2 比较稳妥。4.3 实操现场一次完整的接入记录我拿自己的环境走一遍记录关键节点# 1. 检查版本 $ codex --version codex 0.x.x # 2. 确认配置目录 $ ls ~/.codex/ config.toml models.json # 3. 设置环境变量 $ export DEEPSEEK_API_KEYsk-xxxxxxxx # 4. 启动 $ codex 你好帮我写个冒泡排序 正常返回代码说明接入成功如果第 4 步报错就进入下一节的排查流程。5. 常见报错逐条排查5.1 401 UnauthorizedKey 的问题占九成热词里unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****是最常见的报错。401 就是认证失败原因无非几个Key 复制错了。前后有空格、少复制了几位、把sk-前缀漏了。环境变量没生效。你在 A 终端设的变量在 B 终端跑 Codex读不到。Key 被吊销或过期。去控制台确认 Key 状态。provider 配置里的env_key名字和实际环境变量名不一致。比如配置写DEEPSEEK_API_KEY你设的是DEEPSEEK_KEY那就读不到。排查顺序先echo环境变量确认值对不对再确认配置里的变量名最后去控制台确认 Key 有效。5.2 模型不识别models.json 和 config.toml 对不上报错类似model not found或unknown model。原因通常是config.toml里的model值在models.json里找不到对应id。models.json里的provider和config.toml里定义的 provider 名字不一致。模型名拼写错误比如把deepseek-chat写成deepseek_chat。解决方法是把两个文件里的名字逐个对照确保完全一致。5.3 配置被忽略废弃字段警告codex is ignoring 1 unrecognized configuration setting这类警告说明某个字段当前版本不认。处理原则如果这个字段不是必需的直接删掉。如果是必需的去查当前版本文档找替代字段。不要因为警告就以为整个配置失效了通常只是那一个字段被跳过其他配置照常生效。5.4 上下文超限token 预算没算对this models maximum context length is 1048576 tokens这种报错说明你请求的内容超过了模型窗口。注意 1048576 是 1M token这个数字很大出现这个报错通常意味着你把context_window填得比模型实际支持的大Codex 没截断。或者你一次性塞了超大文件进去。解决办法是把context_window改成模型真实值或者拆分输入内容。5.5 常见问题速查表报错关键词可能原因解决方向401 unauthorizedKey 错误/未生效检查环境变量和 Key 有效性model not found模型名不匹配对照 config 和 models.jsonunrecognized setting字段废弃/拼写错删除或替换字段maximum context length上下文超限调小 context_windowconnection refusedbase_url 错误检查接口地址400 organization disabled账号状态异常检查账号控制台6. 几个我踩过的坑和实操心得第一个坑是路径里的隐藏字符。从网页复制路径时有时会带上不可见的空格或特殊字符导致配置文件加载失败。我的习惯是手动敲路径或者复制后用cat -A检查有没有异常字符。第二个坑是环境变量的作用域。在 macOS 上如果你在.zshrc里设了变量但用的是 bash那读不到。确认你当前 shell 和配置文件对应。Windows 上更麻烦系统环境变量改完要重启终端才生效。第三个坑是模型能力差异。deepseek-chat支持工具调用deepseek-reasoner不一定支持。如果你在models.json里给 reasoner 标了supports_tools: true但实际不支持Codex 发工具调用请求时就会报错。这个字段要如实填。第四个坑是别频繁改配置。每次改完config.toml都要重启 Codex 才生效。有人改一下试一下改一下试一下最后自己都忘了改到哪一版。建议改之前先备份改完一次性重启验证。第五个坑是Key 的额度监控。DeepSeek 按 token 计费虽然便宜但如果你把 Codex 挂在那里跑大批量任务额度消耗会很快。建议在控制台设置额度告警别等账单出来才发现。最后分享一个实用技巧如果你同时想保留官方后端和 DeepSeek 后端可以在config.toml里定义多个 provider通过切换model_provider来快速切换。这样不用每次改配置改一行就能换后端调试起来方便很多。