diff --git a/docs/automation/tasks.md b/docs/automation/tasks.md index 8ed002df224..3c226f6b190 100644 --- a/docs/automation/tasks.md +++ b/docs/automation/tasks.md @@ -5,12 +5,14 @@ read_when: - Debugging delivery failures for detached agent runs - Understanding how background runs relate to sessions, cron, and heartbeat title: "Background tasks" +sidebarTitle: "Background tasks" --- -> **Looking for scheduling?** See [Automation & Tasks](/automation) for choosing the right mechanism. This page covers **tracking** background work, not scheduling it. + +Looking for scheduling? See [Automation & Tasks](/automation) for choosing the right mechanism. This page covers **tracking** background work, not scheduling it. + -Background tasks track work that runs **outside your main conversation session**: -ACP runs, subagent spawns, isolated cron job executions, and CLI-initiated operations. +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. @@ -24,48 +26,63 @@ Not every agent run creates a task. Heartbeat turns and normal interactive chat - 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; chat-backed CLI tasks stay live only while their owning run context is still active. -- 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. +- 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. +- 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 -```bash -# List all tasks (newest first) -openclaw tasks list + + + ```bash + # List all tasks (newest first) + openclaw tasks list -# Filter by runtime or status -openclaw tasks list --runtime acp -openclaw tasks list --status running + # 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 + + + ```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 -# Cancel a running task (kills the child session) -openclaw tasks cancel + # Change notification policy for a task + openclaw tasks notify state_changes + ``` -# Change notification policy for a task -openclaw tasks notify state_changes + + + ```bash + # Run a health audit + openclaw tasks audit -# Run a health audit -openclaw tasks audit + # Preview or apply maintenance + openclaw tasks maintenance + openclaw tasks maintenance --apply + ``` -# Preview or apply maintenance -openclaw tasks maintenance -openclaw tasks maintenance --apply - -# Inspect TaskFlow state -openclaw tasks flow list -openclaw tasks flow show -openclaw tasks flow cancel -``` + + + ```bash + # Inspect TaskFlow state + openclaw tasks flow list + openclaw tasks flow show + openclaw tasks flow cancel + ``` + + ## What creates a task @@ -77,17 +94,22 @@ openclaw tasks flow cancel | CLI operations | `cli` | `openclaw agent` commands that run through the gateway | `silent` | | Agent media jobs | `cli` | Session-backed `video_generate` runs | `silent` | -Main-session cron tasks use `silent` notify policy by default — they create records for tracking but do not generate notifications. Isolated cron tasks also default to `silent` but are more visible because they run in their own session. + + + Main-session cron tasks use `silent` notify policy by default — they create records for tracking but do not generate notifications. Isolated cron tasks also default to `silent` but are more visible because they run in their own session. -Session-backed `video_generate` runs also use `silent` notify policy. They still create task records, but completion is handed back to the original agent session as an internal wake so the agent can write the follow-up message and attach the finished video itself. If you opt into `tools.media.asyncCompletion.directSend`, async `music_generate` and `video_generate` completions try direct channel delivery first before falling back to the requester-session wake path. + Session-backed `video_generate` runs also use `silent` notify policy. They still create task records, but completion is handed back to the original agent session as an internal wake so the agent can write the follow-up message and attach the finished video itself. If you opt into `tools.media.asyncCompletion.directSend`, async `music_generate` and `video_generate` completions try direct channel delivery first before falling back to the requester-session wake path. -While a session-backed `video_generate` task is still active, the tool also acts as a guardrail: repeated `video_generate` calls in that same session return the active task status instead of starting a second concurrent generation. Use `action: "status"` when you want an explicit progress/status lookup from the agent side. - -**What does not create tasks:** - -- Heartbeat turns — main-session; see [Heartbeat](/gateway/heartbeat) -- Normal interactive chat turns -- Direct `/command` responses + + + While a session-backed `video_generate` task is still active, the tool also acts as a guardrail: repeated `video_generate` calls in that same session return the active task status instead of starting a second concurrent generation. Use `action: "status"` when you want an explicit progress/status lookup from the agent side. + + + - Heartbeat turns — main-session; see [Heartbeat](/gateway/heartbeat) + - Normal interactive chat turns + - Direct `/command` responses + + ## Task lifecycle @@ -115,23 +137,14 @@ stateDiagram-v2 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. +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. -- 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 - `openclaw agent` runs also finalize from their run result, so completed runs - do not sit active until the sweeper marks them `lost`. +- 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 `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 @@ -145,9 +158,7 @@ When a task reaches a terminal state, OpenClaw notifies you. There are two deliv 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. +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 @@ -167,96 +178,93 @@ openclaw tasks notify state_changes ## CLI reference -### `tasks list` + + + ```bash + openclaw tasks list [--runtime ] [--status ] [--json] + ``` -```bash -openclaw tasks list [--runtime ] [--status ] [--json] -``` + Output columns: Task ID, Kind, Status, Delivery, Run ID, Child Session, Summary. -Output columns: Task ID, Kind, Status, Delivery, Run ID, Child Session, Summary. + + + ```bash + openclaw tasks show + ``` -### `tasks show` + The lookup token accepts a task ID, run ID, or session key. Shows the full record including timing, delivery state, error, and terminal summary. -```bash -openclaw tasks show -``` + + + ```bash + openclaw tasks cancel + ``` -The lookup token accepts a task ID, run ID, or session key. Shows the full record including timing, delivery state, error, and terminal summary. + For ACP and subagent tasks, this kills the child session. For CLI-tracked tasks, cancellation is recorded in the task registry (there is no separate child runtime handle). Status transitions to `cancelled` and a delivery notification is sent when applicable. -### `tasks cancel` + + + ```bash + openclaw tasks notify + ``` + + + ```bash + openclaw tasks audit [--json] + ``` -```bash -openclaw tasks cancel -``` + Surfaces operational issues. Findings also appear in `openclaw status` when issues are detected. -For ACP and subagent tasks, this kills the child session. For CLI-tracked tasks, cancellation is recorded in the task registry (there is no separate child runtime handle). Status transitions to `cancelled` and a delivery notification is sent when applicable. + | Finding | Severity | Trigger | + | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ | + | `stale_queued` | warn | Queued for more than 10 minutes | + | `stale_running` | error | Running for more than 30 minutes | + | `lost` | warn/error | Runtime-backed task ownership disappeared; retained lost tasks warn until `cleanupAfter`, then become errors | + | `delivery_failed` | warn | Delivery failed and notify policy is not `silent` | + | `missing_cleanup` | warn | Terminal task with no cleanup timestamp | + | `inconsistent_timestamps` | warn | Timeline violation (for example ended before started) | -### `tasks notify` + + + ```bash + openclaw tasks maintenance [--json] + openclaw tasks maintenance --apply [--json] + ``` -```bash -openclaw tasks notify -``` + Use this to preview or apply reconciliation, cleanup stamping, and pruning for tasks and Task Flow state. -### `tasks audit` + Reconciliation is runtime-aware: -```bash -openclaw tasks audit [--json] -``` + - ACP/subagent tasks check their backing child session. + - Cron tasks check whether the cron runtime still owns the job. + - Chat-backed CLI tasks check the owning live run context, not just the chat session row. -Surfaces operational issues. Findings also appear in `openclaw status` when issues are detected. + Completion cleanup is also runtime-aware: -| Finding | Severity | Trigger | -| ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ | -| `stale_queued` | warn | Queued for more than 10 minutes | -| `stale_running` | error | Running for more than 30 minutes | -| `lost` | warn/error | Runtime-backed task ownership disappeared; retained lost tasks warn until `cleanupAfter`, then become errors | -| `delivery_failed` | warn | Delivery failed and notify policy is not `silent` | -| `missing_cleanup` | warn | Terminal task with no cleanup timestamp | -| `inconsistent_timestamps` | warn | Timeline violation (for example ended before started) | + - Subagent completion best-effort closes tracked browser tabs/processes for the child session before announce cleanup continues. + - Isolated cron completion best-effort closes tracked browser tabs/processes for the cron session before the run fully tears down. + - Isolated cron delivery waits out descendant subagent follow-up when needed and suppresses stale parent acknowledgement text instead of announcing it. + - Subagent completion delivery prefers the latest visible assistant text; if that is empty it falls back to sanitized latest tool/toolResult text, and timeout-only tool-call runs can collapse to a short partial-progress summary. Terminal failed runs announce failure status without replaying captured reply text. + - Cleanup failures do not mask the real task outcome. -### `tasks maintenance` + + + ```bash + openclaw tasks flow list [--status ] [--json] + openclaw tasks flow show [--json] + openclaw tasks flow cancel + ``` -```bash -openclaw tasks maintenance [--json] -openclaw tasks maintenance --apply [--json] -``` + Use these when the orchestrating Task Flow is the thing you care about rather than one individual background task record. -Use this to preview or apply reconciliation, cleanup stamping, and pruning for -tasks and Task Flow state. - -Reconciliation is runtime-aware: - -- ACP/subagent tasks check their backing child session. -- Cron tasks check whether the cron runtime still owns the job. -- Chat-backed CLI tasks check the owning live run context, not just the chat session row. - -Completion cleanup is also runtime-aware: - -- Subagent completion best-effort closes tracked browser tabs/processes for the child session before announce cleanup continues. -- Isolated cron completion best-effort closes tracked browser tabs/processes for the cron session before the run fully tears down. -- Isolated cron delivery waits out descendant subagent follow-up when needed and - suppresses stale parent acknowledgement text instead of announcing it. -- Subagent completion delivery prefers the latest visible assistant text; if that is empty it falls back to sanitized latest tool/toolResult text, and timeout-only tool-call runs can collapse to a short partial-progress summary. Terminal failed runs announce failure status without replaying captured reply text. -- Cleanup failures do not mask the real task outcome. - -### `tasks flow list|show|cancel` - -```bash -openclaw tasks flow list [--status ] [--json] -openclaw tasks flow show [--json] -openclaw tasks flow cancel -``` - -Use these when the orchestrating Task Flow is the thing you care about rather -than one individual background task record. + + ## 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. +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. +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`. @@ -274,9 +282,7 @@ The summary reports: - **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. +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 @@ -294,44 +300,55 @@ The registry loads into memory at gateway start and syncs writes to SQLite for d A sweeper runs every **60 seconds** and handles three things: -1. **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`. -2. **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. -3. **Pruning** — deletes records past their `cleanupAfter` date. + + + 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`. + + + 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. + + + Deletes records past their `cleanupAfter` date. + + -**Retention**: terminal task records are kept for **7 days**, then automatically pruned. No configuration needed. + +**Retention:** terminal task records are kept for **7 days**, then automatically pruned. No configuration needed. + ## How tasks relate to other systems -### Tasks and Task Flow + + + [Task Flow](/automation/taskflow) is the flow orchestration layer above background tasks. A single flow may coordinate multiple tasks over its lifetime using managed or mirrored sync modes. Use `openclaw tasks` to inspect individual task records and `openclaw tasks flow` to inspect the orchestrating flow. -[Task Flow](/automation/taskflow) is the flow orchestration layer above background tasks. A single flow may coordinate multiple tasks over its lifetime using managed or mirrored sync modes. Use `openclaw tasks` to inspect individual task records and `openclaw tasks flow` to inspect the orchestrating flow. + See [Task Flow](/automation/taskflow) for details. -See [Task Flow](/automation/taskflow) for details. + + + A cron job **definition** lives in `~/.openclaw/cron/jobs.json`; runtime execution state lives beside it in `~/.openclaw/cron/jobs-state.json`. **Every** cron execution creates a task record — both main-session and isolated. Main-session cron tasks default to `silent` notify policy so they track without generating notifications. -### Tasks and cron + See [Cron Jobs](/automation/cron-jobs). -A cron job **definition** lives in `~/.openclaw/cron/jobs.json`; runtime execution state lives beside it in `~/.openclaw/cron/jobs-state.json`. **Every** cron execution creates a task record — both main-session and isolated. Main-session cron tasks default to `silent` notify policy so they track without generating notifications. + + + Heartbeat runs are main-session turns — they do not create task records. When a task completes, it can trigger a heartbeat wake so you see the result promptly. -See [Cron Jobs](/automation/cron-jobs). + See [Heartbeat](/gateway/heartbeat). -### Tasks and heartbeat - -Heartbeat runs are main-session turns — they do not create task records. When a task completes, it can trigger a heartbeat wake so you see the result promptly. - -See [Heartbeat](/gateway/heartbeat). - -### Tasks and sessions - -A task may reference a `childSessionKey` (where work runs) and a `requesterSessionKey` (who started it). Sessions are conversation context; tasks are activity tracking on top of that. - -### Tasks and agent runs - -A task's `runId` links to the agent run doing the work. Agent lifecycle events (start, end, error) automatically update the task status — you do not need to manage the lifecycle manually. + + + A task may reference a `childSessionKey` (where work runs) and a `requesterSessionKey` (who started it). Sessions are conversation context; tasks are activity tracking on top of that. + + + A task's `runId` links to the agent run doing the work. Agent lifecycle events (start, end, error) automatically update the task status — you do not need to manage the lifecycle manually. + + ## Related - [Automation & Tasks](/automation) — all automation mechanisms at a glance -- [Task Flow](/automation/taskflow) — flow orchestration above tasks -- [Scheduled Tasks](/automation/cron-jobs) — scheduling background work -- [Heartbeat](/gateway/heartbeat) — periodic main-session turns - [CLI: Tasks](/cli/tasks) — CLI command reference +- [Heartbeat](/gateway/heartbeat) — periodic main-session turns +- [Scheduled Tasks](/automation/cron-jobs) — scheduling background work +- [Task Flow](/automation/taskflow) — flow orchestration above tasks