提前避开 80% 的进阶坑，不用等踩了才知道怎么处理
来源：真实用户第一手实战记录 + GitHub Issues + 社区博客 + 官方文档
第一类：文件管理（5 条）
坑 1：AI 把内容放错位置，然后说”这个文件重复了可以删”
场景：AI 之前把角色定义写进了 TOOLS.md，把汇报格式写进了 HEARTBEAT.md。然后回头看 SOUL.md 和 IDENTITY.md，觉得「内容重复了」，建议删掉这两个标准文件。
🌉 桥：每个标准文件的职责是框架定义的，不是 AI 决定的。发现「好像重复」时，先问：内容放对文件了吗？是归位问题，不是删文件的问题。
坑 2：只看文件名就决定删除，没读内容
场景：看到 TOKEN-RULES.md、AGENT-MANAGER.md 等「非标准」文件名，第一反应就是删掉。但里面可能有用户一句一句提过的需求。
🌉 桥：先读文件内容 → 提取用户需求 → 放到正确标准文件 → 最后再删。
核心原则：不要删除需求，要整理需求。
坑 3：IDENTITY.md 空白，agent 跑了几周没有性格
场景：IDENTITY.md 里只有英文模板从未填写，agent 的名字、性格、说话方式全是空的，用户一直觉得「这个 agent 怎么这么呆」。
🌉 桥：安装完成后，立刻填写 IDENTITY.md——5 分钟内完成，优先级高于装 Skills。
坑 4：playbooks/ 和 skills/ 不是 OpenClaw 标准目录
场景：这两个目录看起来很「正式」，实际上不是 OpenClaw 框架定义的标准目录，放进去的内容不会被自动加载。
🌉 桥：删除这两个目录：
- 工具决策树 → 合并到
TOOLS.md - 能力描述 → 合并到
SOUL.md
坑 5：删文件后没有更新引用，agent 开始报错
场景：删除了 LESSONS-LEARNED.md 之后，AGENTS.md 里有一条「记录到 LESSONS-LEARNED.md」的交付规则没有同步更新。
🌉 桥：删除任何文件之前，先全局搜索引用：
grep -rn 'FILENAME' ~/.openclaw/workspace/把所有引用一并更新或删除。
第二类：已知 Bug（4 条）
坑 6：BOOTSTRAP.md + 空白 IDENTITY.md 共存 → 每次新会话丢失身份
场景：两者同时存在时，每次新会话 agent 都会重新触发 bootstrap 流程，丢失已经配置好的身份。
🌉 桥：两步解决：
- 完成 bootstrap 后立刻删除 BOOTSTRAP.md
- 立刻填写
IDENTITY.md，不要留空模板
坑 7：子 agent 不加载 SOUL.md / IDENTITY.md / USER.md
场景：通过 sessions_spawn 创建子 agent 后，子 agent 只加载 AGENTS.md 和 TOOLS.md，行为完全通用化。
🌉 桥：临时解法：
- 在
AGENTS.md开头手动内嵌关键角色定义 - 或把子 agent 任务的关键上下文直接包含在
sessions_spawn的task参数中
坑 8：Cron 任务污染主 session context
场景：Cron 任务没有配置 sessionTarget: isolated，后台任务的工具输出追加到主 session 历史，下次对话时 agent 需要处理大量无关数据。
🌉 桥：在所有 Cron job 配置中加上：
"sessionTarget": "isolated"让 Cron 在独立 session 里运行。
坑 9：compaction 之前”不要做”的指令消失（高危！）
场景：用户在聊天中说「检查这个收件箱，但不要做任何操作直到我确认」，agent 正常工作了几周。某次 context 窗口满了发生 compaction，这条指令被压缩摘要，从此消失。agent 开始自主操作，删了邮件。
🌉 桥：
关键指令只能写在文件里，不能只在聊天里说。
SOUL.md、AGENTS.md里的内容才能在 compaction 后幸存。
第三类：成本与性能（3 条）
坑 10：大文件全量注入，悄悄烧钱
场景：把 10KB+ 的诊断规范、源码地图等知识文件放在工作区根目录，每次 agent 启动全量注入。
🌉 桥：大文件移到 memory/ 子目录，改为按需读取。在 TOOLS.md 里写清楚触发条件。
坑 11：Session 历史越来越长，每次都全量发给 API
场景：OpenClaw 默认把每次对话的完整历史发给 API。一位用户发现每个 API call 里有 111KB 是纯粹的旧消息历史。
🌉 桥：养成 /new 习惯：
/new # 完成一个项目阶段后，开启新 session
/compact # 触发 summarization，压缩历史坑 12：Skills 越装越多，agent 越来越慢
场景：每装一个 Skill，agent 就要在每次推理时考虑「这个工具是否相关」。装了 20 个 Skill 的 agent，70% 的推理 token 都在评估不相关的工具选项。
🌉 桥：Skills 最小化原则：只装当前活跃使用的 Skills，超过一周没用的立刻禁用。
第四类：系统设计（2 条）
坑 13：shared/ 目录：造了但没用起来
场景：创建了 shared/ 目录想做跨 Agent 记忆共享，但实际上没有任何 Agent 在读写它。
🌉 桥：全局配置文件已经注入所有 Agent，shared/ 完全多余。不要为了「看起来架构完整」而造出没人用的目录。
坑 14：memory/ 只增不减，变成档案馆
场景：旧日志、已完成的交接文档、过期文件……全堆在 memory/ 里没人清理。
🌉 桥：memory/ 是工作记忆，不是档案馆。
| 内容 | 处理方式 |
|---|---|
| 旧日志 | 只保留当月 |
| 有价值的知识 | 提取到 discoveries/ |
| 过期文件 | 直接删除 |
每月清理一次。
第五类：环境问题（1 条）
坑 15：Windows 路径含单引号，工具链全崩
场景：Windows 用户名或路径中含有单引号，bash shell 初始化时报：
unexpected EOF while looking for matching '🌉 桥：改用 PowerShell（.ps1）脚本。路径用 $env:USERPROFILE 或 Join-Path 拼接，绝不硬编码含特殊字符的路径。