Codex 配置不生效，多数不是 Codex 坏了，而是改错了文件、被更高优先级的配置覆盖，或者这项配置写在了不允许它生效的位置。按下面 7 个原因逐个排查，基本都能找到问题，每一条都对照了 OpenAI 官方的 Codex 配置文档。
先搞清楚：Codex 会从哪些地方读配置
Codex CLI 和 IDE 插件共用同一套配置层。官方文档给出的读取顺序如下，越靠前优先级越高：
- 命令行参数和
--config（-c）覆盖 - 项目配置
.codex/config.toml：从项目根目录一路到当前工作目录，离当前目录越近越优先，而且只有受信任的项目才会加载 - 用
--profile 名称选中的配置文件：~/.codex/ 名称.config.toml - 用户配置：
~/.codex/config.toml - 工作区下发的云端托管配置（登录了企业工作区时才有）
- 系统配置：Unix 上是
/etc/codex/config.toml（存在时） - 内置默认值
记住这张顺序表，下面大部分“不生效”的情况都能用它解释。
原因 1：改的不是 Codex 正在读的那个文件
Codex 的本地状态都放在 CODEX_HOME 下，默认是 ~/.codex。如果你（或某个脚本、某个中转工具）设置过 CODEX_HOME 环境变量，Codex 读的就是那个目录里的 config.toml，你改 ~/.codex/config.toml 自然没反应。
排查方法：
# macOS / Linux
echo $CODEX_HOME
# Windows PowerShell
echo $env:CODEX_HOME输出为空，说明用的是默认的 ~/.codex（Windows 上一般是 C:\Users\ 你的用户名 \.codex）。在 IDE 插件里也可以点右上角齿轮，选 Codex Settings > Open config.toml，直接打开它正在用的文件。
原因 2：被更高优先级的配置覆盖了
比如你在 ~/.codex/config.toml 里写了 model = "xxx"，但启动时带了 --model，或者项目目录里的 .codex/config.toml 也写了 model，那最终生效的是优先级更高的那个。
常见的“隐形覆盖”有三种：
- 启动别名或脚本里带了
-c/--model参数； - 仓库里有同事提交的
.codex/config.toml； - 公司电脑上有
/etc/codex/config.toml或托管配置。
进入 Codex 后输入 /status 看一下当前实际使用的模型和设置，和你的预期对不上，就顺着上面的顺序往高优先级去找。斜杠命令的用法可以看 Codex CLI 斜杠命令大全。
原因 3：项目没有被信任，项目配置被跳过
出于安全考虑，Codex 只在项目受信任时 才加载项目里的 .codex/ 目录，包括 .codex/config.toml、项目级 hooks 和 rules。如果你在首次打开项目时选了不信任，这些都会被直接跳过，但用户级和系统级配置照常加载。
所以“全局配置有效、项目配置无效”，第一件事就是确认这个项目是不是被标记成了不受信任。
原因 4：在项目配置里写了不允许的键
这是最容易踩的坑，尤其是想“给某个项目单独接第三方 API”的时候。官方文档写明，项目级 .codex/config.toml 不能覆盖跟凭据、认证、通知和遥测相关的设置，下面这些键写在项目配置里会被 忽略，并在启动时打印警告：
openai_base_url、chatgpt_base_urlmodel_provider、model_providersnotify、otelprofile、profilesapps_mcp_product_sku、experimental_realtime_ws_base_url
解决办法：把模型提供方、base URL 这类设置挪到用户级 ~/.codex/config.toml；想按场景切换，就用下面说的 profile 文件。第三方 API 的完整写法可以参考 Codex CLI 接入 API 教程。
原因 5：还在用旧的 [profiles.xxx] 写法
很多旧教程教的是在 config.toml 里写 [profiles. 名称] 表，再用 profile = "名称" 选中。官方文档说明：从 Codex 0.134.0 开始，--profile 不再读取 config.toml 里的 [profiles. 名称]，顶层的 profile = "名称" 也不再支持。
新写法是每个 profile 单独一个文件，里面直接写顶层键，不要再套 [profiles. 名称]：
# ~/.codex/deep-review.config.toml
model_reasoning_effort = "medium"
approval_policy = "on-request"使用时：
codex --profile deep-reviewprofile 文件叠加在用户配置之上，所以只需要写和基础配置不同的那几项。迁移完记得把旧的 [profiles. 名称] 表和 profile = "名称" 从 config.toml 里删掉。
原因 6：自定义模型提供方写法不对
接第三方 API 时，下面几种写法会导致配置看起来“没生效”：
- 用了保留 ID：自定义提供方不能叫
openai、ollama、lmstudio。如果只是想让内置 OpenAI 提供方走代理或中转地址，官方建议直接设openai_base_url，而不是新建[model_providers.openai]。 - 定义了提供方但没选中：写了
[model_providers.xxx]，却没有在顶层写model_provider = "xxx"。 - 环境变量没设置：
env_key = "OPENAI_API_KEY"表示从这个环境变量读密钥，终端里没设这个变量，请求就会因认证失败报错。
一个正确的结构示例（地址和变量名换成你自己的）：
model = "你的模型名"
model_provider = "proxy"
[model_providers.proxy]
name = "My proxy"
base_url = "https://proxy.example.com/v1"
env_key = "OPENAI_API_KEY"原因 7：TOML 语法问题
TOML 有一个很隐蔽的规则：写在某个 [表头] 下面的键，都属于这个表，直到出现下一个表头。所以如果你把 model = "..." 写在 [model_providers.proxy] 或 [mcp_servers.xxx] 下面，它就不再是顶层的 model，自然不会生效。
正确做法是把 model、model_provider、approval_policy、sandbox_mode 这类顶层键放在文件最上面，所有 [表头] 放在它们后面。
用命令行临时覆盖时也要注意：--config 的值按 TOML 解析，字符串要带引号，例如：
codex --config model='"你的模型名"'
codex --config sandbox_workspace_write.network_access=true常见报错与解决
启动时提示项目配置里的某个键被忽略
对照原因 4，把 model_provider、openai_base_url 等键从项目 .codex/config.toml 挪到 ~/.codex/config.toml。
设置了 approval_policy 或 sandbox_mode 但被改回去
公司管理的电脑上，管理员可能用 requirements.toml 强制限制某些取值，比如不允许 approval_policy = "never" 或 sandbox_mode = "danger-full-access"。这种情况本地配置改不了，需要找管理员。
approval_policy = "untrusted" 不生效
官方已经停止支持 "untrusted" 这个取值，可以改用 "on-request" 或 granular 写法。
MCP 服务器配置不生效
MCP 的写法和启用方式比较多，可以直接看 Codex 配置 MCP 教程。Windows 上沙箱相关的问题可以看 Codex Windows 沙箱 setup 失败解决方法。
FAQ
改完 config.toml 要重启 Codex 吗？
稳妥起见，改完后退出当前会话，重新运行 codex，再用 /status 确认。ChatGPT 桌面应用里的部分设置，官方文档也要求保存后重启应用。
CLI 和 IDE 插件的配置是分开的吗？
不是。官方文档说明，CLI 和 IDE 插件共用同一套配置层。
想让某个项目用不同模型，应该怎么写？
在项目里放 .codex/config.toml 写 model 即可（项目要受信任）；但如果要换提供方或 base URL，只能写在用户配置或 profile 文件里。
