--- read_when: - Ispezione del lavoro in background in corso o completato di recente - Risoluzione dei problemi di consegna per le esecuzioni di agenti scollegate - Comprendere come le esecuzioni in background si collegano alle sessioni, a cron e a heartbeat sidebarTitle: Background tasks summary: Tracciamento delle attività in background per esecuzioni ACP, subagenti, job Cron isolati e operazioni CLI title: Attività in background x-i18n: generated_at: "2026-06-27T17:09:10Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 4a630a52d0d6bfd387a37415dd63fc4bfbce23f99eaa8cb780c3d6f8913675fd source_path: automation/tasks.md workflow: 16 --- Cerchi la pianificazione? Consulta [Automazione](/it/automation) per scegliere il meccanismo giusto. Questa pagina è il registro delle attività per il lavoro in background, non lo scheduler. 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. Non ogni esecuzione dell'agente crea un'attività. I turni Heartbeat e la normale chat interattiva no. Tutte le esecuzioni Cron, gli avvii ACP, gli avvii di subagent e i comandi agente della CLI sì. ## 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 ```bash # List all tasks (newest first) openclaw tasks list # Filter by runtime or status openclaw tasks list --runtime acp openclaw tasks list --status running ``` ```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 # Change notification policy for a task openclaw tasks notify state_changes ``` ```bash # Run a health audit openclaw tasks audit # Preview or apply maintenance openclaw tasks maintenance openclaw tasks maintenance --apply ``` ```bash # Inspect TaskFlow state openclaw tasks flow list openclaw tasks flow show openclaw tasks flow cancel ``` ## 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` | 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. 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. - Turni Heartbeat: sessione principale; vedi [Heartbeat](/it/gateway/heartbeat) - Normali turni di chat interattiva - Risposte dirette `/command` ## Ciclo di vita dell'attività ```mermaid 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. Il completamento dell'attività attiva un wake Heartbeat immediato, così vedi rapidamente il risultato: non devi attendere il prossimo tick Heartbeat pianificato. 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 state_changes ``` ## Riferimento CLI ```bash openclaw tasks list [--runtime ] [--status ] [--json] ``` Colonne di output: ID attività, Tipo, Stato, Consegna, Run ID, Sessione figlia, Riepilogo. ```bash openclaw tasks show ``` 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. ```bash openclaw tasks cancel ``` 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. ```bash openclaw tasks notify ``` ```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) | ```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::run:` più vecchie di 7 giorni, preservando le righe per i job cron attualmente in esecuzione e lasciando intatte le righe di sessione non cron. ```bash openclaw tasks flow list [--status ] [--json] openclaw tasks flow show [--json] openclaw tasks flow cancel ``` 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à: ``` 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: ``` $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: 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`. 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. 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. Elimina i record oltre la loro data `cleanupAfter`. **Conservazione:** i record delle attività terminali vengono mantenuti per **7 giorni**, quindi potati automaticamente. Non è necessaria alcuna configurazione. ## Come le attività si relazionano ad altri sistemi [Task Flow](/it/automation/taskflow) è 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](/it/automation/taskflow) per i dettagli. 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](/it/automation/cron-jobs). 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](/it/gateway/heartbeat). 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. 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](/it/automation) - tutti i meccanismi di automazione a colpo d'occhio - [CLI: Attività](/it/cli/tasks) - riferimento dei comandi CLI - [Heartbeat](/it/gateway/heartbeat) - turni main-session periodici - [Attività pianificate](/it/automation/cron-jobs) - pianificazione del lavoro in background - [Task Flow](/it/automation/taskflow) - orchestrazione dei flussi sopra le attività