Sottoagenti

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

Obiettivi:

• Parallelizzare la ricerca, le attività lunghe e le operazioni lente degli strumenti senza bloccare l'esecuzione principale.
• Mantenere i sub-agenti isolati per impostazione predefinita (separazione delle sessioni, sandboxing facoltativo).
• Rendere difficile un uso improprio dell'insieme di strumenti: per impostazione predefinita, i sub-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 sub-agenti per la sessione corrente:

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

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

Nell'interfaccia di controllo, le sessioni padre con esecuzioni figlie recenti dispongono di una riga espandibile nella barra laterale. Le righe annidate mostrano lo stato e la durata di esecuzione degli agenti figli; selezionandone una si apre la chat dell'agente figlio mantenendo la gerarchia del padre.

Controlli di associazione ai thread

Questi comandi funzionano sui canali con associazioni persistenti ai thread. Consultare Canali che supportano i thread più avanti.

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

Comportamento di generazione

Gli agenti avviano sub-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 sub-agenti nativi vengono avviati isolati, a meno che il chiamante non richieda esplicitamente di creare una ramificazione della trascrizione corrente.

Usare fork con moderazione. Serve per la delega sensibile al contesto, non come sostituto di un prompt dell'attività chiaro.

Strumento: sessions_spawn

Avvia un'esecuzione di un sub-agente con deliver: false sulla corsia globale subagent, quindi esegue un passaggio di comunicazione e pubblica la risposta della comunicazione 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 invece no. full consente tutti gli strumenti. Aggiungere tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"], oppure usare 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. Usare /tools dalla stessa sessione per confermare l'elenco effettivo degli strumenti.

Impostazioni predefinite:

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

Le generazioni accettate di sub-agenti nativi includono i metadati risolti del modello dell'agente figlio nel risultato dello strumento: 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 solo le indicazioni del prompt; non modifica i criteri degli strumenti né impone la delega.

• suggest (impostazione predefinita): mantiene il normale suggerimento del prompt a usare i sub-agenti per attività più grandi o lente.
• prefer: indica all'agente principale di restare reattivo e 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 degli obiettivi

taskName è un handle destinato al modello per l'orchestrazione, non una chiave di sessione. Utilizzarlo 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 degli obiettivi accetta corrispondenze esatte di taskName e prefissi non ambigui. La corrispondenza è limitata alla stessa finestra di obiettivi attivi/recenti utilizzata dagli obiettivi numerati /subagents, pertanto un figlio completato obsoleto non rende ambiguo un handle riutilizzato. Se due figli attivi o recenti condividono lo stesso taskName, l'obiettivo è ambiguo; utilizzare invece l'indice dell'elenco, la chiave di sessione o l'id di esecuzione.

Gli obiettivi riservati last e all non sono valori taskName validi perché hanno già significati di controllo.

Strumento: sessions_yield

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

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

Utilizzare 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 esistono figli attivi, OpenClaw inserisce nei turni normali un blocco di prompt compatto Active Subagents generato dal runtime, affinché il richiedente possa vedere le sessioni figlie correnti, gli id di esecuzione, gli stati, le etichette, le attività e gli alias taskName senza polling. I campi attività ed etichetta in tale blocco sono racchiusi tra virgolette come dati, non come istruzioni, perché possono provenire da argomenti di creazione forniti dall'utente o dal modello.

Strumento: subagents

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

Utilizzare subagents per lo stato e il debug su richiesta. Utilizzare sessions_yield per attendere gli eventi di completamento.

Sessioni associate ai thread

Quando le associazioni ai thread sono abilitate per un canale, un sotto-agente può rimanere associato a un thread, affinché 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 ai thread (sessions_spawn con thread: true) quando registra un adattatore di associazione delle conversazioni. Canali inclusi con tale supporto: 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. Utilizzare le chiavi di configurazione threadBindings specifiche del canale per l'abilitazione, i timeout e spawnSessions.

Flusso rapido

Controlli manuali

Opzioni di configurazione

