Automation

Attività in background

Le attività in background tracciano il lavoro eseguito fuori dalla sessione di conversazione principale: esecuzioni ACP, avvii 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.

In breve

Le attività sono record, non scheduler: Cron e Heartbeat decidono quando viene eseguito il lavoro, le attività tracciano 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 del runtime in memoria è scomparso, la manutenzione delle attività controlla prima la cronologia durevole delle esecuzioni Cron prima di marcare un'attività come persa.
Il completamento è guidato da push: il lavoro scollegato può notificare direttamente o risvegliare la sessione/Heartbeat del richiedente quando termina, quindi i cicli di polling dello stato sono di solito la forma sbagliata.
Le esecuzioni Cron isolate e i completamenti dei subagent ripuliscono 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 padre intermedie obsolete 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 sono conservati per 7 giorni, poi eliminati automaticamente.

Avvio rapido

Elenca e filtra

bash

# List all tasks (newest first)openclaw tasks list # Filter by runtime or statusopenclaw tasks list --runtime acpopenclaw tasks list --status running

Ispeziona

bash

# Show details for a specific task (by ID, run ID, or session key)openclaw tasks show <lookup>

Annulla e notifica

bash

# Cancel a running task (kills the child session)openclaw tasks cancel <lookup> # Change notification policy for a taskopenclaw tasks notify <lookup> state_changes

Audit e manutenzione

bash

# Run a health auditopenclaw tasks audit # Preview or apply maintenanceopenclaw tasks maintenanceopenclaw tasks maintenance --apply

Flusso attività

bash

# Inspect TaskFlow stateopenclaw tasks flow listopenclaw tasks flow show <lookup>openclaw tasks flow cancel <lookup>

Cosa crea un'attività

Origine	Tipo runtime	Quando viene creato un record attività	Policy di notifica predefinita
Esecuzioni ACP in background	`acp`	Avvio di una sessione ACP figlia	`done_only`
Orchestrazione subagent	`subagent`	Avvio di un subagent tramite `sessions_spawn`	`done_only`
Cron job (tutti i tipi)	`cron`	Ogni esecuzione Cron (sessione principale e isolata)	`silent`
Operazioni CLI	`cli`	Comandi `openclaw agent` eseguiti tramite il Gateway	`silent`
Job multimediali dell'agente	`cli`	Esecuzioni `image_generate`/`music_generate`/`video_generate` supportate da sessione	`silent`

Valori predefiniti di notifica per Cron e contenuti multimediali

Le attività Cron della sessione principale usano la policy di notifica silent per impostazione predefinita: creano record per il tracciamento ma non generano notifiche. Anche le attività Cron isolate usano silent per impostazione predefinita, ma sono più visibili perché vengono eseguite nella propria sessione.

Anche le esecuzioni image_generate, music_generate e video_generate supportate da sessione usano la policy di notifica silent. Creano comunque record attività, ma il completamento viene restituito alla sessione agente originale come wake interno, così l'agente può scrivere il messaggio di follow-up e allegare direttamente il contenuto multimediale terminato. L'agente richiedente segue il suo normale contratto di risposta visibile: risposta finale automatica quando configurata, oppure message(action="send") più NO_REPLY quando la sessione richiede risposte tramite strumento di messaggistica. Se la sessione richiedente non è più attiva o il suo wake attivo non riesce, e l'agente di completamento perde alcuni o tutti i contenuti multimediali generati, OpenClaw invia un fallback diretto idempotente con solo i contenuti mancanti al target del canale originale.

Guardrail per generazione multimediale concorrente

Finché un'attività di generazione multimediale supportata da sessione è ancora attiva, gli strumenti multimediali agiscono anche come guardrail contro ritentativi accidentali. Le chiamate image_generate ripetute per lo stesso prompt restituiscono lo stato dell'attività attiva corrispondente, mentre un prompt immagine distinto può avviare la propria attività. Le chiamate music_generate e video_generate restituiscono comunque lo stato dell'attività attiva per quella sessione invece di avviare una seconda generazione concorrente. Usa action: "status" quando vuoi una ricerca esplicita di avanzamento/stato dal lato agente.

