Codex config.toml 不生效？从配置路径、优先级到会话验证逐步排查

你在 config.toml 改了模型、审批设置或 MCP 配置，重新打开 Codex 却仍看到原来的行为。先确认两件事：当前进程是否加载了你编辑的文件，以及那个值是否被更高优先级的设置覆盖。 文件保存成功，只证明编辑器写入了文件。

本文以本地 Codex CLI 为例，解决 codex config.toml not working、配置路径找错和项目配置被忽略等问题。IDE 扩展可参考相同的配置层；桌面应用与远程连接还要核对实际执行主机。AGENTS.md 是任务指令文件，读取机制另见 AGENTS.md 不生效排查。

先按现象选择下一步

现象	检查起点	预期结果
改了文件，所有项目都没变化	实际配置目录、启动命令、CLI 版本	编辑的文件属于当前运行环境
用户配置有效，项目配置没变化	启动目录、项目加载状态	目标项目层出现在配置诊断中且未被跳过
只有某个启动方式不生效	--profile、-c、模型或权限启动参数	找到覆盖同一个键的来源
某些键生效，另一些没变化	TOML 所属表、键名、版本支持	键放在正确层级且当前版本支持
改了文件，旧对话仍显示原值	当前会话与新会话分别验证	新会话读到预期配置，实际状态相符
提示设置被策略禁止	管理要求与允许值	由管理员确认约束，不靠放宽全部权限修复

每次只检查一个发生变化的键。模型、审批与网络同时修改，会让你很难知道哪一步真正解决了问题。

1. 先找当前环境的配置路径

在出问题的同一个终端执行：

codex --version
codex --help

记录版本与实际启动方式。若机器上有多个安装，macOS/Linux 用 command -v codex，PowerShell 用 Get-Command codex 确认入口。然后只查看目录，不输出认证文件或带密钥的配置正文。

macOS/Linux：

pwd
printf '%s\n' "${CODEX_HOME:-$HOME/.codex}"

PowerShell：

Get-Location
if ($env:CODEX_HOME) {
  $env:CODEX_HOME
} else {
  Join-Path $HOME ".codex"
}

未自定义时，用户配置通常是 ~/.codex/config.toml；设置了 CODEX_HOME 时，要检查那个目录下的文件。项目配置是仓库内的 .codex/config.toml，两者不是同一个文件。

验证： 编辑器里的完整文件路径，与当前进程使用的配置目录一致。若不一致，先在正确文件中核对需要的设置，不要把旧目录整份复制过去。

在 WSL、容器或 SSH 主机中运行 CLI 时，也在那个环境里执行检查。Windows 用户目录和 WSL 的 Linux 用户目录不同；桌面应用打开的本地文件，也未必属于远程主机。可通过 IDE 扩展的 Codex Settings → Open config.toml 打开文件，但仍要核对完整路径。

2. 查看加载层，再核对实际会话状态

当前官方 CLI 参考提供了两个互补的诊断入口。在 Codex 会话的输入框中使用，不是在操作系统 shell 中执行：

/debug-config
/status

/debug-config 用来查看配置层顺序、是否启用及策略来源；其输出按低优先级在前的顺序展示。/status 用来检查当前模型、审批策略、可写目录等实际状态。它们不是一个能显示所有配置键的通用导出命令。

验证： 目标配置层未被跳过；你要排查的模型或权限状态符合预期。若文件已加载而状态不符，继续查同一个键的覆盖来源。

若当前版本的 / 菜单没有这些入口，先核对版本与对应官方参考，不把未确认的参数当成修复工具。支持 doctor 的版本也可先运行 codex doctor --help，再用 codex doctor --summary 检查配置加载等健康项；报告中的登录或运行环境问题不等于该配置文件没有加载。

模型自己的“我已经读了配置”不是运行时配置证明。诊断输出可能包含本机路径和策略信息，求助前应脱敏。

3. 按优先级找出谁覆盖了同一个键

官方当前列出的普通配置优先级，从高到低是：

1. CLI 参数与 -c / --config 一次性覆盖。
2. 项目 .codex/config.toml，从仓库根目录到当前目录逐层读取，靠近当前目录的层更优先；只加载受信项目层。
3. --profile 选择的 profile 文件。
4. 用户 config.toml。
5. 已下发的云端托管默认配置。
6. 系统配置，例如 Unix 上的 /etc/codex/config.toml。
7. 内置默认值。

