ClawFlow: add linear flow control surface (#58227)

* ClawFlow: add linear flow control surface

* Flows: clear blocked metadata on resume

docs/automation/clawflow.md

@@ -0,0 +1,62 @@
+---
+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.
+
+## 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
+
+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

docs/automation/index.md

@@ -51,11 +51,19 @@ The most effective setups combine multiple mechanisms:
 3. **Hooks** react to specific events (tool calls, session resets, compaction) with custom scripts.
 4. **Standing Orders** give the agent persistent context ("always check the project board before replying").
 5. **Background Tasks** automatically track all detached work so you can inspect and audit it.
+6. **ClawFlow** groups related detached tasks into a single flow when the work needs a higher-level job view.
 
 See [Cron vs Heartbeat](/automation/cron-vs-heartbeat) for a detailed comparison of the two scheduling mechanisms.
 
+## ClawFlow
+
+ClawFlow sits above [Background Tasks](/automation/tasks). Tasks still track the detached runs, while ClawFlow groups related task runs into one job that you can inspect or cancel from the CLI.
+
+See [ClawFlow](/automation/clawflow) for the flow overview and [CLI: flows](/cli/flows) for the command surface.
+
 ## Related
 
 - [Cron vs Heartbeat](/automation/cron-vs-heartbeat) — detailed comparison guide
+- [ClawFlow](/automation/clawflow) — flow-level orchestration above tasks
 - [Troubleshooting](/automation/troubleshooting) — debugging automation issues
 - [Configuration Reference](/gateway/configuration-reference) — all config keys

docs/automation/tasks.md

@@ -210,6 +210,12 @@ A sweeper runs every **60 seconds** and handles three things:
 
 ## How tasks relate to other systems
 
+### Tasks and ClawFlow
+
+ClawFlow is the flow layer above tasks. A flow groups one or more task runs into a single job, owns the parent session context, and gives you a higher-level control surface for blocked or multi-step work.
+
+See [ClawFlow](/automation/clawflow) for the flow overview and [CLI: flows](/cli/flows) for the command surface.
+
 ### Tasks and cron
 
 A cron job **definition** lives in `~/.openclaw/cron/jobs.json`. **Every** cron execution creates a task record — both main-session and isolated. Main-session cron tasks default to `silent` notify policy so they track without generating notifications.
@@ -233,7 +239,9 @@ A task's `runId` links to the agent run doing the work. Agent lifecycle events (
 ## Related
 
 - [Automation Overview](/automation) — all automation mechanisms at a glance
+- [ClawFlow](/automation/clawflow) — job-level orchestration above tasks
 - [Cron Jobs](/automation/cron-jobs) — scheduling background work
 - [Cron vs Heartbeat](/automation/cron-vs-heartbeat) — choosing the right mechanism
 - [Heartbeat](/gateway/heartbeat) — periodic main-session turns
+- [CLI: flows](/cli/flows) — flow inspection and control commands
 - [CLI: Tasks](/cli/index#tasks) — CLI command reference

docs/cli/flows.md

@@ -0,0 +1,54 @@
+---
+summary: "CLI reference for `openclaw flows` (list, inspect, cancel)"
+read_when:
+  - You want to inspect or cancel a flow
+  - You want to see how background tasks roll up into a higher-level job
+title: "flows"
+---
+
+# `openclaw flows`
+
+Inspect and manage [ClawFlow](/automation/clawflow) jobs.
+
+```bash
+openclaw flows list
+openclaw flows show <lookup>
+openclaw flows cancel <lookup>
+```
+
+## Commands
+
+### `flows list`
+
+List tracked flows and their task counts.
+
+```bash
+openclaw flows list
+openclaw flows list --status blocked
+openclaw flows list --json
+```
+
+### `flows show`
+
+Show one flow by flow id or owner session key.
+
+```bash
+openclaw flows show <lookup>
+openclaw flows show <lookup> --json
+```
+
+The output includes the flow status, current step, blocked summary when present, and linked tasks.
+
+### `flows cancel`
+
+Cancel a flow and any active child tasks.
+
+```bash
+openclaw flows cancel <lookup>
+```
+
+## Related
+
+- [ClawFlow](/automation/clawflow) — job-level orchestration above tasks
+- [Background Tasks](/automation/tasks) — detached work ledger
+- [CLI reference](/cli/index) — full command tree

docs/cli/index.md

@@ -45,6 +45,7 @@ This page describes the current CLI behavior. If commands change, update this do
 - [`tui`](/cli/tui)
 - [`browser`](/cli/browser)
 - [`cron`](/cli/cron)
+- [`flows`](/cli/flows)
 - [`dns`](/cli/dns)
 - [`docs`](/cli/docs)
 - [`hooks`](/cli/hooks)
@@ -171,6 +172,10 @@ openclaw [--dev] [--profile <name>] <command>
     show
     notify
     cancel
+  flows
+    list
+    show
+    cancel
   gateway
     call
     health
@@ -809,6 +814,14 @@ List and manage [background task](/automation/tasks) runs across agents.
 - `tasks cancel <id>` — cancel a running task
 - `tasks audit` — surface operational issues (stale, lost, delivery failures)
 
+### `flows`
+
+List and manage [ClawFlow](/automation/clawflow) jobs across agents.
+
+- `flows list` — show active and recent flows
+- `flows show <id>` — show details for a specific flow
+- `flows cancel <id>` — cancel a flow and its active child tasks
+
 ## Gateway
 
 ### `gateway`

docs/docs.json

@@ -1121,6 +1121,7 @@
                   "automation/cron-jobs",
                   "automation/cron-vs-heartbeat",
                   "automation/tasks",
+                  "automation/clawflow",
                   "automation/troubleshooting",
                   "automation/webhook",
                   "automation/gmail-pubsub",
@@ -1432,6 +1433,7 @@
                       "cli/approvals",
                       "cli/browser",
                       "cli/cron",
+                      "cli/flows",
                       "cli/node",
                       "cli/nodes",
                       "cli/sandbox"