引言

OpenClaw（小龙虾）是一个基于大模型的 AI Agent 框架，核心思路是通过 AGENTS.md 文件定义 Agent 的行为规则，再配合记忆系统让 Agent 在长周期任务中保持上下文连贯。

AGENTS.md 相当于给 Agent 写的操作手册——你在里面定义它该做什么、不该做什么、遇到什么情况走什么分支。听起来很直觉，但实际用下来，我踩了一个反复出现的坑：AGENTS.md 中的模棱两可的词语，会被记忆系统放大，最终导致 Agent 行为严重偏离预期。

这篇文章记录这个坑的具体表现、排查过程和解决方案。

问题：模棱两可的描述 + 记忆 = 误判

先说结论：AGENTS.md 里的每一个词，Agent 都会当真。如果你用了一个有多种解释的词，Agent 不会来问你”你指的是哪个意思”，它会自己挑一个——而且挑的往往不是你想要的那个。

这本身还能容忍，真正致命的是记忆系统的叠加效应。Agent 的记忆机制会把每次执行的上下文存下来，用于指导后续决策。当 Agent 第一次基于模糊规则做出了某个理解，这个理解会写入记忆，下一次执行时它就更加”确信”自己的理解是对的。

整个链条是这样的：

模糊规则 → 第一次随机理解 → 写入记忆 → 第二次基于记忆强化理解 → 越跑越偏

几轮下来，Agent 的行为可能和你最初的意图完全相反，但它自己”认为”自己严格遵守了 AGENTS.md。

实测：记忆的影响比想象中大

我做了一个对比测试。同一份 AGENTS.md，同一个任务，分别在清空记忆和保留记忆两种状态下执行：

  • 清空记忆：Agent 对模糊规则的理解每次都不太一样，但大致在合理范围内波动。
  • 保留记忆：Agent 在前两三次执行后就锁定了一个理解，之后无论怎么调整 prompt，它都坚持那个方向。

具体数据：在我的场景中，保留记忆时 Agent 的误判率从首次的约 30% 逐步上升到第五次执行时的 70% 以上。原因很简单——记忆里积累了越来越多基于错误理解的”成功经验”，Agent 越来越确信自己是对的。

这说明一个关键问题：AGENTS.md 中的模糊表述不是”偶尔出错”的问题，而是”必然漂移”的问题。记忆系统会把小偏差滚成大偏差。

典型案例：”消息”这个词

在我的项目中，AGENTS.md 里有这样一条规则：

# Before（模糊版本）
当收到消息时，先判断消息类型，再决定处理方式。
如果消息包含指令，执行对应操作。
处理完成后，发送消息通知用户。

看起来很清楚？问题是”消息”这个词在我的系统中至少有五种含义：

含义 实际指向 场景
飞书消息 channel message IM 渠道收到的用户聊天内容
系统事件 system event 内部组件触发的事件通知
用户消息 user turn 对话中用户发送的一轮输入
assistant 回复 assistant text 模型生成的回复文本
推送通知 push notification 发给用户的异步提醒

Agent 第一次执行时，把”收到消息”理解成了”收到飞书消息”，把”发送消息通知用户”理解成了”发送一条 assistant text”。这个理解写入记忆后，后续所有涉及”消息”的规则都被锁定在这两个含义上。

结果就是：当系统事件触发时，Agent 不处理（因为它”记得”消息 = 飞书消息）；需要发飞书通知用户时，Agent 只生成了一段 assistant text（因为它”记得”发送消息 = 生成回复）。

解决方案：用精确术语替代模糊词

修复方法很简单——把每个模棱两可的词替换成只有一种解释的精确术语：

# After（精确版本）
当收到飞书群聊消息时，先判断是否包含指令前缀，再决定处理方式。
如果飞书群聊消息包含 `/` 开头的指令，执行对应操作。
处理完成后，通过飞书回复通知用户执行结果。

以下是我整理的替代规则表：

模糊词 可能的精确替代
消息 飞书群聊消息 / 系统事件 / user turn / assistant text / 推送通知
发送 飞书回复 / 调用 API / 写入日志 / 触发事件
通知 飞书卡片推送 / 系统日志记录 / webhook 回调
处理 解析并执行指令 / 转发到下游服务 / 写入数据库
用户 飞书群聊发起人 / API 调用方 / 管理后台操作者

通用原则：

  1. 同一个名词在文档中只能有一种含义。 如果有多种含义，给每种含义起不同的名字。
  2. 动词要带上执行方式。 不说”发送”，说”通过飞书回复”或”调用 XX API”。
  3. 写完之后做消歧测试。 把 AGENTS.md 交给另一个人（或另一个模型实例）读，让它列出每个关键词的含义。如果列出了多种可能，说明还不够精确。
  4. 定期清理记忆中的模糊推断。 即使 AGENTS.md 改好了，历史记忆中可能还残留着旧的错误理解，需要主动清除。

总结

AGENTS.md 不是写给人看的文档，是写给 Agent 执行的规则。人类可以根据上下文消歧，Agent 不会——它只会挑一个理解然后坚持到底，记忆系统还会帮它把这个理解越强化越深。

一条经验：在 AGENTS.md 中，每个名词只能有一种含义，每个动词必须带上执行方式。 做到这一点，能避免大量因为”Agent 看起来正常运行但实际在做错误的事”导致的排查成本。