Cron

text

Copy

openclaw cron

Manage cron jobs for the Gateway scheduler.

Sessions

accepts , , , or .

Session keys

Isolated session semantics

Delivery

and preview the resolved delivery route. For , the preview shows whether the route resolved from the main or current session, or will fail closed.

Delivery ownership

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

• The agent can send directly using the
  text

  Copy

  message
  tool when a chat route is available.
• text

  Copy

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

  Copy

  webhook
  posts the finished payload to a URL.
• text

  Copy

  none
  disables runner fallback delivery.

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

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.

Failure delivery

Failure notifications resolve in this order:

1. text

   Copy

   delivery.failureDestination
   on the job.
2. Global
   text

   Copy

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

Note: isolated cron runs treat run-level agent failures as job errors even when no reply payload is produced, so model/provider failures still increment error counters and trigger failure notifications.

Scheduling

One-shot jobs

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

Recurring jobs

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

Skipped runs are tracked separately from execution errors. They do not affect retry backoff, but

can opt failure alerts into repeated skipped-run notifications.

For isolated jobs that target a local configured model provider, cron runs a lightweight provider preflight before starting the agent turn. Loopback, private-network, and

providers are probed at ; local OpenAI-compatible providers such as vLLM, SGLang, and LM Studio are probed at . If the endpoint is unreachable, the run is recorded as and retried on a later schedule; matching dead endpoints are cached for 5 minutes to avoid many jobs hammering the same local server.

Note: cron job definitions live in

, while pending runtime state lives in . If is edited externally, the Gateway reloads changed schedules and clears stale pending slots; formatting-only rewrites do not clear the pending slot.

Manual runs

returns as soon as the manual run is queued. Successful responses include . Use to follow the eventual outcome.

Models

selects an allowed model for the job.

Cron

is a job primary, not a chat-session override. That means:

• Configured model fallbacks still apply when the selected job model fails.
• Per-job payload
  text

  Copy

  fallbacks
  replaces the configured fallback list when present.
• An empty per-job fallback list (
  text

  Copy

  fallbacks: []
  in the job payload/API) makes the cron run strict.
• When a job has
  text

  Copy

  --model
  but no fallback list is configured, OpenClaw passes an explicit empty fallback override so the agent primary is not appended as a hidden retry target.

Isolated cron model precedence

Isolated cron resolves the active model in this order:

1. Gmail-hook override.
2. Per-job
   text

   Copy

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

applies by default, but a stored session override still wins over config.

Live model switch retries

If an isolated run throws

, 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 (

or ), 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

, , and approval-binding refusal phrases.

and run history surface the denial reason instead of reporting a blocked command as .

Retention

Retention and pruning are controlled in config:

• text

  Copy

  cron.sessionRetention
  (default
  text

  Copy

  24h
  ) prunes completed isolated run sessions.
• text

  Copy

  cron.runLog.maxBytes
  and
  text

  Copy

  cron.runLog.keepLines
  prune
  text

  Copy

  ~/.openclaw/cron/runs/<jobId>.jsonl
  .

Migrating older jobs

Common edits

Update delivery settings without changing the message:

bash
Copy
openclaw cron edit <job-id> --announce --channel telegram --to "123456789"

Disable delivery for an isolated job:

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

Enable lightweight bootstrap context for an isolated job:

bash
Copy
openclaw cron edit <job-id> --light-context

Announce to a specific channel:

bash
Copy
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"

Announce to a Telegram forum topic:

bash
Copy
openclaw cron edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42

Create an isolated job with lightweight bootstrap context:

bash
Copy
openclaw cron add \
  --name "Lightweight morning brief" \
  --cron "0 7 * * *" \
  --session isolated \
  --message "Summarize overnight updates." \
  --light-context \
  --no-deliver

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

Common admin commands

Manual run and inspection:

bash
Copy
openclaw cron list
openclaw cron show <job-id>
openclaw cron run <job-id>
openclaw cron run <job-id> --due
openclaw cron runs --id <job-id> --limit 50

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

Agent and session retargeting:

bash
Copy
openclaw cron edit <job-id> --agent ops
openclaw cron edit <job-id> --clear-agent
openclaw cron edit <job-id> --session current
openclaw cron edit <job-id> --session "session:daily-brief"

warns when is omitted on agent-turn jobs and falls back to the default agent (). Pass at create time to pin a specific agent.

Delivery tweaks:

bash
Copy
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
openclaw cron edit <job-id> --best-effort-deliver
openclaw cron edit <job-id> --no-best-effort-deliver
openclaw cron edit <job-id> --no-deliver

Related

• CLI reference
• Scheduled tasks