Sottoagenti

I sotto-agenti sono esecuzioni di agenti in background avviate da un'esecuzione di agente esistente. Ciascuno viene eseguito nella propria sessione (agent:<agentId>:subagent:<uuid>) e, al termine, annuncia il proprio risultato al canale di chat del richiedente. Ogni esecuzione di sotto-agente viene registrata come attività in background.

Obiettivi:

• Parallelizzare la ricerca, le attività lunghe e le operazioni lente degli strumenti senza bloccare l'esecuzione principale.
• Mantenere i sotto-agenti isolati per impostazione predefinita (separazione delle sessioni, uso facoltativo della sandbox).
• Rendere difficile un uso improprio degli strumenti: per impostazione predefinita, i sotto-agenti non ricevono strumenti per sessioni o messaggi.
• Supportare una profondità di annidamento configurabile per i modelli di orchestrazione.

Comando slash

/subagents esamina le esecuzioni dei sotto-agenti per la sessione corrente:

/subagents list/subagents log <id|#> [limit] [tools]/subagents info <id|#>

/subagents info mostra i metadati dell'esecuzione (stato, indicatori temporali, ID sessione, percorso della trascrizione, pulizia). /subagents log stampa i turni di chat recenti di un'esecuzione; aggiungi il token tools per includere i messaggi di chiamata/risultato degli strumenti (omessi per impostazione predefinita). Usa sessions_history per una vista di richiamo limitata e filtrata per sicurezza dall'interno di un turno dell'agente, oppure esamina il percorso della trascrizione sul disco per consultare la trascrizione completa non elaborata.

Controlli di associazione ai thread

Questi comandi funzionano sui canali con associazioni persistenti ai thread. Consulta Canali che supportano i thread di seguito.

/focus <subagent-label|session-key|session-id|session-label>/unfocus/agents/session idle <duration|off>/session max-age <duration|off>

Comportamento di avvio

Gli agenti avviano sotto-agenti in background con lo strumento sessions_spawn. I completamenti vengono restituiti come eventi interni della sessione padre; l'agente padre/richiedente decide se è necessario un aggiornamento visibile all'utente.

Modalità di contesto

I sotto-agenti nativi vengono avviati in isolamento, a meno che il chiamante non richieda esplicitamente di diramare la trascrizione corrente.

Usa fork con parsimonia. Serve per la delega sensibile al contesto, non come sostituto di una descrizione chiara dell'attività.

Strumento: sessions_spawn

Avvia un'esecuzione di sotto-agente con deliver: false nella corsia globale subagent, quindi esegue un passaggio di annuncio e pubblica la relativa risposta nel canale di chat del richiedente.

La disponibilità dipende dai criteri effettivi degli strumenti del chiamante. Il profilo integrato coding include sessions_spawn; messaging e minimal no. full consente tutti gli strumenti. Aggiungi tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"] oppure usa tools.profile: "coding" per gli agenti con un profilo più ristretto che devono comunque delegare il lavoro. I criteri di autorizzazione/negazione per canale/gruppo, provider, sandbox e singolo agente possono comunque rimuovere lo strumento dopo la fase del profilo. Usa /tools dalla stessa sessione per confermare l'elenco effettivo degli strumenti.

Impostazioni predefinite:

• Modello: i sotto-agenti nativi ereditano il modello del chiamante, a meno che non imposti agents.defaults.subagents.model (o agents.list[].subagents.model per singolo agente). Gli avvii con runtime ACP usano lo stesso modello configurato per i sotto-agenti, se presente; altrimenti l'ambiente ACP mantiene la propria impostazione predefinita. Un valore esplicito di sessions_spawn.model ha comunque la precedenza.
• Ragionamento: i sotto-agenti nativi ereditano il ragionamento del chiamante, a meno che non imposti agents.defaults.subagents.thinking (o agents.list[].subagents.thinking per singolo agente). Gli avvii con runtime ACP applicano anche agents.defaults.models["provider/model"].params.thinking per il modello selezionato. Un valore esplicito di sessions_spawn.thinking ha comunque la precedenza.
• Timeout dell'esecuzione: OpenClaw usa agents.defaults.subagents.runTimeoutSeconds quando è impostato; altrimenti ripiega su 0 (nessun timeout). sessions_spawn non accetta sostituzioni del timeout per singola chiamata.
• Consegna dell'attività: i sotto-agenti nativi ricevono l'attività delegata nel loro primo messaggio visibile [Subagent Task]. Il prompt di sistema del sotto-agente contiene le regole di esecuzione e il contesto di instradamento, non un duplicato nascosto dell'attività.

