Skip to main content

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_jobs table. On first start after upgrade the Gateway imports ~/.openclaw/cron/jobs.json (or cron.store) into that table so restarts do not lose schedules.
  • Two execution styles:
    • Main session: enqueue an agent.turn (kind cron). 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.
  • 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 jobs wakeMode: "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, and wakeMode only 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: true when cron.webhook is set, migrate those jobs to webhook delivery mode.

Quick start (actionable)

Create a one-shot reminder, verify it exists, and run it immediately:
You can do the same from the Web UI:
  1. Open Cron Jobs in the operations console.
  2. 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.
  3. Set the schedule, prompt/check text, delivery target, and optional advanced settings.
  4. Save the job, then select it to review recent runs.
  5. Use Run now to test a job immediately, or Run if due to test only the due-time path.
Schedule a recurring isolated job with delivery:

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 patch identity — 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 raw sessionTarget 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.
Mobile layout:
  • Jobs shows the scheduled jobs list.
  • Runs shows recent events for the selected job.
  • Settings shows the selected job configuration and coverage notes.
The Web UI exposes the supported editable settings for normal cron operation: name, description, enabled state, schedule, timezone, exact timing/stagger, job type, prompt or check text, routing, delivery, timeout, model/thinking where applicable, identity attribution (assistant-task jobs only), remove-after-run, and failure alerts. Fields that are inherited, unsupported for the selected job type, or only editable through raw API/store paths are called out in the settings coverage panel instead of being silently hidden.

Manual runs from the Web UI

Run now uses cron.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 a cron_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.
  1. Choose a schedule
    • One-shot reminder → schedule.kind = "at" (CLI: --at)
    • Repeating job → schedule.kind = "every" or schedule.kind = "cron"
    • If your ISO timestamp omits a timezone, it is treated as UTC.
  2. Choose where it runs
    • sessionTarget: "main" → enqueue an agent.turn (kind cron) on the main session.
    • sessionTarget: "isolated" → run a dedicated agent turn in cron:<jobId>. Isolated jobs stay isolated unless they wake/nudge the named main session.
  3. 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"
Optional: one-shot jobs (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, or none).
  • 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’s clientId, plus clientMode, clientDisplayName, clientVersion, and deviceId when the client reported them. The CLI shows up as cli, the agent cron tool as gateway-client/agent:<agentId> (gateway-client/agent on older jobs), and the Web UI as openclaw-control-ui. It is read-only (cron.add and cron.update reject it), diagnostic only, and absent on jobs created before it existed.
Jobs are identified by a stable 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 via schedule.at (ISO 8601).
  • every: fixed interval (ms).
  • cron: 5-field cron expression (or 6-field with seconds) with optional IANA timezone.
Cron expressions use 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 (or 1m, 5m) to set an explicit stagger window.
  • --exact to force staggerMs = 0.

Main vs isolated execution

Cron exposes three user-facing job types:
  • Timeline message: sessionTarget: "main" with payload.kind: "systemEvent".
  • Assistant task: sessionTarget: "isolated" with payload.kind: "agentTurn".
  • Check first, then nudge: sessionTarget: "main" with payload.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 (busy policy skip), while exact-time (schedule.kind: "at") jobs park it with busy: "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.
Under the hood, 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 by wakeMode: "now" on recurring jobs): nothing is published and the run is recorded as skipped.
  • delay (selected by wakeMode: "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 in bus_work_items with the acceptedBusyDelay marker (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.
Completed and failed main-session turns are recorded as 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 session cron:<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 delivery is omitted, isolated jobs announce a summary (delivery.mode = "announce").
  • delivery.mode chooses 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 to delivery.to when 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; wakeMode only 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.
Use isolated jobs for noisy, frequent, or “background chores” that shouldn’t spam your main chat history. Isolated 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 claim agent.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 (kind cron).
  • agentTurn: isolated-session only, runs a dedicated agent turn.
  • wakeGate: main-session only, evaluates a gate/check and nudges only when there is work.
Common agentTurn fields:
  • message: required text prompt.
  • model / thinking: optional overrides (see below).
  • timeoutSeconds: optional timeout override.
Delivery config:
  • delivery.mode: none | announce | webhook.
  • delivery.channel: last or a specific channel.
  • delivery.to: channel-specific target (announce) or webhook URL (webhook mode).
  • delivery.bestEffort: avoid failing the job if announce delivery fails.
Announce delivery suppresses messaging tool sends for the run; use 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: command or model.
  • Command gate: gate.command is required; gate.cwd and gate.timeoutMs are optional.
  • Model gate: gate.prompt, gate.model, gate.provider, gate.lightContext, and gate.timeoutMs are optional.
  • reason: optional nudge reason used for the main-session signal type.
Wake-gate timeouts are in milliseconds. If 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

When delivery.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_OK with 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. wakeMode next-heartbeat skips 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

When delivery.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.webhookToken is set, auth header is Authorization: Bearer <cron.webhookToken>.
  • Deprecated fallback: stored legacy jobs with notify: true still post to cron.webhook (if configured), with a warning so you can migrate to delivery.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)
