【Bug已解决】openclaw working directory invalid / Project root not found — OpenClaw 工作目录无效解决方案

【Bug已解决】openclaw: working directory invalid / Project root not found — OpenClaw 工作目录无效解决方案1. 问题描述OpenClaw 无法识别或访问工作目录# 工作目录无效 $ openclaw task Error: Working directory invalid Directory /project/src does not exist. # 或项目根目录未找到 $ openclaw Error: Project root not found Cannot find AGENTS.md or .openclaw/ in parent directories. # 或在子目录无法工作 $ cd src openclaw task Error: Cannot access project root Permission denied: /project # 或路径问题 $ openclaw --working-dir /wrong/path task Error: Directory not found: /wrong/path这个问题在以下场景中特别常见工作目录路径不存在在子目录中启动权限不足软链接问题--working-dir 路径错误目录被移动或删除2. 原因分析原因分类表原因分类具体表现占比子目录启动找不到根约 35%路径不存在删除/移动约 25%权限不足EACCES约 15%--working-dir 错误路径约 15%软链接问题symlink约 5%目录为空无 AGENTS.md约 5%3. 解决方案方案一在项目根目录启动最推荐# 步骤 1切换到项目根目录 cd /project openclaw task # 步骤 2不要在子目录启动 # 错误: cd /project/src openclaw # 正确: cd /project openclaw # 步骤 3检查根目录 ls /project/AGENTS.md ls /project/.openclaw/ # 步骤 4验证 openclaw --debug 21 | grep -i working\|root\|directory方案二使用 --working-dir# 步骤 1指定工作目录 openclaw --working-dir /project task # 步骤 2使用绝对路径 openclaw --working-dir /home/user/project task # 步骤 3验证目录存在 ls /project # 步骤 4验证 openclaw --debug 21 | grep -i working方案三创建缺失的文件# 步骤 1检查根目录文件 ls /project/AGENTS.md ls /project/.openclaw/config.json # 步骤 2如果缺失创建 touch /project/AGENTS.md mkdir -p /project/.openclaw cat /project/.openclaw/config.json EOF { model: claude-sonnet-4-20250514 } EOF # 步骤 3验证 python3 -m json.tool /project/.openclaw/config.json # 步骤 4测试 openclaw task方案四修复权限# 步骤 1检查权限 ls -la /project # 步骤 2修复权限 sudo chown -R $(whoami) /project chmod -R urw /project # 步骤 3验证 ls -la /project # 步骤 4测试 openclaw task方案五修复软链接# 步骤 1检查软链接 ls -la /project # 如果是 symlink: /project - /real/project # 步骤 2检查目标是否存在 readlink -f /project ls $(readlink -f /project) # 步骤 3如果目标不存在修复 ln -sfn /new/real/path /project # 步骤 4验证 openclaw task方案六检查路径有效性# 步骤 1验证路径存在 ls -d /project # 步骤 2如果不是目录 file /project # 如果显示 file 而非 directory # 步骤 3检查路径拼写 pwd ls # 步骤 4使用正确的路径 cd /correct/project openclaw task4. 各方案对比总结方案适用场景推荐指数难度方案一根目录通用⭐⭐⭐⭐⭐低方案二--working-dir指定⭐⭐⭐⭐⭐低方案三创建文件缺失⭐⭐⭐⭐⭐低方案四修复权限EACCES⭐⭐⭐⭐低方案五软链接symlink⭐⭐⭐中方案六路径检查排查⭐⭐⭐⭐⭐低5. 常见问题 FAQ5.1 工作目录是什么OpenClaw 运行的项目根目录包含 AGENTS.md 和 .openclaw/。5.2 如何指定工作目录openclaw --working-dir /project task5.3 在子目录启动有问题吗可能找不到项目根目录。建议在根目录启动。5.4 AGENTS.md 必须存在吗不是必须但推荐。帮助 OpenClaw 理解项目。5.5 如何检查权限ls -la /project sudo chown -R $(whoami) /project5.6 软链接导致问题使用readlink -f检查目标是否存在。5.7 --working-dir 路径错误使用绝对路径ls验证目录存在。5.8 项目根目录如何识别包含.openclaw/或AGENTS.md的目录。5.9 目录被删除怎么办恢复目录或指定新的工作目录。5.10 排查清单速查表□ 1. cd /project 根目录启动 □ 2. openclaw --working-dir /project □ 3. ls AGENTS.md 检查 □ 4. ls .openclaw/config.json 检查 □ 5. touch AGENTS.md 创建 □ 6. mkdir .openclaw 创建 □ 7. sudo chown -R $(whoami) 权限 □ 8. readlink -f 检查软链接 □ 9. file 检查路径类型 □ 10. openclaw --debug | grep working6. 总结根本原因工作目录无效最常见原因是子目录启动35%和路径不存在25%最佳实践在项目根目录启动cd /project openclaw task指定目录使用openclaw --working-dir /project task指定绝对路径创建文件确保 AGENTS.md 和.openclaw/config.json存在最佳实践建议使用openclaw --debug 21 | grep working验证工作目录故障排查流程图flowchart TD A[工作目录无效] -- B[cd /project 根目录] B -- C[openclaw task] C -- D{成功?} D --|是| E[✅ 问题解决] D --|否| F[使用 --working-dir] F -- G[openclaw --working-dir /project] G -- H{成功?} H --|是| E H --|否| I[检查路径存在] I -- j[ls -d /project] j -- K{目录存在?} K --|否| L[创建或修复目录] K --|是| M[检查权限] L -- C M -- N[ls -la /project] N -- O{权限正确?} O --|否| P[sudo chown -R $(whoami)] O --|是| Q[检查 AGENTS.md] P -- C Q -- R{AGENTS.md 存在?} R --|否| S[touch AGENTS.md] R --|是| T[检查软链接] S -- C T -- U[readlink -f /project] U -- V{链接有效?} V --|否| W[ln -sfn 修复] V --|是| X[创建 .openclaw/] W -- C X -- Y[mkdir .openclaw config.json] Y -- C C -- Z{成功?} Z --|是| E Z --|否| AA[检查路径拼写] AA -- AB[pwd ls 验证] AB -- C E -- AC[长期: 根目录 AGENTS.md .openclaw/] AC -- AD[✅ 长期方案]