Gli avvii accettati dei sotto-agenti nativi includono nel risultato dello strumento i metadati risolti del modello dell'agente figlio: resolvedModel contiene il riferimento del modello applicato e resolvedProvider contiene il prefisso del provider quando il riferimento ne include uno.

Modalità del prompt di delega

agents.defaults.subagents.delegationMode controlla soltanto le indicazioni del prompt; non modifica i criteri degli strumenti né impone la delega.

• suggest (predefinito): mantiene l'indicazione standard del prompt a usare i sotto-agenti per lavori più ampi o più lenti.
• prefer: indica all'agente principale di rimanere reattivo e di delegare tramite sessions_spawn qualsiasi attività più complessa di una risposta diretta.

Sostituzione per singolo agente: agents.list[].subagents.delegationMode.

{  agents: {    defaults: {      subagents: {        delegationMode: "prefer",        maxConcurrent: 4,      },    },    list: [      {        id: "coordinator",        subagents: { delegationMode: "prefer" },      },    ],  },}

Parametri dello strumento

Nomi delle attività e selezione dei target

taskName è un identificatore esposto al modello per l'orchestrazione, non una chiave di sessione. Usarlo per nomi stabili dei figli, come review_subagents, linux_validation o docs_update, quando un coordinatore potrebbe dover ispezionare quel figlio in seguito.

La risoluzione del target accetta corrispondenze esatte di taskName e prefissi non ambigui. La corrispondenza è limitata alla stessa finestra di target attivi/recenti usata dai target numerati di /subagents, pertanto un figlio completato e obsoleto non rende ambiguo un identificatore riutilizzato. Se due figli attivi o recenti condividono lo stesso taskName, il target è ambiguo; usare invece l'indice dell'elenco, la chiave di sessione o l'ID dell'esecuzione.

I target riservati last e all non sono valori validi per taskName, perché hanno già significati di controllo.

Strumento: sessions_yield

Termina il turno corrente del modello e attende che gli eventi di runtime, principalmente quelli di completamento dei sotto-agenti, arrivino come messaggio successivo. Usarlo dopo aver generato il lavoro figlio necessario quando il richiedente non può produrre una risposta finale finché tali completamenti non sono disponibili.

sessions_yield è la primitiva di attesa. Non sostituirla con cicli di polling su subagents, sessions_list, sessions_history, con sleep della shell o con il polling dei processi al solo scopo di rilevare il completamento di un figlio.

Usare sessions_yield solo quando l'elenco effettivo degli strumenti della sessione lo include. Alcuni profili di strumenti minimi o personalizzati possono esporre sessions_spawn e subagents senza esporre sessions_yield; in tal caso, non inventare un ciclo di polling al solo scopo di attendere il completamento.

Quando sono presenti figli attivi, OpenClaw inserisce nei turni normali un blocco di prompt compatto, generato dal runtime, denominato Active Subagents, affinché il richiedente possa vedere le sessioni figlie correnti, gli ID delle esecuzioni, gli stati, le etichette, le attività e gli alias taskName senza ricorrere al polling. I campi attività ed etichetta di quel blocco sono racchiusi tra virgolette come dati, non come istruzioni, perché possono provenire da argomenti di generazione forniti dall'utente o dal modello.

Strumento: subagents

Elenca le esecuzioni dei sotto-agenti generati di proprietà della sessione richiedente. L'ambito è limitato al richiedente corrente; un figlio può vedere solo i propri figli controllati.

Usare subagents per ottenere stato e debug su richiesta. Usare sessions_yield per attendere gli eventi di completamento.

