Attività in background

Le attività in background tengono traccia del lavoro eseguito al di fuori della sessione di conversazione principale: esecuzioni ACP, avvii di subagenti, esecuzioni di processi Cron e operazioni avviate dalla CLI.

Le attività non sostituiscono le sessioni, i processi Cron o gli Heartbeat: sono il registro delle attività che annota quale lavoro separato è stato eseguito, quando e se è riuscito.

In breve

• Le attività sono registrazioni, non strumenti di pianificazione: Cron e Heartbeat decidono quando eseguire il lavoro, mentre le attività tengono traccia di ciò che è accaduto.
• ACP, i subagenti, tutti i processi Cron e le operazioni CLI creano attività. I turni Heartbeat non lo fanno.
• Ogni attività attraversa gli stati queued → running → terminal (succeeded, failed, timed_out, cancelled o lost).
• Le attività Cron rimangono attive finché il runtime Cron mantiene la titolarità del processo; se lo stato del runtime in memoria non è più disponibile, la manutenzione delle attività controlla prima la cronologia persistente delle esecuzioni Cron e solo dopo contrassegna un'attività come persa.
• Il completamento è basato su notifiche push: al termine, il lavoro separato può inviare direttamente una notifica oppure riattivare la sessione o l'Heartbeat del richiedente, quindi i cicli di polling dello stato sono generalmente un approccio inadeguato.
• Le esecuzioni Cron isolate e i completamenti dei subagenti tentano, senza garanzia, di chiudere le schede e i processi del browser monitorati per la rispettiva sessione figlia prima della registrazione finale delle operazioni di pulizia.
• La consegna delle esecuzioni Cron isolate elimina le risposte intermedie obsolete del genitore mentre il lavoro dei subagenti discendenti è ancora in fase di completamento e preferisce l'output finale dei discendenti quando questo arriva prima della consegna.
• Le notifiche di completamento vengono recapitate direttamente a un canale o messe in coda per il successivo Heartbeat.
• openclaw tasks list mostra tutte le attività; openclaw tasks audit evidenzia i problemi.
• Le registrazioni terminali vengono conservate per 7 giorni (quelle con stato lost per 24 ore), quindi eliminate automaticamente.

Avvio rapido

# Elenca tutte le attività (dalla più recente)openclaw tasks list # Filtra per runtime o statoopenclaw tasks list --runtime acpopenclaw tasks list --status running

# Mostra i dettagli di un'attività specifica (per ID attività, ID esecuzione o chiave di sessione)openclaw tasks show <lookup>

# Annulla un'attività in esecuzione (termina la sessione figlia)openclaw tasks cancel <lookup> # Modifica i criteri di notifica di un'attivitàopenclaw tasks notify <lookup> state_changes

# Esegue un controllo dello stato operativoopenclaw tasks audit # Mostra un'anteprima della manutenzione o la applicaopenclaw tasks maintenanceopenclaw tasks maintenance --apply

# Esamina lo stato di TaskFlowopenclaw tasks flow listopenclaw tasks flow show <lookup>openclaw tasks flow cancel <lookup>

Cosa crea un'attività

Ciclo di vita delle attività

stateDiagram-v2
    [*] --> queued
    queued --> running : avvio dell'agente
    running --> succeeded : completamento riuscito
    running --> failed : errore
    running --> timed_out : timeout superato
    queued --> cancelled : annullamento da parte dell'operatore
    running --> cancelled : annullamento da parte dell'operatore
    queued --> lost : stato sottostante assente > 5 min
    running --> lost : stato sottostante assente > 5 min

Le transizioni avvengono automaticamente: gli eventi del ciclo di vita dell'esecuzione dell'agente (avvio, fine, errore) aggiornano lo stato dell'attività; non è necessario gestirlo manualmente.

Il completamento dell'esecuzione dell'agente è autorevole per le registrazioni delle attività attive. Un'esecuzione separata riuscita termina con lo stato succeeded, gli errori ordinari di esecuzione terminano con failed, i timeout con timed_out e gli esiti di annullamento o interruzione con cancelled. Quando un'attività raggiunge uno stato terminale, i successivi segnali del ciclo di vita non ne peggiorano lo stato: un'attività annullata dall'operatore o già nello stato failed/timed_out/lost conserva tale stato anche se successivamente arriva un segnale di riuscita.

Lo stato lost dipende dal runtime:

• Attività ACP: solo un turno ACP attivo nel processo del Gateway dimostra che l'esecuzione è attiva; i soli metadati persistenti della sessione non sono sufficienti. Il controllo CLI offline rimane prudente e non recupera mai le attività ACP.
• Attività dei subagenti: la sessione figlia sottostante è scomparsa dall'archivio dell'agente di destinazione oppure contiene una registrazione di recupero dopo il riavvio.
• Attività Cron: il runtime Cron non monitora più il processo come attivo e la cronologia persistente delle esecuzioni Cron non mostra un risultato terminale per quell'esecuzione. Il controllo CLI offline non considera autorevole il proprio stato vuoto del runtime Cron interno al processo.
• Attività CLI: le attività con un ID esecuzione/ID origine usano il contesto di esecuzione attivo, quindi le righe residue della sessione figlia o della sessione di chat non le mantengono attive dopo la scomparsa dell'esecuzione gestita dal Gateway. Le attività CLI precedenti prive di identità dell'esecuzione continuano a ripiegare sulla sessione figlia. Anche le esecuzioni openclaw agent basate sul Gateway vengono finalizzate in base al risultato dell'esecuzione, quindi quelle completate non rimangono attive finché il processo di pulizia non le contrassegna come lost.

