mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-12 21:53:00 -06:00
docs(automation): rename scheduled-tasks feature wording to Automations (#114855)
* docs(automation): rename scheduled-tasks feature wording to Automations Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WhJ8EiMXue6ADLmHfb7FL6 * docs: regenerate docs map and add Automations glossary entries * docs(templates): follow renamed automations-vs-heartbeat anchor * docs(automation): fix markdown formatting drift * docs(automation): teach the canonical automations tool and sync the copied heartbeat default Review follow-ups: normal instructions use the automations tool with cron as an explicit compatibility alias; every verbatim copy of the default heartbeat prompt matches the new shipped text from the strings PR. --------- Co-authored-by: Omar Shahine <10343873+omarshahine@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Omar Shahine
@@ -1694,5 +1694,13 @@
|
||||
{
|
||||
"source": "TOOLS.md retired",
|
||||
"target": "TOOLS.md 已弃用"
|
||||
},
|
||||
{
|
||||
"source": "Automations",
|
||||
"target": "自动化"
|
||||
},
|
||||
{
|
||||
"source": "Automations (cron)",
|
||||
"target": "自动化 (cron)"
|
||||
}
|
||||
]
|
||||
|
||||
+103
-101
@@ -1,65 +1,67 @@
|
||||
---
|
||||
summary: "Scheduled jobs, webhooks, and Gmail PubSub triggers for the Gateway scheduler"
|
||||
summary: "Automations: scheduled jobs, webhooks, and Gmail PubSub triggers for the Gateway scheduler"
|
||||
read_when:
|
||||
- Scheduling background jobs or wakeups
|
||||
- Wiring external triggers (webhooks, Gmail) into OpenClaw
|
||||
- Deciding between heartbeat and cron for scheduled tasks
|
||||
title: "Scheduled tasks"
|
||||
sidebarTitle: "Scheduled tasks"
|
||||
- Deciding between heartbeat and automations for scheduled work
|
||||
title: "Automations"
|
||||
sidebarTitle: "Automations"
|
||||
---
|
||||
|
||||
Cron is the Gateway's built-in scheduler. It persists jobs, wakes the agent at the right time, and can deliver output to a chat channel, a webhook, or nowhere.
|
||||
Automations are OpenClaw's built-in scheduler. The scheduler persists jobs, wakes the agent at the right time, and can deliver output to a chat channel, a webhook, or nowhere.
|
||||
|
||||
Manage automations with the `openclaw automations` CLI; `openclaw cron` remains an alias for the same commands.
|
||||
|
||||
## Quick start
|
||||
|
||||
<Steps>
|
||||
<Step title="Add a one-shot reminder">
|
||||
```bash
|
||||
openclaw cron create "2027-02-01T16:00:00Z" \
|
||||
openclaw automations create "2027-02-01T16:00:00Z" \
|
||||
--name "Reminder" \
|
||||
--session main \
|
||||
--system-event "Reminder: check the cron docs draft" \
|
||||
--system-event "Reminder: check the automations docs draft" \
|
||||
--wake now \
|
||||
--delete-after-run
|
||||
```
|
||||
</Step>
|
||||
<Step title="Check your jobs">
|
||||
```bash
|
||||
openclaw cron list
|
||||
openclaw cron get <job-id>
|
||||
openclaw cron show <job-id>
|
||||
openclaw automations list
|
||||
openclaw automations get <job-id>
|
||||
openclaw automations show <job-id>
|
||||
```
|
||||
</Step>
|
||||
<Step title="See run history">
|
||||
```bash
|
||||
openclaw cron runs --id <job-id>
|
||||
openclaw automations runs --id <job-id>
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## How cron works
|
||||
## How automations work
|
||||
|
||||
- Cron runs **inside the Gateway process**, not inside the model. The Gateway must be running for schedules to fire.
|
||||
- Automations run **inside the Gateway process**, not inside the model. The Gateway must be running for schedules to fire.
|
||||
- Job definitions, runtime state, and run history persist in OpenClaw's shared SQLite state database, so restarts do not lose schedules.
|
||||
- Every cron execution creates a [background task](/automation/tasks) record.
|
||||
- Every automation run creates a [background task](/automation/tasks) record.
|
||||
- One-shot jobs (`--at`) auto-delete after success by default; pass `--keep-after-run` to keep them.
|
||||
- Per-run wall-clock budget: `--timeout-seconds` when set. Otherwise, isolated/detached agent-turn jobs are bounded by cron's own 60-minute watchdog before the underlying agent-turn timeout (`agents.defaults.timeoutSeconds`, default 48 hours) would ever apply; command jobs default to 10 minutes, and script payloads default to 5 minutes.
|
||||
- Per-run wall-clock budget: `--timeout-seconds` when set. Otherwise, isolated/detached agent-turn jobs are bounded by the scheduler's own 60-minute watchdog before the underlying agent-turn timeout (`agents.defaults.timeoutSeconds`, default 48 hours) would ever apply; command jobs default to 10 minutes, and script payloads default to 5 minutes.
|
||||
- On Gateway startup, overdue isolated agent-turn jobs are rescheduled instead of replayed immediately, keeping model/tool bootstrap work out of the channel-connect window.
|
||||
- If you drive `openclaw agent` from system cron or another external scheduler, wrap it with a hard-kill escalation even though the CLI already handles `SIGTERM`/`SIGINT`. Gateway-backed runs ask the Gateway to abort accepted runs; `--local` runs get the same abort signal. For GNU `timeout`, prefer `timeout -k 60 600 openclaw agent ...` over plain `timeout 600 ...` — the `-k` value is the backstop if the process cannot drain in time. For systemd units, use a `SIGTERM` stop signal with a grace window (`TimeoutStopSec`) before the final kill. Reusing a `--run-id` while the original Gateway run is still active reports the duplicate as in-flight instead of starting a second run.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Isolated run hardening">
|
||||
- Isolated runs best-effort close tracked browser tabs/processes for their `cron:<jobId>` session on completion, and dispose any bundled MCP runtime instances created for the job through the same shared teardown path used by main-session and custom-session runs. Cleanup failures are ignored so the cron result still wins.
|
||||
- Isolated runs with the narrow cron self-cleanup grant can read scheduler status, a self-filtered list containing only their own job, and that job's run history, and may remove only their own job.
|
||||
- Isolated runs best-effort close tracked browser tabs/processes for their `cron:<jobId>` session on completion, and dispose any bundled MCP runtime instances created for the job through the same shared teardown path used by main-session and custom-session runs. Cleanup failures are ignored so the run result still wins.
|
||||
- Isolated runs with the narrow automation self-cleanup grant can read scheduler status, a self-filtered list containing only their own job, and that job's run history, and may remove only their own job.
|
||||
- Isolated runs guard against stale acknowledgement replies: if the first result is only an interim status update (`on it`, `pulling everything together`, and similar hints) and no descendant subagent is still responsible for the final answer, OpenClaw re-prompts once for the actual result before delivery.
|
||||
- Structured execution-denial metadata (including node-host `UNAVAILABLE` wrappers whose nested error starts with `SYSTEM_RUN_DENIED` or `INVALID_REQUEST`) is recognized so a blocked command is not reported as a green run, while ordinary assistant prose is not mistaken for a denial.
|
||||
- Run-level agent failures count as job errors even with no reply payload, so model/provider failures increment error counters and trigger failure notifications instead of clearing the job as successful.
|
||||
- When a job hits `timeoutSeconds`, cron aborts the run and gives it a short cleanup window. If it does not drain, Gateway-owned cleanup force-clears that run's session ownership before cron records the timeout, so queued chat work is not stuck behind a stale processing session.
|
||||
- When a job hits `timeoutSeconds`, the scheduler aborts the run and gives it a short cleanup window. If it does not drain, Gateway-owned cleanup force-clears that run's session ownership before the scheduler records the timeout, so queued chat work is not stuck behind a stale processing session.
|
||||
- Setup/startup stalls get a phase-specific timeout (for example `cron: isolated agent setup timed out before runner start` or `cron: isolated agent run stalled before execution start (last phase: context-engine)`). These watchdogs cover embedded and CLI-backed providers even before their external CLI process starts, and are capped independently of long `timeoutSeconds` values so cold-start/auth/context failures surface quickly.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Task reconciliation">
|
||||
Cron task reconciliation is runtime-owned first, durable-history-backed second: an active cron task stays live while the cron runtime still tracks that job as running, even if an old child session row still exists. Once the runtime stops owning the job and a 5-minute grace window expires, maintenance checks persisted run logs and job state for the matching `cron:<jobId>:<startedAt>` run. A terminal result there finalizes the task ledger; otherwise Gateway-owned maintenance can mark the task `lost`. Offline CLI audit can recover from durable history, but its own empty in-process active-job set is not proof a Gateway-owned run is gone.
|
||||
Automation task reconciliation is runtime-owned first, durable-history-backed second: an active automation task stays live while the automations runtime still tracks that job as running, even if an old child session row still exists. Once the runtime stops owning the job and a 5-minute grace window expires, maintenance checks persisted run logs and job state for the matching `cron:<jobId>:<startedAt>` run. A terminal result there finalizes the task ledger; otherwise Gateway-owned maintenance can mark the task `lost`. Offline CLI audit can recover from durable history, but its own empty in-process active-job set is not proof a Gateway-owned run is gone.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -79,18 +81,18 @@ Recurring top-of-hour expressions (minute `0` with a wildcard hour field) are au
|
||||
|
||||
### Heartbeat task migration
|
||||
|
||||
Older heartbeat scratch supported a structured `tasks:` block. Run `openclaw doctor --fix` after upgrading to convert each entry into an ordinary editable main-session cron job. Doctor preserves the interval and previous last-run timing, creates the jobs before removing the block, and safely converges the same declaration keys on rerun.
|
||||
Older heartbeat scratch supported a structured `tasks:` block. Run `openclaw doctor --fix` after upgrading to convert each entry into an ordinary editable main-session automation job. Doctor preserves the interval and previous last-run timing, creates the jobs before removing the block, and safely converges the same declaration keys on rerun.
|
||||
|
||||
These migrated jobs carry public `systemEvent` payloads, so `openclaw cron list`, `get`, `edit`, and `remove` plus the cron tool manage them like other jobs. Their execution uses the guarded heartbeat task wake: active hours, minimum spacing, flood control, and busy retries still apply, while cron owns each task's independent cadence. Jobs due in the same coalescing window can share one heartbeat turn. A scheduled occurrence outside heartbeat active hours is skipped and retried at the job's next occurrence.
|
||||
These migrated jobs carry public `systemEvent` payloads, so `openclaw automations list`, `get`, `edit`, and `remove` plus the `automations` agent tool manage them like other jobs (the tool still accepts its legacy `cron` name as a compatibility alias). Their execution uses the guarded heartbeat task wake: active hours, minimum spacing, flood control, and busy retries still apply, while the scheduler owns each task's independent cadence. Jobs due in the same coalescing window can share one heartbeat turn. A scheduled occurrence outside heartbeat active hours is skipped and retried at the job's next occurrence.
|
||||
|
||||
Heartbeat scratch is now monitor prose only. Runtime heartbeats do not parse `tasks:` text as schedules; create new recurring work with cron.
|
||||
Heartbeat scratch is now monitor prose only. Runtime heartbeats do not parse `tasks:` text as schedules; create new recurring work as automations.
|
||||
|
||||
### Stream sources
|
||||
|
||||
A stream schedule keeps an operator-authored argv command running under the Gateway and fires the job from its stdout and stderr lines. Stream schedules are event-driven, never time-due, and require `cron.triggers.enabled: true` because the long-lived command has the same unattended trust class as trigger scripts. Disabling or removing the job stops the process; Gateway shutdown waits for process-tree teardown. Fast failures restart with cron's built-in error backoff. Five consecutive runs shorter than 60 seconds leave the job in an error state and use the normal failure-alert path; manually re-enable the job to clear the restart cap.
|
||||
A stream schedule keeps an operator-authored argv command running under the Gateway and fires the job from its stdout and stderr lines. Stream schedules are event-driven, never time-due, and require `cron.triggers.enabled: true` because the long-lived command has the same unattended trust class as trigger scripts. Disabling or removing the job stops the process; Gateway shutdown waits for process-tree teardown. Fast failures restart with the scheduler's built-in error backoff. Five consecutive runs shorter than 60 seconds leave the job in an error state and use the normal failure-alert path; manually re-enable the job to clear the restart cap.
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
openclaw automations add \
|
||||
--name "Build event stream" \
|
||||
--stream-command '["node","scripts/build-events.mjs"]' \
|
||||
--stream-mode match \
|
||||
@@ -108,9 +110,9 @@ When a stream job also has `trigger.script`, the gate runs once per closed batch
|
||||
|
||||
### Dynamic cadence (pacing)
|
||||
|
||||
Recurring jobs can set `pacing.min` and/or `pacing.max` to duration strings such as `15m` or `4h`; at least one bound is required. Use `--pacing-min` and `--pacing-max` with `cron add|edit` (`--clear-pacing` removes both bounds).
|
||||
Recurring jobs can set `pacing.min` and/or `pacing.max` to duration strings such as `15m` or `4h`; at least one bound is required. Use `--pacing-min` and `--pacing-max` with `automations add|edit` (`--clear-pacing` removes both bounds).
|
||||
|
||||
During an agent-turn run, a paced job can call the `cron` tool with `action: "next_check"` and `in: "30m"`. The proposal applies only to that currently running job and is measured from successful run completion. OpenClaw silently clamps it to the configured bounds.
|
||||
During an agent-turn run, a paced job can call the `automations` tool with `action: "next_check"` and `in: "30m"`. The proposal applies only to that currently running job and is measured from successful run completion. OpenClaw silently clamps it to the configured bounds.
|
||||
|
||||
Pacing without a proposal leaves the normal schedule unchanged. Failed, timed-out, and skipped runs discard the proposal, so existing retry and error-backoff behavior takes precedence. Manually forcing a recurring job is out-of-band and preserves its pending natural or paced slot. For condition-triggered jobs, the built-in minimum interval remains a lower bound even when a proposal requests an earlier check.
|
||||
|
||||
@@ -132,7 +134,7 @@ This fires roughly 5-6 times a month instead of 0-1 times a month. To require bo
|
||||
|
||||
## Event triggers (condition watchers)
|
||||
|
||||
An event trigger adds a headless condition script to an `every`, `cron`, or `stream` schedule. Time schedules evaluate it when due; stream schedules evaluate it for each closed batch. Cron runs the normal payload only when the script returns `fire: true`:
|
||||
An event trigger adds a headless condition script to an `every`, `cron`, or `stream` schedule. Time schedules evaluate it when due; stream schedules evaluate it for each closed batch. The scheduler runs the normal payload only when the script returns `fire: true`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -146,20 +148,20 @@ An event trigger adds a headless condition script to an `every`, `cron`, or `str
|
||||
}
|
||||
```
|
||||
|
||||
The script must return `{ fire, message?, state? }`. The previous JSON state is available as the deeply frozen `trigger.state`; stream gates also receive the current batch as `trigger.streamBatch`. Return a new `state` value to persist it. State is capped at 16 KB. When a firing result includes `message`, cron appends it to the system-event text or agent-turn message before execution. `once: true` disables the job after its first successful fired payload.
|
||||
The script must return `{ fire, message?, state? }`. The previous JSON state is available as the deeply frozen `trigger.state`; stream gates also receive the current batch as `trigger.streamBatch`. Return a new `state` value to persist it. State is capped at 16 KB. When a firing result includes `message`, the scheduler appends it to the system-event text or agent-turn message before execution. `once: true` disables the job after its first successful fired payload.
|
||||
|
||||
`fire: false` persists evaluation state and counters, then reschedules without creating run history. If a fired payload run fails, the returned `state` is **not** persisted — the next evaluation sees the previous state and can fire again, so write scripts as read-only checks and keep actions in the payload. Trigger schedules have a built-in minimum interval of 30 seconds. Each evaluation has a 30-second wall-clock budget and up to 5 tool calls.
|
||||
|
||||
Author watchers around **actionable state**, not only success: a watcher that goes quiet when its check fails or times out looks healthy while broken. Compare the observation with `trigger.state` and return fresh state to deduplicate; do not rely on model or process memory. When firing, make `message` self-contained because it becomes the fired run's complete event context.
|
||||
|
||||
<Warning>
|
||||
Enabling `cron.triggers.enabled` permits both condition-trigger scripts and `script` payloads to run headlessly with the owning agent's **full tool policy, including `exec`**. Treat this as unattended code execution with that agent's permissions; leave it disabled unless every agent allowed to create cron jobs is trusted accordingly.
|
||||
Enabling `cron.triggers.enabled` permits both condition-trigger scripts and `script` payloads to run headlessly with the owning agent's **full tool policy, including `exec`**. Treat this as unattended code execution with that agent's permissions; leave it disabled unless every agent allowed to create automation jobs is trusted accordingly.
|
||||
</Warning>
|
||||
|
||||
Create a watcher from a local script file (`-` reads the script from stdin):
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
openclaw automations add \
|
||||
--name "PR CI watcher" \
|
||||
--every 30s \
|
||||
--trigger-script ./watch-pr-ci.js \
|
||||
@@ -178,7 +180,7 @@ Every job carries exactly one payload kind, chosen by flag:
|
||||
| Command | `--command <shell>` or `--command-argv <json>` | A shell/process on the Gateway host, no model call |
|
||||
| Script | `--script <file\|->` | A headless code-mode script using the owning agent's tools |
|
||||
|
||||
One additional payload kind, `heartbeat`, is system-owned: the gateway converges one heartbeat monitor job per heartbeat-enabled agent (see [Heartbeat](/gateway/heartbeat)). It appears in `cron list --all` but cannot be created or edited through the CLI or API. Heartbeat config is written through to the persisted monitor schedule at startup, on config reload, or by `openclaw doctor --fix`. When cron is disabled, the monitor does not tick and no fallback heartbeat timer runs.
|
||||
One additional payload kind, `heartbeat`, is system-owned: the gateway converges one heartbeat monitor job per heartbeat-enabled agent (see [Heartbeat](/gateway/heartbeat)). It appears in `automations list --all` but cannot be created or edited through the CLI or API. Heartbeat config is written through to the persisted monitor schedule at startup, on config reload, or by `openclaw doctor --fix`. When automations are disabled, the monitor does not tick and no fallback heartbeat timer runs.
|
||||
|
||||
### Agent-turn options
|
||||
|
||||
@@ -192,16 +194,16 @@ One additional payload kind, `heartbeat`, is system-owned: the gateway converges
|
||||
Per-job fallback model list, for example `--fallbacks openai/gpt-5.6-sol,openrouter/meta-llama/llama-3.3-70b-instruct:free`. Pass `--fallbacks ""` for a strict run with no fallbacks.
|
||||
</ParamField>
|
||||
<ParamField path="--clear-fallbacks" type="boolean">
|
||||
On `cron edit`, removes the per-job fallback override so the job follows configured fallback precedence. Cannot combine with `--fallbacks`.
|
||||
On `automations edit`, removes the per-job fallback override so the job follows configured fallback precedence. Cannot combine with `--fallbacks`.
|
||||
</ParamField>
|
||||
<ParamField path="--clear-model" type="boolean">
|
||||
On `cron edit`, removes the per-job model override so the job follows normal cron model precedence (stored cron-session override, else agent/default model). Cannot combine with `--model`.
|
||||
On `automations edit`, removes the per-job model override so the job follows normal automation model precedence (stored automation-session override, else agent/default model). Cannot combine with `--model`.
|
||||
</ParamField>
|
||||
<ParamField path="--thinking" type="string">
|
||||
Thinking level override (`off|minimal|low|medium|high|xhigh|adaptive|max|ultra`). Available levels still depend on the selected model and agent runtime.
|
||||
</ParamField>
|
||||
<ParamField path="--clear-thinking" type="boolean">
|
||||
On `cron edit`, removes the per-job thinking override. Cannot combine with `--thinking`.
|
||||
On `automations edit`, removes the per-job thinking override. Cannot combine with `--thinking`.
|
||||
</ParamField>
|
||||
<ParamField path="--light-context" type="boolean">
|
||||
Skip workspace bootstrap file injection.
|
||||
@@ -213,7 +215,7 @@ One additional payload kind, `heartbeat`, is system-owned: the gateway converges
|
||||
New jobs that can run tools always store an explicit tool policy. Jobs created by an agent
|
||||
are capped to the tools available to that creating turn, and the agent cannot widen the
|
||||
stored list. Jobs created by an authenticated operator without `--tools` store an
|
||||
unrestricted `*` policy; `cron edit --clear-tools` restores that explicit unrestricted
|
||||
unrestricted `*` policy; `automations edit --clear-tools` restores that explicit unrestricted
|
||||
policy. Existing jobs that predate an explicit tool policy retain their current behavior
|
||||
until their tool policy is explicitly edited or the job is recreated.
|
||||
|
||||
@@ -223,25 +225,25 @@ Model-selection precedence for isolated jobs, highest first:
|
||||
|
||||
1. Per-job payload `model` (explicit config; a disallowed model fails the run)
|
||||
2. Gmail hook model override (only when the run came from Gmail and that override is allowed)
|
||||
3. User-selected stored cron-session model override
|
||||
3. User-selected stored automation-session model override
|
||||
4. Agent/default model selection
|
||||
|
||||
Fast mode follows the resolved live selection. If the selected model config has `params.fastMode`, isolated cron uses it by default; a stored session `fastMode` override (then an agent `fastModeDefault`) still wins over model config either direction. Auto mode uses the model's `params.fastAutoOnSeconds` cutoff, defaulting to 60 seconds.
|
||||
Fast mode follows the resolved live selection. If the selected model config has `params.fastMode`, isolated automation runs use it by default; a stored session `fastMode` override (then an agent `fastModeDefault`) still wins over model config either direction. Auto mode uses the model's `params.fastAutoOnSeconds` cutoff, defaulting to 60 seconds.
|
||||
|
||||
If a run hits a live model-switch handoff, cron retries with the switched provider/model and persists that selection (and any new auth profile) for the active run. Retries are bounded: after the initial attempt plus 2 switch retries, cron aborts instead of looping.
|
||||
If a run hits a live model-switch handoff, the scheduler retries with the switched provider/model and persists that selection (and any new auth profile) for the active run. Retries are bounded: after the initial attempt plus 2 switch retries, the scheduler aborts instead of looping.
|
||||
|
||||
Before an isolated run starts, OpenClaw checks reachable local endpoints for configured `api: "ollama"` and `api: "openai-completions"` providers whose `baseUrl` is loopback, private-network, or `.local`. This preflight walks the job's configured fallback chain and only marks the run `skipped` once every candidate is unreachable; `--fallbacks ""` keeps that walk strict to just the primary model. A down endpoint records the run as `skipped` with a clear error instead of starting a model call. The result is cached for 5 minutes per endpoint (not per job or model), so many due jobs sharing a dead local Ollama/vLLM/SGLang/LM Studio server cost one probe instead of a request storm. Skipped preflight runs do not increment execution-error backoff; set `failureAlert.includeSkipped` to opt into repeated skip alerts.
|
||||
|
||||
### Command payloads
|
||||
|
||||
Command payloads run deterministic scripts inside the Gateway scheduler without starting a model-backed turn. They execute on the Gateway host, capture stdout/stderr, record the run in cron history, and reuse the same `announce`, `webhook`, and `none` delivery modes as agent-turn jobs.
|
||||
Command payloads run deterministic scripts inside the Gateway scheduler without starting a model-backed turn. They execute on the Gateway host, capture stdout/stderr, record the run in the job's run history, and reuse the same `announce`, `webhook`, and `none` delivery modes as agent-turn jobs.
|
||||
|
||||
<Note>
|
||||
Command cron is an operator-admin Gateway automation surface, not an agent `tools.exec` call. Creating, updating, removing, or manually running cron jobs requires `operator.admin`; scheduled command runs later execute inside the Gateway process as that admin-authored automation. Agent exec policy (`tools.exec.mode`, approval prompts, per-agent tool allowlists) governs model-visible exec tools, not command cron payloads.
|
||||
Command payloads are an operator-admin Gateway automation surface, not an agent `tools.exec` call. Creating, updating, removing, or manually running automation jobs requires `operator.admin`; scheduled command runs later execute inside the Gateway process as that admin-authored automation. Agent exec policy (`tools.exec.mode`, approval prompts, per-agent tool allowlists) governs model-visible exec tools, not command payloads.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
openclaw cron create "*/15 * * * *" \
|
||||
openclaw automations create "*/15 * * * *" \
|
||||
--name "Queue depth probe" \
|
||||
--command "scripts/check-queue.sh" \
|
||||
--command-cwd "/srv/app" \
|
||||
@@ -252,14 +254,14 @@ openclaw cron create "*/15 * * * *" \
|
||||
|
||||
`--command <shell>` stores `argv: ["sh", "-lc", <shell>]`. Use `--command-argv '["node","scripts/report.mjs"]'` for exact argv execution without shell parsing. Optional `--command-env KEY=VALUE` (repeatable), `--command-input`, `--timeout-seconds` (default 10 minutes), `--no-output-timeout-seconds`, and `--output-max-bytes` control the process environment, stdin, and output bounds.
|
||||
|
||||
Delivered text is derived from process output: non-empty stdout wins; if stdout is empty and stderr is non-empty, stderr is delivered; if both are present, cron sends a small `stdout:` / `stderr:` block. Exit code `0` records the run `ok`; non-zero exit, signal, timeout, or no-output timeout records `error` and can trigger failure alerts. A command that prints only `NO_REPLY` uses the normal cron silent-token suppression and posts nothing back to chat.
|
||||
Delivered text is derived from process output: non-empty stdout wins; if stdout is empty and stderr is non-empty, stderr is delivered; if both are present, the scheduler sends a small `stdout:` / `stderr:` block. Exit code `0` records the run `ok`; non-zero exit, signal, timeout, or no-output timeout records `error` and can trigger failure alerts. A command that prints only `NO_REPLY` uses the normal automation silent-token suppression and posts nothing back to chat.
|
||||
|
||||
### Script payloads
|
||||
|
||||
Script payloads run headlessly in the same code-mode executor as trigger scripts, without starting a conversational agent turn. Enable `cron.triggers.enabled` before creating or running them; this dangerous-automation gate covers both trigger scripts and script payloads. Script jobs support only `main` and `isolated` session targets.
|
||||
|
||||
```bash
|
||||
openclaw cron create "0 * * * *" \
|
||||
openclaw automations create "0 * * * *" \
|
||||
--name "Hourly queue check" \
|
||||
--script ./automation/check-queue.js \
|
||||
--script-timeout-seconds 300 \
|
||||
@@ -277,37 +279,37 @@ The script may return an object with these optional fields:
|
||||
- `state`: JSON state, capped at 16 KB and persisted only after a successful run. The next run receives a frozen copy as `trigger.state`, matching trigger scripts. Because that namespace has one persisted owner, a script payload cannot be combined with a condition trigger on the same job.
|
||||
- `nextCheck`: A duration such as `"15m"`. It is valid only for jobs with pacing enabled and uses the same pacing clamp as agent-turn proposals.
|
||||
|
||||
Throws, timeouts, exhausted tool budgets, invalid results, and `nextCheck` without pacing are normal cron run errors: they enter run history, backoff, and failure-alert handling without persisting returned state.
|
||||
Throws, timeouts, exhausted tool budgets, invalid results, and `nextCheck` without pacing are normal automation run errors: they enter run history, backoff, and failure-alert handling without persisting returned state.
|
||||
|
||||
## Execution styles
|
||||
|
||||
| Style | `--session` value | Runs in | Best for |
|
||||
| --------------- | ------------------- | ------------------------ | ------------------------------- |
|
||||
| Main session | `main` | Dedicated cron wake lane | Reminders, system events |
|
||||
| Isolated | `isolated` | Dedicated `cron:<jobId>` | Reports, background chores |
|
||||
| Current session | `current` | Bound at creation time | Context-aware recurring work |
|
||||
| Custom session | `session:custom-id` | Persistent named session | Workflows that build on history |
|
||||
| Style | `--session` value | Runs in | Best for |
|
||||
| --------------- | ------------------- | ------------------------- | ------------------------------- |
|
||||
| Main session | `main` | Dedicated automation lane | Reminders, system events |
|
||||
| Isolated | `isolated` | Dedicated `cron:<jobId>` | Reports, background chores |
|
||||
| Current session | `current` | Bound at creation time | Context-aware recurring work |
|
||||
| Custom session | `session:custom-id` | Persistent named session | Workflows that build on history |
|
||||
|
||||
Agent-turn jobs default to the creating conversation when the create request carries session context. Callers without a session key, including CLI and API callers that do not supply one, fall back to `isolated`. System events and heartbeats still default to `main`; command and script payloads still default to `isolated`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Main session vs isolated vs custom">
|
||||
**Main session** jobs enqueue a system event into a cron-owned run lane and optionally wake the heartbeat (`--wake now` or `--wake next-heartbeat`). They can use the target main session's last delivery context for replies, but do not append routine cron turns to the human chat lane and do not extend daily/idle reset freshness for the target session. **Isolated** jobs run a dedicated agent turn with a fresh session. **Custom sessions** (`session:xxx`) persist context across runs, enabling workflows like daily standups that build on previous summaries.
|
||||
**Main session** jobs enqueue a system event into a scheduler-owned run lane and optionally wake the heartbeat (`--wake now` or `--wake next-heartbeat`). They can use the target main session's last delivery context for replies, but do not append routine automation turns to the human chat lane and do not extend daily/idle reset freshness for the target session. **Isolated** jobs run a dedicated agent turn with a fresh session. **Custom sessions** (`session:xxx`) persist context across runs, enabling workflows like daily standups that build on previous summaries.
|
||||
|
||||
Main-session cron events are self-contained system-event reminders. They do not automatically include the default heartbeat prompt or the heartbeat monitor scratch; say it explicitly in the cron event text if a reminder should consult that context.
|
||||
Main-session automation events are self-contained system-event reminders. They do not automatically include the default heartbeat prompt or the heartbeat monitor scratch; say it explicitly in the automation event text if a reminder should consult that context.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="What 'fresh session' means for isolated jobs">
|
||||
A new transcript/session id per run. OpenClaw carries safe preferences (thinking/fast/verbose settings, labels, explicit user-selected model/auth overrides), but does not inherit ambient conversation context from an older cron row: channel/group routing, send or queue policy, elevation, origin, or ACP runtime binding. Use `current` or `session:<id>` when a recurring job should deliberately build on the same conversation context.
|
||||
A new transcript/session id per run. OpenClaw carries safe preferences (thinking/fast/verbose settings, labels, explicit user-selected model/auth overrides), but does not inherit ambient conversation context from an older automation session row: channel/group routing, send or queue policy, elevation, origin, or ACP runtime binding. Use `current` or `session:<id>` when a recurring job should deliberately build on the same conversation context.
|
||||
</Accordion>
|
||||
<Accordion title="Unattended run contract">
|
||||
Isolated cron and hook agent turns are explicitly unattended: no one is present to clarify or approve. The final reply must be the deliverable rather than a plan, acknowledgement, or request for input. The agent returns `HEARTBEAT_OK` when nothing needs doing and states failures plainly; cron owns retry and failure-alert policy.
|
||||
Isolated automation and hook agent turns are explicitly unattended: no one is present to clarify or approve. The final reply must be the deliverable rather than a plan, acknowledgement, or request for input. The agent returns `HEARTBEAT_OK` when nothing needs doing and states failures plainly; the scheduler owns retry and failure-alert policy.
|
||||
|
||||
For trusted scheduled jobs, the job's own instructions win when they intentionally ask for a question or plan, and the agent may remove a job that is no longer needed. External hook turns receive only the common unattended contract; they do not receive that override or self-removal guidance across the external-content boundary.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Subagent and Discord delivery">
|
||||
When isolated cron runs orchestrate subagents, delivery prefers the final descendant output over stale parent interim text. If descendants are still running, OpenClaw suppresses that partial parent update instead of announcing it.
|
||||
When isolated automation runs orchestrate subagents, delivery prefers the final descendant output over stale parent interim text. If descendants are still running, OpenClaw suppresses that partial parent update instead of announcing it.
|
||||
|
||||
For text-only Discord announce targets, OpenClaw sends the canonical final assistant text once instead of replaying both streamed/intermediate text and the final answer. Media and structured Discord payloads are still delivered separately so attachments and components are not dropped.
|
||||
|
||||
@@ -324,7 +326,7 @@ Agent-turn jobs default to the creating conversation when the create request car
|
||||
|
||||
Use `--announce --channel telegram --to "-1001234567890"` for channel delivery. For Telegram forum topics, use `-1001234567890:topic:123`; OpenClaw also accepts the Telegram-owned `-1001234567890:123` shorthand. Direct RPC/config callers may pass `delivery.threadId` as a string or number. Slack/Discord/Mattermost targets use explicit prefixes (`channel:<id>`, `user:<id>`). Matrix room IDs are case-sensitive; use the exact room ID or `room:!room:server` form from Matrix.
|
||||
|
||||
When announce delivery uses `channel: "last"` or omits `channel`, a provider-prefixed target such as `telegram:123` can select the channel before cron falls back to session history or a single configured channel. Only prefixes advertised by the loaded plugin are provider selectors. If `delivery.channel` is explicit, the target prefix must name the same provider; `channel: "whatsapp"` with `to: "telegram:123"` is rejected instead of letting WhatsApp interpret the Telegram ID as a phone number. Target-kind and service prefixes (`channel:<id>`, `user:<id>`, `imessage:<handle>`, `sms:<number>`) stay channel-owned target syntax, not provider selectors.
|
||||
When announce delivery uses `channel: "last"` or omits `channel`, a provider-prefixed target such as `telegram:123` can select the channel before the scheduler falls back to session history or a single configured channel. Only prefixes advertised by the loaded plugin are provider selectors. If `delivery.channel` is explicit, the target prefix must name the same provider; `channel: "whatsapp"` with `to: "telegram:123"` is rejected instead of letting WhatsApp interpret the Telegram ID as a phone number. Target-kind and service prefixes (`channel:<id>`, `user:<id>`, `imessage:<handle>`, `sms:<number>`) stay channel-owned target syntax, not provider selectors.
|
||||
|
||||
For isolated jobs, chat delivery is shared: if a chat route is available, the agent can use the `message` tool even with `--no-deliver`. If the agent sends to the configured/current target, OpenClaw skips the fallback announce. Otherwise `announce`, `webhook`, and `none` only control what the runner does with the final reply after the agent turn.
|
||||
|
||||
@@ -340,17 +342,17 @@ Failure notifications follow a separate destination path:
|
||||
- `job.delivery.failureDestination` overrides that per job.
|
||||
- If neither is set and the job already delivers via `announce`, failure notifications fall back to that primary announce target.
|
||||
- `delivery.failureDestination` is only supported on `sessionTarget="isolated"` jobs unless the primary delivery mode is `webhook`.
|
||||
- `failureAlert.includeSkipped: true` opts a job or global cron alert policy into repeated skipped-run alerts. Skipped runs keep a separate consecutive-skip counter, so they do not affect execution-error backoff.
|
||||
- `openclaw cron edit` exposes per-job alert tuning: `--failure-alert`/`--no-failure-alert`, `--failure-alert-after <n>`, `--failure-alert-channel`, `--failure-alert-to`, `--failure-alert-cooldown`, `--failure-alert-include-skipped`/`--failure-alert-exclude-skipped`, `--failure-alert-mode`, and `--failure-alert-account-id`.
|
||||
- `failureAlert.includeSkipped: true` opts a job or global automation alert policy into repeated skipped-run alerts. Skipped runs keep a separate consecutive-skip counter, so they do not affect execution-error backoff.
|
||||
- `openclaw automations edit` exposes per-job alert tuning: `--failure-alert`/`--no-failure-alert`, `--failure-alert-after <n>`, `--failure-alert-channel`, `--failure-alert-to`, `--failure-alert-cooldown`, `--failure-alert-include-skipped`/`--failure-alert-exclude-skipped`, `--failure-alert-mode`, and `--failure-alert-account-id`.
|
||||
|
||||
Chat failure notifications include the run start time in the agent's configured user timezone. Webhook message text stays stable; integrations can read the same instant from the structured `runAtMs` field.
|
||||
|
||||
### Output language
|
||||
|
||||
Cron jobs do not infer a reply language from channel, locale, or previous messages. Put the language rule in the scheduled message or template:
|
||||
Automation jobs do not infer a reply language from channel, locale, or previous messages. Put the language rule in the scheduled message or template:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <jobId> \
|
||||
openclaw automations edit <jobId> \
|
||||
--message "Summarize the updates. Respond in Chinese; keep URLs, code, and product names unchanged."
|
||||
```
|
||||
|
||||
@@ -361,7 +363,7 @@ For template files, keep the language instruction in the rendered prompt and ver
|
||||
<Tabs>
|
||||
<Tab title="One-shot reminder">
|
||||
```bash
|
||||
openclaw cron add \
|
||||
openclaw automations add \
|
||||
--name "Calendar check" \
|
||||
--at "20m" \
|
||||
--session main \
|
||||
@@ -371,7 +373,7 @@ For template files, keep the language instruction in the rendered prompt and ver
|
||||
</Tab>
|
||||
<Tab title="Recurring isolated job">
|
||||
```bash
|
||||
openclaw cron create "0 7 * * *" \
|
||||
openclaw automations create "0 7 * * *" \
|
||||
"Summarize overnight updates." \
|
||||
--name "Morning brief" \
|
||||
--tz "America/Los_Angeles" \
|
||||
@@ -383,7 +385,7 @@ For template files, keep the language instruction in the rendered prompt and ver
|
||||
</Tab>
|
||||
<Tab title="Model and thinking override">
|
||||
```bash
|
||||
openclaw cron add \
|
||||
openclaw automations add \
|
||||
--name "Deep analysis" \
|
||||
--cron "0 6 * * 1" \
|
||||
--tz "America/Los_Angeles" \
|
||||
@@ -396,7 +398,7 @@ For template files, keep the language instruction in the rendered prompt and ver
|
||||
</Tab>
|
||||
<Tab title="Webhook output">
|
||||
```bash
|
||||
openclaw cron create "0 18 * * 1-5" \
|
||||
openclaw automations create "0 18 * * 1-5" \
|
||||
"Summarize today's deploys as JSON." \
|
||||
--name "Deploy digest" \
|
||||
--webhook "https://example.invalid/openclaw/cron"
|
||||
@@ -404,7 +406,7 @@ For template files, keep the language instruction in the rendered prompt and ver
|
||||
</Tab>
|
||||
<Tab title="Command output">
|
||||
```bash
|
||||
openclaw cron create "*/15 * * * *" \
|
||||
openclaw automations create "*/15 * * * *" \
|
||||
--name "Queue depth probe" \
|
||||
--command "scripts/check-queue.sh" \
|
||||
--command-cwd "/srv/app" \
|
||||
@@ -419,65 +421,65 @@ For template files, keep the language instruction in the rendered prompt and ver
|
||||
|
||||
```bash
|
||||
# List enabled jobs
|
||||
openclaw cron list
|
||||
openclaw automations list
|
||||
|
||||
# Include disabled jobs
|
||||
openclaw cron list --all
|
||||
openclaw automations list --all
|
||||
|
||||
# Get one stored job as JSON
|
||||
openclaw cron get <jobId>
|
||||
openclaw automations get <jobId>
|
||||
|
||||
# Show one job, including resolved delivery route
|
||||
openclaw cron show <jobId>
|
||||
openclaw automations show <jobId>
|
||||
|
||||
# Enable/disable without deleting
|
||||
openclaw cron enable <jobId>
|
||||
openclaw cron disable <jobId>
|
||||
openclaw automations enable <jobId>
|
||||
openclaw automations disable <jobId>
|
||||
|
||||
# Edit a job
|
||||
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"
|
||||
openclaw automations edit <jobId> --message "Updated prompt" --model "opus"
|
||||
|
||||
# Force run a job now
|
||||
openclaw cron run <jobId>
|
||||
openclaw automations run <jobId>
|
||||
|
||||
# Force run a job now and wait for its terminal status
|
||||
openclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s
|
||||
openclaw automations run <jobId> --wait --wait-timeout 10m --poll-interval 2s
|
||||
|
||||
# Run only if due
|
||||
openclaw cron run <jobId> --due
|
||||
openclaw automations run <jobId> --due
|
||||
|
||||
# View run history
|
||||
openclaw cron runs --id <jobId> --limit 50
|
||||
openclaw automations runs --id <jobId> --limit 50
|
||||
|
||||
# View one exact run
|
||||
openclaw cron runs --id <jobId> --run-id <runId>
|
||||
openclaw automations runs --id <jobId> --run-id <runId>
|
||||
|
||||
# Delete a job
|
||||
openclaw cron remove <jobId>
|
||||
openclaw automations remove <jobId>
|
||||
|
||||
# Agent selection (multi-agent setups)
|
||||
openclaw cron create "0 6 * * *" "Check ops queue" --name "Ops sweep" --session isolated --agent ops
|
||||
openclaw cron edit <jobId> --clear-agent
|
||||
openclaw automations create "0 6 * * *" "Check ops queue" --name "Ops sweep" --session isolated --agent ops
|
||||
openclaw automations edit <jobId> --clear-agent
|
||||
```
|
||||
|
||||
Archiving a session (Control UI, or `sessions.patch { archived: true }` from an operator-admin caller) disables every enabled cron job bound to that session: its isolated `cron:<jobId>` session, a `session:<key>` target, or a delivery/wake `sessionKey` lane. Restoring the session does not re-enable those jobs; use `openclaw cron enable <jobId>`. Sessions with an enabled bound job show a clock badge in the Control UI sidebar.
|
||||
Archiving a session (Control UI, or `sessions.patch { archived: true }` from an operator-admin caller) disables every enabled automation job bound to that session: its isolated `cron:<jobId>` session, a `session:<key>` target, or a delivery/wake `sessionKey` lane. Restoring the session does not re-enable those jobs; use `openclaw automations enable <jobId>`. Sessions with an enabled bound job show a clock badge in the Control UI sidebar.
|
||||
|
||||
`openclaw cron run <jobId>` returns after enqueueing the manual run. Use `--wait` for shutdown hooks, maintenance scripts, or other automation that must block until the queued run finishes; it polls the returned `runId` (default timeout `10m`, poll interval `2s`) and exits `0` for status `ok`, non-zero for `error`, `skipped`, or a wait timeout.
|
||||
`openclaw automations run <jobId>` returns after enqueueing the manual run. Use `--wait` for shutdown hooks, maintenance scripts, or other automation that must block until the queued run finishes; it polls the returned `runId` (default timeout `10m`, poll interval `2s`) and exits `0` for status `ok`, non-zero for `error`, `skipped`, or a wait timeout.
|
||||
|
||||
The agent `cron` tool returns compact job summaries (`id`, `name`, `enabled`, `nextRunAtMs`, `scheduleKind`, `lastRunStatus`) from `cron(action: "list")`; use `cron(action: "get", jobId: "...")` for one full job definition. Direct Gateway callers can pass `compact: true` to `cron.list`; omitting it preserves the full response with delivery previews.
|
||||
The agent `automations` tool returns compact job summaries (`id`, `name`, `enabled`, `nextRunAtMs`, `scheduleKind`, `lastRunStatus`) from `automations(action: "list")`; use `automations(action: "get", jobId: "...")` for one full job definition. Direct Gateway callers can pass `compact: true` to `cron.list`; omitting it preserves the full response with delivery previews.
|
||||
|
||||
`openclaw cron create` is an alias for `openclaw cron add`. New jobs can use a positional schedule (`"0 9 * * 1"`, `"every 1h"`, `"20m"`, or an ISO timestamp) followed by a positional agent prompt. Use `--webhook <url>` on `cron add|create` or `cron edit` to POST the finished run payload to an HTTP endpoint; webhook delivery cannot combine with chat delivery flags (`--announce`, `--channel`, `--to`, `--thread-id`, `--account`). On `cron edit`, `--clear-channel`, `--clear-to`, `--clear-thread-id`, and `--clear-account` unset those routing fields individually (each rejected alongside its matching set flag) — distinct from `--no-deliver`, which only disables runner fallback delivery.
|
||||
`openclaw automations create` is an alias for `openclaw automations add`. New jobs can use a positional schedule (`"0 9 * * 1"`, `"every 1h"`, `"20m"`, or an ISO timestamp) followed by a positional agent prompt. Use `--webhook <url>` on `automations add|create` or `automations edit` to POST the finished run payload to an HTTP endpoint; webhook delivery cannot combine with chat delivery flags (`--announce`, `--channel`, `--to`, `--thread-id`, `--account`). On `automations edit`, `--clear-channel`, `--clear-to`, `--clear-thread-id`, and `--clear-account` unset those routing fields individually (each rejected alongside its matching set flag) — distinct from `--no-deliver`, which only disables runner fallback delivery.
|
||||
|
||||
<Note>
|
||||
Model override note:
|
||||
|
||||
- `openclaw cron add|edit --model ...` changes the job's selected model.
|
||||
- `openclaw automations add|edit --model ...` changes the job's selected model.
|
||||
- If the model is allowed, that exact provider/model reaches the isolated agent run.
|
||||
- If it is not allowed or cannot be resolved, cron fails the run with an explicit validation error.
|
||||
- If it is not allowed or cannot be resolved, the scheduler fails the run with an explicit validation error.
|
||||
- API `cron.update` payload patches can set `model: null` to clear a stored job model override.
|
||||
- `openclaw cron edit <job-id> --clear-model` clears that override from the CLI (same effect as the `model: null` patch) and cannot combine with `--model`.
|
||||
- Configured fallback chains still apply because cron `--model` is a job primary, not a session `/model` override.
|
||||
- `openclaw cron add|edit --fallbacks ...` sets payload `fallbacks`, replacing configured fallbacks for that job; `--fallbacks ""` disables fallback and makes the run strict. `openclaw cron edit <job-id> --clear-fallbacks` clears the per-job override.
|
||||
- `openclaw automations edit <job-id> --clear-model` clears that override from the CLI (same effect as the `model: null` patch) and cannot combine with `--model`.
|
||||
- Configured fallback chains still apply because the automation `--model` is a job primary, not a session `/model` override.
|
||||
- `openclaw automations add|edit --fallbacks ...` sets payload `fallbacks`, replacing configured fallbacks for that job; `--fallbacks ""` disables fallback and makes the run strict. `openclaw automations edit <job-id> --clear-fallbacks` clears the per-job override.
|
||||
- A plain `--model` with no explicit or configured fallback list does not fall through to the agent primary as a silent extra retry target.
|
||||
|
||||
</Note>
|
||||
@@ -747,13 +749,13 @@ Use the latest-generation, best-tier model available from your provider for untr
|
||||
}
|
||||
```
|
||||
|
||||
`webhookToken` is sent as `Authorization: Bearer <token>` on cron webhook POSTs.
|
||||
`webhookToken` is sent as `Authorization: Bearer <token>` on automation webhook POSTs.
|
||||
Webhook URLs must not include embedded username/password credentials; use
|
||||
`webhookToken` when the receiver supports bearer authentication.
|
||||
|
||||
`cron.store` is a logical store key and doctor migration path, not a live JSON file to hand-edit. Job data lives in SQLite; use the CLI or Gateway API for changes.
|
||||
|
||||
Disable cron: `cron.enabled: false` or `OPENCLAW_SKIP_CRON=1`.
|
||||
Disable automations: `cron.enabled: false` or `OPENCLAW_SKIP_CRON=1`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Retry behavior">
|
||||
@@ -777,23 +779,23 @@ Disable cron: `cron.enabled: false` or `OPENCLAW_SKIP_CRON=1`.
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
openclaw cron status
|
||||
openclaw cron list
|
||||
openclaw cron runs --id <jobId> --limit 20
|
||||
openclaw automations status
|
||||
openclaw automations list
|
||||
openclaw automations runs --id <jobId> --limit 20
|
||||
openclaw system heartbeat last
|
||||
openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Cron not firing">
|
||||
<Accordion title="Automations not firing">
|
||||
- Check `cron.enabled` and the `OPENCLAW_SKIP_CRON` env var.
|
||||
- Confirm the Gateway is running continuously.
|
||||
- For `cron` schedules, verify timezone (`--tz`) vs the host timezone.
|
||||
- `reason: not-due` in run output means the manual run was checked with `openclaw cron run <jobId> --due` and the job was not due yet.
|
||||
- `reason: not-due` in run output means the manual run was checked with `openclaw automations run <jobId> --due` and the job was not due yet.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron fired but no delivery">
|
||||
<Accordion title="Job fired but no delivery">
|
||||
- Delivery mode `none` means no runner fallback send is expected. The agent can still send directly with the `message` tool when a chat route is available.
|
||||
- Delivery target missing/invalid (`channel`/`to`) means outbound was skipped.
|
||||
- For Matrix, copied or legacy jobs with lowercased `delivery.to` room IDs can fail because Matrix room IDs are case-sensitive. Edit the job to the exact `!room:server` or `room:!room:server` value from Matrix.
|
||||
@@ -802,14 +804,14 @@ openclaw doctor
|
||||
- If the agent should message the user itself, check that the job has a usable route (`channel: "last"` with a previous chat, or an explicit channel/target).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron or heartbeat appears to prevent /new-style rollover">
|
||||
<Accordion title="Automations or heartbeat appear to prevent /new-style rollover">
|
||||
- Daily and idle reset freshness is not based on `updatedAt`; see [Session management](/concepts/session#session-lifecycle).
|
||||
- Cron wakeups, heartbeat runs, exec notifications, and gateway bookkeeping may update the session row for routing/status, but they do not extend `sessionStartedAt` or `lastInteractionAt`.
|
||||
- Automation wakeups, heartbeat runs, exec notifications, and gateway bookkeeping may update the session row for routing/status, but they do not extend `sessionStartedAt` or `lastInteractionAt`.
|
||||
- For legacy rows created before those fields existed, OpenClaw can recover `sessionStartedAt` from the transcript JSONL session header when the file is still available. Legacy idle rows without `lastInteractionAt` use that recovered start time as their idle baseline.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Timezone gotchas">
|
||||
- Cron without `--tz` uses the gateway host timezone.
|
||||
- Cron expressions without `--tz` use the gateway host timezone.
|
||||
- `at` schedules without timezone are treated as UTC.
|
||||
- Heartbeat `activeHours` uses configured timezone resolution.
|
||||
|
||||
@@ -819,6 +821,6 @@ openclaw doctor
|
||||
## Related
|
||||
|
||||
- [Automation](/automation) — all automation mechanisms at a glance
|
||||
- [Background Tasks](/automation/tasks) — task ledger for cron executions
|
||||
- [Background Tasks](/automation/tasks) — task ledger for automation runs
|
||||
- [Heartbeat](/gateway/heartbeat) — periodic main-session turns
|
||||
- [Timezone](/concepts/timezone) — timezone configuration
|
||||
|
||||
@@ -3,10 +3,10 @@ summary: "Redirect to /automation"
|
||||
title: "Cron vs heartbeat"
|
||||
---
|
||||
|
||||
This page moved. See [Scheduled Tasks (Cron) vs Heartbeat](/automation#scheduled-tasks-cron-vs-heartbeat) for the decision table.
|
||||
This page moved. See [Automations vs Heartbeat](/automation#automations-vs-heartbeat) for the decision table.
|
||||
|
||||
## Related
|
||||
|
||||
- [Scheduled tasks](/automation/cron-jobs)
|
||||
- [Automations](/automation/cron-jobs)
|
||||
- [Heartbeat](/gateway/heartbeat)
|
||||
- [Background tasks](/automation/tasks)
|
||||
|
||||
+28
-28
@@ -1,9 +1,9 @@
|
||||
---
|
||||
doc-schema-version: 1
|
||||
summary: "Overview of automation mechanisms: tasks, cron, hooks, standing orders, and Task Flow"
|
||||
summary: "Overview of automation mechanisms: tasks, automations, hooks, standing orders, and Task Flow"
|
||||
read_when:
|
||||
- Deciding how to automate work with OpenClaw
|
||||
- Choosing between heartbeat, cron, hooks, and standing orders
|
||||
- Choosing between heartbeat, automations, hooks, and standing orders
|
||||
- Looking for the right automation entry point
|
||||
title: "Automation"
|
||||
---
|
||||
@@ -22,7 +22,7 @@ flowchart TD
|
||||
START --> Q5{Give the agent persistent instructions?}
|
||||
|
||||
Q1 -->|Yes| Q1a{Exact timing or flexible?}
|
||||
Q1a -->|Exact| CRON["Scheduled Tasks (Cron)"]
|
||||
Q1a -->|Exact| CRON["Automations"]
|
||||
Q1a -->|Flexible| HEARTBEAT[Heartbeat]
|
||||
|
||||
Q2 -->|Yes| TASKS[Background Tasks]
|
||||
@@ -31,23 +31,23 @@ flowchart TD
|
||||
Q5 -->|Yes| SO[Standing Orders]
|
||||
```
|
||||
|
||||
| Use case | Recommended | Why |
|
||||
| --------------------------------------- | ---------------------- | ------------------------------------------------ |
|
||||
| Send daily report at 9 AM sharp | Scheduled Tasks (Cron) | Exact timing, isolated execution |
|
||||
| Remind me in 20 minutes | Scheduled Tasks (Cron) | One-shot with precise timing (`--at`) |
|
||||
| Run weekly deep analysis | Scheduled Tasks (Cron) | Standalone task, can use different model |
|
||||
| Check inbox every 30 min | Heartbeat | Batches with other checks, context-aware |
|
||||
| Monitor calendar for upcoming events | Heartbeat | Natural fit for periodic awareness |
|
||||
| Inspect status of a subagent or ACP run | Background Tasks | Tasks ledger tracks all detached work |
|
||||
| Audit what ran and when | Background Tasks | `openclaw tasks list` and `openclaw tasks audit` |
|
||||
| Multi-step research then summarize | Task Flow | Durable orchestration with revision tracking |
|
||||
| Run a script on session reset | Hooks | Event-driven, fires on lifecycle events |
|
||||
| Execute code on every tool call | Plugin hooks | In-process hooks can intercept tool calls |
|
||||
| Always check compliance before replying | Standing Orders | Injected into every session automatically |
|
||||
| Use case | Recommended | Why |
|
||||
| --------------------------------------- | ---------------- | ------------------------------------------------ |
|
||||
| Send daily report at 9 AM sharp | Automations | Exact timing, isolated execution |
|
||||
| Remind me in 20 minutes | Automations | One-shot with precise timing (`--at`) |
|
||||
| Run weekly deep analysis | Automations | Standalone task, can use different model |
|
||||
| Check inbox every 30 min | Heartbeat | Batches with other checks, context-aware |
|
||||
| Monitor calendar for upcoming events | Heartbeat | Natural fit for periodic awareness |
|
||||
| Inspect status of a subagent or ACP run | Background Tasks | Tasks ledger tracks all detached work |
|
||||
| Audit what ran and when | Background Tasks | `openclaw tasks list` and `openclaw tasks audit` |
|
||||
| Multi-step research then summarize | Task Flow | Durable orchestration with revision tracking |
|
||||
| Run a script on session reset | Hooks | Event-driven, fires on lifecycle events |
|
||||
| Execute code on every tool call | Plugin hooks | In-process hooks can intercept tool calls |
|
||||
| Always check compliance before replying | Standing Orders | Injected into every session automatically |
|
||||
|
||||
### Scheduled Tasks (Cron) vs Heartbeat
|
||||
### Automations vs Heartbeat
|
||||
|
||||
| Dimension | Scheduled Tasks (Cron) | Heartbeat |
|
||||
| Dimension | Automations | Heartbeat |
|
||||
| --------------- | ----------------------------------- | ------------------------------------- |
|
||||
| Timing | Exact (cron expressions, one-shot) | Approximate (default every 30 min) |
|
||||
| Session context | Fresh (isolated) or shared | Full main-session context |
|
||||
@@ -55,19 +55,19 @@ flowchart TD
|
||||
| Delivery | Channel, webhook, or silent | Inline in main session |
|
||||
| Best for | Reports, reminders, background jobs | Inbox checks, calendar, notifications |
|
||||
|
||||
Use Scheduled Tasks (Cron) when you need precise timing or isolated execution. Use Heartbeat when the work benefits from full session context and approximate timing is fine.
|
||||
Use Automations when you need precise timing or isolated execution. Use Heartbeat when the work benefits from full session context and approximate timing is fine.
|
||||
|
||||
## Core concepts
|
||||
|
||||
### Scheduled tasks (cron)
|
||||
### Automations
|
||||
|
||||
Cron is the Gateway's built-in scheduler for precise timing. It persists jobs, wakes the agent at the right time, and can deliver output to a chat channel or webhook endpoint. Supports one-shot reminders, recurring expressions, and inbound webhook triggers.
|
||||
Automations are OpenClaw's built-in scheduler for precise timing. The scheduler persists jobs, wakes the agent at the right time, and can deliver output to a chat channel or webhook endpoint. Supports one-shot reminders, recurring cron expressions, and inbound webhook triggers.
|
||||
|
||||
See [Scheduled Tasks](/automation/cron-jobs).
|
||||
See [Automations](/automation/cron-jobs).
|
||||
|
||||
### Tasks
|
||||
|
||||
The background task ledger tracks all detached work: ACP runs, subagent spawns, isolated cron executions, and CLI operations. Tasks are records, not schedulers. Use `openclaw tasks list` and `openclaw tasks audit` to inspect them.
|
||||
The background task ledger tracks all detached work: ACP runs, subagent spawns, isolated automation runs, and CLI operations. Tasks are records, not schedulers. Use `openclaw tasks list` and `openclaw tasks audit` to inspect them.
|
||||
|
||||
See [Background Tasks](/automation/tasks).
|
||||
|
||||
@@ -79,7 +79,7 @@ See [Task Flow](/automation/taskflow).
|
||||
|
||||
### Standing orders
|
||||
|
||||
Standing orders grant the agent permanent operating authority for defined programs. They live in workspace files (typically `AGENTS.md`) and are injected into every session. Combine with cron for time-based enforcement.
|
||||
Standing orders grant the agent permanent operating authority for defined programs. They live in workspace files (typically `AGENTS.md`) and are injected into every session. Combine with automations for time-based enforcement.
|
||||
|
||||
See [Standing Orders](/automation/standing-orders).
|
||||
|
||||
@@ -95,14 +95,14 @@ See [Hooks](/automation/hooks).
|
||||
|
||||
### Heartbeat
|
||||
|
||||
Heartbeat is a periodic main-session turn (default every 30 minutes). It batches checklist-style monitoring (inbox, calendar, notifications) in one agent turn with full session context. Heartbeat turns do not create task records and do not extend daily/idle session reset freshness. Heartbeat monitor scratch is small prompt context; schedule recurring work as cron jobs. Empty scratch skips as `empty-heartbeat-file`. Scheduled heartbeats automatically defer while the main queue or cron work is busy, another reply or embedded run for the same agent is active, or the resolved target session has active or queued work.
|
||||
Heartbeat is a periodic main-session turn (default every 30 minutes). It batches checklist-style monitoring (inbox, calendar, notifications) in one agent turn with full session context. Heartbeat turns do not create task records and do not extend daily/idle session reset freshness. Heartbeat monitor scratch is small prompt context; schedule recurring work as automation jobs. Empty scratch skips as `empty-heartbeat-file`. Scheduled heartbeats automatically defer while the main queue or automation work is busy, another reply or embedded run for the same agent is active, or the resolved target session has active or queued work.
|
||||
|
||||
See [Heartbeat](/gateway/heartbeat).
|
||||
|
||||
## How they work together
|
||||
|
||||
- **Cron** handles precise schedules (daily reports, weekly reviews) and one-shot reminders. All cron executions create task records.
|
||||
- **Heartbeat** handles one batched monitoring checklist every 30 minutes; cron owns checks that need independent cadences.
|
||||
- **Automations** handle precise schedules (daily reports, weekly reviews) and one-shot reminders. All automation runs create task records.
|
||||
- **Heartbeat** handles one batched monitoring checklist every 30 minutes; automations own checks that need independent cadences.
|
||||
- **Hooks** react to specific events (session resets, compaction, message flow) with custom scripts. Plugin hooks cover tool calls.
|
||||
- **Standing orders** give the agent persistent context and authority boundaries.
|
||||
- **Task Flow** coordinates multi-step flows above individual tasks.
|
||||
@@ -110,7 +110,7 @@ See [Heartbeat](/gateway/heartbeat).
|
||||
|
||||
## Related
|
||||
|
||||
- [Scheduled Tasks](/automation/cron-jobs) — precise scheduling and one-shot reminders
|
||||
- [Automations](/automation/cron-jobs) — precise scheduling and one-shot reminders
|
||||
- [Background Tasks](/automation/tasks) — task ledger for all detached work
|
||||
- [Task Flow](/automation/taskflow) — durable multi-step flow orchestration
|
||||
- [Hooks](/automation/hooks) — event-driven lifecycle scripts
|
||||
|
||||
@@ -28,7 +28,7 @@ Each program specifies:
|
||||
3. **Approval gates** - what requires human sign-off before acting
|
||||
4. **Escalation rules** - when to stop and ask for help
|
||||
|
||||
The agent loads these instructions every session via the workspace bootstrap files (see [Agent Workspace](/concepts/agent-workspace) for the full list of auto-injected files) and executes against them, combined with [cron jobs](/automation/cron-jobs) for time-based enforcement.
|
||||
The agent loads these instructions every session via the workspace bootstrap files (see [Agent Workspace](/concepts/agent-workspace) for the full list of auto-injected files) and executes against them, combined with [automations](/automation/cron-jobs) for time-based enforcement.
|
||||
|
||||
<Tip>
|
||||
Put standing orders in `AGENTS.md` to guarantee they're loaded every session. The workspace bootstrap automatically injects `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `BOOTSTRAP.md`, and `MEMORY.md` - but not arbitrary files in subdirectories.
|
||||
@@ -40,7 +40,7 @@ Put standing orders in `AGENTS.md` to guarantee they're loaded every session. Th
|
||||
## Program: Weekly Status Report
|
||||
|
||||
**Authority:** Compile data, generate report, deliver to stakeholders
|
||||
**Trigger:** Every Friday at 4 PM (enforced via cron job)
|
||||
**Trigger:** Every Friday at 4 PM (enforced via automation job)
|
||||
**Approval gate:** None for standard reports. Flag anomalies for human review.
|
||||
**Escalation:** If data source is unavailable or metrics look unusual (>2σ from norm)
|
||||
|
||||
@@ -59,22 +59,22 @@ Put standing orders in `AGENTS.md` to guarantee they're loaded every session. Th
|
||||
- Do not skip delivery if metrics look bad - report accurately
|
||||
```
|
||||
|
||||
## Standing orders plus cron jobs
|
||||
## Standing orders plus automations
|
||||
|
||||
Standing orders define **what** the agent is authorized to do. [Cron jobs](/automation/cron-jobs) define **when** it happens. They work together:
|
||||
Standing orders define **what** the agent is authorized to do. [Automations](/automation/cron-jobs) define **when** it happens. They work together:
|
||||
|
||||
```text
|
||||
Standing Order: "You own the daily inbox triage"
|
||||
↓
|
||||
Cron Job (8 AM daily): "Execute inbox triage per standing orders"
|
||||
Automation (8 AM daily): "Execute inbox triage per standing orders"
|
||||
↓
|
||||
Agent: Reads standing orders → executes steps → reports results
|
||||
```
|
||||
|
||||
The cron job prompt should reference the standing order rather than duplicating it:
|
||||
The automation job prompt should reference the standing order rather than duplicating it (`openclaw automations`; `openclaw cron` remains an alias):
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
openclaw automations add \
|
||||
--name daily-inbox-triage \
|
||||
--cron "0 8 * * 1-5" \
|
||||
--tz America/New_York \
|
||||
@@ -219,7 +219,7 @@ Each program should have:
|
||||
- Start with narrow authority and expand as trust builds
|
||||
- Define explicit approval gates for high-risk actions
|
||||
- Include "What NOT to do" sections - boundaries matter as much as permissions
|
||||
- Combine with cron jobs for reliable time-based execution
|
||||
- Combine with automations for reliable time-based execution
|
||||
- Review agent logs weekly to verify standing orders are being followed
|
||||
- Update standing orders as your needs evolve - they're living documents
|
||||
|
||||
@@ -229,12 +229,12 @@ Each program should have:
|
||||
- Skip escalation rules - every program needs a "when to stop and ask" clause
|
||||
- Assume the agent will remember verbal instructions - put everything in the file
|
||||
- Mix concerns in a single program - separate programs for separate domains
|
||||
- Forget to enforce with cron jobs - standing orders without triggers become suggestions
|
||||
- Forget to enforce with automations - standing orders without triggers become suggestions
|
||||
|
||||
## Related
|
||||
|
||||
- [Automation](/automation): all automation mechanisms at a glance.
|
||||
- [Cron jobs](/automation/cron-jobs): schedule enforcement for standing orders.
|
||||
- [Automations](/automation/cron-jobs): schedule enforcement for standing orders.
|
||||
- [Hooks](/automation/hooks): event-driven scripts for agent lifecycle events.
|
||||
- [Webhooks](/automation/cron-jobs#webhooks): inbound HTTP event triggers.
|
||||
- [Agent workspace](/concepts/agent-workspace): where standing orders live, including the full list of auto-injected bootstrap files (`AGENTS.md`, `SOUL.md`, etc.).
|
||||
|
||||
@@ -16,7 +16,7 @@ Task Flow is the orchestration layer above [background tasks](/automation/tasks)
|
||||
| Single background job | Plain task |
|
||||
| Multi-step pipeline driven by plugin code | Task Flow (managed) |
|
||||
| Detached ACP or subagent spawn | Task Flow (mirrored, created automatically) |
|
||||
| One-shot reminder | Cron job |
|
||||
| One-shot reminder | Automation job |
|
||||
|
||||
## Sync modes
|
||||
|
||||
@@ -88,15 +88,15 @@ Flows are also covered by `openclaw tasks audit` (stale or broken flow findings)
|
||||
|
||||
For recurring workflows such as market intelligence briefings, treat the schedule, orchestration, and reliability checks as separate layers:
|
||||
|
||||
1. Use [Scheduled Tasks](/automation/cron-jobs) for timing.
|
||||
2. Use a persistent cron session when the workflow should build on prior context.
|
||||
1. Use [Automations](/automation/cron-jobs) for timing.
|
||||
2. Use a persistent automation session when the workflow should build on prior context.
|
||||
3. Use [Lobster](/tools/lobster) for deterministic steps, approval gates, and resume tokens.
|
||||
4. Use Task Flow to track the multi-step run across child tasks, waits, retries, and gateway restarts.
|
||||
|
||||
Example cron shape:
|
||||
Example automation job (`openclaw automations`; `openclaw cron` remains an alias):
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
openclaw automations add \
|
||||
--name "Market intelligence brief" \
|
||||
--cron "0 7 * * 1-5" \
|
||||
--tz "America/New_York" \
|
||||
@@ -138,7 +138,7 @@ Recommended preflight checks:
|
||||
- API credentials and quota for each source.
|
||||
- Network reachability for required endpoints.
|
||||
- Required tools enabled for the agent, such as `lobster`, `browser`, and `llm-task`.
|
||||
- Failure destination configured for cron so preflight failures are visible. See [Scheduled Tasks](/automation/cron-jobs#delivery-and-output).
|
||||
- Failure destination configured for the automation so preflight failures are visible. See [Automations](/automation/cron-jobs#delivery-and-output).
|
||||
|
||||
Recommended data provenance fields for every collected item:
|
||||
|
||||
@@ -165,4 +165,4 @@ Flows coordinate tasks, not replace them. A single flow may drive multiple backg
|
||||
- [Background Tasks](/automation/tasks) - the detached work ledger that flows coordinate
|
||||
- [CLI: tasks](/cli/tasks) - CLI command reference for `openclaw tasks flow`
|
||||
- [Automation Overview](/automation) - all automation mechanisms at a glance
|
||||
- [Cron Jobs](/automation/cron-jobs) - scheduled jobs that may feed into flows
|
||||
- [Automations](/automation/cron-jobs) - scheduled jobs that may feed into flows
|
||||
|
||||
+36
-36
@@ -1,9 +1,9 @@
|
||||
---
|
||||
summary: "Background task tracking for ACP runs, subagents, cron executions, and CLI operations"
|
||||
summary: "Background task tracking for ACP runs, subagents, automation runs, and CLI operations"
|
||||
read_when:
|
||||
- Inspecting background work in progress or recently completed
|
||||
- Debugging delivery failures for detached agent runs
|
||||
- Understanding how background runs relate to sessions, cron, and heartbeat
|
||||
- Understanding how background runs relate to sessions, automations, and heartbeat
|
||||
title: "Background tasks"
|
||||
sidebarTitle: "Background tasks"
|
||||
---
|
||||
@@ -12,25 +12,25 @@ sidebarTitle: "Background tasks"
|
||||
Looking for scheduling? See [Automation](/automation) for choosing the right mechanism. This page is the activity ledger for background work, not the scheduler.
|
||||
</Note>
|
||||
|
||||
Background tasks track work that runs **outside your main conversation session**: ACP runs, subagent spawns, cron job executions, and CLI-initiated operations.
|
||||
Background tasks track work that runs **outside your main conversation session**: ACP runs, subagent spawns, automation job runs, and CLI-initiated operations.
|
||||
|
||||
Tasks do **not** replace sessions, cron jobs, or heartbeats - they are the **activity ledger** that records what detached work happened, when, and whether it succeeded.
|
||||
Tasks do **not** replace sessions, automations, or heartbeats - they are the **activity ledger** that records what detached work happened, when, and whether it succeeded.
|
||||
|
||||
For a strict, ephemeral one-shot agent run in CI or a script, use [`openclaw agent exec`](/cli/agent#agent-exec) instead of managed background work.
|
||||
|
||||
<Note>
|
||||
Not every agent run creates a task. Heartbeat turns and normal interactive chat do not. All cron executions, ACP spawns, subagent spawns, gateway-dispatched CLI agent commands, and agent-started background `exec` commands do.
|
||||
Not every agent run creates a task. Heartbeat turns and normal interactive chat do not. All automation runs, ACP spawns, subagent spawns, gateway-dispatched CLI agent commands, and agent-started background `exec` commands do.
|
||||
</Note>
|
||||
|
||||
## TL;DR
|
||||
|
||||
- Tasks are **records**, not schedulers - cron and heartbeat decide _when_ work runs, tasks track _what happened_.
|
||||
- ACP, subagents, all cron jobs, and CLI operations create tasks. Heartbeat turns do not.
|
||||
- Tasks are **records**, not schedulers - automations and heartbeat decide _when_ work runs, tasks track _what happened_.
|
||||
- ACP, subagents, all automation jobs, and CLI operations create tasks. Heartbeat turns do not.
|
||||
- Each task moves through `queued → running → terminal` (succeeded, failed, timed_out, cancelled, or lost).
|
||||
- Cron tasks stay live while the cron runtime still owns the job; if the in-memory runtime state is gone, task maintenance first checks durable cron run history before marking a task lost.
|
||||
- Automation tasks stay live while the automations runtime still owns the job; if the in-memory runtime state is gone, task maintenance first checks durable automation run history before marking a task lost.
|
||||
- Completion is push-driven: detached work can notify directly or wake the requester session/heartbeat when it finishes, so status polling loops are usually the wrong shape.
|
||||
- Isolated cron runs and subagent completions best-effort clean up tracked browser tabs/processes for their child session before final cleanup bookkeeping.
|
||||
- Isolated cron delivery suppresses stale interim parent replies while descendant subagent work is still draining, and it prefers final descendant output when that arrives before delivery.
|
||||
- Isolated automation runs and subagent completions best-effort clean up tracked browser tabs/processes for their child session before final cleanup bookkeeping.
|
||||
- Isolated automation delivery suppresses stale interim parent replies while descendant subagent work is still draining, and it prefers final descendant output when that arrives before delivery.
|
||||
- Completion notifications are delivered directly to a channel or queued for the next heartbeat.
|
||||
- `openclaw tasks list` shows all tasks; `openclaw tasks audit` surfaces issues.
|
||||
- Terminal records are kept for 7 days (`lost` records for 24 hours), then automatically pruned.
|
||||
@@ -88,17 +88,17 @@ Not every agent run creates a task. Heartbeat turns and normal interactive chat
|
||||
|
||||
## What creates a task
|
||||
|
||||
| Source | Runtime type | When a task record is created | Default notify policy |
|
||||
| ---------------------- | ------------ | ---------------------------------------------------------------------- | --------------------- |
|
||||
| ACP background runs | `acp` | Spawning a child ACP session | `done_only` |
|
||||
| Subagent orchestration | `subagent` | Spawning a subagent via `sessions_spawn` | `done_only` |
|
||||
| Cron jobs (all types) | `cron` | Every cron execution (main-session and isolated) | `silent` |
|
||||
| CLI operations | `cli` | `openclaw agent` commands that run through the gateway | `silent` |
|
||||
| Agent media jobs | `cli` | Session-backed `image_generate`/`music_generate`/`video_generate` runs | `silent` |
|
||||
| Source | Runtime type | When a task record is created | Default notify policy |
|
||||
| --------------------------- | ------------ | ---------------------------------------------------------------------- | --------------------- |
|
||||
| ACP background runs | `acp` | Spawning a child ACP session | `done_only` |
|
||||
| Subagent orchestration | `subagent` | Spawning a subagent via `sessions_spawn` | `done_only` |
|
||||
| Automation jobs (all types) | `cron` | Every automation run (main-session and isolated) | `silent` |
|
||||
| CLI operations | `cli` | `openclaw agent` commands that run through the gateway | `silent` |
|
||||
| Agent media jobs | `cli` | Session-backed `image_generate`/`music_generate`/`video_generate` runs | `silent` |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Notify defaults for cron and media">
|
||||
Cron tasks (main-session and isolated) use `silent` notify policy - they create records for tracking but do not generate task notifications of their own; cron owns its delivery path.
|
||||
<Accordion title="Notify defaults for automations and media">
|
||||
Automation tasks (main-session and isolated) use `silent` notify policy - they create records for tracking but do not generate task notifications of their own; the scheduler owns its delivery path.
|
||||
|
||||
Session-backed `image_generate`, `music_generate`, and `video_generate` runs also use `silent` notify policy. They still create task records, but completion is handed back to the original agent session as an internal wake so the agent can write the follow-up message and attach the finished media itself. The requester agent follows its normal visible-reply contract: automatic final reply when configured, or `message(action="send")` plus `NO_REPLY` when the session requires message-tool replies. If the requester session is no longer active or its active wake fails, and the completion agent misses some or all generated media, OpenClaw sends an idempotent direct fallback with only the missing media to the original channel target.
|
||||
|
||||
@@ -147,7 +147,7 @@ Agent run completion is authoritative for active task records. A successful deta
|
||||
|
||||
- ACP tasks: only a live in-process ACP turn in the Gateway proves the run is alive; persisted session metadata alone does not. Offline CLI audit stays conservative and never reclaims ACP tasks.
|
||||
- Subagent tasks: backing child session disappeared from the target agent store (or carries a restart-recovery tombstone).
|
||||
- Cron tasks: the cron runtime no longer tracks the job as active and durable cron run history does not show a terminal result for that run. Offline CLI audit does not treat its own empty in-process cron runtime state as authority.
|
||||
- Automation tasks: the automations runtime no longer tracks the job as active and durable run history does not show a terminal result for that run. Offline CLI audit does not treat its own empty in-process automations runtime state as authority.
|
||||
- CLI tasks: tasks with a run id/source id use the live run context, so lingering child-session or chat-session rows do not keep them alive after the gateway-owned run disappears. Legacy CLI tasks without run identity still fall back to the child session. Gateway-backed `openclaw agent` runs also finalize from their run result, so completed runs do not sit active until the sweeper marks them `lost`.
|
||||
|
||||
## Delivery and notifications
|
||||
@@ -168,11 +168,11 @@ That means the usual workflow is push-based: start detached work once, then let
|
||||
|
||||
Control how much you hear about each task:
|
||||
|
||||
| Policy | What is delivered |
|
||||
| --------------------- | ------------------------------------------------------- |
|
||||
| `done_only` (default) | Only terminal state (succeeded, failed, etc.) |
|
||||
| `state_changes` | Every state transition and progress update |
|
||||
| `silent` | Nothing at all (default for cron, CLI, and media tasks) |
|
||||
| Policy | What is delivered |
|
||||
| --------------------- | ------------------------------------------------------------- |
|
||||
| `done_only` (default) | Only terminal state (succeeded, failed, etc.) |
|
||||
| `state_changes` | Every state transition and progress update |
|
||||
| `silent` | Nothing at all (default for automation, CLI, and media tasks) |
|
||||
|
||||
Change the policy while a task is running:
|
||||
|
||||
@@ -204,7 +204,7 @@ openclaw tasks notify <lookup> state_changes
|
||||
openclaw tasks cancel <lookup>
|
||||
```
|
||||
|
||||
For ACP and subagent tasks, this kills the child session; ACP and cron cancellations route through the running Gateway (`tasks.cancel`). For CLI-tracked tasks, cancellation is recorded in the task registry (there is no separate child runtime handle). Status transitions to `cancelled` and a delivery notification is sent when applicable.
|
||||
For ACP and subagent tasks, this kills the child session; ACP and automation cancellations route through the running Gateway (`tasks.cancel`). For CLI-tracked tasks, cancellation is recorded in the task registry (there is no separate child runtime handle). Status transitions to `cancelled` and a delivery notification is sent when applicable.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="tasks notify">
|
||||
@@ -249,24 +249,24 @@ openclaw tasks notify <lookup> state_changes
|
||||
openclaw tasks maintenance --apply [--json]
|
||||
```
|
||||
|
||||
Use this to preview or apply reconciliation, cleanup stamping, and pruning for tasks, TaskFlow state, and stale cron run session registry rows.
|
||||
Use this to preview or apply reconciliation, cleanup stamping, and pruning for tasks, TaskFlow state, and stale automation run session registry rows.
|
||||
|
||||
Reconciliation is runtime-aware:
|
||||
|
||||
- ACP tasks require a live in-process turn in the Gateway; subagent tasks check their backing child session.
|
||||
- Subagent tasks whose child session has a restart-recovery tombstone are marked lost instead of being treated as recoverable backing sessions.
|
||||
- Cron tasks check whether the cron runtime still owns the job, then recover terminal status from persisted cron run logs/job state before falling back to `lost`. Only the Gateway process is authoritative for the in-memory cron active-job set; offline CLI audit uses durable history but does not mark a cron task lost solely because that local set is empty.
|
||||
- Automation tasks check whether the automations runtime still owns the job, then recover terminal status from persisted run logs/job state before falling back to `lost`. Only the Gateway process is authoritative for the in-memory active-job set; offline CLI audit uses durable history but does not mark an automation task lost solely because that local set is empty.
|
||||
- CLI tasks with run identity check the owning live run context, not just child-session or chat-session rows.
|
||||
|
||||
Completion cleanup is also runtime-aware:
|
||||
|
||||
- Subagent completion best-effort closes tracked browser tabs/processes for the child session before announce cleanup continues.
|
||||
- Isolated cron completion best-effort closes tracked browser tabs/processes for the cron session before the run fully tears down.
|
||||
- Isolated cron delivery waits out descendant subagent follow-up when needed and suppresses stale parent acknowledgement text instead of announcing it.
|
||||
- Isolated automation completion best-effort closes tracked browser tabs/processes for the run's session before the run fully tears down.
|
||||
- Isolated automation delivery waits out descendant subagent follow-up when needed and suppresses stale parent acknowledgement text instead of announcing it.
|
||||
- Subagent completion delivery uses the child's latest visible assistant text only. Tool/toolResult output is not promoted into child result text. Terminal failed runs announce failure status without replaying captured reply text.
|
||||
- Cleanup failures do not mask the real task outcome.
|
||||
|
||||
When applying maintenance, OpenClaw also removes stale `cron:<jobId>:run:<runId>` session registry rows older than 7 days, while preserving rows for currently running cron jobs and leaving non-cron session rows untouched.
|
||||
When applying maintenance, OpenClaw also removes stale `cron:<jobId>:run:<runId>` session registry rows older than 7 days, while preserving rows for currently running automation jobs and leaving other session rows untouched.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="tasks flow list | show | cancel">
|
||||
@@ -331,7 +331,7 @@ A sweeper runs every **60 seconds** (first pass about 5 seconds after gateway st
|
||||
|
||||
<Steps>
|
||||
<Step title="Reconciliation">
|
||||
Checks whether active tasks still have authoritative runtime backing. ACP tasks require a live in-process turn, subagent tasks use child-session state, cron tasks use active-job ownership plus durable run history, and CLI tasks with run identity use the owning run context. If backing state is gone for more than 5 minutes (30 minutes for childless native subagent tasks), the task is marked `lost`.
|
||||
Checks whether active tasks still have authoritative runtime backing. ACP tasks require a live in-process turn, subagent tasks use child-session state, automation tasks use active-job ownership plus durable run history, and CLI tasks with run identity use the owning run context. If backing state is gone for more than 5 minutes (30 minutes for childless native subagent tasks), the task is marked `lost`.
|
||||
</Step>
|
||||
<Step title="ACP session repair">
|
||||
Closes terminal or orphaned parent-owned one-shot ACP sessions, and closes stale terminal or orphaned persistent ACP sessions only when no active conversation binding remains.
|
||||
@@ -355,10 +355,10 @@ A sweeper runs every **60 seconds** (first pass about 5 seconds after gateway st
|
||||
[Task Flow](/automation/taskflow) is the flow orchestration layer above background tasks. A single flow may coordinate multiple tasks over its lifetime using managed or mirrored sync modes. Use `openclaw tasks` to inspect individual task records and `openclaw tasks flow` to inspect the orchestrating flow.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Tasks and cron">
|
||||
Cron job definitions, runtime execution state, and run history live in OpenClaw's shared SQLite state database. **Every** cron execution creates a task record - both main-session and isolated - with `silent` notify policy, so cron runs are tracked without generating task notifications of their own.
|
||||
<Accordion title="Tasks and automations">
|
||||
Automation job definitions, runtime execution state, and run history live in OpenClaw's shared SQLite state database. **Every** automation run creates a task record - both main-session and isolated - with `silent` notify policy, so automation runs are tracked without generating task notifications of their own.
|
||||
|
||||
See [Cron Jobs](/automation/cron-jobs).
|
||||
See [Automations](/automation/cron-jobs).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Tasks and heartbeat">
|
||||
@@ -380,5 +380,5 @@ A sweeper runs every **60 seconds** (first pass about 5 seconds after gateway st
|
||||
- [Automation](/automation) - all automation mechanisms at a glance
|
||||
- [CLI: Tasks](/cli/tasks) - CLI command reference
|
||||
- [Heartbeat](/gateway/heartbeat) - periodic main-session turns
|
||||
- [Scheduled Tasks](/automation/cron-jobs) - scheduling background work
|
||||
- [Automations](/automation/cron-jobs) - scheduling background work
|
||||
- [Task Flow](/automation/taskflow) - flow orchestration above tasks
|
||||
|
||||
+84
-84
@@ -1,29 +1,29 @@
|
||||
---
|
||||
summary: "CLI reference for `openclaw cron` (schedule and run background jobs)"
|
||||
summary: "CLI reference for `openclaw automations` (schedule and run background jobs)"
|
||||
read_when:
|
||||
- You want scheduled jobs and wakeups
|
||||
- You are debugging cron execution and logs
|
||||
title: "Cron"
|
||||
- You are debugging automation execution and logs
|
||||
title: "Automations (cron)"
|
||||
---
|
||||
|
||||
# `openclaw cron`
|
||||
# `openclaw automations`
|
||||
|
||||
Manage cron jobs for the Gateway scheduler.
|
||||
Manage automation jobs for the Gateway scheduler. `openclaw automations` is the primary command; `openclaw cron` remains an alias, and every subcommand below works with either spelling.
|
||||
|
||||
<Tip>
|
||||
Run `openclaw cron --help` for the full command surface. See [Cron jobs](/automation/cron-jobs) for the conceptual guide.
|
||||
Run `openclaw automations --help` for the full command surface. See [Automations](/automation/cron-jobs) for the conceptual guide.
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
All cron mutations (`add`/`create`, `update`/`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.
|
||||
All automation mutations (`add`/`create`, `update`/`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.
|
||||
</Note>
|
||||
|
||||
## Create jobs quickly
|
||||
|
||||
`openclaw cron create` is an alias for `openclaw cron add`. For new jobs, put the schedule first and the prompt second:
|
||||
`openclaw automations create` is an alias for `openclaw automations add`. For new jobs, put the schedule first and the prompt second:
|
||||
|
||||
```bash
|
||||
openclaw cron create "0 7 * * *" \
|
||||
openclaw automations create "0 7 * * *" \
|
||||
"Summarize overnight updates." \
|
||||
--name "Morning brief" \
|
||||
--agent ops
|
||||
@@ -32,16 +32,16 @@ openclaw cron create "0 7 * * *" \
|
||||
Use `--webhook <url>` when the job should POST the finished payload instead of delivering to a chat target:
|
||||
|
||||
```bash
|
||||
openclaw cron create "0 18 * * 1-5" \
|
||||
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 OpenClaw cron without starting an isolated agent/model run:
|
||||
Use `--command` for deterministic shell-style jobs that run inside the OpenClaw scheduler without starting an isolated agent/model run:
|
||||
|
||||
```bash
|
||||
openclaw cron create "*/15 * * * *" \
|
||||
openclaw automations create "*/15 * * * *" \
|
||||
--name "Queue depth probe" \
|
||||
--command "scripts/check-queue.sh" \
|
||||
--command-cwd "/srv/app" \
|
||||
@@ -50,7 +50,7 @@ openclaw cron create "*/15 * * * *" \
|
||||
--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 cron 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.
|
||||
`--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.
|
||||
|
||||
## Sessions
|
||||
|
||||
@@ -73,26 +73,26 @@ Agent-turn jobs default to the creating conversation when session context is ava
|
||||
|
||||
## Delivery
|
||||
|
||||
`openclaw cron list` and `openclaw cron show <job-id>` 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.
|
||||
`openclaw automations list` and `openclaw automations show <job-id>` 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.
|
||||
|
||||
<Note>
|
||||
Isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep output internal. `--deliver` remains as a deprecated alias for `--announce`.
|
||||
Isolated `automations add` jobs default to `--announce` delivery. Use `--no-deliver` to keep output internal. `--deliver` remains as a deprecated alias for `--announce`.
|
||||
</Note>
|
||||
|
||||
### Delivery ownership
|
||||
|
||||
Isolated cron chat delivery is shared between the agent and the runner:
|
||||
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 `cron add|create --webhook <url>` or `cron 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`.
|
||||
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`.
|
||||
|
||||
`cron 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 only disables runner fallback delivery, these remove the stored field so the job resolves that part of its route from defaults again.
|
||||
`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 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.
|
||||
|
||||
@@ -112,11 +112,11 @@ Main-session jobs may only use `delivery.failureDestination` when primary delive
|
||||
|
||||
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 cron runs treat run-level agent failures as job errors even when no reply payload is produced, so model/provider failures still increment error counters and trigger failure notifications.
|
||||
Isolated automation runs treat run-level agent failures as job errors even when no reply payload is produced, so model/provider failures still increment error counters and trigger failure notifications.
|
||||
|
||||
Command cron 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.
|
||||
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.
|
||||
|
||||
If an isolated run times out before the first model request, `openclaw cron show` and `openclaw cron runs` include a phase-specific error such as `setup timed out before runner start` or a stall message naming the last-known startup phase (for example `context-engine`). For CLI-backed providers, the pre-model watchdog stays active until the external CLI turn starts, so session lookup, hook, auth, prompt, and CLI setup stalls are reported as pre-model cron failures.
|
||||
If an isolated run times out before the first model request, `openclaw automations show` and `openclaw automations runs` include a phase-specific error such as `setup timed out before runner start` or a stall message naming the last-known startup phase (for example `context-engine`). For CLI-backed providers, the pre-model watchdog stays active until the external CLI turn starts, so session lookup, hook, auth, prompt, and CLI setup stalls are reported as pre-model automation failures.
|
||||
|
||||
## Scheduling
|
||||
|
||||
@@ -132,25 +132,25 @@ One-shot jobs delete after success by default. Use `--keep-after-run` to preserv
|
||||
|
||||
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 cron edit <job-id> --failure-alert-include-skipped` can opt failure alerts into repeated skipped-run notifications.
|
||||
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.
|
||||
|
||||
For isolated jobs that target a local configured model provider (base URL on loopback, a private network, or `.local`), cron runs a lightweight provider preflight before starting the agent turn: `api: "ollama"` providers are probed at `/api/tags`; other local OpenAI-compatible providers (`api: "openai-completions"`, e.g. vLLM, SGLang, LM Studio) are probed at `/models`. If the endpoint is unreachable, the run is recorded as `skipped` and retried on a later schedule; the reachability result is cached per endpoint for 5 minutes so many jobs against the same local server do not hammer it with repeated probes.
|
||||
For isolated jobs that target a local configured model provider (base URL on loopback, a private network, or `.local`), the scheduler runs a lightweight provider preflight before starting the agent turn: `api: "ollama"` providers are probed at `/api/tags`; other local OpenAI-compatible providers (`api: "openai-completions"`, e.g. vLLM, SGLang, LM Studio) are probed at `/models`. If the endpoint is unreachable, the run is recorded as `skipped` and retried on a later schedule; the reachability result is cached per endpoint for 5 minutes so many jobs against the same local server do not hammer it with repeated probes.
|
||||
|
||||
Cron jobs, pending runtime state, and run history live in the shared SQLite state database. Legacy `jobs.json`, `<name>-state.json`, and `runs/*.jsonl` files are imported once and renamed with a `.migrated` suffix. After import, edit schedules with `openclaw cron add|edit|remove` instead of editing JSON files.
|
||||
Automation jobs, pending runtime state, and run history live in the shared SQLite state database. Legacy `jobs.json`, `<name>-state.json`, and `runs/*.jsonl` files are imported once and renamed with a `.migrated` suffix. After import, edit schedules with `openclaw automations add|edit|remove` instead of editing JSON files.
|
||||
|
||||
### Manual runs
|
||||
|
||||
`openclaw cron run <job-id>` 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:
|
||||
`openclaw automations run <job-id>` 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 cron run <job-id>
|
||||
openclaw cron runs --id <job-id> --run-id <run-id>
|
||||
openclaw automations run <job-id>
|
||||
openclaw automations runs --id <job-id> --run-id <run-id>
|
||||
```
|
||||
|
||||
Add `--wait` when a script should block until that exact queued run records a terminal status:
|
||||
|
||||
```bash
|
||||
openclaw cron run <job-id> --wait --wait-timeout 10m --poll-interval 2s
|
||||
openclaw automations run <job-id> --wait --wait-timeout 10m --poll-interval 2s
|
||||
```
|
||||
|
||||
With `--wait`, the CLI still calls `cron.run` first, then polls `cron.runs` for the returned `runId`. The command exits `0` only when the run finishes with status `ok`. It exits non-zero when the run finishes with `error` or `skipped`, when the Gateway response does not include a `runId`, or when `--wait-timeout` expires (default `10m`, polled every `2s` by default). `--poll-interval` must be greater than zero.
|
||||
@@ -161,68 +161,68 @@ Use `--due` when you want the manual command to run only if the job is currently
|
||||
|
||||
## Models
|
||||
|
||||
`cron add|edit --model <ref>` selects an allowed model for the job. `cron 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. `cron edit <job-id> --clear-fallbacks` removes the per-job fallback override. `cron edit <job-id> --clear-model` removes the per-job model override so the job follows normal cron model-selection precedence (a stored cron-session override if present, otherwise the agent/default model); it cannot be combined with `--model`. `cron add|edit --thinking <level>` sets a per-job thinking override; `cron edit <job-id> --clear-thinking` removes it so the job follows normal cron thinking precedence, and it cannot be combined with `--thinking`.
|
||||
`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 so the job follows normal automation model-selection precedence (a stored automation-session override if present, otherwise the agent/default model); it cannot be combined 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, and it cannot be combined with `--thinking`.
|
||||
|
||||
<Warning>
|
||||
If the model is not allowed or cannot be resolved, cron fails the run with an explicit validation error instead of falling back to the job's agent or default model selection.
|
||||
If the model is not allowed or cannot be resolved, the scheduler fails the run with an explicit validation error instead of falling back to the job's agent or default model selection.
|
||||
</Warning>
|
||||
|
||||
Cron `--model` is a **job primary**, not a chat-session `/model` override. That means:
|
||||
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 cron run strict.
|
||||
- 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 so the agent primary is not appended as a hidden retry target.
|
||||
- Local-provider preflight checks walk configured fallbacks before marking a cron run `skipped`.
|
||||
- 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 cron model precedence
|
||||
### Isolated automation model precedence
|
||||
|
||||
Isolated cron resolves the active model in this order:
|
||||
Isolated automation runs resolve the active model in this order:
|
||||
|
||||
1. Gmail-hook override.
|
||||
2. Per-job `--model`.
|
||||
3. Stored cron-session model override (when the user selected one).
|
||||
3. Stored automation-session model override (when the user selected one).
|
||||
4. Agent or default model selection.
|
||||
|
||||
### Fast mode
|
||||
|
||||
Isolated cron fast mode follows the resolved live model selection. Model config `params.fastMode` applies by default, but a stored session `fastMode` override still wins over config. When the resolved mode is `auto`, the cutoff uses the selected model's `params.fastAutoOnSeconds` value, defaulting to 60 seconds.
|
||||
Isolated automation fast mode follows the resolved live model selection. Model config `params.fastMode` applies by default, but a stored session `fastMode` override still wins over config. 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`, cron persists the switched provider and model (and switched auth profile override when present) for the active run before retrying. The outer retry loop is bounded to two switch retries after the initial attempt, then aborts instead of looping forever.
|
||||
If an isolated run throws `LiveSessionModelSwitchError`, the scheduler persists the switched provider and model (and switched auth profile override when present) for the active run before retrying. 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 cron turns suppress stale acknowledgement-only replies. If the first result is just an interim status update and no descendant subagent run is responsible for the eventual answer, cron re-prompts once for the real result before delivery.
|
||||
Isolated automation turns suppress stale acknowledgement-only replies. If the first result is just an interim status update and no descendant subagent run is responsible for the eventual answer, the scheduler re-prompts once for the real result before delivery.
|
||||
|
||||
### Silent token suppression
|
||||
|
||||
If an isolated cron run returns only the silent token (`NO_REPLY` or `no_reply`), cron suppresses both direct outbound delivery and the fallback queued summary path, so nothing is posted back to chat.
|
||||
If an isolated automation run returns only the silent token (`NO_REPLY` or `no_reply`), the scheduler suppresses both direct outbound delivery and the fallback queued summary path, so nothing is posted back to chat.
|
||||
|
||||
### Structured denials
|
||||
|
||||
Isolated cron 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.
|
||||
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.
|
||||
|
||||
Cron does not classify final-output prose or approval-looking refusal phrases as denials unless the embedded run also provides structured denial metadata, so ordinary assistant text is not treated as a blocked command.
|
||||
The scheduler does not classify final-output prose or approval-looking refusal phrases as denials unless the embedded run also provides structured denial metadata, so ordinary assistant text is not treated as a blocked command.
|
||||
|
||||
`cron list` and run history surface the denial reason instead of reporting a blocked command as `ok`.
|
||||
`automations list` and run history surface the denial reason instead of reporting a blocked command as `ok`.
|
||||
|
||||
## Retention
|
||||
|
||||
Retention behavior:
|
||||
|
||||
- `cron.sessionRetention` (default `24h`, or `false` to disable) prunes completed isolated run sessions.
|
||||
- Run history keeps the newest 2000 terminal rows per cron job. Lost rows retain the standard 24-hour lost-task cleanup window.
|
||||
- Run history keeps the newest 2000 terminal rows per job. Lost rows retain the standard 24-hour lost-task cleanup window.
|
||||
|
||||
## Migrating older jobs
|
||||
|
||||
<Note>
|
||||
If you have cron jobs from before the current delivery and store format, run `openclaw doctor --fix`. Doctor normalizes legacy cron fields (`jobId`, `schedule.cron`, top-level delivery fields including legacy `threadId`, payload `provider` delivery aliases) and migrates `notify: true` webhook fallback jobs from the retired raw `cron.webhook` value to explicit webhook delivery before removing that config key. Jobs that already announce to a chat keep that delivery and get a completion webhook destination. Without a legacy webhook, the inert top-level `notify` marker is removed for jobs with no migration target (the existing delivery is preserved unchanged), so `doctor --fix` no longer keeps re-warning about them.
|
||||
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`, payload `provider` delivery aliases) and migrates `notify: true` webhook fallback jobs from the retired raw `cron.webhook` value to explicit webhook delivery before removing that config key. Jobs that already announce to a chat keep that delivery and get a completion webhook destination. Without a legacy webhook, the inert top-level `notify` marker is removed for jobs with no migration target (the existing delivery is preserved unchanged), so `doctor --fix` no longer keeps re-warning about them.
|
||||
</Note>
|
||||
|
||||
## Common edits
|
||||
@@ -230,37 +230,37 @@ If you have cron jobs from before the current delivery and store format, run `op
|
||||
Update delivery settings without changing the message:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --announce --channel telegram --to "123456789"
|
||||
openclaw automations edit <job-id> --announce --channel telegram --to "123456789"
|
||||
```
|
||||
|
||||
Disable delivery for an isolated job:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --no-deliver
|
||||
openclaw automations edit <job-id> --no-deliver
|
||||
```
|
||||
|
||||
Enable lightweight bootstrap context for an isolated job:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --light-context
|
||||
openclaw automations edit <job-id> --light-context
|
||||
```
|
||||
|
||||
Announce to a specific channel:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
|
||||
openclaw automations edit <job-id> --announce --channel slack --to "channel:C1234567890"
|
||||
```
|
||||
|
||||
Announce to a Telegram forum topic:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42
|
||||
openclaw automations edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42
|
||||
```
|
||||
|
||||
Create an isolated job with lightweight bootstrap context:
|
||||
|
||||
```bash
|
||||
openclaw cron create "0 7 * * *" \
|
||||
openclaw automations create "0 7 * * *" \
|
||||
"Summarize overnight updates." \
|
||||
--name "Lightweight morning brief" \
|
||||
--session isolated \
|
||||
@@ -268,12 +268,12 @@ openclaw cron create "0 7 * * *" \
|
||||
--no-deliver
|
||||
```
|
||||
|
||||
`--light-context` applies to isolated agent-turn jobs only. For cron runs, lightweight mode keeps bootstrap context empty instead of injecting the full workspace bootstrap set.
|
||||
`--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 cron create "*/30 * * * *" \
|
||||
openclaw automations create "*/30 * * * *" \
|
||||
--name "Position export" \
|
||||
--command-argv '["node","scripts/export-position.mjs"]' \
|
||||
--command-cwd "/srv/app" \
|
||||
@@ -290,60 +290,60 @@ openclaw cron create "*/30 * * * *" \
|
||||
Manual run and inspection:
|
||||
|
||||
```bash
|
||||
openclaw cron list
|
||||
openclaw cron list --agent ops
|
||||
openclaw cron get <job-id>
|
||||
openclaw cron show <job-id>
|
||||
openclaw cron run <job-id>
|
||||
openclaw cron run <job-id> --due
|
||||
openclaw cron run <job-id> --wait --wait-timeout 10m
|
||||
openclaw cron run <job-id> --wait --wait-timeout 10m --poll-interval 2s
|
||||
openclaw cron runs --id <job-id> --limit 50
|
||||
openclaw cron runs --id <job-id> --run-id <run-id>
|
||||
openclaw automations list
|
||||
openclaw automations list --agent ops
|
||||
openclaw automations get <job-id>
|
||||
openclaw automations show <job-id>
|
||||
openclaw automations run <job-id>
|
||||
openclaw automations run <job-id> --due
|
||||
openclaw automations run <job-id> --wait --wait-timeout 10m
|
||||
openclaw automations run <job-id> --wait --wait-timeout 10m --poll-interval 2s
|
||||
openclaw automations runs --id <job-id> --limit 50
|
||||
openclaw automations runs --id <job-id> --run-id <run-id>
|
||||
```
|
||||
|
||||
`openclaw cron list` shows enabled jobs by default. Pass `--all` to include disabled jobs, or `--agent <id>` to show only jobs whose effective normalized agent id matches; jobs without a stored agent id count as the configured default agent.
|
||||
`openclaw automations list` shows enabled jobs by default. Pass `--all` to include disabled jobs, or `--agent <id>` to show only jobs whose effective normalized agent id matches; jobs without a stored agent id count as the configured default agent.
|
||||
|
||||
`openclaw cron get <job-id>` returns the stored job JSON directly. Use `cron show <job-id>` when you want the human-readable view with delivery-route preview.
|
||||
`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.
|
||||
|
||||
`cron list --json` and `cron 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 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 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 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.
|
||||
|
||||
`cron runs` entries include delivery diagnostics with the intended cron target, the resolved target, message-tool sends, fallback use, and delivered state.
|
||||
`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 cron scratch <job-id> # print current scratch content
|
||||
openclaw cron scratch <job-id> --json # scratch plus revision metadata
|
||||
openclaw cron scratch <job-id> --set "text" # replace scratch with exact text
|
||||
openclaw cron scratch <job-id> --file notes.md # replace scratch from a file (- for stdin)
|
||||
openclaw cron scratch <job-id> --unset # remove the scratch row
|
||||
openclaw automations scratch <job-id> # print current scratch content
|
||||
openclaw automations scratch <job-id> --json # scratch plus revision metadata
|
||||
openclaw automations scratch <job-id> --set "text" # replace scratch with exact text
|
||||
openclaw 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 `cron list`/`cron get`/`cron 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. See [Heartbeat](/gateway/heartbeat#monitor-scratch-optional) for how heartbeat monitors use scratch.
|
||||
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. See [Heartbeat](/gateway/heartbeat#monitor-scratch-optional) for how heartbeat monitors use scratch.
|
||||
|
||||
Agent and session retargeting:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --agent ops
|
||||
openclaw cron edit <job-id> --clear-agent
|
||||
openclaw cron edit <job-id> --session current
|
||||
openclaw cron edit <job-id> --session "session:daily-brief"
|
||||
openclaw automations edit <job-id> --agent ops
|
||||
openclaw automations edit <job-id> --clear-agent
|
||||
openclaw automations edit <job-id> --session current
|
||||
openclaw automations edit <job-id> --session "session:daily-brief"
|
||||
```
|
||||
|
||||
`openclaw cron 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.
|
||||
`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:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
|
||||
openclaw cron edit <job-id> --webhook "https://example.invalid/openclaw/cron"
|
||||
openclaw cron edit <job-id> --best-effort-deliver
|
||||
openclaw cron edit <job-id> --no-best-effort-deliver
|
||||
openclaw cron edit <job-id> --no-deliver
|
||||
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-deliver
|
||||
openclaw automations edit <job-id> --no-best-effort-deliver
|
||||
openclaw automations edit <job-id> --no-deliver
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- [CLI reference](/cli)
|
||||
- [Scheduled tasks](/automation/cron-jobs)
|
||||
- [Automations](/automation/cron-jobs)
|
||||
|
||||
+8
-8
@@ -64,7 +64,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
|
||||
- Route: /automation/cron-jobs
|
||||
- Headings:
|
||||
- H2: Quick start
|
||||
- H2: How cron works
|
||||
- H2: How automations work
|
||||
- H2: Schedule types
|
||||
- H3: Heartbeat task migration
|
||||
- H3: Stream sources
|
||||
@@ -144,9 +144,9 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
|
||||
- Route: /automation
|
||||
- Headings:
|
||||
- H2: Quick decision guide
|
||||
- H3: Scheduled Tasks (Cron) vs Heartbeat
|
||||
- H3: Automations vs Heartbeat
|
||||
- H2: Core concepts
|
||||
- H3: Scheduled tasks (cron)
|
||||
- H3: Automations
|
||||
- H3: Tasks
|
||||
- H3: Task Flow
|
||||
- H3: Standing orders
|
||||
@@ -168,7 +168,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
|
||||
- H2: Why standing orders
|
||||
- H2: How they work
|
||||
- H2: Anatomy of a standing order
|
||||
- H2: Standing orders plus cron jobs
|
||||
- H2: Standing orders plus automations
|
||||
- H2: Examples
|
||||
- H3: Example 1: content and social media (weekly cycle)
|
||||
- H3: Example 2: finance operations (event-triggered)
|
||||
@@ -1476,7 +1476,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
|
||||
|
||||
- Route: /cli/cron
|
||||
- Headings:
|
||||
- H1: openclaw cron
|
||||
- H1: openclaw automations
|
||||
- H2: Create jobs quickly
|
||||
- H2: Sessions
|
||||
- H2: Delivery
|
||||
@@ -1487,7 +1487,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
|
||||
- H3: Recurring jobs
|
||||
- H3: Manual runs
|
||||
- H2: Models
|
||||
- H3: Isolated cron model precedence
|
||||
- H3: Isolated automation model precedence
|
||||
- H3: Fast mode
|
||||
- H3: Live model switch retries
|
||||
- H2: Run output and denials
|
||||
@@ -3561,7 +3561,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
|
||||
- H2: Wizard
|
||||
- H2: Identity
|
||||
- H2: Bridge (legacy, removed)
|
||||
- H2: Cron
|
||||
- H2: Automations (cron)
|
||||
- H3: cron.failureAlert
|
||||
- H2: Media model template variables
|
||||
- H2: Config includes ($include)
|
||||
@@ -3694,7 +3694,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
|
||||
- H3: Per-channel vs per-account examples
|
||||
- H3: Common patterns
|
||||
- H2: Monitor scratch (optional)
|
||||
- H3: Schedule recurring checks with cron
|
||||
- H3: Schedule recurring checks with automations
|
||||
- H3: Can the agent update its scratch?
|
||||
- H2: Manual wake (on-demand)
|
||||
- H2: Cost awareness
|
||||
|
||||
@@ -1447,7 +1447,7 @@ Current builds no longer include the TCP bridge. Nodes connect over the Gateway
|
||||
|
||||
---
|
||||
|
||||
## Cron
|
||||
## Automations (`cron`)
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -1462,11 +1462,11 @@ Current builds no longer include the TCP bridge. Nodes connect over the Gateway
|
||||
}
|
||||
```
|
||||
|
||||
- `enabled`: execute stored cron jobs (default: `true`). Set `false` to pause all cron execution without deleting jobs.
|
||||
- `triggers.enabled`: also run event-driven cron triggers (default: `false`).
|
||||
- `sessionRetention`: how long to keep completed isolated cron run sessions before pruning SQLite session rows. Also controls cleanup of archived deleted cron transcripts. Default: `24h`; set `false` to disable.
|
||||
- `enabled`: execute stored automation jobs (default: `true`). Set `false` to pause all automation execution without deleting jobs.
|
||||
- `triggers.enabled`: also run event-driven automation triggers (default: `false`).
|
||||
- `sessionRetention`: how long to keep completed isolated automation run sessions before pruning SQLite session rows. Also controls cleanup of archived deleted automation transcripts. Default: `24h`; set `false` to disable.
|
||||
- Run history automatically keeps the newest 2000 terminal rows per job. Lost rows retain their 24-hour cleanup window.
|
||||
- `webhookToken`: bearer token used for cron webhook POST delivery (`delivery.mode = "webhook"`), if omitted no auth header is sent.
|
||||
- `webhookToken`: bearer token used for automation webhook POST delivery (`delivery.mode = "webhook"`), if omitted no auth header is sent.
|
||||
|
||||
The `cron` block is strict; `cron.enabled`, `cron.triggers`, `cron.webhookToken`,
|
||||
`cron.sessionRetention`, and `cron.failureAlert` are the only accepted keys. The
|
||||
@@ -1498,7 +1498,7 @@ when preserving announce delivery. `openclaw doctor --fix` strips a leftover
|
||||
destination for every job. The retired `cron.failureDestination` block is merged
|
||||
into it by [`openclaw doctor --fix`](/cli/doctor).
|
||||
|
||||
- `enabled`: enable failure alerts for cron jobs (default: `false`).
|
||||
- `enabled`: enable failure alerts for automation jobs (default: `false`).
|
||||
- `after`: consecutive failures before an alert fires (positive integer, min: `1`; default: `2`).
|
||||
- `cooldownMs`: minimum milliseconds between repeated alerts for the same job (non-negative integer; default: `3600000`).
|
||||
- `includeSkipped`: count consecutive skipped runs toward the alert threshold (default: `false`). Skipped runs are tracked separately and do not affect execution-error backoff.
|
||||
@@ -1510,7 +1510,7 @@ into it by [`openclaw doctor --fix`](/cli/doctor).
|
||||
- When neither global nor per-job failure destination is set, jobs that already deliver via `announce` fall back to that primary announce target on failure.
|
||||
- `delivery.failureDestination` is only supported for `sessionTarget="isolated"` jobs unless the job's primary `delivery.mode` is `"webhook"`.
|
||||
|
||||
See [Cron Jobs](/automation/cron-jobs). Isolated cron executions are tracked as [background tasks](/automation/tasks).
|
||||
See [Automations](/automation/cron-jobs). Isolated automation runs are tracked as [background tasks](/automation/tasks).
|
||||
|
||||
## Media model template variables
|
||||
|
||||
|
||||
+24
-24
@@ -2,24 +2,24 @@
|
||||
summary: "Heartbeat polling messages and notification rules"
|
||||
read_when:
|
||||
- Adjusting heartbeat cadence or messaging
|
||||
- Deciding between heartbeat and cron for scheduled tasks
|
||||
- Deciding between heartbeat and automations for scheduled work
|
||||
title: "Heartbeat"
|
||||
sidebarTitle: "Heartbeat"
|
||||
---
|
||||
|
||||
<Note>
|
||||
**Heartbeat vs cron?** See [Automation](/automation) for guidance on when to use each.
|
||||
**Heartbeat vs automations?** See [Automation](/automation) for guidance on when to use each.
|
||||
</Note>
|
||||
|
||||
Heartbeat runs **periodic agent turns** in the main session so the model can surface anything that needs attention without spamming you.
|
||||
|
||||
Heartbeat is a scheduled main-session turn - it does **not** create [background task](/automation/tasks) records. Task records are for detached work (ACP runs, subagents, isolated cron jobs).
|
||||
Heartbeat is a scheduled main-session turn - it does **not** create [background task](/automation/tasks) records. Task records are for detached work (ACP runs, subagents, isolated automation jobs).
|
||||
|
||||
Under the hood, heartbeat cadence is owned by the cron scheduler: the gateway maintains one system-owned cron job per heartbeat-enabled agent (visible in `openclaw cron list --all` as `Heartbeat (agent-id)`). Heartbeat config remains the desired-state input, while the persisted monitor schedule owns the actual tick and the runner's later cooldown. The gateway writes config changes through at startup and on config reload; `openclaw doctor --fix` can materialize missing or stale monitor rows before the next gateway start. Edit `agents.*.heartbeat`, not the cron job.
|
||||
Under the hood, heartbeat cadence is owned by the Automations scheduler: the gateway maintains one system-owned automation job per heartbeat-enabled agent (visible in `openclaw cron list --all` as `Heartbeat (agent-id)`). Heartbeat config remains the desired-state input, while the persisted monitor schedule owns the actual tick and the runner's later cooldown. The gateway writes config changes through at startup and on config reload; `openclaw doctor --fix` can materialize missing or stale monitor rows before the next gateway start. Edit `agents.*.heartbeat`, not the automation job.
|
||||
|
||||
Scheduled heartbeats require cron. When `cron.enabled` is `false` or `OPENCLAW_SKIP_CRON=1`, the gateway logs a startup warning and does not run scheduled heartbeats; manual and event-driven heartbeat wakes remain available. There is no separate heartbeat fallback timer.
|
||||
Scheduled heartbeats require automations. When `cron.enabled` is `false` or `OPENCLAW_SKIP_CRON=1`, the gateway logs a startup warning and does not run scheduled heartbeats; manual and event-driven heartbeat wakes remain available. There is no separate heartbeat fallback timer.
|
||||
|
||||
Troubleshooting: [Scheduled Tasks](/automation/cron-jobs#troubleshooting)
|
||||
Troubleshooting: [Automations](/automation/cron-jobs#troubleshooting)
|
||||
|
||||
## Quick start (beginner)
|
||||
|
||||
@@ -63,25 +63,25 @@ Example config:
|
||||
## Defaults
|
||||
|
||||
- Interval: `30m`. Applying Anthropic provider defaults bumps this to `1h` when the resolved auth mode is OAuth/token (including Claude CLI reuse), but only while `heartbeat.every` is unset. Set `agents.defaults.heartbeat.every` or per-agent `agents.entries.*.heartbeat.every`; use `0m` to disable.
|
||||
- Prompt body (configurable via `agents.defaults.heartbeat.prompt`): `Follow the heartbeat monitor scratch context when provided. Recurring tasks are cron jobs; create or change their schedules with cron tools or the openclaw cron CLI, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
|
||||
- Prompt body (configurable via `agents.defaults.heartbeat.prompt`): `Follow the heartbeat monitor scratch context when provided. Recurring tasks are automations; create or change their schedules with the automations tool, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
|
||||
- Timeout: unset heartbeat turns use `agents.defaults.timeoutSeconds` when set. Otherwise, they use the heartbeat cadence capped at 600 seconds. Set `agents.defaults.heartbeat.timeoutSeconds` or per-agent `agents.entries.*.heartbeat.timeoutSeconds` for longer heartbeat work.
|
||||
- The heartbeat prompt is sent **verbatim** as the user message. The system prompt automatically includes a "Heartbeats" section when cadence is enabled for the default agent; that guidance has no separate heartbeat toggle.
|
||||
- When heartbeats are disabled with `0m`, the monitor cron job stays but is disabled, and its scratch is retained for when you re-enable the cadence.
|
||||
- When cron itself is disabled, scheduled heartbeats do not run even if heartbeat cadence remains enabled.
|
||||
- When heartbeats are disabled with `0m`, the monitor automation job stays but is disabled, and its scratch is retained for when you re-enable the cadence.
|
||||
- When automations are disabled entirely, scheduled heartbeats do not run even if heartbeat cadence remains enabled.
|
||||
- Active hours (`heartbeat.activeHours`) are checked in the configured timezone. Outside the window, heartbeats are skipped until the next tick inside the window.
|
||||
- Scheduled heartbeats defer while the main queue or cron work is active or queued, while any reply or embedded run for the same agent is active, and while the resolved target session has active or queued work. Immediate and manual wakes bypass the broad same-agent active-run check, but still honor the main, cron, and target-session busy guards. Sibling agents do not pause each other.
|
||||
- Scheduled heartbeats defer while the main queue or automation work is active or queued, while any reply or embedded run for the same agent is active, and while the resolved target session has active or queued work. Immediate and manual wakes bypass the broad same-agent active-run check, but still honor the main, automation, and target-session busy guards. Sibling agents do not pause each other.
|
||||
|
||||
## What the heartbeat prompt is for
|
||||
|
||||
The default prompt is intentionally narrow: follow the heartbeat monitor scratch
|
||||
context when provided, keep recurring work in cron jobs, and reply
|
||||
context when provided, keep recurring work in automation jobs, and reply
|
||||
`HEARTBEAT_OK` when nothing needs attention. It explicitly tells the agent
|
||||
**not** to infer or repeat old tasks from prior chats, so a default install stays
|
||||
quiet instead of rehashing stale conversation context.
|
||||
|
||||
Proactive heartbeat behavior is opt-in:
|
||||
|
||||
- **Recurring checks**: create [scheduled jobs](/automation/cron-jobs) for inbox
|
||||
- **Recurring checks**: create [automations](/automation/cron-jobs) for inbox
|
||||
review, calendar sweeps, or queued follow-ups. Each job executes its configured
|
||||
payload on its own schedule; the default heartbeat does not infer recurring
|
||||
work from prior chats.
|
||||
@@ -121,7 +121,7 @@ Outside heartbeats, stray `HEARTBEAT_OK` at the start/end of a message is stripp
|
||||
target: "last", // default: none | options: last | none | <channel id> (core or plugin, e.g. "imessage")
|
||||
to: "+15551234567", // optional channel-specific override
|
||||
accountId: "ops-bot", // optional multi-account channel id
|
||||
prompt: "Follow the heartbeat monitor scratch context when provided. Recurring tasks are cron jobs; create or change their schedules with cron tools or the openclaw cron CLI, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
|
||||
prompt: "Follow the heartbeat monitor scratch context when provided. Recurring tasks are automations; create or change their schedules with the automations tool, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
|
||||
},
|
||||
},
|
||||
},
|
||||
@@ -160,7 +160,7 @@ Example: two agents, only the second agent runs heartbeats.
|
||||
target: "whatsapp",
|
||||
to: "+15551234567",
|
||||
timeoutSeconds: 45,
|
||||
prompt: "Follow the heartbeat monitor scratch context when provided. Recurring tasks are cron jobs; create or change their schedules with cron tools or the openclaw cron CLI, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
|
||||
prompt: "Follow the heartbeat monitor scratch context when provided. Recurring tasks are automations; create or change their schedules with the automations tool, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
|
||||
},
|
||||
},
|
||||
],
|
||||
@@ -244,7 +244,7 @@ Use `accountId` to target a specific account on multi-account channels like Tele
|
||||
When true, heartbeat runs use lightweight bootstrap context and skip workspace bootstrap files. Monitor scratch is injected by the heartbeat runner either way.
|
||||
</ParamField>
|
||||
<ParamField path="isolatedSession" type="boolean" default="false">
|
||||
When true, each heartbeat runs in a fresh session with no prior conversation history. Uses the same isolation pattern as cron `sessionTarget: "isolated"`. Dramatically reduces per-heartbeat token cost. Combine with `lightContext: true` for maximum savings. Delivery routing still uses the main session context.
|
||||
When true, each heartbeat runs in a fresh session with no prior conversation history. Uses the same isolation pattern as automation jobs with `sessionTarget: "isolated"`. Dramatically reduces per-heartbeat token cost. Combine with `lightContext: true` for maximum savings. Delivery routing still uses the main session context.
|
||||
</ParamField>
|
||||
<ParamField path="session" type="string">
|
||||
Optional session key for heartbeat runs.
|
||||
@@ -303,7 +303,7 @@ Heartbeat configuration is strict: only the fields listed above are accepted. Ac
|
||||
- `session` only affects the run context; delivery is controlled by `target` and `to`.
|
||||
- To deliver to a specific channel/recipient, set `target` + `to`. With `target: "last"`, delivery uses the last external channel for that session.
|
||||
- Heartbeat deliveries allow direct/DM targets by default. Set `directPolicy: "block"` to suppress direct-target sends while still running the heartbeat turn.
|
||||
- Scheduled heartbeats are skipped and retried later when the main queue or cron work is busy, any reply or embedded run for the same agent is active, or the resolved target session has active or queued work. Immediate and manual wakes bypass only the broad same-agent active-run precheck.
|
||||
- Scheduled heartbeats are skipped and retried later when the main queue or automation work is busy, any reply or embedded run for the same agent is active, or the resolved target session has active or queued work. Immediate and manual wakes bypass only the broad same-agent active-run precheck.
|
||||
- If `target` resolves to no external destination, the run still happens but no outbound message is sent.
|
||||
|
||||
</Accordion>
|
||||
@@ -384,9 +384,9 @@ channels:
|
||||
|
||||
## Monitor scratch (optional)
|
||||
|
||||
Each heartbeat monitor cron job owns a private scratch document stored in the shared state database. Think of it as your "heartbeat checklist": small, stable, and safe to consider every 30 minutes. When scratch exists, its content is appended to the heartbeat prompt.
|
||||
Each heartbeat monitor automation job owns a private scratch document stored in the shared state database. Think of it as your "heartbeat checklist": small, stable, and safe to consider every 30 minutes. When scratch exists, its content is appended to the heartbeat prompt.
|
||||
|
||||
Manage it with the cron CLI (the job id comes from `openclaw cron list --all`):
|
||||
Manage it with the automations CLI (the job id comes from `openclaw cron list --all`):
|
||||
|
||||
```bash
|
||||
openclaw cron scratch <jobId> # print the current scratch
|
||||
@@ -400,7 +400,7 @@ Writes are compare-and-swap guarded: pass `--expected-revision <n>` to fail inst
|
||||
The agent can also update its own scratch: during a heartbeat turn, `heartbeat_respond` accepts an optional `scratch` string that fully replaces the monitor's scratch for future heartbeats.
|
||||
|
||||
<Note>
|
||||
**Migrating from HEARTBEAT.md or config-only cadence?** Run `openclaw doctor --fix`. Doctor first creates or updates the system-owned monitor rows from `agents.*.heartbeat`, then imports each agent's workspace `HEARTBEAT.md` into the monitor's scratch, converts any valid legacy `tasks:` entries into cron jobs, archives the original under the state directory (`backups/heartbeat-migration/`), and removes the file. Runtime heartbeat instructions come from database scratch only; the runtime never reads `HEARTBEAT.md`.
|
||||
**Migrating from HEARTBEAT.md or config-only cadence?** Run `openclaw doctor --fix`. Doctor first creates or updates the system-owned monitor rows from `agents.*.heartbeat`, then imports each agent's workspace `HEARTBEAT.md` into the monitor's scratch, converts any valid legacy `tasks:` entries into automation jobs, archives the original under the state directory (`backups/heartbeat-migration/`), and removes the file. Runtime heartbeat instructions come from database scratch only; the runtime never reads `HEARTBEAT.md`.
|
||||
</Note>
|
||||
|
||||
If scratch exists but is effectively empty (only blank lines, Markdown/HTML comments, Markdown headings like `# Heading`, fence markers, or empty checklist stubs), OpenClaw skips the heartbeat run to save API calls. That skip is reported as `reason=empty-heartbeat-file`. If no scratch exists, the heartbeat still runs and the model decides what to do.
|
||||
@@ -417,17 +417,17 @@ Example scratch:
|
||||
- If a task is blocked, write down _what is missing_ and ask Peter next time.
|
||||
```
|
||||
|
||||
### Schedule recurring checks with cron
|
||||
### Schedule recurring checks with automations
|
||||
|
||||
Heartbeat scratch is prompt context, not a scheduler. Create each recurring check as a [cron job](/automation/cron-jobs) so it has its own cadence, enable/disable state, and run history. Cron jobs can still target the main session when the check should use the normal conversation context.
|
||||
Heartbeat scratch is prompt context, not a scheduler. Create each recurring check as an [automation job](/automation/cron-jobs) so it has its own cadence, enable/disable state, and run history. Automation jobs can still target the main session when the check should use the normal conversation context.
|
||||
|
||||
Older scratch may contain a structured `tasks:` block. Run `openclaw doctor --fix` once after upgrading: Doctor converts every valid entry into an independently scheduled cron job, preserves its interval and previous last-run timing, and removes the retired block while keeping surrounding scratch prose. Runtime heartbeat turns do not parse `tasks:` text as schedules.
|
||||
Older scratch may contain a structured `tasks:` block. Run `openclaw doctor --fix` once after upgrading: Doctor converts every valid entry into an independently scheduled automation job, preserves its interval and previous last-run timing, and removes the retired block while keeping surrounding scratch prose. Runtime heartbeat turns do not parse `tasks:` text as schedules.
|
||||
|
||||
Doctor-created heartbeat task jobs keep heartbeat active-hours, cooldown, flood, and busy guards. Jobs due together can coalesce into one heartbeat turn. An occurrence outside active hours is skipped and tried again at its next cron occurrence.
|
||||
Doctor-created heartbeat task jobs keep heartbeat active-hours, cooldown, flood, and busy guards. Jobs due together can coalesce into one heartbeat turn. An occurrence outside active hours is skipped and tried again at its next scheduled occurrence.
|
||||
|
||||
### Can the agent update its scratch?
|
||||
|
||||
Yes. During a heartbeat turn, the agent can pass a `scratch` value to `heartbeat_respond` to fully replace the monitor prose for future heartbeats. You can also ask it in a normal chat to run `openclaw cron scratch <jobId> --set ...`, or edit the scratch yourself with the same command. Manage recurring schedules with cron instead of writing scheduler syntax into scratch.
|
||||
Yes. During a heartbeat turn, the agent can pass a `scratch` value to `heartbeat_respond` to fully replace the monitor prose for future heartbeats. You can also ask it in a normal chat to run `openclaw cron scratch <jobId> --set ...`, or edit the scratch yourself with the same command. Manage recurring schedules with automations instead of writing scheduler syntax into scratch.
|
||||
|
||||
<Warning>
|
||||
Don't put secrets (API keys, phone numbers, private tokens) into monitor scratch - it becomes part of the prompt context.
|
||||
|
||||
@@ -220,7 +220,7 @@ Notes:
|
||||
- It resolves CLI smoke metadata from the owning plugin, then installs the matching Linux CLI package (`@anthropic-ai/claude-code` or `@google/gemini-cli`) into a cached writable prefix at `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (default: `~/.cache/openclaw/docker-cli-tools`).
|
||||
- `codex-cli` is no longer a bundled CLI backend; use `openai/*` with the Codex app-server runtime instead (see [Live: Codex app-server harness smoke](#live-codex-app-server-harness-smoke)).
|
||||
- `pnpm test:docker:live-cli-backend:claude-subscription` requires portable Claude Code subscription OAuth through either `~/.claude/.credentials.json` with `claudeAiOauth.subscriptionType` or `CLAUDE_CODE_OAUTH_TOKEN` from `claude setup-token`. It first proves direct `claude -p` in Docker, then runs two Gateway CLI-backend turns without preserving Anthropic API-key env vars. This subscription lane disables the Claude MCP/tool and image probes by default because it consumes the signed-in subscription's usage limits and Anthropic can change Claude Agent SDK / `claude -p` billing and rate-limit behavior without an OpenClaw release.
|
||||
- Claude and Gemini support the same probe set (text turn, image classification, MCP `cron` tool call, model-switch continuity) through the flags above, but none of those probes run by default - opt in per flag as needed.
|
||||
- Claude and Gemini support the same probe set (text turn, image classification, MCP `automations` tool call, model-switch continuity) through the flags above, but none of those probes run by default - opt in per flag as needed.
|
||||
|
||||
## Live: APNs HTTP/2 proxy reachability
|
||||
|
||||
|
||||
@@ -116,7 +116,7 @@ Example placeholders (replace or remove them):
|
||||
|
||||
When you receive a heartbeat poll (message matches the configured heartbeat prompt), don't just reply `HEARTBEAT_OK` every time. Keep a short checklist or reminders in the heartbeat monitor's cron scratch; use `openclaw cron list --all` to find the monitor job, then `openclaw cron scratch <jobId> --set "..."` to update it. Keep it small to limit token burn.
|
||||
|
||||
See [Scheduled Tasks (Cron) vs Heartbeat](/automation#scheduled-tasks-cron-vs-heartbeat) for the full decision table. Short version: heartbeat batches periodic checks with full session context on approximate timing (default every 30 minutes); cron is for exact timing, isolated runs, a different model, or one-shot reminders.
|
||||
See [Scheduled Tasks (Cron) vs Heartbeat](/automation#automations-vs-heartbeat) for the full decision table. Short version: heartbeat batches periodic checks with full session context on approximate timing (default every 30 minutes); cron is for exact timing, isolated runs, a different model, or one-shot reminders.
|
||||
|
||||
**Things to check (rotate through these, 2-4 times per day):** emails for urgent unread messages; calendar for events in the next 24-48h; social mentions; weather if your human might go out.
|
||||
|
||||
@@ -151,5 +151,5 @@ This is a starting point. Add your own conventions, style, and rules as you figu
|
||||
## Related
|
||||
|
||||
- [Default AGENTS.md](/reference/AGENTS.default)
|
||||
- [Scheduled tasks vs heartbeat](/automation#scheduled-tasks-cron-vs-heartbeat)
|
||||
- [Scheduled tasks vs heartbeat](/automation#automations-vs-heartbeat)
|
||||
- [Heartbeat](/gateway/heartbeat)
|
||||
|
||||
@@ -168,7 +168,7 @@ Example:
|
||||
## Heartbeats (proactive mode)
|
||||
|
||||
By default, OpenClaw runs a heartbeat every 30 minutes with the prompt:
|
||||
`Follow the heartbeat monitor scratch context when provided. Recurring tasks are cron jobs; create or change their schedules with cron tools or the openclaw cron CLI, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
|
||||
`Follow the heartbeat monitor scratch context when provided. Recurring tasks are automations; create or change their schedules with the automations tool, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
|
||||
Set `agents.defaults.heartbeat.every: "0m"` to disable. Heartbeat checklists live in the monitor's cron scratch (see [Heartbeat](/gateway/heartbeat)); `openclaw doctor --fix` migrates a legacy workspace `HEARTBEAT.md` into it.
|
||||
|
||||
- If the monitor scratch exists but is effectively empty (only blank lines, Markdown/HTML comments, Markdown headings like `# Heading`, fence markers, or empty checklist stubs), OpenClaw skips the heartbeat run to save API calls.
|
||||
|
||||
@@ -122,7 +122,7 @@ Malformed local-model reasoning tags are handled conservatively. Closed `<think>
|
||||
|
||||
## Heartbeats
|
||||
|
||||
- Heartbeat probe body is the configured heartbeat prompt (default: `Follow the heartbeat monitor scratch context when provided. Recurring tasks are cron jobs; create or change their schedules with cron tools or the openclaw cron CLI, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Inline directives in a heartbeat message apply as usual (but avoid changing session defaults from heartbeats).
|
||||
- Heartbeat probe body is the configured heartbeat prompt (default: `Follow the heartbeat monitor scratch context when provided. Recurring tasks are automations; create or change their schedules with the automations tool, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Inline directives in a heartbeat message apply as usual (but avoid changing session defaults from heartbeats).
|
||||
- Heartbeat delivery uses the last outbound-capable non-reasoning payload. Separate reasoning or `Thinking` payloads remain internal, and a reasoning-only heartbeat result produces no alert.
|
||||
|
||||
## Web chat UI
|
||||
|
||||
@@ -325,7 +325,7 @@ capabilities? }` — create/update by name; `pin` places it on the board.
|
||||
- `dashboard { action, ... }` — board management verbs: `read`, `tab_create`,
|
||||
`tab_update`, `tab_delete`, `tabs_reorder`, `widget_move`, `widget_remove`,
|
||||
`unpin`, `focus_tab`, `set_chat_dock`.
|
||||
- Existing `cron` tools cover the automation tier; no new tool needed.
|
||||
- The existing `automations` tool covers the automation tier; no new tool needed.
|
||||
|
||||
Tool descriptions teach the size/anchor vocabulary and the tier model. The
|
||||
agent is told about user tier-1 events via session notices, e.g.
|
||||
|
||||
Reference in New Issue
Block a user