• Valore predefinito globale: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Le chiavi di sostituzione per canale e di associazione automatica alla creazione sono specifiche dell'adattatore. Vedere Canali che supportano i thread sopra.

Vedere Riferimento della configurazione e Comandi slash per i dettagli correnti degli adattatori.

Elenco consentito

Se la sessione richiedente è in sandbox, sessions_spawn rifiuta gli obiettivi che verrebbero eseguiti senza sandbox.

Individuazione

Utilizzare 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, l'app-server Codex e gli altri runtime nativi configurati.

Le voci allowAgents devono puntare a id agente configurati in agents.list[]. ["*"] indica qualsiasi agente di destinazione configurato più il richiedente. Se la configurazione di un agente viene eliminata ma il suo id rimane in allowAgents, sessions_spawn rifiuta tale id e agents_list lo omette. Eseguire openclaw doctor --fix per rimuovere le voci obsolete dell'elenco consentito oppure aggiungere una voce agents.list[] minima quando l'obiettivo deve rimanere disponibile per la creazione ereditando al contempo i valori predefiniti.

Archiviazione automatica

• Le sessioni dei sotto-agenti vengono archiviate automaticamente dopo agents.defaults.subagents.archiveAfterMinutes (valore predefinito 60).
• L'archiviazione utilizza sessions.delete e rinomina la trascrizione in *.deleted.<timestamp> (stessa cartella).
• cleanup: "delete" archivia immediatamente dopo l'annuncio (conserva comunque la trascrizione rinominandola).
• L'archiviazione automatica avviene secondo il principio del massimo sforzo; i timer in sospeso 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 da quella 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 viene conservato.

Sotto-agenti annidati

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

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // consente ai sotto-agenti di creare 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 dell'annuncio del Gateway      },    },  },}

Livelli di profondità

Catena degli annunci

I risultati risalgono lungo la catena:

1. Il worker di livello 2 termina → invia un annuncio al proprio genitore (orchestratore di livello 1).
2. L'orchestratore di livello 1 riceve l'annuncio, sintetizza i risultati, termina → invia un annuncio all'agente principale.
3. L'agente principale riceve l'annuncio e lo consegna all'utente.

Ogni livello vede solo gli annunci dei propri figli diretti.

Criteri degli strumenti per profondità

• Il ruolo e l'ambito di controllo vengono registrati nei metadati della sessione al momento della generazione. Ciò impedisce alle chiavi di sessione piatte o ripristinate di riacquisire accidentalmente i privilegi di orchestratore.
• Livello 1 (orchestratore, quando maxSpawnDepth >= 2): riceve sessions_spawn, subagents, sessions_list, sessions_history, così può generare figli e verificarne lo stato. Gli altri strumenti di sessione/sistema restano negati.
• Livello 1 (terminale, quando maxSpawnDepth == 1): nessuno strumento di sessione (comportamento predefinito attuale).
• Livello 2 (worker terminale): nessuno strumento di sessione — sessions_spawn è sempre negato al livello 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 una proliferazione incontrollata a partire da un singolo orchestratore.

Arresto a cascata

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

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

Autenticazione

L'autenticazione degli agenti secondari viene risolta in base all'ID agente, non al tipo di sessione:

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

L'unione è additiva, quindi i profili principali sono sempre disponibili come fallback. L'autenticazione completamente isolata per ciascun agente non è ancora supportata.

Annuncio

Gli agenti secondari restituiscono i risultati tramite un passaggio di annuncio:

• Il passaggio di annuncio viene eseguito all'interno della sessione dell'agente secondario (non nella sessione del richiedente).
• Se l'agente secondario risponde esattamente ANNOUNCE_SKIP, non viene pubblicato nulla.
• Se il testo più recente dell'assistente è esattamente il token silenzioso NO_REPLY / no_reply, l'output dell'annuncio viene soppresso anche se in precedenza erano presenti avanzamenti visibili.

La consegna dipende dalla profondità del richiedente:

