AI多Agent协作系统实战（二十三）：Agent读HEARTBEAT.md不读AGENTS.md——openclaw的文件加载之谜

系列第23篇 | 当你以为写对了文件，但Agent根本不读

背景

今天下午，我花了大量时间修改AGENTS.md，期望agent能按步骤执行任务。但agent始终不按指令执行------读inbox、分析文件、做各种事情，就是不按我写的步骤来。

最后发现：agent读的是HEARTBEAT.md，根本没读AGENTS.md。

问题1：AGENTS.md写了但没用

现象

我写了详细的AGENTS.md，包含6个步骤：

1. 读取inbox JSON
2. 读取任务MD
3. 修改代码
4. 执行deploy.sh
5. 执行done.sh

但agent执行时完全不按这些步骤。它自己决定读什么文件、做什么操作。

原因

openclaw的文件加载机制：

• HEARTBEAT.md：agent每次heartbeat都会读取
• AGENTS.md：agent不一定读取（取决于openclaw配置）

我一直在修改AGENTS.md，但agent根本没读它。它读的是HEARTBEAT.md。

修复

把正确的流程写到HEARTBEAT.md中，而不是AGENTS.md。

# 小虾的HEARTBEAT.md
# 第一步：读取wakeup消息中指定的inbox文件
# 第二步：读取任务MD
# 第三步：按MD要求修改代码
# 第四步：打包部署
# 第五步：完成回复

问题2：inbox JSON没有steps字段

现象

agent读取了inbox JSON，但不知道要做什么。JSON中只有task_id和content，没有执行步骤。

原因

send_task.py生成的inbox JSON没有steps字段。agent不知道要执行什么命令。

修复

在inbox JSON中添加steps字段：

{
  "task_id": "DEV-20260724-001",
  "content": "修复im-chat.html左侧菜单缺失",
  "steps": [
    "1. 读取任务MD: cat /vol1/1000/workspace/claw-sync/task/DEV-20260724-001.md",
    "2. 修改代码",
    "3. 打包部署: bash /vol1/1000/workspace/scripts/send_Check/deploy.sh",
    "4. 完成回复: bash /vol1/1000/workspace/scripts/send_Check/done.sh main DEV-20260724-001 \"开发完成\""
  ]
}

问题3：wakeup消息没有指定文件路径

现象

agent收到wakeup消息后，扫描整个inbox目录，读取所有文件，包括旧文件。

原因

wakeup消息只说"请处理任务"，没有指定读取哪个文件。

修复

wakeup消息指定具体文件路径：

wake_agent('小虾', f'请读取文件 {inbox_file_path}，按steps字段的步骤执行。')

问题4：ws_server的task_db导入问题

现象

ws_server收到消息后，报错：cannot access local variable 'task_db'

原因

task_db在函数内部导入，但变量作用域问题导致无法访问。

修复

在文件开头导入task_db：

import task_db

问题5：清理RETEST代码引发连环语法错误

现象

清理RETEST代码后，format_report.py和auto_pipeline.py出现大量缩进错误。

原因

RETEST清理删除了for循环和if语句，但留下了孤立的代码块。

修复

逐个修复缩进错误，添加continue或pass。

问题6：自动复核没有触发

现象

小牛测试完成后，没有自动调用review.py复核。

原因

dispatch_after_test只发送通知，没有调用review.py。

修复

在dispatch_after_test中添加review.py调用：

# 测试通过→自动复核（调用review.py）
result = subprocess.run(['python3', 'review.py', task_id], 
                      capture_output=True, text=True, timeout=60)

问题7：feishu_notify通知内容不一致

现象

一个通知说"✅ 任务 xxx 完成"，另一个说"请读取文件 xxx，按steps字段的步骤执行"。

原因

两个不同的通知路径：

• done.sh→ws_notify→ws_server→飞书通知
• check_and_retry→wake_agent→openclaw agent→飞书通知

修复

统一通知格式，根据sender显示不同的内容。

问题8：报告中混入通知消息

现象

统筹报告前出现📤和✅通知消息。

原因

feishu_notify的print输出到stdout，混入了报告。

修复

将print输出到stderr：

print(f"📤 [{source}] {message[:100]}", file=sys.stderr)

经验总结

1. 文件加载机制要确认：openclaw读HEARTBEAT.md不读AGENTS.md，写错文件等于白写
2. inbox JSON要包含steps：agent需要明确的执行步骤
3. wakeup消息要指定文件路径：避免agent扫描整个目录
4. 清理代码要谨慎：删除RETEST时要检查语法完整性
5. 通知格式要统一：不同路径的通知内容要一致
6. print输出要分清楚：报告内容用stdout，调试信息用stderr
7. 自动复核要真正调用review.py：不能只发通知