mirror of https://github.com/openclaw/openclaw.git
110 lines
3.5 KiB
Markdown
110 lines
3.5 KiB
Markdown
---
|
|
summary: "ClawFlow workflow orchestration for background tasks and detached runs"
|
|
read_when:
|
|
- You want a flow to own one or more detached tasks
|
|
- You want to inspect or cancel a background job as a unit
|
|
- You want to understand how flows relate to tasks and background work
|
|
title: "ClawFlow"
|
|
---
|
|
|
|
# ClawFlow
|
|
|
|
ClawFlow is the flow layer above [Background Tasks](/automation/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
|
|
|
|
```bash
|
|
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.
|
|
|
|
## Related
|
|
|
|
- [Background Tasks](/automation/tasks) — detached work ledger
|
|
- [CLI: flows](/cli/flows) — flow inspection and control commands
|
|
- [Cron Jobs](/automation/cron-jobs) — scheduled jobs that may create tasks
|