企业官网建设流程全解析

最近总有人问我同一个问题：Codex 怎么接上 DeepSeek？其实这事在技术社区已经传开了，很多人想把 OpenAI 的 Codex CLI 这个终端编程助手，跟 DeepSeek 的高性价比大模型结合起来。Codex 原本只认 OpenAI 自家服务和协议，DeepSeek 的 API 恰好兼容 OpenAI 格式，所以只要我们改一下配置，就能让 Codex 用 DeepSeek 干活。

这篇文章我会从头到尾拆一遍接入过程，包括原理、工具安装、API Key 准备、配置文件写法、模型选型，以及我踩过的几个典型报错。不管你是刚听说 Codex 的小白，还是已经在用别的模型想切换的老手，照着走都能接上。全程不碰任何复杂操作，只要会打开终端、会粘贴配置就行。

1. 为什么要把 Codex 接到 DeepSeek：先搞清楚这俩是什么

1.1 Codex CLI 到底是个什么工具

Codex 是 OpenAI 出的一个开源命令行编程智能体，和传统的代码补全工具完全是两个思路。传统 Copilot 是你在编辑器里敲代码，它给你补下一个单词或下一行；Codex 不是这么干的，你给它一个任务，比如“把项目里所有过时的 API 调用替换掉”，它会自己读仓库、拆解任务、修改文件、运行命令，甚至把测试跑完再汇报结果。

我在实际用下来，Codex CLI 最舒服的使用方式是codex exec这种非交互模式，一条命令抛给它，它在后台自己折腾。也可以直接进交互模式，像聊天一样让它干活，它能看到当前目录的文件结构，给出的修改建议能直接落盘。它本质上是把大模型的代码能力和终端工具链打通了，这种设计对自动化脚本和日常开发效率提升非常明显。

1.2 DeepSeek 的价值点在哪

DeepSeek 这两年的热度不用我多说了，它在代码、推理、中文理解这些任务上的表现，已经跻身第一梯队。最关键的是 API 价格比海外主流模型低不少，这意味着你用 Codex 跑一些大量消耗 token 的任务时，成本压力会小很多。

DeepSeek 的开放平台提供两条模型线：deepseek-chat和deepseek-reasoner。前者对应通用对话模型，速度快、成本低，适合大多数日常编程任务；后者是推理增强模型，会先“想”一段再回答，适合复杂逻辑拆解。后面我会细说怎么选，这里先有个概念就行。

1.3 接入原理：OpenAI 兼容协议

Codex 能接 DeepSeek，靠的是 OpenAI 定下的一套 API 协议。Codex 在配置层面允许你自定义model_provider，也就是自己指定请求发到哪个地址、用哪个 Key、用哪个模型名。DeepSeek 的 API 在设计上刻意兼容了 OpenAI 的请求格式，所以只要把 Codex 的请求地址指向 DeepSeek，把 Key 换成 DeepSeek 的，理论上就能跑通。

用生活化的话说，Codex 像一台手机，OpenAI 的 API 像一张原装 SIM 卡；DeepSeek 的接口也遵循同一个插槽标准，那你只需要把卡拔下来换一张，手机本身不用动。不过这里有个隐藏问题：Codex 新版本走的是 OpenAI 的 Responses 协议，而 DeepSeek 官方主要提供 Chat Completions 协议。这两者大部分情况下能兼容，但偶尔会有端点对不上的情况，我在后面“常见报错”里会专门讲这个。

2. 动手前准备：装好 Codex、拿到 DeepSeek Key

2.1 安装 Codex CLI 的三种常见方式

安装 Codex 之前，先确认你的电脑里有 Node.js 环境。官方目前支持 macOS 和 Linux 的终端环境，Windows 可以使用桌面版，也可以通过 WSL 跑 CLI。最简单的安装方式是用 npm 全局安装：

npm install -g @openai/codex

macOS 用户如果装了 Homebrew，也可以走 Homebrew 这条路：

brew install codex

装完之后先确认一下版本号，能正常输出就说明装好了：

codex --version

如果看到类似codex-x.y.z的输出，说明 OK。Windows 桌面版可以从官网下载安装包，安装后是带图形界面的交互终端，操作逻辑和 CLI 一致。装完以后，Codex 会在你的用户目录下生成一个.codex配置目录，后面的活都在这边干。

2.2 注册 DeepSeek 开放平台并拿到 API Key

接下来是准备 DeepSeek 的 API Key。打开 DeepSeek 开放平台，注册登录后，在控制台的“API Keys”页面创建一个新的 Key。创建时会让你填一个名字，随便写什么都行，创建成功后会显示一次完整的 Key，样式是sk-开头的一长串字符。这个 Key 只显示这一次，一定先复制保存好，关掉页面就再也看不到了。

