Cron Jobs & Heartbeats: Making OpenClaw Proactive

Use cron jobs for precise schedules and heartbeats for quiet, context-aware checks. This OpenClaw guide shows how to choose, configure, test, and secure both.

Try OpenClaw Free

How OpenClaw Becomes Proactive

A reactive agent waits for a message. A proactive agent has a safe reason to wake up, check something, and report only when it matters.

In OpenClaw, the two core scheduling mechanisms are cron jobs and heartbeats. They solve different problems:

Cron jobs run on an exact schedule, such as 9:00 AM every weekday or 20 minutes from now.
Heartbeats run periodic agent turns in the main session, so the agent can batch a small set of context-aware checks.

The best setup is usually not “make it run constantly.” Start with one useful check, a narrow permission set, a quiet success path, and a clear human approval boundary.

Cron Jobs vs Heartbeats: Which Should You Use?

Question	Use Cron Jobs	Use Heartbeats
Timing	Exact time, interval, or one-shot reminder	Approximate periodic checks
Context	Fresh isolated run, main session, or a named custom session	Main-session context by default
Best for	Reports, reminders, scheduled jobs, webhooks	Inbox, calendar, follow-ups, low-noise monitoring
Delivery	Channel, webhook, or no fallback delivery	Internal by default, or alerts to a chosen target
Example	Send a weekday status brief at 9 AM	Check for urgent work every 30 minutes

Use cron when missing the exact time would matter. Use a heartbeat when it is fine to check on the next cycle and the agent benefits from knowing the current session context.

What People Build With OpenClaw Scheduling

Precise cron workflows

Weekday project or deployment digests
One-time reminders and deadline follow-ups
Weekly backlog, incident, or spend reviews
Scheduled data checks that post to a webhook
Isolated report generation without chat context

Heartbeat workflows

Urgent inbox and calendar scans
Blocked-task and follow-up checks
Lightweight agent or Gateway health awareness
Monitoring a small, changing work queue
Quiet prompts to review something only when needed

For broader workflow ideas, see the OpenClaw business automation guide and the browser automation guide. Scheduling should support a workflow, not create background activity for its own sake.

How to Create Safe OpenClaw Cron Jobs

Cron runs inside the Gateway process, not inside the model. The Gateway must stay running for schedules to fire. Saved jobs, runtime state, and run history persist in OpenClaw's shared SQLite state database.

1. Start with a one-shot, read-only reminder

A one-shot main-session event is the lowest-risk way to confirm that the scheduler, timezone, and delivery path are working.

openclaw cron add \
  --name "Calendar check" \
  --at "20m" \
  --session main \
  --system-event "Next heartbeat: check calendar for urgent preparation." \
  --wake now

One-shot jobs delete after success by default. Use --keep-after-run if you need to retain a completed job for inspection.

2. Use isolated jobs for independent reports

An isolated cron job starts a dedicated agent turn without inheriting ambient chat context. That makes it a good choice for a report, maintenance check, or task that should not alter the conversation.

openclaw cron create "0 9 * * 1-5" \
  "Summarize open issues, blocked work, and deploys from the last 24 hours. Keep it under 10 bullets." \
  --name "Weekday engineering brief" \
  --tz "Asia/Kolkata" \
  --session isolated \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

Use an explicit IANA timezone. Without --tz, cron expressions use the Gateway host timezone. Offset-less one-shot timestamps are treated as UTC unless you set a timezone.

3. Inspect, test, then enable delivery

openclaw cron list
openclaw cron show <job-id>
openclaw cron run <job-id> --wait
openclaw cron runs --id <job-id> --limit 20

Start with no write actions and a private delivery target. After you confirm the output and schedule, add the smallest approved delivery or integration capability.

4. Choose the right execution style

Main session: queues a system event and can wake a heartbeat. Best for reminders and context-aware nudges.
Isolated: starts a fresh dedicated run. Best for reports and background chores.
Custom session: deliberately preserves a named workflow's context between runs. Use only when continuity is genuinely useful.
Command payload: runs a deterministic command on the Gateway host. Treat it as operator-managed automation, not a casual agent tool call.

How to Use Heartbeats Without Creating Noise

Heartbeats are periodic main-session turns. Their job is not to narrate that nothing happened. Their job is to surface something that needs attention and otherwise remain quiet.

Use a small HEARTBEAT.md checklist

If a HEARTBEAT.md file exists in the agent workspace, the default heartbeat prompt tells OpenClaw to read it. Keep the file short, stable, and free of secrets.

# Heartbeat checklist

- Check for urgent unread inbox items.
- Check whether the next calendar event needs preparation.
- If a task is blocked, explain what is missing.
- Keep alerts short. If nothing needs attention, reply HEARTBEAT_OK.

Give different checks different intervals

Use a tasks: block when some checks are more frequent than others. OpenClaw includes only due tasks in that heartbeat cycle, which avoids paying for every check every time.

tasks:
  - name: inbox-triage
    interval: 30m
    prompt: "Check for urgent unread emails and flag only time-sensitive items."
  - name: calendar-scan
    interval: 2h
    prompt: "Check for upcoming meetings that need preparation or follow-up."

- Keep alerts concise. If nothing needs attention, reply HEARTBEAT_OK.

