OpenClaw Heartbeat Not Firing: Complete Fix Guide for Cron & Scheduled Tasks
The Problem: You set up OpenClaw to run background tasks — morning briefings, hourly status checks, scheduled reminders. But the agent is silent. The heartbeat never fires, scheduled tasks never run, and your "always-on AI" is doing nothing between conversations. This guide covers every reason heartbeats and cron jobs fail, and how to fix each one.
Heartbeats are the core of what makes OpenClaw genuinely proactive. User @HixVAC on X captured this perfectly: "Apparently @openclaw checks in during heartbeats!? A kinda awesome surprise! Love the proactive reaching out." And user @BraydonCoyer described his setup: "Named him Jarvis. Daily briefings, calendar checks, reminds me when to leave for pickleball based on traffic." When heartbeats work, OpenClaw becomes a 24/7 digital assistant. When they don't, it's just a reactive chatbot.
OpenClaw's heartbeat system allows you to schedule the agent to wake up at defined intervals, perform tasks, and report back to you — all without you having to send a message first. This is what separates it from conventional AI chatbots. But this feature has several failure modes that are easy to trigger and hard to diagnose without knowing exactly where to look.
How OpenClaw Heartbeat Works
OpenClaw heartbeat is a cron-based scheduling system built into the gateway. When configured, the gateway wakes the agent at specified intervals, injects a heartbeat prompt, and the agent performs its scheduled tasks then optionally sends you a message. There are three ways to configure heartbeats:
HEARTBEAT.md
A file in your workspace that defines what the agent does during each heartbeat cycle. Simple natural language instructions run on schedule.
openclaw.json cron
Define cron expressions directly in openclaw.json for precise scheduling. Supports standard cron syntax for complex timing patterns.
Skills-based cron
Custom skill files that include cron scheduling metadata. The most flexible approach — each skill can have its own schedule.
Step 1: Diagnose Why Heartbeats Are Not Firing
Start with these diagnostic commands to understand the current state of your heartbeat system:
# Check if gateway is running (heartbeat requires gateway)
openclaw gateway status
# List all configured cron jobs
openclaw cron list
# Check heartbeat configuration
openclaw config get heartbeat
# View recent heartbeat logs
openclaw logs --type heartbeat --tail 50
# Run the doctor to identify config issues
openclaw doctor
# Check if any tasks ran recently
openclaw sessions list --type heartbeat
Cause #1: Gateway Is Not Running
This is by far the most common cause. The heartbeat system is part of the OpenClaw gateway process. If the gateway stops — due to a computer restart, a crash, or manual shutdown — all scheduled tasks stop permanently until the gateway is restarted. Unlike a system cron job, OpenClaw's scheduler only exists while the gateway is active.
# Check gateway status
openclaw gateway status
# If it shows "stopped" or "not running", start it:
openclaw gateway start
# Verify it's running
openclaw gateway status
# Should show: "Gateway is running on port 18789"
# Check if it starts successfully by looking at logs:
openclaw logs --follow
The Permanent Fix: Auto-Start Gateway on Boot
If you rely on heartbeats for daily tasks, configure the gateway to start automatically when your computer boots. This prevents the most common cause of missed heartbeats.
# macOS: Use launchd (LaunchAgent)
openclaw autostart enable
# Creates ~/Library/LaunchAgents/com.openclaw.gateway.plist
# Linux: Use systemd
openclaw autostart enable --systemd
# Creates /etc/systemd/system/openclaw-gateway.service
# Windows: Use Task Scheduler or startup folder
openclaw autostart enable --windows
# Verify autostart is configured
openclaw autostart status
Cause #2: Incorrect Cron Syntax
OpenClaw uses standard cron syntax for scheduling, but a subtle mistake in the expression silently disables the job. If the expression cannot be parsed, the heartbeat is registered but never fires.
# Common cron expressions for OpenClaw:
"0 8 * * *" # Every day at 8:00 AM
"0 */2 * * *" # Every 2 hours
"*/30 * * * *" # Every 30 minutes
"0 9 * * 1-5" # Weekdays at 9 AM
"0 8,20 * * *" # At 8 AM and 8 PM daily
# In openclaw.json config format:
{
"heartbeat": {
"enabled": true,
"cron": "0 8 * * *",
"timezone": "America/New_York"
}
}
# Validate cron expression before saving:
# Use https://crontab.guru to test expressions
Common Cron Mistakes
"8 * * * *"— fires at minute 8 every hour, not at 8 AM. Should be"0 8 * * *""* * * * *"— fires every minute (hits API limits fast, avoid unless testing)- Missing timezone — heartbeat fires at UTC time, not your local time
- Natural language like "every morning" — not valid cron, use
"0 8 * * *"
Cause #3: HEARTBEAT.md Not Found or Misconfigured
If you're using the HEARTBEAT.md approach — placing a file in your workspace that tells the agent what to do — the file must be in exactly the right location with exactly the right name. Even a capitalization error will cause it to be silently ignored.
# Confirm workspace location
openclaw config get workspace
# Output: /Users/yourname/.openclaw/workspace
# Verify HEARTBEAT.md exists with correct name
ls ~/.openclaw/workspace/
# Must show: HEARTBEAT.md (uppercase, correct spelling)
# Common mistakes:
# heartbeat.md ← wrong (lowercase)
# Heartbeat.md ← wrong (mixed case)
# HEARTBEAT.txt ← wrong (wrong extension)
Example HEARTBEAT.md That Works
# HEARTBEAT.md
# This file runs on every heartbeat cycle
## Morning Routine (8 AM daily)
- Check my calendar for today's events
- Check weather for my city
- Send me a Telegram message summarizing: events + weather + any urgent emails
- Subject line: "☀️ Morning briefing - [Day, Date]"
## Every 2 Hours
- Check if I have any unread emails marked urgent
- If yes, send me a Telegram notification with the subject and sender
## Evening Routine (9 PM daily)
- Summarize what tasks were completed today
- List anything scheduled for tomorrow
- Send via Telegram: "🌙 Evening wrap-up"
Cause #4: Notification Channel Not Connected
Even when heartbeats fire correctly, you might never know it because the notification is going to a channel you're not monitoring. OpenClaw sends heartbeat results to a configured communication channel (Telegram, WhatsApp, Discord, SMS). If that channel is disconnected, the heartbeat runs silently with no visible output.
# Check which channels are connected
openclaw channels list
# Test a channel is receiving messages
openclaw channels test telegram
openclaw channels test discord
openclaw channels test whatsapp
# Check channel configuration
openclaw config get channels
# Force a manual heartbeat test (fires immediately):
openclaw heartbeat trigger
# Look for the response in your configured channel
Reconnecting a Channel
# Re-run the onboarding for a specific channel:
openclaw onboard --channel telegram
openclaw onboard --channel discord
openclaw onboard --channel whatsapp
# For Telegram specifically:
# 1. Message @OpenClawBot on Telegram
# 2. Run: openclaw config set channels.telegram.chatId [your-chat-id]
# 3. Test: openclaw channels test telegram
Cause #5: API Rate Limits Blocking Heartbeats
If heartbeats are configured to run frequently (every 30 minutes or more often), they can exhaust your API token quota. When a heartbeat fires but the API returns a 429 rate limit error, the heartbeat fails silently — it ran, but produced no result. Your logs show the heartbeat triggered but the task never completed.
# Check heartbeat logs for API errors
openclaw logs --type heartbeat --tail 100 | grep -i "429\|rate\|limit\|error"
# Fix: Configure failover model for heartbeats
{
"heartbeat": {
"model": {
"primary": "anthropic/claude-haiku-4", ← Cheaper model for routine tasks
"failover": ["openai/gpt-4o-mini"] ← Even cheaper fallback
},
"cron": "0 8,20 * * *" ← Only twice daily
}
}
Cause #6: Computer Sleep Mode Interrupts Heartbeat
This is a particularly frustrating issue for MacBook and laptop users. When your computer sleeps, the OpenClaw gateway process is suspended. Scheduled heartbeats that were supposed to fire while the computer was asleep are missed entirely — they don't run when the computer wakes up, they're simply skipped. The next heartbeat will fire at the next scheduled time.
Solutions for Laptop/Desktop Users
Option 1: Prevent Sleep (Simple)
caffeinate -i -s & # macOS: prevent sleep while on power
pmset -a sleep 0 # macOS: disable sleep permanently (with power adapter)
Option 2: Run OpenClaw on a Always-On Server
Deploy OpenClaw on a cloud VM (AWS free tier, Hetzner, Zeabur) that runs 24/7 regardless of your laptop's state. Connect to it via Telegram from anywhere.
Option 3: Run on a Raspberry Pi or Home Server
User @AlbertMoral set it up on a Raspberry Pi: "I just finished setting up @openclaw by @steipete on my Raspberry Pi with Cloudflare, and it feels magical." A Pi runs for pennies per day and never sleeps.
Manual Heartbeat Testing Protocol
Before relying on scheduled heartbeats, test them manually. This confirms the heartbeat system works correctly and only then rule out scheduling issues:
# Step 1: Trigger heartbeat manually
openclaw heartbeat trigger
# Or in chat: /heartbeat
# Step 2: Verify you receive the message in your channel (Telegram/Discord)
# Wait 30-60 seconds for it to arrive
# Step 3: Check logs to see what happened
openclaw logs --type heartbeat --tail 20
# Step 4: If manual works but scheduled doesn't, it's a cron/timing issue
# Check cron configuration:
openclaw cron list
openclaw config get heartbeat
# Step 5: Verify cron is active in gateway
openclaw gateway status --verbose
Advanced: Skills-Based Cron Scheduling
For complex scheduling needs, skills-based cron is more powerful than HEARTBEAT.md. You can create individual skill files with their own cron schedules, each handling a specific task. This is how experienced OpenClaw users build sophisticated automation pipelines.
Example Skills-Based Cron Setup
# Tell OpenClaw to create a scheduled skill:
"Create a skill called 'morning-briefing' that runs at 8 AM every weekday.
It should check my Google Calendar, get the weather for San Francisco,
and send me a Telegram message with: greeting, weather, and today's schedule."
# OpenClaw will create a skill file like:
# ~/.openclaw/workspace/skills/morning-briefing.js
# with cron metadata embedded
# To manage skills:
openclaw skills list
openclaw skills status morning-briefing
openclaw skills run morning-briefing # manual test
openclaw skills delete morning-briefing
Reliable Network for Heartbeat API Calls
Heartbeat reliability depends heavily on your network connection. When a heartbeat fires, OpenClaw must make API calls to your AI provider, potentially call external tools (Google Calendar, email), and then send a message via your channel. If any of these calls time out or fail due to network issues, the heartbeat produces no visible output even though it "ran."
Users running OpenClaw in regions with inconsistent internet quality — or on networks that throttle AI provider traffic — experience frequent partial heartbeat failures. Running through a high-speed VPN with stable, unthrottled connections dramatically improves heartbeat reliability, especially for API calls to Anthropic, OpenAI, and Google services.
VPN07 — Reliable Connections for AI Automation
Ensure every heartbeat API call completes successfully, every time
VPN07's 1000Mbps gigabit nodes across 70+ countries have been trusted for over 10 years. Your OpenClaw heartbeat calls to Anthropic, OpenAI, and Google APIs route through fast, clean connections — no throttling, no partial failures, no missed morning briefings.
Heartbeat FAQ
Can I have multiple different heartbeat schedules?
Yes, using skills-based cron. Ask your agent to "create a skill that runs at 8 AM daily" for the morning briefing and "create another skill that runs every Friday at 5 PM" for a weekly summary. Each skill has its own independent schedule.
How many tokens does a heartbeat use?
A simple heartbeat (read calendar, send summary) typically uses 2,000–8,000 tokens depending on data complexity. At Claude API rates, that's roughly $0.03–$0.12 per heartbeat. To minimize costs, configure heartbeats to use Claude Haiku (cheaper) or set them to twice-daily maximum.
Heartbeat fires but I don't receive a message. Why?
Either the channel isn't connected (openclaw channels test telegram), or the heartbeat task doesn't include a "send me a message" instruction. Add explicit send instructions to HEARTBEAT.md: "Send me a Telegram message with the summary."
Can heartbeats run without internet / with offline models?
Partially. If you configure Ollama as the AI provider, the LLM inference runs offline. But tools that call external services (calendar, email, weather) still need internet. A heartbeat using only local tools (file operations, local data) can run fully offline.
Real-World Heartbeat Examples From OpenClaw Users
Here are proven heartbeat setups shared by actual OpenClaw users on X.com in early 2026, with the exact HEARTBEAT.md content that worked for them:
The Executive Morning Briefing (@BraydonCoyer style)
## Daily 7:30 AM (weekdays only: 0 7:30 * * 1-5)
- Check Google Calendar for today's meetings
- Check estimated commute time to the office (Google Maps)
- Pull top 5 unread emails from Gmail (subjects only)
- Check weather for my city
- Format everything as a Telegram message:
"🌅 Morning [Day] — [Weather] | [Meetings] | [Commute time]"
- If any meeting in next 2 hours: add red alert emoji 🚨
The Health Tracker (@antonplex / @sharoni_k style)
## Every morning at 6 AM (0 6 * * *)
- Fetch WHOOP data: sleep score, HRV, recovery %
- Fetch weather: today's temperature and UV index
- If recovery < 50%: suggest lighter activity day
- If recovery > 75%: suggest workout
- Send Telegram: "💪 Recovery: [X]% | HRV: [X]ms | Sleep: [X]h"
The Developer Status Monitor (@nateliason style)
## Every 2 hours (0 */2 * * *)
- Check GitHub: any new issues assigned to me?
- Check Sentry: any new errors in production in last 2h?
- If Sentry errors found: send Telegram alert immediately
- Check GitHub Actions: any failed builds?
- If issues/failures found: create a summary and send via Telegram
Monitoring Heartbeat Performance
After setting up heartbeats, monitor them to ensure they're running reliably and within token budgets. Missed heartbeats or failed executions should be caught early before they become habitual failures.
# View heartbeat execution history with results
openclaw sessions list --type heartbeat --limit 20
# Check how many tokens each heartbeat is consuming
openclaw sessions show [heartbeat-session-id] --usage
# Find failed heartbeats
openclaw logs --type heartbeat | grep -i "error\|failed\|timeout"
# Set up heartbeat failure alerting:
# Add to your HEARTBEAT.md:
## If this heartbeat fails or has errors
# Re-try once after 15 minutes
# If still failing, send me a Telegram alert: "⚠️ Heartbeat failed - check logs"
# Review overall heartbeat stats:
openclaw stats --type heartbeat --period 7days
💡 Heartbeat Best Practices Summary
- Enable autostart so heartbeats survive reboots:
openclaw autostart enable - Test manually first before relying on schedule:
openclaw heartbeat trigger - Keep frequency to 1–4 times per day to avoid token exhaustion
- Use Claude Haiku or GPT-4o-mini for heartbeats (cheaper, still capable)
- Run OpenClaw on an always-on server for truly reliable 24/7 heartbeats
- Verify channel connection before assuming heartbeat is broken