Sessioni associate a thread

Quando le associazioni ai thread sono abilitate per un canale, un sotto-agente può rimanere associato a un thread, in modo che i successivi messaggi dell'utente in quel thread continuino a essere instradati alla stessa sessione del sotto-agente.

Canali che supportano i thread

Un canale supporta sessioni persistenti di sotto-agenti associate a thread (sessions_spawn con thread: true) quando registra un adattatore di associazione delle conversazioni. I canali inclusi con questo supporto sono: Discord, iMessage, Matrix e Telegram. Discord e Matrix creano per impostazione predefinita un thread figlio; Telegram e iMessage associano per impostazione predefinita la conversazione corrente. Usare le chiavi di configurazione threadBindings specifiche per canale per l'abilitazione, i timeout e spawnSessions.

Flusso rapido

Controlli manuali

Opzioni di configurazione

• Impostazione predefinita globale: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Le chiavi di sostituzione per canale e di associazione automatica alla generazione sono specifiche dell'adattatore. Consultare Canali che supportano i thread sopra.

Consultare il riferimento della configurazione e i comandi slash per i dettagli aggiornati sugli adattatori.

Elenco consentito

Se la sessione richiedente è isolata in una sandbox, sessions_spawn rifiuta i target che verrebbero eseguiti senza sandbox.

Individuazione

Usare agents_list per vedere quali ID agente sono attualmente consentiti per sessions_spawn. La risposta include il modello effettivo di ogni agente elencato e i metadati del runtime incorporato, affinché i chiamanti possano distinguere OpenClaw, il server dell'app Codex e gli altri runtime nativi configurati.

Le voci di allowAgents devono indicare ID agente configurati in agents.list[]. ["*"] indica qualsiasi agente di destinazione configurato più il richiedente. Se una configurazione agente viene eliminata ma il relativo ID rimane in allowAgents, sessions_spawn rifiuta tale ID e agents_list lo omette. Eseguire openclaw doctor --fix per eliminare le voci obsolete dell'elenco consentito oppure aggiungere una voce minima in agents.list[] quando il target deve rimanere generabile ereditando al contempo le impostazioni predefinite.

Archiviazione automatica

• Le sessioni dei sotto-agenti vengono archiviate automaticamente dopo agents.defaults.subagents.archiveAfterMinutes (valore predefinito: 60).
• L'archiviazione usa sessions.delete e rinomina la trascrizione in *.deleted.<timestamp> nella stessa cartella.
• cleanup: "delete" archivia immediatamente dopo l'annuncio, mantenendo comunque la trascrizione tramite ridenominazione.
• L'archiviazione automatica è eseguita con la massima diligenza; i timer in attesa vengono persi se il Gateway si riavvia.
• I timeout di esecuzione configurati non archiviano automaticamente; arrestano solo l'esecuzione. La sessione rimane fino all'archiviazione automatica.
• L'archiviazione automatica si applica allo stesso modo alle sessioni di profondità 1 e 2.
• La pulizia del browser è separata dalla pulizia dell'archivio: si tenta di chiudere le schede e i processi del browser monitorati al termine dell'esecuzione, anche se la trascrizione o il record della sessione vengono conservati.

Sotto-agenti annidati

Per impostazione predefinita, i sotto-agenti non possono generare i propri sotto-agenti (maxSpawnDepth: 1). Impostare maxSpawnDepth: 2 per abilitare un livello di annidamento: il modello orchestratore: principale → sotto-agente orchestratore → sotto-sotto-agenti esecutori.

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // consente ai sotto-agenti di generare figli (valore predefinito: 1, intervallo 1-5)        maxChildrenPerAgent: 5, // numero massimo di figli attivi per sessione agente (valore predefinito: 5, intervallo 1-20)        maxConcurrent: 8, // limite globale della corsia di concorrenza (valore predefinito: 8)        runTimeoutSeconds: 900, // timeout predefinito per sessions_spawn (0 = nessun timeout)        announceTimeoutMs: 120000, // timeout per chiamata per l'annuncio del Gateway      },    },  },}

Livelli di profondità

