OpenClaw automation payloads

Once a schedule decides when a job fires, the payload decides what runs and where. OpenClaw jobs carry exactly one payload kind: a system event enqueued into the main session with no model call, an agent message that runs a model-backed turn, a command that runs a process on the Gateway host, or a headless script that uses the owning agent’s tools. Here are the kinds, the agent-turn options and how model and tool choices resolve, the command and script contracts, and the four session execution styles.

Kinds and options

• System-owned monitor jobs are converged by the Gateway and cannot be created or edited by the CLI or API: the heartbeat kind creates one monitor job per heartbeat-enabled agent, and the weekly Skill Workshop review is a normal isolated agent-turn job with a reserved key that runs every seven days when the Workshop’s autonomous mode is auto; both appear in the list, and scheduled reviews require automations to be enabled.
• Agent-turn options: the required message, a model override that must resolve to an allowed model or the run fails with a validation error, a per-job fallback list where an empty string means a strict run, clear flags on edit for model, fallbacks and thinking, a thinking level whose availability depends on the model and runtime, a light-context flag that skips workspace bootstrap injection, and a tools flag that restricts the job’s tools.
• New jobs that can run tools always store an explicit tool policy: jobs created by an agent are capped to the tools available to the creating turn and the agent cannot widen the list, jobs created by an authenticated operator without a tools flag store an unrestricted policy, and older jobs keep their behaviour until edited or recreated.
• Model precedence for isolated jobs, highest first: the per-job payload model, a Gmail hook override when the run came from Gmail, the stored automation-session override, then the agent default; fast mode follows the resolved live selection, a live model-switch handoff is retried at most twice, and before an isolated run starts OpenClaw probes reachable local endpoints for loopback or private-network providers, caching the result five minutes per endpoint and marking the run skipped instead of starting a model call when every candidate is down.

Pick the model for the job’s difficulty, not the agent’s default.

Commands and scripts

Command payloads run deterministic scripts inside the Gateway scheduler without a model turn: they execute on the Gateway host, capture stdout and stderr, record the run in history and reuse the announce, webhook and none delivery modes. A shell command is stored as a login-shell argv while an argv flag gives exact execution without shell parsing, with optional environment entries, stdin, a ten-minute default timeout, a no-output timeout and an output cap. Delivered text is derived from output, non-empty stdout first, then stderr, or a small block of both; exit zero records ok, and a non-zero exit, signal or timeout records an error that can trigger failure alerts, while a command printing only the silent token posts nothing. The docs are precise about authority: command payloads are an operator-admin Gateway surface, not an agent exec call, so creating, updating, removing or manually running them requires operator admin, and agent exec policy and approval prompts govern model-visible tools, not these. When an agent-turn job’s exec needs approval, the card reaches the connected approval surfaces, the run waits, and answering always-allow mints a scoped standing grant so later occurrences run without prompting. Script payloads run headlessly in the same code-mode executor as trigger scripts, support only main and isolated sessions, read JavaScript from a file or stdin, default to a three-hundred-second timeout capped at nine hundred and a fifty-call tool budget capped at two hundred, and may return a notify text delivered through the job’s mode, a wake of now or next-heartbeat, a state value persisted only after success and handed back frozen, and a next-check duration valid only with pacing; throws, timeouts, exhausted budgets and invalid results are ordinary run errors.

Where a job runs

• Four styles: main runs in the owning agent’s main session and suits reminders and system events; isolated runs in a dedicated per-job session for reports and chores; current runs detached but commits its final visible result to the conversation the job was created from; and a named custom session persists context across runs for workflows that build on history. Agent-turn jobs default to the creating conversation when the create request carries session context and otherwise to isolated, system events and heartbeats default to main, and command and script payloads default to isolated.
• Main-session jobs enqueue a system event, optionally waking the heartbeat now or at the next tick, and use the session’s existing delivery context rather than a separate announce target, so edits that enable announce delivery on them are rejected; a fresh isolated session means a new transcript per run that carries safe preferences such as thinking, fast mode and explicit model overrides but no ambient routing, queue policy, elevation or ACP binding.
• The unattended run contract: isolated automation and hook turns have no one present to clarify or approve, so the final reply must be the deliverable rather than a plan or a question, the agent returns the silent token when nothing needs doing and states failures plainly, and the scheduler owns retry and alerts; trusted scheduled jobs may ask for a question when their instructions say so and may remove a job that is no longer needed, while external hook turns get only the common contract. When isolated runs orchestrate sub-agents, delivery prefers the final descendant output over stale parent text, and text-only Discord targets receive the canonical final text once.

OpenClaw models and providers covers the providers a per-job model can name, and OpenClaw thinking levels the levels the thinking flag selects.

Authority and context

Two distinctions carry the page: command payloads belong to the operator, not to the agent’s exec policy, and an isolated session is fresh on purpose, so a job that needs the conversation must say current or name a session. OpenClaw exec approvals explains the standing grants an approved automation exec mints, and OpenClaw sessions the keys a custom session is addressed by.

On Diali

On Diali the agent-message payload is what the dashboard creates, with per-job model and thinking overrides drawing on the same providers as the chat; command and script payloads are an operator surface that runs inside the Gateway with the assistant’s own permissions. Hosted OpenClaw on Diali is the assistant and The OpenClaw Skill Workshop the system-owned weekly review job that shares this scheduler.

• One payload kind per job; four kinds in all.
• Agent-created jobs cannot widen their tools.
• Isolated is fresh by design; current commits back.