HEARTBEAT.md Deep Dive

+15 Mana ✨
OpenClaw Heartbeat Documentation(DOCUMENTATION)OpenClaw Agent Workspace Guide(DOCUMENTATION)

Introduction

The HEARTBEAT.md file is the central contract between you and your OpenClaw agent's periodic check-in behavior. It defines what the agent should inspect during each heartbeat cycle and how it should report its findings. Mastering this file is the foundation of reliable autonomous monitoring.

Key Concepts

  • HEARTBEAT.md: A markdown checklist file placed in the agent's workspace that defines what the agent checks during each heartbeat
  • HEARTBEAT_OK Response: The standardized response an agent returns when all checklist items pass without issues
  • Prompt Inflation: The risk of a heartbeat file growing so large that it consumes excessive tokens on every cycle
  • Checklist Items: Individual tasks the agent performs during a heartbeat, written as markdown checkboxes
  • Heartbeat Turn: A single execution cycle where the agent reads HEARTBEAT.md and processes all items

Real World Context

Consider an engineering team that manages a fleet of microservices. They configure an OpenClaw agent to monitor service health, check deployment status, and verify SSL certificate expiry every 30 minutes. Instead of writing complex monitoring scripts, they simply list these checks in a HEARTBEAT.md file. The agent reads the checklist, performs each check using its available tools, and reports back with either HEARTBEAT_OK or a detailed alert.

Deep Dive

The HEARTBEAT.md file lives in your agent's workspace directory. Here is a well-structured example:

markdown
# Heartbeat Checklist

- [ ] Check if the production API returns 200 on /health
- [ ] Verify the database connection pool is below 80% utilization
- [ ] Confirm no error rate spike above 5% in the last 30 minutes

Each line is a discrete check the agent will perform. The agent reads this file at the start of every heartbeat turn, executes each item in order, and reports the results. When every item passes, the agent responds with the standard HEARTBEAT_OK message.

The HEARTBEAT_OK response contract is critical. It signals to the system that no action is needed. Here is what a successful heartbeat cycle produces:

json
{
  "status": "HEARTBEAT_OK",
  "checks": 3,
  "passed": 3,
  "failed": 0,
  "timestamp": "2026-02-20T10:30:00Z"
}

This JSON response confirms all three checks passed. Downstream systems can parse this to update dashboards or suppress unnecessary alerts.

Keeping the checklist small is essential. Every heartbeat turn consumes API tokens because the agent must read and reason about the entire HEARTBEAT.md file. A file with 50 checklist items will cost significantly more per cycle than one with 5 items. This is known as prompt inflation.

Here is an anti-pattern that causes prompt inflation:

markdown
# Heartbeat Checklist (BAD - too many items)

- [ ] Check service-auth health
- [ ] Check service-billing health
- [ ] Check service-notifications health
- [ ] Check service-search health
- [ ] Check Redis memory usage
- [ ] Check PostgreSQL replication lag
- [ ] Verify all SSL certs have > 30 days remaining
- [ ] Check disk usage on all nodes

Instead of listing every service individually, consolidate related checks into a single item that references a monitoring tool:

markdown
# Heartbeat Checklist (GOOD - consolidated)

- [ ] Run the health-check tool against all production services
- [ ] Verify infrastructure metrics are within thresholds
- [ ] Confirm SSL certificates have > 30 days remaining

This consolidated version delegates the detailed checking to tools, keeping the heartbeat file small and token costs low.

Common Pitfalls

  • Overloading HEARTBEAT.md with too many items: Each item adds to the prompt size, increasing cost and latency on every heartbeat cycle. Consolidate related checks into single tool-backed items.
  • Using vague checklist items: Items like "Check if everything is okay" give the agent no actionable guidance. Be specific about what to check and what thresholds to use.
  • Forgetting to handle the failure path: If a check fails, the agent should report what failed and why, not just skip the HEARTBEAT_OK response.

Best Practices

  • Keep the checklist under 5-7 items to minimize prompt inflation and keep heartbeat turns fast and cheap.
  • Delegate detailed checks to tools rather than listing every individual check in the markdown file.
  • Version-control your HEARTBEAT.md alongside your agent configuration so changes are tracked and reviewable.

Hooks vs Heartbeat: If you need event-driven automation instead of time-based polling, see Building Custom Hooks for responding to session, message, and tool events.

Summary

  • HEARTBEAT.md is a markdown checklist that defines what an agent inspects during each heartbeat cycle
  • The HEARTBEAT_OK response is the standard signal that all checks passed successfully
  • Prompt inflation occurs when the checklist grows too large, increasing token costs per cycle
  • Consolidate related checks into tool-backed items to keep the file small
  • Be specific in checklist items and define clear failure reporting expectations
✓ Completed