Catena di notifica

I risultati risalgono lungo la catena:

1. L'esecutore di profondità 2 termina → invia una notifica al proprio genitore (orchestratore di profondità 1).
2. L'orchestratore di profondità 1 riceve la notifica, sintetizza i risultati, termina → invia una notifica all'agente principale.
3. L'agente principale riceve la notifica e comunica il risultato all'utente.

Ogni livello vede solo le notifiche provenienti dai propri figli diretti.

Criteri di accesso agli strumenti per profondità

• Il ruolo e l'ambito di controllo vengono registrati nei metadati della sessione al momento della generazione. Ciò impedisce che chiavi di sessione appiattite o ripristinate riacquistino accidentalmente i privilegi di orchestratore.
• Profondità 1 (orchestratore, quando maxSpawnDepth >= 2): riceve sessions_spawn, subagents, sessions_list, sessions_history per poter generare figli e verificarne lo stato. Gli altri strumenti di sessione o di sistema rimangono negati.
• Profondità 1 (terminale, quando maxSpawnDepth == 1): nessuno strumento di sessione (comportamento predefinito attuale).
• Profondità 2 (esecutore terminale): nessuno strumento di sessione; sessions_spawn è sempre negato alla profondità 2. Non può generare ulteriori figli.

Limite di generazione per agente

Ogni sessione agente, a qualsiasi profondità, può avere al massimo maxChildrenPerAgent figli attivi contemporaneamente (valore predefinito: 5). Ciò impedisce un'espansione incontrollata da parte di un singolo orchestratore.

Arresto a cascata

L'arresto di un orchestratore di profondità 1 arresta automaticamente tutti i suoi figli di profondità 2:

• /stop nella chat principale arresta tutti gli agenti di profondità 1 e propaga l'arresto ai rispettivi figli di profondità 2.

Autenticazione

L'autenticazione dei sottoagenti viene risolta in base all'ID agente, non al tipo di sessione:

• La chiave di sessione del sottoagente è agent:<agentId>:subagent:<uuid>.
• L'archivio di autenticazione viene caricato dall'agentDir di tale agente.
• I profili di autenticazione dell'agente principale vengono uniti come ripiego; in caso di conflitto, i profili dell'agente prevalgono su quelli dell'agente principale.

L'unione è additiva, quindi i profili dell'agente principale sono sempre disponibili come ripiego. Un'autenticazione completamente isolata per ciascun agente non è ancora supportata.

Notifica

I sottoagenti comunicano i risultati mediante un passaggio di notifica:

• Il passaggio di notifica viene eseguito all'interno della sessione del sottoagente, non nella sessione del richiedente.
• Se il sottoagente risponde esattamente ANNOUNCE_SKIP, non viene pubblicato nulla.
• Se il testo più recente dell'assistente corrisponde esattamente al token silenzioso NO_REPLY / no_reply, l'output della notifica viene soppresso anche se in precedenza erano presenti aggiornamenti visibili.

La consegna dipende dalla profondità del richiedente:

• Le sessioni richiedenti di livello superiore usano una chiamata agent successiva con consegna esterna (deliver=true).
• Le sessioni richiedenti di sottoagenti annidati ricevono un'iniezione interna successiva (deliver=false), affinché l'orchestratore possa sintetizzare nella sessione i risultati dei figli.
• Se una sessione richiedente di un sottoagente annidato non esiste più, OpenClaw ricorre al richiedente di quella sessione, se disponibile.

Per le sessioni richiedenti di livello superiore, la consegna diretta in modalità di completamento risolve prima l'eventuale percorso associato alla conversazione o alla discussione e la sostituzione definita dall'hook, quindi completa i campi mancanti di canale e destinazione usando il percorso memorizzato nella sessione del richiedente. In questo modo i completamenti rimangono nella chat o nell'argomento corretto anche quando l'origine del completamento identifica soltanto il canale.

Durante la creazione dei risultati dei completamenti annidati, l'aggregazione dei completamenti dei figli è limitata all'esecuzione corrente del richiedente, impedendo che output obsoleti di figli appartenenti a esecuzioni precedenti confluiscano nella notifica corrente. Le risposte di notifica mantengono l'instradamento della discussione o dell'argomento quando è disponibile negli adattatori dei canali.

