桌面版如何使用国内大模型配置
桌面版如何使用国内大模型配置
Section titled “桌面版如何使用国内大模型配置”桌面版接入国内大模型，核心不是“在 App 里找一个模型配置页”，而是理解 Codex 的配置层。
前置教程：Codex 桌面版第一次选择项目
如果你还没有用桌面版成功选择项目并完成只读分析，先完成前置教程。
依据来源：OpenAI Codex 官方手册中的 Configuration、Custom model providers、Authentication、Desktop app and VS Code extension 环境变量说明。
桌面版和 CLI 的大模型配置 大方向一样：
- 都使用 Codex 的配置层。
- 用户级配置通常在
~/.codex/config.toml。 - 国内大模型通常通过 OpenAI 兼容接口配置 provider。
- API Key 不应该写进教程、截图或聊天内容。
但桌面版和 CLI 有一个关键的区别：
桌面版不一定能继承你在 PowerShell 里临时设置的环境变量。
所以桌面版配置国内大模型时，更推荐把需要的密钥环境变量放到：
~/.codex/.env然后重启 Codex 桌面版。
第 1 步：先确认你已经有一份可用模型配置
Section titled “第 1 步：先确认你已经有一份可用模型配置”如果你还没有配置过国内大模型，先不要从本篇开始。
请先看：
如果你已经决定用某个服务商，再看对应教程：
- Codex + DeepSeek 配置
- Codex + 通义千问/Qwen 配置
- Codex + Kimi 配置
- Codex + 硅基流动配置
- Codex + 智谱 GLM 配置
- Codex + 豆包/火山方舟配置
本篇不重复讲每个服务商的 Base URL 和模型名。
本篇只解决一个问题：这些配置怎么让桌面版也能用。
第 2 步：理解两个关键文件
Section titled “第 2 步：理解两个关键文件”桌面版通常要关注两个文件：
C:\Users\你的用户名\.codex\config.toml和：
C:\Users\你的用户名\.codex\.env它们分工不同：
| 文件 | 放什么 | 能不能截图公开 |
|---|---|---|
config.toml | 模型名、provider 名、Base URL、配置项 | 可以截图，但要检查是否有密钥 |
.env | API Key 等密钥环境变量 | 不要截图公开 |
你可以这样理解：
config.toml告诉 Codex 去哪里找模型。.env告诉 Codex 用什么密钥访问模型。
第 3 步：打开 config.toml
Section titled “第 3 步：打开 config.toml”在 Codex 桌面版里，通常可以从设置中打开配置文件。
你要找类似含义的入口：
- Settings
- Configuration
- Open config.toml
- 设置
- 配置
如果界面入口找不到，也可以在资源管理器地址栏输入：
%USERPROFILE%\.codex然后打开：
config.toml第 4 步：检查模型 provider 是否写在用户级配置
Section titled “第 4 步：检查模型 provider 是否写在用户级配置”国内模型 provider 建议优先写在用户级：
~/.codex/config.toml不要一开始就写到项目里的：
.codex/config.toml原因是：
- 用户级配置可以被桌面版、CLI、IDE 扩展复用。
- 项目级配置只有在项目被信任后才会加载。
- 新手把模型 provider 写到项目级，容易出现“CLI 能用，桌面版新项目不能用”的困惑。
一个简化示例：
model = "你的模型名"model_provider = "你的provider"
[model_providers.你的provider]name = "你的服务商名称"base_url = "https://你的服务商OpenAI兼容地址"env_key = "你的环境变量名"注意：这只是结构示例，不要直接复制运行。具体 model、base_url、env_key 以对应服务商教程为准。
第 5 步：把 API Key 放到 .env
Section titled “第 5 步：把 API Key 放到 .env”桌面版和 IDE 扩展可能不会继承 PowerShell 里临时设置的环境变量。
因此，给桌面版用国内大模型时，建议在：
C:\Users\你的用户名\.codex\.env写入类似这样的内容：
DEEPSEEK_API_KEY=这里换成你的真实APIKey或者：
DASHSCOPE_API_KEY=这里换成你的真实APIKey变量名必须和 config.toml 里的 env_key 对上。
例如：
env_key = "DEEPSEEK_API_KEY"那么 .env 里就要写：
DEEPSEEK_API_KEY=你的真实密钥不要写成：
DEEPSEEK_KEY=你的真实密钥这两个名字不一样，Codex 就找不到。
第 6 步：重启 Codex 桌面版
Section titled “第 6 步：重启 Codex 桌面版”改完 config.toml 或 .env 后，不要在旧会话里继续测试。
请按顺序做：
- 关闭 Codex 桌面版。
- 确认它不是最小化在托盘里。
- 重新打开 Codex 桌面版。
- 打开你的练习项目。
- 新建一个会话。
原因是：配置和环境变量通常在应用启动或新会话时加载。
如果你不重启，可能出现“明明配置对了，但 App 还是用旧状态”的错觉。
第 7 步：用只读任务验证模型
Section titled “第 7 步：用只读任务验证模型”在桌面版里输入：
请只读检查当前 Codex 会话的模型和 provider 配置是否可用。
要求：1. 不要修改任何文件。2. 不要把我的 API Key 输出出来。3. 如果能确认当前模型或 provider，请用中文说明。4. 如果不能确认，请告诉我应该检查 config.toml、.env、Base URL、模型名、额度还是网络。如果 Codex 能正常回复，而且没有模型报错，说明基础链路可用。
如果出现错误，先不要改配置。
先把错误归类：
- API Key 错。
- 模型名错。
- Base URL 错。
- 额度不足。
- 服务商没有开通模型。
- 桌面版没有读取到
.env。 env_key和.env变量名不一致。
然后看：国内模型配置排障总表。
第 8 步：确认桌面版和 CLI 的关系
Section titled “第 8 步：确认桌面版和 CLI 的关系”如果你同时使用桌面版和 CLI，请记住：
- 用户级
~/.codex/config.toml是共用配置层。 - 桌面版、CLI、IDE 扩展都可能读取它。
- CLI 的一次性命令参数只影响那一次 CLI。
- 桌面版新会话通常要重启或重新开会话后才更稳。
- 桌面版和 IDE 扩展对环境变量继承更容易踩坑，所以
.env更稳。
这是为什么本站会把“模型配置”放在正式项目实战之前。
模型没配清楚，后面任何报错都不好判断。
我已经在 PowerShell 设置了环境变量，桌面版还需要 .env 吗
Section titled “我已经在 PowerShell 设置了环境变量，桌面版还需要 .env 吗”建议需要。
PowerShell 里的临时环境变量只对当前终端会话可靠。桌面 App 不一定能继承。
如果你希望桌面版稳定读取 API Key，把它放到 ~/.codex/.env 更直观。
我改了 config.toml，为什么桌面版没变化
Section titled “我改了 config.toml，为什么桌面版没变化”按这个顺序检查：
- 是否保存了文件。
- 是否改的是
C:\Users\你的用户名\.codex\config.toml。 - 是否关闭并重新打开了 Codex 桌面版。
- 是否新建了会话。
model_provider是否和[model_providers.xxx]对得上。
桌面版能不能给每个项目用不同模型
Section titled “桌面版能不能给每个项目用不同模型”可以通过项目级 .codex/config.toml 做更细的设置，但新手阶段不建议一开始这么做。
原因是项目级配置涉及“项目是否被信任”和配置层优先级，排障复杂度会变高。
先把用户级配置跑通，再学项目级配置。
完成后，你应该能说清楚：
- 桌面版和 CLI 的模型配置大方向一样。
- 用户级配置是
~/.codex/config.toml。 - 桌面版更推荐把 API Key 放到
~/.codex/.env。 - 改配置后要重启桌面版并新建会话。
- 验证时先做只读任务，不要上来就改项目。
下一篇看：CLI、桌面版、IDE 配置为什么能共用。