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.

Every automation subcommand accepts the shared Gateway connection options. Use --port <port> for a Gateway on a non-default local port, or --url <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.

Automation commands require a running Gateway. With token, password, or none authentication, calls to the configured local loopback Gateway do not open the shared state database for device authentication. Remote and explicit URL targets retain their device authentication and pairing requirements.

Create jobs quickly

openclaw automations create is an alias for openclaw automations add. For new jobs, put the schedule first and the prompt second:

openclaw automations create "0 7 * * *" \  "Summarize overnight updates." \  --name "Morning brief" \  --agent ops

For agent or command jobs, --timeout-seconds accepts non-negative whole seconds. Set --timeout-seconds 0 on add/create or edit to disable the scheduler's wall-clock ceiling. Omitting the flag on creation keeps the default timeout; omitting it on edit leaves the stored timeout unchanged. Agent/provider timeouts, startup watchdogs, and command-runner limits still apply. System-event jobs reject --timeout-seconds; script jobs use --script-timeout-seconds instead.

Use --webhook <url> when the job should POST the finished payload instead of delivering to a chat target:

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 script-based shell-style jobs that run inside the OpenClaw scheduler without starting an isolated agent/model run:

openclaw automations create "*/15 * * * *" \  --name "Queue depth check" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

--command <shell> stores argv: ["sh", "-lc", <shell>]. 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 <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 <job-id> --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

For positional interval schedules, use every <duration>, such as "every 10m". Natural-language schedules such as "every day at 9am sharp" are not supported; use "0 9 * * *" instead. Invalid cron expressions are rejected by the CLI with the supplied expression and examples of valid syntax.

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 <when> schedules one run from an ISO timestamp or a duration such as 20m. Offset-less timestamps use UTC unless --tz <iana> is supplied.
• --every <duration> sets a recurring interval such as 10m, 1h, or 1d.
• --cron <expression> sets a five- or six-field cron schedule. Use --tz <iana> for the evaluation timezone, --exact to disable staggering, or --stagger <duration> to set a stagger window.
• --on-exit <shell> starts a watched command and fires the job once when it exits. --on-exit-cwd <path> sets that command's working directory and requires --on-exit.
• --stream-command <json> 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 <path> sets the source's working directory. --stream-mode line|match selects every line or only matching lines. Match mode requires --stream-match <regex>, which is invalid in line mode. --stream-batch-ms <n> sets the quiet-window delay in milliseconds, and --stream-max-batch-bytes <n> 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 for stream lifecycle, batching limits, and trigger details.

On creation, omit --command-cwd, --on-exit-cwd, or --stream-cwd to use the default working directory. An explicitly empty or whitespace-only path is an error. When editing a stream job, --stream-cwd "" still clears its configured working directory.

Monitoring policies

Use these flags with automations add|create or automations edit for ordinary monitoring jobs:

• --active-hours-start <HH:MM> and --active-hours-end <HH:MM> define an execution window. Start is inclusive; end is exclusive and also accepts 24:00. Overnight windows work; equal endpoints define an empty window.
• --active-hours-timezone <zone> chooses an IANA timezone, user (the default, using the configured user timezone), or local (Gateway host). This is independent of the schedule's --tz.
• --idle-only gives foreground work priority. --no-idle-only turns that policy off.
• --skip-if-scratch-empty skips an agent turn with explicitly empty scratch. Missing scratch still runs. --no-skip-if-scratch-empty turns this off.
• --include-reasoning includes reasoning returned by an agent alongside a meaningful result; --no-include-reasoning keeps it out. This does not set the thinking level.

A new window requires both endpoints. An edit can update just one field of an existing window. automations edit --clear-active-hours removes the window; --clear-idle-only removes the stored idle policy. Do not combine a clear flag with its corresponding set flag. The scratch and reasoning flags require an agent-turn payload (--message on creation).

Manual force-runs bypass cadence but still respect the execution window and the job's authority and delivery policies. See Monitoring policies.

Sessions

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

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.

An isolated agent-turn job created from a conversation also captures that conversation's generation for delivery. With announce and no explicit or remembered external route, its final result is committed into that conversation while the run remains isolated. Ordinary CLI jobs without a creating session still need a resolvable channel route, webhook delivery, or --no-deliver.

Binding older jobs to their conversation

