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 | Cron job |
Sync modes
Managed mode
A managed flow has a controller: plugin code that creates the flow through the plugin runtime Task Flow API with a goal and a required controller id, then drives it explicitly.- Each step runs as a background task created under the flow; the flow’s owner key and requester origin carry over to child tasks.
- The controller advances the flow between
running,waiting, and terminal states, and stores arbitrary JSON step state on the flow record. - Every mutation passes the flow’s expected revision. A stale write is rejected as a revision conflict instead of clobbering newer state.
- Once cancellation is requested, new child tasks are refused, and the flow finalizes as
cancelledwhen no child task remains active.
Mirrored mode
OpenClaw creates a mirrored one-task flow automatically when a detached ACP or subagent run starts (session-scoped tasks with deliverable completion). The flow record mirrors its single backing task - status, goal, and timing - so detached spawns get a stable flow handle for status and retry surfaces without a controller. Mirrored flows show sync modetask_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 | A step finished without a usable result; blockedTaskId/summary say which |
succeeded | Completed successfully |
failed | Completed with an error |
cancelled | Cancel requested and all child tasks settled |
lost | Flow lost its authoritative backing state |
Durable state and revision tracking
Flow records persist in the shared SQLite state database (~/.openclaw/state/openclaw.sqlite, flow_runs table) alongside task records, so progress survives gateway restarts. Each write bumps the flow’s revision; concurrent writers that pass a stale expected revision get a conflict and must re-read. WAL growth is bounded 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 sets a sticky cancel intent on the flow, cancels its active child tasks, and refuses new managed child tasks. Once no child task remains active, the flow finalizes as cancelled - immediately, or via 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
| 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 |
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 such as market intelligence briefings, treat the schedule, orchestration, and reliability checks as separate layers:- Use Scheduled Tasks for timing.
- Use a persistent cron 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.
--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:
- Browser availability and profile choice, for example
openclawfor managed state oruserwhen 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, andllm-task. - Failure destination configured for cron so preflight failures are visible. See Scheduled Tasks.
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 coordinate tasks, not replace them. A single flow may drive multiple background tasks over its lifetime. Useopenclaw 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