【Bug已解决】openclaw: AGENTS.md not found / Project context not loaded — OpenClaw 项目指令文件未加载解决方案1. 问题描述OpenClaw 无法找到或加载 AGENTS.md 项目指令文件# AGENTS.md 未找到 $ openclaw Warning: AGENTS.md not found No project context loaded. # 或 AGENTS.md 不生效 $ cat AGENTS.md # Always use TypeScript $ openclaw 创建新文件 # OpenClaw 创建了 .js 文件未遵循 AGENTS.md # 或 AGENTS.md 格式错误 $ openclaw Error: Failed to parse AGENTS.md Invalid markdown format at line 15. # 或在工作子目录找不到 $ cd src openclaw # 找不到 /project/AGENTS.md这个问题在以下场景中特别常见AGENTS.md 不在项目根目录文件名拼写错误工作目录不对AGENTS.md 格式错误文件编码问题AGENTS.md 过大被忽略2. 原因分析原因分类表原因分类具体表现占比位置不对不在根目录约 35%文件名错误agents.md/AGENTS.txt约 25%工作目录子目录启动约 15%格式错误Markdown约 10%编码问题BOM约 10%过大被忽略 5000 tokens约 5%3. 解决方案方案一在项目根目录创建 AGENTS.md最推荐# 步骤 1在项目根目录创建 cd /project cat AGENTS.md EOF # Project Instructions ## Code Style - Always use TypeScript - Use 2-space indentation - Prefer named exports ## Commands - Build: npm run build - Test: npm test - Lint: npm run lint EOF # 步骤 2验证 ls -la AGENTS.md # 步骤 3测试 openclaw 创建新文件 # 步骤 4验证加载 openclaw --debug 21 | grep -i agents\|context\|instruction方案二检查文件名# 步骤 1检查文件名 ls -la AGENTS.md # 正确: AGENTS.md大写 # 错误: agents.md, AGENTS.txt, .agents.md # 步骤 2如果文件名错误重命名 mv agents.md AGENTS.md # 或 mv AGENTS.txt AGENTS.md # 步骤 3验证 ls -la AGENTS.md # 步骤 4测试 openclaw --debug 21 | grep -i agents方案三在根目录启动# 步骤 1切换到项目根目录 cd /project openclaw task # 步骤 2不要在子目录启动 # 错误: cd /project/src openclaw # 正确: cd /project openclaw # 步骤 3或指定工作目录 openclaw --working-dir /project task # 步骤 4验证 openclaw --debug 21 | grep -i working\|root\|agents方案四修复 AGENTS.md 格式# 步骤 1检查格式 cat AGENTS.md # 步骤 2确保是有效的 Markdown # 使用 # 标题 # 使用 - 列表 # 使用 代码块 # 步骤 3修复后 cat AGENTS.md EOF # Project Instructions ## Code Style - Use TypeScript - 2-space indentation ## Commands - npm run build - npm test EOF # 步骤 4验证 openclaw --debug 21 | grep -i agents\|loaded方案五检查编码# 步骤 1检查编码 file -I AGENTS.md # 应该是: text/markdown; charsetutf-8 # 步骤 2如果有 BOM sed -i 1s/^\xEF\xBB\xBF// AGENTS.md # 步骤 3或重新创建无 BOM cat AGENTS.md EOF # Project Instructions EOF # 步骤 4验证 file -I AGENTS.md openclaw --debug 21 | grep -i agents方案六精简 AGENTS.md# 步骤 1检查大小 wc -c AGENTS.md wc -w AGENTS.md # 步骤 2如果过大 5000 tokens精简 cat AGENTS.md EOF # Project Instructions - Use TypeScript - 2-space indentation - npm run build / npm test EOF # 步骤 3验证大小 wc -c AGENTS.md # 应该 5000 字符 # 步骤 4测试 openclaw --debug 21 | grep -i agents\|context4. 各方案对比总结方案适用场景推荐指数难度方案一创建无文件⭐⭐⭐⭐⭐低方案二文件名名称错误⭐⭐⭐⭐⭐低方案三根目录路径⭐⭐⭐⭐⭐低方案四格式Markdown⭐⭐⭐⭐⭐低方案五编码BOM⭐⭐⭐⭐低方案六精简过大⭐⭐⭐⭐⭐低5. 常见问题 FAQ5.1 AGENTS.md 放哪里项目根目录/project/AGENTS.md。5.2 文件名大小写重要吗是的。使用AGENTS.md全大写。5.3 如何验证加载openclaw --debug 21 | grep -i agents\|context\|instruction5.4 AGENTS.md 支持什么格式标准 Markdown 格式。5.5 AGENTS.md 多大合适建议 500-5000 字符约 200-2000 tokens。5.6 在子目录启动找不到在项目根目录启动或使用--working-dir /project。5.7 如何检查编码file -I AGENTS.md5.8 BOM 导致问题使用sed -i 1s/^\xEF\xBB\xBF//移除 BOM。5.9 AGENTS.md 不生效检查文件名、位置、格式、编码、大小。5.10 排查清单速查表□ 1. ls AGENTS.md 确认存在 □ 2. 文件名: AGENTS.md全大写 □ 3. cd /project 根目录启动 □ 4. openclaw --debug | grep agents 验证 □ 5. cat AGENTS.md 检查内容 □ 6. 使用标准 Markdown 格式 □ 7. file -I 检查编码 □ 8. sed 移除 BOM □ 9. wc -c 检查大小 5000 □ 10. --working-dir 指定目录6. 总结根本原因AGENTS.md 未加载最常见原因是位置不对35%和文件名错误25%最佳实践在项目根目录创建AGENTS.md全大写验证方法openclaw --debug 21 | grep -i agents确认加载格式要求标准 MarkdownUTF-8 无 BOM最佳实践建议保持 AGENTS.md 精简 5000 字符在项目根目录启动 OpenClaw故障排查流程图flowchart TD A[AGENTS.md 未加载] -- B[ls AGENTS.md 检查] B -- C{文件存在?} C --|否| D[在根目录创建] C --|是| E{文件名正确?} D -- F[cat AGENTS.md EOF] F -- G[openclaw --debug | grep agents] E --|否| H[mv 改为 AGENTS.md] E --|是| I[在根目录启动] H -- G I -- j[cd /project openclaw] j -- G G -- K{加载成功?} K --|是| L[✅ 问题解决] K --|否| M[检查格式] M -- N[cat AGENTS.md] N -- O{Markdown 有效?} O --|否| P[修复格式] O --|是| Q[检查编码] P -- G Q -- R[file -I AGENTS.md] R -- S{有 BOM?} S --|是| T[sed 移除 BOM] S --|否| U[检查大小] T -- G U -- V[wc -c AGENTS.md] V -- W{过大?} W --|是| X[精简 AGENTS.md] W --|否| Y[使用 --working-dir] X -- G Y -- Z[openclaw --working-dir /project] Z -- G G -- AA{成功?} AA --|是| L AA --|否| AB[重新创建 AGENTS.md] AB -- F L -- AC[长期: 根目录 正确名 精简] AC -- AD[✅ 长期方案]