`.codex` 文件夹放错位置：monorepo 里配置不生效的排查路线

2026-08-09

这个坑我见过好几次，症状很统一：同事在群里说「配置我提交了，你 pull 一下就行」，你 pull 了，跑起来 Codex（OpenAI Codex）该有的行为一个都没有。你去翻文件，文件确实在仓库里躺着。于是开始怀疑是不是版本不对、是不是要重启、是不是缓存。

绝大多数时候，问题比这朴素得多：那个 .codex 文件夹不在项目根，或者你启动 Codex 时打开的根本不是项目根目录——在 monorepo 里，后一种情况尤其容易发生，因为你平时就习惯 cd packages/xxx 再干活。

下面按排查文章的老套路走：现象 → 怎么确认 → 官方给的处置 → 处置后怎么验证 → 什么情况说明不是这个原因。

一、先把三个「配置」分清楚，否则越查越乱

这是我认为本篇最值钱的一段，因为一半的时间浪费在这里：大家嘴里的「Codex 配置」其实指着三个不同的东西。

第一个是 $CODEX_HOME/config.toml。 官方《Configuration Reference》页把位置写得很死：$CODEX_HOME/config.toml，默认就是 ~/.codex/config.toml。这里面放的是 model、sandbox_mode、approval_policy、mcp_servers.<id>.*、features.* 这一大堆键。注意它是用户目录下的 .codex，不是仓库里的。

第二个是项目根的 .codex 文件夹。 官方《Troubleshooting》页里有一条排查条目，症状写的是「同事的本地环境配置识别不到」，给出的原因是「配置不在 .codex 文件夹里」，处置是「确保 .codex 文件夹在项目根；monorepo 要打开正确的目录」。这条讲的是跟着仓库走、可以提交给同事共享的那份本地环境配置。

第三个是 AGENTS.md 这类指令文件。 它和上面两个又不是一回事。本机在 codex-cli 0.147.0（Windows 11）上看到 ~/.codex/ 目录里就有一个 AGENTS.md，那是全局层的自定义指令；同时官方配置参考里还有 project_doc_max_bytes（读取 AGENTS.md 的最大字节）、project_doc_fallback_filenames（AGENTS.md 不存在时的备选文件名）这两个键，说明项目侧的指令文件是被单独当一类东西处理的。

三者混起来的直接后果是：你把本该写进 ~/.codex/config.toml 的键搬到项目根的 .codex 里，然后纳闷为什么没生效；或者反过来，同事共享的那份东西你塞进了用户目录，团队里只有你一个人「配好了」。

顺带说一句边界：官方配置参考里确实还有 project_root_markers 这个键，但那一页没有给出它的取值与默认值，我们本机也没有验证过它的行为——所以别凭名字推断「它能改项目根的判定规则」，真要用请以官方文档为准。

二、怎么确认就是这个问题（可执行的判定命令）

排查顺序建议从「便宜的」往「贵的」排。

第 1 步，确认版本，别用记忆里的版本号。

codex --version

这不是走过场。本机采集那天出过一件事：开头执行这条命令得到 codex-cli 0.131.0，十几分钟后再执行同一条命令，得到的是 codex-cli 0.147.0，而 which -a codex 全程只有一个可执行文件。Codex 是有自更新能力的（配置里 check_for_update_on_startup 默认 true），所以「我昨天看到的版本」不能当依据。排查任何和行为差异有关的问题，都以当次输出为准。

第 2 步，跑一次体检，看配置到底加载没加载。

codex doctor --summary

在 codex-cli 0.147.0（Windows 11）上，这条命令的输出抬头是 Codex Doctor v0.147.0 · windows-x86_64，内容分成 Notes / Environment / Configuration / Updates / Connectivity / Background Server 几组。你要盯的是 Configuration 组，里面有 config、auth、mcp、sandbox 四行。

这一步能直接帮你二分：本机故意用 codex -c 'features=[unclosed' doctor --summary 传了一段语法不合法的 TOML，命令没有崩溃退出，doctor 照常跑完，但报出了这一行：

✗ config       config could not be loaded - Fix the reported config error, then rerun codex doctor.

结论很清楚：如果你看到的是这一行，那是配置文件本身坏了，跟 .codex 放哪儿没关系，先去修语法。如果 config 这行是正常的 loaded，配置文件层面没毛病，才轮到怀疑位置和工作目录。

第 3 步，把「工作根目录」这个变量按住。

monorepo 的坑几乎全出在这一步。CLI 有一个顶层选项 -C, --cd <DIR>，官方说明就是指定 agent 的工作根目录。与其猜自己当前在哪，不如显式指定仓库根跑一次做对照：

codex -C /path/to/repo-root

如果显式指到仓库根就正常、在子包目录里启动就不正常，那基本可以定案了：不是配置写错，是启动位置不对。

Windows 侧命令行写法是一样的，路径按你 shell 的习惯写即可；如果你在 PowerShell 或 cmd 里用反斜杠路径，注意带空格的路径要加引号。

第 4 步（可选），确认不是「另一份用户配置」在捣乱。

codex exec 有个 --ignore-user-config，作用是不加载 $CODEX_HOME/config.toml（注意：auth 仍然使用 CODEX_HOME）。用它跑一次做对照，可以判断你观察到的行为是来自用户配置还是别处。另外 -p, --profile <CONFIG_PROFILE_V2> 会把 $CODEX_HOME/<name>.config.toml 叠加到基础用户配置之上——如果你或者团队用了 profile，那又多了一层，排查时先把它摘掉。

