Technical reference for the OpenClaw framework. Real-time synchronization with the official documentation engine.
Use this file to discover all available pages before exploring further.
Background tasks
note
Looking for scheduling? See [Automation and tasks](/automation) for choosing the right mechanism. This page is the activity ledger for background work, not the scheduler.
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.
note
Not every agent run creates a task. Heartbeat turns and normal interactive chat do not. All cron executions, ACP spawns, subagent spawns, and CLI agent commands do.
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
text
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.
text
openclaw tasks list
shows all tasks;
text
openclaw tasks audit
surfaces issues.
Terminal records are kept for 7 days, then automatically pruned.
Quick start
```bash}
# List all tasks (newest first)
openclaw tasks list
text
# Filter by runtime or status
openclaw tasks list --runtime acp
openclaw tasks list --status running
```
```bash}
# Show details for a specific task (by ID, run ID, or session key)
openclaw tasks show
```
```bash}
# Cancel a running task (kills the child session)
openclaw tasks cancel
text
# Change notification policy for a task
openclaw tasks notify <lookup> state_changes
```
```bash}
# Run a health audit
openclaw tasks audit
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: isolated child-session tasks use the child session; chat-backed
CLI tasks use the live run context instead, so lingering
channel/group/direct session rows do not keep them alive. Gateway-backed
text
openclaw agent
runs also finalize from their run result, so completed runs
do not sit active until the sweeper marks them
text
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
text
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
text
to
/ account from the requester session's stored route (
text
lastChannel
/
text
lastTo
/
text
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.
tip
Task completion triggers an immediate heartbeat wake so you see the result quickly — you do not have to wait for the next scheduled heartbeat tick.
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:
Policy
What is delivered
text
done_only
(default)
Only terminal state (succeeded, failed, etc.) — this is the default
text
state_changes
Every state transition and progress update
text
silent
Nothing at all
Change the policy while a task is running:
bash
openclaw tasks notify <lookup> state_changes
CLI reference
Chat task board (
text
/tasks
)
Use
text
/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,
text
/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:
text
openclaw tasks list
.
Status integration (task pressure)
text
openclaw status
includes an at-a-glance task summary:
text
Tasks: 3 queued · 2 running · 1 issues
The summary reports:
active — count of
text
queued
+
text
running
failures — count of
text
failed
+
text
timed_out
+
text
lost
byRuntime — breakdown by
text
acp
,
text
subagent
,
text
cron
,
text
cli
Both
text
/status
and the
text
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:
text
$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
text
TRUNCATE
checkpoints.
Automatic maintenance
A sweeper runs every 60 seconds and handles four things:
Reconciliation
Checks whether active tasks still have authoritative runtime backing. ACP/subagent tasks use child-session state, cron tasks use active-job ownership, and chat-backed CLI tasks use the owning run context. If that backing state is gone for more than 5 minutes, the task is marked `lost`.
ACP session repair
Closes terminal or orphaned parent-owned one-shot ACP sessions, and closes stale terminal or orphaned persistent ACP sessions only when no active conversation binding remains.
Cleanup stamping
Sets a `cleanupAfter` timestamp on terminal tasks (endedAt + 7 days). During retention, lost tasks still appear in audit as warnings; after `cleanupAfter` expires or when cleanup metadata is missing, they are errors.
Pruning
Deletes records past their `cleanupAfter` date.
note
**Retention:** terminal task records are kept for **7 days**, then automatically pruned. No configuration needed.