HEARTBEAT.md, Day 6 of the Free Comprehensive OpenClaw Course

How does HEARTBEAT.md actually work?

OpenClaw heartbeat.md is the file that turns your agent from a chatbot into a system. The runtime fires the agent loop on a recurring tick, the agent reads HEARTBEAT.md on every tick, and decides whether to act. The "decides whether to act" part is what makes it different from a cron job.

The flow on every tick:

1. The runtime wakes the agent.
2. The agent loads HEARTBEAT.md alongside SOUL.md, MEMORY.md, AGENTS.md.
3. The agent reads the heartbeat instructions and the current time, and decides whether anything in the file applies right now.
4. If yes, the agent acts (sends a message, calls a tool, runs a check).
5. If no, the tick is silent and costs roughly one cheap-model API call.

The "agent decides" part is what cron cannot do. A cron job runs the same script at the same time every day, no judgement. An OpenClaw agent reading HEARTBEAT.md can say "the file says morning briefing, but the user is on vacation this week, skip it". That judgement is the whole reason the heartbeat costs more than a cron tick.

What should I put in my OpenClaw HEARTBEAT.md file?

The canonical things people put in openclaw heartbeat.md:

• Morning briefing. "Each weekday at 7am local time, send a summary of today's calendar, anything urgent in email, and the top three things on the task list."
• End of day wrap. "Each weekday at 6pm, ask whether anything is unresolved that I want logged in MEMORY.md."
• Inbox triage. "Every hour during business hours, scan new email and surface anything that needs a same-day reply."
• System checks. "Every six hours, check the production server is responding, the agent's own log file is not growing past 100MB, and the spending counter is under the daily cap."
• Reminders. "If MEMORY.md mentions an upcoming deadline within 48 hours, surface a reminder once a day."

The thing not to put in HEARTBEAT.md is anything that does not need agent judgement. "Run this script at 3am" is a cron job, not a heartbeat instruction. Use cron for that and keep the heartbeat for things where the agent's read of the situation matters.

Example HEARTBEAT.md files for different use cases

The morning-briefing pattern, the most common use case. Save as HEARTBEAT.md:

# HEARTBEAT.md

## Morning briefing
Each weekday at 7am America/Los_Angeles, send a single message to
Telegram with:
- Today's calendar events with times and locations
- Any email from the last 12 hours flagged as urgent
- The top three open tasks from MEMORY.md
- One sentence on weather if a calendar event is outdoors

Skip on weekends. Skip if MEMORY.md says I am on vacation.

## End of day wrap
Each weekday at 6pm, ask: "Anything from today I want logged in
MEMORY.md?" If I respond with a one-liner, append it to MEMORY.md
under the "Recent decisions" section with today's date.

## Deadline reminders
If MEMORY.md mentions a deadline within 48 hours, surface a
reminder once a day at 9am. Do not repeat within the same day.

The system-monitoring pattern, for an agent watching production:

# HEARTBEAT.md

## Health check
Every 5 minutes, GET https://yourapp.com/healthz with a 5-second
timeout. If the response is not 200 OK two times in a row, post
to #ops on Slack with the error and the time of first failure.
Do not re-alert within 30 minutes for the same incident.

## Disk and log size check
Every hour, run df -h. If any partition is over 85 percent, post
a Slack alert. Run du -sh on /var/log/openclaw, alert if over 500MB.

## Daily cost report
At 9am every day, post the previous day's API spend and the
running monthly total to #ops.

The scheduled-report pattern, for a periodic content agent:

# HEARTBEAT.md

## Weekly digest
Every Monday at 10am, scan the last week's news in MEMORY.md
under "Industry watch", produce a 200-word summary, post it to
the team Slack channel. Skip if last week had no notable items.

## Monthly review
First of the month at 9am, summarize the previous month's
key decisions, wins, and outstanding questions. Post as a
threaded message in #leadership.

How often should the OpenClaw heartbeat fire?

