Sottoagenti

I sub-agent sono esecuzioni di agent in background generate da un'esecuzione di agent esistente. Vengono eseguiti nella propria sessione (agent:<agentId>:subagent:<uuid>) e, al termine, annunciano il risultato al canale chat del richiedente. Ogni esecuzione di sub-agent viene tracciata come attività in background.

Obiettivi principali:

• Parallelizzare il lavoro di "ricerca / attività lunga / strumento lento" senza bloccare l'esecuzione principale.
• Mantenere i sub-agent isolati per impostazione predefinita (separazione della sessione + sandboxing opzionale).
• Mantenere la superficie degli strumenti difficile da usare in modo improprio: i sub-agent non ricevono gli strumenti di sessione per impostazione predefinita.
• Supportare una profondità di annidamento configurabile per i pattern di orchestrator.

Comando slash

Usa /subagents per ispezionare o controllare le esecuzioni di sub-agent per la sessione corrente:

/subagents list/subagents kill <id|#|all>/subagents log <id|#> [limit] [tools]/subagents info <id|#>/subagents send <id|#> <message>/subagents steer <id|#> <message>/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]

Usa /steer <message> di primo livello per guidare l'esecuzione attiva della sessione richiedente corrente. Usa /subagents steer <id|#> <message> quando il target è un'esecuzione figlia.

/subagents info mostra i metadati dell'esecuzione (stato, timestamp, ID sessione, percorso della trascrizione, pulizia). Usa sessions_history per una vista di richiamo limitata e filtrata per sicurezza; ispeziona il percorso della trascrizione su disco quando ti serve la trascrizione completa grezza.

Controlli di vincolo al thread

Questi comandi funzionano sui canali che supportano vincoli persistenti ai thread. Consulta Canali con supporto 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 generazione

/subagents spawn avvia un sub-agent in background come comando utente (non un relay interno) e invia un aggiornamento finale di completamento alla chat richiedente quando l'esecuzione termina.

Modalità di contesto

I sub-agent nativi partono isolati, a meno che il chiamante non chieda esplicitamente di forcare la trascrizione corrente.

Usa fork con parsimonia. Serve per deleghe sensibili al contesto, non come sostituto della scrittura di un prompt di attività chiaro.

Strumento: sessions_spawn

Avvia un'esecuzione di sub-agent con deliver: false sulla lane globale subagent, poi esegue un passaggio di annuncio e pubblica la risposta di annuncio nel canale chat del richiedente.

La disponibilità dipende dalla policy effettiva degli strumenti del chiamante. I profili coding e full espongono sessions_spawn per impostazione predefinita. Il profilo messaging no; aggiungi tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"] oppure usa tools.profile: "coding" per gli agent che dovrebbero delegare lavoro. Le policy di canale/gruppo, provider, sandbox e allow/deny per agent possono comunque rimuovere lo strumento dopo la fase del profilo. Usa /tools dalla stessa sessione per confermare l'elenco effettivo degli strumenti.

Valori predefiniti:

• Modello: eredita dal chiamante a meno che tu non imposti agents.defaults.subagents.model (o agents.list[].subagents.model per agent); un sessions_spawn.model esplicito prevale comunque.
• Ragionamento: eredita dal chiamante a meno che tu non imposti agents.defaults.subagents.thinking (o agents.list[].subagents.thinking per agent); un sessions_spawn.thinking esplicito prevale comunque.
• Timeout di esecuzione: se sessions_spawn.runTimeoutSeconds viene omesso, OpenClaw usa agents.defaults.subagents.runTimeoutSeconds quando impostato; altrimenti ripiega su 0 (nessun timeout).

Modalità prompt di delega

agents.defaults.subagents.delegationMode controlla solo la guida del prompt; non modifica la policy degli strumenti né impone la delega.

• suggest (predefinito): mantiene il normale suggerimento del prompt a usare i sub-agent per lavori più grandi o più lenti.
• prefer: dice all'agent principale di restare reattivo e delegare tramite sessions_spawn qualsiasi cosa più articolata di una risposta diretta.

Gli override per agent usano agents.list[].subagents.delegationMode.

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

Parametri dello strumento

Nomi delle attività e targeting

taskName è un handle rivolto al modello per l'orchestrazione, non una chiave di sessione. Usalo per nomi figlio stabili come review_subagents, linux_validation o docs_update quando un coordinatore potrebbe dover indirizzare o terminare 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, quindi un figlio completato obsoleto non rende ambiguo un handle riutilizzato. Se due figli attivi o recenti condividono lo stesso taskName, il target è ambiguo; usa invece l'indice dell'elenco, la chiave di sessione o l'ID esecuzione.

