OpenClaw tasks capability specification

Overview

OpenClaw tasks give operators, agents, and trusted clients a shared record of background work that continues outside the immediate conversation. The capability helps people answer what is running, what finished, what failed, what needs attention, and where completion should be reported, without turning the task system into the scheduler or executor for that work.

Users and actors

Operator: a person responsible for inspecting, debugging, cancelling, or cleaning up background work.
Chat user: a person asking the assistant to show current background activity from a conversation.
Agent: an assistant process that can start delegated work, receive completion events, or report status.
Scheduler: a system actor that starts work at a configured time and reports each run outcome.
Delegation runner: a system actor that performs work in a child context and reports lifecycle changes.
Trusted client: an approved application that needs task summaries, details, or cancellation controls.
Plugin: an extension that needs owner-scoped visibility into its own background work.

Capabilities

Background work visibility

Users can see detached work as a durable activity record: Description: When supported background work starts, the product records what work began, who owns it, where it belongs, its current state, recent progress, and its eventual outcome.; Inputs required: A background work request from a supported source, a human-readable task description, ownership context, and any available run or session identity.; Observable outcomes: The work appears in operator and status views with current state, timing, owner, and summary information.; Acceptance criteria: A scheduled run, delegated run, command-backed run, or media generation run creates one visible task record; records can be read after the initiating interaction has ended; records include enough information to correlate work with its owner.
Users can understand the current state of background work: Description: Each task reports whether it is waiting, actively running, completed, failed, timed out, cancelled, or lost.; Inputs required: Lifecycle updates from the actor that owns the work.; Observable outcomes: Status views and task details show a clear, current state and relevant timing.; Acceptance criteria: Running work becomes active; successful work becomes complete; errors and timeouts are represented distinctly; a stronger terminal state is not replaced by a later lower-confidence success update.
Users can distinguish task tracking from scheduling: Description: The task capability records what happened to background work without deciding when scheduled work should start.; Inputs required: A task-producing actor that already owns the work lifecycle.; Observable outcomes: Scheduled jobs keep their own timing behavior while task views show individual run activity.; Acceptance criteria: Creating a task record does not by itself schedule new work; every scheduled execution can still create a task record for visibility.

Operator inspection and control

Operators can list and filter task records: Description: Operators can view recent background work and narrow the view by work kind or status.; Inputs required: Optional kind and status filters.; Observable outcomes: The operator receives a newest-first list with task identifiers, status, delivery state, run correlation, and summary text.; Acceptance criteria: No-filter listing shows all visible records; kind filtering excludes other kinds; status filtering excludes other statuses; an empty result clearly says no tasks matched.
Operators can inspect a single task: Description: Operators can retrieve full detail for one background work record using a task, run, or session lookup.; Inputs required: A lookup value that identifies the task, run, or related session.; Observable outcomes: The operator sees status, delivery policy, ownership, timing, progress, error, terminal summary, and cleanup timing when present.; Acceptance criteria: Valid lookups return one matching record; invalid lookups fail with guidance to list available records; terminal records include outcome details when available.
Operators can cancel background work: Description: Operators can request that running background work stop and can record cancellation for work whose underlying owner cannot be directly stopped.; Inputs required: A task lookup and, when available, an optional cancellation reason.; Observable outcomes: The task becomes cancelled or returns a clear reason it could not be cancelled.; Acceptance criteria: Running child work receives a stop request; command-tracked work can be marked cancelled; successful cancellation updates the task state; failed cancellation reports a reason.
Operators can change task notification behavior: Description: Operators can choose whether a task reports only terminal changes, every state change, or no task-specific notifications.; Inputs required: A task lookup and a notification policy.; Observable outcomes: Future task delivery follows the selected policy.; Acceptance criteria: Terminal-only policy reports completion; state-change policy reports progress transitions; silent policy suppresses task-specific user notifications.

Reliability and recovery