Consegna e notifiche

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

Consegna diretta: se l'attività ha una destinazione di canale (requesterOrigin), il messaggio di completamento viene inviato direttamente a tale canale (Discord, Slack, Telegram e così via). I completamenti delle attività di gruppo e di canale vengono invece instradati tramite la sessione richiedente, affinché l'agente genitore possa scrivere la risposta visibile. Per i completamenti dei subagenti, OpenClaw conserva inoltre l'instradamento associato al thread o all'argomento, se disponibile, e può ricavare dalla rotta memorizzata della sessione richiedente (lastChannel / lastTo / lastAccountId) un valore to o un account mancante prima di rinunciare alla consegna diretta.

Consegna in coda nella sessione: se la consegna diretta non riesce o non è impostata alcuna origine, l'aggiornamento viene accodato come evento di sistema nella sessione del richiedente e viene mostrato al successivo Heartbeat.

Ciò significa che il flusso di lavoro abituale è basato su notifiche push: avvia una sola volta il lavoro separato, quindi lascia che il runtime ti riattivi o ti notifichi al completamento. Controlla ripetutamente lo stato dell'attività solo quando devi eseguire il debug, intervenire o effettuare un controllo esplicito.

Criteri di notifica

Controlla quante informazioni ricevere per ogni attività:

Modifica il criterio 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> [--json]

openclaw tasks cancel <lookup>

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

openclaw tasks audit [--severity <warn|error>] [--code <name>] [--limit <n>] [--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>

Pannello delle attività della chat (/tasks)

Utilizza /tasks in qualsiasi sessione di chat per visualizzare le attività in background collegate a tale sessione. Il pannello mostra fino a cinque attività attive e completate di recente, con dettagli su runtime, stato, tempistiche e avanzamento o errore.

Quando la sessione corrente non presenta attività collegate visibili, /tasks mostra in alternativa i conteggi delle attività locali dell'agente, offrendo comunque una panoramica senza divulgare dettagli di altre sessioni.

Per il registro completo dell'operatore, utilizza la CLI: openclaw tasks list.

Interfaccia di controllo

L'interfaccia web di controllo dispone di una pagina Attività nella barra laterale, con le attività in background attive e recenti aggiornate in tempo reale. Utilizzala per esaminare l'avanzamento, aprire le sessioni collegate, aggiornare il registro o annullare le attività in coda e in esecuzione.

I riquadri della chat includono inoltre un pannello comprimibile Attività in background limitato all'agente del riquadro: mostra attività e sottoagenti in esecuzione con un controllo di arresto, una sezione delle attività completate e collegamenti Visualizza trascrizione alle sessioni figlie di ciascuna attività. Aprilo tramite il pulsante di attivazione dell'attività nell'intestazione del riquadro oppure tramite il pulsante mobile dell'attività nella chat a riquadro singolo.

Integrazione dello stato (carico delle attività)

openclaw status include una riga riepilogativa delle attività:

Attività    2 attive · 1 in coda · 1 in esecuzione · 1 problema · controllo senza problemi · 6 monitorate

Il riepilogo conteggia il lavoro attivo (queued + running), gli errori (failed + timed_out + lost), i risultati del controllo e il totale dei record monitorati; il payload JSON suddivide inoltre i conteggi per runtime (acp, subagent, cron, cli).

Sia /status sia lo strumento session_status utilizzano un'istantanea delle attività che tiene conto della pulizia: vengono privilegiate le attività attive, le righe scadute vengono nascoste e le attività terminate vengono visualizzate soltanto per un breve intervallo recente (5 minuti), mettendo in evidenza gli errori quando non rimane alcun lavoro attivo. In questo modo, la scheda di stato rimane concentrata su ciò che conta al momento.

Archiviazione e manutenzione

Dove risiedono le attività

I record delle attività e lo stato di consegna persistono nel database di stato SQLite condiviso di OpenClaw:

~/.openclaw/state/openclaw.sqlite   (tabelle: task_runs, task_delivery_state, flow_runs)

Imposta OPENCLAW_STATE_DIR per spostare altrove l'intera radice dello stato (impostazione predefinita: ~/.openclaw); anche il percorso del database condiviso verrà spostato.

Il registro viene caricato in memoria al primo utilizzo e ogni scrittura viene salvata in SQLite, pertanto i record persistono dopo i riavvii del Gateway. La crescita del WAL rimane limitata grazie alla soglia predefinita di autocheckpoint di SQLite e ai checkpoint periodici PASSIVE; i checkpoint durante l'arresto e la manutenzione esplicita utilizzano TRUNCATE, in modo che le normali chiusure recuperino lo spazio del WAL senza costringere il processo di pulizia in background ad attendere i lettori attivi.

Gli archivi di supporto precedenti provenienti da installazioni meno recenti (tasks/runs.sqlite, flows/registry.sqlite) vengono importati nel database condiviso da openclaw doctor.

Manutenzione automatica

Un processo di pulizia viene eseguito ogni 60 secondi (il primo passaggio avviene circa 5 secondi dopo l'avvio del Gateway) e gestisce quattro operazioni:

Relazione tra le attività e gli altri sistemi

Correlati

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