OpenClaw automation schedules

An automation is two decisions, when it fires and what it runs; this post is about the first. OpenClaw offers five schedule kinds, a small set of timezone rules that decide how a timestamp or a cron expression is read, event-driven stream sources that turn a long-lived command’s output into runs, dynamic pacing that lets a job propose its own next check, and condition scripts that gate a schedule on observed state. Here are the kinds and their flags, the timezone and stagger rules, the stream and pacing mechanics, the cron trap the docs call out, and the watcher contract.

The five kinds

• At fires once at an ISO timestamp or a relative time like twenty minutes; every fires at a fixed interval; cron takes a five- or six-field expression with an optional timezone; on-exit fires once when a watched command exits, an event trigger that survives turn teardown; and stream fires from batched lines produced by a supervised long-lived command. The same flags work on add and on edit, so an existing job can be converted to an exit-triggered one.
• Timestamps without a timezone are treated as UTC; the timezone flag interprets an offset-less one-shot datetime or evaluates a cron expression in an IANA zone, cron expressions without it use the Gateway host timezone, and the flag is invalid with every and on-exit.
• Recurring top-of-hour expressions, minute zero with a wildcard hour, are automatically staggered by up to five minutes to reduce load spikes; an exact flag forces precise timing and a stagger flag sets an explicit window, cron schedules only.
• Heartbeat scratch supported a structured tasks block before the 2026.8.1 release; the doctor fix converts each entry into an ordinary editable main-session job, preserving the interval and last-run timing, and runtime heartbeats no longer parse that text as schedules. The migrated jobs still run through the guarded heartbeat wake with active hours, minimum spacing, flood control and busy retries, and an occurrence outside active hours is skipped and retried at the next one.

Author watchers around actionable state, not only success: a watcher that goes quiet when its check fails or times out looks healthy while broken.

Streams and pacing

A stream schedule keeps an operator-authored argv command running under the Gateway and fires the job from its stdout and stderr lines; it is event-driven, never time-due, and available by default, with one triggers setting that disables streams, condition scripts and script payloads together. Line mode accepts every line, match mode only lines matching a compiled regex, a batch closes after a quiet period defaulting to 250 milliseconds within a clamped range or at a byte cap defaulting to sixteen kilobytes, and at the cap the batch ends with a truncation marker while match mode still evaluates complete lines against their full text. Fast failures restart with the scheduler’s error backoff, five consecutive runs shorter than sixty seconds leave the job in an error state until it is re-enabled, only one payload fire and one bounded pending batch are retained per job, lines arriving during a run or before the built-in thirty-second trigger interval coalesce rather than queue, failed payloads are not retried because they may not be idempotent, and a source identity rotates when the source is disabled, removed or replaced so retired batches cannot fire. There is no native WebSocket source; bridge one with a command-line client. Pacing lets a recurring job set minimum and maximum bounds, and during a run the job can propose its next check through the automations tool, measured from successful completion, silently clamped to the bounds, discarded by failed, timed-out or skipped runs, and surviving a Gateway restart. In chat, the owner-only loop command creates a recurring job bound to that conversation, with a fixed interval or self-pacing between one minute and one hour.

The cron trap and the watchers

• Cron expressions are parsed by croner, and when both day-of-month and day-of-week are non-wildcard the job fires when either matches, standard Vixie behaviour: nine in the morning on the fifteenth if it is a Monday actually fires on every fifteenth and every Monday. To require both, use croner’s plus modifier on the day-of-week field, or schedule on one field and guard the other in the prompt.
• An event trigger adds a headless condition script to an every, cron or stream schedule; time schedules evaluate it when due and streams per closed batch, and the payload runs only when the script returns fire true, optionally with a message appended to the event text and a state value persisted up to sixteen kilobytes and handed back frozen on the next evaluation. A once flag disables the job after its first fired payload, fire false persists state and reschedules without creating run history, and if a fired payload fails the returned state is not persisted, so scripts should be read-only checks with actions in the payload. Trigger schedules have a thirty-second minimum interval, and each evaluation gets a thirty-second budget and up to five tool calls; editing a running watcher’s condition or state protects that edit from the old evaluation.
• The warning matters: condition scripts and script payloads run unattended with the owning agent’s full tool policy, including exec, and stream schedules keep operator-authored commands running unattended, so the docs say to treat them as unattended code execution with that agent’s permissions and to set the triggers setting to false for a hard stop. A watcher is created from a local script file or stdin with a trigger-script flag beside the schedule and message.

OpenClaw automations is the guide these schedules belong to, and Timezones in OpenClaw explains the zone a cron expression is read in when no flag is given.

Where events come from

Stream sources and on-exit schedules cover the cases where the trigger is a process rather than a clock; for inbound HTTP events the webhook path is the sibling mechanism. OpenClaw heartbeat is the cycle migrated heartbeat tasks still ride, and OpenClaw hooks and webhooks the event-driven scripts and webhooks that sit next to schedules.

On Diali

On Diali the time-based kinds are what the dashboard automations screen creates, in the timezone you chose at onboarding; condition scripts and stream sources run unattended with the assistant’s full tool policy, so treat them as code you trust. Hosted OpenClaw on Diali is the assistant and OpenClaw standing orders the authority a scheduled job usually enforces.

• At, every, cron, on-exit, stream.
• Offset-less means UTC; day fields are OR, not AND.
• Watchers run with the agent’s full tools; write them read-only.