尧图网页设计 
1. 为什么要在 Codex 里接入 DeepSeekCodex 这个 CLI 工具刚出来的时候默认只能对接 OpenAI 自家的模型。但实际用下来很多人会发现两个问题一是官方额度消耗快二是某些场景下 DeepSeek 的中文理解和代码生成反而更顺手。把 DeepSeek 接进 Codex本质上是把 Codex 当作一个前端壳后端换成 DeepSeek 的 API 来跑。这件事解决的核心痛点是你不需要放弃 Codex 已经习惯的交互方式终端里直接对话、自动读写文件、执行命令同时又能用上 DeepSeek 的模型能力。适合谁来参考已经装好 Codex、手里有 DeepSeek API Key、想让两者打通的人。如果你还没装 Codex后面我也会顺带说安装的事。需要提前说清楚一个概念Codex 和 DeepSeek 之间靠的是API 协议对接。Codex 默认走的是 OpenAI 的 Responses API 格式而 DeepSeek 提供的是兼容 OpenAI 的 Chat Completions 接口。这两者不完全一样所以配置的时候不能随便填个 base_url 就完事得注意接口路径和参数格式的差异。这也是很多人配完之后报 401 或者 400 的根源。我前后折腾了几轮踩过config.toml被忽略、API Key 格式不对、模型名写错导致 400 这些坑下面把完整流程和排查思路整理出来。2. 接入前的环境与账号准备2.1 Codex CLI 的安装与版本确认Codex 的安装方式取决于你的系统。Windows 下一般是通过 npm 全局安装macOS 和 Linux 类似。装完之后第一件事是确认版本因为不同版本的 Codex 对配置文件的支持程度不一样老版本可能根本不认config.toml里的某些字段。# 确认 node 环境 node -v npm -v # 全局安装 codex npm install -g openai/codex # 确认安装成功及版本 codex --version装完之后Codex 会在用户目录下生成一个配置文件夹。Windows 下路径通常是C:\Users\你的用户名\.codex\macOS 和 Linux 下是~/.codex/。这个目录里最关键的文件就是config.toml所有模型接入的配置都写在这里。注意如果你之前登录过 OpenAI 账号Codex 可能会缓存一份默认配置。接入 DeepSeek 之前建议先备份原来的config.toml改坏了还能还原。2.2 DeepSeek API Key 的获取与格式核对DeepSeek 的 API Key 需要到它的开放平台申请。申请流程不复杂注册账号、实名、创建 API Key 就行。拿到 Key 之后格式一般是sk-开头的一长串字符。这里有个高频坑很多人复制 Key 的时候带上了多余的空格或者换行导致请求时报401 unauthorized: incorrect api key provided。我建议拿到 Key 之后先做一次纯文本粘贴检查确认前后没有空白字符。另外要确认你的 DeepSeek 账号里有余额或者免费额度。API 调用是按 token 计费的余额为 0 的时候同样会返回 401 或 403容易被误判成 Key 的问题。2.3 网络与接口地址的确认DeepSeek 的 API 基础地址是https://api.deepseek.com。注意有些文档里写的是带/v1的版本比如https://api.deepseek.com/v1。这两个在多数情况下都能用但配置到 Codex 里的时候要和你填的接口路径匹配否则会出现 404 或者路径拼接错误。我个人的做法是base_url 只写到域名部分具体的路径交给 Codex 的 provider 配置去拼。这样不容易出错。3. config.toml 的核心配置拆解3.1 配置文件的结构与关键字段Codex 的config.toml用的是 TOML 格式本质上是键值对加表结构。接入 DeepSeek 的核心是定义一个 model provider然后指定默认模型走这个 provider。一个能跑通的最小配置大概长这样# 定义模型提供方 [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY # 指定默认使用的模型和提供方 model deepseek-chat model_provider deepseek这里几个字段的含义要搞清楚model_providers.deepseek是你自定义的 provider 名字叫什么都行但要和下面model_provider的值对上。base_url是 DeepSeek 的接口地址。env_key指定从哪个环境变量读取 API Key。这样做比把 Key 明文写在配置文件里安全得多。model是你要调用的具体模型名DeepSeek 常用的有deepseek-chat和deepseek-reasoner。model_provider告诉 Codex 默认走哪个 provider。3.2 环境变量的设置方式把 API Key 放在环境变量里是避免泄露的基本操作。设置方式分系统Windows PowerShell$env:DEEPSEEK_API_KEY sk-你的key # 永久生效需要写入用户环境变量 [System.Environment]::SetEnvironmentVariable(DEEPSEEK_API_KEY, sk-你的key, User)macOS / Linuxexport DEEPSEEK_API_KEYsk-你的key # 永久生效写入 shell 配置 echo export DEEPSEEK_API_KEYsk-你的key ~/.bashrc source ~/.bashrc设置完之后重启终端用echo $DEEPSEEK_API_KEYWindows 用echo $env:DEEPSEEK_API_KEY确认能读到值。提示如果你在 IDE 内置终端里跑 Codex环境变量可能不会自动继承。这种情况要么在 IDE 里单独配置要么直接在启动 Codex 的那个终端会话里临时 export 一次。3.3 关于 Responses API 与 Chat Completions 的差异这是整个接入过程中最容易被忽略、也最容易导致失败的一点。Codex 默认使用的是 OpenAI 的Responses API格式请求路径是/responses。而 DeepSeek 提供的是标准的Chat Completions接口路径是/chat/completions。如果你直接把 base_url 指向 DeepSeek 却让 Codex 走 Responses 协议就会看到类似local proxy failed while handling codex endpoint /responses的报错。因为 DeepSeek 那边根本没有/responses这个端点。解决办法有两个方向一是让 Codex 改用 Chat Completions 协议去请求二是在中间加一层转换。多数情况下Codex 的 provider 配置里可以通过指定wire_api之类的字段来切换协议。具体字段名随版本变化建议对照你当前版本的官方配置说明确认。[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat # 关键切换到 chat completions 协议这个wire_api字段就是决定走哪套协议的关键。填chat走 Chat Completions不填或者填responses就走 Responses。很多人配完报/responses相关的错就是这里没改。4. 完整实操流程与验证4.1 从零到跑通的完整步骤把前面的准备串起来完整流程是这样的安装 Codex CLI确认版本。申请 DeepSeek API Key核对格式和余额。设置DEEPSEEK_API_KEY环境变量重启终端确认可读。编辑~/.codex/config.toml写入 provider 和 model 配置。确认wire_api设置为chat。启动 Codex发一条测试消息验证。启动 Codex 直接在终端敲codex就行。进去之后随便问一句比如让它写个快排。如果配置正确你会看到它正常返回内容而不是报错。4.2 验证配置是否生效的几种方法光看它能不能回话还不够最好确认它确实走的是 DeepSeek。几个验证角度看返回内容的风格。DeepSeek 和 GPT 在中文表达上有细微差别但这个不够严谨。查 DeepSeek 开放平台的用量统计。调用成功之后后台会记录 token 消耗。这是最直接的证据。在 Codex 里用调试模式或者 verbose 参数启动看它实际请求的 URL 和模型名。我一般用第二种去 DeepSeek 后台看用量有记录就说明通了。4.3 模型名的选择与参数调整DeepSeek 目前主要提供两个模型deepseek-chat偏向通用对话和代码deepseek-reasoner偏向复杂推理。日常写代码用deepseek-chat就够了响应快、成本低。遇到需要深度推理的任务再切deepseek-reasoner。切换模型只需要改config.toml里的model字段或者启动时用命令行参数临时指定。如果你经常切换可以在配置里定义多个 provider用的时候选。参数方面DeepSeek 的上下文窗口很大但也不是无限的。有人的报错信息里提到maximum context length is 1048576 tokens说明超长上下文会触发 400。日常使用基本碰不到这个上限但如果让它读整个大仓库就要注意分批处理。5. 常见报错与排查速查5.1 401 与 400 报错的定位思路这两类错误占了接入问题的绝大多数。我把常见表现和原因整理成表报错信息可能原因排查方向401 incorrect api key providedKey 错误、带空格、环境变量没读到检查 Key 格式和环境变量401 unauthorized账号余额不足或 Key 被禁用登录 DeepSeek 后台确认400 maximum context length输入 token 超限减少上下文或分批400 organization disabled账号状态异常联系平台确认账号/responses 相关错误协议没切到 chat检查 wire_api 字段config.toml 被忽略字段名拼写错误或版本不支持核对字段名和版本401 的核心永远是 Key 的问题。先确认环境变量能读到再确认 Key 本身有效最后确认账号有余额。三步走下来基本能定位。400 里最常见的是上下文超限和协议不匹配。上下文超限看输入长度协议不匹配看wire_api。5.2 config.toml 被忽略的典型场景有个很隐蔽的坑Codex 提示ignoring 1 unrecognized configuration setting意思是它读到了某个字段但不认识直接忽略了。比如mcp_servers.node_repl.type is ignored这种。出现这个的原因通常是字段名拼错了或者你用的 Codex 版本不支持这个字段。解决办法是核对官方文档里当前版本支持的字段列表把不认识的字段删掉或者改名。还有一种情况是配置文件路径不对。Codex 只认它默认目录下的config.toml你放在别处它不会读。Windows 下确认是C:\Users\用户名\.codex\config.toml注意用户名里的中文一般不影响但路径里有空格可能出问题。5.3 代理与本地转发失败的排查报错里出现local proxy failed while handling codex endpoint这类信息说明 Codex 内部有个本地代理层在转发请求但转发失败了。常见原因是目标端点不存在比如 DeepSeek 没有/responses。本地端口被占用。代理配置和实际请求协议不匹配。排查顺序是先确认协议对不对wire_api再确认端口有没有冲突最后看日志里具体的失败原因。Codex 一般会把详细错误打在终端里仔细读那几行通常能找到线索。6. 实操心得与避坑建议6.1 我踩过的几个真实坑第一个坑是 Key 里的空格。我从网页复制 Key 的时候末尾带了一个看不见的换行粘贴到环境变量里结果一直报 401。后来用echo打印出来对比才发现。这个坑很蠢但很常见建议复制后先粘到纯文本编辑器里看一眼。第二个坑是协议没切。我一开始只配了 base_url 和 model没管wire_api结果 Codex 一直往/responses发请求DeepSeek 那边 404。加上wire_api chat之后立刻通了。第三个坑是配置文件位置。我在项目目录下建了个config.toml以为 Codex 会读结果它只认用户目录下的那个。改到正确路径才生效。6.2 让配置更稳的几个习惯配置文件改完先备份出问题能快速回滚。API Key 永远走环境变量不写进配置文件。每次升级 Codex 之后重新核对一遍配置字段版本更新可能改字段名。用 DeepSeek 后台的用量统计作为最终验证比看返回内容可靠。遇到报错先读完整错误信息Codex 的报错通常写得很具体关键词就在里面。6.3 关于成本和性能的取舍DeepSeek 的价格比 OpenAI 官方低不少这是很多人接入的主要动机。但要注意便宜不代表无脑用。长上下文、高频调用一样会累积成本。我的做法是日常任务用deepseek-chat只在确实需要深度推理时才切deepseek-reasoner这样成本和效果比较平衡。性能上DeepSeek 的响应速度在多数场景下够用但高峰期偶尔会有延迟。如果对延迟敏感可以在配置里设置合理的超时时间避免卡死。7. 后续可以扩展的方向配置跑通之后还能做几件事让它更好用。一是把常用的 provider 配置模板化换模型的时候直接改一个字段。二是结合 Codex 的 MCP 能力把外部工具接进来让 DeepSeek 能调用更多资源。三是写个简单的脚本一键切换不同模型和 provider省得每次手动改配置。我自己现在是把 DeepSeek 作为主力偶尔切回官方模型对比效果。这套配置稳定跑了挺长时间除了版本升级时偶尔要调字段日常使用没什么问题。如果你在配置过程中遇到表里没覆盖的报错建议先把完整错误信息贴出来多数问题看关键词就能定位。 Codex CLI 接入 DeepSeek API 完整配置指南与避坑实践
1. 为什么要在 Codex 里接入 DeepSeekCodex 这个 CLI 工具刚出来的时候默认只能对接 OpenAI 自家的模型。但实际用下来很多人会发现两个问题一是官方额度消耗快二是某些场景下 DeepSeek 的中文理解和代码生成反而更顺手。把 DeepSeek 接进 Codex本质上是把 Codex 当作一个前端壳后端换成 DeepSeek 的 API 来跑。这件事解决的核心痛点是你不需要放弃 Codex 已经习惯的交互方式终端里直接对话、自动读写文件、执行命令同时又能用上 DeepSeek 的模型能力。适合谁来参考已经装好 Codex、手里有 DeepSeek API Key、想让两者打通的人。如果你还没装 Codex后面我也会顺带说安装的事。需要提前说清楚一个概念Codex 和 DeepSeek 之间靠的是API 协议对接。Codex 默认走的是 OpenAI 的 Responses API 格式而 DeepSeek 提供的是兼容 OpenAI 的 Chat Completions 接口。这两者不完全一样所以配置的时候不能随便填个 base_url 就完事得注意接口路径和参数格式的差异。这也是很多人配完之后报 401 或者 400 的根源。我前后折腾了几轮踩过config.toml被忽略、API Key 格式不对、模型名写错导致 400 这些坑下面把完整流程和排查思路整理出来。2. 接入前的环境与账号准备2.1 Codex CLI 的安装与版本确认Codex 的安装方式取决于你的系统。Windows 下一般是通过 npm 全局安装macOS 和 Linux 类似。装完之后第一件事是确认版本因为不同版本的 Codex 对配置文件的支持程度不一样老版本可能根本不认config.toml里的某些字段。# 确认 node 环境 node -v npm -v # 全局安装 codex npm install -g openai/codex # 确认安装成功及版本 codex --version装完之后Codex 会在用户目录下生成一个配置文件夹。Windows 下路径通常是C:\Users\你的用户名\.codex\macOS 和 Linux 下是~/.codex/。这个目录里最关键的文件就是config.toml所有模型接入的配置都写在这里。注意如果你之前登录过 OpenAI 账号Codex 可能会缓存一份默认配置。接入 DeepSeek 之前建议先备份原来的config.toml改坏了还能还原。2.2 DeepSeek API Key 的获取与格式核对DeepSeek 的 API Key 需要到它的开放平台申请。申请流程不复杂注册账号、实名、创建 API Key 就行。拿到 Key 之后格式一般是sk-开头的一长串字符。这里有个高频坑很多人复制 Key 的时候带上了多余的空格或者换行导致请求时报401 unauthorized: incorrect api key provided。我建议拿到 Key 之后先做一次纯文本粘贴检查确认前后没有空白字符。另外要确认你的 DeepSeek 账号里有余额或者免费额度。API 调用是按 token 计费的余额为 0 的时候同样会返回 401 或 403容易被误判成 Key 的问题。2.3 网络与接口地址的确认DeepSeek 的 API 基础地址是https://api.deepseek.com。注意有些文档里写的是带/v1的版本比如https://api.deepseek.com/v1。这两个在多数情况下都能用但配置到 Codex 里的时候要和你填的接口路径匹配否则会出现 404 或者路径拼接错误。我个人的做法是base_url 只写到域名部分具体的路径交给 Codex 的 provider 配置去拼。这样不容易出错。3. config.toml 的核心配置拆解3.1 配置文件的结构与关键字段Codex 的config.toml用的是 TOML 格式本质上是键值对加表结构。接入 DeepSeek 的核心是定义一个 model provider然后指定默认模型走这个 provider。一个能跑通的最小配置大概长这样# 定义模型提供方 [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY # 指定默认使用的模型和提供方 model deepseek-chat model_provider deepseek这里几个字段的含义要搞清楚model_providers.deepseek是你自定义的 provider 名字叫什么都行但要和下面model_provider的值对上。base_url是 DeepSeek 的接口地址。env_key指定从哪个环境变量读取 API Key。这样做比把 Key 明文写在配置文件里安全得多。model是你要调用的具体模型名DeepSeek 常用的有deepseek-chat和deepseek-reasoner。model_provider告诉 Codex 默认走哪个 provider。3.2 环境变量的设置方式把 API Key 放在环境变量里是避免泄露的基本操作。设置方式分系统Windows PowerShell$env:DEEPSEEK_API_KEY sk-你的key # 永久生效需要写入用户环境变量 [System.Environment]::SetEnvironmentVariable(DEEPSEEK_API_KEY, sk-你的key, User)macOS / Linuxexport DEEPSEEK_API_KEYsk-你的key # 永久生效写入 shell 配置 echo export DEEPSEEK_API_KEYsk-你的key ~/.bashrc source ~/.bashrc设置完之后重启终端用echo $DEEPSEEK_API_KEYWindows 用echo $env:DEEPSEEK_API_KEY确认能读到值。提示如果你在 IDE 内置终端里跑 Codex环境变量可能不会自动继承。这种情况要么在 IDE 里单独配置要么直接在启动 Codex 的那个终端会话里临时 export 一次。3.3 关于 Responses API 与 Chat Completions 的差异这是整个接入过程中最容易被忽略、也最容易导致失败的一点。Codex 默认使用的是 OpenAI 的Responses API格式请求路径是/responses。而 DeepSeek 提供的是标准的Chat Completions接口路径是/chat/completions。如果你直接把 base_url 指向 DeepSeek 却让 Codex 走 Responses 协议就会看到类似local proxy failed while handling codex endpoint /responses的报错。因为 DeepSeek 那边根本没有/responses这个端点。解决办法有两个方向一是让 Codex 改用 Chat Completions 协议去请求二是在中间加一层转换。多数情况下Codex 的 provider 配置里可以通过指定wire_api之类的字段来切换协议。具体字段名随版本变化建议对照你当前版本的官方配置说明确认。[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat # 关键切换到 chat completions 协议这个wire_api字段就是决定走哪套协议的关键。填chat走 Chat Completions不填或者填responses就走 Responses。很多人配完报/responses相关的错就是这里没改。4. 完整实操流程与验证4.1 从零到跑通的完整步骤把前面的准备串起来完整流程是这样的安装 Codex CLI确认版本。申请 DeepSeek API Key核对格式和余额。设置DEEPSEEK_API_KEY环境变量重启终端确认可读。编辑~/.codex/config.toml写入 provider 和 model 配置。确认wire_api设置为chat。启动 Codex发一条测试消息验证。启动 Codex 直接在终端敲codex就行。进去之后随便问一句比如让它写个快排。如果配置正确你会看到它正常返回内容而不是报错。4.2 验证配置是否生效的几种方法光看它能不能回话还不够最好确认它确实走的是 DeepSeek。几个验证角度看返回内容的风格。DeepSeek 和 GPT 在中文表达上有细微差别但这个不够严谨。查 DeepSeek 开放平台的用量统计。调用成功之后后台会记录 token 消耗。这是最直接的证据。在 Codex 里用调试模式或者 verbose 参数启动看它实际请求的 URL 和模型名。我一般用第二种去 DeepSeek 后台看用量有记录就说明通了。4.3 模型名的选择与参数调整DeepSeek 目前主要提供两个模型deepseek-chat偏向通用对话和代码deepseek-reasoner偏向复杂推理。日常写代码用deepseek-chat就够了响应快、成本低。遇到需要深度推理的任务再切deepseek-reasoner。切换模型只需要改config.toml里的model字段或者启动时用命令行参数临时指定。如果你经常切换可以在配置里定义多个 provider用的时候选。参数方面DeepSeek 的上下文窗口很大但也不是无限的。有人的报错信息里提到maximum context length is 1048576 tokens说明超长上下文会触发 400。日常使用基本碰不到这个上限但如果让它读整个大仓库就要注意分批处理。5. 常见报错与排查速查5.1 401 与 400 报错的定位思路这两类错误占了接入问题的绝大多数。我把常见表现和原因整理成表报错信息可能原因排查方向401 incorrect api key providedKey 错误、带空格、环境变量没读到检查 Key 格式和环境变量401 unauthorized账号余额不足或 Key 被禁用登录 DeepSeek 后台确认400 maximum context length输入 token 超限减少上下文或分批400 organization disabled账号状态异常联系平台确认账号/responses 相关错误协议没切到 chat检查 wire_api 字段config.toml 被忽略字段名拼写错误或版本不支持核对字段名和版本401 的核心永远是 Key 的问题。先确认环境变量能读到再确认 Key 本身有效最后确认账号有余额。三步走下来基本能定位。400 里最常见的是上下文超限和协议不匹配。上下文超限看输入长度协议不匹配看wire_api。5.2 config.toml 被忽略的典型场景有个很隐蔽的坑Codex 提示ignoring 1 unrecognized configuration setting意思是它读到了某个字段但不认识直接忽略了。比如mcp_servers.node_repl.type is ignored这种。出现这个的原因通常是字段名拼错了或者你用的 Codex 版本不支持这个字段。解决办法是核对官方文档里当前版本支持的字段列表把不认识的字段删掉或者改名。还有一种情况是配置文件路径不对。Codex 只认它默认目录下的config.toml你放在别处它不会读。Windows 下确认是C:\Users\用户名\.codex\config.toml注意用户名里的中文一般不影响但路径里有空格可能出问题。5.3 代理与本地转发失败的排查报错里出现local proxy failed while handling codex endpoint这类信息说明 Codex 内部有个本地代理层在转发请求但转发失败了。常见原因是目标端点不存在比如 DeepSeek 没有/responses。本地端口被占用。代理配置和实际请求协议不匹配。排查顺序是先确认协议对不对wire_api再确认端口有没有冲突最后看日志里具体的失败原因。Codex 一般会把详细错误打在终端里仔细读那几行通常能找到线索。6. 实操心得与避坑建议6.1 我踩过的几个真实坑第一个坑是 Key 里的空格。我从网页复制 Key 的时候末尾带了一个看不见的换行粘贴到环境变量里结果一直报 401。后来用echo打印出来对比才发现。这个坑很蠢但很常见建议复制后先粘到纯文本编辑器里看一眼。第二个坑是协议没切。我一开始只配了 base_url 和 model没管wire_api结果 Codex 一直往/responses发请求DeepSeek 那边 404。加上wire_api chat之后立刻通了。第三个坑是配置文件位置。我在项目目录下建了个config.toml以为 Codex 会读结果它只认用户目录下的那个。改到正确路径才生效。6.2 让配置更稳的几个习惯配置文件改完先备份出问题能快速回滚。API Key 永远走环境变量不写进配置文件。每次升级 Codex 之后重新核对一遍配置字段版本更新可能改字段名。用 DeepSeek 后台的用量统计作为最终验证比看返回内容可靠。遇到报错先读完整错误信息Codex 的报错通常写得很具体关键词就在里面。6.3 关于成本和性能的取舍DeepSeek 的价格比 OpenAI 官方低不少这是很多人接入的主要动机。但要注意便宜不代表无脑用。长上下文、高频调用一样会累积成本。我的做法是日常任务用deepseek-chat只在确实需要深度推理时才切deepseek-reasoner这样成本和效果比较平衡。性能上DeepSeek 的响应速度在多数场景下够用但高峰期偶尔会有延迟。如果对延迟敏感可以在配置里设置合理的超时时间避免卡死。7. 后续可以扩展的方向配置跑通之后还能做几件事让它更好用。一是把常用的 provider 配置模板化换模型的时候直接改一个字段。二是结合 Codex 的 MCP 能力把外部工具接进来让 DeepSeek 能调用更多资源。三是写个简单的脚本一键切换不同模型和 provider省得每次手动改配置。我自己现在是把 DeepSeek 作为主力偶尔切回官方模型对比效果。这套配置稳定跑了挺长时间除了版本升级时偶尔要调字段日常使用没什么问题。如果你在配置过程中遇到表里没覆盖的报错建议先把完整错误信息贴出来多数问题看关键词就能定位。