Understanding OpenClaw's Heartbeat System

OpenClaw's heartbeat system is a powerful mechanism for enabling proactive, periodic checks and background task execution without requiring constant manual intervention. Unlike one-off commands or event-driven triggers, the heartbeat operates on a recurring schedule, allowing your agent to autonomously scan for updates, perform routine maintenance, and surface important information at regular intervals.

How Heartbeat Works

At its core, the heartbeat is a scheduled agent turn that runs in the main session. By default, it executes every 30 minutes (or every hour when using certain authentication methods like Anthropic OAuth). During each run, the agent processes a specific prompt—typically instructing it to read a HEARTBEAT.md file if present—and responds accordingly.

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."

This design allows you to define a consistent set of actions the agent should take during each heartbeat cycle. If there's nothing urgent, the agent replies with HEARTBEAT_OK, which OpenClaw recognizes and suppresses to avoid cluttering your chat feed.

Configuring Heartbeat Intervals and Targets

Heartbeat behavior is controlled through configuration settings. You can adjust the frequency using the every parameter, expressed as a duration string (e.g., 30m for every 30 minutes). Setting this to 0m disables the heartbeat entirely.

You can also specify where heartbeat messages should be delivered using the target field:

• last (default): Sends to the last used external channel
• none: Runs the heartbeat but suppresses external delivery
• Specific channel names: Directs output to WhatsApp, Telegram, Discord, etc.

Additionally, you can override the recipient with the to field (e.g., a specific phone number or chat ID) and use accountId for multi-account channels like Telegram bots.

Using HEARTBEAT.md for Task Management

The optional HEARTBEAT.md file acts as your agent's recurring checklist. When present, the heartbeat prompt instructs the agent to read and follow its contents. This file should remain concise—focused on high-priority checks like unread emails, upcoming calendar events, or critical system alerts.

For example:

# Heartbeat Checklist

- Scan inbox for urgent messages
- Check calendar for events within the next 24 hours
- Verify system health and resource usage
- Perform lightweight human check-in during daytime hours

Keep sensitive information out of this file, as it becomes part of the agent's context with every heartbeat cycle.

Active Hours and Scheduling

To prevent nighttime disturbances, you can restrict heartbeats to specific time windows using the activeHours setting. This accepts a start and end time in HH:MM format, along with an optional timezone. For instance:

{
  "activeHours": {
    "start": "09:00",
    "end": "22:00",
    "timezone": "America/New_York"
  }
}

Outside this window, heartbeats are skipped until the next scheduled tick within the allowed period.

Handling Responses: OK vs Alerts

The heartbeat system follows a strict response contract:

• If nothing requires attention, respond with HEARTBEAT_OK (typically suppressed)
• For urgent matters, return only the alert text—do not include HEARTBEAT_OK

This ensures that only meaningful alerts reach your attention while routine OK responses remain silent.

Visibility Controls

You can fine-tune how heartbeat responses appear across different channels using visibility controls:

• showOk: Whether to display HEARTBEAT_OK acknowledgments
• showAlerts: Whether to deliver alert messages
• useIndicator: Whether to emit status indicator events for UIs

These can be set globally, per-channel, or per-account, following a clear precedence order.

Manual Wake and On-Demand Execution

Sometimes you need to trigger a heartbeat immediately. Use:

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

This enqueues a system event and forces an immediate heartbeat run. Use --mode next-heartbeat to wait for the next scheduled interval instead.

Cost and Performance Considerations

Since each heartbeat consumes tokens like any other agent turn, consider the cost implications of frequent intervals. Keeping HEARTBEAT.md small and using cheaper models for non-critical checks helps maintain efficiency. For purely internal state updates, set target: "none" to avoid unnecessary message delivery.

Heartbeat vs Cron: When to Use Each

While both enable automation, heartbeats and cron jobs serve different purposes:

• Use heartbeat for bundled checks (email + calendar + weather), when you need conversational context, or when timing can drift slightly
• Use cron for precise scheduling (e.g., "9:00 AM every Monday"), task isolation, or standalone reminders

In practice, many users combine both: using heartbeats for comprehensive daily scans and cron jobs for time-critical notifications.

The heartbeat system transforms your AI agent from a reactive tool into a proactive partner—constantly monitoring, evaluating, and ready to alert you only when it truly matters.