Cosa non crea attività

Turni Heartbeat: sessione principale; vedi Heartbeat
Normali turni di chat interattiva
Risposte dirette /command

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

Stato	Cosa significa
`queued`	Creata, in attesa che l'agente inizi
`running`	Il turno dell'agente è in esecuzione attiva
`succeeded`	Completata correttamente
`failed`	Completata con un errore
`timed_out`	Ha superato il timeout configurato
`cancelled`	Interrotta dall'operatore tramite `openclaw tasks cancel`
`lost`	Il runtime ha perso lo stato di supporto autorevole dopo un periodo di tolleranza di 5 minuti

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 segnale di successo successivo non declassa quello stato terminale.

lost è consapevole del runtime:

Attività ACP: i metadati della sessione ACP figlia 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 vuoto del runtime Cron in-process come autorità.
Attività CLI: le attività con un run id/source id usano il contesto di esecuzione live, quindi righe persistenti di sessione figlia o chat session non le mantengono attive dopo che l'esecuzione posseduta dal Gateway scompare. Le attività CLI legacy senza identità di esecuzione tornano comunque alla sessione figlia. Anche le esecuzioni openclaw agent supportate dal Gateway vengono finalizzate dal loro risultato di esecuzione, quindi le esecuzioni completate non restano attive finché lo sweeper non le marca 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.). I completamenti delle attività di gruppo e canale vengono invece instradati tramite la sessione richiedente, così l'agente padre può scrivere la risposta visibile. Per i completamenti dei subagent, OpenClaw preserva anche l'instradamento di thread/topic associato 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 in coda alla sessione: se la consegna diretta fallisce o non è impostata alcuna origine, l'aggiornamento viene messo in coda come evento di sistema nella sessione del richiedente ed emerge al prossimo Heartbeat.

Questo significa che il flusso di lavoro usuale è basato su push: avvia il lavoro scollegato una volta, poi lascia che il runtime ti risvegli o ti notifichi al completamento. Interroga lo stato dell'attività solo quando hai bisogno di debug, intervento o audit esplicito.

Policy di notifica

Controlla quanto vuoi sentire di ogni attività:

Policy	Cosa viene consegnato
`done_only` (predefinita)	Solo stato terminale (succeeded, failed, ecc.) - questo è il valore predefinito
`state_changes`	Ogni transizione di stato e aggiornamento di avanzamento
`silent`	Nulla

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

bash

openclaw tasks notify <lookup> state_changes

Riferimento CLI

tasks list

bash

openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]

Colonne di output: ID attività, Tipo, Stato, Consegna, Run ID, Sessione figlia, Riepilogo.

tasks show

bash

openclaw tasks show <lookup>

Il token di lookup accetta un ID attività, run ID o chiave di sessione. Mostra il record completo, inclusi tempistiche, stato di consegna, errore e riepilogo terminale.

tasks cancel

bash

openclaw tasks cancel <lookup>

Per attività ACP e subagent, questo termina la sessione figlia. Per attività tracciate dalla CLI, l'annullamento viene registrato nel registro attività (non esiste un handle runtime figlio separato). Lo stato passa a cancelled e, quando applicabile, viene inviata una notifica di consegna.

tasks notify

bash

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

tasks audit

bash

openclaw tasks audit [--json]

Evidenzia problemi operativi. I risultati compaiono anche in openclaw status quando vengono rilevati problemi.

