The HEARTBEAT.md file is the 📝OpenClaw configuration file that manages an agent's autonomous pulse — the scheduled tasks, periodic self-reflection loops, and maintenance routines the agent runs even when no human is prompting it.

HEARTBEAT.md is what makes an OpenClaw agent feel alive between conversations. While 📝BOOTSTRAP.md defines what loads at session start and 📝SOUL.md defines how the agent behaves in conversation, HEARTBEAT.md defines what the agent does when no one is watching. Daily backups, weekly security audits, hourly cost checks, scheduled report generation — anything that should happen on a rhythm rather than on demand lives here.

How It Works

HEARTBEAT.md is structured as a set of scheduled task definitions, each describing:

When — the schedule (hourly, daily at a specific time, weekly on a specific day)
What — the action the agent takes (run a script, generate a report, check a system, post a message)
Why — the purpose, so the agent can reason about whether to run, skip, or adjust
Where output goes — log file, daily memo, notification channel, or silent

At session start, the agent reads HEARTBEAT.md to know what it should be doing on a schedule. When the heartbeat fires (via launchd, cron, or an in-process scheduler), the agent executes the scheduled task and writes the result wherever HEARTBEAT.md specifies.

Common Heartbeat Patterns

Daily memo generation — kick off a templated daily memo at a consistent time each morning
Periodic security audits — run a security-weekly.sh script on Sunday mornings and alert if anything fails
Cost monitoring — check API spend hourly and alert if thresholds are crossed
Log rotation — keep gateway and agent logs from growing unbounded
Backup commits — run git commit on the workspace daily so memory history is versioned
Inbound monitoring — periodically scan messaging channels for items that need triage

Why It Matters

Most chatbot systems are purely reactive — they wait for input. OpenClaw agents become collaborators rather than tools precisely because HEARTBEAT.md makes them proactive. The agent that wakes you up with a useful summary, catches the cost spike before you notice it, or flags the security audit failure on its own behaves like a teammate rather than a search engine.

HEARTBEAT.md is also the file that makes an agent's autonomous behavior auditable. Every scheduled task is documented in plain prose; a human can read the file and know exactly what the agent will do unsupervised. There are no hidden cron jobs or magic background processes — if it runs, it's in HEARTBEAT.md.

FAQ

What's the difference between HEARTBEAT.md and a cron file?

HEARTBEAT.md is the agent's understanding of its own schedule, written in prose. A cron file or launchd plist is the operating system's mechanism for invoking scheduled commands. The two often work together — HEARTBEAT.md describes what should happen and why; cron or launchd actually fires the events on time.

Can the agent modify its own HEARTBEAT.md?

Yes, with care. Agents can propose new scheduled tasks during conversation ("should I add a weekly check for this?"), but the human typically reviews and approves before HEARTBEAT.md is updated. Self-modifying schedules without human approval is a security risk.

What happens if a scheduled task fails?

Failure handling is part of each task's definition in HEARTBEAT.md. Common patterns: log and continue, log and notify, log and pause the schedule until human intervention. The pattern depends on the criticality of the task.

📝OpenClaw — the open-source AI assistant platform this file belongs to
📝Markdown-File Agent Definition — the design pattern HEARTBEAT.md belongs to
📝OpenClaw Memory Architecture — the temporal layer in the seven-surface memory model
📝BOOTSTRAP.md — the initialization file that loads HEARTBEAT.md
📝SOUL.md — defines the agent's conversational behavior between heartbeats
📝Security Hardening for OpenClaw — includes HEARTBEAT.md scheduled tasks for audits and monitoring