【Bug已解决】codex: working directory not set correctly / Wrong project root — CodeX CLI 工作目录设置错误解决方案

1. 问题描述

CodeX CLI 的工作目录不正确，导致无法找到项目文件或配置：

# 工作目录错误
$ cd /project/src && codex
# CodeX 在 /project/src 中工作
# 找不到 /project/AGENTS.md 和 /project/.codex/config.json

# 或 --working-dir 不生效
$ codex --working-dir /project "task"
# 仍在当前目录工作，未切换到 /project

# 或相对路径解析错误
$ codex --working-dir ../ "task"
# 路径解析错误，找不到文件

# 或 Docker 中工作目录不对
$ docker run codex-env codex
# 默认在 / 或 /app，而非项目目录

这个问题在以下场景中特别常见：

• 在子目录中启动 CodeX
• --working-dir 路径错误
• Docker 默认目录不对
• 符号链接解析问题
• 相对路径解析
• 环境变量冲突

2. 原因分析

原因分类表

原因分类	具体表现	占比
子目录启动	不在根目录	约 40%
--working-dir	不生效	约 25%
Docker 默认	/ 或 /app	约 15%
相对路径	解析错误	约 10%
符号链接	realpath	约 5%
环境变量	CODEX_WORKING_DIR	约 5%

3. 解决方案

方案一：在项目根目录启动（最推荐）

# 步骤 1：切换到项目根目录
cd /project
codex "task"

# 步骤 2：验证
pwd  # 应显示 /project
ls AGENTS.md .codex/config.json  # 应存在

# 步骤 3：启动
codex --debug 2>&1 | grep -i "working\|root\|dir"

# 步骤 4：如果必须在子目录
cd /project/src
codex --working-dir /project "task"

方案二：使用 --working-dir

# 步骤 1：指定工作目录
codex --working-dir /project "task"

# 步骤 2：使用绝对路径
codex --working-dir /Users/zhubo/project "task"

# 步骤 3：验证
codex --working-dir /project --debug 2>&1 | grep -i "working\|root"

# 步骤 4：如果 --working-dir 不生效
export CODEX_WORKING_DIR=/project
codex "task"

方案三：使用环境变量

# 步骤 1：设置环境变量
export CODEX_WORKING_DIR=/project
codex "task"

# 步骤 2：永久设置
echo 'export CODEX_WORKING_DIR=/project' >> ~/.zshrc
source ~/.zshrc

# 步骤 3：或按项目设置
cd /project
export CODEX_WORKING_DIR=$(pwd)
codex "task"

# 步骤 4：验证
codex --debug 2>&1 | grep -i "working"

方案四：Docker 中设置工作目录

# 步骤 1：使用 -w 指定工作目录
docker run -w /app -v $(pwd):/app codex-env codex "task"

# 步骤 2：或 Dockerfile 中设置
# WORKDIR /app
docker run -v $(pwd):/app codex-env codex

# 步骤 3：验证
docker run -w /app -v $(pwd):/app codex-env codex --debug 2>&1 | grep -i "working"

# 步骤 4：确保配置在 /app 中
docker run -w /app -v $(pwd):/app codex-env ls /app/AGENTS.md

方案五：修复符号链接

# 步骤 1：检查是否通过符号链接访问
readlink -f /project  # 获取真实路径

# 步骤 2：使用真实路径
codex --working-dir $(readlink -f /project) "task"

# 步骤 3：或直接在真实路径启动
cd $(readlink -f /project)
codex "task"

# 步骤 4：验证
pwd
codex --debug 2>&1 | grep -i "working\|root"

方案六：检查配置加载

# 步骤 1：验证配置是否从正确目录加载
codex --debug 2>&1 | grep -i "config\|agents\|root"

# 步骤 2：如果配置未加载
ls -la AGENTS.md .codex/config.json
# 确保在工作目录中

# 步骤 3：或在配置中指定路径
cat > ~/.codex/config.json << 'EOF'
{
  "workingDirectory": "/project"
}
EOF