Operators can audit unhealthy background work: Description: The product identifies task records that look stale, lost, undelivered, incomplete, or internally inconsistent.; Inputs required: A request for a health audit and optional severity or issue filters.; Observable outcomes: The operator sees findings with severity, issue type, affected record, and detail.; Acceptance criteria: Long-queued work is warned; long-running work is errored; delivery failures are visible unless notifications are silent; retained lost records warn before their cleanup window expires and error afterward.
Operators can preview and apply maintenance safely: Description: The product can reconcile active records with their owning actors, recover known outcomes, stamp cleanup timing, remove expired records, and report what it would change before writing changes.; Inputs required: A maintenance request and an apply or preview mode.; Observable outcomes: Preview reports expected changes; apply performs eligible changes and reports before-and-after health.; Acceptance criteria: Preview does not mutate task state; apply reconciles eligible records; maintenance explains why stale work is retained, recovered, marked lost, or pruned.
Scheduled work can be recovered before being marked lost: Description: When a scheduled run no longer appears active, the product checks durable run evidence before declaring its task lost.; Inputs required: A stale scheduled-run task and available run history or job state.; Observable outcomes: Completed scheduled runs are finalized from durable evidence; only unrecoverable stale runs become lost.; Acceptance criteria: A completed scheduled run is not falsely marked lost after restart; offline inspection does not treat absence of live ownership as conclusive by itself.
Task records are retained long enough for review and then cleaned up: Description: Terminal task records remain available for a bounded review period and are later removed automatically.; Inputs required: A task reaching a terminal state.; Observable outcomes: Recent terminal work remains inspectable; expired work disappears from normal task records.; Acceptance criteria: Terminal work receives cleanup timing; expired records are pruned; stale completed records are hidden from concise status views before final removal.

Completion and delivery

Users can receive completion updates through the right conversation: Description: When policy allows, the product delivers task completion to the remembered conversation target or queues it for the requester session.; Inputs required: A terminal task, delivery context when available, and notification policy.; Observable outcomes: Completion appears in the intended conversation, or the requester session is awakened to handle it.; Acceptance criteria: Direct delivery is attempted when a valid target exists; fallback queuing is used when direct delivery is unavailable; silent policy suppresses user-facing task notifications.
Users are protected from stale interim completion text: Description: For background runs that delegate further work, the product prefers the final responsible output over interim acknowledgement text.; Inputs required: A background run that has descendant work or interim output.; Observable outcomes: Users receive the final relevant result instead of a premature acknowledgement when the final result is available.; Acceptance criteria: Interim-only updates are suppressed while descendant work is still responsible; final descendant output is preferred when it arrives before delivery.

Chat, status, and client visibility

Chat users can view current-session background activity: Description: A chat user can ask for the current task board and see active and recent work linked to that conversation.; Inputs required: An authorized chat request from a session.; Observable outcomes: The user sees active and recent tasks with status, timing, progress, and error detail.; Acceptance criteria: Active work is shown first; recent failures remain visible; stale completed work is hidden; unauthorized requests do not disclose task details.
Chat users can see safe aggregate task counts without cross-session detail leaks: Description: When no current-session tasks are visible, the product can show aggregate same-agent counts without exposing another session's task text.; Inputs required: A chat request from a session with no visible linked tasks.; Observable outcomes: The user sees aggregate active and total counts for the same agent when relevant.; Acceptance criteria: Detail from other sessions is not shown; same-agent counts can appear; unrelated agent work is not exposed.
Status views summarize task pressure: Description: Status surfaces include concise task pressure so users can tell whether background work is active or recently failed.; Inputs required: A status request for a session or agent context.; Observable outcomes: Status includes active counts, recent failure context, and task kind when useful.; Acceptance criteria: Active work is prioritized over completed work; recent failures are shown when no active work exists; stale completed work is omitted.
Trusted clients can manage task records through a stable contract: Description: Approved client applications can list task summaries, retrieve task detail, and request cancellation.; Inputs required: Client request parameters such as status, agent, session, task identity, limit, or cancellation reason.; Observable outcomes: Clients receive sanitized task summaries or cancellation results with stable status names.; Acceptance criteria: Listing supports filtering and pagination; reading a missing task fails clearly; cancellation returns whether a record was found and whether it was cancelled.

