Cron jobs (Gateway scheduler)
Cron vs Heartbeat? See Cron vs Heartbeat for guidance on when to use each.Cron is the Gateway’s built-in scheduler. It persists jobs, wakes the agent at the right time, and can optionally deliver output back to a chat. If you want “run this every morning” or “poke the agent in 20 minutes”, cron is the mechanism. Troubleshooting: /automation/troubleshooting
TL;DR
- Cron runs inside the Gateway (not inside the model).
- Job definitions persist in the Gateway
cron_jobstable. On first start after upgrade the Gateway imports~/.openclaw/cron/jobs.json(orcron.store) into that table so restarts do not lose schedules. - Two execution styles:
- Main session: enqueue an agent.turn (
kindcron). They do not call the heartbeat runner. - Isolated: run a dedicated agent turn in
cron:<jobId>, with delivery (announce by default or none). Isolated jobs stay isolated unless they wake/nudge the named main session.
- Main session: enqueue an agent.turn (
- Wakeups are first-class:
wakeMode: "now"runs recurring main-session turns immediately unless the lane is busy; exact-time (schedule.kind: "at") turns park instead of skipping. For main-session jobswakeMode: "next-heartbeat"delivers on the next main-lane idle (publishes immediately when the lane is idle at fire time, otherwise parks and runs once the lane frees up) — isolated jobs always run at fire time, andwakeModeonly controls the post-run main-session wake — not a heartbeat tick. - Webhook posting is per job via
delivery.mode = "webhook"+delivery.to = "<url>". - Legacy fallback remains for stored jobs with
notify: truewhencron.webhookis set, migrate those jobs to webhook delivery mode.
Quick start (actionable)
Create a one-shot reminder, verify it exists, and run it immediately:- Open Cron Jobs in the operations console.
- Choose a job type:
- Timeline message for a main-session reminder.
- Assistant task for an isolated agent turn.
- Check first, then nudge for a wake-gate job that only nudges when the check finds work.
- Set the schedule, prompt/check text, delivery target, and optional advanced settings.
- Save the job, then select it to review recent runs.
- Use Run now to test a job immediately, or Run if due to test only the due-time path.
Tool-call equivalents (Gateway cron tool)
For the canonical JSON shapes and examples, see JSON schema for tool calls. The agent-facing cron tool deliberately cannot set or patchidentity — identity attribution is
operator-only (CLI, gateway RPC, Web UI), so an agent cannot escalate its own runs to a user’s identity.
Identity is also only supported on isolated agent-turn jobs; see
Identity attribution.
Web UI workflow
The Web UI is the recommended path when you are configuring cron by hand. It groups the rawsessionTarget and payload.kind fields into human-facing job types, so you do not need to
remember internal pairings.
Desktop layout:
- The left pane lists jobs and filters.
- The right pane shows the selected job, recent runs, settings coverage, and actions.
- Edit opens the job configuration in a drawer. The list and recent runs stay visible while you review the job.
- Jobs shows the scheduled jobs list.
- Runs shows recent events for the selected job.
- Settings shows the selected job configuration and coverage notes.
Manual runs from the Web UI
Run now usescron.run with mode: "force". It bypasses only the schedule due-time check.
It still respects payload validity, wake gates, already-running protection, heartbeat/runtime
guards, and delivery constraints. A disabled job is not run: the result is
{ ok: true, ran: false, reason: "disabled" } rather than already-running. A successful
click can still create a Skipped run when one of those other guards says the job should
not execute.
Run if due uses cron.run with mode: "due". It runs only when the schedule is currently due.
For Check first, then nudge jobs, the test action evaluates the wake gate now. A skipped result
with wake-gate-empty means the check found no work, so no nudge was sent.
If the manual run or scheduled run is cancelled, cron forwards the cancellation signal into the
wake-gate check. An accepted nudge follows its own lifecycle and is not cancelled by job abort.
Cancelled checks resolve as a failed/skipped
run instead of leaving a command or model gate running after the cron job has stopped.
Where cron jobs are stored
Cron job definitions live in the Gateway session store as acron_jobs table
(sibling to task_runs). The table is created for both SQLite and Postgres
session backends. On Postgres, every epoch-ms column (created_at_ms,
updated_at_ms, next_run_at_ms, running_at_ms, last_run_at_ms,
last_duration_ms, last_failure_alert_at_ms) is BIGINT. A guarded
ALTER ... TYPE BIGINT runs on Gateway start if an older table still has
32-bit integer on those columns. Definitions also carry a created_by_json
column (SQLite TEXT, Postgres JSONB) holding the createdBy provenance
stamp (see Jobs); the column is added automatically on Gateway start.
Nullable owner_user_id, owner_org_id and space_id columns are also added
on start for the upcoming resource-ownership model; nothing reads or writes them yet.
On first start after upgrade, the Gateway imports
~/.openclaw/cron/jobs.json (or cron.store if you set it) into that table
with every row migrated = false, then the table is the source of truth.
cron.store remains a valid config key and the import path. After import,
cron add / edit / remove / list / run read and write the table.
Hand-editing jobs.json while the Gateway is running was already unsupported;
after cutover it also has no effect. Emptying cron_jobs and restarting
re-imports jobs.json (including jobs added after the first import) and
resets migrated to false. Prefer wednesdayai cron add/edit or the
Gateway cron.* methods.
A cut-over job (migrated = true) is claimed through the task pipeline and is
not selected by the legacy timer. Two Gateway processes cannot both fire the
same job. Each pipeline fire leaves a task_runs row with trigger_source
cron (see Task operations). After downtime, enabled
migrated jobs that became due while the Gateway was down catch up at the next
start: at least one fire per missed occurrence (duplicate delivery is
accepted; see F-2026-08-18-01), with idempotency key
cron-run:<jobId>:<nextRunAtMs>.
Restart the Gateway after upgrade so the table is created and import runs
(Linux: systemctl --user restart openclaw-gateway; macOS:
wednesdayai gateway restart --deep).
Beginner-friendly overview
Think of a cron job as: when to run + what to do.-
Choose a schedule
- One-shot reminder →
schedule.kind = "at"(CLI:--at) - Repeating job →
schedule.kind = "every"orschedule.kind = "cron" - If your ISO timestamp omits a timezone, it is treated as UTC.
- One-shot reminder →
-
Choose where it runs
sessionTarget: "main"→ enqueue an agent.turn (kindcron) on the main session.sessionTarget: "isolated"→ run a dedicated agent turn incron:<jobId>. Isolated jobs stay isolated unless they wake/nudge the named main session.
-
Choose the payload
- Timeline message →
sessionTarget: "main"+payload.kind = "systemEvent" - Assistant task →
sessionTarget: "isolated"+payload.kind = "agentTurn" - Check first, then nudge →
sessionTarget: "main"+payload.kind = "wakeGate"
- Timeline message →
schedule.kind = "at") delete after they finish by default — on success,
and on an error that is not retried. Set deleteAfterRun: false to keep them (they will disable
instead).
Concepts
Jobs
A cron job is a stored record with:- a schedule (when it should run),
- a payload (what it should do),
- optional delivery mode (
announce,webhook, ornone). - optional agent binding (
agentId): run the job under a specific agent; if missing or unknown, the gateway falls back to the default agent. - a creator stamp (
createdBy), set by the Gateway when the job is created: the creating connection’sclientId, plusclientMode,clientDisplayName,clientVersion, anddeviceIdwhen the client reported them. The CLI shows up ascli, the agentcrontool asgateway-client/agent:<agentId>(gateway-client/agenton older jobs), and the Web UI asopenclaw-control-ui. It is read-only (cron.addandcron.updatereject it), diagnostic only, and absent on jobs created before it existed.
jobId (used by CLI/Gateway APIs).
In agent tool calls, jobId is canonical; legacy id is accepted for compatibility.
One-shot jobs auto-delete after success or a terminal error by default; set deleteAfterRun: false
to keep them.
Schedules
Cron supports three schedule kinds:at: one-shot timestamp viaschedule.at(ISO 8601).every: fixed interval (ms).cron: 5-field cron expression (or 6-field with seconds) with optional IANA timezone.
croner. If a timezone is omitted, the Gateway host’s
local timezone is used.
To reduce top-of-hour load spikes across many gateways, WednesdayAI applies a
deterministic per-job stagger window of up to 5 minutes for recurring
top-of-hour expressions (for example 0 * * * *, 0 */2 * * *). Fixed-hour
expressions such as 0 7 * * * remain exact.
For any cron schedule, you can set an explicit stagger window with schedule.staggerMs
(0 keeps exact timing). CLI shortcuts:
--stagger 30s(or1m,5m) to set an explicit stagger window.--exactto forcestaggerMs = 0.
Main vs isolated execution
Cron exposes three user-facing job types:Timeline message:sessionTarget: "main"withpayload.kind: "systemEvent".Assistant task:sessionTarget: "isolated"withpayload.kind: "agentTurn".Check first, then nudge:sessionTarget: "main"withpayload.kind: "wakeGate".
Main session jobs (timeline messages and wake gates)
Main jobs enqueue an agent.turn (kind cron). They do not call the heartbeat runner.
Timeline message jobs use payload.kind = "systemEvent". Check first, then nudge jobs
use payload.kind = "wakeGate" to evaluate a gate/check first and only nudge when
there is work to do.
wakeMode: "now"(default): attempt immediate delivery. If the main lane is busy, recurring jobs skip the turn (busypolicyskip), while exact-time (schedule.kind: "at") jobs park it withbusy: "delay"so a one-shot run is not lost.wakeMode: "next-heartbeat": deliver on the next main-lane idle, not a heartbeat tick. At fire time the payload publishes immediately when the main lane is idle; when the lane is busy it parks and delivers once the lane goes idle.
wakeMode selects the busy policy on the enqueued agent turn for when the main
lane is occupied at fire time:
skip(the enqueue default, used bywakeMode: "now"on recurring jobs): nothing is published and the run is recorded as skipped.delay(selected bywakeMode: "next-heartbeat"or an exact-time schedule): when the main lane is idle the turn is enqueued immediately like any other policy. Only when the lane is actually busy is the turn parked, and then it is accepted only after it is persisted inbus_work_itemswith theacceptedBusyDelaymarker (per-session cap 32; a 33rd is rejected and the run records an error). It releases FIFO once the main lane goes idle, or after 10 minutes (AGENT_TURN_DELAY_MAX_WAIT_MS). On Gateway restart, recovery re-arms only those producer-accepted pending rows; it does not execute at boot. Overflow and invalid work are rejected before acceptance and are never recorded as a successful skip.run: publish and claim immediately even while the lane is busy. There is no preemption — the turn’s model work serializes behind the in-flight command on the serial main lane and starts as soon as the lane permits.
session-runs rows (kind cron,
status completed/failed); read them via the sessions.runs.list Gateway RPC.
Cron does not require heartbeat config.
See Heartbeat.
Isolated jobs (dedicated cron sessions)
Isolated jobs run a dedicated agent turn in sessioncron:<jobId>.
Key behaviors:
- Prompt is prefixed with
[cron:<jobId> <job name>]for traceability. - Each run starts a fresh session id (no prior conversation carry-over).
- Default behavior: if
deliveryis omitted, isolated jobs announce a summary (delivery.mode = "announce"). delivery.modechooses what happens:announce: deliver a summary to the target channel and post a brief summary to the main session.webhook: POST the finished event payload todelivery.towhen the finished event includes a summary.none: internal only (no delivery, no main-session summary).
- Isolated jobs stay isolated unless they wake/nudge the named main session.
- The isolated turn itself always runs at fire time;
wakeModeonly controls the post-run main-session wake and never starts a heartbeat run for the job:now: wake the main session immediately after the run so it picks up the summary.next-heartbeat: do not wake the main session; the summary surfaces with the next main-session activity.
agentTurn jobs are claimed as durable agent.turn work inside the
Gateway, then executed by the in-process agent-turn runner. The runner writes a
session-runs row with kind: "cron" before execution starts, then marks that
row completed or failed through ack/nack. A crash mid-turn therefore leaves
a durable record that recovery treats as a cron run, not as a chat turn. Chat
replies still run as a direct in-process turn with streaming; they do not go
through this claim path. Heartbeat ticks enqueue their own agent.turn (kind heartbeat).
A gateway restart waits for in-flight claimed cron turns the same way it waits
for other active runs (confirm drain, or use force).
See Agent-turn runner for the developer contract.
Cron outcomes as agent turns
Four residual cron outcomes enqueue and claimagent.turn directly through
produceCronAgentTurn. They do not call the heartbeat runner and they do not
create heartbeat session-run rows:
Non-sentinel text from these turns reaches the configured delivery target.
NO_REPLY and HEARTBEAT_OK stay silent. Named agents (agentId on the job)
run under that agent’s merged heartbeat configuration (model, identity, context,
delivery), not the global defaults alone.
Payload shapes (what runs)
Three payload kinds are supported:systemEvent: main-session only, enqueued as an agent.turn (kindcron).agentTurn: isolated-session only, runs a dedicated agent turn.wakeGate: main-session only, evaluates a gate/check and nudges only when there is work.
agentTurn fields:
message: required text prompt.model/thinking: optional overrides (see below).timeoutSeconds: optional timeout override.
delivery.mode:none|announce|webhook.delivery.channel:lastor a specific channel.delivery.to: channel-specific target (announce) or webhook URL (webhook mode).delivery.bestEffort: avoid failing the job if announce delivery fails.
delivery.channel/delivery.to
to target the chat instead. When delivery.mode = "none", no summary is posted to the main session.
If delivery is omitted for isolated jobs, WednesdayAI defaults to announce.
Common wakeGate fields:
gate.kind:commandormodel.- Command gate:
gate.commandis required;gate.cwdandgate.timeoutMsare optional. - Model gate:
gate.prompt,gate.model,gate.provider,gate.lightContext, andgate.timeoutMsare optional. reason: optional nudge reason used for the main-session signal type.
timeoutMs is omitted, command and model gates use
30000 ms. Command gates parse only the last non-empty stdout line as
{ "wakeAgent": true|false, "text"?: string, "data"?: unknown }; non-zero exit, timeout, invalid
JSON, or wakeAgent !== true records the run as skipped with wake-gate-empty.
Announce delivery flow
Whendelivery.mode = "announce", cron delivers directly via the outbound channel adapters.
The main agent is not spun up to craft or forward the message.
Behavior details:
- Content: delivery uses the isolated run’s outbound payloads (text/media) with normal chunking and channel formatting.
- Heartbeat-only responses (
HEARTBEAT_OKwith no real content) are not delivered. - If the isolated run already sent a message to the same target via the message tool, delivery is skipped to avoid duplicates.
- Missing or invalid delivery targets fail the job unless
delivery.bestEffort = true. - A short summary is posted to the main session only when
delivery.mode = "announce". - Isolated jobs stay isolated unless they wake/nudge the named main session.
wakeModenext-heartbeatskips the immediate post-run wake of the main session (the summary surfaces with the next main-session activity); it is not a heartbeat tick.
Webhook delivery flow
Whendelivery.mode = "webhook", cron posts the finished event payload to delivery.to when the finished event includes a summary.
Behavior details:
- The endpoint must be a valid HTTP(S) URL.
- No channel delivery is attempted in webhook mode.
- No main-session summary is posted in webhook mode.
- If
cron.webhookTokenis set, auth header isAuthorization: Bearer <cron.webhookToken>. - Deprecated fallback: stored legacy jobs with
notify: truestill post tocron.webhook(if configured), with a warning so you can migrate todelivery.mode = "webhook".
Identity attribution
identity links a job’s runs to a registered person instead of leaving them as anonymous system runs.
It is a session.identityLinks key, matched case-insensitively; an unmatched or absent value leaves
runs unattributed. There is never a default or fallback identity.
Supported job shape: isolated agent-turn jobs only (sessionTarget: "isolated" with
payload.kind: "agentTurn" — the Assistant task job type). Only that shape carries
job identity into the run.
Main-session jobs (systemEvent timeline messages and wakeGate checks) enqueue an
agent.turn (kind cron, or a nudge after a positive wake-gate) and do not call the
heartbeat runner. Identity attribution is still only honoured on isolated agent-turn
jobs, so those main-session turns do not carry a job identity. Because the attribution
could never be honoured there, cron rejects identity on those
shapes on both create and update instead of accepting it and dropping it. Switching an attributed job
to a main-session shape is rejected too; clear the identity in the same edit (identity: null,
or --clear-identity) if you want to make that change.
Jobs created before this validation existed could carry an identity on a main-session shape. Cron
never blocks you from managing such a job: it strips the orphaned attribution when the job store is
loaded (logging a warning with the job id), and an edit that does not itself re-assert the identity —
enabled: false from the list toggle, a rename, a schedule change — succeeds and drops the orphan
rather than failing. Re-adding an identity to an unsupported shape is still rejected.
Caveat: attribution only applies to agents backed by the embedded agent runtime. When an agent is
backed by a CLI provider, cron runs the turn through the CLI runner, which has no sender-identity
plumbing — those runs stay unattributed even on a supported job shape.
Identity is operator-only: it can be set from the CLI, the gateway RPC surface, and the Web UI, but
never from the agent-facing cron tool.
Model and thinking overrides
Isolated jobs (agentTurn) can override the model and thinking level:
model: Provider/model string (e.g.,anthropic/claude-sonnet-4-20250514) or alias (e.g.,opus)thinking: Thinking level (off,minimal,low,medium,high,xhigh; GPT-5.2 + Codex models only)
model on main-session jobs too, but it changes the shared main
session model. We recommend model overrides only for isolated jobs to avoid
unexpected context shifts.
Resolution priority:
- Job payload override (highest)
- Hook-specific defaults (e.g.,
hooks.gmail.model) - Agent config default
Delivery (channel + target)
Isolated jobs can deliver output to a channel via the top-leveldelivery config:
delivery.mode:announce(channel delivery),webhook(HTTP POST), ornone.delivery.channel:whatsapp/telegram/discord/slack/mattermost(plugin) /signal/imessage/last.delivery.to: channel-specific recipient target.
announce delivery is only valid for isolated jobs (sessionTarget: "isolated").
webhook delivery is valid for both main and isolated jobs.
If delivery.channel or delivery.to is omitted, cron can fall back to the main session’s
“last route” (the last place the agent replied).
When the agent creates a job from a chat session and omits a target, the cron tool captures the
delivery target at creation time. The creating turn’s own route (channel, target, account id) is
the source of record; the session’s deliveryContext (channel, target and account id) and its last
channel + last target pair are fallbacks, used as one coherent tuple each — fields are never mixed
across sources. Cron selects the first complete source in that order. If the selected source does
not match the requested delivery.channel, the target stays unset; cron does not fall through to
another source. The captured values are stored on job.delivery, so they survive restarts and the
job keeps announcing to the chat it was created from even if that session is later reset.
Threads are preserved at capture: a Telegram topic folds into the :topic: target form
(-1001234567890:topic:77). Channels whose delivery.to cannot carry a thread (for example Slack
thread timestamps) are not captured at all — run-time resolution keeps using the thread session
entry, and the fail-closed rule below applies if that entry is deleted. A parent-conversation
target is never persisted for a thread-origin job.
Retained limits (jobs created before capture existed, and legacy fallbacks):
- A legacy to-less job still follows the session’s latest route at run time; the creating-turn route cannot be reconstructed for it.
- Jobs without their own
sessionKeyuse the main session’s last route. - On WhatsApp, implicit delivery still substitutes an allowlisted recipient when the resolved target is outside the allowlist.
- To make a job’s destination immutable, pin
delivery.channelanddelivery.to(anddelivery.accountIdfor multi-account channels).
- At job creation/update (gateway RPC, CLI, and the agent tool all pass through the same
validated service boundary): an unprefixed
delivery.tothat equals asession.identityLinkskey is rejected with an error naming the key and theidentity:fix, and anidentity:<key>that does not match any configured key is rejected. Gateway RPC clients receive these asINVALID_REQUESTerrors. AnnouncefailureDestinationtargets are validated the same way; webhook URLs and targets retained underdelivery.mode: "none"are dormant and not namespace-checked (a webhook URL keeps its HTTP validation). A key that exists but has no unique link for the delivery channel is accepted here — channel resolution has not happened yet — and fails at the next check. An update that disables the job (enabled: false), switches the delivery tomode: "none", or clears the target always succeeds so operators can repair. Clearing the target is an explicit empty value —cron edit <id> --to ""(CLI), or a patch withdelivery.to: ""(agent tool / RPC) — not an omitted field; the persisted job drops thedelivery.toproperty. - At delivery time (when the channel is resolved):
identity:<key>resolves to that key’s single linked id for the delivery channel. An unknown key, or a key without exactly one link for the channel, fails with an error naming the identity and channel. An unprefixed target that now equals a configured key fails closed instead of silently rerouting. - A rejection is terminal for routing even when
delivery.bestEffort = true: the target rejection is recorded (errorKind: delivery-target) and the summary is not relayed to the main session or heartbeat destination. This holds even when the run itself also produced a fatal agent error payload: the run is then reported as an execution error, and the delivery status isnot-delivered, never a fallback summary. Failure notifications inherit the job’s own session provenance; a failure alert that inherits the primary route also inherits its account id unless explicitly overridden. - Repair: update the job with
delivery.channelplus a channel-nativedelivery.to, or with theidentity:<key>form oncesession.identityLinksis configured.
sessionKey and that session’s entry no longer exists (for example
after a reset or a deleted store), a delivery with no explicit delivery.to fails the job with
cron delivery for session <key> failed: its session entry no longer exists and the job has no explicit target; re-add the job with delivery.channel and delivery.to (also logged at error level
under the cron/delivery subsystem, with the job id) instead of falling back to the main session’s
last route, which could belong to a different conversation.
Target format reminders:
- Slack/Discord/Mattermost (plugin) targets should use explicit prefixes (e.g.
channel:<id>,user:<id>) to avoid ambiguity. - Telegram topics should use the
:topic:form (see below). - With
session.identityLinksconfigured, only theidentity:<key>form is accepted for linked people; an unprefixed key fails closed as described above.
Telegram delivery targets (topics / forum threads)
Telegram supports forum topics viamessage_thread_id. For cron delivery, you can encode
the topic/thread into the to field:
-1001234567890(chat id only)-1001234567890:topic:123(preferred: explicit topic marker)-1001234567890:123(shorthand: numeric suffix)
telegram:... / telegram:group:... are also accepted:
telegram:group:-1001234567890:topic:123
JSON schema for tool calls
Use these shapes when calling Gatewaycron.* tools directly (agent tool calls or RPC).
CLI flags accept human durations like 20m, but tool calls should use an ISO 8601 string
for schedule.at and milliseconds for schedule.everyMs.
cron.add params
One-shot, main session job (system event):schedule.kind:at(at),every(everyMs), orcron(expr, optionaltz).schedule.ataccepts ISO 8601 (timezone optional; treated as UTC when omitted).everyMsis milliseconds.sessionTargetmust be"main"or"isolated"and must matchpayload.kind.wakeGateis valid only withsessionTarget: "main".- Optional fields:
agentId,identity(operator RPC only — not accepted from the agent-facing cron tool),description,enabled,deleteAfterRun(defaults to true forat),delivery. createdByis not accepted oncron.addorcron.update: the Gateway stamps it from the creating connection and rejects a client-supplied value withINVALID_REQUEST.identity: asession.identityLinkskey (matched case-insensitively). Only accepted onsessionTarget: "isolated"withpayload.kind: "agentTurn"; the call is rejected on any other shape. On match, runs carry that canonical identity as the requester identity (identitySource: "job-config"); unmatched or absent values leave runs as unattributed system runs — there is never a default or fallback identity. See Identity attribution.wakeModedefaults to"now"when omitted.
cron.update params
jobIdis canonical;idis accepted for compatibility.- Use
agentId: nullin the patch to clear an agent binding. identityfollows the same semantics as oncron.add(operator RPC only — not accepted from the agent-facing cron tool, and only valid on isolatedagentTurnjobs); useidentity: nullin the patch to clear identity attribution. A patch that moves an attributed job to an unsupported shape is rejected unless the same patch clearsidentity.
cron.run and cron.remove params
Storage & history
- Job store:
cron_jobstable in the Gateway session store (SQLite or Postgres). Postgres epoch-ms columns areBIGINT(SQLiteINTEGERis already 64-bit). Thecreated_by_jsoncolumn (SQLiteTEXT, PostgresJSONB) stores thecreatedByprovenance stamp and is added automatically on Gateway start. Nullableowner_user_id,owner_org_idandspace_idcolumns (reserved for resource ownership, currently unused) are added the same way.~/.openclaw/cron/jobs.jsonis the import source on first start (override withcron.store). After import the table is truth; the file is not the claim path. - Run history:
~/.openclaw/cron/runs/<jobId>.jsonl(JSONL, auto-pruned by size and line count). Pipeline fires also appear inwednesdayai task status --task cron-run. - Isolated cron run sessions are tombstoned from the session index by
cron.sessionRetention(default24h; setfalseto disable). Their conversation rows stay in the session database until enforce-mode session retention ends them (see Session Management / Maintenance). - Override import path:
cron.storein config.
Retry policy
When a job fails, WednesdayAI classifies errors as transient (retryable) or permanent (disable immediately).Transient errors (retried)
- Rate limit (429, too many requests, resource exhausted)
- Network errors (timeout, ECONNRESET, fetch failed, socket)
- Server errors (5xx)
- Cloudflare-related errors
Permanent errors (no retry)
- Auth failures (invalid API key, unauthorized)
- Config or validation errors
- Other non-transient errors
Default behavior (no config)
One-shot jobs (schedule.kind: "at"):
- On transient error: retry up to 3 times with exponential backoff (30s → 1m → 5m), then treat it as terminal.
- On terminal error (permanent, or retries exhausted): disable immediately, or delete if
deleteAfterRun: true. The failed run stays inopenclaw cron runs --id <id>either way. - On success or skip: disable (or delete on success if
deleteAfterRun: true).
cron / every):
- On any error: apply exponential backoff (30s → 1m → 5m → 15m → 60m) before the next scheduled run.
- Job stays enabled; backoff resets after the next successful run.
cron.retry to override these defaults (see Configuration).
Configuration
cron.runLog.maxBytes: max run-log file size before pruning.cron.runLog.keepLines: when pruning, keep only the newest N lines.- Both apply to
cron/runs/<jobId>.jsonlfiles.
- Preferred: set
delivery.mode: "webhook"withdelivery.to: "https://..."per job. - Webhook URLs must be valid
http://orhttps://URLs. - When posted, payload is the cron finished event JSON.
- If
cron.webhookTokenis set, auth header isAuthorization: Bearer <cron.webhookToken>. - If
cron.webhookTokenis not set, noAuthorizationheader is sent. - Deprecated fallback: stored legacy jobs with
notify: truestill usecron.webhookwhen present.
cron.enabled: false(config)OPENCLAW_SKIP_CRON=1(env)
Maintenance
Cron has two built-in maintenance paths: isolated run-session retention and run-log pruning.Defaults
cron.sessionRetention:24h(setfalseto disable run-session pruning)cron.runLog.maxBytes:2_000_000bytescron.runLog.keepLines:2000
How it works
- Isolated runs create session entries (
...:cron:<jobId>:run:<uuid>) in the SQL session store. - The reaper removes expired run-session index rows older than
cron.sessionRetention(a tombstone only — stored conversation history is never deleted and stays readable); no per-run transcript files or archives are written. - After each run append,
cron/runs/<jobId>.jsonlis size-checked:- if file size exceeds
runLog.maxBytes, it is trimmed to the newestrunLog.keepLineslines.
- if file size exceeds
Performance caveat for high volume schedulers
High-frequency cron setups can generate large run-session and run-log footprints. Maintenance is built in, but loose limits can still create avoidable IO and cleanup work. What to watch:- long
cron.sessionRetentionwindows with many isolated runs - high
cron.runLog.keepLinescombined with largerunLog.maxBytes - many noisy recurring jobs writing to the same
cron/runs/<jobId>.jsonl
- keep
cron.sessionRetentionas short as your debugging/audit needs allow - keep run logs bounded with moderate
runLog.maxBytesandrunLog.keepLines - move noisy background jobs to isolated mode with delivery rules that avoid unnecessary chatter
- review growth periodically with
wednesdayai cron runsand adjust retention before logs become large
Customize examples
Keep run sessions for a week and allow bigger run logs:CLI quickstart
One-shot reminder (UTC ISO, auto-delete after success):--due to only run when due):
reason: "disabled"); it is not reported as
already running. A manual run may correctly record Skipped.
Edit an existing job (patch fields):
Gateway API surface
cron.list,cron.status,cron.add,cron.update,cron.remove- Jobs returned by
cron.list/cron.statuscarry a read-onlycreatedByprovenance stamp (see the creator stamp under Jobs). cron.run(force or due),cron.runsFor immediate system events without a job, usewednesdayai system event.
Troubleshooting
Nothing runs
- Check cron is enabled:
cron.enabledandOPENCLAW_SKIP_CRON. - Check the Gateway is running continuously (cron runs inside the Gateway process).
- For
cronschedules: confirm timezone (--tz) vs the host timezone. - After upgrade, restart the Gateway so the
cron_jobstable is created (and Postgres*_mscolumns are widened toBIGINTif needed) andjobs.jsonimport runs (Linux:systemctl --user restart openclaw-gateway; macOS:wednesdayai gateway restart --deep). [cron] failed to start: value "..." is out of range for type integermeans the live Postgres table still has 32-bitintegeron an epoch-ms column. Restart on a build that includes the guardedALTER. Confirm withinformation_schema.columns(data_type = biginton every*_mscolumn) and a row count or job-ID check that matches the expected jobs injobs.json(zero rows is success when the import source is empty).- If
tasks.enabledisfalse, jobs already flipped tomigrated = truestay on the pipeline claim path and will not fire until the pipeline is enabled again. Unmigrated jobs keep using the legacy timer. - After downtime, enabled migrated jobs that were due while the Gateway was
down fire once per missed occurrence at the next start. A disabled job
(
enabled: false) does not catch up and a forcedcron.runreturnsreason: "disabled". - Hand-editing
~/.openclaw/cron/jobs.jsonafter the first import does not change the table. Usewednesdayai cron add/editorcron.*methods.
A job I didn’t create keeps appearing
- Check who created it:
wednesdayai cron list --all --json | jq '.jobs[] | {name, createdBy}', the Created by column inwednesdayai cron list, or the job inspector in the Web UI. createdBy.clientId: "cli"means something on a host ranwednesdayai cron add(a script, hook, or shell);gateway-client/agent:<agentId>means an agent’scrontool created it (gateway-client/agenton older entries).- The Gateway log line
cron: job createdcarries the samecreatedByplusactor,deviceId,clientIp, andconnIdfor that connection.cron: job updatedandcron: job removedcarry the same connection fields.
Main job requires payload.kind="systemEvent"
- Use the Timeline message job type for plain main-session reminders.
- Use Check first, then nudge for a main-session
wakeGate. - Assistant task jobs must stay isolated because they use
payload.kind = "agentTurn".
A next-heartbeat reminder vanished after restart
- Delayed main-session turns persist in
bus_work_itemsbefore acceptance. - After a Gateway restart, recovery re-arms only producer-accepted pending
rows (
acceptedBusyDelay). Checksessions.runs.listandwednesdayai task status --task cron-run. - A
:skippedor:rejected-overflowwork id is not an accepted reminder. Overflow (more than 32 parked turns on one session) records an error.
wake-gate-empty
- The Check first, then nudge gate ran and found no work.
- The job correctly recorded
Skippedinstead of nudging.
A recurring job keeps delaying after failures
- WednesdayAI applies exponential retry backoff for recurring jobs after consecutive errors: 30s, 1m, 5m, 15m, then 60m between retries.
- Backoff resets automatically after the next successful run.
- One-shot (
at) jobs retry transient errors (rate limit, network, server_error) up to 3 times with backoff; permanent errors disable immediately. See Retry policy.
Telegram delivers to the wrong place
- For forum topics, use
-100…:topic:<id>so it’s explicit and unambiguous. - If you see
telegram:...prefixes in logs or stored “last route” targets, that’s normal; cron delivery accepts them and still parses topic IDs correctly.
Subagent announce delivery retries
- When a subagent run completes, the gateway announces the result to the requester session.
- If the announce flow returns
false(e.g. requester session is busy), the gateway retries up to 3 times with tracking viaannounceRetryCount. - Announces older than 5 minutes past
endedAtare force-expired to prevent stale entries from looping indefinitely. - If you see repeated announce deliveries in logs, check the subagent registry for entries with high
announceRetryCountvalues.
A job turned itself off or lost its delivery settings
The SQLite and Postgres stores check each job’s stored JSON when they load it.- If the payload or schedule is unreadable or missing a required field, the job is disabled and
its payload or schedule is replaced with a placeholder (an empty system event, or every 60 s).
The job still shows in
wednesdayai cron list --all, so you can fix or remove it. Log line:cron: disabled job <id>: malformed payload_json(orschedule_json). - If the delivery or failure-alert settings are unreadable, they are dropped and the job keeps
running without them. Log line:
cron: dropped malformed delivery_json on job <id>(orfailure_alert_json). - Each warning is logged once per job and column, under subsystem
cron/stored-job, with the original column text (first 500 characters) inraw. The repair is saved on the next store write, so that log line is the only record of the original value. - Payload or schedule kinds this version does not know (written by a newer version) are left untouched.
raw from the log, then restore the job with wednesdayai cron edit <id> ... and
wednesdayai cron enable <id>, or delete it with wednesdayai cron rm <id>.