• Le sessioni richiedenti di livello superiore usano una chiamata successiva a agent con consegna esterna (deliver=true).
• Le sessioni annidate degli agenti secondari richiedenti ricevono un'iniezione interna successiva (deliver=false), così l'orchestratore può sintetizzare i risultati dei figli all'interno della sessione.
• Se una sessione annidata dell'agente secondario richiedente non esiste più, OpenClaw ricorre al richiedente di tale sessione, quando disponibile.

Per le sessioni richiedenti di livello superiore, la consegna diretta in modalità di completamento risolve innanzitutto qualsiasi percorso associato di conversazione/thread e qualsiasi sostituzione tramite hook, quindi completa i campi mancanti di canale e destinazione usando il percorso memorizzato della sessione richiedente. Ciò mantiene i completamenti nella chat o nell'argomento corretto anche quando l'origine del completamento identifica soltanto il canale.

Durante la creazione dei risultati di completamento annidati, l'aggregazione dei completamenti dei figli è limitata all'esecuzione corrente del richiedente, impedendo che gli output obsoleti dei figli provenienti da esecuzioni precedenti confluiscano nell'annuncio corrente. Le risposte agli annunci mantengono l'instradamento di thread/argomento, quando disponibile negli adattatori di canale.

Contesto dell'annuncio

Il contesto dell'annuncio viene normalizzato in un blocco di eventi interno stabile:

Le esecuzioni terminali non riuscite segnalano lo stato di errore senza riprodurre il testo della risposta acquisito. L'output di strumenti/toolResult non viene promosso a testo del risultato del figlio.

Riga delle statistiche

I payload degli annunci includono alla fine una riga di statistiche (anche quando vengono racchiusi):

• Runtime (ad esempio runtime 5m12s).
• Utilizzo dei token (input/output/totale).
• Costo stimato quando sono configurati i prezzi del modello (models.providers.*.models[].cost).
• sessionKey, sessionId e il percorso della trascrizione, così l'agente principale può recuperare la cronologia tramite sessions_history o esaminare il file su disco.

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

Perché preferire sessions_history

sessions_history è il percorso di orchestrazione più sicuro per leggere la trascrizione di un figlio dall'interno del turno di un agente:

• Oscura il testo simile a credenziali/token anche quando l'oscuramento generale dei log è disabilitato.
• Tronca i blocchi di testo lunghi (4000 caratteri per blocco) ed elimina le firme di pensiero, i payload di riproduzione del ragionamento e i dati delle immagini incorporati.
• Impone un limite di risposta di 80 KB; le righe troppo grandi vengono sostituite con [sessions_history omitted: message too large].
• Usare nextOffset, quando presente, per scorrere all'indietro le finestre precedenti della trascrizione.
• sessions_history non rimuove dal testo dei messaggi i tag di ragionamento, la struttura <relevant-memories> o l'XML delle chiamate agli strumenti: restituisce blocchi di contenuto strutturati vicini alla forma grezza della trascrizione, ma oscurati e con dimensioni limitate. /subagents log applica una sanificazione del testo più intensa (rimuove i tag di ragionamento, la struttura della memoria e l'XML delle chiamate agli strumenti), perché visualizza righe di chat in testo semplice anziché blocchi strutturati.
• L'ispezione della trascrizione grezza su disco è il fallback quando è necessaria la trascrizione completa byte per byte.

Criteri degli strumenti

Gli agenti secondari usano innanzitutto lo stesso profilo e la stessa pipeline dei criteri degli strumenti dell'agente principale o di destinazione. Successivamente, OpenClaw applica il livello di restrizioni degli agenti secondari.

