Complete reference for openclaw cron, scheduling one-shot and recurring agent jobs, targeting sessions and channels, managing job lifecycle, and querying run history.
What is Openclaw Cron?
The cron subsystem is OpenClaw’s built-in job scheduler, it lets you define timed agent turns that run on a recurring schedule, at a specific timestamp, or at a relative offset
Unlike a system cron, these jobs are Gateway-native: they’re stored in the Gateway, run against configured agent sessions, and can deliver output directly to a chat channel without any extra plumbing. All cron commands are Gateway RPC calls, meaning they work locally or against a remote Gateway over WebSocket.
Finding the Right Command
Every cron add call needs three things, when to run (–at, –every, or –cron), where to run (–session main or –session isolated), and what to do (–message or –system-event). Start with Core Commands for the full command reference, then jump to Examples for copy-paste patterns covering one-shot reminders, daily recurring jobs, model overrides, and multi-agent targeting. If you’re editing an existing job, cron edit patches specific fields without requiring a full recreate.
Gateway RPC — Remote Flags
All cron commands are Gateway RPC calls and accept the following remote targeting flags. These are additive to every command below.
All openclaw cron commands accept remote flags to target a specific Gateway instance:
–url | –token | –timeout | –expect-final
Core Commands
Full command reference. Aliases are shown in the second column.
| Command | Badge | Description |
|---|---|---|
| cron status | read-only | Shows whether the cron scheduler is enabled and displays the next upcoming wake time. |
| cron list | read-only | Lists all configured cron jobs in a table format. Append –all to include disabled jobs, or –json for machine-readable output. |
cron add / create | creates | Creates a new scheduled job. Requires a schedule flag, a session flag, and a message or event flag. See §3 for required flags breakdown. |
cron edit <id> | patches | Modifies an existing job by patching specific fields, e.g. changing the schedule, message, delivery target, or agent. Does not require recreating the job. |
cron rm <id> | deletes | Deletes a scheduled job permanently. Aliases: remove, delete. |
cron enable <id> | mutates | Enables a specific job without deleting and recreating it. Paired with cron disable <id> to toggle jobs on and off. |
cron disable <id> | mutates | Disables a specific job, suspending execution without removing the job definition. |
cron run <id> | exec | Manually forces a job to run immediately, regardless of its schedule. Append –due to only execute if the job is currently past-due. |
cron runs --id <id> | read-only | Displays the run history for a specific job. Limit output rows with --limit <n>. |
Required Flags for cron add
Every cron add call must answer three questions. Missing any one of these will fail validation.
| When — Schedule Defines the trigger timing. Pass exactly one. –at “<offset|timestamp>”–every “<interval>”–cron “<expr>” | Where — Session Defines which session context the agent runs in. Pass one. –session main–session isolated | What — Payload Defines what the agent receives. Pass one. –message “<text>”–system-event “<text>” |
–session main appends the event to the persistent main session, the agent retains prior context. –session isolated spins up a fresh, stateless agent turn every time, safer for autonomous jobs where you don’t want context bleed between runs.
Common Uses & Examples
Five working patterns. Copy, adjust the values in angle brackets and quotes, and run.
01 One-Shot Reminder (Main Session)
openclaw cron add --name "Calendar check" --at "20m" --session main --system-event "Next heartbeat: check calendar" --wake now
What this does: Adds an event to the main session and wakes the heartbeat runner immediately to process it. –at “20m” schedules it 20 minutes from now. Good for one-shot reminders that need to run in the context of an ongoing session.
02 Scheduled Recurring Job (Isolated Session)
openclaw cron add --name "Morning status" --cron "0 7 * * *" --tz "America/Los_Angeles" --session isolated --message "Summarize inbox + calendar for today" --announce --channel whatsapp --to "+15551234567"
What this does: Runs a completely isolated agent turn at 7:00 AM every day and announces the summary directly to a WhatsApp channel. –tz anchors the cron expression to a specific timezone, always include this for wall-clock schedules.
03 Advanced Job with Model Override
openclaw cron add --name "Deep analysis" --cron "0 6 * * 1" --tz "America/Los_Angeles" --session isolated --message "Weekly deep analysis of project progress" --model "opus" --thinking high --announce --channel whatsapp --to "+15551234567"
What this does: Runs every Monday at 6:00 AM with a model and thinking-level override. You can use a different model or thinking level for specific heavy-duty cron jobs without changing the agent’s default configuration.
04 Editing an Existing Job
# Change delivery channel openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890" # Turn off delivery completely openclaw cron edit <job-id> --no-deliver
What this does: Patches specific fields of an existing job without recreating it. Use cron list –json to get the <job-id> if you don’t have it. –no-deliver silently drops the output instead of routing it to a channel.
05 Pinning to a Specific Agent (Multi-Agent Setups)
# Assign to agent "ops" openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops # Switch an existing job to another agent openclaw cron edit <jobId> --agent main
What this does: If you run multiple agents, –agent <id> pins the job to a specific one. Without it, the job runs against the default agent. Use cron edit –agent to reassign an existing job without deleting and recreating it.