I target 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 del runtime, principalmente gli eventi di completamento dei sotto-agenti, arrivino come messaggio successivo. Usalo dopo aver generato lavoro figlio richiesto quando il richiedente non può produrre una risposta finale finché tali completamenti non arrivano.

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

Usa 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 solo per attendere il completamento.

Quando esistono figli attivi, OpenClaw inserisce un blocco prompt compatto generato dal runtime Active Subagents nei turni normali, così il richiedente può vedere le sessioni figlie correnti, gli ID esecuzione, gli stati, le etichette, le attività e gli alias taskName senza polling. I campi attività ed etichetta in quel blocco sono citati come dati, non come istruzioni, perché possono provenire da argomenti di generazione forniti dall'utente/modello.

Strumento: subagents

Elenca, indirizza o termina le esecuzioni di sotto-agenti generate possedute dalla sessione richiedente. È limitato al richiedente corrente; un figlio può solo vedere/controllare i propri figli controllati.

Usa subagents per stato su richiesta, debug, indirizzamento o terminazione. Usa 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 affinché i messaggi utente successivi in quel thread continuino a essere instradati alla stessa sessione del sotto-agente.

Canali con supporto thread

Discord è attualmente l'unico canale supportato. Supporta sessioni subagent persistenti associate a thread (sessions_spawn con thread: true), controlli manuali dei thread (/focus, /unfocus, /agents, /session idle, /session max-age) e chiavi adattatore channels.discord.threadBindings.enabled, channels.discord.threadBindings.idleHours, channels.discord.threadBindings.maxAgeHours e channels.discord.threadBindings.spawnSessions.

Flusso rapido

Controlli manuali

Interruttori di configurazione

• Predefinito globale: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Le chiavi di override del canale e auto-associazione alla generazione sono specifiche dell'adattatore. Vedi Canali con supporto thread sopra.

Vedi Riferimento di configurazione e Comandi slash per i dettagli correnti dell'adattatore.

Allowlist

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

Scoperta

Usa agents_list per vedere quali ID agente sono attualmente consentiti per sessions_spawn. La risposta include il modello effettivo di ciascun agente elencato e i metadati di runtime incorporati, così i chiamanti possono distinguere PI, server app Codex e altri runtime nativi configurati.

Archiviazione automatica

• Le sessioni dei sotto-agenti vengono archiviate automaticamente dopo agents.defaults.subagents.archiveAfterMinutes (predefinito 60).
• L'archiviazione usa sessions.delete e rinomina la trascrizione in *.deleted.<timestamp> (stessa cartella).
• cleanup: "delete" archivia immediatamente dopo l'annuncio (mantiene comunque la trascrizione tramite rinomina).
• L'archiviazione automatica è best-effort; i timer in sospeso vengono persi se il gateway si riavvia.
• runTimeoutSeconds non archivia automaticamente; interrompe solo l'esecuzione. La sessione resta fino all'archiviazione automatica.
• L'archiviazione automatica si applica ugualmente alle sessioni di profondità 1 e profondità 2.
• La pulizia del browser è separata dalla pulizia dell'archivio: le schede/processi del browser tracciati vengono chiusi best-effort al termine dell'esecuzione, anche se la trascrizione/il record di sessione viene mantenuto.

Sotto-agenti annidati

Per impostazione predefinita, i sotto-agenti non possono generare i propri sotto-agenti (maxSpawnDepth: 1). Imposta maxSpawnDepth: 2 per abilitare un livello di annidamento — il pattern orchestrator: principale → sotto-agente orchestrator → sotto-sotto-agenti worker.

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)        maxConcurrent: 8, // global concurrency lane cap (default: 8)        runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout)        announceTimeoutMs: 120000, // per-call gateway announce timeout      },    },  },}

Livelli di profondità

Catena di annunci

I risultati risalgono lungo la catena:

1. Il worker di profondità 2 termina → annuncia al suo genitore (orchestrator di profondità 1).
2. L'orchestrator di profondità 1 riceve l'annuncio, sintetizza i risultati, termina → annuncia al principale.
3. L'agente principale riceve l'annuncio e lo recapita all'utente.

Ogni livello vede solo gli annunci dei propri figli diretti.

Criterio degli strumenti per profondità

