openclaw/docs/cli/tasks.md

summary, read_when, title

summary	read_when	title
CLI reference for `openclaw tasks` (background task ledger and Task Flow state)	You want to inspect, audit, or cancel background task records You are documenting Task Flow commands under `openclaw tasks flow`	`openclaw tasks`

Inspect durable background tasks and Task Flow state. With no subcommand, openclaw tasks is equivalent to openclaw tasks list.

See Background Tasks for the lifecycle and delivery model.

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

• --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 newest first.

show

openclaw tasks show <lookup> [--json]

Shows one task by task ID, run ID, or session key.

notify

openclaw tasks notify <lookup> <done_only|state_changes|silent>

Changes the notification policy for a running task.

cancel

openclaw tasks cancel <lookup>

Cancels a running background task.

audit

openclaw tasks audit [--severity <warn|error>] [--code <name>] [--limit <n>] [--json]

Surfaces stale, lost, delivery-failed, or otherwise inconsistent task and Task Flow records. Lost tasks retained until cleanupAfter are warnings; expired or unstamped lost tasks are errors.

maintenance

openclaw tasks maintenance [--apply] [--json]

Previews or applies task and Task Flow reconciliation, cleanup stamping, and pruning. For cron tasks, reconciliation uses persisted run logs/job state before marking an old active task lost, so completed cron runs do not become false audit errors just 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.

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.

Related

• CLI reference
• Background tasks