In OpenClaw, how do `--at`, `--every` and `--cron` schedules differ when you add a job with `openclaw cron add`, and where does `--tz` apply?
answer
- one-shot, interval, expression
- offset-less timestamps read as UTC
- --tz names an IANA zone
- no --tz means the Gateway host zone
- top-of-hour jobs get staggered
basics
~20 s--at fires once, at a timestamp or after a delay like 20m; --every repeats at a fixed interval; --cron follows a 5- or 6-field expression. --tz gives cron expressions and offset-less --at times an IANA zone, and --every rejects it.
solid answer
~50 sAll three are schedule flags on `openclaw cron add` (the same command family is also available as `openclaw automations`), and the job lives in the Gateway's scheduler, so it fires only while the Gateway runs. `--at` is a one-shot: an ISO timestamp or a relative delay such as `20m`; an offset-less timestamp is read as UTC unless you add `--tz`, and the job deletes itself after a successful run unless you pass `--keep-after-run`. `--every 1h` repeats at a fixed interval and does not accept `--tz`. `--cron "0 7 * * 1-5"` follows a cron expression: with `--tz Europe/Berlin` it is evaluated in that zone, without `--tz` in the Gateway host's zone, which is the usual reason a morning briefing arrives at the wrong hour. Recurring top-of-hour expressions such as `0 * * * *` are staggered by up to five minutes unless you pass `--exact`.
code
bash · 6 linesopenclaw cron add \
--name "Stretch reminder" \
--at "20m" \
--session main \
--system-event "Reminder: stand up and stretch." \
--wake nowgo deeper
Recall the three flags: --at for once, --every for a fixed interval, --cron for an expression, and that offset-less --at times are UTC.
Explain where --tz applies, why a cron expression without it follows the Gateway host clock, and how one-shots delete themselves after success.
Show you can predict real firing times: top-of-hour stagger, the day-of-month or day-of-week OR rule, and catch-up after downtime with cron.skipMissedJobs.
Discuss pinning every schedule to an explicit IANA zone as a team rule, and whether missed runs should catch up or be skipped for each kind of job.
## Where OpenClaw keeps a schedule OpenClaw's scheduler is part of the **Gateway**, the long-running daemon that connects chat channels to agents. A scheduled job is not a line in the host's crontab: job definitions, runtime state and run history sit in OpenClaw's shared SQLite state database, so they survive restarts, and the job fires only while the Gateway process is running. You manage jobs with `openclaw cron` (since 2026.8.1 the same commands also answer to `openclaw automations`). Creating, editing, removing or manually running a job needs `operator.admin`. Every job has exactly one **schedule** and one **payload** (what runs: a system event, an agent message, a command or a script). This question is about the schedule. ## The three time-based schedule flags | Flag | Kind | Accepts | `--tz` | |---|---|---|---| | `--at` | one-shot | ISO 8601 timestamp, or a delay such as `20m` | valid for offset-less timestamps | | `--every` | fixed interval | durations such as `10m`, `1h`, `1d` | rejected | | `--cron` | expression | 5-field, or 6-field with seconds | valid; sets the evaluation zone | Two event-driven kinds also exist (`--on-exit` and `--stream-command`), but they fire on a watched process rather than the clock. ## Time zones: the part people get wrong - **Offset-less `--at` timestamps are UTC.** `--at "2026-11-02T07:00:00"` means 07:00 UTC unless you add `--tz` with an IANA name such as `America/New_York`. - **`--cron` without `--tz` uses the Gateway host's time zone**, not UTC and not the agent's `agents.defaults.userTimezone`. A VPS set to UTC runs `0 7 * * 1-5` at 07:00 UTC. - **`--every` has no zone at all**; it counts an interval, so `--tz` is an error there. - Invalid `--tz` values are rejected before the job is saved, and nonexistent local times during a daylight-saving jump are reported as `--at` errors. ## A worked example: the weekday briefing A person in Berlin wants a summary at 7:00 every weekday, posted to Telegram. The schedule is `--cron "0 7 * * 1-5"` with `--tz "Europe/Berlin"`, so daylight-saving changes are handled by the zone rather than by editing the expression. The payload is an agent `--message` in an isolated session, with announce delivery to the chat. ```bash openclaw cron add \ --name "Weekday briefing" \ --cron "0 7 * * 1-5" \ --tz "Europe/Berlin" \ --session isolated \ --message "Summarize today's calendar and overnight email." \ --announce --channel telegram --to "123456789" ``` A one-off reminder in twenty minutes is simpler: `--at "20m"` with a `--system-event` for the main session. ## Behaviours that surprise people 1. **Top-of-hour stagger.** A recurring expression with minute `0` and a wildcard hour, such as `0 * * * *`, is spread over a window of up to 5 minutes to avoid load spikes. `--exact` disables it; `--stagger 30s` sets an explicit window. `0 7 * * 1-5` has a fixed hour, so it is not staggered by default. 2. **Day-of-month and day-of-week are ORed.** Expressions are parsed by croner, which follows Vixie cron: `0 9 15 * 1` fires on every 15th *and* every Monday. Use croner's `+1` modifier or guard one condition in the job itself. 3. **One-shots clean up after success.** An `--at` job is deleted after a successful run; a failed or unknown required delivery keeps it, disabled, for inspection. `--keep-after-run` keeps successful ones too. 4. **Missed runs catch up by default.** If the Gateway was down, recurring slots are caught up after restart. `cron.skipMissedJobs: true` (added in 2026.9.1) moves `cron` and `every` jobs to their next future slot instead. 5. **The Gateway must be running.** `cron.enabled: false` or `OPENCLAW_SKIP_CRON=1` in the Gateway's environment stops all automatic runs. ## Choosing between them - **Use `--at`** for anything that happens once: a reminder, a follow-up after a meeting, a check tomorrow morning. Relative delays such as `2h` avoid time-zone arithmetic entirely. - **Use `--every`** when the spacing matters more than the clock: every `30m`, regardless of calendar boundaries; `--tz` has no meaning here. - **Use `--cron`** when the wall clock matters: weekdays at 7:00, the first Monday of a month, 18:00 on Fridays. Pair it with `--tz` so the job follows local time through daylight-saving changes. - **Changing your mind** does not need a new job: `openclaw cron edit <jobId>` accepts the same schedule flags and replaces the schedule in place, keeping the payload and delivery settings. ## Checking what you created - `openclaw cron list` shows enabled jobs and their next run; `--all` adds disabled ones. - `openclaw cron show <jobId>` gives the human view, including the resolved delivery route. - `openclaw cron runs <jobId>` lists run history, so you can confirm the job fired when you expected. Knowing which flag fits is the junior bar; knowing that a cron expression without `--tz` follows the host clock is what keeps the 7 a.m. briefing at 7 a.m.
- Why might an OpenClaw job with `--cron "0 9 15 * 1"` fire far more often than intended?OpenClaw parses cron expressions with croner, which follows Vixie cron: when both day-of-month and day-of-week are non-wildcard, either one matching is enough. So `0 9 15 * 1` fires at 9:00 on every 15th and on every Monday, roughly five or six times a month. Use croner's `+` modifier (`0 9 15 * +1`) to require both, or schedule on one field and check the other inside the job.
- What happens to a recurring OpenClaw job whose slot passed while the Gateway was stopped?By default the scheduler catches up missed work after the Gateway restarts; overdue agent-turn jobs are rescheduled rather than fired the instant the Gateway starts. Setting `cron.skipMissedJobs: true`, added in 2026.9.1, instead advances `cron` and `every` jobs to their next future slot, avoiding stale reminders and extra model calls at the cost of dropping the missed run. One-shot `--at` jobs still catch up either way.
- OpenClaw cron jobs are written into the host's system crontab.
- A cron expression without --tz is always evaluated in UTC.
- Adding --tz Europe/Berlin to an --every 1d job pins it to Berlin midnight.
- A one-shot --at job stays listed after it succeeds unless you remove it.
- An expression like 0 * * * * always fires exactly on the hour.
Assumes OpenClaw 2026.9.9; openclaw automations became an alias of openclaw cron in 2026.8.1 and cron.skipMissedJobs arrived in 2026.9.1.