负载

What a job runs and where it runs: the four payload kinds, their flags, and the four session execution styles. Part of the Automations guide.

Payloads¶

Every job carries exactly one payload kind, chosen by flag:

System-owned monitor jobs are gateway-converged and cannot be created or edited through the CLI or API. The heartbeat kind creates one heartbeat monitor job per heartbeat-enabled agent (see Heartbeat). The weekly Skill Workshop review is a normal isolated agentTurn job with a reserved declaration key. Both appear in openclaw cron list; use --all to include disabled rows. The skillCollectionReview payload kind is not accepted. Stored rows that use it are replaced with the canonical review job.

Skill collection review runs every 7 days. It is enabled when skills.workshop.autonomous.mode is auto; propose and off keep the system-owned job disabled. In auto mode, a review stays disabled when every statically resolvable model candidate is known to lack rooted execution support. Its display name includes no-rooted-runtime; inspect disabled rows with openclaw cron list --all --json. A supported fallback keeps the job enabled. Stored session model/runtime preferences and unknown eligibility also keep it enabled, with final checks at execution time. The Gateway converges these jobs at startup and after config reload. Convergence clears the reason and restores auto-mode enablement when the configured chain becomes eligible or unknown. Scheduled reviews require automations. When cron.enabled is false or OPENCLAW_SKIP_CRON=1, the Gateway logs a startup warning and does not run scheduled reviews. There is no separate weekly Gateway timer.

Agent-turn options¶

--message string (path) required

Prompt text (required for isolated/current/custom-session jobs).

--model string (path)

Model override; must resolve to an allowed model or the run fails with a validation error.

--fallbacks string (path)

Per-job fallback model list, for example --fallbacks openai/gpt-6-astra,openrouter/meta-llama/llama-3.3-70b-instruct:free. Pass --fallbacks "" for a strict run with no fallbacks.

--clear-fallbacks boolean (path)

On automations edit, removes the per-job fallback override so the job follows configured fallback precedence. Cannot combine with --fallbacks.

--clear-model boolean (path)

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.

--thinking string (path)

Thinking level override (off|minimal|low|medium|high|xhigh|adaptive|max|ultra). Available levels still depend on the selected model and agent runtime.

--clear-thinking boolean (path)

On automations edit, removes the per-job thinking override. Cannot combine with --thinking.

--light-context boolean (path)

Skip workspace bootstrap file injection.

--tools string (path)

Restrict which tools the job can use, for example --tools exec,read. Pass --tools "" for an empty allowlist that disables all agent tools, including tools used by a condition trigger.

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

Changing an account-bound job to a payload that does not run tools and later back to an agent turn preserves its account restriction. A payload conversion does not reauthorize that job as an operator-created job.

Management edits cannot restore missing policy metadata as operator authority. For a legacy job that has lost its policy, an authenticated operator can explicitly reauthorize it, or an authenticated creator can recreate it with a fresh tool cap.

When the creator's exec capability is fixed to the Gateway, the automation also retains that target. With tools.exec.host: "auto", the saved target determines placement. A conflicting current explicit host setting or required sandbox isolation blocks the command instead of moving it to another host. Current tool and approval policies still apply.

With message in the tool cap, scheduled agent turns can read messages and channel information on supported channel plugins without an inbound chat. Operator-created jobs use the current operator read policy. Agent-created jobs retain their recorded creator origin and account, and the channel's delegated read restrictions still apply. Delivery settings do not grant read access.

Current global, agent, profile, and provider tool policy is checked when each new scheduled message invocation starts. Configuration changes apply to later invocations; an invocation already admitted retains its configuration. Disabling or removing a job, withdrawing its message capability, or revoking its caller or plugin authority stops further affected reads from that occurrence, including pending reads before another provider request or result delivery. Re-enabling the job does not restore an occurrence's revoked access.

A new account-bound job created by a verified local administrator retains that authenticated local source, allowing provider-permitted reads through its saved creator account. Editing its toolsAllow cap from the same local source explicitly reauthorizes an existing job. Description, display-label, and exact no-op edits preserve the recorded source. Changes to model-facing names, prompts, tools, schedules, or other executable behavior need fresh source authorization and clear the old source when none is present. Remote management alone cannot supply local-source authorization, and older jobs without a provable origin remain blocked until reauthorized or recreated from a fresh authorized source.

Scheduled turns can also edit, delete, pin, and unpin Discord messages. Agent-created jobs use their recorded creator account and Discord's delegated target restrictions. Operator-created jobs use Discord's operator target policy. Trusted operator jobs can additionally use channel-edit, including the existing channel and thread edit options; account-created jobs do not inherit operator administration.

For these writes, the job needs message in its tool policy, an enabled account and action, and the bot's required Discord permissions. Use an updated Discord plugin with scheduled write support.

Account-bound jobs can use Discord channel-edit when an authenticated Discord turn has authorized their current definition. OpenClaw privately retains that requester's Discord account and sender identity, and Discord's current channel or thread permissions must allow the edit. The original session creator and a configured OpenClaw owner are not substitutes for those native permissions.