Jobs created before OpenClaw recorded the creating conversation's incarnation name their conversation only by session key. They keep their existing behavior, with the run session's board, memory, and workspace, until someone binds them. To bind one, ask the agent in that conversation to bind it (the automations tool's bind action) from an authenticated owner turn: a Control UI administrator or the configured channel owner. The binding records the conversation's current incarnation, and later runs use that conversation's resources as a linked child run. Bind refuses a job whose recorded conversation is another one, a job that is already bound or is not linked by key alone, and turns without owner authority. Run from a shell, openclaw automations bind has no conversation and is refused with that instruction.

A bind from an authenticated Control UI turn also stores that turn's operator source, as creation from that turn would, so each occurrence rechecks the device and access grant. Other owner turns keep the job's recorded requester.

When an operator removes an automation with an active run, OpenClaw requests cancellation of that run. An admitted automation can remove its own job without cancelling the active run. If the caller cannot be confirmed as the job's exact live run, self-removal fails without deleting the job or cancelling the active run. The JSON removal response includes activeRunCancellationRequested: true when cancellation was requested. For an isolated automation, reusable-session cleanup then waits for the active run to stop and reports sessionCleanup: "pending" while 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 <key> --yes to retry cleanup after the Gateway or worker recovers.

Delivery

openclaw automations add, openclaw automations list, and openclaw automations show <job-id> preview the resolved delivery route. For channel: "last", the preview shows a conversation commit, the resolved channel route, or why delivery will be blocked.

If an existing session metadata store cannot be read or its schema is not ready, the preview keeps the requested destination and reports why it is unavailable without blocking job creation or listing. An absent database has no session routing history and uses the normal delivery fallback.

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.

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 sends the final result unless a verified matching send already did so, then adds confirmed delivery to the destination chat's transcript.
• webhook posts the finished payload to a URL.
• none disables automatic conversation results and external notifications.

Agent, command, and script results belong to the chat or topic that receives them. An explicit different destination gets the result instead of the creating conversation, including for CLI and older jobs without a creating session. With no external route, the creating conversation receives it; WebChat shows the same message live and after reload. Retries do not duplicate results. Resetting an explicitly configured external destination does not stop delivery: the result enters its current session. Implicit agent-turn announcements and routeless WebChat results fail if the creating conversation was deleted or reset; recreate the job or set explicit external delivery coordinates. Command and script announcements retain an already resolved route without a source-generation check, as before. A confirmed external send remains delivered, with a warning if the conversation write fails. See Automation delivery.

Use automations add|create --webhook <url> or automations edit <job-id> --webhook <url> 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 <job-id> 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 disables automatic results and notifications, these remove the stored field so the job resolves that part of its route from defaults again.

--announce enables the conversation result and notification flow. --no-deliver disables that automatic flow 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 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.

Owner targets and direct-message policy

--delivery-target owner resolves a positively identified owner DM dynamically instead of following the last group conversation. It cannot be combined with --to, --thread-id, or --webhook. On edit, it clears a previous explicit recipient and thread; setting an explicit recipient replaces owner targeting. Use --clear-delivery-target to remove it.

--direct-policy allow|block controls direct/DM delivery for the job. The default is allow; block prohibits DMs. Use --clear-direct-policy to remove the stored policy. These policies support agent-turn jobs in any supported session, including main, and non-main command or script jobs with chat delivery. They cannot be set and cleared in the same command.

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. Terminal one-shot failures bypass after: eligible owned jobs receive a repair turn in their owner conversation, other jobs use an enabled failure-alert route, and jobs without one receive the auto-disable safety notice. Operator cancellations and runs retired by a Gateway restart stay quiet.

Repeated failures with the same cause stay grouped into one incident across Gateway restarts. A changed cause or destination can notify after the cooldown. Successful completion clears the incident silently; the recovery stays in automation history. Skipped runs and unknown delivery outcomes do not count as recovery. If script setup cannot refresh tools after a plugin reload, the alert explains that automatic recovery failed before the script ran.

After an in-place plugin replacement, the next script invocation refreshes its retained tool runtime before executing. It uses the current plugin hooks without restarting the Gateway or replaying a completed tool effect.

For transient failures, a scheduler-authored repair may intentionally return NO_REPLY and finish silently without a WebChat error. Public messages do not gain that waiver by claiming cron provenance.

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 and group repeated failures into one incident. Alerts for changed failures honor the shared job/global failureAlert.cooldownMs (default 1 hour), including the first delivery failure after an execution alert. An alert never retries the primary route that just failed.

An unresolved announcement target (for example, no configured channels) is a delivery-only failure when the agent turn succeeds. Its report remains in run history; configure the destination before running the job again.

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

Invalid --tz values are rejected before saving a job; use an IANA timezone such as America/New_York. Invalid timestamps and nonexistent local times during a daylight-saving transition are reported separately as --at errors.

An at job records a terminal execution failure after a permanent error or exhausted retries. An on-exit job fired by its watcher is terminal on any execution error, including a transient one, because retrying would rerun the watched command. These failures record state.autoDisabled, which openclaw doctor reports. Manually force-running a paused on-exit job preserves its pause without recording an auto-disable.

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 <job-id> 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.

For provider network failures, request timeouts, overloads, rate limits, and server errors (not the job's own execution timeout), the scheduler first re-runs the job after 30s, 1m, and 5m (or at its next scheduled run when sooner), and holds failure alerts and owner repair requests until those re-runs also fail.

Skipped runs are tracked separately from execution errors. They do not affect retry backoff, but openclaw automations edit <job-id> --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 checks api: "ollama" providers at /api/tags. It checks 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 checks.

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 retired. If jobs.json, <name>-state.json, or runs/*.jsonl files remain, install OpenClaw 2026.9.7 and run openclaw doctor --fix before upgrading to the latest version. Current Doctor preserves these files and reports the intermediate upgrade requirement. Supported jobs-quarantine.json sidecars are still imported and archived with a .migrated suffix. 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 <job-id> to resume scheduled runs.

openclaw automations run <job-id> force-runs by default and returns after the Gateway durably reserves the run and accepts it into its execution lane. Successful responses include { ok: true, enqueued: true, runId }; the job may still be waiting for a slot. If admission or caller checks fail before queue acceptance, the request fails without reporting a queued run. If the Gateway exits before dispatch, startup records an interrupted receipt for that exact request in the state database. Such pre-dispatch interruptions do not appear in executed-run history. Use the returned runId to inspect an executed run's result:

openclaw automations run <job-id>openclaw automations runs <job-id> --run-id <run-id>

A forced run skips the job's trigger.script condition gate and executes the payload directly. An agentTurn payload therefore wakes the model even if the gate would return fire: false. The automations tool also skips the gate when called with action: "run", runMode: "force"; its default runMode is "due".

Add --wait when a script should block until that exact queued run records a terminal status:

openclaw automations run <job-id> --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.

Models

automations add|edit --model <ref> selects an allowed model for the job. automations add|edit --fallbacks <list> 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 <job-id> --clear-fallbacks removes the per-job fallback override. automations edit <job-id> --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 <level> sets a per-job thinking override. automations edit <job-id> --clear-thinking removes it, so the job follows normal automation thinking precedence. You cannot combine it with --thinking.

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.

When every local provider is unreachable, automations runs and automations show retain the skipped status and preflight reason. Start the provider or correct its configured endpoint. Repeated preflight skips use the existing failure-alert route and threshold without requiring failureAlert.includeSkipped, while explicit alert opt-outs still apply. Recurring jobs stay enabled and resume on a later scheduled run once reachability is checked again; endpoint results are cached for up to five minutes.

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 require a final deliverable rather than an interim status update. Recorded pending-descendant work retains ownership of the eventual answer; the scheduler does not infer completion or pending work from acknowledgment prose.

Silent token suppression

For text-only isolated automation announcements, only a completed final whose entire text trims to uppercase NO_REPLY suppresses direct outbound delivery and the fallback queued summary path. The terminal producer records this decision; delivery does not reparse the reply.

For example, this final reply sends no chat message:

NO_REPLY

A literal leading NO_REPLY\n strips that one control line and delivers the rest unchanged. Lowercase no_reply, NO_REPLY., quoted or JSON forms, and a trailing NO_REPLY after a report are visible text. For media payloads, silent model text can be removed while tool-owned media is still delivered.

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.

Successful executions with an unconfirmed delivery outcome show delivery unknown, including webhook requests that time out before receiving response headers. This label applies to both required and best-effort delivery; it does not claim delivery failed. JSON execution status remains ok.

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

Run openclaw doctor --fix to convert supported July 2026 and later heartbeat configuration and monitor jobs to ordinary editable agent-turn automations. After migration, edit or disable the job itself. Config reloads, restarts, and later Doctor runs do not overwrite edits or recreate a deleted migrated job. Use automations show, runs, enable, and disable to manage the jobs. Legacy system heartbeat controls apply only to converted/default jobs. See Heartbeat migration.

The cron.* Gateway methods remain compatible. The deprecated --wake now|next-heartbeat field remains accepted, but scheduled jobs execute their payload through ordinary session execution when the job is due. It does not add another wake or deferral step. Use the job's schedule to control timing.

Common edits

Update delivery settings without changing the message:

openclaw automations edit <job-id> --announce --channel telegram --to "123456789"

Disable delivery for an isolated job:

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

Enable lightweight bootstrap context for an isolated job:

openclaw automations edit <job-id> --light-context

Announce to a specific channel:

openclaw automations edit <job-id> --announce --channel slack --to "channel:C1234567890"

Announce to a Telegram forum topic:

openclaw automations edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42

Create an isolated job with lightweight bootstrap context:

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:

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:

openclaw automations listopenclaw automations list --agent opsopenclaw automations list --all --agent ops --query backup --jsonopenclaw automations get <job-id>openclaw automations get <job-id> --jsonopenclaw automations show <job-id>openclaw automations run <job-id>openclaw automations run <job-id> --dueopenclaw automations run <job-id> --wait --wait-timeout 10mopenclaw automations run <job-id> --wait --wait-timeout 10m --poll-interval 2sopenclaw automations runs <job-id> --limit 50openclaw automations runs <job-id> --limit 50 --jsonopenclaw automations runs <job-id> --run-id <run-id>openclaw automations runs <job-id> --status error --query timeoutopenclaw automations runs <job-id> --delivery-status not-deliveredopenclaw automations runs <job-id> --sort asc --offset 200 --limit 50

automations runs is the preferred spelling. cron runs and the leaf-local --id <job-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 <text> searches run summaries and errors. --sort asc|desc selects oldest-first or newest-first order, and --offset <n> 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 <id> 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.

Use --query <text> to search job IDs, names, descriptions, declared agent IDs, and display names. Matching is case-insensitive and compares canonically equivalent Unicode forms as the same text without rewriting stored metadata. The Gateway filters before paging; the CLI reads every bounded matching page with the same query. It combines with --all, --agent, and either text or --json output. Omitting the flag or passing only whitespace keeps the existing listing. This searches job metadata, not message or script payloads; use automations runs <job-id> --query <text> to search run summaries and errors instead.

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 <job-id> --agent <id> 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 <job-id> returns the stored job JSON directly. Use automations show <job-id> 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.

If a returned job has no runtime state, human-readable show still displays the available job details, using - for unavailable run fields and idle for an enabled job with no recorded status.

automations show also accepts an exact job name, matched without regard to case. Job IDs take precedence. When multiple jobs match the name, including disabled jobs, the command reports ambiguity and includes the matching jobs' full IDs, names, schedule summaries, enabled state, and status. Retry the same command with the intended job ID instead of the name.

With --json, the failure envelope includes these summaries in error.matches. Event schedules appear as on-exit or stream without their command text.

automations list --json and automations show <job-id> --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 uses the plain values above without decoration, 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 for checklists and other run context:

openclaw automations scratch <job-id>                  # print current scratch contentopenclaw automations scratch <job-id> --json           # scratch plus revision metadataopenclaw automations scratch <job-id> --set "text"     # replace scratch with exact textopenclaw automations scratch <job-id> --file notes.md  # replace scratch from a file (- for stdin)openclaw automations scratch <job-id> --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 <n> to pin an explicit revision instead. Present scratch becomes bounded model prompt context, so do not store secrets in it. See Job scratch and quiet results for self-scoped scratch and result actions.

For a job with --skip-if-scratch-empty, blank text, comments, headings, fence markers, and empty checklist stubs skip the run. --unset removes scratch; missing scratch still runs. Use automations disable <job-id> to stop the job regardless of scratch content.

Agent and session retargeting:

openclaw automations edit <job-id> --agent opsopenclaw automations edit <job-id> --clear-agentopenclaw automations edit <job-id> --session currentopenclaw automations edit <job-id> --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 <id> at create time to pin a specific agent.

Delivery tweaks:

openclaw automations edit <job-id> --announce --channel slack --to "channel:C1234567890"openclaw automations edit <job-id> --webhook "https://example.invalid/openclaw/cron"openclaw automations edit <job-id> --best-effort-deliveropenclaw automations edit <job-id> --no-best-effort-deliveropenclaw automations edit <job-id> --no-deliver

History across automations

Use openclaw automations runs --all to query the existing Gateway history across visible automations without looking up each job ID. Filters and pagination apply to the combined history:

openclaw automations runs --all --status error --limit 20openclaw automations runs --all --sort asc --offset 20 --limit 20

Do not combine --all with a positional job ID or --id. Omitting --all keeps the existing per-job query. Gateway permissions and visibility rules are unchanged.

Related

• CLI reference
• Automations