Background tasks

Background tasks track work that runs outside your main conversation session: ACP runs, subagent spawns, isolated cron job executions, and CLI-initiated operations.

Tasks do not replace sessions, cron jobs, or heartbeats - they are the activity ledger that records what detached work happened, when, and whether it succeeded.

# TL;DR

• Tasks are records, not schedulers - cron and heartbeat decide when work runs, tasks track what happened.
• ACP, subagents, all cron jobs, and CLI operations create tasks. Heartbeat turns do not.
• Each task moves through queued → running → terminal (succeeded, failed, timed_out, cancelled, or lost).
• Cron tasks stay live while the cron runtime still owns the job; if the in-memory runtime state is gone, task maintenance first checks durable cron run history before marking a task lost.
• Completion is push-driven: detached work can notify directly or wake the requester session/heartbeat when it finishes, so status polling loops are usually the wrong shape.
• Isolated cron runs and subagent completions best-effort clean up tracked browser tabs/processes for their child session before final cleanup bookkeeping.
• Isolated cron delivery suppresses stale interim parent replies while descendant subagent work is still draining, and it prefers final descendant output when that arrives before delivery.
• Completion notifications are delivered directly to a channel or queued for the next heartbeat.
• openclaw tasks list shows all tasks; openclaw tasks audit surfaces issues.
• Terminal records are kept for 7 days, then automatically pruned.

# Quick start

# List all tasks (newest first)
openclaw tasks list

# Filter by runtime or status
openclaw tasks list --runtime acp
openclaw tasks list --status running

# Show details for a specific task (by ID, run ID, or session key)
openclaw tasks show <lookup>

# Cancel a running task (kills the child session)
openclaw tasks cancel <lookup>

# Change notification policy for a task
openclaw tasks notify <lookup> state_changes

# Run a health audit
openclaw tasks audit

# Preview or apply maintenance
openclaw tasks maintenance
openclaw tasks maintenance --apply

# Inspect TaskFlow state
openclaw tasks flow list
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>

# What creates a task

# Task lifecycle

stateDiagram-v2
    [*] --> queued
    queued --> running : agent starts
    running --> succeeded : completes ok
    running --> failed : error
    running --> timed_out : timeout exceeded
    running --> cancelled : operator cancels
    queued --> lost : session gone > 5 min
    running --> lost : session gone > 5 min

Transitions happen automatically - when the associated agent run ends, the task status updates to match.

Agent run completion is authoritative for active task records. A successful detached run finalizes as succeeded, ordinary run errors finalize as failed, and timeout or abort outcomes finalize as timed_out. If an operator already cancelled the task, or the runtime already recorded a stronger terminal state such as failed, timed_out, or lost, a later success signal does not downgrade that terminal status.

lost is runtime-aware:

• ACP tasks: backing ACP child session metadata disappeared.
• Subagent tasks: backing child session disappeared from the target agent store.
• Cron tasks: the cron runtime no longer tracks the job as active and durable cron run history does not show a terminal result for that run. Offline CLI audit does not treat its own empty in-process cron runtime state as authority.
• CLI tasks: tasks with a run id/source id use the live run context, so lingering child-session or chat-session rows do not keep them alive after the gateway-owned run disappears. Legacy CLI tasks without run identity still fall back to the child session. Gateway-backed openclaw agent runs also finalize from their run result, so completed runs do not sit active until the sweeper marks them lost.

# Delivery and notifications

When a task reaches a terminal state, OpenClaw notifies you. There are two delivery paths:

Direct delivery - if the task has a channel target (the requesterOrigin), the completion message goes straight to that channel (Telegram, Discord, Slack, etc.). For subagent completions, OpenClaw also preserves bound thread/topic routing when available and can fill a missing to / account from the requester session's stored route (lastChannel / lastTo / lastAccountId) before giving up on direct delivery.

Session-queued delivery - if direct delivery fails or no origin is set, the update is queued as a system event in the requester's session and surfaces on the next heartbeat.

That means the usual workflow is push-based: start detached work once, then let the runtime wake or notify you on completion. Poll task state only when you need debugging, intervention, or an explicit audit.

# Notification policies

Control how much you hear about each task:

Change the policy while a task is running:

openclaw tasks notify <lookup> state_changes

# CLI reference

openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]

openclaw tasks show <lookup>

openclaw tasks cancel <lookup>

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

openclaw tasks audit [--json]

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

openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>

# Chat task board (/tasks)

Use /tasks in any chat session to see background tasks linked to that session. The board shows active and recently completed tasks with runtime, status, timing, and progress or error detail.

When the current session has no visible linked tasks, /tasks falls back to agent-local task counts so you still get an overview without leaking other-session details.

For the full operator ledger, use the CLI: openclaw tasks list.

# Status integration (task pressure)

openclaw status includes an at-a-glance task summary:

Tasks: 3 queued · 2 running · 1 issues

The summary reports:

• active - count of queued + running
• failures - count of failed + timed_out + lost
• byRuntime - breakdown by acp, subagent, cron, cli

Both /status and the session_status tool use a cleanup-aware task snapshot: active tasks are preferred, stale completed rows are hidden, and recent failures only surface when no active work remains. This keeps the status card focused on what matters right now.

# Storage and maintenance

# Where tasks live

Task records persist in SQLite at:

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

The registry loads into memory at gateway start and syncs writes to SQLite for durability across restarts. The Gateway keeps the SQLite write-ahead log bounded by using SQLite's default autocheckpoint threshold plus periodic and shutdown TRUNCATE checkpoints.

# Automatic maintenance

A sweeper runs every 60 seconds and handles four things:

# How tasks relate to other systems

# Related

• Automation & Tasks - all automation mechanisms at a glance
• CLI: Tasks - CLI command reference
• Heartbeat - periodic main-session turns
• Scheduled Tasks - scheduling background work
• Task Flow - flow orchestration above tasks