ClawFlow: add linear flow control surface (openclaw#58227)

* ClawFlow: add linear flow control surface

* Flows: clear blocked metadata on resume

Author: mbelinky

CHANGELOG.md

@@ -25,6 +25,7 @@ Docs: https://docs.openclaw.ai
 - Flows/tasks: add a minimal SQLite-backed flow registry plus task-to-flow linkage scaffolding, so orchestrated work can start gaining a first-class parent record without changing current task delivery behavior.
 - Flows/tasks: route one-task ACP and subagent updates through a parent flow owner context, so detached work can emerge back through the intended parent thread/session instead of speaking only as a raw child task.
 - Flows/tasks: persist blocked state on one-task flows and let the same flow reopen cleanly on retry, so blocked detached work can carry a parent-level reason and continue without fragmenting into a new job.
+- ClawFlow: add the first linear flow control surface with `openclaw flows list|show|cancel`, keep manual multi-task flows separate from one-task auto-sync flows, and surface doctor recovery hints for obviously orphaned or broken flow/task linkage.
 - Matrix/history: add optional room history context for Matrix group triggers via `channels.matrix.historyLimit`, with per-agent watermarks and retry-safe snapshots so failed trigger retries do not drift into newer room messages. (#57022) thanks @chain710.
 - Diffs: skip unused viewer-versus-file SSR preload work so `diffs` view-only and file-only runs do less render work while keeping mode outputs aligned. (#57909) thanks @gumadeiras.
 - Matrix/threads: add per-DM `threadReplies` overrides and keep thread session isolation aligned with the effective room or DM thread policy from the triggering message onward. (#57995) thanks @teconomix.
@@ -33,6 +34,7 @@ Docs: https://docs.openclaw.ai
 - Slack/exec approvals: add native Slack approval routing and approver authorization so exec approval prompts can stay in Slack instead of falling back to the Web UI or terminal. Thanks @vincentkoc.
 
 ### Fixes
+
 - Image generation/build: write stable runtime alias files into `dist/` and route provider-auth runtime lookups through those aliases so image-generation providers keep resolving auth/runtime modules after rebuilds instead of crashing on missing hashed chunk files.
 - Config/runtime: pin the first successful config load in memory for the running process and refresh that snapshot on successful writes/reloads, so hot paths stop reparsing `openclaw.json` between watcher-driven swaps.
 - Config/legacy cleanup: stop probing obsolete alternate legacy config names and service labels during local config/service detection, while keeping the active `~/.openclaw/openclaw.json` path canonical.

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"

src/cli/program/register.status-health-sessions.test.ts

@@ -5,6 +5,9 @@ import { registerStatusHealthSessionsCommands } from "./register.status-health-s
 const mocks = vi.hoisted(() => ({
   statusCommand: vi.fn(),
   healthCommand: vi.fn(),
+  flowsListCommand: vi.fn(),
+  flowsShowCommand: vi.fn(),
+  flowsCancelCommand: vi.fn(),
   sessionsCommand: vi.fn(),
   sessionsCleanupCommand: vi.fn(),
   tasksListCommand: vi.fn(),
@@ -23,6 +26,9 @@ const mocks = vi.hoisted(() => ({
 
 const statusCommand = mocks.statusCommand;
 const healthCommand = mocks.healthCommand;
+const flowsListCommand = mocks.flowsListCommand;
+const flowsShowCommand = mocks.flowsShowCommand;
+const flowsCancelCommand = mocks.flowsCancelCommand;
 const sessionsCommand = mocks.sessionsCommand;
 const sessionsCleanupCommand = mocks.sessionsCleanupCommand;
 const tasksListCommand = mocks.tasksListCommand;
@@ -42,6 +48,12 @@ vi.mock("../../commands/health.js", () => ({
   healthCommand: mocks.healthCommand,
 }));
 
+vi.mock("../../commands/flows.js", () => ({
+  flowsListCommand: mocks.flowsListCommand,
+  flowsShowCommand: mocks.flowsShowCommand,
+  flowsCancelCommand: mocks.flowsCancelCommand,
+}));
+
 vi.mock("../../commands/sessions.js", () => ({
   sessionsCommand: mocks.sessionsCommand,
 }));
@@ -79,6 +91,9 @@ describe("registerStatusHealthSessionsCommands", () => {
     runtime.exit.mockImplementation(() => {});
     statusCommand.mockResolvedValue(undefined);
     healthCommand.mockResolvedValue(undefined);
+    flowsListCommand.mockResolvedValue(undefined);
+    flowsShowCommand.mockResolvedValue(undefined);
+    flowsCancelCommand.mockResolvedValue(undefined);
     sessionsCommand.mockResolvedValue(undefined);
     sessionsCleanupCommand.mockResolvedValue(undefined);
     tasksListCommand.mockResolvedValue(undefined);
@@ -317,4 +332,39 @@ describe("registerStatusHealthSessionsCommands", () => {
       runtime,
     );
   });
+
+  it("runs flows list from the parent command", async () => {
+    await runCli(["flows", "--json", "--status", "blocked"]);
+
+    expect(flowsListCommand).toHaveBeenCalledWith(
+      expect.objectContaining({
+        json: true,
+        status: "blocked",
+      }),
+      runtime,
+    );
+  });
+
+  it("runs flows show subcommand with lookup forwarding", async () => {
+    await runCli(["flows", "show", "flow-123", "--json"]);
+
+    expect(flowsShowCommand).toHaveBeenCalledWith(
+      expect.objectContaining({
+        lookup: "flow-123",
+        json: true,
+      }),
+      runtime,
+    );
+  });
+
+  it("runs flows cancel subcommand with lookup forwarding", async () => {
+    await runCli(["flows", "cancel", "flow-123"]);
+
+    expect(flowsCancelCommand).toHaveBeenCalledWith(
+      expect.objectContaining({
+        lookup: "flow-123",
+      }),
+      runtime,
+    );
+  });
 });