> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Cron Jobs

# Cron jobs (Gateway scheduler)

> **Cron vs Heartbeat?** See [Cron vs Heartbeat](https://docs.wednesdayai.dev/next/users/automation/cron-vs-heartbeat.md) 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](https://docs.wednesdayai.dev/next/users/automation/troubleshooting.md)

## 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:

```bash theme={"dark"}
wednesdayai cron add \
  --name "Reminder" \
  --at "2026-02-01T16:00:00Z" \
  --session main \
  --system-event "Reminder: check the cron docs draft" \
  --wake now \
  --delete-after-run

wednesdayai cron list
wednesdayai cron run <job-id>
wednesdayai cron runs --id <job-id>
```

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:

```bash theme={"dark"}
wednesdayai cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize overnight updates." \
  --announce \
  --channel slack \
  --to "channel:C1234567890"
```

## Tool-call equivalents (Gateway cron tool)

For the canonical JSON shapes and examples, see [JSON schema for tool calls](https://docs.wednesdayai.dev/next/users/automation/cron-jobs.md#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](https://docs.wednesdayai.dev/next/users/automation/cron-jobs.md#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](#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](https://docs.wednesdayai.dev/next/admin/gateway/tasks.md)). 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](https://docs.wednesdayai.dev/next/admin/gateway/heartbeat.md).

#### 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](https://docs.wednesdayai.dev/next/developers/plugins/agent-turn-runner.md) 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:

| Outcome | When | Busy policy |
| - | - | - |
| Isolated summary | Isolated job posts a short main-session summary after the run | `delay` (awaits completion) |
| Failure alert | Isolated announce delivery failed and the fallback must notify | `delay` |
| Auto-disable notice | A job is disabled after repeated schedule errors | `delay` |
| Cron wake RPC | `cron.wake` / `wake({ mode, text })` | `now` → `run`; `next-heartbeat` → `delay` |

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):

```json theme={"dark"}
{
  "name": "Reminder",
  "schedule": { "kind": "at", "at": "2026-02-01T16:00:00Z" },
  "sessionTarget": "main",
  "wakeMode": "now",
  "payload": { "kind": "systemEvent", "text": "Reminder text" },
  "deleteAfterRun": true
}
```

Recurring, isolated job with delivery:

```json theme={"dark"}
{
  "name": "Morning brief",
  "schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "America/Los_Angeles" },
  "sessionTarget": "isolated",
  "wakeMode": "next-heartbeat",
  "payload": {
    "kind": "agentTurn",
    "message": "Summarize overnight updates."
  },
  "delivery": {
    "mode": "announce",
    "channel": "slack",
    "to": "channel:C1234567890",
    "bestEffort": true
  }
}
```

Recurring, main-session wake-gate job:

```json theme={"dark"}
{
  "name": "Inbox gate",
  "schedule": { "kind": "every", "everyMs": 900000 },
  "sessionTarget": "main",
  "wakeMode": "now",
  "payload": {
    "kind": "wakeGate",
    "reason": "inbox",
    "gate": {
      "kind": "command",
      "command": "node ./scripts/inbox-check.mjs",
      "timeoutMs": 10000
    }
  }
}
```

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](https://docs.wednesdayai.dev/next/users/automation/cron-jobs.md#identity-attribution).
* `wakeMode` defaults to `"now"` when omitted.

### cron.update params

```json theme={"dark"}
{
  "jobId": "job-123",
  "patch": {
    "enabled": false,
    "schedule": { "kind": "every", "everyMs": 3600000 }
  }
}
```

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

```json theme={"dark"}
{ "jobId": "job-123", "mode": "force" }
```

```json theme={"dark"}
{ "jobId": "job-123" }
```

## 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](https://docs.wednesdayai.dev/next/developers/concepts/session.md#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](https://docs.wednesdayai.dev/next/users/automation/cron-jobs.md#configuration)).

## Configuration

```json5 theme={"dark"}
{
  cron: {
    enabled: true, // default true
    store: "~/.openclaw/cron/jobs.json", // import source; table is truth after first start
    maxConcurrentRuns: 1, // default 1
    // Optional: override retry policy for one-shot jobs
    retry: {
      maxAttempts: 3,
      backoffMs: [60000, 120000, 300000],
      retryOn: ["rate_limit", "network", "server_error"],
    },
    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
    webhookToken: "replace-with-dedicated-webhook-token", // optional bearer token for webhook mode
    sessionRetention: "24h", // duration string or false
    runLog: {
      maxBytes: "2mb", // default 2_000_000 bytes
      keepLines: 2000, // default 2000
    },
  },
}
```

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:

```json5 theme={"dark"}
{
  cron: {
    sessionRetention: "7d",
    runLog: {
      maxBytes: "10mb",
      keepLines: 5000,
    },
  },
}
```

Disable isolated run-session pruning but keep run-log pruning:

```json5 theme={"dark"}
{
  cron: {
    sessionRetention: false,
    runLog: {
      maxBytes: "5mb",
      keepLines: 3000,
    },
  },
}
```

Tune for high-volume cron usage (example):

```json5 theme={"dark"}
{
  cron: {
    sessionRetention: "12h",
    runLog: {
      maxBytes: "3mb",
      keepLines: 1500,
    },
  },
}
```

## CLI quickstart

One-shot reminder (UTC ISO, auto-delete after success):

```bash theme={"dark"}
wednesdayai cron add \
  --name "Send reminder" \
  --at "2026-01-12T18:00:00Z" \
  --session main \
  --system-event "Reminder: submit expense report." \
  --wake now \
  --delete-after-run
```

One-shot reminder (main session, wake immediately):

```bash theme={"dark"}
wednesdayai cron add \
  --name "Calendar check" \
  --at "20m" \
  --session main \
  --system-event "Next heartbeat: check calendar." \
  --wake now
```

Recurring isolated job (announce to WhatsApp):

```bash theme={"dark"}
wednesdayai 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"
```

Recurring cron job with explicit 30-second stagger:

```bash theme={"dark"}
wednesdayai cron add \
  --name "Minute watcher" \
  --cron "0 * * * * *" \
  --tz "UTC" \
  --stagger 30s \
  --session isolated \
  --message "Run minute watcher checks." \
  --announce
```

Recurring isolated job (deliver to a Telegram topic):

```bash theme={"dark"}
wednesdayai cron add \
  --name "Nightly summary (topic)" \
  --cron "0 22 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize today; send to the nightly topic." \
  --announce \
  --channel telegram \
  --to "-1001234567890:topic:123"
```

Isolated job with model and thinking override:

```bash theme={"dark"}
wednesdayai 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"
```

Agent selection (multi-agent setups):

```bash theme={"dark"}
# Pin a job to agent "ops" (falls back to default if that agent is missing)
wednesdayai cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops

# Switch or clear the agent on an existing job
wednesdayai cron edit <jobId> --agent ops
wednesdayai cron edit <jobId> --clear-agent
```

Identity attribution (link job runs to a person). Only valid on isolated assistant-task jobs —
see [Identity attribution](https://docs.wednesdayai.dev/next/users/automation/cron-jobs.md#identity-attribution):

```bash theme={"dark"}
# Attribute runs to the identityLinks key "alice" (runs stay unattributed if the key does not match)
wednesdayai cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --identity alice

# Switch or clear the identity on an existing job
wednesdayai cron edit <jobId> --identity alice
wednesdayai cron edit <jobId> --clear-identity
```

Manual run (force is the default, use `--due` to only run when due):

```bash theme={"dark"}
wednesdayai cron run <jobId>
wednesdayai cron run <jobId> --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):

```bash theme={"dark"}
wednesdayai cron edit <jobId> \
  --message "Updated prompt" \
  --model "opus" \
  --thinking low
```

Force an existing cron job to run exactly on schedule (no stagger):

```bash theme={"dark"}
wednesdayai cron edit <jobId> --exact
```

Run history:

```bash theme={"dark"}
wednesdayai cron runs --id <jobId> --limit 50
```

Immediate system event without creating a job:

```bash theme={"dark"}
wednesdayai system event --mode now --text "Next heartbeat: check battery."
```

## 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](#jobs)).
* `cron.run` (force or due), `cron.runs`
  For immediate system events without a job, use [`wednesdayai system event`](https://docs.wednesdayai.dev/next/users/cli/system).

## 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](https://docs.wednesdayai.dev/next/users/automation/cron-jobs.md#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>`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.