openclaw tasks CLI reference for background task management
Reference for the openclaw tasks command, which lists and manages durable background tasks and Task Flow state. Covers subcommands list, show, notify, and cancel with filtering options.
Read this when
- You want to inspect, audit, or cancel background task records
- You are documenting Task Flow commands under `openclaw tasks flow`
Review durable background tasks and Task Flow state. Without a subcommand,
openclaw tasks behaves the same as openclaw tasks list.
Refer to Background Tasks for lifecycle and delivery
details, and its tasks audit section for complete finding descriptions.
Usage
openclaw tasks
openclaw tasks list
openclaw tasks list --runtime acp
openclaw tasks list --status running
openclaw tasks show <lookup>
openclaw tasks notify <lookup> state_changes
openclaw tasks cancel <lookup>
openclaw tasks audit
openclaw tasks maintenance
openclaw tasks maintenance --apply
openclaw tasks flow list
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>
Root Options
| Flag | Description |
|---|---|
--json | Output JSON. |
--runtime <name> | Filter by kind: subagent, acp, cron, or cli. |
--status <name> | Filter by status: queued, running, succeeded, failed, timed_out, cancelled, or lost. |
Subcommands
list
openclaw tasks list [--runtime <name>] [--status <name>] [--json]
Lists tracked background tasks with newest entries first.
show
openclaw tasks show <lookup> [--json]
Displays a single task by task ID, run ID, or session key.
notify
openclaw tasks notify <lookup> <done_only|state_changes|silent>
Modifies the notification policy for a task that is currently running.
cancel
openclaw tasks cancel <lookup>
Stops a running background task.
audit
openclaw tasks audit [--severity <warn|error>] [--code <name>] [--limit <n>] [--json]
Flags stale, lost, delivery-failed, or otherwise inconsistent task and
Task Flow records. Lost tasks kept until cleanupAfter are warnings;
expired or unstamped lost tasks are errors.
--code accepts task codes (stale_queued, stale_running, lost,
delivery_failed, missing_cleanup, inconsistent_timestamps) and Task
Flow codes (restore_failed, stale_waiting, stale_blocked,
cancel_stuck, missing_linked_tasks, blocked_task_missing). See
Background Tasks for severity and trigger details per
code.
maintenance
openclaw tasks maintenance [--apply] [--json]
Previews or applies task and Task Flow reconciliation, cleanup stamping, pruning, and stale cron run session registry cleanup.
For cron tasks, reconciliation uses persisted run logs and job state before
marking an old active task lost, so completed cron runs do not become
false audit errors simply because the in-memory Gateway runtime state is gone.
Offline CLI audit is not authoritative for the Gateway's process-local cron
active-job set. CLI tasks with a run ID or source ID are marked lost when
their live Gateway run context is missing, even if an old child-session row
remains.
When applied, maintenance also prunes cron:<jobId>:run:<uuid> session
registry rows older than 7 days while preserving currently running cron
jobs and leaving non-cron session rows unchanged.
flow
openclaw tasks flow list [--status <name>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
Inspects or cancels durable Task Flow state under the task ledger.
flow list --status accepts queued, running, waiting, blocked,
succeeded, failed, cancelled, or lost.