OpenClaw心跳机制失效问题分析与解决方案

1. 问题现象与初步排查

最近在使用OpenClaw的龙虾（Lobster）AI助手时，遇到了一个棘手的问题：配置好的心跳机制完全失效，飞书端没有任何反应。具体表现为：

• 按照文档要求创建了HEARTBEAT.md文件并填写了任务内容
• 预期每30分钟执行一次心跳检测并执行任务
• 实际运行中只有第一次修改配置后会执行一次，后续完全无响应

这个问题困扰了我整整两天，期间尝试了各种方法：

1. 检查HEARTBEAT.md文件权限和路径
2. 验证openclaw.json配置文件格式
3. 重启OpenClaw服务多次
4. 查看系统日志寻找错误信息

关键发现：通过日志观察到每次心跳触发时，AI助手都会返回HEARTBEAT_OK状态，但实际上后续任务并未执行。

2. 问题根源分析

经过深入排查，发现问题出在默认的prompt指令设计上。原始prompt内容为：

code复制Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.

这个指令存在两个关键缺陷：

1. "Do not infer or repeat old tasks" 这条规则导致AI认为已经执行过的任务属于"old tasks"，后续不再重复执行
2. "HEARTBEAT_OK" 的响应机制让系统误以为任务已完成，实际上是被跳过了

2.1 心跳机制工作原理

OpenClaw的心跳机制本质上是一个定时任务触发器，其工作流程如下：

1. 根据配置的间隔时间（如30分钟）触发心跳事件
2. 加载并执行预设的prompt指令
3. 根据AI的响应判断是否需要执行后续操作
4. 将结果发送到指定目标（飞书、上次会话等）

在这个流程中，prompt的设计直接影响着整个机制的可靠性。

3. 解决方案与配置调整

经过多次测试，最终确定的解决方案是修改prompt指令，新的prompt如下：

code复制Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Please do not skip tasks just because you have done them before. Strictly execute every task with every heartbeat. If nothing needs attention, reply HEARTBEAT_GET_IT

这个修改解决了两个关键问题：

1. 明确禁止跳过已执行过的任务（"do not skip tasks just because you have done them before"）
2. 更改了无任务时的响应标识（HEARTBEAT_GET_IT），避免与正常响应混淆

3.1 完整配置文件示例

以下是经过验证可用的openclaw.json配置示例：

json复制{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "feishu",
        "to": "user_123456",
        "prompt": "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Please do not skip tasks just because you have done them before. Strictly execute every task with every heartbeat. If nothing needs attention, reply HEARTBEAT_GET_IT."
      }
    }
  }
}

配置参数说明：

• every: 心跳间隔时间，支持格式如"30m"（30分钟）、"1h"（1小时）
• target: 消息发送目标，可选"feishu"（飞书）、"last"（上次会话）、"none"（不发送）
• to: 目标用户ID，可通过询问龙虾获取
• prompt: 关键指令，必须包含完整的新版提示词

4. 实操步骤与验证

4.1 配置修改步骤

1. 定位openclaw.json配置文件（通常位于~/.openclaw/目录）
2. 备份原始配置文件
3. 修改heartbeat部分的配置，特别是prompt字段
4. 保存文件并重启OpenClaw服务

4.2 HEARTBEAT.md文件规范

心跳任务文件需要遵循特定格式：

markdown复制# 心跳任务列表

## 任务1：每日数据备份
- 执行时间：每天9:00
- 命令：/backup --full

## 任务2：系统状态检查
- 执行时间：每小时
- 命令：/system check

重要提示：每个任务必须包含清晰的执行时间和命令，避免使用模糊的描述。

4.3 验证方法

1. 手动触发一次心跳测试：

   bash复制curl -X POST http://localhost:8080/api/heartbeat/trigger
   

2. 查看飞书消息是否收到预期响应
3. 检查系统日志确认任务执行情况
4. 等待下一个自动触发周期验证定时功能

5. 常见问题与排查技巧

5.1 心跳完全不触发

可能原因：

• 配置文件路径错误
• 时间间隔设置过小（如"1s"可能不被支持）
• 服务未正确加载配置

解决方案：

1. 确认配置文件路径正确
2. 将时间间隔调整为"5m"或更长测试
3. 重启服务并检查启动日志

5.2 任务执行但飞书无通知

可能原因：

• target配置错误
• 飞书用户ID不正确
• 飞书机器人权限不足

排查步骤：

1. 运行/myid命令确认用户ID
2. 检查飞书机器人是否已添加并启用
3. 测试直接发送消息验证飞书连通性

5.3 任务被重复执行

可能原因：

• HEARTBEAT.md中包含循环任务但未设置条件
• prompt指令被过度修改

解决方法：

1. 在任务中添加执行条件判断
2. 恢复为推荐的prompt模板
3. 在任务命令中加入时间戳检查

6. 高级配置与优化建议

6.1 动态任务生成

可以通过在HEARTBEAT.md中使用特殊标记实现动态任务：

markdown复制<!-- dynamic:weather -->
每天18:00发送天气预报
<!-- /dynamic:weather -->

然后在prompt中添加处理逻辑：

code复制Read HEARTBEAT.md and process any dynamic tags. Follow instructions strictly...

6.2 心跳日志分析

建议配置日志记录每次心跳的执行情况：

json复制{
  "heartbeat": {
    "log": "/var/log/openclaw_heartbeat.log",
    "level": "debug"
  }
}

6.3 性能优化

当任务较多时，可以：

1. 将长时间任务拆分为独立流程
2. 设置不同的心跳间隔
3. 使用条件判断减少不必要的执行

例如：

json复制{
  "heartbeat": {
    "every": "1h",
    "heavy_tasks": {
      "every": "24h",
      "time": "02:00"
    }
  }
}

7. 最佳实践总结

经过这次问题排查和修复，我总结了以下经验：

1. prompt设计要精准：指令中的每个词都可能影响AI行为，必须明确无歧义
2. 测试要全面：不仅要测试首次执行，还要验证重复执行场景
3. 日志是关键：详细日志能快速定位问题根源
4. 文档要同步更新：任何配置变更都要及时更新团队文档

在实际部署中，我建议：

1. 先在小范围测试新配置
2. 逐步增加任务复杂度
3. 建立监控告警机制
4. 定期review心跳任务列表

这套解决方案在我们生产环境运行稳定，已经连续正常工作超过30天，每日处理200+定时任务无遗漏。特别提醒后来者注意prompt中的关键语句"Strictly execute every task with every heartbeat"，这是保证可靠性的核心要点。