Codex 配置大模型总览

Codex 配置大模型总览

这一篇放在安装教程后面、项目实战前面。

原因很简单：你还没有开始让 Codex 正式读项目、改代码之前，先要知道它背后用的是哪个模型、谁来计费、配置写在哪里、API Key 怎么保护。否则后面一旦报错，你分不清是 Codex 没装好、模型服务商配置错了，还是网络和额度出了问题。

前置教程：Codex CLI 安装与登录
如果你还没有安装 codex 命令、完成登录，并能在项目目录里启动 Codex，先完成前置教程，再回到本篇。

依据来源：OpenAI Codex 官方手册中的 config.toml、Custom model providers、Authentication 等章节。

本篇目标

跟着本篇看完后，你应该能讲清楚：

1. Codex 为什么需要“模型配置”。
2. model、model_provider、base_url、env_key 分别是什么。
3. API Key 应该放在哪里，不应该放在哪里。
4. 为什么国内模型要优先看“OpenAI 兼容接口”。
5. 为什么不要直接复制别人几个月前的模型名。
6. 后面配置 DeepSeek、通义千问、Kimi 等服务商时，你要先准备哪些信息。

先理解一句话

你可以把 Codex 理解成“会读项目、会改文件、会跑检查的编程助手”，但真正生成答案的是它连接的模型服务。

所以一次 Codex 任务大概是这样流动的：

你输入任务
-> Codex 读取项目上下文
-> Codex 按配置调用某个模型
-> 模型返回计划或代码建议
-> Codex 在你的确认和权限范围内执行
-> Codex 汇报结果

本篇只讲中间这一段：

Codex 按配置调用某个模型

你先不要改配置

新手最容易犯的错是：看到别人发了一个配置片段，就立刻复制到自己的电脑里。

这样很容易出 5 类问题：

1. 模型名已经过期。
2. Base URL 写错地域。
3. API Key 环境变量没设置。
4. 把 API Key 明文写进配置文件。
5. 还没确认 Codex 本身能正常启动，就开始排查模型。

正确顺序是：

先确认 Codex CLI 能启动
-> 再理解模型配置概念
-> 再选择模型服务商
-> 再准备 API Key / Base URL / 模型名
-> 再写配置
-> 最后用只读任务验证

4 个核心概念

1. model

model 是你要调用的模型名。

示例：

deepseek-v4-pro
qwen-plus
kimi-k2.6

注意：模型名必须以服务商官方文档或控制台为准。国内服务商的模型名变化很快，不要只看旧博客。

2. model_provider

model_provider 是 Codex 里给某个模型服务商起的编号。

你可以理解成：

我要用哪个服务商配置

例如你可以给 DeepSeek 起一个 provider id：

deepseek

给通义千问起一个 provider id：

dashscope

Codex 官方手册里说明，自定义 provider 不能复用内置保留 ID，例如 openai、ollama、lmstudio。

3. base_url

base_url 是模型服务商的接口地址。

你可以理解成：

Codex 要把请求发到哪里

例如 DeepSeek 官方文档给出的 OpenAI 兼容 Base URL 是：

https://api.deepseek.com

通义千问百炼北京地域的 OpenAI 兼容地址是：

https://dashscope.aliyuncs.com/compatible-mode/v1

Base URL 不要凭感觉写。尤其是阿里云、火山方舟这类平台，可能区分地域、工作空间或专属域名。

4. env_key

env_key 是环境变量名，不是 API Key 本身。

比如你把 DeepSeek 的 API Key 放到系统环境变量里：

DEEPSEEK_API_KEY

那么 Codex 配置里写的是：

env_key = "DEEPSEEK_API_KEY"

不是：

env_key = "sk-xxxxxxxx"

这点关键。

API Key 绝对不要这样放

不要把 API Key 放在这些地方：

• 不要发给 Codex 聊天窗口。
• 不要发到微信群、文章、截图。
• 不要写进教程文档。
• 不要写进 Git 仓库。
• 不要写到会被提交的 .md、.js、.env.example 里。

正确做法是：

把真实 API Key 放到本机环境变量里。
配置文件只写环境变量名。
截图时遮住控制台 Key、余额、账号、组织信息。

Codex 自定义 provider 长什么样

OpenAI Codex 官方手册给出的思路是：定义一个 provider，再让 model_provider 指向它。

结构大概长这样：

model = "这里写模型名"
model_provider = "这里写 provider id"

[model_providers.provider_id]
name = "这里写显示名称"
base_url = "这里写服务商 Base URL"
env_key = "这里写环境变量名"