三、官方给出的处置

《Troubleshooting》页对这个症状给的做法只有两句，但两句都得照做：

确保 .codex 文件夹在项目根。 不是子包根，不是你打开的那个目录，是项目根。
monorepo 要打开正确的目录。

第二句在 CLI 侧的落地方式就是上面的 -C, --cd <DIR>；桌面应用侧，官方文档给的做法是打开一个文件夹后，ChatGPT 会使用你选定位置里的文件与上下文——所以「选哪个位置」在那边同样是决定性的（桌面应用我们没有实测，这里是官方文档口径）。

这里要老实交代一个边界：官方 Troubleshooting 页上的条目大多数是围绕桌面应用的界面操作写的，这一条没有明确限定使用面，我们本机也没有在 CLI 上验证过它——我们这次采集一次模型对话请求都没发过，只跑了只读命令。所以这两句请按官方口径理解，不要当成我们的实测结论。

还有一个跟 monorepo 高度相关的连带情况：worktree。官方对「代码在 worktree 上跑不起来」给出的原因是「worktree 是另一个目录、继承了 Git 文件，缺依赖」，处置是通过本地环境跑初始化脚本，或者用 .worktreeinclude 把被忽略的文件纳入进来。把这条挪到本篇的语境：如果你团队里那个 .codex 文件夹（或它下面某些文件）被 .gitignore 忽略了，那在 worktree 里它就是不存在的，你在 worktree 里怎么查都查不出问题——因为文件根本没过去。

四、处置后怎么验证

改完别急着说「好了」，按下面三处回看：

再跑一次 codex doctor --summary，确认 Configuration 组的 config 行是加载成功的状态，mcp、sandbox 两行也顺手扫一眼。本机在 codex-cli 0.147.0（Windows 11）上，sandbox 那行显示的是 restricted fs + restricted network · approval OnRequest 这种形式，mcp 行会告诉你有几个 server、几个被禁用——如果你共享的配置里带 MCP server，这一行就是最快的验收点。doctor 结尾还有一行统计，形如 17 ok · 1 idle · 1 notes · 0 warn · 0 fail，先看有没有 fail。
如果涉及 MCP，用 codex mcp list 对一遍。 在 codex-cli 0.147.0（Windows 11）上，这条命令的表头是 Name | Command | Args | Env | Cwd | Status | Auth，而且 Env 列里的环境变量值会被打成 *****、只显示键名——自带脱敏，贴给同事对照比较放心。特别注意 Cwd 这一列，monorepo 里 server 的工作目录对不对，一眼就能看出来。
如果涉及特性开关，用 codex features list 看生效值。 它输出特性名、所处阶段、当前生效值三列。这里有个容易误判的点：在 codex-cli 0.147.0（Windows 11）上观测到阶段一共五种（stable、under development、experimental、deprecated、removed），而 removed 阶段的特性仍然会出现在列表里，并且有的 removed 项生效值还是 true。所以看到 removed 别急着下结论说「这功能没了」。

另外，--strict-config 这个选项会在 config.toml 出现本版本不认识的字段时直接报错退出，听上去像是个拼写检查神器。但本机实测它有边界：codex -c model_reasoning_effortt=high --strict-config exec --help 正常打印了 help，没有报未知字段错误。说明校验发生在真正加载配置去跑会话的时候，--help 这类不进入会话的路径不触发。别把它当成「任何情况下都能拦住拼写错误」的护栏。

五、什么情况说明不是这个原因

一条道走到黑最费时间，下面几种情况请立刻换方向：

doctor 报了 ✗ config could not be loaded：配置文件语法坏了，跟位置无关，先修文件。
你想生效的是 model、sandbox_mode、approval_policy、mcp_servers.* 这类键：官方《Configuration Reference》给的位置是 $CODEX_HOME/config.toml（默认 ~/.codex/config.toml）。把它们搬进仓库里的 .codex 文件夹再怎么摆位置也解决不了问题，方向从一开始就错了。
「CLI 上有、桌面应用上没有」：官方排查页对这个症状给的原因是两个面的 Codex 版本不同，查法是分别看版本——CLI 用 codex --version，macOS 上的桌面应用用 /Applications/Codex.app/Contents/Resources/codex --version。这属于版本口径问题，不是配置位置问题。
codex login status 不是登录状态：本机在 codex-cli 0.147.0（Windows 11）上执行它输出一行 Logged in using ChatGPT。如果你这边输出不是登录状态，那先解决认证，别在配置目录上耗着。
你在 worktree 里：先确认那个文件夹是不是根本没被带过去（见上一节 .worktreeinclude）。
不是「不生效」而是「行为和预期不同」：那更可能是键的语义问题。举个真实容易理解反的例子，shell_environment_policy.ignore_default_excludes 默认 true，含义是保留（不是排除）含 KEY、SECRET、TOKEN 的变量——名字读起来跟实际效果是拧着的。这类问题查目录位置永远查不出来。

最后一句实操建议：团队里把这件事写进 README 一行就够了——「.codex 在仓库根，用 Codex 时请从仓库根打开/启动」。比事后一个个人排查便宜太多。