• Il ruolo e l'ambito di controllo vengono scritti nei metadati della sessione al momento dello spawn. Questo impedisce a chiavi di sessione piatte o ripristinate di recuperare accidentalmente privilegi di orchestratore.
• Profondità 1 (orchestratore, quando maxSpawnDepth >= 2): riceve sessions_spawn, subagents, sessions_list, sessions_history così può gestire i propri figli. Gli altri strumenti di sessione/sistema restano negati.
• Profondità 1 (foglia, quando maxSpawnDepth == 1): nessuno strumento di sessione (comportamento predefinito attuale).
• Profondità 2 (worker foglia): nessuno strumento di sessione: sessions_spawn è sempre negato alla profondità 2. Non può generare ulteriori figli.

Limite di spawn per agente

Ogni sessione agente (a qualsiasi profondità) può avere al massimo maxChildrenPerAgent (predefinito 5) figli attivi alla volta. Questo impedisce una proliferazione incontrollata da 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 si propaga ai loro figli di profondità 2.
• /subagents kill <id> arresta uno specifico sotto-agente e si propaga ai suoi figli.
• /subagents kill all arresta tutti i sotto-agenti del richiedente e si propaga.

Autenticazione

L'autenticazione del sotto-agente viene risolta per id agente, non per tipo di sessione:

• La chiave di sessione del sotto-agente è agent:<agentId>:subagent:<uuid>.
• Lo store di autenticazione viene caricato dall'agentDir di quell'agente.
• I profili di autenticazione dell'agente principale vengono uniti come fallback; i profili agente sovrascrivono i profili principali in caso di conflitti.

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

Annuncio

I sotto-agenti rispondono tramite un passaggio di annuncio:

• Il passaggio di annuncio viene eseguito dentro la sessione del sotto-agente (non nella sessione del richiedente).
• Se il sotto-agente risponde esattamente ANNOUNCE_SKIP, non viene pubblicato nulla.
• Se l'ultimo testo dell'assistente è l'esatto token silenzioso NO_REPLY / no_reply, l'output di annuncio viene soppresso anche se prima esisteva un avanzamento visibile.

La consegna dipende dalla profondità del richiedente:

• Le sessioni richiedenti di livello superiore usano una chiamata agent di follow-up con consegna esterna (deliver=true).
• Le sessioni sotto-agente richiedenti annidate ricevono un'iniezione di follow-up interna (deliver=false) così l'orchestratore può sintetizzare i risultati figli nella sessione.
• Se una sessione sotto-agente richiedente annidata è scomparsa, OpenClaw ripiega sul richiedente di quella sessione quando disponibile.

Per le sessioni richiedenti di livello superiore, la consegna diretta in modalità completamento risolve prima qualunque route di conversazione/thread associata e override di hook, poi riempie i campi canale-destinazione mancanti dalla route memorizzata della sessione richiedente. Questo mantiene i completamenti nella chat/argomento corretti anche quando l'origine del completamento identifica solo il canale.

L'aggregazione dei completamenti figli è limitata all'esecuzione corrente del richiedente quando crea i risultati di completamento annidati, impedendo agli output figli obsoleti di esecuzioni precedenti di filtrare nell'annuncio corrente. Le risposte di annuncio preservano il routing di thread/argomento quando disponibile sugli adattatori di canale.

Contesto dell'annuncio

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

Le esecuzioni terminali fallite segnalano lo stato di errore senza riprodurre il testo di risposta acquisito. In caso di timeout, se il figlio è arrivato solo fino alle chiamate agli strumenti, l'annuncio può comprimere quella cronologia in un breve riepilogo di avanzamento parziale invece di riprodurre l'output grezzo degli strumenti.

Riga delle statistiche

I payload di annuncio includono una riga delle statistiche alla fine (anche quando sono racchiusi):

• Runtime (ad es. runtime 5m12s).
• Utilizzo dei token (input/output/totale).
• Costo stimato quando il pricing del modello è configurato (models.providers.*.models[].cost).
• sessionKey, sessionId e percorso del transcript così l'agente principale può recuperare la cronologia tramite sessions_history o ispezionare il file su disco.

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

Perché preferire sessions_history

sessions_history è il percorso di orchestrazione più sicuro:

