HEARTBEAT.md & Periodic Check-ins

+15 Mana ✨
OpenClaw Heartbeat Documentation(DOCUMENTATION)

Introduction

OpenClaw agents can autonomously check in on a schedule through a feature called Heartbeat. The agent periodically wakes up, runs through a checklist defined in a file called HEARTBEAT.md, and reports back only if something needs attention. This transforms your agent from a purely reactive assistant into a proactive monitor.

Key Concepts

  • HEARTBEAT.md: A workspace bootstrap file containing a checklist of tasks the agent should perform on each periodic check-in. It is injected into the system prompt alongside other bootstrap files like SOUL.md and AGENTS.md.
  • Heartbeat Turn: A scheduled agent turn where the agent reads the HEARTBEAT.md checklist and processes each item. If everything is normal, the agent responds with HEARTBEAT_OK.
  • HEARTBEAT_OK Contract: The convention that an agent responds with the exact text HEARTBEAT_OK when all checklist items pass. This allows the system to suppress routine notifications and only alert on actionable findings.
  • Active Hours: A configurable time window (with timezone support) during which heartbeat check-ins occur. Outside active hours, the heartbeat is paused to save costs.
  • Target Routing: Controls where the heartbeat result is delivered — last sends to the most recent session, channel sends to a specific channel, and none suppresses all output (useful for background monitoring).

Real World Context

Imagine you have an AI assistant monitoring a production deployment. Instead of manually asking "is everything okay?" every 30 minutes, you write a HEARTBEAT.md checklist: check if the API is responding, verify disk space, confirm the last backup completed. The agent autonomously performs these checks and only pings you if something is wrong. You save time and catch issues faster than manual monitoring.

Deep Dive

The HEARTBEAT.md file lives in your agent's workspace directory and follows a simple checklist format:

markdown
# Heartbeat Checklist

- [ ] Check if the project builds without errors
- [ ] Verify no critical issues in the error log
- [ ] Confirm the API health endpoint returns 200
- [ ] Check disk usage is below 80%

If all checks pass, respond with HEARTBEAT_OK.
If any check fails, describe what failed and suggest a fix.

This markdown file is the entire instruction set for the heartbeat turn. The agent reads it, executes each check using its available tools, and responds accordingly. The beauty of this design is its simplicity — you control what the agent monitors by editing a markdown file.

The heartbeat is configured in the gateway or agent configuration:

json
{
  "heartbeat": {
    "enabled": true,
    "interval": 30,
    "activeHours": {
      "start": "09:00",
      "end": "18:00",
      "timezone": "America/New_York"
    },
    "target": "last",
    "showOk": false,
    "showAlerts": true,
    "useIndicator": true
  }
}

This configuration enables heartbeat with a 30-minute interval, restricts check-ins to business hours in the Eastern timezone, routes results to the last active session, hides routine HEARTBEAT_OK messages (since showOk is false), but shows alert messages when checks fail. The useIndicator flag shows a typing indicator during heartbeat processing.

The HEARTBEAT_OK contract is important for keeping noise low. When showOk is set to false, the system swallows the response entirely if the agent replies with HEARTBEAT_OK. The user only gets notified when something needs attention. This is the difference between a useful monitor and an annoying one.

Cost Considerations

Each heartbeat turn consumes tokens — the system prompt plus the HEARTBEAT.md content plus the agent's response. At a 30-minute interval over an 8-hour workday, that is 16 turns per day. Keep your HEARTBEAT.md checklist small and focused to minimize prompt inflation. You can also use a cheaper model for heartbeat turns by overriding the model in the heartbeat configuration.

Common Pitfalls

  1. Writing overly long HEARTBEAT.md files — Each heartbeat injects the entire file into the prompt. A long checklist means high token consumption on every turn. Keep it under 20 items.
  2. Forgetting to set active hours — Without active hours, the heartbeat runs 24/7, wasting tokens during off-hours when nobody is watching.
  3. Not using the HEARTBEAT_OK contract — If your checklist instructions do not tell the agent to respond with HEARTBEAT_OK on success, the system cannot distinguish routine check-ins from alerts.

Best Practices

  1. Keep the checklist actionable — Each item should be a concrete, verifiable check. Vague items like "make sure things are good" waste tokens without providing value.
  2. Use model overrides for cost control — Set a cheaper, faster model for heartbeat turns since they typically do not require deep reasoning.
  3. Start with a long interval and shorten it — Begin at 60 minutes, observe token usage, then tighten to 30 or 15 minutes if the cost is acceptable.

Summary

  • HEARTBEAT.md defines a checklist that the agent processes on a schedule
  • The HEARTBEAT_OK contract suppresses routine notifications, only alerting on failures
  • Active hours with timezone support prevent unnecessary check-ins outside working hours
  • Target routing controls where heartbeat results are delivered
  • Keep the checklist small and use model overrides to manage costs
✓ Completed