Want your AI assistant to proactively monitor your systems without constant manual checks? OpenClaw Heartbeat is the lightweight automation mechanism that makes this possible. Here’s everything you need to know about configuring it in 2026.

—

What Is OpenClaw Heartbeat?

OpenClaw Heartbeat is a lightweight, automatic checking mechanism built into the OpenClaw Gateway. It runs at regular intervals to execute background monitoring tasks — completely hands-off once configured.

Unlike traditional cron jobs, Heartbeat is designed specifically for frequent, lightweight checks rather than heavy scheduled tasks. Think of it as your AI assistant’s “pulse” — always running, always watching, but only speaks up when something needs your attention.

—

Heartbeat vs. Cron: What’s the Difference?

| Feature | Heartbeat | Cron |
|———|———–|——|
| Frequency | Every 30 minutes (configurable) | Fixed time points (e.g., 8:00 AM) |
| Model | Can use cheap/lightweight models | Best with premium models |
| Use Case | Frequent light checks | Scheduled heavy tasks |
| Cost | Lower (high frequency, lighter models) | Higher (less frequent, heavier tasks) |

—

Complete Configuration Guide

Step 1: Configure in openclaw.json

Add the Heartbeat settings under `agents.defaults.heartbeat`:

“`json
{
“agents”: {
“defaults”: {
“heartbeat”: {
“every”: “30m”,
“model”: “qwen3.5-flash”,
“includeReasoning”: true
}
}
}
}
“`

Configuration Options:

| Parameter | Type | Description |
|———–|——|————-|
| `every` | string | Interval (e.g., “15m”, “2h”, “1h30m”) |
| `model` | string | Model for Heartbeat tasks (e.g., “qwen3.5-flash”, “gpt-4o”) |
| `includeReasoning` | boolean | Show AI thinking process in responses |

Step 2: Set Up Your Model

Models must be pre-configured in `models.providers`. Here’s an example using Alibaba Cloud’s Qwen:

“`json
{
“models”: {
“providers”: {
“alibailian”: {
“baseUrl”: “https://dashscope.aliyuncs.com/compatible-mode/v1”,
“apiKey”: “sk-xxxxxxxxxxxx”,
“api”: “openai-completions”,
“models”: [
{
“id”: “qwen3.5-flash”,
“name”: “qwen3.5-flash”,
“contextWindow”: 200000,
“maxTokens”: 8192
}
]
}
}
}
}
“`

—

HEARTBEAT.md: Your Task Definition File

The Heartbeat mechanism reads `~/.openclaw/workspace/HEARTBEAT.md` to know what tasks to perform.

File Format

“`markdown

Task 1

Describe the check or task to execute…

Task 2

Another task description…
“`

Special Rules

• Empty file or only comments → Returns `HEARTBEAT_OK` (silent acknowledgment)

• Has actual content → Executes the tasks and returns results

• Task fails → Returns error and notifies the user

—

Practical Examples

Example 1: Weather Alert

“`markdown

Weather Alert

Check current weather in Quanzhou. Provide practical reminders (umbrella, sunscreen, clothing, etc.).

If severe weather occurs (heavy rain, typhoon), alert immediately.
Use brief, natural language.
“`

Result: Automatically checks weather every 30 minutes. Only alerts when needed.

Example 2: Email + Calendar + Weather Combo

“`markdown

Email Check

Check unread email count. If > 3 unread, list the top 3 subjects and senders.

Calendar Check

Review today’s upcoming schedule. If there’s a meeting within 2 hours, remind me of the time and topic.

Weather Alert

Check current weather. One-line reminder if umbrella/coat/sunscreen needed.
“`

Example 3: Multi-City Weather Monitoring

“`markdown

Weather Monitor

Check current weather for these cities:

• Quanzhou (primary)

• Shanghai (business trip)

• Beijing (family)

Alert immediately if:

• Heavy rain/typhoon/heavy snow

• Temperature > 38°C or < 0°C

• Air quality index > 150

Otherwise, give a brief one-line summary.
“`

—

Cost Optimization Strategy

| Task Type | Recommended Model | Why |
|———–|——————|—–|
| Heartbeat (frequent, light) | qwen3.5-flash | Cheap, fast, sufficient |
| Cron (scheduled, heavy) | GPT-4o / Claude 3.5 | Premium quality for important tasks |

Pro Tip: Use lightweight models like `qwen3.5-flash` for Heartbeat checks to minimize costs while keeping monitoring effective.

—

Common Questions

Q1: Can I set exact times for Heartbeat triggers?

No. Heartbeat only supports “every X minutes” intervals, not specific clock times. For time-specific tasks, use Cron instead.

Q2: What models are supported?

Any model configured in `models.providers`, including:

• OpenAI (GPT-4o, GPT-3.5)

• Anthropic (Claude 3.5)

• Alibaba Cloud (Qwen series)

• Local models (Ollama)

• Any OpenAI-compatible API

Q3: What happens if HEARTBEAT.md is missing?

The Heartbeat won’t know what to execute. This file is required for every Heartbeat configuration.

—

Conclusion

OpenClaw Heartbeat transforms your AI assistant from a passive tool into a proactive digital assistant that monitors, checks, and alerts — automatically. With minimal setup, you get:

✅ 24/7 automated monitoring
✅ Intelligent alerts only when needed
✅ Low-cost operation with lightweight models
✅ Flexible combinations with Cron for complete coverage

Master Heartbeat, and your OpenClaw becomes the round-the-clock assistant that truly has your back.

—

Related Articles:

• [How to Set Up Your First AI Agent in 2026](https://yyyl.me)

• [OpenClaw vs. Other AI Assistants: A Complete Comparison](https://yyyl.me)

Tags: OpenClaw, AI Tools, Automation, Background Monitoring, AI Assistant, Productivity

—

*Did this guide help you? Have questions about Heartbeat configuration? Drop a comment below and don’t forget to subscribe for more AI productivity tips!*