【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）
• 在子目录中启动 CodeX
• AGENTS.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 2>&1 | grep -i "root\|agents\|config"

方案二：添加标记文件

# 步骤 1：确保有 .git 或 package.json
# 如果没有 Git
git init

# 或如果没有 package.json
npm init -y

# 步骤 2：CodeX 通过这些文件识别项目根目录

# 步骤 3：验证
ls -la .git package.json
codex

方案三：正确放置 AGENTS.md

# 步骤 1：AGENTS.md 必须在项目根目录
mv src/AGENTS.md ./AGENTS.md
mv docs/AGENTS.md ./AGENTS.md

# 步骤 2：验证位置
ls -la AGENTS.md
# 应在项目根目录

# 步骤 3：验证加载
codex --debug 2>&1 | 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 2>&1 | 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 2>&1 | grep -i "working\|root"
ls -la /project/AGENTS.md /project/.codex/

4. 各方案对比总结

方案	适用场景	推荐指数	难度
方案一：根目录启动	通用	⭐⭐⭐⭐⭐	低
方案二：标记文件	无标记	⭐⭐⭐⭐⭐	低
方案三：AGENTS.md	位置错误	⭐⭐⭐⭐⭐	低
方案四：.codex/ 位置	配置位置	⭐⭐⭐⭐⭐	低
方案五：嵌套项目	多项目	⭐⭐⭐⭐	低
方案六：--working-dir	指定目录	⭐⭐⭐⭐⭐	低

5. 常见问题 FAQ

5.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=/project

5.5 没有 .git 会被识别吗

可能不会。建议 git init 或添加 package.json 作为标记文件。

5.6 嵌套项目如何处理

在正确的项目根目录启动，删除不需要的嵌套 .codex/ 目录。

5.7 AGENTS.md 是什么

项目指令文件，告诉 CodeX 项目的规则、上下文和约定。

5.8 如何验证配置已加载

codex --debug 2>&1 | grep -i "config\|agents\|root"

5.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. 总结

1. 根本原因：无法识别根目录最常见原因是在子目录启动（40%）和缺少标记文件（25%）
2. 最佳实践：在项目根目录启动 CodeX，或使用 --working-dir /project 指定
3. 标记文件：确保有 .git 或 package.json，CodeX 通过这些识别项目根目录
4. 文件位置：AGENTS.md、.codex/、.codexignore 都应放在项目根目录
5. 最佳实践建议：使用 codex --debug 2>&1 | 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[✅ 长期方案]