Rilevamento	Gravità	Attivazione
`stale_queued`	avviso	In coda da più di 10 minuti
`stale_running`	errore	In esecuzione da più di 30 minuti
`lost`	avviso/errore	La proprietà dell'attività supportata dal runtime è scomparsa; le attività perse mantenute generano avvisi fino a `cleanupAfter`, poi diventano errori
`delivery_failed`	avviso	La consegna non è riuscita e la policy di notifica non è `silent`
`missing_cleanup`	avviso	Attività terminale senza timestamp di pulizia
`inconsistent_timestamps`	avviso	Violazione della sequenza temporale (ad esempio terminata prima dell'avvio)

tasks maintenance

bash

openclaw tasks maintenance [--json]openclaw tasks maintenance --apply [--json]

Usalo per visualizzare in anteprima o applicare riconciliazione, marcatura della pulizia e potatura per attività, stato di Task Flow e righe obsolete del registro delle sessioni di esecuzione cron.

La riconciliazione è consapevole del runtime:

Le attività ACP/subagent controllano la sessione figlia di supporto.
Le attività subagent la cui sessione figlia ha una tombstone di recupero dopo riavvio vengono contrassegnate come perse invece di essere trattate come sessioni di supporto recuperabili.
Le attività Cron controllano se il runtime cron possiede ancora il job, quindi recuperano lo stato terminale dai log di esecuzione cron/stato del job persistiti prima di ripiegare su lost. Solo il processo Gateway è autorevole per l'insieme in memoria dei job cron attivi; l'audit CLI offline usa la cronologia durevole ma non contrassegna un'attività cron come persa solo perché quel Set locale è vuoto.
Le attività CLI con identità di esecuzione controllano il contesto di esecuzione live proprietario, non solo le righe di sessione figlia o sessione chat.

Anche la pulizia del completamento è consapevole del runtime:

Il completamento del subagent chiude in modalità best-effort le schede/processi del browser tracciati per la sessione figlia prima che la pulizia dell'annuncio continui.
Il completamento cron isolato chiude in modalità best-effort le schede/processi del browser tracciati per la sessione cron prima che l'esecuzione venga completamente smantellata.
La consegna cron isolata attende il completamento del follow-up dei subagent discendenti quando necessario e sopprime il testo di riconoscimento del genitore obsoleto invece di annunciarlo.
La consegna del completamento del subagent usa solo l'ultimo testo visibile dell'assistente del figlio. L'output tool/toolResult non viene promosso a testo del risultato del figlio. Le esecuzioni terminali non riuscite annunciano lo stato di errore senza riprodurre il testo di risposta acquisito.
Gli errori di pulizia non mascherano il vero esito dell'attività.

Quando applica la manutenzione, OpenClaw rimuove anche le righe obsolete del registro sessioni cron:<jobId>:run:<uuid> più vecchie di 7 giorni, preservando le righe per i job cron attualmente in esecuzione e lasciando intatte le righe di sessione non cron.

tasks flow list | show | cancel

bash

openclaw tasks flow list [--status <status>] [--json]openclaw tasks flow show <lookup> [--json]openclaw tasks flow cancel <lookup>

Usali quando ciò che ti interessa è il Task Flow orchestrante, invece di un singolo record di attività in background.

Bacheca 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, tempi e dettagli di avanzamento o errore.

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

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

Integrazione dello stato (pressione delle attività)

openclaw status include un riepilogo immediato delle attività:

Code

Tasks: 3 queued · 2 running · 1 issues

Il riepilogo riporta:

active - conteggio di queued + running
failures - 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 hanno priorità, le righe completate obsolete vengono nascoste e gli errori recenti emergono solo quando non rimane alcun lavoro attivo. Questo mantiene la scheda di stato concentrata su ciò che conta in questo momento.

Archiviazione e manutenzione

Dove risiedono le attività

I record delle attività persistono in SQLite in:

Code

$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 PASSIVE. Arresto e checkpoint di manutenzione espliciti usano ancora TRUNCATE, così le chiusure normali possono recuperare spazio WAL senza costringere lo sweeper in background ad attendere lettori attivi.

Manutenzione automatica

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

Reconciliation

Controlla se le attività attive hanno ancora un supporto runtime autorevole. Le attività ACP/subagent usano lo stato della sessione figlia, le attività cron usano la proprietà dei job attivi e le attività CLI con identità di esecuzione usano il contesto di esecuzione proprietario. Se quello stato di supporto è assente per più di 5 minuti, l'attività viene contrassegnata come lost.

ACP session repair

Chiude le sessioni ACP one-shot terminali o orfane di proprietà del genitore, e chiude le sessioni ACP persistenti terminali obsolete o orfane solo quando non rimane alcun binding di conversazione attivo.

Cleanup stamping

Imposta un timestamp cleanupAfter sulle attività terminali (endedAt + 7 giorni). Durante la conservazione, le attività perse appaiono ancora nell'audit come avvisi; dopo la scadenza di cleanupAfter o quando mancano i metadati di pulizia, sono errori.

Pruning

Elimina i record oltre la loro data cleanupAfter.

Come le attività si relazionano ad altri sistemi

Tasks and Task Flow

Task Flow è il livello di orchestrazione dei flussi sopra le attività in background. Un singolo flusso può coordinare più attività nel corso della sua vita usando modalità di sincronizzazione gestite o rispecchiate. Usa openclaw tasks per ispezionare i record delle singole attività e openclaw tasks flow per ispezionare il flusso orchestrante.

Vedi Task Flow per i dettagli.

Tasks and cron

Le definizioni dei job Cron, lo stato di esecuzione runtime e la cronologia delle esecuzioni risiedono nel database di stato SQLite condiviso di OpenClaw. Ogni esecuzione cron crea un record di attività, sia main-session sia isolata. Le attività cron main-session usano per impostazione predefinita la policy di notifica silent, così vengono tracciate senza generare notifiche.

Vedi Job Cron.

Tasks and heartbeat

Le esecuzioni Heartbeat sono turni main-session: non creano record di attività. Quando un'attività viene completata, può attivare un risveglio Heartbeat così vedi rapidamente il risultato.

Vedi Heartbeat.

Tasks and sessions

Un'attività può fare riferimento a una childSessionKey (dove viene eseguito il lavoro) e a una requesterSessionKey (chi l'ha avviata). Il suo agentId identifica l'agente che esegue il lavoro, mentre i campi richiedente e proprietario preservano il contesto di avvio e controllo. Le sessioni sono contesto di conversazione; le attività sono tracciamento dell'attività sopra di esse.

