Task Flow

Task Flow

Task Flow is the flow orchestration substrate that sits above background tasks. It manages durable multi-step flows with their own state, revision tracking, and sync semantics while individual tasks remain the unit of detached work.

When to use Task Flow

Use Task Flow when work spans multiple sequential or branching steps and you need durable progress tracking across gateway restarts. For single background operations, a plain task is sufficient.

Scenario	Use
Single background job	Plain task
Multi-step pipeline (A then B then C)	Task Flow (managed)
Observe externally created tasks	Task Flow (mirrored)
One-shot reminder	Cron job

Sync modes

Managed mode

Task Flow owns the lifecycle end-to-end. It creates tasks as flow steps, drives them to completion, and advances the flow state automatically.

Example: a weekly report flow that (1) gathers data, (2) generates the report, and (3) delivers it. Task Flow creates each step as a background task, waits for completion, then moves to the next 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

Task Flow observes externally created tasks and keeps flow state in sync without taking ownership of task creation. This is useful when tasks originate from cron jobs, CLI commands, or other sources and you want a unified view of their progress as a flow.

Example: three independent cron jobs that together form a “morning ops” routine. A mirrored flow tracks their collective progress without controlling when or how they run.

Durable state and revision tracking

Each flow persists its own state and tracks revisions so progress survives gateway restarts. Revision tracking enables conflict detection when multiple sources attempt to advance the same flow concurrently.

Cancel behavior

openclaw tasks flow cancel sets a sticky cancel intent on the flow. Active tasks within the flow are cancelled, and no new steps are started. The cancel intent persists across restarts, 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

# Show details for a specific flow
openclaw tasks flow show <lookup>

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

Command	Description
openclaw tasks flow list	Shows tracked flows with status and sync mode
openclaw tasks flow show <id>	Inspect one flow by flow id or lookup key
openclaw tasks flow cancel <id>	Cancel a running flow and its active tasks

How flows relate to tasks

Flows coordinate tasks, not replace them. A single flow may drive multiple background tasks over its lifetime. Use openclaw tasks to inspect individual task records and openclaw tasks flow to inspect the orchestrating flow.

Related

• 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
• Cron Jobs — scheduled jobs that may feed into flows