Contesto della notifica

Il contesto della notifica viene normalizzato in un blocco di eventi interno stabile:

Le esecuzioni terminate con errore riportano lo stato di errore senza riprodurre il testo di risposta acquisito. L'output tool/toolResult non viene promosso a testo del risultato del figlio.

Riga delle statistiche

I payload delle notifiche includono alla fine una riga di statistiche, anche quando sono racchiusi:

• Durata di esecuzione, ad esempio runtime 5m12s.
• Utilizzo dei token (input/output/totale).
• Costo stimato quando è configurata la tariffazione dei modelli (models.providers.*.models[].cost).
• sessionKey, sessionId e percorso della trascrizione, affinché l'agente principale possa recuperare la cronologia tramite sessions_history o esaminare il file sul disco.

I metadati interni sono destinati esclusivamente all'orchestrazione; le risposte rivolte all'utente devono essere riscritte con il normale tono dell'assistente.

Perché preferire sessions_history

sessions_history è il percorso di orchestrazione più sicuro per leggere la trascrizione di un figlio durante un turno dell'agente:

• Oscura il testo simile a credenziali o token anche quando l'oscuramento generale dei registri è disabilitato.
• Tronca i blocchi di testo lunghi (4000 caratteri per blocco) e rimuove le firme di elaborazione, i payload di riproduzione del ragionamento e i dati immagine incorporati.
• Impone un limite di risposta di 80 KB; le righe sovradimensionate vengono sostituite con [sessions_history omitted: message too large].
• Quando presente, usa nextOffset per scorrere all'indietro le finestre precedenti della trascrizione.
• sessions_history non rimuove i tag di ragionamento, la struttura <relevant-memories> o l'XML delle chiamate agli strumenti dal testo dei messaggi: restituisce blocchi di contenuto strutturati simili alla forma grezza della trascrizione, ma oscurati e con dimensioni limitate. /subagents log applica una sanificazione più incisiva del testo (rimuove i tag di ragionamento, la struttura dei ricordi e l'XML delle chiamate agli strumenti), poiché visualizza righe di chat in testo semplice anziché blocchi strutturati.
• L'esame della trascrizione grezza sul disco è il ripiego da usare quando serve la trascrizione completa, identica byte per byte.

Criteri di accesso agli strumenti

I sottoagenti usano inizialmente lo stesso profilo e la stessa catena di criteri di accesso agli strumenti del genitore o dell'agente di destinazione. Successivamente, OpenClaw applica il livello di restrizione dei sottoagenti.

I sottoagenti perdono sempre gateway, agents_list, session_status e cron, indipendentemente dalla profondità o dal ruolo: si tratta di strumenti a livello di sistema o interattivi, oppure di strumenti il cui coordinamento spetta all'agente principale. I sottoagenti terminali, ossia il comportamento predefinito alla profondità 1 e sempre alla profondità 2, perdono inoltre subagents, sessions_list, sessions_history e sessions_spawn. I sottoagenti non ricevono mai lo strumento message: viene disabilitato al momento della generazione, non filtrato da questo elenco di esclusione. Anche sessions_send rimane negato, affinché i sottoagenti comunichino esclusivamente attraverso la catena di notifica.

Anche in questo caso, sessions_history rimane una vista di consultazione limitata e sanificata, non un'esportazione grezza della trascrizione.

Quando maxSpawnDepth >= 2, i sottoagenti orchestratori di profondità 1 ricevono inoltre sessions_spawn, subagents, sessions_list e sessions_history, così da poter gestire i propri figli.

Sostituzione tramite configurazione

