Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw cron
Manage cron jobs for the Gateway scheduler.
Sessions
--session accepts main, isolated, current, or session:<id>.
Session keys
Session keys
mainbinds to the agent’s main session.isolatedcreates a fresh transcript and session id for each run.currentbinds to the active session at creation time.session:<id>pins to an explicit persistent session key.
Isolated session semantics
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.
Delivery
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.
Isolated
cron add jobs default to --announce delivery. Use --no-deliver to keep output internal. --deliver remains as a deprecated alias for --announce.Delivery ownership
Isolated cron chat delivery is shared between the agent and the runner:- The agent can send directly using the
messagetool when a chat route is available. announcefallback-delivers the final reply only when the agent did not send directly to the resolved target.webhookposts the finished payload to a URL.nonedisables runner fallback delivery.
--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.
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:delivery.failureDestinationon the job.- Global
cron.failureDestination. - The job’s primary announce target (when no explicit failure destination is set).
Main-session jobs may only use
delivery.failureDestination when primary delivery mode is webhook. Isolated jobs accept it in all modes.Scheduling
One-shot jobs
--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.
One-shot jobs delete after success by default. Use
--keep-after-run to preserve them.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, butopenclaw cron edit <job-id> --failure-alert-include-skipped 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 .local api: "ollama" providers are probed at /api/tags; local OpenAI-compatible providers such as vLLM, SGLang, and LM Studio are probed at /models. If the endpoint is unreachable, the run is recorded as skipped 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 jobs.json, while pending runtime state lives in jobs-state.json. If jobs.json is edited externally, the Gateway reloads changed schedules and clears stale pending slots; formatting-only rewrites do not clear the pending slot.
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.
openclaw cron run <job-id> force-runs by default. Use --due to keep the older “only run if due” behavior.Models
cron add|edit --model <ref> selects an allowed model for the job.
Cron --model is a job primary, not a chat-session /model override. That means:
- Configured model fallbacks still apply when the selected job model fails.
- Per-job payload
fallbacksreplaces the configured fallback list when present. - An empty per-job fallback list (
fallbacks: []in the job payload/API) makes the cron run strict. - When a job has
--modelbut 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:- Gmail-hook override.
- Per-job
--model. - Stored cron-session model override (when the user selected one).
- Agent or default model selection.
Fast mode
Isolated cron fast mode follows the resolved live model selection. Model configparams.fastMode applies by default, but a stored session fastMode override still wins over config.
Live model switch retries
If an isolated run throwsLiveSessionModelSwitchError, 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 asSYSTEM_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(default24h) prunes completed isolated run sessions.cron.runLog.maxBytesandcron.runLog.keepLinesprune~/.openclaw/cron/runs/<jobId>.jsonl.
Migrating older jobs
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.Common edits
Update delivery settings without changing the message:--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.
Common admin commands
Manual run and inspection:cron runs entries include delivery diagnostics with the intended cron target, the resolved target, message-tool sends, fallback use, and delivered state.
Agent and session retargeting: