Cron jobs
Cron is the Gateway’s built-in scheduler. It persists jobs, fires them at the right time, and can deliver output to a chat or webhook. Every “run this every morning” or “poke the agent in 20 minutes” is a cron job — cron runs inside the Gateway, not inside the model. Job execution goes through the task pipeline: each fire of a migrated job is acron-run task run.
Deciding between heartbeat and cron? The user-facing comparison lives at Reminders and schedules — Cron vs heartbeat; for your own scheduling decisions see Heartbeat.
All
cron.* config changes hot-apply — the Gateway restarts only the cron service in place when it detects the change. No Gateway restart is needed.Quick start
Config reference
All keys live undercron in openclaw.json.
Example — failure alerts to a Telegram chat after 3 consecutive failures, plus looser retention:
Job types
Cron exposes three job types, each a pairing of a session target and a payload kind:
Every cron outcome is produced as an agent turn — the isolated-run summary, failure alerts, auto-disable notices, and the post-run main-session wake are all enqueued through the
agent.turn machinery (see src/cron/service/agent-turn.ts). Cron never sends messages directly; delivery flows through the same backbone path as heartbeat and nudge turns.
- Schedules:
at(one-shot ISO timestamp; UTC when the timezone is omitted),every(fixed interval in ms),cron(5-field, or 6-field with seconds, with optional IANAtz; host-local timezone when omitted). - Stagger: recurring top-of-hour expressions (e.g.
0 * * * *) get a deterministic per-job offset in a 0–5 minute window. Override per job withschedule.staggerMs(--stagger 30s, or--exactfor 0). - Wake modes:
wakeMode: "now"(default) delivers immediately — a busy main lane skips the turn;wakeMode: "next-heartbeat"parks the delivery until the main lane goes idle. Isolated jobs always run at fire time;wakeModeonly controls the post-run main-session wake. - Delivery (isolated jobs):
announce(summary todelivery.channel/delivery.to, default whendeliveryis omitted),webhook(POST the finished event todelivery.to), ornone. Webhook mode is valid for main-session jobs too. - Model overrides: isolated jobs accept per-job
modelandthinking. Main-sessionmodeloverrides change the shared main session model — avoid them. - Identity attribution:
--identity <key>links runs to asession.identityLinkskey. IsolatedagentTurnjobs only; rejected on other shapes. Operator-only — the agent-facing cron tool can never set it. - Agent binding:
--agent <id>pins a job to an agent; missing or unknown ids fall back to the default agent. - One-shot (
at) jobs delete after success by default (deleteAfterRun: falsekeeps them, disabled).
Identity attribution
Key:identity on the job — default unset (a pure system run with no identity).
- Set it with
--identity <user>onopenclaw cron add(andcron edit, which also takes--clear-identityto unset it). The value must case-insensitively match asession.identityLinkskey at run time; isolatedagentTurnjobs only, and it is operator-set only — the agent-facing cron tool can never set it. - Identity-linked delivery targets: a
delivery.tovalue that is asession.identityLinkskey is resolved to that channel’s linked chat id at delivery time. An ambiguous or unlinked key is never remapped to a different id — it fails downstream as an unknown recipient (the one exception: WhatsApp implicit delivery still substitutes theallowFromentry).
Storage and the table cutover
Job definitions live in thecron_jobs table in the Gateway session store (SQLite or Postgres), sibling to task_runs. On first start after upgrade the Gateway imports ~/.openclaw/cron/jobs.json (or cron.store) into the table with every row migrated = false, then the table is the source of truth.
- After import,
cron add/edit/remove/list/runread and write the table. Hand-editingjobs.jsonwhile the Gateway runs has no effect. - Emptying
cron_jobsand restarting re-importsjobs.jsonand resetsmigrated. - A migrated job is claimed through the task pipeline (two Gateway processes cannot both fire it); each fire leaves a
task_runsrow with trigger sourcecron. After downtime, enabled migrated jobs catch up: at least one fire per missed occurrence (duplicate delivery accepted), keyedcron-run:<jobId>:<nextRunAtMs>. - Postgres: every epoch-ms column is
BIGINT; a guardedALTER ... TYPE BIGINTruns on Gateway start for older 32-bit tables. - Run history:
~/.openclaw/cron/runs/<jobId>.jsonl(auto-pruned bycron.runLog); pipeline fires also appear inwednesdayai task status --task cron-run.
systemctl --user restart openclaw-gateway; macOS: wednesdayai gateway restart --deep).
Retry behavior
Errors are classified transient (rate limit, network, server errors, Cloudflare) or permanent (auth, validation).- One-shot (
at) jobs: transient errors retry up tocron.retry.maxAttempts(default 3) with backoff 30s → 1m → 5m. Permanent errors disable immediately. On success or skip the job disables (or deletes whendeleteAfterRun). - Recurring (
cron/every) jobs: consecutive errors apply backoff 30s → 1m → 5m → 15m → 60m before the next scheduled run; the job stays enabled and backoff resets after the next success.
cron-run is intentionally maxAttempts: 1 so cron.retry stays the single operator-visible backoff — do not layer task retries on cron jobs.
Disable cron
cron.enabled: falsein configOPENCLAW_SKIP_CRON=1environment variable
Troubleshooting
Nothing runs
- Check
cron.enabledandOPENCLAW_SKIP_CRON; cron runs inside the Gateway process, so the Gateway must be up continuously. - After upgrade, restart the Gateway so the
cron_jobstable is created andjobs.jsonimports. [cron] failed to start: value "..." is out of range for type integermeans the Postgres table still has 32-bit epoch-ms columns — restart on a build with the guardedALTER.- For
cronschedules, confirm--tzvs the host timezone.
Main job requires payload.kind="systemEvent"
Timeline messages and wake gates are the main-session job types; assistant tasks must stay isolated (agentTurn). Pair the target and payload kind correctly.
wake-gate-empty
The check ran and found no work, so the run was correctly recorded as Skipped instead of nudging.
Telegram delivers to the wrong place
Forum topics must use the explicit form-100…:topic:<id> in the delivery target.
Related
- Task pipeline — the queue that executes
cron-run, budgets, and recovery - Heartbeat — heartbeat cadence and wake-gates on the heartbeat path
- Reminders and schedules — the user-facing guide to what these jobs do from chat