CLI、桌面版、IDE 配置为什么能共用

很多新手会问：我在 CLI 配好了模型，桌面版能不能用？我在桌面版改了设置，IDE 扩展会不会生效？

答案是：很多基础配置可以共用，但不是所有临时状态都共用。

前置教程：桌面版如何使用国内大模型配置
如果你还没有理解 config.toml 和 .env 的分工，先完成前置教程。

依据来源：OpenAI Codex 官方手册中的 Configuration、Config basics、Project config files、Authentication and sessions、Models 等章节。

核心结论

Codex 的多个本地入口共享同一套配置层。

这些入口包括：

Codex CLI。
Codex 桌面版。
Codex IDE 扩展。

但你在某一个入口里做的“本次会话临时选择”，不一定会变成全局配置。

第 1 层：用户级配置

最重要的是用户级配置：

C:\Users\你的用户名\.codex\config.toml

在文档里也常写成：

~/.codex/config.toml

这个文件适合放：

默认模型。
默认 provider。
自定义国内大模型 provider。
常用审批策略。
常用沙箱策略。
MCP 配置。
功能开关。

这类配置适合“我希望以后默认都这样”。

第 2 层：密钥环境变量

API Key 不应该直接写在公开教程、聊天、截图里。

更稳的方式是：

C:\Users\你的用户名\.codex\.env

里面放：

某个变量名=真实APIKey

然后在 config.toml 里通过：

env_key = "某个变量名"

引用它。

注意：变量名必须完全一致。

第 3 层：项目级配置

项目里也可以有：

.codex/config.toml

它适合放项目独有配置，比如：

这个项目默认用哪个模型。
这个项目需要哪些 MCP。
这个项目的审批和沙箱偏好。
这个项目的特殊规则。

但新手阶段先不要用。

原因是项目级配置只有在项目被信任后才会加载。你如果还没搞懂用户级配置，直接用项目级配置，排障会变复杂。

第 4 层：入口内的临时选择

不同入口可能提供临时选择方式。

例如：

CLI 里用 /model 临时切换。
CLI 启动时加 --model。
IDE 扩展里用输入框下方的模型选择器。
桌面版里从界面切换某个会话的选项。

这些临时选择适合“本次任务临时换一下”。

不要把它们理解成一定会永久写进 config.toml。

如果你希望长期默认，就写用户级 config.toml。

一张表看懂

你想做什么	放哪里
以后默认都用某个模型	`~/.codex/config.toml`
配置国内服务商 Base URL	`~/.codex/config.toml`
保存 API Key	`~/.codex/.env` 或安全环境变量
某个项目专用配置	项目里的 `.codex/config.toml`
只在这次 CLI 会话换模型	CLI 临时命令或 `/model`
只在 IDE 当前任务换模型	IDE 模型选择器
排查桌面版读不到密钥	优先检查 `~/.codex/.env` 并重启 App

最稳的新手配置路线

如果你是新手，按这个路线走：

先安装并登录一个入口。
优先用用户级 ~/.codex/config.toml 配模型。
把 API Key 放到 ~/.codex/.env。
重启桌面版或 IDE 扩展。
新建会话。
做只读验证。
成功后再进入项目实战。

不要同时改 3 个地方。

否则失败以后，你不知道到底是哪个配置生效了。

如何让 Codex 帮你检查配置

你可以直接把下面这段发给 Codex：

请帮我只读检查 Codex 配置层是否清晰。

要求：
1. 不要输出任何 API Key。
2. 不要修改任何文件。
3. 请说明用户级 config.toml、项目级 .codex/config.toml、.env、当前会话临时设置分别可能影响什么。
4. 如果你发现配置冲突，请先列出来，不要直接修改。

这段提示词适合在你已经进入项目后使用。

它的重点是让 Codex 先解释配置来源，而不是直接帮你乱改。

常见问题

我在 CLI 能用，桌面版不能用，为什么

优先怀疑环境变量。

CLI 是从终端启动的，可能能读到当前终端环境变量。

桌面版是图形应用，不一定继承终端里的临时变量。

解决路线：

把 API Key 放到 ~/.codex/.env。
确认 env_key 名字一致。
重启桌面版。
新建会话验证。

我在项目里写了 .codex/config.toml，为什么不生效

常见原因：

项目没有被信任。
文件路径写错。
配置项写错。
被更近目录下的 .codex/config.toml 覆盖。
用户级配置和项目级配置理解混乱。

新手优先把模型 provider 放到用户级配置。

我应该先学项目级配置吗

不建议。

项目级配置很有用，但它适合你已经跑通用户级配置之后。

本站后面会单独写 config.toml 入门 和项目级配置教程。

本篇验收

完成后，你应该能判断：

哪些配置适合写到用户级。
哪些配置适合写到项目级。
为什么桌面版可能读不到 PowerShell 临时环境变量。
为什么改 .env 后要重启桌面版或 IDE。
为什么不要同时在多个地方乱改配置。

下一篇看：配置后怎么验证当前用的是哪个模型。