如果 config.toml 还没有报错，你只是要添加 STDIO / HTTP Server、配置 OAuth 或确认 codex mcp add 的写法，请先看2026 Codex MCP 配置教程；本页负责配置无法解析、加载或生效的情况。
30 秒分流：加载失败和配置不生效不是一回事
| 错误或现象 | 更可能的范围 | 第一步 |
|---|---|---|
failed to load configuration | 某个配置层无法读取、解析或验证 | 保存文件路径、行列号和下一层错误 |
TOML parse error | 引号、数组、表头、逗号或换行语法 | 只检查错误行附近和最近一次改动 |
duplicate key / duplicate table | 同一文件重复定义 | 搜索键与表头，只保留一个定义 |
unknown variant / unknown field | 旧字段、拼写、类型或版本不匹配 | 对照当前官方 Reference 与客户端版本 |
| 项目配置完全不生效 | 项目未受信任、路径或 host 不同 | 用 /debug-config 看加载层与忽略原因 |
| provider / profile 写在项目里不生效 | 项目级禁止覆盖的机器级字段 | 移到用户级配置或对应 profile |
| 只有 WSL / SSH / IDE 失败 | 运行 host、home 或 CODEX_HOME 不同 | 从实际运行侧核对路径与版本 |
把 chatgpt.localeOverride 写进 TOML 不会设置 IDE 中文界面，参见 Codex 中文界面、回答语言与编辑器设置边界。
先画清配置层级：不要只盯着一份 config.toml
OpenAI 当前 Configuration Reference 说明，用户级配置位于 ~/.codex/config.toml；受信任项目可以在仓库中放置 .codex/config.toml。profile 文件与主配置同在 CODEX_HOME，文件名形如 profile-name.config.toml，通过 --profile profile-name 选择。
| 层级 | 典型位置 | 常见误判 |
|---|---|---|
| 用户级 | ~/.codex/config.toml | 在 Windows、WSL、SSH 或容器中指向不同 home |
| 项目级 | <repo>/.codex/config.toml | 项目未受信任时不会加载 |
| Profile | $CODEX_HOME/name.config.toml | 启动参数选择了另一 profile |
| 命令行覆盖 | --model、-c key=value 等 | 脚本、快捷方式或 CI 持续覆盖文件值 |
| 组织托管要求 | requirements.toml / 管理策略 | 本地设置与管理员边界冲突 |
项目级配置有明确边界：这些字段写进去会被忽略
当前官方文档明确写出，项目级 .codex/config.toml 不能覆盖机器本地的 provider、认证、host 托管 app 请求元数据、通知、profile 选择和 telemetry 路由。当前列出的受限键包括：
openai_base_url
chatgpt_base_url
apps_mcp_product_sku
model_provider
model_providers
notify
profile
profiles
experimental_realtime_ws_base_url
otel这解释了一个常见现象：TOML 语法完全正确，项目也受信任，但自定义 provider 仍没有生效。不要继续复制同一段配置或把它改成更危险的格式，应把机器级字段放到用户级配置或选中的 profile 中。
TOML 常见错误：按行列号修，不要整份重写
| 现象 | 常见原因 | 安全修复 |
|---|---|---|
| 字符串到下一行才报错 | 引号未闭合或复制了弯引号 | 使用普通半角引号，检查前一行 |
| 数组附近报错 | 缺逗号、括号不配对或元素类型混用 | 缩小到最小数组再逐项恢复 |
| duplicate key | 同一表内重复键，或普通键与表冲突 | 全文件搜索该键和对应表头 |
| invalid type | 把布尔值写成字符串，或字段需要数组/表 | 按官方字段类型改值，不靠猜测 |
| unknown variant | 枚举值拼写、大小写或版本不支持 | 使用当前 Reference 列出的值 |
| 从 JSON 粘贴后失败 | 冒号、花括号、双引号键或数组格式不兼容 | 按 TOML 表和键值重写，不直接改扩展名 |
错误行可能只是解析器最终无法继续的位置，真正缺失的引号或括号有时在前一行。先备份，再围绕错误行查看最近改动；不要把完整配置贴到公开网站在线验证，因为里面可能包含私有 URL、环境变量名和组织信息。
用有效配置判断“谁覆盖了谁”
在支持的 Codex 交互环境中使用：
/debug-config
/status/debug-config 用来查看配置层与 requirements 诊断；/status 可帮助确认会话配置和 token 用量。若只有某个项目失败，在一个没有项目级 .codex/config.toml 的空目录做对照；若所有项目失败，再检查用户级和 profile。
- 记录当前 Codex、App 或 IDE 扩展版本。
- 保存报错路径，确认它属于 Local、WSL、SSH 还是容器。
- 查看最近是否切换 profile、脚本或配置管理工具。
- 每次只隔离一个配置块并复测。
- 恢复后再逐项加入，确认是哪一个字段触发。
不要创建 cron、LaunchAgent 或计划任务持续改写 config.toml。这种做法会覆盖人工修复，也会在版本更新后持续写入过时字段。
安全回滚：保留认证和会话，只隔离自己写的配置
- 先复制错误文件到私有备份位置
记录时间、版本和原始错误；不要把备份提交到公开仓库。
- 移除最近新增的最小区块
优先处理错误行附近，不删除整个
~/.codex。 - 在空项目做一次对照
判断是用户级、项目级还是 profile。
- 使用客户端默认值启动
确认基础加载恢复，再逐项添加需要的设置。
- 核对当前官方字段
旧博客、其他 host 和实验版字段不能代替当前 Reference。
- 保护认证材料
不要删除、上传或发送
auth.json、API Key、Cookie 与 Session。
一份可处理的配置故障报告
Codex、IDE/App 版本，Local / WSL / SSH / 容器。
文件路径、行列号、字段和下一层错误文字。
用户级、项目级、profile、命令行或托管要求。
仅保留复现所需字段，并对 URL、路径和组织信息脱敏。
空项目、默认配置、升级前后和一次单变量回滚。
不要公开 token、API Key、Cookie、Session、auth.json 内容、完整环境变量、私有 provider URL 或项目代码。
Codex config.toml 常见问题
Codex failed to load configuration 是什么意思？
表示 Codex 无法读取、解析或验证某一配置层。先保存文件路径、行列号和字段，再区分用户级、项目级、profile 或组织配置。
Codex config.toml 默认在哪里？
用户级默认位于 ~/.codex/config.toml；受信任项目可使用 .codex/config.toml；profile 文件位于 CODEX_HOME。
为什么 .codex/config.toml 写了却不生效？
项目可能未受信任，或写入了不能由项目覆盖的 provider、认证、profile、notify 与 telemetry 字段。用 /debug-config 查看来源和忽略原因。
unknown variant 或 unknown field 怎么处理？
核对客户端版本与当前官方 Configuration Reference。不要用旧博客、其他工具或实验版字段猜测替代。
duplicate key 或 duplicate table 怎么修？
在错误文件全局搜索重复键和表头，只保留一个定义；同时检查是否先把某个名称定义成普通键、后又定义为表。
可以删除整个 ~/.codex 修复配置吗？
不建议。先备份并隔离自己写的配置，不要删除认证和会话材料，也不要把整个目录交给第三方。
Codex CLI 和 IDE 扩展会共用 config.toml 吗？
同一 Codex host 上会共享；WSL、SSH、容器或另一台机器可能不是同一 host，要分别核对 home 与 CODEX_HOME。
config.toml 能写 JSON 吗？
不能。必须符合 TOML 语法及 Codex 当前字段类型，不能只把 JSON 文件改名。
配置错误是 Plus 或 Pro 套餐导致的吗？
通常不是。TOML 解析、配置层级和项目信任不会因为 Plus 或 Pro 充值而改变。
报告 Codex 配置错误要提供什么？
提供版本、host、完整错误、路径、行列号、字段、配置层和最小脱敏片段；删除所有凭证与私密数据。
来源与利益关系说明
本文由 Hi Codex 服务团队根据 OpenAI 当前 Configuration Reference、Config basics、Agent approvals & security 文档整理。团队提供独立人工充值协助，与 ChatGPT / Codex 套餐主题存在商业利益关系；与 OpenAI 不存在隶属、代理或官方授权关系。
Codex 配置字段和层级规则会随版本变化，请以当前客户端错误、有效配置和官方文档为准。本文不提供共享凭证、配置校验绕过、第三方 API 中转或自动脚本持续改写配置的方法。