HEARTBEAT.md 模板

HEARTBEAT.md 定义了 Agent 的心跳任务——按时间周期自动触发的操作。它让 Agent 具备主动执行能力，不再只是被动响应用户消息。

模板

# HEARTBEAT.md

## Schedule

### Every Morning (09:00)
- Check for new support tickets overnight
- Summarize unread messages
- Send daily briefing to admin

### Every Hour
- Monitor system health metrics
- Check for pending approvals
- Update cache if needed

### Every Day (23:00)
- Generate daily usage report
- Archive completed sessions
- Clean up temporary files

工作机制

心跳任务由网关的 Scheduler（调度器）管理：

网关调度器
    │
    ├─ 读取 HEARTBEAT.md
    ├─ 解析时间表达式
    ├─ 注册定时任务
    │
    └─ 到时触发
         │
         ├─ 创建心跳消息
         ├─ 发送给 Agent
         ├─ Agent 执行任务
         └─ 记录执行结果

心跳消息

心跳触发时，调度器会向 Agent 发送一条特殊的系统消息，包含当前时间和应执行的任务描述。

时间表达式

HEARTBEAT.md 支持多种时间表达式：

表达式	说明	示例
Every N minutes	每 N 分钟	Every 30 minutes
Every N hours	每 N 小时	Every 2 hours
Every day (HH:MM)	每天固定时间	Every day (09:00)
Every Monday (HH:MM)	每周几	Every Monday (10:00)
Cron: expression	Cron 表达式	Cron: 0 */6 * * *

实际示例

运维监控 Agent

# HEARTBEAT.md

## Schedule

### Every 5 minutes
- Check all monitored services health status
- If any service is down, alert the on-call team via send_notification

### Every Hour
- Collect performance metrics from all nodes
- Compare with baseline thresholds
- Generate alert if anomalies detected

### Every Day (08:00)
- Generate overnight incident report
- Send summary to ops-team channel

### Cron: 0 0 1 * *
- Generate monthly uptime report
- Archive last month's metrics data

销售助手 Agent

# HEARTBEAT.md

## Schedule

### Every Morning (08:30)
- Query CRM for today's follow-up tasks
- Check for leads that haven't been contacted in 7 days
- Send task list to sales team

### Every Day (17:00)
- Summarize today's sales activities
- Update pipeline statistics
- Send end-of-day report to manager

### Every Friday (16:00)
- Generate weekly sales report
- Highlight top performers and concerns
- Send to management team

配置选项

在 openclaw.config.yaml 中配置心跳行为：

agents:
  - name: monitor
    heartbeat:
      enabled: true
      timezone: 'Asia/Shanghai'    # 时区设置
      maxConcurrent: 1              # 最大并行心跳任务数
      timeout: 60000                # 单次心跳超时（毫秒）
      onFailure: 'retry'           # retry | skip | alert
      retryCount: 3

资源消耗

心跳任务会消耗 API Token。高频心跳（如每分钟）可能产生显著成本。建议根据实际需要设置合理频率。

心跳日志

# 查看心跳执行历史
openclaw heartbeat logs --agent monitor

# 查看下次心跳时间
openclaw heartbeat next --agent monitor

# 手动触发心跳
openclaw heartbeat trigger --agent monitor

最佳实践

1. 频率合理 — 根据业务需要设置频率，避免不必要的高频执行
2. 任务明确 — 每个心跳时段的任务要具体可执行
3. 容错处理 — 考虑外部服务不可用时的降级方案
4. 时区意识 — 明确配置时区，避免时间混乱
5. 成本意识 — 监控心跳任务的 Token 消耗