OpenClaw background tasks

Work that runs outside your main conversation, an ACP run, a sub-agent spawn, an automation job, a CLI-initiated operation, needs somewhere to be seen. OpenClaw’s background tasks are that place: an activity ledger recording what detached work happened, when, and whether it succeeded, without replacing sessions, automations or heartbeats, which decide when work runs. Here is what creates a task, the lifecycle and the runtime-aware lost state, why delivery is tracked apart from execution, the notification paths and policies, the recovery commands, and the audit and maintenance rules.

What creates a task

• ACP background runs when a child ACP session is spawned, sub-agent orchestration when a sub-agent is spawned, every automation run whether main-session or isolated, agent commands that run through the Gateway, and session-backed image, music and video generation runs; heartbeat turns, normal interactive chat and direct command responses do not.
• Default notify policies differ: ACP and sub-agent tasks report only the terminal state, while automation, CLI and media tasks are silent, since the scheduler owns its own delivery path and media completion is handed back to the requesting session as an internal wake, with an idempotent direct fallback of any missing media to the original channel if that wake fails.
• While a media-generation task is active, repeating the same prompt returns the active task’s status instead of starting a duplicate, a distinct prompt starts its own task, and a status action gives an explicit progress lookup.
• Terminal records are kept seven days, lost records twenty-four hours, then pruned automatically; the tasks list shows everything newest first with runtime and status filters, and a bare tasks command behaves like list.

Tasks are records, not schedulers - automations and heartbeat decide when work runs, tasks track what happened.

Lifecycle and delivery

Each task moves from queued to running to a terminal state, succeeded, failed, timed out, cancelled or lost, driven automatically by run lifecycle events, and once terminal a later signal never downgrades it. Lost is runtime-aware: an ACP task is alive only while a live in-process turn exists in the Gateway, a sub-agent task is lost when its child session disappeared or carries a restart-recovery tombstone, an automation task first checks durable run history before being marked lost, and a CLI task with run identity checks the live run context rather than lingering session rows. Execution and result delivery are separate: a sub-agent task can stay succeeded while its delivery is queued or failed, and the terminal outcome is succeeded after delivery and blocked when the work finished but the result could not be handed back, which preserves the result instead of misreporting the child as failed; blocked tasks appear under both the blocked and succeeded filters. Delivery is push-driven: direct delivery goes straight to the requesting channel when the task has an origin, with group and channel completions routed through the requester session so the parent agent writes the visible reply, and session-queued delivery, used when direct delivery fails or no origin exists, surfaces the update as a system event on the next heartbeat, which it wakes immediately. Durable sub-agent handoffs retry for up to thirty minutes with capped backoff; when delivery reaches its deadline the task shows a blocked outcome and keeps its result for seven days, and a retry starts a fenced new delivery generation while dismiss records intentional non-delivery. With a public origin configured and the Control UI enabled, direct notifications carry an inspect link to the task’s own session.

Policies, audit, maintenance

• Three notification policies: done-only, the default for ACP and sub-agents, delivering only the terminal state; state-changes, delivering every transition and progress update; and silent, the default for automation, CLI and media tasks; the policy can be changed while a task runs, and notifications stay with the recorded requester agent even under a global session scope.
• The tasks audit surfaces issues for tasks and flows in one report and in the status command: queued more than ten minutes, running more than thirty, lost ownership, failed delivery under a non-silent policy, a terminal task with no cleanup timestamp, and timeline violations; flow findings add failed registry restores, stale running, waiting or blocked flows, stuck cancels after five minutes, missing linked tasks and dangling blocked task ids.
• Maintenance previews or applies reconciliation, cleanup stamping and pruning: only the Gateway process is authoritative for liveness, so offline CLI audit never reclaims ACP tasks or marks an automation task lost merely because its local in-memory set is empty; cancellation aborts only the selected live run and its pending approvals and reports success only after it settles, and completion cleanup best-effort closes tracked browser tabs and processes for the child session while isolated automation delivery waits out descendant sub-agent work and suppresses stale parent acknowledgements.

OpenClaw Task Flow is the orchestration record that coordinates several of these tasks, and OpenClaw heartbeat the tick that session-queued completions wake.

The push-based habit

The docs’ conclusion is a working habit: start detached work once, then let the runtime wake or notify you on completion, and poll task state only for debugging, intervention or an explicit audit. OpenClaw sub-agents covers the spawns that fill most of this ledger, and OpenClaw automations the jobs whose every run lands in it silently.

On Diali

On Diali the task ledger runs with the upstream defaults, seven days of terminal records on the assistant’s volume, and completion notices reach the channel the work was requested from. Hosted OpenClaw on Diali is the assistant and OpenClaw sessions the requester session a queued completion returns to.

• A ledger, not a scheduler.
• Succeeded can still be blocked; delivery is tracked apart.
• Push, do not poll; audit when something looks stale.