Gli agenti secondari perdono sempre gateway, agents_list, session_status e cron, indipendentemente dalla profondità o dal ruolo (strumenti a livello di sistema/interattivi o strumenti che l'agente principale deve coordinare). Gli agenti secondari terminali (comportamento predefinito di livello 1 e sempre al livello 2) perdono inoltre subagents, sessions_list, sessions_history e sessions_spawn. Gli agenti secondari non ricevono mai lo strumento message: viene disabilitato al momento della generazione, non filtrato da questo elenco di elementi negati; anche sessions_send resta negato, affinché gli agenti secondari comunichino esclusivamente tramite la catena degli annunci.

Anche qui sessions_history rimane una vista di richiamo limitata e sanificata: non è un dump grezzo della trascrizione.

Quando maxSpawnDepth >= 2, gli agenti secondari orchestratori di livello 1 ricevono inoltre sessions_spawn, subagents, sessions_list e sessions_history, così possono gestire i propri figli.

Sostituzione tramite configurazione

{  agents: {    defaults: {      subagents: {        maxConcurrent: 1,      },    },  },  tools: {    subagents: {      tools: {        // la negazione prevale        deny: ["gateway", "cron"],        // se allow è impostato, diventa un elenco esclusivo di elementi consentiti (la negazione prevale comunque)        // allow: ["read", "exec", "process"]      },    },  },}

tools.subagents.tools.allow è un filtro finale esclusivo degli elementi consentiti. 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 agli agenti secondari con profilo di programmazione di usare l'automazione del browser, aggiungere il browser nella fase del profilo:

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

Usare agents.list[].tools.alsoAllow: ["browser"] per agente quando soltanto un agente deve ottenere l'automazione del browser.

Concorrenza

Gli agenti secondari usano una corsia dedicata della coda interna al processo:

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

Operatività e ripristino

OpenClaw non considera l'assenza di endedAt una prova permanente che un agente secondario sia ancora attivo. Le esecuzioni non terminate più vecchie dell'intervallo per le esecuzioni obsolete (2 ore oppure il timeout di esecuzione configurato più un breve periodo di tolleranza, a seconda di quale sia maggiore) non vengono più conteggiate come attive/in sospeso in /subagents list, nei riepiloghi dello stato, nel blocco del completamento dei discendenti e nei controlli di concorrenza per sessione.

Dopo il riavvio del Gateway, le esecuzioni obsolete, ripristinate e non terminate vengono eliminate, a meno che la relativa sessione figlia non sia contrassegnata con abortedLastRun: true. Le esecuzioni interrotte dal riavvio restano registrate per il flusso di ripristino degli agenti secondari orfani: le esecuzioni obsolete vengono finalizzate senza ripresa, mentre le sessioni figlie recenti ricevono un messaggio sintetico di ripresa prima che il marcatore di interruzione venga cancellato.

Il ripristino automatico dopo il riavvio è limitato per ciascuna sessione figlia. Se lo stesso figlio agente secondario viene accettato ripetutamente per il ripristino degli orfani all'interno dell'intervallo di rapido blocco ricorrente, OpenClaw salva un marcatore permanente di ripristino su tale sessione e smette di riprenderla automaticamente ai riavvii successivi. Eseguire openclaw tasks maintenance --apply per riconciliare il record dell'attività oppure openclaw doctor --fix per cancellare i flag obsoleti di ripristino interrotto nelle sessioni con marcatore permanente.

Arresto

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

Limitazioni

• La notifica del sub-agente è eseguita secondo il principio del massimo impegno. Se il gateway si riavvia, il lavoro di "notifica di ritorno" in sospeso viene perso.
• I sub-agenti continuano a condividere le stesse risorse del processo del gateway; considerare maxConcurrent come una valvola di sicurezza.
• sessions_spawn è sempre non bloccante: restituisce immediatamente { status: "accepted", runId, childSessionKey }.
• Il contesto del sub-agente inserisce solo AGENTS.md e TOOLS.md (senza SOUL.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md o BOOTSTRAP.md). I sub-agenti nativi di Codex seguono lo stesso limite: TOOLS.md rimane nelle istruzioni ereditate del thread Codex, mentre i file di persona, 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à pari a 2.
• maxChildrenPerAgent limita il numero di figli attivi per sessione (valore predefinito 5, intervallo 1-20).

Argomenti correlati

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