Note: You can set 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:
  1. Job payload override (highest)
  2. Hook-specific defaults (e.g., hooks.gmail.model)
  3. Agent config default

Delivery (channel + target)

Isolated jobs can deliver output to a channel via the top-level delivery config:
  • delivery.mode: announce (channel delivery), webhook (HTTP POST), or none.
  • 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 sessionKey use 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.channel and delivery.to (and delivery.accountId for multi-account channels).
Fail-closed delivery target rules — what is checked when:
  • At job creation/update (gateway RPC, CLI, and the agent tool all pass through the same validated service boundary): an unprefixed delivery.to that equals a session.identityLinks key is rejected with an error naming the key and the identity: fix, and an identity:<key> that does not match any configured key is rejected. Gateway RPC clients receive these as INVALID_REQUEST errors. Announce failureDestination targets are validated the same way; webhook URLs and targets retained under delivery.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 to mode: "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 with delivery.to: "" (agent tool / RPC) — not an omitted field; the persisted job drops the delivery.to property.
  • 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 is not-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.channel plus a channel-native delivery.to, or with the identity:<key> form once session.identityLinks is configured.
If an isolated job names its own 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.identityLinks configured, only the identity:<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 via message_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)
Prefixed targets like telegram:... / telegram:group:... are also accepted:
  • telegram:group:-1001234567890:topic:123

JSON schema for tool calls

Use these shapes when calling Gateway cron.* 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):
Recurring, isolated job with delivery:
Recurring, main-session wake-gate job:
Notes:
  • schedule.kind: at (at), every (everyMs), or cron (expr, optional tz).
  • schedule.at accepts ISO 8601 (timezone optional; treated as UTC when omitted).
  • everyMs is milliseconds.
  • sessionTarget must be "main" or "isolated" and must match payload.kind.
  • wakeGate is valid only with sessionTarget: "main".
  • Optional fields: agentId, identity (operator RPC only — not accepted from the agent-facing cron tool), description, enabled, deleteAfterRun (defaults to true for at), delivery.
  • createdBy is not accepted on cron.add or cron.update: the Gateway stamps it from the creating connection and rejects a client-supplied value with INVALID_REQUEST.
  • identity: a session.identityLinks key (matched case-insensitively). Only accepted on sessionTarget: "isolated" with payload.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.
  • wakeMode defaults to "now" when omitted.

cron.update params

Notes:
  • jobId is canonical; id is accepted for compatibility.
  • Use agentId: null in the patch to clear an agent binding.
  • identity follows the same semantics as on cron.add (operator RPC only — not accepted from the agent-facing cron tool, and only valid on isolated agentTurn jobs); use identity: null in the patch to clear identity attribution. A patch that moves an attributed job to an unsupported shape is rejected unless the same patch clears identity.

cron.run and cron.remove params