Set active hours and quiet delivery

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "none",
        lightContext: true,
        isolatedSession: true,
        skipWhenBusy: true,
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "Asia/Kolkata"
        }
      }
    }
  }
}

target: "none" is the safe default for a new heartbeat. It can still run, but it will not send external messages. Switch to a specific target only after you are happy with the alert behavior. Do not set identical start and end times for active hours, because that creates a zero-width window.

Cost, Reliability, and Delivery Controls

Keep costs predictable

Use the longest practical cadence.
Keep HEARTBEAT.md short.
Use lightContext: true for checklist-only runs.
Use isolatedSession: true when shared chat history is unnecessary.
Choose a suitable lower-cost model for lightweight checks.

Make delivery reliable

Set explicit channel and recipient targets for proactive messages.
Use a webhook when another system owns the next action.
Review run history rather than assuming a scheduled message arrived.
Configure failure alerts separately from the primary report.
Keep Gateway uptime in mind: no running Gateway means no scheduled execution.

Heartbeats automatically defer while cron work is active or queued. With skipWhenBusy: true, they also wait while the same agent has certain nested work in progress. This reduces collisions and duplicate effort.

Security Checklist for Proactive Automation

Start with read-only checks and silent or private delivery.
Require approval before a scheduled workflow edits data, sends external messages, deploys, or spends significant API budget.
Use explicit delivery recipients rather than relying on stale chat context.
Do not put credentials, private tokens, or phone numbers in HEARTBEAT.md or scheduled prompts.
Treat command cron and event-trigger scripts as unattended code execution with the permissions of the Gateway environment.
Test external hooks behind loopback, a private network, or a trusted reverse proxy with a dedicated token.
Review logs and run history after changing a schedule, model, delivery route, or tool access.

For the broader hardening checklist, read OpenClaw security best practices. If you are operating a persistent agent yourself, also compare managed and self-hosted OpenClaw.

Common Problems and Fixes

Problem	Likely cause	What to check
Cron job never runs	Gateway is stopped, cron is disabled, or timezone is wrong	`openclaw status`, `openclaw gateway status`, schedule timezone
Job ran but no message arrived	No valid delivery target or no fallback delivery	Job delivery mode, channel, recipient, and run history
Heartbeat is too noisy	Checklist is too broad or delivery is enabled for normal acknowledgments	Shorten HEARTBEAT.md, use HEARTBEAT_OK, set a quiet target
Heartbeats do not fire during work	They defer while cron or busy lanes are active	Queue activity and `skipWhenBusy` behavior
Costs are higher than expected	Cadence is too frequent or each run includes too much context	Cadence, model, lightContext, isolatedSession, checklist size

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <job-id> --limit 20
openclaw system heartbeat last
openclaw logs --follow
openclaw doctor

Start With One Proactive Workflow

The best first workflow is small and reversible: a weekday brief, an inbox urgency scan, or a one-time reminder. Keep the first version read-only, inspect the result, and add delivery or write access only when the behavior is reliable.

If you want an always-on OpenClaw workflow without managing Gateway uptime, ports, updates, and monitoring yourself, managed hosting lets you spend more time designing the workflow and less time operating the server.

Frequently Asked Questions

What is the difference between cron jobs and heartbeats in OpenClaw?

Cron jobs run at an exact time or interval and are best for reminders, reports, and isolated background work. Heartbeats are periodic main-session agent turns and are best for batched, context-aware checks where approximate timing is acceptable.

When should I use an OpenClaw cron job?

Use cron when timing matters: a report at 9 AM, a one-time reminder in 20 minutes, a weekly review, or an isolated job that should deliver to a channel or webhook.

When should I use an OpenClaw heartbeat?

Use a heartbeat for a small, repeatable checklist such as scanning for urgent inbox items, checking upcoming calendar events, or surfacing blocked work. Keep it quiet when nothing needs attention.

Do cron jobs keep running after OpenClaw restarts?

OpenClaw stores cron job definitions, runtime state, and run history in its shared SQLite state database. The Gateway must be running for scheduled work to fire, but a normal restart does not remove saved schedules.

How can I stop heartbeats from spamming me?

Use a short HEARTBEAT.md checklist, keep HEARTBEAT_OK acknowledgments hidden, restrict heartbeats to active hours, and only deliver alerts when something needs attention. The default heartbeat target is none.

How do I test a cron job before relying on it?

Create the smallest read-only version first, inspect it with openclaw cron show, run it manually with openclaw cron run --wait, then review openclaw cron runs before enabling delivery or write actions.

Also Read

Business

OpenClaw Business Automation: Replace Manual Work With AI Agents

Guide

OpenClaw Browser Automation Guide: Extension Setup & Fixes

Guide

OpenClaw Security Best Practices Guide

Written by

Michael Park

Senior Technical Writer & DevRel

Michael creates comprehensive installation and setup guides for developers and system administrators. With experience across Linux, macOS, Windows, and embedded systems, he has written over 200 technical tutorials used by millions of developers. He focuses on clear, step-by-step instructions that work the first time, covering everything from Raspberry Pi to enterprise servers.

Make OpenClaw proactive without babysitting infrastructure

Run scheduled reports, quiet checks, and reliable workflows on managed OpenClaw hosting, then scale only when the workflow proves useful.

Start Free Trial