OpenClaw Task Flow

A single background job needs a task record; a multi-step pipeline needs something that remembers where it is across restarts. OpenClaw’s Task Flow is that layer: a flow is a durable record of multi-step work with its own status, JSON state, revision counter and linked task records, it survives Gateway restarts, and individual tasks remain the unit of detached work. Here is when to use one, the managed and mirrored sync modes, the statuses, how state and revisions are stored, how cancellation settles, the CLI, and the docs’ pattern for a reliable scheduled workflow.

When and how

• A single background job is a plain task, a multi-step pipeline driven by plugin code is a managed flow, a detached ACP or sub-agent spawn gets a mirrored flow created automatically, and a one-shot reminder is an automation job.
• A managed flow has a controller: plugin code creates the flow with a goal and controller id and drives it explicitly. Creating a managed flow creates state, not an execution, linking a task links an existing execution rather than launching one, the controller moves between running, waiting and terminal states while keeping bounded ids, summaries and cursors in the state JSON, and every transition, waiting, resume, finish, fail and cancel request, requires the latest expected revision, so every result must be checked.
• Child work is launched through its supported runtime before it is linked, and linking requires the existing authoritative backing task, its canonical run id and child session key, the right runtime and the same owner session; a copied session key or invented run id is not authority. For Gateway-backed plugin sub-agents the public path is the runtime’s sub-agent run with current-requester completion delivery inside a real requester-bound dispatch hook, and the host creates the canonical task and mirrored flow.
• A mirrored flow is created automatically when a detached ACP or sub-agent run starts: it mirrors its single backing task, status, goal and timing, giving detached spawns a stable handle for status and retry surfaces without a controller, and shows the task-mirrored sync mode in the CLI.

Flows coordinate tasks, not replace them.

Statuses, state, cancellation

Eight statuses: queued, running, waiting when a managed flow is parked on wait metadata such as a timer or external event, blocked, succeeded, failed, cancelled once a cancel was requested and all children settled, and lost when the flow lost its authoritative backing state. Blocked is the only status whose terminal meaning depends on the record: a managed flow with no end time remains resumable, while a blocked flow with an end time is finished, including mirrored flows whose backing task ended blocked. Records persist in the shared SQLite state database alongside tasks, each write bumps the revision, a stale expected revision gets a conflict and must re-read, and an older sidecar registry is imported by the doctor command. Durability covers records, not a JavaScript call stack or automatic scheduling: after a restart the owning controller reloads the flow, checks cancellation and terminal state, reconciles child outcomes and explicitly resumes from the latest revision, waiting metadata alone registers no timer, and side effects are never blindly replayed after a conflict. Finished flows are retained seven days, resumable blocked ones regardless of age. Cancelling sets a sticky intent, cancels active children, refuses new managed children, and finalises as cancelled once no child is active, immediately or via the maintenance sweep, and the intent survives a restart.

CLI and the workflow pattern

• The flow commands list tracked flows with sync mode, status, revision, controller and task counts, show one flow by id or owner key including linked tasks, and cancel a running flow and its active tasks; flows are also covered by the tasks audit for stale or broken findings and by tasks maintenance, which finalises stuck cancels and prunes terminal flows after seven days.
• For recurring workflows such as a market intelligence brief, the docs separate four layers: automations for timing, a persistent automation session when the workflow should build on prior context, the optional Lobster tool for deterministic steps, approval gates and resume tokens, and Task Flow to track the run across child tasks, waits, retries and restarts. The Lobster tool can run a workflow with a flow controller id and goal, records a real approval pause as waiting, and returns a mutation whose applied flag and post-mutation record supply the next expected revision.
• Inside the workflow, reliability checks come before the model summary step: a preflight for browser availability and profile, credentials and quota, network reachability, required tools and a configured failure destination, provenance fields on every collected item with a source URL, retrieval time and as-of date, rejection of stale items before summarisation, and a schema-validated model step that must preserve those fields.

OpenClaw background tasks is the ledger of detached work a flow coordinates, and OpenClaw automations the timing layer that feeds it.

Where it fits

A flow does not replace tasks, sessions, automations or goals; it gives a multi-step run one durable handle whose revision protects it from two writers. OpenClaw sub-agents explains the detached spawns that get mirrored flows, and OpenClaw doctor the command that imports an older flow registry into the shared database.

On Diali

On Diali flow records live in the assistant’s state database on its volume and survive releases like the rest of its state, and the timing layer is the automations you create from the dashboard. Hosted OpenClaw on Diali is the assistant and OpenClaw session goals the per-session objective that sits beside a flow rather than inside it.

• A durable record with a revision, not a call stack.
• Managed flows have a controller; mirrored flows have a task.
• Cancel is sticky; blocked has two meanings.