Attività in background

Le attività in background tracciano il lavoro eseguito fuori dalla sessione di conversazione principale: esecuzioni ACP, creazione di subagent, esecuzioni isolate di cron job e operazioni avviate dalla CLI.

Le attività non sostituiscono sessioni, cron job o Heartbeat: sono il registro delle attività che registra quale lavoro scollegato è avvenuto, quando e se è riuscito.

# TL;DR

• Le attività sono record, non scheduler: cron e Heartbeat decidono quando il lavoro viene eseguito, le attività tracciano che cosa è successo.
• ACP, subagent, tutti i cron job e le operazioni CLI creano attività. I turni Heartbeat no.
• Ogni attività passa attraverso queued → running → terminal (succeeded, failed, timed_out, cancelled o lost).
• Le attività cron restano attive finché il runtime cron possiede ancora il job; se lo stato runtime in memoria non esiste più, la manutenzione delle attività controlla prima la cronologia durevole delle esecuzioni cron prima di contrassegnare un'attività come lost.
• Il completamento è guidato da push: il lavoro scollegato può notificare direttamente o riattivare la sessione/Heartbeat del richiedente quando termina, quindi i loop di polling dello stato sono di solito la forma sbagliata.
• Le esecuzioni cron isolate e i completamenti dei subagent puliscono al meglio le schede/processi del browser tracciati per la loro sessione figlia prima della contabilità finale di pulizia.
• La consegna cron isolata sopprime le risposte intermedie obsolete del genitore mentre il lavoro dei subagent discendenti è ancora in fase di svuotamento, e preferisce l'output finale del discendente quando arriva prima della consegna.
• Le notifiche di completamento vengono consegnate direttamente a un canale o messe in coda per il prossimo Heartbeat.
• openclaw tasks list mostra tutte le attività; openclaw tasks audit evidenzia i problemi.
• I record terminali vengono conservati per 7 giorni, poi eliminati automaticamente.

# Avvio rapido

# 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>

# Che cosa crea un'attività

# Ciclo di vita dell'attività

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

Le transizioni avvengono automaticamente: quando l'esecuzione dell'agente associata termina, lo stato dell'attività viene aggiornato di conseguenza.

Il completamento dell'esecuzione dell'agente è autorevole per i record attività attivi. Un'esecuzione scollegata riuscita viene finalizzata come succeeded, gli errori ordinari di esecuzione vengono finalizzati come failed e gli esiti di timeout o interruzione vengono finalizzati come timed_out. Se un operatore ha già annullato l'attività, o il runtime ha già registrato uno stato terminale più forte come failed, timed_out o lost, un successivo segnale di successo non degrada quello stato terminale.

lost è consapevole del runtime:

• Attività ACP: i metadati della sessione figlia ACP di supporto sono scomparsi.
• Attività subagent: la sessione figlia di supporto è scomparsa dallo store dell'agente di destinazione.
• Attività cron: il runtime cron non traccia più il job come attivo e la cronologia durevole delle esecuzioni cron non mostra un risultato terminale per quell'esecuzione. L'audit CLI offline non tratta il proprio stato runtime cron in-process vuoto come autorevole.
• Attività CLI: le attività con sessione figlia isolata usano la sessione figlia; le attività CLI basate su chat usano invece il contesto di esecuzione live, quindi le righe persistenti di sessione canale/gruppo/diretta non le mantengono attive. Anche le esecuzioni openclaw agent basate su Gateway vengono finalizzate dal loro risultato di esecuzione, quindi le esecuzioni completate non restano attive finché lo sweeper le contrassegna come lost.

# Consegna e notifiche

Quando un'attività raggiunge uno stato terminale, OpenClaw ti notifica. Esistono due percorsi di consegna:

Consegna diretta: se l'attività ha un target di canale (il requesterOrigin), il messaggio di completamento va direttamente a quel canale (Telegram, Discord, Slack, ecc.). Per i completamenti dei subagent, OpenClaw conserva anche l'instradamento associato di thread/topic quando disponibile e può compilare un to / account mancante dalla route salvata della sessione richiedente (lastChannel / lastTo / lastAccountId) prima di rinunciare alla consegna diretta.

Consegna accodata nella sessione: se la consegna diretta fallisce o non è impostata alcuna origine, l'aggiornamento viene accodato come evento di sistema nella sessione del richiedente e riemerge al prossimo Heartbeat.

Ciò significa che il flusso di lavoro usuale è basato su push: avvia una volta il lavoro scollegato, poi lascia che il runtime ti riattivi o ti notifichi al completamento. Esegui il polling dello stato dell'attività solo quando hai bisogno di debug, intervento o audit esplicito.

# Policy di notifica

Controlla quanto vuoi essere informato su ogni attività:

Modifica la policy mentre un'attività è in esecuzione:

openclaw tasks notify <lookup> state_changes

# Riferimento CLI

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>

# Bacheca delle attività chat (/tasks)

Usa /tasks in qualsiasi sessione chat per vedere le attività in background collegate a quella sessione. La bacheca mostra le attività attive e completate di recente con runtime, stato, tempistiche e dettagli di avanzamento o errore.

Quando la sessione corrente non ha attività collegate visibili, /tasks ricade sui conteggi delle attività locali dell'agente, così ottieni comunque una panoramica senza esporre dettagli di altre sessioni.

Per il registro operativo completo, usa la CLI: openclaw tasks list.

# Integrazione dello stato (pressione delle attività)

openclaw status include un riepilogo immediato delle attività:

Tasks: 3 queued · 2 running · 1 issues

Il riepilogo riporta:

• attive - conteggio di queued + running
• errori - conteggio di failed + timed_out + lost
• byRuntime - suddivisione per acp, subagent, cron, cli

Sia /status sia lo strumento session_status usano uno snapshot delle attività consapevole della pulizia: le attività attive sono preferite, le righe completate obsolete vengono nascoste e gli errori recenti emergono solo quando non resta alcun lavoro attivo. Questo mantiene la scheda di stato focalizzata su ciò che conta in questo momento.

# Archiviazione e manutenzione

# Dove vivono le attività

I record delle attività persistono in SQLite in:

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

Il registro viene caricato in memoria all'avvio del Gateway e sincronizza le scritture su SQLite per garantire durabilità tra i riavvii. Il Gateway mantiene limitato il log write-ahead di SQLite usando la soglia predefinita di autocheckpoint di SQLite più checkpoint periodici e di arresto TRUNCATE.

# Manutenzione automatica

Uno sweeper viene eseguito ogni 60 secondi e gestisce quattro cose:

# Come le attività si collegano ad altri sistemi

# Correlati

• Automazione e attività - tutti i meccanismi di automazione in sintesi
• CLI: Attività - riferimento dei comandi CLI
• Heartbeat - turni periodici della sessione principale
• Attività pianificate - pianificazione del lavoro in background
• Task Flow - orchestrazione dei flussi sopra le attività