Cron Jobs & Heartbeats — Making OpenClaw Proactive

## Step 1: Verify Cron is Enabled

First, check if the Gateway is running and cron is enabled:

openclaw gateway status

Look for 'cron: enabled' in the output. If cron is disabled, check your config:

cat ~/.openclaw/openclaw.json | grep -A5 cron

Make sure you don't have OPENCLAW_SKIP_CRON=1 in your environment:

env | grep OPENCLAW

## Step 2: List Current Cron Jobs

View all scheduled jobs and their status:

openclaw cron list

Jobs showing 'idle' with 'Last: -' have never run. Check that 'enabled' is true for each job.

## Step 3: Fix Message Delivery (Critical)

The most common issue is messages going to a 'system' channel instead of reaching you. For reliable delivery, use this proven configuration:

{  "sessionTarget": "isolated",  "payload": {    "kind": "agentTurn",    "deliver": true,    "message": "Respond with [your exact text]. Do not remain silent."  }}

Key settings explained:

- sessionTarget: 'isolated' — Runs in its own session, doesn't conflict with active conversations

- deliver: true — Explicitly tells the agent to send output to your channel

- Explicit message instruction — Tell the agent exactly what to say; vague instructions may result in silence

## Step 4: Create a Reliable Cron Job via CLI

Jobs created via chat sometimes have schema issues. Create directly via CLI for reliability:

openclaw cron add \  --name "daily-reminder" \  --schedule "0 9 * * *" \  --session isolated \  --channel telegram \  --message "Good morning! Here's your daily briefing."

Or use the full JSON format:

openclaw cron add --json '{  "name": "daily-reminder",  "schedule": "0 9 * * *",  "enabled": true,  "sessionTarget": "isolated",  "payload": {    "kind": "agentTurn",    "deliver": true,    "channel": "telegram",    "message": "Send me a good morning message with today\'s priorities."  }}'

## Step 5: Main Session vs Isolated Session

Understanding the difference prevents most issues:

| Session Type | Requires Heartbeat | Conflicts with Active Chat | Best For |

|--------------|-------------------|---------------------------|----------|

| main | Yes | Yes—may skip if you're chatting | Context-aware tasks |

| isolated | No | No—runs independently | Reminders, scheduled messages |

If heartbeats are disabled, main session cron jobs will never run. Either:

- Enable heartbeats in config, or

- Use sessionTarget: 'isolated' for all cron jobs

## Step 6: Fix 'not-due' When Force-Running

If openclaw cron run --force still returns 'not-due':

# Check the job's next scheduled timeopenclaw cron list --verbose# Verify the schedule expression is validopenclaw cron validate "*/5 * * * *"# Try updating the job to run immediatelyopenclaw cron update daily-reminder --next-run now

## Step 7: Prevent Heartbeats from Interrupting Work

If heartbeats are killing your subagent tasks:

Edit your HEARTBEAT.md to only say HEARTBEAT_OK as the absolute final step:

# Heartbeat Checklist1. Check memory/ for pending tasks2. Review subagent status (do NOT interrupt active ones)3. Only if no active work exists, consider proactive actions4. FINAL STEP (always last): HEARTBEAT_OK

The key insight: When HEARTBEAT_OK is delivered, it can interrupt current activity including subagents. Structure your heartbeat so HEARTBEAT_OK only happens when truly idle.

## Step 8: Debug Why a Specific Job Didn't Run

Check the logs for your job:

openclaw logs --follow | grep cron

Common log messages and meanings:

- cron job skipped: session busy — Active conversation blocked it; use isolated session

- cron job skipped: not due — Schedule hasn't triggered yet

- cron delivered to system — deliver: true was missing; message went nowhere

- cron job ok, duration: Xms — Job ran but check if delivery worked