Setting Up Heartbeat Automation

You have OpenClaw running. Maybe it handles your messages, runs automations, or powers your workflows. But what happens when something breaks at 3am? Without monitoring, you might not find out until users complain.

Heartbeat automation solves this. It runs periodic health checks and alerts you when something needs attention.

Understanding OpenClaw Heartbeats

OpenClaw's heartbeat system is built on cron jobs that run health checks on a schedule. Each heartbeat can verify different aspects of your system:

• Gateway connectivity and authentication status
• Memory index health and coverage percentage
• Cron job success rates and recent failures
• System health warnings and error logs
• Disk space and resource usage

The heartbeat state is tracked in a JSON file that persists between checks. This lets you see trends over time and detect issues that develop gradually.

Configuring Heartbeat Checks

Heartbeat jobs are defined in the cron section of your OpenClaw configuration. Each job needs a schedule, a target session, and a payload describing what to check.

{
  "name": "System Health Check",
  "enabled": true,
  "schedule": {
    "kind": "cron",
    "expr": "0 */30 * * * *",
    "tz": "Europe/Berlin"
  },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "Run health check: verify gateway status, memory index, cron jobs, and system warnings. Report any issues found."
  }
}

This example runs a health check every 30 minutes. The cron expression `0 */30 * * * *` means "at second 0 of every 30th minute."

Cron Expression Basics

OpenClaw uses standard cron syntax with six fields:

┌───────────── second (0-59) │ ┌───────────── minute (0-59) │ │ ┌───────────── hour (0-23) │ │ │ ┌───────────── day of month (1-31) │ │ │ │ ┌───────────── month (1-12) │ │ │ │ │ ┌───────────── day of week (0-6) │ │ │ │ │ │ * * * * * *

Common patterns:

• 0 * * * * * - Every hour at minute 0
• 0 0 * * * * - Every day at midnight
• 0 0 */3 * * * - Every 3 days at midnight
• 0 10 * * * * - Every day at 10:00

Notification Channels

When a heartbeat detects an issue, it needs somewhere to send the alert. Configure delivery settings in your cron job:

"delivery": {
  "mode": "announce",
  "channel": "telegram",
  "to": "421928930"
}

This sends notifications to a specific Telegram chat. You can configure different channels for different types of checks, or use the last channel to send to wherever the original request came from.

What to Check

A good heartbeat setup covers the critical paths of your OpenClaw deployment:

Gateway Health

Verify the gateway is running and responsive. Check that authentication is enabled and tokens are valid. If the gateway loopback-only setting changed unexpectedly, that is a security flag.

Memory System

OpenClaw maintains a memory index. Check that indexed files percentage is reasonable and coverage is not degrading. A sudden drop in coverage could indicate an indexing problem.

Cron Jobs

Monitor recent cron job runs. Look for consecutive errors, failed deliveries, or jobs that have not run when expected. A cron job that silently fails is worse than no cron job.

System Resources

For deployments that handle heavy workloads, check disk space, memory usage, and CPU load. OpenClaw can run scripts that query system stats and alert when thresholds are exceeded.

Heartbeat State File

OpenClaw tracks heartbeat state in ~/.openclaw/memory/heartbeat-state.json. This file records:

• Last check timestamps for each monitor
• Gateway connectivity status
• Memory index health
• Cron job statistics
• System health warnings

Do not edit this file manually. OpenClaw manages it automatically during heartbeat runs.

Best Practices

Keep your heartbeat setup maintainable:

• Start simple - One hourly check is better than no checks
• Alert on symptoms - Check for problems users would notice, not internal states
• Use escalation - Critical issues get immediate alerts, warnings can wait for hourly summaries
• Test your alerts - Periodically trigger a test alert to verify notifications work
• Review false positives - If you ignore alerts, something is wrong with your thresholds