Storage & history

  • Job store: cron_jobs table in the Gateway session store (SQLite or Postgres). Postgres epoch-ms columns are BIGINT (SQLite INTEGER is already 64-bit). The created_by_json column (SQLite TEXT, Postgres JSONB) stores the createdBy provenance stamp and is added automatically on Gateway start. Nullable owner_user_id, owner_org_id and space_id columns (reserved for resource ownership, currently unused) are added the same way. ~/.openclaw/cron/jobs.json is the import source on first start (override with cron.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 in wednesdayai task status --task cron-run.
  • Isolated cron run sessions are tombstoned from the session index by cron.sessionRetention (default 24h; set false to disable). Their conversation rows stay in the session database until enforce-mode session retention ends them (see Session Management / Maintenance).
  • Override import path: cron.store in 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 in openclaw cron runs --id <id> either way.
  • On success or skip: disable (or delete on success if deleteAfterRun: true).
Recurring jobs (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.
Configure cron.retry to override these defaults (see Configuration).

Configuration

Run-log pruning behavior:
  • 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>.jsonl files.
Webhook behavior:
  • Preferred: set delivery.mode: "webhook" with delivery.to: "https://..." per job.
  • Webhook URLs must be valid http:// or https:// URLs.
  • When posted, payload is the cron finished event JSON.
  • If cron.webhookToken is set, auth header is Authorization: Bearer <cron.webhookToken>.
  • If cron.webhookToken is not set, no Authorization header is sent.
  • Deprecated fallback: stored legacy jobs with notify: true still use cron.webhook when present.
Disable cron entirely:
  • 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 (set false to disable run-session pruning)
  • cron.runLog.maxBytes: 2_000_000 bytes
  • cron.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>.jsonl is size-checked:
    • if file size exceeds runLog.maxBytes, it is trimmed to the newest runLog.keepLines lines.

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.sessionRetention windows with many isolated runs
  • high cron.runLog.keepLines combined with large runLog.maxBytes
  • many noisy recurring jobs writing to the same cron/runs/<jobId>.jsonl
What to do:
  • keep cron.sessionRetention as short as your debugging/audit needs allow
  • keep run logs bounded with moderate runLog.maxBytes and runLog.keepLines
  • move noisy background jobs to isolated mode with delivery rules that avoid unnecessary chatter
  • review growth periodically with wednesdayai cron runs and adjust retention before logs become large

Customize examples

Keep run sessions for a week and allow bigger run logs:
Disable isolated run-session pruning but keep run-log pruning:
Tune for high-volume cron usage (example):

CLI quickstart

One-shot reminder (UTC ISO, auto-delete after success):
One-shot reminder (main session, wake immediately):
Recurring isolated job (announce to WhatsApp):
Recurring cron job with explicit 30-second stagger:
Recurring isolated job (deliver to a Telegram topic):
Isolated job with model and thinking override:
Agent selection (multi-agent setups):
Identity attribution (link job runs to a person). Only valid on isolated assistant-task jobs — see Identity attribution:
Manual run (force is the default, use --due to only run when due):
Forced manual run 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 (reason: "disabled"); it is not reported as already running. A manual run may correctly record Skipped. Edit an existing job (patch fields):
Force an existing cron job to run exactly on schedule (no stagger):
Run history:
Immediate system event without creating a job:

Gateway API surface

  • cron.list, cron.status, cron.add, cron.update, cron.remove
  • Jobs returned by cron.list / cron.status carry a read-only createdBy provenance stamp (see the creator stamp under Jobs).
  • cron.run (force or due), cron.runs For immediate system events without a job, use wednesdayai system event.

Troubleshooting

Nothing runs

  • Check cron is enabled: cron.enabled and OPENCLAW_SKIP_CRON.
  • Check the Gateway is running continuously (cron runs inside the Gateway process).
  • For cron schedules: confirm timezone (--tz) vs the host timezone.
  • After upgrade, restart the Gateway so the cron_jobs table is created (and Postgres *_ms columns are widened to BIGINT if needed) and jobs.json import runs (Linux: systemctl --user restart openclaw-gateway; macOS: wednesdayai gateway restart --deep).
  • [cron] failed to start: value "..." is out of range for type integer means the live Postgres table still has 32-bit integer on an epoch-ms column. Restart on a build that includes the guarded ALTER. Confirm with information_schema.columns (data_type = bigint on every *_ms column) and a row count or job-ID check that matches the expected jobs in jobs.json (zero rows is success when the import source is empty).
  • If tasks.enabled is false, jobs already flipped to migrated = true stay 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 forced cron.run returns reason: "disabled".
  • Hand-editing ~/.openclaw/cron/jobs.json after the first import does not change the table. Use wednesdayai cron add/edit or cron.* 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 in wednesdayai cron list, or the job inspector in the Web UI.
  • createdBy.clientId: "cli" means something on a host ran wednesdayai cron add (a script, hook, or shell); gateway-client/agent:<agentId> means an agent’s cron tool created it (gateway-client/agent on older entries).
  • The Gateway log line cron: job created carries the same createdBy plus actor, deviceId, clientIp, and connId for that connection. cron: job updated and cron: job removed carry 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_items before acceptance.
  • After a Gateway restart, recovery re-arms only producer-accepted pending rows (acceptedBusyDelay). Check sessions.runs.list and wednesdayai task status --task cron-run.
  • A :skipped or :rejected-overflow work 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 Skipped instead 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 via announceRetryCount.
  • Announces older than 5 minutes past endedAt are 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 announceRetryCount values.

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 (or schedule_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> (or failure_alert_json).
  • Each warning is logged once per job and column, under subsystem cron/stored-job, with the original column text (first 500 characters) in raw. 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.
To fix: read 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>.