Automating Tasks with OpenClaw Cron Jobs

Cron jobs are the backbone of automation in OpenClaw, letting you schedule tasks to run at specific times or intervals without manual intervention. Whether it's a daily summary, a recurring maintenance check, or a one-time reminder, cron jobs ensure timely and reliable execution.

What is a Cron Job?

A cron job is a scheduled task that runs inside the OpenClaw Gateway. Unlike heartbeat-driven actions, which depend on periodic polling, cron jobs operate independently and persist across agent restarts. This makes them ideal for time-critical or background operations that shouldn’t rely on the main session’s activity cycle.

Jobs are stored in ~/.openclaw/cron/jobs.json and managed via the openclaw cron CLI or the cron tool in agent sessions.

Two Execution Modes: Main vs Isolated

OpenClaw supports two distinct execution styles for cron jobs:

• Main Session Jobs run within your primary agent session by enqueuing a system event. These are best for tasks that require access to your main conversation history or shared context.
• Isolated Jobs run in a dedicated, fresh session (cron:<jobId>). They start with no prior context and are perfect for noisy or frequent tasks that shouldn’t clutter your main chat.

Choosing the right mode depends on whether you need continuity (main) or isolation (isolated).

Scheduling: At, Every, or Cron

You can define when a job runs using one of three schedule types:

• At: One-shot execution at an absolute time (ISO 8601). Example: --at "2026-02-01T16:00:00Z".
• Every: Recurring execution at a fixed interval (e.g., --every 30m).
• Cron: Unix-style cron expressions with optional timezone support (e.g., --cron "0 7 * * *" --tz "America/New_York").

Timezones matter: if omitted, timestamps default to UTC.

Delivering Results: Announce or None

Isolated jobs can optionally deliver their output directly to a channel. This is called announce delivery:

• Announce: Sends output to a specified channel (e.g., WhatsApp, Slack) and posts a summary to the main session.
• None: Internal-only; no messages are delivered.

Use --announce with --channel and --to to target specific recipients. This bypasses the need for messaging tools in your job logic.

Practical Example: Daily Morning Brief

Here’s how to set up a daily summary delivered to Slack:

openclaw cron add \
  --name "Morning Brief" \
  --cron "0 7 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "Summarize yesterday's activity and today's calendar." \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

This job runs every weekday morning, generates a summary, and delivers it directly to your team’s Slack channel.

Overriding Model and Thinking Level

Isolated jobs can use different models or reasoning levels than your default agent. For example:

openclaw cron add \
  --name "Weekly Deep Dive" \
  --cron "0 6 * * 1" \
  --session isolated \
  --message "Perform a detailed analysis of project progress." \
  --model "opus" \
  --thinking high \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

This ensures resource-intensive analyses use a more capable model without affecting your everyday interactions.

Managing Jobs

Key commands:

• openclaw cron list — view all active jobs
• openclaw cron run <jobId> — trigger a job immediately
• openclaw cron edit <jobId> — update job parameters
• openclaw cron remove <jobId> — delete a job

You can also inspect run history with openclaw cron runs --id <jobId>.

Best Practices

• Use isolated jobs for frequent or noisy tasks to keep your main session clean.
• Prefer announce delivery over in-agent messaging for reliability and efficiency.
• Set active hours to avoid off-hour disruptions.
• Keep HEARTBEAT.md small and focused—cron is better for heavy automation.

By mastering cron jobs, you unlock powerful, hands-off automation that keeps your systems running smoothly—all without lifting a finger.