DEV Community

Hex
Hex

Posted on • Originally published at openclawplaybook.ai

OpenClaw Heartbeats: Making Your AI Agent Proactive Instead of Reactive

#agents #ai #automation #productivity

Most AI agents are reactive. You ask, they answer. You forget to ask, nothing happens. That's fine for a chatbot — it's not fine for an employee.

A real employee doesn't wait for you to ask "did anything go wrong?" They check. They surface issues. They follow up. OpenClaw's heartbeat system is what gives your AI agent that same proactive behavior — without you having to babysit it.

What Is a Heartbeat?

A heartbeat is a periodic agent turn that OpenClaw's Gateway triggers on a schedule. Every N minutes (default: 30), the Gateway wakes up the agent and says: "check on things." The agent reads your HEARTBEAT.md checklist, looks at whatever you've told it to monitor, and either stays silent or surfaces something that needs attention.

If nothing needs attention, the agent replies HEARTBEAT_OK. OpenClaw treats that as a silent acknowledgment — no message is delivered, no noise. The moment something does need attention, you get an alert.

That's the key insight: heartbeats are mostly silent. You only hear from the agent when it has something to say. The rest of the time it's quietly doing its job in the background.

How It Works Under the Hood

Heartbeats run as full agent turns inside the main session. The Gateway sends a message to the agent — the default prompt is:

Read HEARTBEAT.md if it exists (workspace context). Follow it strictly.
Do not infer or repeat old tasks from prior chats.
If nothing needs attention, reply HEARTBEAT_OK.
Enter fullscreen mode Exit fullscreen mode

The agent has full context: your HEARTBEAT.md checklist, the main session history, and access to all its tools. It can read files, run searches, check APIs, inspect logs — whatever your checklist tells it to do.

The result is either:

  • HEARTBEAT_OK — stripped and discarded. No delivery, no noise.
  • An alert message — delivered to whatever channel you've configured (Slack, Telegram, WhatsApp, Discord, etc.).

Heartbeat-only turns don't keep your session "active" — idle expiry behaves normally. This is deliberate: the system is designed to be low-overhead.

Setting Up Heartbeats

Heartbeats are on by default at a 30-minute interval. To customize, add a heartbeat block to your openclaw.json:

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "last",
        "activeHours": {
          "start": "08:00",
          "end": "22:00"
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Key fields:

  • every: interval (e.g. "15m", "1h"). Set "0m" to disable.
  • target: where to deliver alerts. Use "last" for the last active channel, or explicitly name one: "slack", "telegram", "whatsapp", "discord". Default is "none" (runs silently, no external delivery).
  • activeHours: restrict heartbeats to a time window. Outside the window, ticks are skipped. Uses your configured timezone.

The HEARTBEAT.md Checklist

This is the file that actually makes heartbeats useful. It's a small markdown checklist that the agent reads on every heartbeat turn. Think of it as your standing instructions for what to monitor.

Example:

# Heartbeat checklist

- Check Slack DMs for anything urgent
- If a background task finished, summarize results
- Review calendar for events in the next 2 hours
- If it's been more than 8 hours since last check-in, send a brief status update
Enter fullscreen mode Exit fullscreen mode

The agent follows this list on every tick. If the inbox is clear and nothing is pending, it replies HEARTBEAT_OK and you never hear about it. If something is urgent, you get a message.

Keep this file small. It's injected into every heartbeat turn — the bigger it gets, the more tokens every tick costs. Short, stable, actionable items only.

Updating HEARTBEAT.md

It's just a file in your agent workspace. You can edit it yourself, or tell the agent in normal chat: "Update HEARTBEAT.md to add a daily calendar check." The agent will modify the file, and every future heartbeat will include that check automatically.

Restricting to Active Hours

You probably don't want your agent waking up and pinging you at 3am. The activeHours setting handles this:

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "slack",
        "activeHours": {
          "start": "09:00",
          "end": "22:00",
          "timezone": "America/New_York"
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Outside 9am–10pm Eastern, heartbeats are skipped entirely. The next tick inside the window runs normally. If you omit activeHours, heartbeats run 24/7.

Per-Agent Heartbeats

If you're running multiple agents, you can configure heartbeats independently per agent:

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "last"
      }
    },
    "list": [
      { "id": "main", "default": true },
      {
        "id": "ops",
        "heartbeat": {
          "every": "1h",
          "target": "telegram",
          "to": "+15551234567"
        }
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Lightweight Context Mode

By default, heartbeat turns include your full workspace bootstrap context. Enable lightContext for a leaner turn:

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "lightContext": true
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

With lightContext: true, the heartbeat turn loads only HEARTBEAT.md and skips the rest. Cheaper per tick.

Heartbeat vs Cron: Knowing When to Use Each

  • Heartbeat: periodic awareness, batched monitoring, context-aware decisions. One turn handles everything on your checklist. Smart suppression keeps it quiet when nothing needs attention.
  • Cron: precise timing, isolated runs, different model, standalone tasks. Use when you need "send report at exactly 9:00 AM" or want a clean session without main context.

The most efficient setup uses both: heartbeat for routine monitoring, cron for precisely scheduled deliveries.

Manual Wake

You can trigger an immediate heartbeat on demand from the CLI:

openclaw system event --text "Check for urgent follow-ups" --mode now
Enter fullscreen mode Exit fullscreen mode

This enqueues a system event and wakes the agent immediately, bypassing the normal schedule.

Cost Awareness

Heartbeats are full agent turns. A few things to keep in mind:

  • Keep HEARTBEAT.md tight — it's injected every single tick.
  • Use lightContext: true if the agent doesn't need full workspace context.
  • Consider a cheaper model override: "heartbeat": { "model": "anthropic/claude-haiku-3-5" }
  • Set target: "none" if you only want internal state updates.
  • Use activeHours to stop burning tokens at night.

A well-tuned heartbeat setup is surprisingly cheap. At 30-minute intervals with lightContext: true and a lean HEARTBEAT.md, you're looking at maybe a few cents per day for a genuinely proactive agent.

What This Looks Like in Practice

I run heartbeats for this entire operation — blog publishing, Slack monitoring, task follow-ups. My HEARTBEAT.md is maybe 8 lines. Every 30 minutes, the agent wakes up, reads the checklist, checks if anything needs attention, and either goes back to sleep (silently) or pings me on Slack with exactly what's needed.

99% of the time: silence. The rare time it surfaces something is exactly when it matters. That's the point.

The difference between a reactive chatbot and an actual AI employee isn't intelligence. It's initiative. Heartbeats are what give your agent that.

Related Reading

Originally published at openclawplaybook.ai. Get The OpenClaw Playbook — $9.99

Top comments (0)