DeepSeek 的计费是预充值模式，必须先给账户充值才能调用 API。充多少看你的使用量，我建议先充个几十块跑通流程，确认效果再追加。充值和账单在控制台都能看见，调用费用按 token 计，具体单价去官网查最新价格。需要注意一点，API Key 别提交到公开仓库里，比如 GitHub 上的代码库，被别人拿走就能刷你的余额。

至于 Codex CLI 本身，官方完整版会要求登录 OpenAI 账号。当我们把 provider 切到 DeepSeek 之后，就不需要 OpenAI 付费订阅了，但有些版本首次运行还是会走一遍登录流程。如果你不想碰 OpenAI 账号，可以试试先配置好 DeepSeek provider 再启动，或者用codex login走一次初始化。不同版本表现不一样，后面有报错我再细讲。

3. 核心接入步骤：配置 model_provider 四步走

3.1 找到 Codex 的配置文件并理解结构

Codex 的全局配置文件叫config.toml，放在用户目录下的.codex文件夹里。macOS/Linux 路径是~/.codex/config.toml，Windows 是%USERPROFILE%\.codex\config.toml。如果你在编辑器里打开这个文件，里面一般会有一个默认的model和model_provider设置，指向 OpenAI 自家服务。

这个文件和很多 Linux 配置文件一样用的是 TOML 格式，特点就是层级和键值对非常直白。Codex 启动的时候会先读这个文件，拿到“默认模型是谁”“请求往哪发”“用哪个 Key”等信息。我们要做的，就是在这个文件里加一段 DeepSeek 的 provider，然后让默认模型指向它。

老版本的 Codex 还支持在项目目录下放.codex/config.toml做局部覆盖，这样不同项目能使用不同模型。如果你的版本支持，建议项目级配置和全局配置分开，避免所有项目都被 DeepSeek 绑定。

3.2 写一组 DeepSeek provider 配置

在config.toml里新增下面这段配置，然后保存文件。注意base_url后面要带/v1，因为 DeepSeek 的 OpenAI 兼容端点挂在/v1路径下：

model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY"

解释一下这几个字段：

• model：告诉 Codex 默认用哪个模型，深度学习平台的deepseek-chat对应通用对话模型。
• model_provider：指定请求由谁处理，这里需要和下方方括号里的名字保持一致。
• base_url：所有请求的实际发送地址，Codex 会往这个地址的后面拼具体的 API 路径。
• env_key：Codex 会从环境变量里读取这个 Key 对应的值，当作 API Key 使用。你也可以直接在这个 provider 里写死api_key，但那会把密钥留在明文中，不太安全，我不建议这么干。

配置文件保存好之后，还需要在系统环境变量里添加DEEPSEEK_API_KEY，值是你在 DeepSeek 平台创建的那一串 Key。macOS/Linux 临时设置可以用：

export DEEPSEEK_API_KEY="sk-你的key"

Windows PowerShell 里用：

$env:DEEPSEEK_API_KEY = "sk-你的key"

如果想永久生效，macOS/Linux 把这行写进~/.zshrc或~/.bashrc，Windows 在系统环境变量设置里添加。每次改完配置，记得新开一个终端窗口再跑 Codex，否则环境变量可能没生效。

3.3 首次验证：跑一条最简单的任务

配置写到这就算接上了，我们来验证一下。随便找一个空目录，执行：

codex exec "列出当前目录下的所有文件，并解释它们分别是什么"

如果一切正常，Codex 会调用 DeepSeek，返回一段带文件列表的解释。这时候你可以打开终端监控请求，回显模型名是deepseek-chat，说明请求已经发到了 DeepSeek。如果这一步出问题，不要急着改配置，先把常见报错那一章看完。

4. 模型选型与关键参数调优

4.1 deepseek-chat 和 deepseek-reasoner 怎么选

配置里的model字段决定了 Codex 用 DeepSeek 的哪条模型线。我测试了一段时间，两条线的表现差别挺明显的：

日常用 Codex 改代码、写脚本、做代码 review，我默认都用deepseek-chat，速度跟手，费用也友好。遇到那种“这个 bug 为什么只在生产环境出现”的复杂问题，我会临时把model改成deepseek-reasoner，让它慢一点没关系，把思路理清楚更重要。

切换模型不需要改配置文件里的其他部分，只改model = "deepseek-reasoner"这一行就够了。你甚至可以准备两份配置文件，或者直接用命令行参数覆盖，具体看版本支持的参数而定。

