Scheduled Tasks / Cron Jobs (OpenClaw Docs)

Source: https://docs.openclaw.ai/automation/cron-jobs

Summary

OpenClaw's built-in scheduler runs inside the Gateway process. Persists jobs at ~/.openclaw/cron/jobs.json, creates background task records for every execution, auto-deletes one-shot jobs after success, and manages browser cleanup for isolated runs.

Schedule Types

• Timestamps default to UTC unless timezone specified.
• Recurring top-of-hour expressions auto-stagger by up to 5 minutes unless --exact or custom --stagger applied.
• Day-of-month + day-of-week fields: OR logic (fires when either matches), not AND.

Execution Styles

Main session jobs enqueue system events with optional wake triggers.
Isolated jobs run dedicated agent turns with fresh sessions.
Custom sessions persist context across recurring runs.

Isolated Job Payload Options

• --message: prompt text (required)
• --model / --thinking: override defaults
• --light-context: skip workspace bootstrap
• --tools: restrict available tools (e.g., exec,read)

Model selection precedence: Gmail hook override → per-job payload → stored session override → agent/default.

Delivery Modes

Channel formats: --channel telegram --to "-1001234567890", channel:<id>, user:<id> for Slack/Discord/Mattermost. Forum topics: -1001234567890:topic:123.

Failure destination: configured via cron.failureDestination (global) or job.delivery.failureDestination (per-job); falls back to primary announce target.

Task Reconciliation

Active cron task stays live while the cron runtime still tracks that job as running, even if old session rows exist. Tasks marked "lost" after a 5-minute grace window.

CLI Reference

openclaw cron add --name "Reminder" --at "2026-02-01T16:00:00Z" \
  --session main --system-event "Check docs" --wake now --delete-after-run

openclaw cron add --name "Morning brief" --cron "0 7 * * *" \
  --tz "America/Los_Angeles" --session isolated \
  --message "Summarize overnight updates" --announce --channel slack --to "channel:C123"

openclaw cron list
openclaw cron edit <id>
openclaw cron run <id>
openclaw cron run <id> --due          # run only if scheduled time reached
openclaw cron runs --id <id> --limit 50
openclaw cron remove <id>

Inbound Webhooks

Enable in config:

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

Authentication: Authorization: Bearer <token> or x-openclaw-token: <token> header. Query-string tokens rejected.

Endpoints:

• POST /hooks/wake — enqueue system event (text, optional mode)
• POST /hooks/agent — run isolated turn (message required)
• POST /hooks/<name> — custom mapped hooks via hooks.mappings

Security: keep behind loopback/trusted proxy; set hooks.allowedAgentIds; keep hooks.allowRequestSessionKey=false unless needed.

Gmail PubSub Integration

openclaw webhooks gmail setup --account openclaw@gmail.com

Writes config, enables preset, uses Tailscale Funnel for push endpoint. Gateway auto-starts gog gmail watch serve on boot. Supports per-Gmail model override via hooks.gmail.model.

Configuration

{
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1,
    retry: {
      maxAttempts: 3,
      backoffMs: [60000, 120000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
    },
    sessionRetention: "24h",
    runLog: { maxBytes: "2mb", keepLines: 2000 },
  },
}

Disable: set cron.enabled: false or OPENCLAW_SKIP_CRON=1.

Retry behavior: one-shot jobs retry up to 3× on transient errors (exponential backoff); recurring jobs use escalating backoff (30s to 60m). Old sessions pruned after retention window; run logs auto-pruned by size/line count.

Troubleshooting

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

Common issues:

• Cron not firing: verify cron.enabled, check Gateway running, confirm timezone.
• Fired but no delivery: delivery mode may be none; validate channel config and auth.
• Timezone gotchas: --at without TZ = UTC; cron without --tz uses host timezone; heartbeat activeHours uses configured resolution.