diff --git a/CHANGELOG.md b/CHANGELOG.md index a11bcbeb5db..c5a916fcec2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ Docs: https://docs.openclaw.ai ## Unreleased +### Breaking + +- Docs/CLI: stop documenting `openclaw flows`; use `openclaw tasks list|show|cancel` instead. Update old notes or scripts that still reference `openclaw flows`. (#58690) Thanks @neeravmakwana + ### Changes - Gateway/webchat: make `chat.history` text truncation configurable with `gateway.webchat.chatHistoryMaxChars` and per-request `maxChars`, while preserving silent-reply filtering and existing default payload limits. (#58900) @@ -70,7 +74,7 @@ Docs: https://docs.openclaw.ai - Agents/MCP: materialize bundle MCP tools with provider-safe names (`serverName__toolName`), support optional `streamable-http` transport selection plus per-server connection timeouts, and preserve real tool results from aborted/error turns unless truncation explicitly drops them. (#49505) Thanks @ziomancer. - Android/notifications: add notification-forwarding controls with package filtering, quiet hours, rate limiting, and safer picker behavior for forwarded notification events. (#40175) Thanks @nimbleenigma. - Background tasks: turn tasks into a real shared background-run control plane instead of ACP-only bookkeeping by unifying ACP, subagent, cron, and background CLI execution under one SQLite-backed ledger, routing detached lifecycle updates through the executor seam, adding audit/maintenance/status visibility, tightening auto-cleanup and lost-run recovery, improving task awareness in internal status/tool surfaces, and clarifying the split between heartbeat/main-session automation and detached scheduled runs. Thanks @mbelinky and @vincentkoc. -- Background tasks: add the first linear task 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. Thanks @mbelinky and @vincentkoc. +- Background tasks: add the first linear task flow control surface with `openclaw tasks 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. Thanks @mbelinky and @vincentkoc. - Channels/QQ Bot: add QQ Bot as a bundled channel plugin with multi-account setup, SecretRef-aware credentials, slash commands, reminders, and media send/receive support. (#52986) Thanks @sliverp. - 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. - Tasks: add a minimal SQLite-backed task 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. Thanks @mbelinky and @vincentkoc. @@ -179,7 +183,7 @@ Docs: https://docs.openclaw.ai - Agents/MCP: materialize bundle MCP tools with provider-safe names (`serverName__toolName`), support optional `streamable-http` transport selection plus per-server connection timeouts, and preserve real tool results from aborted/error turns unless truncation explicitly drops them. (#49505) Thanks @ziomancer. - Android/notifications: add notification-forwarding controls with package filtering, quiet hours, rate limiting, and safer picker behavior for forwarded notification events. (#40175) Thanks @nimbleenigma. - Background tasks: turn tasks into a real shared background-run control plane instead of ACP-only bookkeeping by unifying ACP, subagent, cron, and background CLI execution under one SQLite-backed ledger, routing detached lifecycle updates through the executor seam, adding audit/maintenance/status visibility, tightening auto-cleanup and lost-run recovery, improving task awareness in internal status/tool surfaces, and clarifying the split between heartbeat/main-session automation and detached scheduled runs. Thanks @mbelinky and @vincentkoc. -- Background tasks: add the first linear task 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. Thanks @mbelinky and @vincentkoc. +- Background tasks: add the first linear task flow control surface with `openclaw tasks 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. Thanks @mbelinky and @vincentkoc. - Channels/QQ Bot: add QQ Bot as a bundled channel plugin with multi-account setup, SecretRef-aware credentials, slash commands, reminders, and media send/receive support. (#52986) Thanks @sliverp. - 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. - Tasks: add a minimal SQLite-backed task 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. Thanks @mbelinky and @vincentkoc. diff --git a/docs/automation/clawflow.md b/docs/automation/clawflow.md index 6c3be1bd396..f1c5db74a3d 100644 --- a/docs/automation/clawflow.md +++ b/docs/automation/clawflow.md @@ -1,109 +1,50 @@ --- -summary: "ClawFlow workflow orchestration for background tasks and detached runs" +summary: "Compatibility note for older ClawFlow references in release notes and docs" 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 + - You encounter ClawFlow or openclaw flows in older release notes or docs + - You want to understand what ClawFlow terminology maps to in the current CLI + - You want to translate older flow references into the supported task commands 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. +`ClawFlow` appears in some older OpenClaw release notes and documentation as if it were a user-facing runtime with its own `openclaw flows` command 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. +That is not the current operator-facing surface in this repository. -## TL;DR +Today, the supported CLI surface for inspecting and managing detached work is [`openclaw tasks`](/automation/tasks). -- 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. +## What to use today -## Quick start +- `openclaw tasks list` shows tracked detached runs +- `openclaw tasks show ` shows one task by task id, run id, or session key +- `openclaw tasks cancel ` cancels a running task +- `openclaw tasks audit` surfaces stale or broken task runs ```bash -openclaw flows list -openclaw flows show -openclaw flows cancel +openclaw tasks list +openclaw tasks show +openclaw tasks cancel ``` -## How it relates to tasks +## What this means for older references -Background tasks still do the low-level work: +If you see `ClawFlow` or `openclaw flows` in: -- ACP runs -- subagent runs -- cron executions -- CLI-initiated runs +- old release notes +- issue threads +- stale search results +- outdated local notes -ClawFlow sits above that ledger: +translate those instructions to the current task CLI: -- 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 ` shows one flow and its linked tasks -- `openclaw flows cancel ` 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. +- `openclaw flows list` -> `openclaw tasks list` +- `openclaw flows show ` -> `openclaw tasks show ` +- `openclaw flows cancel ` -> `openclaw tasks cancel ` ## Related - [Background Tasks](/automation/tasks) — detached work ledger -- [CLI: flows](/cli/flows) — flow inspection and control commands +- [CLI: flows](/cli/flows) — compatibility note for the mistaken command name - [Cron Jobs](/automation/cron-jobs) — scheduled jobs that may create tasks diff --git a/docs/automation/index.md b/docs/automation/index.md index f738786fb30..dace088af36 100644 --- a/docs/automation/index.md +++ b/docs/automation/index.md @@ -51,19 +51,18 @@ 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 +## Older ClawFlow references -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. +Older release notes and docs may mention `ClawFlow` or `openclaw flows`, but the current CLI surface in this repo is `openclaw tasks`. -See [ClawFlow](/automation/clawflow) for the flow overview and [CLI: flows](/cli/flows) for the command surface. +See [Background Tasks](/automation/tasks) for the supported task ledger commands, plus [ClawFlow](/automation/clawflow) and [CLI: flows](/cli/flows) for compatibility notes. ## Related - [Cron vs Heartbeat](/automation/cron-vs-heartbeat) — detailed comparison guide -- [ClawFlow](/automation/clawflow) — flow-level orchestration above tasks +- [ClawFlow](/automation/clawflow) — compatibility note for older docs and release notes - [Troubleshooting](/automation/troubleshooting) — debugging automation issues - [Configuration Reference](/gateway/configuration-reference) — all config keys diff --git a/docs/automation/tasks.md b/docs/automation/tasks.md index c2c30b49bbd..d8d76fba10c 100644 --- a/docs/automation/tasks.md +++ b/docs/automation/tasks.md @@ -224,11 +224,11 @@ A sweeper runs every **60 seconds** and handles three things: ## How tasks relate to other systems -### Tasks and ClawFlow +### Tasks and older flow references -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. +Some older OpenClaw release notes and docs referred to task management as `ClawFlow` and documented an `openclaw flows` command surface. -See [ClawFlow](/automation/clawflow) for the flow overview and [CLI: flows](/cli/flows) for the command surface. +In the current codebase, the supported operator surface is `openclaw tasks`. See [ClawFlow](/automation/clawflow) and [CLI: flows](/cli/flows) for compatibility notes that map those older references to the current task commands. ### Tasks and cron @@ -253,9 +253,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 +- [ClawFlow](/automation/clawflow) — compatibility note for older docs and release notes - [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: flows](/cli/flows) — compatibility note for the mistaken command name - [CLI: Tasks](/cli/index#tasks) — CLI command reference diff --git a/docs/cli/flows.md b/docs/cli/flows.md index 6c8f0e4a7b1..667c75f5c90 100644 --- a/docs/cli/flows.md +++ b/docs/cli/flows.md @@ -1,54 +1,36 @@ --- -summary: "CLI reference for `openclaw flows` (list, inspect, cancel)" +summary: "Compatibility note for the mistakenly documented `openclaw flows` command" read_when: - - You want to inspect or cancel a flow - - You want to see how background tasks roll up into a higher-level job + - You encounter openclaw flows in older release notes, issue threads, or search results + - You want to know what command replaced openclaw flows title: "flows" --- # `openclaw flows` -Inspect and manage [ClawFlow](/automation/clawflow) jobs. +`openclaw flows` is **not** a current OpenClaw CLI command. + +Some older release notes and docs mistakenly documented a `flows` command surface. The supported operator surface is [`openclaw tasks`](/automation/tasks). ```bash -openclaw flows list -openclaw flows show -openclaw flows cancel +openclaw tasks list +openclaw tasks show +openclaw tasks cancel ``` -## Commands +## Use instead -### `flows list` +- `openclaw tasks list` — list tracked background tasks +- `openclaw tasks show ` — inspect one task by task id, run id, or session key +- `openclaw tasks cancel ` — cancel a running background task +- `openclaw tasks notify ` — change task notification behavior +- `openclaw tasks audit` — surface stale or broken task runs -List tracked flows and their task counts. +## Why this page exists -```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 -openclaw flows show --json -``` - -The output includes the flow status, current step, wait target, blocked summary when present, stored output keys, and linked tasks. - -### `flows cancel` - -Cancel a flow and any active child tasks. - -```bash -openclaw flows cancel -``` +This page stays in place so existing links from older changelog entries, issue threads, and search results have a clear correction instead of a dead end. ## Related -- [ClawFlow](/automation/clawflow) — job-level orchestration above tasks - [Background Tasks](/automation/tasks) — detached work ledger - [CLI reference](/cli/index) — full command tree diff --git a/docs/cli/index.md b/docs/cli/index.md index c69fd40484a..3754c12112b 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -45,7 +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) +- [`tasks`](/cli/index#tasks) - [`dns`](/cli/dns) - [`docs`](/cli/docs) - [`hooks`](/cli/hooks) @@ -172,10 +172,6 @@ openclaw [--dev] [--profile ] show notify cancel - flows - list - show - cancel gateway call health @@ -814,14 +810,6 @@ List and manage [background task](/automation/tasks) runs across agents. - `tasks cancel ` — 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 ` — show details for a specific flow -- `flows cancel ` — cancel a flow and its active child tasks - ## Gateway ### `gateway` diff --git a/docs/tools/lobster.md b/docs/tools/lobster.md index 58e55af97e0..8fae07459de 100644 --- a/docs/tools/lobster.md +++ b/docs/tools/lobster.md @@ -10,7 +10,7 @@ read_when: Lobster is a workflow shell that lets OpenClaw run multi-step tool sequences as a single, deterministic operation with explicit approval checkpoints. -Lobster is one authoring layer above [ClawFlow](/automation/clawflow). Lobster can decide the step logic, but ClawFlow still owns the job identity, owner context, and how detached work returns to the original conversation. +Lobster is one authoring layer above detached background work. If you run into older `ClawFlow` terminology, treat it as historical naming around the same task-oriented runtime area; the current operator-facing CLI surface is [`openclaw tasks`](/automation/tasks). ## Hook