注意：上面是结构示意，不是让你直接复制运行。

不同服务商是否需要额外字段、是否完全兼容、模型名是否可用，都要以对应服务商单篇教程为准。

配置前要收集的信息

每次配置一个国内模型服务商，都先准备下面 6 项：

信息	例子	从哪里拿
服务商	DeepSeek / 通义千问 / Kimi	你选择的平台
OpenAI 兼容性	是否提供 /chat/completions 或兼容 OpenAI SDK	官方文档
Base URL	https://api.deepseek.com	官方文档
模型名	deepseek-v4-pro、qwen-plus	官方模型列表
API Key 环境变量名	DEEPSEEK_API_KEY	你自己命名，建议全大写
最小验证任务	只读分析当前项目	本站教程

如果这 6 项缺任何一项，先不要写配置。

让 Codex 帮你整理配置草稿

注意：不要把真实 API Key 发给 Codex。

你可以在 Codex 里这样说：

我准备为 Codex 配置一个 OpenAI 兼容的国内模型服务商。

已知信息如下：
- 服务商：DeepSeek
- provider_id：deepseek
- base_url：https://api.deepseek.com
- model：deepseek-v4-pro
- API Key 环境变量名：DEEPSEEK_API_KEY

要求：
1. 先不要修改任何文件。
2. 不要要求我把真实 API Key 发给你。
3. 请先根据当前 Codex 官方配置方式，给出 config.toml 配置草稿。
4. 请解释每一行配置是什么意思。
5. 请告诉我还需要确认哪些风险点。

这段提示词的目的不是让 Codex 马上动手，而是让它先把配置草稿和风险讲清楚。

配置完成后怎么验收

模型配置不是“写进去就算完”，必须验收。

推荐验收顺序：

1. 启动 Codex。
2. 发一句普通中文问题，确认模型能回复。
3. 进入练习项目。
4. 只读分析项目，不修改文件。
5. 让 Codex 解释它当前使用的模型配置来源。
6. 检查 Git 状态，确认没有意外改动。

最小验收提示词：

请只读分析当前项目，不要修改任何文件。

另外请用中文说明：
1. 你是否能正常响应。
2. 本次任务有没有读取项目文件。
3. 本次任务有没有修改文件。
4. 如果你能判断，请说明当前使用的是哪个模型配置；如果不能判断，请明确说不能判断。

常见误区

误区 1：国内模型都能直接替代 OpenAI 官方模型

不一定。

很多服务商提供 OpenAI 兼容接口，但“接口兼容”不等于“能力、工具调用、流式输出、推理参数、上下文长度、报错格式完全一样”。

教程里会把每个服务商逐个验证，不会默认一份配置通吃。

误区 2：模型越大越适合 Codex

不一定。

Codex 任务需要的不只是聊天能力，还包括：

• 理解项目结构。
• 稳定遵守修改范围。
• 输出可执行计划。
• 处理长上下文。
• 解释命令结果。
• 不乱猜。

有些模型聊天很强，但做代码代理任务未必稳定。本站后面会用真实任务来验收。

误区 3：配置失败就是 Codex 坏了

不一定。

最常见原因反而是：

• API Key 没设置。
• 环境变量设置后没有重开终端。
• Base URL 写错。
• 模型名过期。
• 账号没开通模型权限。
• 余额或额度不足。
• 网络、代理、地域限制。

本篇验收结果

看完这篇，你不需要马上完成某个服务商配置。

只要你能做到下面 5 点，就算完成：

1. 你知道 model 是模型名。
2. 你知道 model_provider 是 Codex 使用哪个 provider。
3. 你知道 base_url 必须来自官方文档。
4. 你知道 env_key 是环境变量名，不是真实 API Key。
5. 你知道模型配置完成后，先用只读任务验收，不要直接改代码。

下一篇学什么

下一篇看：国内大模型配置方案。

那一篇会把 DeepSeek、通义千问、Kimi、硅基流动等服务商的信息放在同一张表里，先教你怎么选、怎么收集参数、怎么避免泄露 API Key。

参考资料

• OpenAI Codex 官方手册：https://developers.openai.com/codex/codex-manual.md
• DeepSeek API 文档：https://api-docs.deepseek.com/
• 阿里云百炼 OpenAI 兼容文档：https://help.aliyun.com/zh/model-studio/compatibility-of-openai-with-dashscope
• Kimi OpenAI 迁移文档：https://platform.kimi.com/docs/guide/migrating-from-openai-to-kimi