Skip to main content

​
ClawFlow

ClawFlow is the flow layer above Background Tasks. Tasks still track detached work. ClawFlow groups those task runs into a single job, keeps the parent owner context, and gives you a flow-level control surface. Use ClawFlow when the work is more than a single detached run. A flow can still be one task, but it can also coordinate multiple tasks in a simple linear sequence.

​
TL;DR

  • Tasks are the execution records.
  • ClawFlow is the job-level wrapper above tasks.
  • A flow keeps one owner/session context for the whole job.
  • Use openclaw flows list, openclaw flows show, and openclaw flows cancel to inspect or manage flows.

​
Quick start

openclaw flows list
openclaw flows show <flow-id-or-owner-session>
openclaw flows cancel <flow-id-or-owner-session>

​
How it relates to tasks

Background tasks still do the low-level work:
  • ACP runs
  • subagent runs
  • cron executions
  • CLI-initiated runs
ClawFlow sits above that ledger:
  • it keeps related task runs under one flow id
  • it tracks the flow state separately from the individual task state
  • it makes blocked or multi-step work easier to inspect from one place
For a single detached run, the flow can be a one-task flow. For more structured work, ClawFlow can keep multiple task runs under the same job.

​
Runtime substrate

ClawFlow is the runtime substrate, not a workflow language. It owns:
  • the flow id
  • the owner session and return context
  • waiting state
  • small persisted outputs
  • finish, fail, cancel, and blocked state
It does not own branching or business logic. Put that in the authoring layer that sits above it:
  • Lobster
  • acpx
  • plain TypeScript helpers
  • bundled skills
In practice, authoring layers target a small runtime surface:
  • createFlow(...)
  • runTaskInFlow(...)
  • setFlowWaiting(...)
  • setFlowOutput(...)
  • appendFlowOutput(...)
  • emitFlowUpdate(...)
  • resumeFlow(...)
  • finishFlow(...)
  • failFlow(...)
That keeps flow ownership and return-to-thread behavior in core without forcing a single DSL on top of it.

​
Authoring pattern

The intended shape is linear:
  1. Create one flow for the job.
  2. Run one detached task under that flow.
  3. Wait for the child task or outside event.
  4. Resume the flow in the caller.
  5. Spawn the next child task or finish.
ClawFlow persists the minimal state needed to resume that job: the current step, the task it is waiting on, and a small output bag for handoff between steps.

​
CLI surface

The flow CLI is intentionally small:
  • openclaw flows list shows active and recent flows
  • openclaw flows show <lookup> shows one flow and its linked tasks
  • openclaw flows cancel <lookup> cancels the flow and any active child tasks
flows show also surfaces the current wait target and any stored output keys, which is often enough to answer “what is this job waiting on?” without digging into every child task. The lookup token accepts either a flow id or the owner session key.