summary: "CLI reference for `openclaw cron` (schedule and run background jobs)"

read_when:

- You want scheduled jobs and wakeups

- You’re debugging cron execution and logs

- You are debugging cron execution and logs

title: "Cron"

---

# `openclaw cron`

Manage cron jobs for the Gateway scheduler.

Related:

<Tip>

Run `openclaw cron --help` for the full command surface. See [Cron jobs](/automation/cron-jobs) for the conceptual guide.

</Tip>

- Cron jobs: [Cron jobs](/automation/cron-jobs)

## Sessions

Tip: run `openclaw cron --help` for the full command surface.

`--session` accepts `main`, `isolated`, `current`, or `session:<id>`.

Note: `openclaw cron list` and `openclaw cron show <job-id>` preview the

resolved delivery route. For `channel: "last"`, the preview shows whether the

route resolved from the main/current session or will fail closed.

<AccordionGroup>

<Accordion title="Session keys">

- `main` binds to the agent's main session.

- `isolated` creates a fresh transcript and session id for each run.

- `current` binds to the active session at creation time.

- `session:<id>` pins to an explicit persistent session key.

</Accordion>

<Accordion title="Isolated session semantics">

Isolated runs reset ambient conversation context. Channel and group routing, send/queue policy, elevation, origin, and ACP runtime binding are reset for the new run. Safe preferences and explicit user-selected model or auth overrides can carry across runs.

</Accordion>

</AccordionGroup>

Note: isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep

output internal. `--deliver` remains as a deprecated alias for `--announce`.

## Delivery

Note: isolated cron chat delivery is shared. `--announce` is runner fallback

delivery for the final reply; `--no-deliver` disables that fallback but does

not remove the agent's `message` tool when a chat route is available.