{  agents: {    defaults: {      subagents: {        maxConcurrent: 1,      },    },  },  tools: {    subagents: {      tools: {        // deny wins        deny: ["gateway", "cron"],        // if allow is set, it becomes allow-only (deny still wins)        // allow: ["read", "exec", "process"]      },    },  },}

tools.subagents.tools.allow è un filtro finale che consente esclusivamente gli strumenti elencati. Può restringere l'insieme di strumenti già risolto, ma non può aggiungere nuovamente uno strumento rimosso da tools.profile. Ad esempio, tools.profile: "coding" include web_search/web_fetch, ma non lo strumento browser. Per consentire ai sottoagenti con profilo di programmazione di usare l'automazione del browser, aggiungi browser nella fase del profilo:

{  tools: {    profile: "coding",    alsoAllow: ["browser"],  },}

Usa agents.list[].tools.alsoAllow: ["browser"] per singolo agente quando l'automazione del browser deve essere concessa a un solo agente.

Concorrenza

I sottoagenti usano una corsia dedicata nella coda interna al processo:

• Nome della corsia: subagent
• Concorrenza: agents.defaults.subagents.maxConcurrent (valore predefinito: 8)

Attività e ripristino

OpenClaw non considera l'assenza di endedAt una prova permanente che un sottoagente sia ancora attivo. Le esecuzioni non terminate più vecchie della finestra di obsolescenza delle esecuzioni (2 ore oppure il timeout configurato per l'esecuzione più un breve periodo di tolleranza, scegliendo il valore maggiore) non vengono più conteggiate come attive o in sospeso in /subagents list, nei riepiloghi di stato, nel controllo del completamento dei discendenti e nelle verifiche della concorrenza per sessione.

Dopo il riavvio del Gateway, le esecuzioni obsolete ripristinate ma non terminate vengono eliminate, a meno che la relativa sessione figlia non sia contrassegnata con abortedLastRun: true. Le esecuzioni interrotte dal riavvio rimangono registrate per il flusso di ripristino dei sottoagenti orfani: le esecuzioni obsolete vengono finalizzate senza ripresa, mentre le sessioni figlie recenti ricevono un messaggio sintetico di ripresa prima della rimozione del contrassegno di interruzione.

Il ripristino automatico dopo il riavvio è limitato per ciascuna sessione figlia. Se lo stesso sottoagente figlio viene accettato ripetutamente per il ripristino degli orfani all'interno della finestra di rapido blocco ricorrente, OpenClaw salva in modo persistente un contrassegno definitivo di ripristino su tale sessione e smette di riprenderla automaticamente nei riavvii successivi. Esegui openclaw tasks maintenance --apply per riconciliare il record dell'attività oppure openclaw doctor --fix per rimuovere i contrassegni obsoleti di ripristino interrotto nelle sessioni contrassegnate definitivamente.

Arresto

• L'invio di /stop nella chat del richiedente interrompe la sessione del richiedente e arresta tutte le esecuzioni attive dei sottoagenti generate da essa, propagando l'arresto ai figli annidati.

Limitazioni

• L'annuncio del sottoagente è eseguito secondo il principio del massimo sforzo. Se il Gateway si riavvia, le operazioni di "annuncio al chiamante" in sospeso vengono perse.
• I sottoagenti continuano a condividere le risorse dello stesso processo Gateway; considera maxConcurrent una valvola di sicurezza.
• sessions_spawn è sempre non bloccante: restituisce immediatamente { status: "accepted", runId, childSessionKey }.
• Il contesto del sottoagente include solo AGENTS.md e TOOLS.md (non SOUL.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md o BOOTSTRAP.md). I sottoagenti nativi di Codex rispettano lo stesso limite: TOOLS.md rimane nelle istruzioni ereditate del thread Codex, mentre i file relativi a personalità, identità e utente, riservati al genitore, vengono inseriti come istruzioni di collaborazione limitate al turno, affinché i figli non li clonino.
• La profondità massima di annidamento è 5 (intervallo di maxSpawnDepth: 1-5). Per la maggior parte dei casi d'uso è consigliata una profondità di 2.
• maxChildrenPerAgent limita il numero di figli attivi per sessione (valore predefinito 5, intervallo 1-20).

Contenuti correlati

• Strumenti di sessione e modifiche dello stato
• Agenti ACP
• Invio dell'agente
• Attività in background
• Strumenti sandbox multiagente