Tasks and agent runs

Il runId di un'attività si collega all'esecuzione dell'agente che svolge il lavoro. Gli eventi del ciclo di vita dell'agente (avvio, fine, errore) aggiornano automaticamente lo stato dell'attività: non devi gestire manualmente il ciclo di vita.

Correlati

Automazione - tutti i meccanismi di automazione a colpo d'occhio
CLI: Attività - riferimento dei comandi CLI
Heartbeat - turni main-session periodici
Attività pianificate - pianificazione del lavoro in background
Task Flow - orchestrazione dei flussi sopra le attività

Was this useful?

Attività in background

In breve

Avvio rapido

Elenca e filtra

Ispeziona

Annulla e notifica

Audit e manutenzione

Flusso attività

Cosa crea un'attività

Ciclo di vita dell'attività

Consegna e notifiche

Policy di notifica

Riferimento CLI

Bacheca attività chat (`/tasks`)

Integrazione dello stato (pressione delle attività)

Archiviazione e manutenzione

Dove risiedono le attività

Manutenzione automatica

Reconciliation

ACP session repair

Cleanup stamping

Pruning

Come le attività si relazionano ad altri sistemi

Correlati

On this page

Molty

In breve

Avvio rapido

Elenca e filtra

Ispeziona

Annulla e notifica

Audit e manutenzione

Flusso attività

Cosa crea un'attività

Ciclo di vita dell'attività

Consegna e notifiche

Policy di notifica

Riferimento CLI

Bacheca attività chat (/tasks)

Integrazione dello stato (pressione delle attività)

Archiviazione e manutenzione

Dove risiedono le attività

Manutenzione automatica

Reconciliation

ACP session repair

Cleanup stamping

Pruning

Come le attività si relazionano ad altri sistemi

Correlati

On this page

Bacheca attività chat (`/tasks`)