Codex 接入 DeepSeek 等国产模型配置教程
很多人用 Codex 写代码时会发现一个痛点：它默认绑定 OpenAI，国内访问慢、计费走美元、还可能触网受限。其实 Codex 支持改配置文件、把模型供应商换成 DeepSeek 等国产模型——这篇就讲清楚改哪里、怎么改、改完效果怎么样，以及踩坑时怎么排查。本文面向已经装好 Codex、想把后端模型换成国产兼容端点的开发者。
原理：Codex 为什么能换模型
Codex 接入 DeepSeek 的本质，是把请求从 OpenAI 官方端点改指向一个”OpenAI 兼容”的第三方端点。
这里的关键概念叫 OpenAI 兼容 API。DeepSeek、Kimi、GLM 这些国产模型，大多对外提供一套和 OpenAI chat/completions 接口格式一致的 HTTP 端点。请求体长一样、响应结构长一样，只是域名（base_url）、模型名（model）、密钥（api_key）不同。
所以换模型不需要改 Codex 源码，只要在配置里告诉它三件事：
- 去哪发请求（base_url 指向 DeepSeek 的兼容端点）
- 用哪个模型（model 填 DeepSeek 的模型名）
- 拿什么钥匙（api_key 用 DeepSeek 平台申请的）
这就是为什么”机制是长青的、参数是易变的”——端点地址和模型名可能随官方调整，但改 provider + base_url 的套路不变。具体的端点 URL 和模型名一律以 DeepSeek 官方文档为准。
但这里有个容易被忽略的细节：“接口格式兼容”不等于”能力和行为完全一致”。 Codex 除了发普通对话请求，还会发工具调用（tool calling）请求——比如”帮我改这个文件""帮我跑这条命令”，背后都是模型返回一段结构化的函数调用指令，Codex 解析后去执行。这套协议 OpenAI 模型是原生训练、深度调校过的；国产模型即便声称”兼容 function calling”，在多轮嵌套调用、参数格式严谨度、指令跟随的稳定性上多少会有差异。这也是为什么同样是”能接”,简单问答几乎零感知,复杂 agent 任务却可能出现”格式对不上导致工具调用失败”的情况。理解这一层，你才知道换模型之后该往哪个方向去验证，而不是只测一句”你好”就下结论。
通用配置：三步换后端
Codex 的模型配置走的是配置文件 + 环境变量，不是图形界面。下面是通用骨架，具体字段名以你装的 Codex 版本官方文档为准。
第一步：在配置文件里定义一个新 provider。
Codex 的配置文件通常在用户目录下（如 ~/.codex/config.toml 一类路径，具体以官方文档为准）。新增一个自定义供应商，指向 DeepSeek 的兼容端点：
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1" # 以 DeepSeek 官方文档为准
env_key = "DEEPSEEK_API_KEY" # 从环境变量读密钥
第二步：把默认 provider 和 model 切到 DeepSeek。
model_provider = "deepseek"
model = "deepseek-chat" # 具体模型名以官方文档为准
第三步：配置密钥（环境变量）。
不要把 api_key 明文写进配置文件，用环境变量更安全：
export DEEPSEEK_API_KEY="你的密钥" # 写进 ~/.bashrc 或 ~/.zshrc 持久化
配好后重开终端，让环境变量生效，再启动 Codex 即可。
进阶技巧：别只留一个 provider，多写几套按任务切换。 实际用下来最舒服的方式不是”一劳永逸换成 DeepSeek”，而是在配置文件里同时保留 openai 和 deepseek 两个 provider 块，日常任务默认走 DeepSeek，遇到复杂 agent 任务再手动把 model_provider 改回 openai 跑一遍。这个切换成本只是改一行配置、重启一次，比”能力不够又要临时申请 OpenAI 额度”省心得多。如果你的 Codex 版本支持通过命令行参数或 profile 临时指定 provider（不用改配置文件），优先用这种方式——具体是否支持、参数怎么写，以你本地 codex --help 或官方文档为准，别凭经验硬猜。
同样的套路适用于把 Claude Code 接入国产模型，原理一致——都是改兼容端点。
分情况说明：DeepSeek / Kimi / GLM
不同国产模型只是端点和模型名不同，配置结构完全一样，照着上面骨架替换即可：
| 模型 | provider 名（自取） | base_url | 模型名示例 |
|---|---|---|---|
| DeepSeek | deepseek | DeepSeek 官方兼容端点 | deepseek-chat / 推理模型 |
| Kimi | kimi | 月之暗面兼容端点 | Kimi 系列模型名 |
| GLM（智谱） | glm | 智谱兼容端点 | GLM 系列模型名 |
表中 base_url 和模型名一律以各家官方文档为准，不同时期会变。建议在配置文件里多写几个 provider 块预备好，需要时只改 model_provider 一行即可快速切换。
怎么验证成功
改完别急着写大任务，先做一个最小验证：
- 看启动日志：Codex 启动时通常会打印当前用的 provider / model，确认显示的是 deepseek 而非 openai。
- 发一句简单指令：让它”用一句话解释什么是闭包”，能正常返回中文回答即说明端点通了。
- 看计费后台：去 DeepSeek 平台后台看是否产生了调用记录——有记录说明请求真的打到了国产端点，而不是悄悄回落到 OpenAI。
效果取舍：换了之后会差吗
换国产模型省钱、访问稳，但要接受能力差异，给几条实在判断：
- 日常写代码、补全、解释、改 bug：国产模型完全够用，体验差距小，性价比明显。
- 复杂多步骤 agent 任务、长链路工具调用：Codex 的智能体能力是和 OpenAI 模型深度调校的，换模型后编排稳定性可能下降，需要多试。
- 超长上下文、跨大量文件重构：不同模型上下文窗口和长文表现不同，以实际任务体感为准，别只看参数表。
拿几个真实场景对号入座会更直观：
- “帮我把这个函数的参数从位置参数改成关键字参数，顺带改调用处”——这类局部改动，国产模型基本一次到位，跟 OpenAI 模型几乎没差别。
- “读一遍这个模块的代码，帮我写一版单元测试”——中等难度，国产模型大多能完成，但偶尔会漏边界情况，建议自己再过一遍测试用例，别全信。
- “跨 10+ 个文件重构一套接口签名，改完自动跑测试并修复失败用例”——这是典型的多步 agent 任务，链路一长，工具调用出错的概率会累积。这种场景先用国产模型跑一遍探路，卡住了再切回强模型收尾，比一开始就死磕更省时间。
还有一种情况建议别换：如果你所在团队对代码走向有合规审计要求（比如金融、医疗类客户明确要求只能用指定供应商的模型），或者任务重度依赖多模态（读图、读 PDF 里的图表），国产兼容端点在这些能力上的支持程度参差不齐，先去官方文档确认能力清单，别等任务跑到一半才发现不支持。
一句话：把国产模型当主力日常用、把强模型留给硬骨头，按任务难度切 model_provider，是性价比最高的用法。想系统理清各模型差异，可看 国产 AI 编程工具横评（规划中）。
常见坑与排查
接入失败大多是这几类，按”报错 → 原因 → 解法”对号入座：
- 401 / 鉴权失败：密钥没读到或填错。检查环境变量名和配置里的
env_key是否一致、终端是否重开。 - 404 / 模型不存在：模型名拼错或该平台没这个模型。回 DeepSeek 官方文档核对当前可用模型名。
- 请求超时 / 连不上：base_url 写错（漏了
/v1、协议头、多了斜杠），或网络问题。逐字符核对端点。 - 能连但回答乱码/截断：可能是该 provider 对某些参数（如 max_tokens、流式）支持不同。先关掉流式、用默认参数跑通再调。
- agent 任务跑一半卡住：国产模型对 Codex 的工具调用协议适配可能不完整，换个模型版本或退回简单任务验证。
- 公司网络连不上外部端点：如果你在公司内网或有代理，DeepSeek 的域名可能被防火墙拦截、或者必须走代理才能出网。先用
curl直接测一下端点能不能通，再回头怀疑 Codex 配置的问题，别本末倒置排查半天。 - TOML 配置文件语法报错：手改配置文件最容易踩的坑是引号不对称、缩进错乱、多写或漏写一层方括号。改完先用 TOML 校验工具（或编辑器插件）过一遍语法，再启动 Codex，能省掉不少”明明改对了却报错”的抓狂时间。
- 输入过长直接报错：不同模型的上下文窗口大小不同，如果你把一整个大文件甩给它、之前在 OpenAI 模型上没问题，换了国产模型可能会因为窗口更小而报”超长”错误。这种情况先精简输入范围，或者查一下该模型的窗口上限是不是确实比你之前用的小。
排查口诀：先确认密钥、再确认端点、最后确认模型名，九成问题在前两步。
常见问题
Codex 接入 DeepSeek 要钱吗？ Codex 本身的接入不额外收费，但你调用 DeepSeek 是按它的 API 计费（通常比 OpenAI 便宜不少）。具体价格以 DeepSeek 官方为准，本文不写易变数字。
改了配置 Codex 还是连 OpenAI 怎么办？
多半是配置文件路径不对、或 model_provider 没切过来。确认你改的是 Codex 实际读取的那个配置文件，并重启工具；再去 DeepSeek 后台看有没有调用记录验证。
国产模型能跑 Codex 的自动化 agent 吗？ 能跑，但复杂多步任务的稳定性不如官方强模型。简单任务无感，硬任务建议临时切回强模型。按任务切 provider 是最优解。
一定要用环境变量存密钥吗？ 强烈建议。明文写进配置文件容易随仓库泄露。用环境变量（或密钥管理工具）是基本安全习惯。
只想试试，不想动配置文件行不行？ 可以先在终端临时 export 环境变量、命令行临时指定 model，跑通后再决定要不要写进配置文件持久化。
👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。