--- summary: "CLI reference for `openclaw automations` (schedule and run background jobs)" read_when: - You want scheduled jobs and wakeups - You are debugging automation execution and logs title: "Automations (cron)" --- # `openclaw automations` Manage automation jobs for the Gateway scheduler. The command registers as `openclaw cron` with `openclaw automations` as an alias. Every subcommand below works with either spelling. Run `openclaw automations --help` for the full command surface. See [Automations](/automation/cron-jobs) for the conceptual guide. All automation mutations (`add`/`create`, `edit`, `remove`, `run`) require `operator.admin`. Command-payload runs execute directly in the Gateway process, not as an agent `tools.exec` tool call. `tools.exec.*` and exec approvals still govern model-visible exec tools. Every automation subcommand accepts the shared Gateway connection options. Use `--port ` for a Gateway on a non-default local port, or `--url ` for an explicit WebSocket URL. Do not combine them. Connection options such as `--port`, `--url`, and `--token` may appear before or after the subcommand. ## Create jobs quickly `openclaw automations create` is an alias for `openclaw automations add`. For new jobs, put the schedule first and the prompt second: ```bash openclaw automations create "0 7 * * *" \ "Summarize overnight updates." \ --name "Morning brief" \ --agent ops ``` Use `--webhook ` when the job should POST the finished payload instead of delivering to a chat target: ```bash openclaw automations create "0 18 * * 1-5" \ "Summarize today's deploys as JSON." \ --name "Deploy digest" \ --webhook "https://example.invalid/openclaw/cron" ``` Use `--command` for deterministic shell-style jobs that run inside the OpenClaw scheduler without starting an isolated agent/model run: ```bash openclaw automations create "*/15 * * * *" \ --name "Queue depth probe" \ --command "scripts/check-queue.sh" \ --command-cwd "/srv/app" \ --announce \ --channel telegram \ --to "-1001234567890" ``` `--command ` stores `argv: ["sh", "-lc", ]`. Use `--command-argv '["node","scripts/report.mjs"]'` for exact argv execution. Command jobs capture stdout/stderr, record normal run history, and route output through the same `announce`, `webhook`, or `none` delivery modes as isolated jobs. A command that prints only `NO_REPLY` is suppressed. Use `--display-name ` when the list and detail views should show a human-readable label distinct from the automation's stable name. Set or update that label with `automations add|edit --display-name`. Use `automations edit --clear-display-name` to remove the label and restore the stable name in list and detail views. The set and clear options cannot be combined. ## Schedule types As an alternative to positional creation syntax, `automations add|create` accepts one of these schedule flags. `automations edit` uses the same flags to replace a job's schedule: - `--at ` schedules one run from an ISO timestamp or a duration such as `20m`. Offset-less timestamps use UTC unless `--tz ` is supplied. - `--every ` sets a recurring interval such as `10m`, `1h`, or `1d`. - `--cron ` sets a five- or six-field cron schedule. Use `--tz ` for the evaluation timezone, `--exact` to disable staggering, or `--stagger ` to set a stagger window. - `--on-exit ` starts a watched command and fires the job once when it exits. `--on-exit-cwd ` sets that command's working directory and requires `--on-exit`. - `--stream-command ` takes a nonempty JSON array of nonempty strings as the arguments for a supervised long-lived command and fires the job from its batched output. `--stream-cwd ` sets the source's working directory. `--stream-mode line|match` selects every line or only matching lines. Match mode requires `--stream-match `, which is invalid in line mode. `--stream-batch-ms ` sets the quiet-window delay in milliseconds, and `--stream-max-batch-bytes ` sets the maximum UTF-8 bytes per batch. `--tz` applies to cron schedules and offset-less `--at` timestamps, while `--exact` and `--stagger` apply only to cron schedules. None of these three flags is valid with exit or stream schedules. See [Automation schedules](/automation/cron-jobs/schedules#schedule-types) for stream lifecycle, batching limits, and trigger details. ## Sessions `--session` accepts `main`, `isolated`, `current`, or `session:`. Agent-turn jobs default to the creating conversation when session context is available. Without a session key, including ordinary CLI calls and API calls that omit one, the target falls back to `isolated`. - `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:` pins to an explicit persistent session key. 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. Removing an isolated automation stops future runs and cleans up its reusable session after active work stops. The JSON removal response includes `sessionCleanup: "pending"` while that cleanup is deferred. Run history is retained. If session cleanup fails, the error is logged. A removal with no active run also returns the cleanup error to the caller. Use `openclaw sessions list --json` to find the remaining session, then `openclaw sessions delete --yes` to retry cleanup after the Gateway or worker recovers. ## Delivery `openclaw automations add`, `openclaw automations list`, and `openclaw automations show ` 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. Provider-prefixed targets can disambiguate unresolved announce channels. For example, `to: "telegram:123"` selects Telegram when `delivery.channel` is omitted or `last`. Only prefixes advertised by the loaded plugin are provider selectors. If `delivery.channel` is explicit, the prefix must match that channel. `channel: "whatsapp"` with `to: "telegram:123"` is rejected. Service prefixes such as `imessage:` and `sms:` remain channel-owned target syntax. Isolated `automations add` jobs default to `--announce` delivery. Use `--no-deliver` to keep output internal. `--deliver` remains as a deprecated alias for `--announce`, which replaced it in 2026.2.3. ### Delivery ownership Isolated automation chat delivery is shared between the agent and the runner: - 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. Use `automations add|create --webhook ` or `automations edit --webhook ` to set webhook delivery. Do not combine `--webhook` with chat delivery flags such as `--announce`, `--no-deliver`, `--channel`, `--to`, `--thread-id`, or `--account`. `automations edit ` can unset individual delivery routing fields with `--clear-channel`, `--clear-to`, `--clear-thread-id`, and `--clear-account` (each is rejected when combined with its matching set flag). Unlike `--no-deliver`, which only disables runner fallback delivery, these remove the stored field so the job resolves that part of its route from defaults again. `--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: 1. Route fields in the job's `failureAlert` object. 2. `delivery.failureDestination` on the job, layered over the global destination fields on `cron.failureAlert` (`mode`, `channel`, `to`, `accountId`). The `cron.failureDestination` block, retired in 2026.8.1, is merged into them by `openclaw doctor --fix`. 3. The job's primary announce target (when neither of the above resolves to a concrete destination). Jobs with one of those routes default to an execution-failure alert after 2 consecutive failures and a 1-hour cooldown. A per-job or global `failureAlert` object explicitly activates/tunes the policy even without an existing route. `failureAlert: false` disables execution and required-delivery failure alerts for the job, but not the auto-disable safety notification. Global `enabled: false` disables inheritance unless the job has its own `failureAlert` object. `delivery.bestEffort: true` suppresses inherited/default execution alerts, but not an explicit per-job policy. Main-session jobs may only use `delivery.failureDestination` when primary delivery mode is `webhook`. Isolated jobs accept it in all modes. Chat failure notifications include the run start time in the agent's configured user timezone. Webhook message text stays stable and exposes the instant as `runAtMs`. Isolated automation runs treat run-level agent failures as job errors, even when no reply payload is produced. Model and provider failures still increment error counters and trigger failure notifications. Command jobs do not start an isolated agent turn. A zero exit code records `ok`. Non-zero exit, signal, timeout, or no-output timeout records `error`, and can trigger the same failure notification path. Required completion delivery is separate: `status: "ok"` with `completionStatus: "failed"` does not increment the execution streak or backoff. Delivery-failure alerts use a resolved alternate failure destination without the `after` threshold. Every alert honors the shared job/global `failureAlert.cooldownMs` (default 1 hour). This includes the first delivery failure after an execution alert. An alert never retries the primary route that just failed. If an isolated run times out before the first model request, `openclaw automations show` and `openclaw automations runs` include a phase-specific error. Examples are `setup timed out before runner start`, or a stall message naming the last-known startup phase such as `context-engine`. For CLI-backed providers, the pre-model watchdog stays active until the external CLI turn starts. Session lookup, hook, auth, prompt, and CLI setup stalls are therefore reported as pre-model automation failures. ## Scheduling ### One-shot jobs `--at ` schedules a one-shot run. Offset-less datetimes are treated as UTC unless you also pass `--tz `, which interprets the wall-clock time in the given timezone. One-shot jobs delete only after `completionStatus: "succeeded"`. Required-delivery failure or unknown completion keeps the job disabled, with no next run, so restarts do not replay payload side effects. Intentional silence and successful executions with explicit `delivery.bestEffort: true` complete and delete normally. Use `--keep-after-run` to preserve successful jobs too. ### Recurring jobs Configured intervals and stagger windows retain millisecond precision in human-readable output: `--every 90s` appears as `every 1m 30s`, and `--stagger 1001ms` as `stagger 1s 1ms`. Use `automations show ` for the full duration when the list column is truncated. Relative next-run and last-run labels remain rounded. 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 `openclaw automations edit --failure-alert-include-skipped` can opt failure alerts into repeated skipped-run notifications. A local configured model provider has a base URL on loopback, on a private network, or on `.local`. For isolated jobs that target such a provider, the scheduler runs a lightweight provider preflight before it starts the agent turn. The scheduler probes `api: "ollama"` providers at `/api/tags`. It probes other local OpenAI-compatible providers (`api: "openai-completions"`, for example vLLM, SGLang, and LM Studio) at `/models`. If the endpoint is unreachable, the scheduler records the run as `skipped` and retries it on a later schedule. It caches the reachability result per endpoint for 5 minutes, so many jobs against the same local server do not send repeated probes. Automation jobs, pending runtime state, and run history live in the shared SQLite state database. The file store it replaced in 2026.6.1 is still imported once: legacy `jobs.json`, `-state.json`, and `runs/*.jsonl` files are read and then renamed with a `.migrated` suffix. After import, edit schedules with `openclaw automations add|edit|remove` instead of editing JSON files. ### Manual runs Manually running a disabled job does not enable its schedule or create automatic retries. Use `openclaw automations enable ` to resume scheduled runs. `openclaw automations run ` force-runs by default and returns as soon as the manual run is queued. Successful responses include `{ ok: true, enqueued: true, runId }`. Use the returned `runId` to inspect the later result: ```bash openclaw automations run openclaw automations runs --run-id ``` Add `--wait` when a script should block until that exact queued run records a terminal status: ```bash openclaw automations run --wait --wait-timeout 10m --poll-interval 2s ``` With `--wait`, the CLI calls `cron.run` first, then polls the durable `cron.runs` row for the returned `runId`. It does not reread mutable job delivery settings. JSON reports payload execution as `status` and whole-run completion as `completionStatus`. The command exits `0` only for `completionStatus: "succeeded"`. `failed`, `unknown`, execution errors or skips, a missing `runId`, and timeout expiry exit non-zero (default `10m`, polled every `2s` by default). `--poll-interval` must be greater than zero. Completed JSON output, including the run summary, is flushed before the command exits, so it can be piped to a JSON reader. Use `--due` when you want the manual command to run only if the job is currently due. If `--due --wait` does not enqueue a run, the command returns the normal non-run response instead of polling. ## Models `automations add|edit --model ` selects an allowed model for the job. `automations add|edit --fallbacks ` sets per-job fallback models, for example `--fallbacks openrouter/gpt-4.1-mini,openai/gpt-5`. Pass `--fallbacks ""` for a strict run with no fallbacks. `automations edit --clear-fallbacks` removes the per-job fallback override. `automations edit --clear-model` removes the per-job model override. The job then follows normal automation model-selection precedence: a stored automation-session override if present, otherwise the agent or default model. You cannot combine it with `--model`. `automations add|edit --thinking ` sets a per-job thinking override. `automations edit --clear-thinking` removes it, so the job follows normal automation thinking precedence. You cannot combine it with `--thinking`. If the model is not allowed or cannot be resolved, the scheduler fails the run with an explicit validation error. It does not fall back to the job's agent or default model selection. The automation `--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 `fallbacks` replaces the configured fallback list when present. - An empty per-job fallback list (`--fallbacks ""` or `fallbacks: []` in the job payload/API) makes the run strict. - When a job has `--model` but no fallback list is configured, OpenClaw passes an explicit empty fallback override. The agent primary is therefore not appended as a hidden retry target. - Local-provider preflight checks walk configured fallbacks before marking a run `skipped`. `openclaw doctor` reports jobs that already have `payload.model` set, including provider namespace counts and mismatches against `agents.defaults.model`. Use that check when auth, provider, or billing behavior looks different between live chat and scheduled jobs. ### Isolated automation model precedence Isolated automation runs resolve the active model in this order: 1. Gmail-hook override. 2. Per-job `--model`. 3. Stored automation-session model override (when the user selected one). 4. Agent or default model selection. ### Fast mode Isolated automation fast mode follows the resolved live model selection. It resolves stored session `fastMode`, per-agent `agents.entries.*.fastModeDefault`, global `agents.defaults.fastModeDefault`, then selected-model `params.fastMode`. When the resolved mode is `auto`, the cutoff uses the selected model's `params.fastAutoOnSeconds` value, defaulting to 60 seconds. ### Live model switch retries If an isolated run throws `LiveSessionModelSwitchError`, the scheduler persists the switched provider and model for the active run before it retries. It also persists the switched auth profile override when one is present. 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 automation turns suppress stale acknowledgement-only replies. If the first result is only an interim status update, the scheduler re-prompts once for the real result before delivery. It does not re-prompt when a descendant subagent run is responsible for the eventual answer. ### Silent token suppression If an isolated automation run returns only the silent token (`NO_REPLY` or `no_reply`), the scheduler suppresses direct outbound delivery and the fallback queued summary path. Nothing is posted back to chat. Human-readable `automations list` and `automations show` label successful intentional suppression as `ok (suppressed)`, not a delivery warning. `automations show` includes `last delivery suppression` with the recorded reason (`empty`, `silent`, `heartbeat`, or `channel_transform`). JSON keeps `deliveryStatus: "not-delivered"` and the separate `deliverySuppressionReason`. Genuine delivery failures without an intentional reason still show `ok (not delivered)` when execution succeeded. ### Structured denials Isolated automation runs use structured execution-denial metadata from the embedded run (fatal exec-tool errors coded `SYSTEM_RUN_DENIED` or `INVALID_REQUEST`) as the authoritative denial signal. They also honor node-host `UNAVAILABLE` wrappers around a nested structured error carrying one of those codes. The scheduler classifies final-output prose or approval-looking refusal phrases as denials only when the embedded run also provides structured denial metadata. Ordinary assistant text is therefore not treated as a blocked command. `automations list` and run history surface the denial reason instead of reporting a blocked command as `ok`. ## Retention Retention behavior: - `cron.sessionRetention` prunes completed isolated run sessions. The default is `24h`. Set `false`, or a zero duration such as `"0h"`, to disable it. - Terminal run history is retained for 7 days, and `lost` rows for 24 hours. An additional ceiling keeps only the newest 2000 rows per job and history class. ## Migrating older jobs If you have automation jobs from before the current delivery and store format, run `openclaw doctor --fix`. Doctor normalizes legacy job fields: `jobId`, `schedule.cron`, top-level delivery fields including legacy `threadId`, and payload `provider` delivery aliases. It also migrates `notify: true` webhook fallback jobs from the retired raw `cron.webhook` value to explicit webhook delivery. It removes that config key afterwards. Jobs that already announce to a chat keep that delivery and get a completion webhook destination. Without a legacy webhook, Doctor removes the inert top-level `notify` marker for jobs with no migration target. The existing delivery is preserved unchanged. `doctor --fix` therefore stops re-warning about them. ## Common edits Update delivery settings without changing the message: ```bash openclaw automations edit --announce --channel telegram --to "123456789" ``` Disable delivery for an isolated job: ```bash openclaw automations edit --no-deliver ``` Enable lightweight bootstrap context for an isolated job: ```bash openclaw automations edit --light-context ``` Announce to a specific channel: ```bash openclaw automations edit --announce --channel slack --to "channel:C1234567890" ``` Announce to a Telegram forum topic: ```bash openclaw automations edit --announce --channel telegram --to "-1001234567890" --thread-id 42 ``` Create an isolated job with lightweight bootstrap context: ```bash openclaw automations create "0 7 * * *" \ "Summarize overnight updates." \ --name "Lightweight morning brief" \ --session isolated \ --light-context \ --no-deliver ``` `--light-context` applies to isolated agent-turn jobs only. For automation runs, lightweight mode keeps bootstrap context empty instead of injecting the full workspace bootstrap set. Create a command job with exact argv, cwd, env, stdin, and output limits: ```bash openclaw automations create "*/30 * * * *" \ --name "Position export" \ --command-argv '["node","scripts/export-position.mjs"]' \ --command-cwd "/srv/app" \ --command-env "NODE_ENV=production" \ --command-input '{"mode":"summary"}' \ --timeout-seconds 120 \ --no-output-timeout-seconds 30 \ --output-max-bytes 65536 \ --webhook "https://example.invalid/openclaw/cron" ``` ## Common admin commands Manual run and inspection: ```bash openclaw automations list openclaw automations list --agent ops openclaw automations get openclaw automations get --json openclaw automations show openclaw automations run openclaw automations run --due openclaw automations run --wait --wait-timeout 10m openclaw automations run --wait --wait-timeout 10m --poll-interval 2s openclaw automations runs --limit 50 openclaw automations runs --limit 50 --json openclaw automations runs --run-id openclaw automations runs --status error --query timeout openclaw automations runs --delivery-status not-delivered openclaw automations runs --sort asc --offset 200 --limit 50 ``` `automations runs` is the preferred spelling. `cron runs` and the leaf-local `--id ` form remain supported compatibility aliases. Run-history filters are applied by the Gateway before paging. Use `--status` with `all`, `ok`, `error`, or `skipped`; use `--delivery-status` with `delivered`, `not-delivered`, `unknown`, or `not-requested`. `--query ` searches run summaries and errors. `--sort asc|desc` selects oldest-first or newest-first order, and `--offset ` advances through the result set using the page metadata returned by the previous command. `openclaw automations list` shows enabled jobs across agents by default, including jobs whose owner cannot be resolved. Pass `--all` to include disabled jobs, or `--agent ` to filter by the effective normalized agent ID. Ownership resolves from the job's declared agent, its agent-scoped session key, then the configured system-agent owner. Unresolved jobs do not match an agent filter. The `cron list` alias has the same behavior. The human-readable Agent ID column shows the effective owner. JSON list rows preserve the declared `agentId` and include `effectiveAgentId`, which is `null` when ownership is unresolved. Existing main-session jobs can still be renamed, disabled, or rescheduled after their agent stops being the system default. Creating a main-session job or explicitly setting its agent, session target, or payload kind revalidates the current main-session rules. An unresolved owner does not stop the scheduler: that job is skipped with an explanation in `state.lastError`, while other jobs continue. Run `openclaw doctor --fix` to repair unresolved multi-agent legacy ownership, set `agents.defaults.systemAgent.agentId`, or use `openclaw cron edit --agent ` to repair the job. Sole-agent rosters and legacy default markers honored by the runtime already resolve an owner and need no owner migration. The explanation stays on the job. No agent run-history entry is created, because no agent run starts. `--json` always requests JSON output. Commands whose product is already a machine-readable result emit JSON results by default: `add`/`create`, `status`, `enable`, `disable`, `rm`/`remove`/`delete`, `run`, `edit`, `get`, and `runs`. They accept `--json` as the explicit machine-output spelling. `openclaw automations get ` returns the stored job JSON directly. Use `automations show ` when you want the human-readable view with delivery-route preview. `list` and `show` use human-readable output by default and switch to JSON with `--json`. `scratch` reads raw scratch content by default. With `--json` it prints the scratch plus revision metadata. Scratch writes return the revision result as JSON by default, and accept `--json` as the explicit machine-output spelling. `automations list --json` and `automations show --json` include a top-level `status` field on each job, computed from `enabled`, `state.runningAtMs`, and `state.lastRunStatus`. Values: `disabled`, `running`, `ok`, `error`, `skipped`, or `idle`. JSON status stays canonical and undecorated, so external tooling can read job state without re-deriving it. Human output may decorate repeated `error` statuses with a failure count. `automations runs` entries include delivery diagnostics with the intended automation target, the resolved target, message-tool sends, fallback use, and delivered state. Private per-job scratch (heartbeat checklists and similar monitor context): ```bash openclaw automations scratch # print current scratch content openclaw automations scratch --json # scratch plus revision metadata openclaw automations scratch --set "text" # replace scratch with exact text openclaw automations scratch --file notes.md # replace scratch from a file (- for stdin) openclaw automations scratch --unset # remove the scratch row ``` Scratch is stored in the shared state database, capped at 256 KiB, and never included in `automations list`/`automations get`/`automations runs` output. Writes are compare-and-swap guarded against the revision read at command start. Pass `--expected-revision ` to pin an explicit revision instead. See [Heartbeat](/gateway/heartbeat#monitor-scratch-optional) for how heartbeat monitors use scratch. Agent and session retargeting: ```bash openclaw automations edit --agent ops openclaw automations edit --clear-agent openclaw automations edit --session current openclaw automations edit --session "session:daily-brief" ``` `openclaw automations add` warns when `--agent` is omitted on agent-turn jobs and falls back to the default agent (`main`). Pass `--agent ` at create time to pin a specific agent. Delivery tweaks: ```bash openclaw automations edit --announce --channel slack --to "channel:C1234567890" openclaw automations edit --webhook "https://example.invalid/openclaw/cron" openclaw automations edit --best-effort-deliver openclaw automations edit --no-best-effort-deliver openclaw automations edit --no-deliver ``` ## Related - [CLI reference](/cli) - [Automations](/automation/cron-jobs)