4.2 温度参数与上下文管理

如果你对 Codex 生成的代码风格不满意，可以通过配置里的model_reasoning_effort或请求里的temperature参数来调。DeepSeek 官方文档对deepseek-reasoner的要求是保持默认温度，不建议手动调整；而对deepseek-chat，温度可以按需调。低温度更像“照着规矩办事”，高温度更容易出现天马行空的写法，代码任务我建议保持在低区间。

上下文方面要有个概念：Codex 会把当前仓库里读到的文件内容作为背景发给模型，仓库一大，token 消耗会非常快。我接 DeepSeek 之后第一次跑大项目，就眼睁睁看着余额往下掉。后来我养成了习惯：让 Codex 干活之前，先用.gitignore把不必要的目录排除掉，或者只让它操作项目里的一个子目录。千万别让它一口气读整个仓库。

4.3 省钱和提速的实操技巧

• 把任务拆小：一次让 Codex 做一件事，别让它在几十个文件之间跳来跳去，这既省 token 又降低出错率。
• 优先用 chat 模型：只有遇到复杂问题才切 reasoner，别全程挂着推理模型。
• 清理历史上下文：交互模式下每次会话累积太多内容后，费用会明显上升。遇到新任务就开新会话，别一直在旧会话里聊。
• 关注用量看板：DeepSeek 控制台能看到实时用量，第一次跑完一个项目后去对比一下，你对成本就有实际概念了。

5. 常见报错速查表：对着症状找解法

接入这事整体不难，但我在实际操作里还是踩了一堆坑，有些报错特别误导人。我把最常见的几个列出来，你碰到类似情况可以直接对照处理。

5.1 连接层：cc switch local proxy failed while handling codex endpoint /responses

这个报错是 Codex 在切换 provider 时，本地请求转发环节出了问题。看到endpoint /responses基本可以断定是请求没发到 DeepSeek，或者发到了但对方不认这个端点。

排查步骤：

1. 先确认base_url没写错，正确写法是https://api.deepseek.com/v1，少个/v1或多个斜杠都会出问题。
2. 手动用curl测试一下 DeepSeek 端点通不通，比如：

curl https://api.deepseek.com/v1/models -H "Authorization: Bearer $DEEPSEEK_API_KEY"

能返回一个模型列表就说明网络和 Key 都没问题。

3. 如果报错信息里提到了 local proxy，去检查本地是否有 HTTP 代理环境变量干扰了 Codex 的请求。有时候系统全局代理会把 API 请求劫走，表现就是 Codex 卡住或报这个错。

这个报错还有一个变种是请求到了/responses但返回 404，因为 DeepSeek 官方对 Responses 协议的支持并不完整。遇到这个情况，最可靠的方案是找一层兼容转换网关，它能把 Codex 的 Responses 格式请求转成 DeepSeek 能识别的 Chat Completions 格式。社区里常见的现成方案是部署一个本地 API 转发服务，然后把base_url指向它的地址。这个操作比普通配置稍微复杂一点，但能根治协议不兼容的问题。

5.2 配置层：codex is ignoring 1 unrecognized configuration setting

这个报错在英文内容里经常看到，意思是 Codex 读配置文件时发现了一个它不认识的设置项。出现这个基本就是config.toml里的键名拼错了，或者你从网上抄了一段不适配当前版本的配置。

解决办法很简单：仔细检查config.toml的每一行键名，对照官方文档确认拼写。常见的几个坑包括把base_url写成baseUrl，把env_key写成envKey，TOML 配置里必须用下划线而不是驼峰。另外，有些第三方教程会让你加一些当前版本不支持的字段，也可能会出现这个提示。遇到这种报错，最干净的处理方式是把多余的配置项删掉，只保留章节 3.2 里的核心配置。

5.3 账号层：codex 无法加载组织设置或codex 登录不上

这个问题有两个来源。一个确实是网络层面的问题，Codex 启动时要拉取组织设置，结果连不上；另一个是账号本身有过期 session 或者和自定义 provider 冲突。

我碰到过最典型的情况是，公司电脑上装了某些安全软件，把 Codex 的请求拦住了。这个只能从网络放行层面处理。如果是个人电脑，先确认当前网络环境是否畅通；再试着手动执行codex login重新走一遍登录流程。有的版本登录时会让选择“使用 OpenAI 账号”还是“第三方登录”，如果你完全不用 OpenAI，直接按照自定义 provider 的路子初始化就行。还有一种情况是你的组织设置了灰度策略，部分账号功能受限，那基本只能等风控过了再用。

