Neura Market Logo

Task Flow Orchestration Layer for Multi-Step Pipelines

This page explains Task Flow, an orchestration layer above background tasks for managing multi-step pipelines. It covers sync modes, when to use flows versus plain tasks, and how flows persist across restarts.

Read this when

  • You want to understand how Task Flow relates to background tasks
  • You encounter Task Flow or openclaw tasks flow in release notes or docs
  • You want to inspect or manage durable flow state

Task Flow sits above background tasks as an orchestration layer. A flow represents a durable record of work spanning multiple steps, carrying its own status, JSON state, revision counter, and associated task records. Flows persist across gateway restarts, while individual tasks remain the unit of independent work.

When to use Task Flow

ScenarioUse
Single background jobPlain task
Multi-step pipeline driven by plugin codeTask Flow (managed)
Detached ACP or subagent spawnTask Flow (mirrored, created automatically)
One-shot reminderCron job

Sync modes

Managed mode

A managed flow requires a controller: plugin code that uses the plugin runtime Task Flow API to create the flow with a goal and a mandatory controller id, then drives it explicitly.

  • Each step executes as a background task created under the flow; the flow's owner key and requester origin propagate to child tasks.
  • The controller moves the flow between running, waiting, and terminal states, and stores arbitrary JSON step state on the flow record.
  • Every mutation requires the flow's expected revision. A stale write is rejected as a revision conflict instead of overwriting newer state.
  • Once cancellation is requested, new child tasks are denied, and the flow finalizes as cancelled when no child task remains active.

Example: a weekly report flow that (1) gathers data, (2) generates the report, and (3) delivers it, one background task per step:

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

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

Flow statuses

StatusMeaning
queuedCreated, not yet progressing
runningFlow is actively progressing
waitingManaged flow is parked on wait metadata (timer, external event)
blockedA step finished without a usable result; blockedTaskId/summary say which
succeededCompleted successfully
failedCompleted with an error
cancelledCancel requested and all child tasks settled
lostFlow lost its authoritative backing state

Durable state and revision tracking

Flow records live in the shared SQLite state database (~/.openclaw/state/openclaw.sqlite, flow_runs table) alongside task records, so progress survives gateway restarts. Each write increments the flow's revision; concurrent writers that supply a stale expected revision receive a conflict and must re-read. WAL growth is limited by SQLite autocheckpointing plus periodic passive checkpoints, with truncate checkpoints on shutdown. The legacy flows/registry.sqlite sidecar from older installs is imported by openclaw doctor.

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. When no child task remains active, the flow finalizes as cancelled either immediately or through the maintenance sweep if children take longer to settle. The intent is persisted, so a cancelled flow stays cancelled even if the gateway restarts before all child tasks have terminated.

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>
CommandDescription
openclaw tasks flow listTracked 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 are also handled by 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 the schedule, orchestration, and reliability checks as separate layers:

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

Example cron shape:

openclaw cron 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"

Use --session session:<id> instead of isolated when the recurring workflow needs deliberate history, previous run summaries, or standing context. Use isolated when each run should start fresh and all required state is explicit in the workflow.

Inside the workflow, put 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

Recommended 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 cron so preflight failures are visible. See Scheduled Tasks.

Recommended 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 reject or mark stale items before summarization. The LLM step should receive only structured JSON and should be asked to preserve sourceUrl, retrievedAt, and asOf in its output. Use LLM Task when you need a schema-validated model step inside the workflow.

For reusable team or community workflows, package the CLI, .lobster files, and any setup notes as a skill or plugin and publish it through ClawHub. Keep workflow-specific guardrails in that package unless the plugin API is missing a needed generic capability.

How flows relate to tasks

Flows orchestrate tasks rather than substituting for them. Over its lifespan, a single flow can coordinate several background operations. Use openclaw tasks to examine specific task entries and openclaw tasks flow to review the coordinating flow.