OpenClaw Cron Jobs: Scheduling, Timing & Payload Options

+15 Mana ✨
OpenClaw Cron Jobs Guide(DOCUMENTATION)Crontab Guru(DOCUMENTATION)

Introduction

Cron jobs in OpenClaw let you schedule tasks that execute at specific times or intervals without manual intervention. Unlike heartbeats which follow a fixed checklist, cron jobs are individual scheduled tasks with their own timing, payload, and execution context. This lesson covers how to create cron jobs and the different timing and payload options available.

Key Concepts

  • openclaw cron add: The CLI command to create a new scheduled job
  • --at: Schedules a one-time job at a specific date and time
  • --every: Creates a recurring job with a fixed interval (e.g., every 2 hours)
  • --cron: Uses standard cron expression syntax for complex schedules
  • --system-event: Delivers the job as a system event that the agent processes silently
  • --message: Delivers the job as a regular message to the agent's conversation

Real World Context

A startup uses OpenClaw to manage their deployment pipeline. Every weekday at 9 AM, they want the agent to pull the latest code, run tests, and deploy to staging. Every Friday at 5 PM, they want a weekly summary of all deployments. These two jobs have different schedules and payloads, but both are managed through the same cron system with simple CLI commands.

Deep Dive

Creating a cron job uses the openclaw cron add command with one of three timing options.

One-Time Jobs with --at

The --at flag schedules a job to run exactly once at a specific time:

bash
openclaw cron add \
  --at "2026-02-21T09:00:00Z" \
  --message "Run the quarterly security audit on all production services"

This creates a one-time job that fires at 9 AM UTC on February 21, 2026. The agent receives the message as a regular conversation turn and processes it using its available tools. After execution, the job is marked as completed and does not repeat.

Recurring Jobs with --every

The --every flag creates jobs that repeat at a fixed interval:

bash
openclaw cron add \
  --every "2h" \
  --system-event "Check API response times and alert if p95 > 500ms"

This job runs every 2 hours. The payload is delivered as a system event rather than a message, which means it is processed by the agent without appearing in the conversation history. Supported interval units include minutes (m), hours (h), and days (d).

Complex Schedules with --cron

For schedules that do not fit a simple interval, use standard cron expression syntax:

bash
openclaw cron add \
  --cron "0 9 * * 1-5" \
  --message "Pull latest main branch, run tests, deploy to staging"

This cron expression means "at minute 0 of hour 9, every day Monday through Friday." The five fields are minute, hour, day-of-month, month, and day-of-week, following standard Unix cron syntax.

Payload Types: --system-event vs --message

The choice between --system-event and --message affects how the agent receives the job:

bash
# System event: processed silently, not in conversation history
openclaw cron add --every "1h" --system-event "Check disk usage"

# Message: appears as a regular conversation message
openclaw cron add --every "1h" --message "Check disk usage"

System events are ideal for background monitoring tasks that should not clutter the conversation. Messages are better for tasks where you want a visible record of the request and response in the chat history.

Common Pitfalls

  • Using --at when you need --every: The --at flag only fires once. If you forget to use --every or --cron for recurring tasks, the job will execute once and never run again.
  • Incorrect cron expression syntax: Cron expressions use five fields, not six. Including a seconds field will cause a parse error.
  • Mixing up --system-event and --message for audit trails: System events do not appear in conversation history, so they are not suitable when you need a visible audit trail.

Best Practices

  • Use --system-event for monitoring tasks that should run silently in the background.
  • Use --message for tasks that need visibility in the conversation history for accountability.
  • Test cron expressions with a validator before deploying to avoid schedule mistakes.

Event-driven alternative: For automation that triggers on events rather than schedules, see Building Custom Hooks.

Summary

  • openclaw cron add creates scheduled jobs with three timing options: --at (one-time), --every (interval), --cron (expression)
  • --system-event delivers payloads silently while --message adds them to conversation history
  • Cron expressions follow standard five-field Unix syntax
  • Interval units for --every include minutes (m), hours (h), and days (d)
  • Choose the payload type based on whether you need a visible audit trail
✓ Completed