`openclaw cron list` and `openclaw cron show <job-id>` preview the resolved delivery route. For `channel: "last"`, the preview shows whether the route resolved from the main or current session, or will fail closed.

Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-run` to keep them.

<Note>

Isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep output internal. `--deliver` remains as a deprecated alias for `--announce`.

</Note>

Note: `--session` supports `main`, `isolated`, `current`, and `session:<id>`.

Use `current` to bind to the active session at creation time, or `session:<id>` for

an explicit persistent session key.

### Delivery ownership

Note: `--session isolated` creates a fresh transcript/session id for each run.

Safe preferences and explicit user-selected model/auth overrides can carry, but

ambient conversation context does not: channel/group routing, send/queue policy,

elevation, origin, and ACP runtime binding are reset for the new isolated run.

Isolated cron chat delivery is shared between the agent and the runner:

Note: for one-shot CLI jobs, offset-less `--at` datetimes are treated as UTC unless you also pass

`--tz <iana>`, which interprets that local wall-clock time in the given timezone.

- The agent can send directly using the `message` tool when a chat route is available.

- `announce` fallback-delivers the final reply only when the agent did not send directly to the resolved target.

- `webhook` posts the finished payload to a URL.

- `none` disables runner fallback delivery.

Note: recurring jobs now use exponential retry backoff after consecutive errors (30s → 1m → 5m → 15m → 60m), then return to normal schedule after the next successful run.

`--announce` is runner fallback delivery for the final reply. `--no-deliver` disables that fallback but does not remove the agent's `message` tool when a chat route is available.

Note: `openclaw cron run` now returns as soon as the manual run is queued for execution. Successful responses include `{ ok: true, enqueued: true, runId }`; use `openclaw cron runs --id <job-id>` to follow the eventual outcome.

Reminders created from an active chat preserve the live chat delivery target for fallback announce delivery. Internal session keys may be lowercase; do not use them as a source of truth for case-sensitive provider IDs such as Matrix room IDs.

Note: `openclaw cron run <job-id>` force-runs by default. Use `--due` to keep the

older "only run if due" behavior.

### Failure delivery

Note: isolated cron turns suppress stale acknowledgement-only replies. If the

first result is just an interim status update and no descendant subagent run is

responsible for the eventual answer, cron re-prompts once for the real result

before delivery.

Failure notifications resolve in this order:

Note: if an isolated cron run returns only the silent token (`NO_REPLY` /

`no_reply`), cron suppresses direct outbound delivery and the fallback queued

summary path as well, so nothing is posted back to chat.

1. `delivery.failureDestination` on the job.

2. Global `cron.failureDestination`.

3. The job's primary announce target (when no explicit failure destination is set).

Note: isolated cron runs prefer structured execution-denial metadata from the

embedded run, then fall back to known denial markers in final output, such as

`SYSTEM_RUN_DENIED`, `INVALID_REQUEST`, and approval-binding refusal phrases.

`cron list` and run history surface the denial reason instead of reporting a

blocked command as `ok`.

<Note>

Main-session jobs may only use `delivery.failureDestination` when primary delivery mode is `webhook`. Isolated jobs accept it in all modes.

</Note>

Note: `cron add|edit --model ...` uses that selected allowed model for the job.

If the model is not allowed, cron warns and falls back to the job's agent/default

model selection instead. Configured fallback chains still apply, but a plain

model override with no explicit per-job fallback list no longer appends the

agent primary as a hidden extra retry target.

## Scheduling

Note: isolated cron model precedence is Gmail-hook override first, then per-job

`--model`, then any user-selected stored cron-session model override, then the

normal agent/default selection.

### One-shot jobs

Note: isolated cron fast mode follows the resolved live model selection. Model

config `params.fastMode` applies by default, but a stored session `fastMode`

override still wins over config.

`--at <datetime>` schedules a one-shot run. Offset-less datetimes are treated as UTC unless you also pass `--tz <iana>`, which interprets the wall-clock time in the given timezone.

Note: if an isolated run throws `LiveSessionModelSwitchError`, cron persists the

switched provider/model (and switched auth profile override when present) for

the active run before retrying. The outer retry loop is bounded to 2 switch

retries after the initial attempt, then aborts instead of looping forever.

<Note>

One-shot jobs delete after success by default. Use `--keep-after-run` to preserve them.

</Note>

Note: failure notifications use `delivery.failureDestination` first, then

global `cron.failureDestination`, and finally fall back to the job's primary

announce target when no explicit failure destination is configured.

### Recurring jobs

Note: retention/pruning is controlled in config:

Recurring jobs use exponential retry backoff after consecutive errors: 30s, 1m, 5m, 15m, 60m. The schedule returns to normal after the next successful run.

### Manual runs

`openclaw cron run` returns as soon as the manual run is queued. Successful responses include `{ ok: true, enqueued: true, runId }`. Use `openclaw cron runs --id <job-id>` to follow the eventual outcome.

<Note>

`openclaw cron run <job-id>` force-runs by default. Use `--due` to keep the older "only run if due" behavior.

</Note>

## Models

`cron add|edit --model <ref>` selects an allowed model for the job.

<Warning>

If the model is not allowed, cron warns and falls back to the job's agent or default model selection. Configured fallback chains still apply, but a plain model override with no explicit per-job fallback list no longer appends the agent primary as a hidden extra retry target.

</Warning>

### Isolated cron model precedence

Isolated cron resolves the active model in this order:

1. Gmail-hook override.

2. Per-job `--model`.

3. Stored cron-session model override (when the user selected one).

4. Agent or default model selection.

### Fast mode

Isolated cron fast mode follows the resolved live model selection. Model config `params.fastMode` applies by default, but a stored session `fastMode` override still wins over config.

### Live model switch retries

If an isolated run throws `LiveSessionModelSwitchError`, cron persists the switched provider and model (and switched auth profile override when present) for the active run before retrying. The outer retry loop is bounded to two switch retries after the initial attempt, then aborts instead of looping forever.

## Run output and denials

### Stale acknowledgement suppression

Isolated cron turns suppress stale acknowledgement-only replies. If the first result is just an interim status update and no descendant subagent run is responsible for the eventual answer, cron re-prompts once for the real result before delivery.

### Silent token suppression

If an isolated cron run returns only the silent token (`NO_REPLY` or `no_reply`), cron suppresses both direct outbound delivery and the fallback queued summary path, so nothing is posted back to chat.

### Structured denials

Isolated cron runs prefer structured execution-denial metadata from the embedded run, then fall back to known denial markers in final output, such as `SYSTEM_RUN_DENIED`, `INVALID_REQUEST`, and approval-binding refusal phrases.

`cron list` and run history surface the denial reason instead of reporting a blocked command as `ok`.

## Retention

Retention and pruning are controlled in config:

- `cron.sessionRetention` (default `24h`) prunes completed isolated run sessions.

- `cron.runLog.maxBytes` + `cron.runLog.keepLines` prune `~/.openclaw/cron/runs/<jobId>.jsonl`.

- `cron.runLog.maxBytes` and `cron.runLog.keepLines` prune `~/.openclaw/cron/runs/<jobId>.jsonl`.

Upgrade note: if you have older cron jobs from before the current delivery/store format, run

`openclaw doctor --fix`. Doctor now normalizes legacy cron fields (`jobId`, `schedule.cron`,

top-level delivery fields including legacy `threadId`, payload `provider` delivery aliases) and migrates simple

`notify: true` webhook fallback jobs to explicit webhook delivery when `cron.webhook` is

configured.

## Migrating older jobs

<Note>

If you have cron jobs from before the current delivery and store format, run `openclaw doctor --fix`. Doctor normalizes legacy cron fields (`jobId`, `schedule.cron`, top-level delivery fields including legacy `threadId`, payload `provider` delivery aliases) and migrates simple `notify: true` webhook fallback jobs to explicit webhook delivery when `cron.webhook` is configured.

</Note>

## Common edits

`--light-context` applies to isolated agent-turn jobs only. For cron runs, lightweight mode keeps bootstrap context empty instead of injecting the full workspace bootstrap set.

Delivery ownership note:

- Isolated cron chat delivery is shared. The agent can send directly with the

`message` tool when a chat route is available.

- `announce` fallback-delivers the final reply only when the agent did not send

directly to the resolved target. `webhook` posts the finished payload to a URL.

`none` disables runner fallback delivery.

- Reminders created from an active chat preserve the live chat delivery target

for fallback announce delivery. Internal session keys may be lowercase; do not

use them as a source of truth for case-sensitive provider IDs such as Matrix

room IDs.

## Common admin commands

Manual run:

Manual run and inspection:

```bash

openclaw cron list

openclaw cron runs --id <job-id> --limit 50

```

`cron runs` entries include delivery diagnostics with the intended cron target,

the resolved target, message-tool sends, fallback use, and delivered state.

`cron runs` entries include delivery diagnostics with the intended cron target, the resolved target, message-tool sends, fallback use, and delivered state.

Agent/session retargeting:

Agent and session retargeting:

```bash

openclaw cron edit <job-id> --agent ops

openclaw cron edit <job-id> --no-deliver

```

Failure-delivery note:

- `delivery.failureDestination` is supported for isolated jobs.

- Main-session jobs may only use `delivery.failureDestination` when primary

delivery mode is `webhook`.

- If you do not set any failure destination and the job already announces to a

channel, failure notifications reuse that same announce target.

## Related

- [CLI reference](/cli)