OpenClaw HEARTBEAT.md Guide — Automate Tasks Without Being Asked

The Basics

What is a Heartbeat?

OpenClaw wakes up on a configurable interval (default every 30 minutes) and runs the agent with HEARTBEAT.md as the task list.

The agent checks each item and either acts on it or responds with HEARTBEAT_OK (which is silently swallowed — you never see it). Only meaningful output reaches you.

⏰

Configurable Interval

How often does the agent wake up? Every 30 min? Hourly? You decide. Trade off between freshness and battery drain.

📋

Plain English Tasks

Write in natural language. "Check if I have unread emails from my boss" not API calls or scripts.

🤐

Silent Success

If nothing needs doing, the agent returns HEARTBEAT_OK and we don't bother you. Only real updates come through.

📢

Smart Notifications

You decide how to get alerted: push notification, email, Telegram, Slack, WhatsApp. The agent can use any channel.

Important Concept

The HEARTBEAT_OK Token

ℹ️

HEARTBEAT_OK is a special token: When every item in HEARTBEAT.md has nothing to do, the agent returns this token. The Gateway catches it and suppresses it so you don't get spammed with "nothing to do" messages every 30 minutes. Only items that find something important break the silence.

This means your HEARTBEAT tasks should be specific about conditions. Don't write "check email" (you get alerted every 30 min). Write "if any emails from my boss have arrived in the last hour, alert me" (you only hear about important things).

Best Practices

How to Write Heartbeat Items

Use plain English. Be specific about conditions. Include time constraints. Specify the action and how to notify.

✅ Good Heartbeat Items:

• "Check if any unread emails arrived in the last hour from high-priority contacts. If yes, send a Telegram notification."
• "If a file named URGENT.txt appears in ~/Desktop/, read it and notify me immediately."
• "Every Monday at 9am, summarize last week's completed tasks and save to ~/summaries/."
• "If a server I'm monitoring is down, alert me via email within 5 minutes."

❌ Bad Heartbeat Items:

• "Check emails" (too broad, you get alerted every 30 min)
• "Update project status" (vague, agent doesn't know when to act)
• "Run backup" (should be a scheduled task, not a heartbeat conditional)
• "Ask me if I need anything" (spammy, defeats the purpose of automation)

Copy & Customize

Complete HEARTBEAT.md Template

Start with this and adapt it to your needs:

# HEARTBEAT.md

## Every heartbeat (every 30 min)
- Check if any terminal processes I started are still running. If one has been running for more than 2 hours, alert me on Telegram.
- If any email from [VIP name] arrived since last heartbeat, alert me immediately via email.
- If a file named URGENT.txt appears in ~/Desktop/, read it and act on it immediately.

## Morning (08:00 on weekdays)
- Fetch today's calendar events, top 5 unread emails, and open GitHub PRs assigned to me. Send a briefing to my WhatsApp.

## Evening (18:00 on weekdays)
- Summarise what tasks were completed today from memory/[today].md. Save to ~/summaries/[date].md.
- Check if any high-priority GitHub issues were opened today in my repos. Alert if yes.

## Weekly (Monday 09:00)
- Check Shopify orders from the past 7 days. Compare to previous week. Send revenue summary to WhatsApp.
- Review last week's memory files and suggest updates to MEMORY.md.

## Monthly (1st of each month, 09:00)
- Generate a month-in-review report of all completed projects and save to ~/reports/.
- Review and clean up old memory files.

Configuration

How to Set the Heartbeat Interval

Control how often your agent wakes up:

{
  "heartbeat": {
    "interval": 1800,           // seconds (1800 = 30 min, 3600 = 1 hour)
    "enabled": true,
    "quiet_hours": {
      "start": "23:00",         // Don't wake up after 11pm
      "end": "07:00"            // Don't wake up before 7am
    }
  }
}

⚡
30 minutes (1800s): Frequent, responsive, good for email and chat. Drains battery faster on mobile.
⚡
1 hour (3600s): Balanced. Email still feels fresh. Less battery drain.
⚡
3 hours (10800s): Lazy. Good if you only care about critical alerts.

Real-World Patterns

Common Heartbeat Patterns

Here are patterns people use in their HEARTBEAT.md:

📧

Morning Briefing

Every weekday at 8am: calendar, top emails, open PRs. Sent to WhatsApp or email so it's waiting when you wake up.

💰

Price/Revenue Monitor

Check crypto prices, stock prices, or Shopify revenue every hour. Alert if above/below thresholds.

🔧

CI/Build Watcher

Monitor GitHub Actions, Jenkins, or other CI. If a build fails, alert you immediately with the error.

📊

Weekly Report

Every Friday at 5pm: summarize the week, what was done, metrics, plans for next week. Save or email.

Best Practices

Tips & Gotchas

🎯
Don't make items too broad If your heartbeat item is vague, the agent will always find something to do. Be specific about conditions.
🤫
Use quiet hours Set quiet_hours so the agent doesn't wake you at 3am. Defaults to 11pm-7am.
🧪
Test your HEARTBEAT.md Manually run a heartbeat to make sure it works before relying on it. Ask the agent to do a test run.
📏
Keep items under 20 More items = longer execution time = more battery drain. Keep your heartbeat lean.
⏰
Use cron-like scheduling for one-time tasks Don't put "every 30 min" tasks in heartbeat if they should only run once a day. Use cron-style conditions.
🔔
Combine with USER.md for smarter alerts Store notification preferences in USER.md (which channels, which hours) so the agent knows how to alert you.

💡

Start simple: Begin with 3-4 heartbeat items. Check email, monitor one key metric, send a morning briefing. Once that's working smoothly, add more. Heartbeat is powerful but only when it's actually useful to you.

Explore the Workspace

Related Workspace Files

HEARTBEAT.md is one of four key workspace files. Learn about the others:

👤

Your Agent Works While You Sleep