# 步骤 4：验证
codex --debug 2>&1 | grep -i "working\|config"

4. 各方案对比总结

方案	适用场景	推荐指数	难度
方案一：根目录	通用	⭐⭐⭐⭐⭐	低
方案二：--working-dir	指定	⭐⭐⭐⭐⭐	低
方案三：环境变量	全局	⭐⭐⭐⭐	低
方案四：Docker -w	Docker	⭐⭐⭐⭐⭐	低
方案五：符号链接	链接	⭐⭐⭐⭐	低
方案六：配置检查	验证	⭐⭐⭐⭐⭐	低

5. 常见问题 FAQ

5.1 CodeX 如何确定工作目录

1. --working-dir 参数
2. CODEX_WORKING_DIR 环境变量
3. 当前目录（pwd）

5.2 如何查看当前工作目录

codex --debug 2>&1 | grep -i "working\|root\|dir"

5.3 --working-dir 不生效

检查是否有 CODEX_WORKING_DIR 环境变量覆盖，或使用绝对路径。

5.4 Docker 中如何设置

docker run -w /app -v $(pwd):/app codex-env codex

5.5 在子目录启动有什么问题

CodeX 可能将子目录作为根目录，找不到 AGENTS.md 和 .codex/ 配置。

5.6 CODEX_WORKING_DIR 是什么

环境变量，指定 CodeX 的工作目录。

5.7 如何使用真实路径

codex --working-dir $(readlink -f /path) "task"

5.8 配置中的 workingDirectory

在 ~/.codex/config.json 中设置 "workingDirectory": "/project"。

5.9 AGENTS.md 在哪里找

在项目根目录。CodeX 从工作目录查找 AGENTS.md。

5.10 排查清单速查表

□ 1. cd /project 在根目录启动
□ 2. codex --working-dir /project
□ 3. CODEX_WORKING_DIR=/project 环境变量
□ 4. Docker: -w /app -v $(pwd):/app
□ 5. readlink -f 获取真实路径
□ 6. 使用绝对路径
□ 7. codex --debug | grep working 验证
□ 8. ls AGENTS.md 确认在根目录
□ 9. config: workingDirectory
□ 10. pwd 确认当前目录

6. 总结

1. 根本原因：工作目录错误最常见原因是在子目录启动（40%）和 --working-dir 不生效（25%）
2. 最佳实践：在项目根目录启动 CodeX，或使用 --working-dir /project 指定
3. 环境变量：export CODEX_WORKING_DIR=/project 设置全局工作目录
4. Docker 修复：使用 -w /app -v $(pwd):/app 指定容器工作目录
5. 最佳实践建议：始终在项目根目录启动，使用 codex --debug 2>&1 | grep -i working 验证

故障排查流程图

flowchart TD
    A[工作目录错误] --> B[cd /project 根目录]
    B --> C[codex --debug | grep working]
    C --> D{目录正确?}
    D -->|是| E[✅ 问题解决]
    D -->|否| F[使用 --working-dir]
    F --> G[codex --working-dir /project]
    G --> H{生效?}
    H -->|是| E
    H -->|否| I[设置环境变量]
    I --> j[export CODEX_WORKING_DIR=/project]
    j --> K{生效?}
    K -->|是| E
    K -->|否| L[检查路径]
    L --> M{是绝对路径?}
    M -->|否| N[使用绝对路径]
    M -->|是| O[检查符号链接]
    N --> G
    O --> P[readlink -f 真实路径]
    P --> G
    G --> Q{Docker?}
    Q -->|是| R[docker run -w /app]
    Q -->|否| S[检查配置加载]
    R --> T[-v $(pwd):/app]
    T --> E
    S --> U[ls AGENTS.md .codex/]
    U --> V{配置存在?}
    V -->|否| W[移到根目录]
    V -->|是| X[config: workingDirectory]
    W --> E
    X --> E
    E --> Y[长期: 始终根目录启动]
    Y --> Z[✅ 长期方案]