Codex 报 failed to load configuration 时，问题通常比较直接：配置文件没有通过解析或字段校验。更难排查的是另一种情况——config.toml 语法完全正确，Codex 也能启动，但某个配置就是没有生效。
这两类故障的处理顺序不同。前者先看报错行列，后者要先确认“Codex 实际读取了哪一份配置，以及哪一层允许覆盖这个字段”。
一、先把故障分成“加载失败”和“加载后不生效”
常见错误可以先按下面的方式分流：
| 现象 | 更可能的原因 | 第一个动作 |
|---|---|---|
TOML parse error |
引号、数组、逗号或表头语法错误 | 查看报错行和前一行 |
duplicate key / duplicate table |
同一键或表重复定义 | 全文件搜索重复项 |
unknown variant / invalid type |
字段名、枚举值或类型不匹配 | 对照当前版本的官方 Reference |
| Codex 正常启动，但设置不生效 | 配置来源、profile、项目级限制或启动参数覆盖 | 查看实际配置来源 |
不要在看到第一条错误后就删除整个 ~/.codex。这样可能同时清掉仍有用的配置与认证现场，反而让问题更难复现。
二、确认运行环境中的“家目录”
用户级配置通常位于：
~/.codex/config.toml
受信任项目还可以包含仓库级配置：
项目目录/.codex/config.toml
但 ~ 不是一个跨环境固定不变的路径。在以下组合中，Codex 看到的 home 目录可能不同：
- Windows 终端与 WSL；
- 本机终端与 SSH 主机；
- 本机与容器；
- VS Code 本地窗口与 Remote / WSL Extension Host；
- 普通启动与设置了自定义
CODEX_HOME的启动脚本。
因此，“我已经修改了 config.toml”还不够。要确认修改的是当前 Codex 进程真正读取的那一份文件。
三、理解项目级配置的边界
一个容易被忽略的点是：项目级 .codex/config.toml 并不是所有字段都能覆盖。
OpenAI 当前 Configuration Reference 明确列出了不能从项目级配置覆盖的机器本地字段，包括 provider、认证、profile 选择、通知与 telemetry 路由等。相关键包括：
openai_base_url
chatgpt_base_url
model_provider
model_providers
profile
profiles
notify
otel
这类限制有明确的安全意义。仓库中的项目配置可能被多人拉取，如果它能够重定向认证或 provider，打开一个项目就可能改变机器级请求路径。
所以，当项目里的 provider 配置“完全没反应”时，不要先判断为缓存故障，也不要写定时任务反复覆盖文件。先把机器级字段放到用户级配置或相应 profile，再验证一次。
四、用对照实验定位配置来源
比起一次修改十个字段，更可靠的方法是做最小对照：
- 保留原始错误、当前工作目录和 Codex 版本；
- 在一个不含
.codex/config.toml的空目录启动 Codex； - 比较空目录与目标项目的行为；
- 如果只有目标项目失败，检查项目配置与项目信任；
- 如果所有目录都失败，检查用户级配置、profile 与启动参数；
- 一次只恢复一个字段，直到重新出现问题。
在 Codex TUI 中，可以使用 /debug-config 查看配置层与 requirements 诊断，使用 /status 核对当前会话、工作目录和相关运行状态。具体显示项可能随客户端版本变化，应以当前客户端和官方文档为准。
五、几个容易制造“假修复”的做法
1. 复制一份网上的完整 config.toml
旧教程中的字段可能已经变化；他人的 provider、profile 与路径也不属于你的环境。完整覆盖虽然可能让原错误消失，却会引入新的变量。
2. 把项目配置复制到用户目录后宣布问题解决
这只能证明字段在用户级有效，不能证明项目级应该允许覆盖。应继续核对该字段是否属于机器本地限制项。
3. 用脚本持续重写配置
cron、LaunchAgent 或计划任务会让配置在后台变化，使得“刚改好又失效”。排错期间应先暂停这类自动覆盖，保留单一可信来源。
4. 把整份配置发到公开论坛
配置中可能包含组织名称、内部地址、路径和 provider 信息。auth.json、API Key、Cookie、Session 更不应上传。公开前只保留最小复现片段，并把敏感字段替换为明确占位符。
六、一套安全回滚顺序
可以把回滚控制在最小范围：
- 私下备份自己编写的配置；
- 只隔离最近新增的最小区块；
- 在空项目中验证默认加载；
- 逐个恢复字段；
- 每次记录工作目录、profile 和启动方式；
- 不删除或公开认证文件；
- 不用定时任务掩盖配置来源问题。
这套流程的核心不是“找到一份能启动的配置”，而是确认每个字段由哪一层负责、为什么在当前环境生效。只有这样，配置从本机切换到 WSL、SSH、容器或远程 IDE 时，结果才可复现。
官方资料：
- Configuration Reference：https://developers.openai.com/codex/config-reference
- Config basics：https://developers.openai.com/codex/config-basic
本文为原创技术排错记录，不提供第三方 API 中转、共享凭证、认证绕过或来源不明的配置模板。
