【Bug已解决】codex: cannot find project root / AGENTS.md not loaded — CodeX CLI 无法识别项目根目录解决方案1. 问题描述CodeX CLI 无法识别项目根目录导致 AGENTS.md 或项目配置未加载# AGENTS.md 未加载 $ codex # CodeX 不知道项目规则和上下文 # AGENTS.md 存在但未被读取 # 或项目根目录识别错误 $ cd /project/src/components $ codex # CodeX 把 /project/src/components 当作根目录 # 而非 /project # 或配置文件未找到 $ codex Warning: No config found # .codex/config.json 存在但未被加载 # 或 .codexignore 不生效 $ codex # .codexignore 存在但被忽略的文件仍被读取这个问题在以下场景中特别常见项目缺少标记文件.git、package.json在子目录中启动 CodeXAGENTS.md 不在根目录嵌套项目结构符号链接导致路径解析问题多个 .codex/ 目录2. 原因分析核心原理拆解CodeX 启动 → 向上搜索项目根目录 ↓ 找不到标记文件/在子目录启动/路径解析问题 ↓ 项目配置未加载原因分类表原因分类具体表现占比子目录启动不在根目录约 40%无标记文件缺 .git/package.json约 25%AGENTS.md 位置不在根目录约 15%嵌套项目多个 .codex/约 10%符号链接路径解析约 5%配置路径.codex/ 不在根约 5%3. 解决方案方案一在项目根目录启动最推荐# 步骤 1确保在项目根目录 cd /project # 而非 /project/src/components codex # 步骤 2或使用 --working-dir codex --working-dir /project # 步骤 3验证 pwd ls -la AGENTS.md .codex/ codex --debug 21 | grep -i root\|agents\|config方案二添加标记文件# 步骤 1确保有 .git 或 package.json # 如果没有 Git git init # 或如果没有 package.json npm init -y # 步骤 2CodeX 通过这些文件识别项目根目录 # 步骤 3验证 ls -la .git package.json codex方案三正确放置 AGENTS.md# 步骤 1AGENTS.md 必须在项目根目录 mv src/AGENTS.md ./AGENTS.md mv docs/AGENTS.md ./AGENTS.md # 步骤 2验证位置 ls -la AGENTS.md # 应在项目根目录 # 步骤 3验证加载 codex --debug 21 | grep -i agents # 步骤 4或使用 --agents-file codex --agents-file /project/AGENTS.md方案四正确放置 .codex/ 目录# 步骤 1.codex/ 必须在项目根目录 mv src/.codex/ ./.codex/ # 步骤 2验证 ls -la .codex/config.json # 步骤 3或使用 --config-file codex --config-file /project/.codex/config.json # 步骤 4验证加载 codex --debug 21 | grep -i config方案五处理嵌套项目# 步骤 1如果有嵌套项目 # /project/.codex/ 和 /project/sub/.codex/ # CodeX 使用最近的 .codex/ # 步骤 2在正确的项目启动 cd /project # 使用 /project/.codex/ codex # 或 cd /project/sub # 使用 /project/sub/.codex/ codex # 步骤 3删除不需要的嵌套配置 rm -rf /project/sub/.codex/方案六使用 --working-dir# 步骤 1指定工作目录 codex --working-dir /project # 步骤 2或在 Shell 中设置 export CODEX_WORKING_DIR/project codex # 步骤 3验证 codex --debug 21 | grep -i working\|root ls -la /project/AGENTS.md /project/.codex/4. 各方案对比总结方案适用场景推荐指数难度方案一根目录启动通用⭐⭐⭐⭐⭐低方案二标记文件无标记⭐⭐⭐⭐⭐低方案三AGENTS.md位置错误⭐⭐⭐⭐⭐低方案四.codex/ 位置配置位置⭐⭐⭐⭐⭐低方案五嵌套项目多项目⭐⭐⭐⭐低方案六--working-dir指定目录⭐⭐⭐⭐⭐低5. 常见问题 FAQ5.1 CodeX 如何识别项目根目录向上搜索标记文件.git、package.json、.codex/ 等找到的第一个就是根目录。5.2 AGENTS.md 应该放在哪里项目根目录。CodeX 在根目录查找 AGENTS.md。5.3 在子目录启动会怎样CodeX 可能将子目录作为根目录导致无法找到根目录的配置和 AGENTS.md。5.4 如何指定工作目录codex --working-dir /project # 或 export CODEX_WORKING_DIR/project5.5 没有 .git 会被识别吗可能不会。建议git init或添加package.json作为标记文件。5.6 嵌套项目如何处理在正确的项目根目录启动删除不需要的嵌套 .codex/ 目录。5.7 AGENTS.md 是什么项目指令文件告诉 CodeX 项目的规则、上下文和约定。5.8 如何验证配置已加载codex --debug 21 | grep -i config\|agents\|root5.9 .codexignore 应该放在哪里项目根目录。CodeX 在根目录查找 .codexignore。5.10 排查清单速查表□ 1. 在项目根目录启动 codex □ 2. 或使用 --working-dir /project □ 3. 确保 .git 或 package.json 存在 □ 4. AGENTS.md 放在根目录 □ 5. .codex/ 放在根目录 □ 6. .codexignore 放在根目录 □ 7. codex --debug 验证加载 □ 8. 删除不需要的嵌套 .codex/ □ 9. 符号链接: 使用 realpath □ 10. CODEX_WORKING_DIR 环境变量6. 总结根本原因无法识别根目录最常见原因是在子目录启动40%和缺少标记文件25%最佳实践在项目根目录启动 CodeX或使用--working-dir /project指定标记文件确保有.git或package.jsonCodeX 通过这些识别项目根目录文件位置AGENTS.md、.codex/、.codexignore 都应放在项目根目录最佳实践建议使用codex --debug 21 | grep -i root\|agents\|config验证项目根目录和配置加载故障排查流程图flowchart TD A[无法识别根目录] -- B[在项目根目录启动] B -- C[cd /project codex] C -- D{AGENTS.md 加载?} D --|是| E[✅ 问题解决] D --|否| F[检查标记文件] F -- G{有 .git 或 package.json?} G --|否| H[git init 或 npm init] G --|是| I[检查 AGENTS.md 位置] H -- j[codex 验证] I -- K{AGENTS.md 在根目录?} K --|否| L[mv 到根目录] K --|是| M[检查 .codex/ 位置] L -- j M -- N{.codex/ 在根目录?} N --|否| O[mv 到根目录] N --|是| P[codex --debug 验证] O -- j j -- Q{成功?} Q --|是| E Q --|否| R[使用 --working-dir] P -- Q R -- S[codex --working-dir /project] S -- E E -- T[确保每次在根目录启动] T -- U[✅ 长期方案]