shared-config

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

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

> 前置教程：桌面版如何使用国内大模型配置

> 如果你还没有理解 config.toml 和 .env 的分工，先完成前置教程。

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

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

这些入口包括：

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

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

最重要的是用户级配置：


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


在文档里也常写成：


~/.codex/config.toml


这个文件适合放：

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

这类配置适合“我希望以后默认都这样”。
API Key 不应该直接写在公开教程、聊天、截图里。
更稳的方式是：


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


里面放：


某个变量名=真实APIKey

然后在 config.toml 里通过：


env_key = "某个变量名"


引用它。
注意：变量名必须完全一致。
项目里也可以有：


.codex/config.toml


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

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

但新手阶段先不要用。
原因是项目级配置只有在项目被信任后才会加载。你如果还没搞懂用户级配置，直接用项目级配置，排障会变复杂。
不同入口可能提供临时选择方式。
例如：

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 |
如果你是新手，按这个路线走：


先安装并登录一个入口。

2. 优先用用户级 ~/.codex/config.toml 配模型。

3. 把 API Key 放到 ~/.codex/.env。


4. 重启桌面版 or IDE 扩展。
5. 新建会话。
6. 做只读验证。
7. 成功后再进入项目实战。

不要同时改 3 个地方。
否则失败以后，你不知道到底是哪个配置生效了。
你可以直接把下面这段发给 Codex：


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


不要输出任何 API Key。

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


这段提示词适合在你已经进入项目后使用。
它的重点是让 Codex 先解释配置来源，而不是直接帮你乱改。
我在 CLI 能用，桌面版不能用，为什么
Section titled “我在 CLI 能用，桌面版不能用，为什么”
优先怀疑环境变量。
CLI 是从终端启动的，可能能读到当前终端环境变量。
桌面版是图形应用，不一定继承终端里的临时变量。
解决路线：

把 API Key 放到 ~/.codex/.env。

2. 确认 env_key 名字一致。


3. 重启桌面版。
4. 新建会话验证。

我在项目里写了 .codex/config.toml，为什么不生效
Section titled “我在项目里写了 .codex/config.toml，为什么不生效”
常见原因：


项目没有被信任。
文件路径写错。
配置项写错。

被更近目录下的 .codex/config.toml 覆盖。


用户级配置 and 项目级配置理解混乱。


新手优先把模型 provider 放到用户级配置。
不建议。
项目级配置很有用，但它适合你已经跑通用户级配置之后。

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


完成后，你应该能判断：


哪些配置适合写到用户级。
哪些配置适合写到项目级。
为什么桌面版可能读不到 PowerShell 临时环境变量。

为什么改 .env` 后要重启桌面版 or IDE。
为什么不要同时在多个地方乱改配置。

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