Reinventing.AI
AI Agent InsightsBy Reinventing.AI
OpenClaw Guides

Setting Up Heartbeats

Make OpenClaw proactive. Heartbeats allow your AI assistant to check email, calendar, and notifications automatically—even when you're not actively using it.

What Are Heartbeats?

A heartbeat is OpenClaw's way of "checking in" periodically. Every 30 minutes (by default), OpenClaw runs through a checklist you define and can alert you to important events or take actions on your behalf.

Why Heartbeats Matter

Most AI assistants are reactive—they only respond when you ask. OpenClaw with heartbeats is proactive—it works for you in the background.

Example: Instead of checking your email yourself, OpenClaw can scan your inbox every 30 minutes and alert you only to urgent messages.

How Heartbeats Work

Every heartbeat interval, OpenClaw:

  1. Reads HEARTBEAT.md in your workspace
  2. Executes the tasks listed in that file
  3. Either reports findings or sends HEARTBEAT_OK if nothing needs attention
  4. Logs the results in your memory files

Setting Up Your First Heartbeat

Step 1: Enable Heartbeats

By default, heartbeats are enabled. Check your config at ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m"
      }
    }
  }
}

You can adjust the interval: 15m, 1h, etc. Or disable with "every": "0m".

Step 2: Create HEARTBEAT.md

In your workspace directory (~/.openclaw/workspace), create or edit HEARTBEAT.md:

# HEARTBEAT.md

## Tasks to check every heartbeat:

1. **Check unread emails** - Look for urgent messages from VIPs
2. **Check calendar** - Alert if meeting in next 2 hours
3. **Weather check** - If rain forecasted, remind to bring umbrella

## Notes:
- Only alert if something needs attention
- If all clear, respond with HEARTBEAT_OK
- Keep checks lightweight to minimize API usage

Step 3: Test Your Heartbeat

You can trigger a heartbeat manually to test:

openclaw agent --message "Run heartbeat check"

Or just wait for the next scheduled heartbeat. Check your logs to see when it runs:

openclaw logs --follow

Practical Heartbeat Examples

💼 Work Assistant

# Check inbox for urgent emails
# Check calendar for meetings in next 3 hours
# Check GitHub for mentions or PR reviews
# Respond HEARTBEAT_OK if nothing urgent

🏠 Home Automation

# Check weather forecast
# If temperature drops below 15°C tonight, remind to close windows
# Check if any package deliveries expected today
# Respond HEARTBEAT_OK if all normal

📊 Business Monitoring

# Check website uptime (ping main domain)
# Check for new customer support tickets
# Check social media mentions
# Alert if any metric is abnormal, otherwise HEARTBEAT_OK

Advanced: Tracking State

To avoid duplicate alerts, OpenClaw can track state. Create memory/heartbeat-state.json:

{
  "lastChecks": {
    "email": 1707552000,
    "calendar": 1707552000,
    "weather": null
  },
  "lastAlerts": {
    "urgentEmail": null,
    "upcomingMeeting": null
  }
}

Your HEARTBEAT.md can reference this file to track timestamps and avoid repeated alerts.

Heartbeat Best Practices

⚡ Keep It Lightweight

Each heartbeat uses API credits. Focus on 3-5 key checks that actually matter. Avoid redundant or slow operations.

🔕 Respect Quiet Hours

Add time checks to your HEARTBEAT.md. Example: "Don't send alerts between 11 PM and 7 AM unless critical."

📝 Use HEARTBEAT_OK

If nothing needs attention, respond with exactly HEARTBEAT_OK. This keeps logs clean and minimizes noise.

🔄 Rotate Checks

Not every check needs to run every heartbeat. Use state tracking to rotate between different tasks throughout the day.

Heartbeats vs Cron Jobs

💓 Heartbeats

  • Regular interval (every 30m, 1h, etc.)
  • Multiple checks in one execution
  • Context-aware (can read recent messages)
  • Responds in main session

⏰ Cron Jobs

  • Precise timing (9 AM every Monday)
  • Single isolated task
  • Runs in isolated session
  • Can deliver to specific channels

Use heartbeats for ongoing monitoring. Use cron jobs for scheduled one-off tasks.

Pro Tip: Combining Both

Many users run heartbeats for regular monitoring (email, calendar) and use cron jobs for specific scheduled tasks (weekly reports, backups, reminders). Together, they make OpenClaw truly autonomous.

Troubleshooting

Heartbeats Not Running

Check that:

  • Gateway is running: openclaw status
  • Heartbeat interval is not set to 0m
  • Check logs for errors: openclaw logs

Too Many Alerts

Use state tracking to avoid duplicate alerts. Update heartbeat-state.json with timestamps when alerts are sent.

High API Costs

Reduce heartbeat frequency or limit checks. Every heartbeat call uses tokens. Consider using a cheaper model for heartbeats.

Next Steps