This is the single biggest cost lever in the whole runtime, see the openclaw cost optimization lesson for the math. Every heartbeat tick is a paid API call. The runtime defaults to 5 minutes, which is too tight for most personal agents.

The honest decision tree:

• 15 minutes is the sweet spot for a personal assistant. Catches morning briefings, inbox triage, end of day wraps. About 96 ticks a day.
• 30 minutes to 1 hour is fine for an agent whose only job is monitoring or briefings. About 24 to 48 ticks a day.
• 5 minutes or tighter only if you have a real-time use case (an alerting system, a live monitor, a trading helper). 288+ ticks a day, the bill compounds fast.
• Don't go below 1 minute. The fixed cost per tick is roughly the same whether the agent acts or not, so a 1-minute heartbeat is 5x more expensive than a 5-minute one for the same usable behavior.

The other lever is whether the heartbeat runs on the cheap tier or the smart tier. Most heartbeat decisions are routine (should the agent act now or not), so route the heartbeat to openclaw with ollama or to your provider's cheap tier. Save the smart tier for the actual work the agent does after deciding to act.

Why heartbeat instead of plain cron

The honest comparison. Cron is dead simple, free, and reliable. If your task is "run this exact script at this exact time", cron is the right tool. The advantage cron has over heartbeat is zero per-tick cost, the downside is zero judgement.

Heartbeat earns its cost by reading context the cron job cannot see. The agent knows you are on vacation because MEMORY.md says so. The agent knows the production system is already in a known incident because last hour's heartbeat logged it. The agent knows you have replied to "anything urgent today" with "no, skip" three days running, so it stops asking. None of that is possible in cron, which fires the same script with no memory.

The right rule of thumb: cron for deterministic scheduled tasks (backups, log rotation, certificate renewals), heartbeat for tasks where the right action depends on the current state of your life. Use both. They complement, they do not compete.

Tuning the tick interval over time

The first month of running an agent, watch the heartbeat log. The runtime writes one line per tick, including the agent's decision (acted, or skipped). After a week, you will see the actual ratio of "acted" to "skipped". A healthy ratio is around 1 in 10 to 1 in 20. Higher than that and your interval is probably too long, you are missing the moment things matter. Lower and your interval is too tight, you are paying for ticks that never do anything.

The second-order tuning is per-section. Some sections of HEARTBEAT.md only matter at specific times (the morning briefing only fires once a day no matter how often the heartbeat ticks). Other sections matter continuously (system monitoring). The runtime supports per-section schedules, you can write "Morning briefing: at 7am" and "Health check: every 5 minutes" and the heartbeat tick interval becomes the floor for the most-frequent section.

If your most-frequent section is "every 5 minutes", set the heartbeat tick to 5 minutes. If your most-frequent is "every hour", the tick can be 30 minutes (firing twice an hour to make sure no edge case slips). Match the tick to the work, not to a generic default.

A note on cost runaways

Before May 2026 there was a real bug in the runtime where a wedged provider connection could cause the heartbeat retry loop to fan out hundreds of paid calls in 60 seconds. I caught and patched that bug, the full write-up is at openclaw cost runaway fix. The fix is now merged into core (PR #76345). If you are on a recent OpenClaw version, the circuit breaker is in place and a wedged provider can no longer cost you more than 30 cents per incident. But understanding heartbeat cost math is still on you.

How this connects to your full agent

HEARTBEAT.md is the keystone file that makes the agent feel alive. Without it, your agent is a chatbot waiting on you. With it, the agent is a system that remembers you. The right next reads to make heartbeat actually useful: openclaw soul.md on day 7 ensures the morning briefing sounds like a person rather than a corporate report, and openclaw memory.md on day 8 gives the agent the context it needs to decide what is worth surfacing in the first place.

The other dependency is openclaw agents.md on day 9, which is where the spending caps that protect you from a runaway heartbeat actually live. Wire the heartbeat after you have agents.md in place, not before. The order matters because a heartbeat instruction that triggers a destructive tool call without the spending caps and confirmation gates from agents.md is a real foot-cannon. Get the safety rails in first, then turn the autonomy on.