操作： 查看本次完整启动命令、终端 alias、启动脚本与目标目录各层配置，只查发生问题的键。例如，脚本指定了 --model，就不能用用户配置里的 model 判断这次会话会选哪个模型。

如果确认某个启动参数是你自己加的覆盖，在新开会话时仅移除这个参数，其余条件保持一致；再检查 /debug-config 与 /status。

预期结果： 实际设置回到下一层的有效值。如果仍没变化，继续查项目层或 profile，别反复重写同一份用户配置。

管理要求与普通默认值是两回事。组织可限制允许的审批策略、沙箱等设置；有明确策略错误时，交给管理员核对适用要求。普通优先级表不能用来绕过管理约束。

4. 项目配置为什么被忽略？

适用现象：用户设置正常，但仓库中的 .codex/config.toml 不生效。

先确认启动目录就在目标仓库内，再查看 /debug-config 中对应项目层的加载状态。不要假设从仓库外启动、或进入了同名 worktree，也会加载你原仓库的配置。

官方说明中，标为不受信的项目会跳过项目级 .codex/ 层。若项目层因此被跳过，先审阅仓库及其中的配置、hooks 和规则。只有确认自己有权使用且信任该项目后，才按客户端正常流程设置项目信任；陌生仓库不应为了消除提示就直接信任。

验证： 从同一仓库目录新开会话后，项目层被加载，并且没有更高层覆盖你检查的键。若策略仍不允许该值，回到管理要求排查；信任项目不会取消组织限制。

5. 使用 profile 时，检查文件写法与版本

适用现象：普通启动能读到设置，使用 --profile 后不同，或旧教程中的 profile 没效果。

当前官方写法是独立文件，例如 ~/.codex/deep-review.config.toml；文件内使用普通的顶层配置键。只有这个文件存在且内容有效时，才使用：

codex --profile deep-review

官方说明明确：从 Codex 0.134.0 起，--profile 不再读取主文件中的 [profiles.deep-review]，顶层 profile = "deep-review" 选择器也不再支持。使用 CODEX_HOME 时，对应 profile 文件位于那个配置目录。

操作： 对照当前版本，把你仍需使用的旧 profile 设置整理到独立文件中，再处理旧表与旧选择器；先保留本地备份。不要把新旧两种写法混用。

验证： 新会话的诊断中有预期 profile 层。项目配置和 CLI 覆盖仍可高于 profile，因此“profile 文件被加载”不等于它的每个值最终生效。

6. TOML 能保存，不代表键放对了位置

检查报错指出的行、引号、重复键以及键所在的表。下面两个片段说明一个常见差异：

# 错误层级：这里的设置已进入 features 表
[features]
apps = true
model_reasoning_effort = "medium"

# 正确层级：顶层设置放在表之前
model_reasoning_effort = "medium"

[features]
apps = true

这只是层级示例；实际键与取值要与当前版本、所选模型的支持范围一致。TOML 语法通过，也不能证明 Codex 支持那个键或你把它放在了正确位置。

操作： 对照官方配置示例与当前版本文档，纠正报错对应的一项。不要整份粘贴示例配置覆盖自己的文件，其中可能包含你不需要的模型、服务和权限设置。

验证： 加载不再报告该错误，目标层被加载，并且目标设置的实际状态正确。若错误只发生于某个版本，记录版本差异后再决定是否按既有安装渠道更新。

最后用同一组条件确认修复

结束旧会话，在同一执行环境和仓库目录中重新启动 CLI，保持账号与其他启动参数一致。按下面顺序检查：

1. 编辑文件的路径正确。
2. 配置层被加载，优先级与覆盖来源清楚。
3. /status 中可检查的实际设置符合预期。
4. 原来的使用场景恢复正常，例如对应 MCP 的状态与工具可用性正常。

只修改一项后复验。如果“文件读到了”但原问题仍在，应继续查那项功能的状态、权限与错误阶段，而不是继续换配置路径。需要发起模型任务验证行为时，会使用相应额度；配置文件解析成功本身不能替代行为验证。

若仍失败，准备版本、执行环境、启动目录、脱敏启动命令、修改的键及值、加载层和错误文本。配置可能包含 MCP 密钥等敏感内容，不上传完整文件或认证数据。

技能被禁用或不触发时继续看 Skills 不显示、不触发排查；一般命令与依赖问题看 Codex 常见故障排查。