Skip to content

Cron & Automation

OpenClaw's cron system enables scheduled tasks, reminders, and background automation.

What It Does

The cron system supports:

  • Recurring tasks: Daily/weekly/monthly schedules
  • One-shot reminders: Future-dated notifications
  • Background agents: Isolated sub-agents for long tasks

Cron Types

Recurring Jobs

Run on a schedule:

  • Daily reports (e.g., OpenRouter usage summary)
  • Periodic health checks
  • Weekly backups

Schedule formats:

  • cron expression: "0 9 * * 1" (Mondays at 9 AM)
  • every interval: "everyMs": 86400000 (24 hours)
  • at timestamp: One-shot at specific time

One-Time Reminders

Schedule a future reminder:

  • "Remind me in 30 minutes"
  • "Remind me tomorrow at 9 AM"

Agent Turn Jobs

Spawn an isolated sub-agent to:

  • Run long tasks without blocking main session
  • Execute complex multi-step workflows
  • Generate reports and deliver to channels

Managing Jobs

Action Description
cron add Create a new scheduled job
cron list View all active jobs
cron remove Delete a job by ID
cron run Trigger a job immediately
cron runs View job execution history

Job Configuration

Example: Daily Report

{
  "name": "daily-openrouter-report",
  "schedule": {
    "kind": "cron",
    "expr": "0 16 * * *",
    "tz": "UTC"
  },
  "payload": {
    "kind": "agentTurn",
    "message": "Generate daily OpenRouter usage report and send to Discord"
  },
  "sessionTarget": "isolated",
  "delivery": {
    "mode": "announce",
    "to": "discord-user-id"
  }
}

Delivery Modes

  • sessionTarget: main: Injects into current session
  • sessionTarget: isolated: Runs in background, announces result
  • delivery.mode: announce: Posts to specified channel/user
  • delivery.mode: none: Silent execution

Use Cases from Your Setup

Daily OpenRouter Usage Report

  • Schedule: Daily at 16:00 UTC (23:00 Jakarta)
  • Action: Generates cost summary (USD + IDR)
  • Delivery: Discord DM

Infrastructure Monitoring

  • Schedule: Every 6 hours
  • Action: Check k3s pod status
  • Delivery: Alert only on issues

Expense Tracking (n8n Integration)

  • Trigger: Cron or n8n webhook
  • Action: Process expense data
  • Delivery: Spreadsheet update + notification

Best Practices

  1. Use isolated sessions for long-running tasks
  2. Set appropriate timeouts: Default 600s, increase for heavy tasks
  3. Include error handling: Failed jobs should notify
  4. Delivery to specific channels: Don't spam main session
  5. Clean up old jobs: Remove one-shots after execution

Constraints

  • main session target requires systemEvent payload
  • isolated session target requires agentTurn payload
  • Maximum context messages: 10 for job execution