Flow-level coordination

Operators can observe multi-step background work as a flow: Description: When work spans multiple steps, the product can represent the parent flow separately from individual task records.; Inputs required: A flow owner, goal, current state, and linked task records when present.; Observable outcomes: Operators can see flow status, task counts, current step, blocking reason, and linked task records.; Acceptance criteria: A flow can be listed; a flow can be inspected; linked task counts reflect active, total, and issue counts.
Operators can cancel a background flow: Description: Operators can request cancellation for a multi-step flow so it stops starting new child work and settles once active work ends or is cancelled.; Inputs required: A flow lookup.; Observable outcomes: The flow records cancellation intent, active child tasks receive cancellation requests when possible, and the flow stops progressing to new steps.; Acceptance criteria: Cancellation intent survives restart; active linked tasks are addressed; no new child work starts after cancellation is requested.
Operators can audit unhealthy flows: Description: The product can identify flows that are stuck, missing linked task evidence, blocked by missing work, stuck during cancellation, or unable to restore state.; Inputs required: A health audit request.; Observable outcomes: Flow findings appear alongside task findings with severity and detail.; Acceptance criteria: Stale running flows are flagged; stale waiting or blocked flows are flagged; missing linked task evidence is reported only after the flow is stale enough to avoid false positives.

Safety and privacy

User-facing task text is sanitized and bounded: Description: The product removes internal context and limits verbose task text before showing it in chat, status, or client responses.; Inputs required: Task title, progress, terminal summary, or error text that may contain internal context or excessive length.; Observable outcomes: Users see concise, safe summaries rather than internal runtime details.; Acceptance criteria: Internal markers are removed; long text is shortened; error context is safe for user-facing display.
Plugins can manage only owner-scoped task and flow records: Description: Extensions can access task and flow visibility for the session they are bound to without receiving broad operator access.; Inputs required: A bound session context.; Observable outcomes: The plugin can list, resolve, inspect, and request cancellation for owned task or flow records.; Acceptance criteria: A plugin without a bound session cannot use the task surface; owner-scoped access does not disclose unrelated task records.

Constraints

Task tracking must not become the scheduler or executor for the underlying work.
Normal interactive chat and heartbeat turns must not create task records.
Notification delivery must obey the selected notification policy.
Cancellation is best-effort and must report when the underlying work cannot be stopped.
Task and flow text shown outside trusted internals must be sanitized and bounded.
Session and agent visibility boundaries must prevent cross-session detail leaks.
Terminal records must be retained for recent inspection and eventually removed.
Lost-state detection must account for the owning actor before reporting a task lost.

Integrations

Scheduler for time-based work and scheduled-run history.
Delegation runners for child-agent work.
External agent session runners for background sessions.
Command-backed agent runner for operator-initiated background work.
Media providers for long-running generation jobs.
Messaging channels for direct completion delivery.
Trusted client applications for task listing, inspection, and cancellation.
Plugins that need owner-scoped task and flow controls.

Out of scope

Choosing when scheduled jobs run.
Executing the underlying background work directly.
Creating task records for normal chat turns or heartbeat turns.
Guaranteeing cancellation when the owning actor cannot be stopped.
Providing unlimited task history.
Exposing full task details across unrelated sessions or agents.

Success indicators

Operators can identify active background work without searching logs.
False lost reports for scheduled work decrease after restarts.
Completion messages arrive in the intended conversation or are queued for the requester.
Stale running and delivery-failed work is surfaced through audit and status views.
Chat task boards show useful current-session detail without leaking other-session task content.
Expired terminal records are removed without operator intervention.
Multi-step background work can be inspected and cancelled at both flow and individual task levels.