How much do heartbeats cost in API tokens?

A heartbeat that returns HEARTBEAT_OK uses minimal tokens (under 1,000). Active heartbeats that check email or calendar use more. Keep HEARTBEAT.md small and use cron jobs for heavy tasks to optimize costs.

What's the difference between heartbeats and cron jobs?

Heartbeats run in the main session with conversational context and can batch multiple checks together. Cron jobs run in isolated sessions with exact timing. Use heartbeats for lightweight periodic checks, cron for precise schedules and heavy tasks.

Can I customize what my agent checks during heartbeats?

Yes. Edit HEARTBEAT.md in your workspace to define exactly what the agent should check. You can include email monitoring, calendar lookups, weather checks, project status, or any custom business metrics.

💓

OpenClaw Heartbeats

Heartbeats turn your AI agent from reactive to proactive. Instead of waiting for commands, your agent periodically checks email, calendar, weather, and business metrics on its own.

Proactive MonitoringToken EfficientFully Customizable

How Heartbeats Work

Every ~30 Minutes

OpenClaw sends a heartbeat poll to your agent's main session.

↓

Agent Reads HEARTBEAT.md

The agent checks your HEARTBEAT.md file for instructions on what to monitor.

↓

Check → Act or Stay Quiet

If something needs attention, the agent notifies you. Otherwise, it replies HEARTBEAT_OK silently.

The beauty of heartbeats is they run in the main session, meaning your agent has full conversational context. It knows what you discussed earlier, what projects you're working on, and can make intelligent decisions about what's worth reporting.

Configuring HEARTBEAT.md

Example HEARTBEAT.md

# HEARTBEAT.md

## Checks (rotate through these, 2-4 per heartbeat)

### Email
- Check for unread emails from important senders
- Flag anything urgent, summarize the rest

### Calendar  
- Any events in the next 2 hours?
- Remind me 30 min before meetings

### Weather
- Check if weather has changed significantly
- Alert if rain/storms expected  

### Projects
- Run git status on active repos
- Check if any CI builds failed

## Quiet Hours
- 23:00 - 08:00: HEARTBEAT_OK unless urgent
- During focused work: minimal interruptions

Keep your HEARTBEAT.md concise. Every line gets read on each heartbeat, so shorter files = fewer tokens = lower cost.

⚠️ Token Optimization

HEARTBEAT.md is injected into every heartbeat session. A 500-word file means ~750 tokens per heartbeat. At 48 heartbeats/day, that's ~36,000 tokens just for instructions — roughly $0.10-0.50/day depending on your model.

• Keep HEARTBEAT.md under 200 words
• Move heavy tasks to cron jobs instead
• Use a cheaper model for heartbeat sessions

Smart State Tracking

Your agent can track what it's already checked using a state file, avoiding redundant checks and distributing tasks across heartbeats efficiently.

heartbeat-state.json

{
  "lastChecks": {
    "email": 1741665600,
    "calendar": 1741662000,
    "weather": 1741648800,
    "projects": 1741641600
  },
  "nextPriority": "email"
}

The agent rotates through checks based on timestamps, ensuring each gets attention without doing everything on every heartbeat. This keeps costs low and responses fast.

Heartbeats vs Cron Jobs

💓 Heartbeats

• Runs in main session with full context
• Batch multiple checks together
• Timing can drift (~30 min intervals)
• Best for lightweight, rotating checks
• Can reference recent conversations

Use for: Email checks, calendar reminders, weather updates, quick project status

⏰ Cron Jobs

• Runs in isolated session
• Exact timing (9:00 AM sharp)
• Can use different model/thinking level
• Best for heavy, scheduled tasks
• Delivers output directly to channels

Use for: Nightly builds, weekly reports, scheduled deploys, one-shot reminders

Learn more about cron automation →