skip to content

Proactive Runs

What makes OpenClaw act without being messaged: heartbeat turns, scheduled cron jobs, HTTP-triggered runs and internal hooks on lifecycle events. Interviewers ask about cost and runaway work.

part ofAI coding toolsread it →
on this pageshow

explore

questions

17

In OpenClaw, how do `--at`, `--every` and `--cron` schedules differ when you add a job with `openclaw cron add`, and where does `--tz` apply?

level: juniorimportance: must knowfreq 14%

answer

  1. one-shot, interval, expression
  2. offset-less timestamps read as UTC
  3. --tz names an IANA zone
  4. no --tz means the Gateway host zone
  5. 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 s

All 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 lines
bash
openclaw cron add \
  --name "Stretch reminder" \
  --at "20m" \
  --session main \
  --system-event "Reminder: stand up and stretch." \
  --wake now

go deeper

for a junior

Recall the three flags: --at for once, --every for a fixed interval, --cron for an expression, and that offset-less --at times are UTC.

for a middle

Explain where --tz applies, why a cron expression without it follows the Gateway host clock, and how one-shots delete themselves after success.

for a senior

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.

for a principal

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.

open as a page

In OpenClaw, what is a heartbeat, how often does it run by default, and how does it stay silent when nothing needs attention?

level: juniorimportance: must knowfreq 18%

basics

~20 s

An OpenClaw heartbeat is a system-owned automation that runs a periodic agent turn in the main session, every 30m by default (1h with Anthropic OAuth/token auth). When nothing needs attention the agent replies NO_REPLY and nothing is sent.

open as a page

An OpenClaw owner wants each `/new` to save the old conversation and every command logged: which bundled hooks do this, and what do they record?

level: middleimportance: must knowfreq 14%

basics

~10 s

Enable the bundled session-memory and command-logger hooks with openclaw hooks enable. session-memory saves the last 15 user and assistant messages to memory/YYYY-MM-DD-HHMM.md; command-logger appends one JSON line per /new, /reset or /stop to logs/commands.log.

open as a page

An OpenClaw heartbeat burns tokens all day checking an inbox; which heartbeat settings cut its per-run cost, and what does each trade away?

level: seniorimportance: must knowfreq 12%

basics

~20 s

Each OpenClaw heartbeat is a full agent turn. Cut cost with isolatedSession: true (no chat history), lightContext: true (no workspace bootstrap files), a cheaper model, a longer every and activeHours; each trades away context or judgment.

open as a page

Why does OpenClaw treat internal hooks as fully trusted code, and what should you check before enabling a workspace hook or a downloaded hook pack?

level: seniorimportance: must knowfreq 9%

basics

~20 s

OpenClaw internal hooks run inside the Gateway process with its filesystem, network and environment access, and no sandbox wraps them. Before enabling one, read its handler and HOOK.md, see what it stores or sends, and pin where it came from.

open as a page

In OpenClaw, what is an internal hook made of, and how does it choose which Gateway events it handles?

level: juniorimportance: should knowfreq 10%

basics

~20 s

An OpenClaw internal hook is a folder holding HOOK.md and a JavaScript or TypeScript handler. HOOK.md's metadata.openclaw.events array subscribes it to exact keys such as command:new or message:received, or to a whole family such as command.

open as a page

An OpenClaw isolated cron job runs on schedule but its report never reaches the team Slack channel — how is delivery decided, and what do you check?

level: middleimportance: should knowfreq 6%

basics

~20 s

Isolated jobs default to announce: the runner posts the final reply to the resolved channel and target unless the agent already sent it. Check the route with openclaw cron show, then run history for delivery errors or suppression.

open as a page

When a CI pipeline should alert an OpenClaw agent about a failed build, when do you call `/hooks/wake` and when `/hooks/agent`?

level: middleimportance: should knowfreq 7%

basics

~20 s