Executable edits from the job's owning conversation and account bind the job to the current authorized editor. This includes the prompt, model, name, schedule, delivery, and tool policy. An executable edit without a matching authenticated Discord requester clears this permission and stops further native actions from the old occurrence. Description and display-label changes preserve it.

Older jobs, jobs edited by older writers, and jobs whose requester authorization was cleared need fresh authorization before channel-edit can run. From the original Discord conversation and account, ask the agent to edit the job with an explicit finite toolsAllow list including message, or recreate it there. If its execution authorization is also missing, recreate it from that conversation; management access alone does not restore the missing authorization. The editor must already have automation-management access. Other job behavior keeps its existing policy; a CLI edit cannot invent a Discord requester. These requester facts are omitted from public job results, and no new setting is needed.

Channel-name lookup and subsequent write requests retain the current job and plugin authority. Configuration changes apply to the next message invocation; disabling or narrowing the job itself stops later requests and retries in the current invocation. A confirmed write still returns its result if authority ends while the response is pending.

--model sets the job's primary model; it does not replace a session /model override, so configured fallback chains still apply on top of it. An unresolved or disallowed model fails the run with an explicit validation error rather than silently falling back to the default. If a job has --model but no explicit or configured fallback list, OpenClaw passes an empty fallback override instead of silently appending the agent primary as a hidden retry target.

Pick the model for the job's difficulty, not the agent's default. Routine automation - summaries, triage, classification, status checks - runs well on a lighter model, which is cheaper and faster per run and adds up across a schedule. Keep your default model for jobs that need deep reasoning, and use --fallbacks when a light primary should escalate on failure.

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 automation-session model override
4. Agent/default model selection

Fast mode follows the resolved live selection. Isolated automation resolves it in this order: stored session fastMode, per-agent agents.entries.*.fastModeDefault, global agents.defaults.fastModeDefault, then selected-model params.fastMode. Auto mode uses the model's params.fastAutoOnSeconds cutoff, defaulting to 60 seconds.

When a runtime reports token usage without a cost, automation estimates use the selected agent's local models.json prices and the model metadata retained for that run.

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.

Client-side preflight timeouts are not cached. The next scheduled run probes the endpoint again instead of inheriting a timeout from another run.

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 the job's run history, and reuse the same announce, webhook, and none delivery modes as agent-turn jobs.

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

--command <shell> stores argv: ["sh", "-lc", <shell>]. Use --command-argv '["node","scripts/report.mjs"]' for exact argv execution 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, 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.

When the run deadline stops a command, run history retains its captured output and command timeout reason after bounded process cleanup. Completion delivery does not start after that deadline.

Script payloads¶

Script payloads run headlessly in the same code-mode executor as trigger scripts, without starting a conversational agent turn. They are available by default; setting cron.triggers.enabled: false disables creation and execution of script payloads together with condition-trigger scripts and stream schedules. Script jobs support only main and isolated session targets.

openclaw automations create "0 * * * *" \
  --name "Hourly queue check" \
  --script ./automation/check-queue.js \
  --script-timeout-seconds 300 \
  --script-tool-budget 50 \
  --session isolated \
  --announce

Use --script <file|-> to read JavaScript from a file or stdin. The CLI preserves leading and trailing spaces in file paths; quote the path as one shell argument. The timeout defaults to 300 seconds and is capped at 900; the tool budget defaults to 50 calls and is capped at 200. These payload budgets are separate from the smaller trigger-gate evaluation budgets.

The script may return an object with these optional fields:

• notify: Text delivered through the job's announce, webhook, or none delivery mode. If omitted, nothing is delivered. For a main job, the text becomes a system event.
• wake: "now" requests an immediate heartbeat after enqueueing notify (or a compact completion event); "next-heartbeat" enqueues the event for the next heartbeat.
• 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 automation run errors: they enter run history, backoff, and failure-alert handling without persisting returned state.

Plugin reloads invalidate cached script preparation. If a plugin retires during setup, OpenClaw refreshes the tools once before starting the script, within the original deadline. A failure after the script starts never triggers this setup retry. If the refresh fails, run history and failure alerts explain that automatic setup recovery failed and the script did not run.

Changing a running job's script payload or saved state protects that edit from the old script's returned state, including when completion is recovered after a Gateway restart. The completed run still retains its history.

Execution styles¶

Codex apps in scheduled automations¶

Codex-created automations can retain the app IDs and permission ceiling available to the authenticated creator thread. At execution, OpenClaw requires the same prepared Codex profile and account, then narrows the stored cap against current app policy. Revoked apps, account/runtime changes, and interactive approval requirements fail closed with a recovery message; they never fall back to broader or different credentials. Older jobs without a captured app envelope continue their ordinary non-app behavior; recreate or reauthorize one only when it needs Codex app access. See Native Codex plugins.

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.