Task Flow Orchestration

Task Flow sits on top of background tasks as the coordination layer. Each flow is a persistent record of work spanning multiple steps, carrying its own status, JSON state, revision counter, and references to linked tasks. Flows survive gateway restarts; individual tasks continue to serve as the unit of detached execution.

When to use Task Flow

Scenario	Use
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	Automation job

Sync modes

Managed mode

A managed flow is controlled by plugin code. That code creates the flow through the plugin runtime Task Flow API, supplying a goal and a mandatory controller id, and then drives it step by step.

Each step executes as a background task created beneath the flow; child tasks inherit the flow's owner key and requester origin.
The controller moves the flow between running, waiting, and terminal states, and writes arbitrary JSON step state onto the flow record.
Every change is checked against the flow's expected revision. A write carrying a stale revision is refused as a conflict rather than overwriting newer data.
After cancellation is requested, no new child tasks are accepted, and the flow ends as cancelled once every child task has stopped.

For instance, a weekly report flow might (1) collect data, (2) produce the report, and (3) send it out, with one background task per phase:

Flow: weekly-report
  Step 1: gather-data     → task created → succeeded
  Step 2: generate-report → task created → succeeded
  Step 3: deliver         → task created → running

Mirrored mode

When a detached ACP or subagent run starts (session-scoped tasks with deliverable completion), OpenClaw automatically creates a mirrored flow holding a single task. The flow record mirrors its one backing task, including status, goal, and timing, so detached spawns receive a stable flow handle for status and retry surfaces without any controller. Mirrored flows report sync mode task_mirrored in the CLI.

Flow statuses

Status	Meaning
`queued`	Created, not yet progressing
`running`	Flow is actively progressing
`waiting`	Managed flow is parked on wait metadata (timer, external event)
`blocked`	Waiting on a blocking condition, or ended without a usable result
`succeeded`	Completed successfully
`failed`	Completed with an error
`cancelled`	Cancel requested and all child tasks settled
`lost`	Flow lost its authoritative backing state

blocked is the sole status whose terminal interpretation depends on the record. A managed flow lacking endedAt can still be resumed. A blocked flow that carries endedAt is done, which covers mirrored flows whose backing task finished with a blocked outcome.

Durable state and revision tracking

Flow records live in the shared SQLite state database (~/.openclaw/state/openclaw.sqlite, flow_runs table) next to task records, so progress persists across gateway restarts. Each write increments the flow's revision; concurrent writers submitting a stale expected revision receive a conflict and must re-read. WAL growth stays bounded through SQLite autocheckpointing plus periodic passive checkpoints, with truncate checkpoints at shutdown. The older flows/registry.sqlite sidecar from previous installs gets imported by openclaw doctor.

Gateway maintenance keeps finished flows for 7 days before pruning them. That includes blocked flows with endedAt; resumable managed blocked flows stay regardless of how old they are.

Cancel behavior

openclaw tasks flow cancel applies a sticky cancel intent to the flow, cancels its active child tasks, and blocks new managed child tasks. Once no child task remains active, the flow finalizes as cancelled, either right away or through the maintenance sweep if children take longer to wind down. Because the intent is persisted, a cancelled flow remains cancelled even if the gateway restarts before all child tasks have ended.

CLI commands

# List active and recent flows
openclaw tasks flow list [--status <status>] [--json]

# Show details for a specific flow
openclaw tasks flow show <lookup> [--json]

# Cancel a running flow and its active tasks
openclaw tasks flow cancel <lookup>

Command	Description
`openclaw tasks flow list`	Tracked flows with sync mode, status, revision, controller, task counts
`openclaw tasks flow show <id>`	Inspect one flow by flow id or owner key, including linked tasks
`openclaw tasks flow cancel <id>`	Cancel a running flow and its active tasks

Flows also fall under openclaw tasks audit (stale or broken flow findings) and openclaw tasks maintenance (finalizes stuck cancels, prunes terminal flows after 7 days).

Reliable scheduled workflow pattern

For recurring workflows like market intelligence briefings, treat scheduling, orchestration, and reliability checks as separate concerns:

Use Automations for timing.
Use a persistent automation session when the workflow should build on prior context.
Use Lobster for deterministic steps, approval gates, and resume tokens.
Use Task Flow to track the multi-step run across child tasks, waits, retries, and gateway restarts.

Example automation job (openclaw automations; openclaw cron remains an alias):

openclaw automations add \
  --name "Market intelligence brief" \
  --cron "0 7 * * 1-5" \
  --tz "America/New_York" \
  --session session:market-intel \
  --message "Run the market-intel Lobster workflow. Verify source freshness before summarizing." \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

Choose --session session:<id> over isolated when the recurring workflow needs deliberate history, previous run summaries, or standing context. Pick isolated when each run should begin clean and all required state is spelled out in the workflow.

Inside the workflow, place reliability checks before the LLM summary step:

name: market-intel-brief
steps:
  - id: preflight
    command: market-intel check --json
  - id: collect
    command: market-intel collect --json
    stdin: $preflight.json
  - id: summarize
    command: market-intel summarize --json
    stdin: $collect.json
  - id: approve
    command: market-intel deliver --preview
    stdin: $summarize.json
    approval: required
  - id: deliver
    command: market-intel deliver --execute
    stdin: $summarize.json
    condition: $approve.approved

Suggested preflight checks:

Browser availability and profile choice, for example openclaw for managed state or user when a signed-in Chrome session is required. See Browser.
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 the automation so preflight failures are visible. See Automations.

Suggested data provenance fields for every collected item:

{
  "sourceUrl": "https://example.com/report",
  "retrievedAt": "2026-04-24T12:00:00Z",
  "asOf": "2026-04-24",
  "title": "Example report",
  "content": "..."
}

Have the workflow flag or reject outdated items prior to summarization. The LLM step must receive only structured JSON and should be instructed to retain sourceUrl, retrievedAt, and asOf in its response. When a schema-validated model step is required within the workflow, opt for LLM Task.

For reusable team or community workflows, bundle the CLI, .lobster files, and any setup instructions as a skill or plugin, then distribute it via ClawHub. Unless the plugin API lacks a necessary generic capability, keep workflow-specific guardrails inside that package.

How flows relate to tasks

Flows orchestrate tasks rather than replace them. Over its lifespan, a single flow can drive multiple background tasks. To examine individual task records, use openclaw tasks; to examine the orchestrating flow, use openclaw tasks flow.

Background Tasks - the detached work ledger that flows coordinate
CLI: tasks - CLI command reference for openclaw tasks flow
Automation Overview - all automation mechanisms at a glance
Automations - scheduled jobs that may feed into flows