• Il richiamo dell'assistente viene prima normalizzato: tag di pensiero rimossi; impalcatura <relevant-memories> / <relevant_memories> rimossa; blocchi di payload XML di chiamate strumento in testo semplice (<tool_call>, <function_call>, <tool_calls>, <function_calls>) rimossi, inclusi payload troncati che non si chiudono correttamente; impalcatura di chiamate/risultati strumento declassata e marcatori di contesto storico rimossi; token di controllo del modello trapelati (<|assistant|>, altri ASCII <|...|>, full-width <｜...｜>) rimossi; XML di chiamate strumento MiniMax malformato rimosso.
• Il testo simile a credenziali/token viene oscurato.
• I blocchi lunghi possono essere troncati.
• Cronologie molto grandi possono eliminare righe più vecchie o sostituire una riga troppo grande con [sessions_history omitted: message too large].
• L'ispezione del transcript grezzo su disco è il fallback quando serve il transcript completo byte per byte.

Criterio degli strumenti

I sotto-agenti usano prima la stessa pipeline di profilo e criterio degli strumenti del genitore o dell'agente target. Dopo questo, OpenClaw applica il livello di restrizione per sotto-agente.

Senza un tools.profile restrittivo, i sotto-agenti ricevono tutti gli strumenti eccetto gli strumenti di sessione e gli strumenti di sistema:

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

Anche qui sessions_history resta una vista di richiamo limitata e sanificata: non è un dump grezzo del transcript.

Quando maxSpawnDepth >= 2, i sotto-agenti orchestratori di profondità 1 ricevono inoltre sessions_spawn, subagents, sessions_list e sessions_history così possono gestire i propri figli.

Override 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 solo-allow. Può restringere l'insieme di strumenti già risolto, ma non può riaggiungere uno strumento rimosso da tools.profile. Per esempio, tools.profile: "coding" include web_search/web_fetch ma non lo strumento browser. Per consentire ai sotto-agenti con profilo coding di usare l'automazione del browser, aggiungi browser nella fase di profilo:

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

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

Concorrenza

I sotto-agenti usano una corsia di coda dedicata nello stesso processo:

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

Vitalità e ripristino

OpenClaw non tratta l'assenza di endedAt come prova permanente che un sotto-agente sia ancora attivo. Le esecuzioni non concluse più vecchie della finestra di esecuzione obsoleta smettono di contare come attive/in attesa in /subagents list, nei riepiloghi di stato, nel gating dei completamenti discendenti e nei controlli di concorrenza per sessione.

Dopo un riavvio del Gateway, le esecuzioni ripristinate obsolete e non concluse vengono eliminate, a meno che la loro sessione figlia sia contrassegnata abortedLastRun: true. Queste sessioni figlie interrotte dal riavvio restano recuperabili tramite il flusso di recupero degli orfani del sotto-agente, che invia un messaggio sintetico di ripresa prima di cancellare il marcatore di interruzione.

Il recupero automatico dopo riavvio è limitato per sessione figlia. Se lo stesso figlio sotto-agente viene accettato ripetutamente per il recupero degli orfani dentro la finestra rapida di re-wedge, OpenClaw persiste una tombstone di recupero su quella sessione e smette di riprenderla automaticamente ai riavvii successivi. Esegui openclaw tasks maintenance --apply per riconciliare il record dell'attività, oppure openclaw doctor --fix per cancellare flag di recupero interrotto obsoleti sulle sessioni con tombstone.

Arresto

• L'invio di /stop nella chat del richiedente interrompe la sessione del richiedente e arresta tutte le esecuzioni sotto-agente attive generate da essa, propagandosi ai figli annidati.
• /subagents kill <id> arresta uno specifico sotto-agente e si propaga ai suoi figli.

Limitazioni

• L'annuncio dei sotto-agenti è best-effort. Se il Gateway si riavvia, il lavoro "annuncia indietro" in sospeso viene perso.
• I sotto-agenti condividono comunque le stesse risorse del processo Gateway; considera maxConcurrent una valvola di sicurezza.
• sessions_spawn è sempre non bloccante: restituisce { status: "accepted", runId, childSessionKey } immediatamente.
• Il contesto del sotto-agente inietta solo AGENTS.md, TOOLS.md, SOUL.md, IDENTITY.md e USER.md (nessun MEMORY.md, HEARTBEAT.md o BOOTSTRAP.md).
• La profondità massima di annidamento è 5 (intervallo maxSpawnDepth: 1–5). La profondità 2 è consigliata per la maggior parte dei casi d'uso.
• maxChildrenPerAgent limita i figli attivi per sessione (predefinito 5, intervallo 1–20).

Correlati

• Agenti ACP
• Invio agente
• Attività in background
• Strumenti sandbox multi-agente