Use /hooks/wake for a short trusted notice that the main session should handle, now or at the next heartbeat. Use /hooks/agent to start a separate agent turn on a message, isolated by default, that can deliver its own result to a chat channel.

open as a page

For an OpenClaw cron job, when should it run with `--session main` rather than `--session isolated`, and what changes between them?

level: middleimportance: should knowfreq 9%

basics

~20 s

A main-session job drops a system event into the agent's main session, handled with that conversation's context. An isolated job runs its own agent turn in a fresh cron session each time and can announce its result to a chat channel.

open as a page

An OpenClaw heartbeat pings its owner at 3 a.m.; how do you confine it with `activeHours`, and which timezone does that window use?

level: middleimportance: should knowfreq 10%

basics

~10 s

Set agents.defaults.heartbeat.activeHours with start and end in HH:MM and an optional timezone. Ticks outside the window are skipped, not queued. Without timezone it uses agents.defaults.userTimezone, else the host's timezone.

open as a page

Where does an OpenClaw heartbeat deliver its alerts by default, and why might a poll be skipped with `reason=no-route`?

level: middleimportance: should knowfreq 6%

basics

~20 s

By default target is owner: the first concrete entry in commands.ownerAllowFrom, then a channel allowFrom, as a direct message and never a group. With no resolvable owner DM, the poll is skipped as reason=no-route before the agent runs.

open as a page

How does OpenClaw authenticate requests to its `/hooks` endpoints, what does it reject, and how should `hooks.token` be managed?

level: seniorimportance: should knowfreq 5%

basics

~20 s

Hook endpoints stay off until hooks.enabled is set with a nonempty hooks.token, sent as Authorization: Bearer or x-openclaw-token. A token query parameter gets 400, a wrong token 401, repeated failures 429. Use a dedicated token, never the Gateway auth secret.

open as a page

An OpenClaw hook shows as ready in `openclaw hooks list`, yet its side effect never appears: how do you find out why?

level: seniorimportance: should knowfreq 5%

basics

~20 s

In OpenClaw, ready means requirements pass, policy allows the hook and it declares events, not that the Gateway loaded it. Check the master switch and named entries on the Gateway host, read the Gateway log, then trigger the exact event.

open as a page

In an OpenClaw internal hook handler, what can returning a value or pushing to `event.messages` actually change?

level: middleimportance: nice to knowfreq 4%

basics

~20 s

An OpenClaw hook handler's return value is ignored, so it cannot block, cancel or rewrite anything. Strings pushed to event.messages become a chat reply only for /new and /reset from chat, reach compaction callbacks, and are dropped elsewhere.

open as a page

An OpenClaw recurring cron job starts failing every night — what does the scheduler do on its own, and how do you find out?

level: seniorimportance: nice to knowfreq 3%

basics

~20 s

Recurring failures back off (30s, 1m, 5m, 15m, 60m) until a success. A job with an alert route alerts after 2 consecutive failures with a 1-hour cooldown, and after 10 consecutive failures the scheduler auto-disables it and notifies the owning agent.

open as a page

After upgrading OpenClaw, edits to the workspace HEARTBEAT.md checklist no longer change what the heartbeat checks; why, and what do you do instead?

level: seniorimportance: nice to knowfreq 4%

basics

~20 s

In OpenClaw 2026.9.9 the runtime never reads a workspace HEARTBEAT.md; heartbeat instructions come from the monitor job's scratch in the state database. Run openclaw doctor --fix to import the file, then edit with openclaw cron scratch <jobId>.

open as a page

Rolling OpenClaw out for a small team, how do you decide how proactive its heartbeat should be: cadence, hours, reach, and what it may do unprompted?

level: principalimportance: nice to knowfreq 3%

basics

~20 s

Start narrow and widen with evidence: owner-DM delivery, team-timezone active hours, an isolated light monitor unless chat context earns its cost, and separate jobs for recurring work. Tool policy, not the prompt, limits unprompted actions.

open as a page