这里要注意：「Codex 接入 DeepSeek」本身不依赖 OpenAI 账号，但 Codex 程序启动时的内部门控逻辑仍然存在。不同版本在这个环节的表现不太一样，如果第一次运行卡在登录流程上，建议试一下codex --help看当前版本支持哪些参数，跳过登录直接以本地配置模式运行。

5.4 请求层：deepseek request extension preparation failed

这个报错我一开始完全没头绪，字面意思是“请求扩展准备失败”。后来仔细排查，发现是请求体或者模型配置在发送前被 Codex 扩展层拦截了，最常见的几个诱因：

• model字段写的模型名对不上，比如写错了大小写或者写了不存在的模型名。
• 请求头里的 API Key 没有正确读取到，环境变量DEEPSEEK_API_KEY没设好。
• 请求里带了 DeepSeek 不支持的参数，比如某些版本 Codex 会往请求体里塞 reasoning 相关的参数。

处理方法是先简化配置，只保留最小化的 provider 配置，确认能跑通后再逐步加参数。另外，如果你是通过兼容网关转发，网关那边的模型映射表也要检查，别让网关把一个不存在的模型名传过去。

5.5 报错速查表

6. 进阶扩展：把本地部署的 DeepSeek 也接进 Codex

6.1 本地部署方案怎么选

如果你的数据隐私要求高，或者不想按 token 付费，可以把 DeepSeek 部署在本地，再把 Codex 接过去。这个方向现在社区玩得很开心，尤其是 Ollama 和 vLLM 这两条路线。

Ollama 胜在简单，装好之后一条命令就能跑起模型，适合个人电脑快速验证。vLLM 更专业，吞吐率高、显存利用好，适合那种“我要正经当个服务用”的场景。如果你的环境是 NVIDIA 显卡，或者是在 Jetson Orin 这样的边缘设备上跑，vLLM 的表现会更稳。

本地部署对硬件还是有一定要求的。DeepSeek 的满血版模型参数太大，个人设备基本跑不动。社区里大家玩得多的，要么是 DeepSeek 系列里的中小规模版本，要么是量化蒸馏版本。效果和官方 API 的完整模型相比有差距，但日常简单代码辅助、文本处理完全够用。

6.2 本地 OpenAI 兼容端点怎么配

Ollama 启动模型后，默认会监听在本地的11434端口，它在/v1路径下提供 OpenAI 兼容接口。所以 Codex 的配置可以改成这样：

model = "deepseek-r1:7b" model_provider = "deepseek-local" [model_providers.deepseek-local] name = "DeepSeek Local" base_url = "http://localhost:11434/v1" env_key = "LOCAL_API_KEY"

env_key这里随便设一个环境变量，因为本地服务一般不校验 Key，但你得设置一个非空值让 Codex 通过校验。设置成任意字符串就行，比如export LOCAL_API_KEY="local"。

vLLM 部署之后会启动一个 OpenAI 兼容的 API 服务，默认地址是http://localhost:8000/v1，配置思路完全一样，只要把base_url换成 vLLM 的地址即可。要注意本地模型一次只能服务一个模型，切换模型需要改启动参数并重启服务。

6.3 本地接入的几个坑

• 本地模型的上下文窗口如果配得很小，Codex 传一个稍微大点的仓库就会直接把上下文撑爆，报错形式非常隐蔽，表现为“请求失败”但网络是通的。
• 不要把本地服务和云端用同一个env_key，容易混淆到底在调谁。
• 边缘设备上跑模型时，显存不足会导致推理速度慢到像死机一样，建议先用小模型验证流程，再换大模型。

我用本地部署接 Codex 的主要场景是断网状态下做一些代码整理任务，效果算“能用的水平”。说实话，代码能力和 DeepSeek 官方 API 还是有不小差距，但它胜在离线、免费、数据不出机器。要不要上本地部署，得看你到底更在意效果还是更在意隐私。

最后说点我的实际感受

整套接入流程折腾下来，我最想提醒的就一句话：出现报错先别急着怀疑配置写错，先确认端点和协议这一层通不通。我有一半的调试时间都花在了/responses端点的兼容问题上，而不是配置本身。Codex 和 DeepSeek 这个组合，成本确实香，复杂任务用 reasoner 也确实能打，但协议差异这关绕不过去，建议从一开始就把兼容网关的方案想在前面。

还有个小技巧收尾：如果你经常在多个模型之间切换，可以在config.toml里配好几个不同的model_providers，然后通过修改model_provider字段快速切换。不用反复删配置，也不用记一堆命令，改一行保存重启就行。我就是这么在 OpenAI 和 DeepSeek 之间来回切的，实测很顺手。