Sotto-agenti

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

Obiettivi principali:

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

Comando slash

Usa /subagents per ispezionare le esecuzioni di sotto-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). 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 associazione dei thread

Questi comandi funzionano sui canali che supportano associazioni persistenti dei thread. Vedi Canali che supportano i thread sotto.

/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 sotto-agenti in background con sessions_spawn. I completamenti dei sotto-agenti ritornano come eventi interni della sessione genitore; l'agente genitore/richiedente decide se è necessario un aggiornamento visibile all'utente.

Modalità di contesto

I sotto-agenti nativi iniziano isolati a meno che il chiamante non chieda esplicitamente di biforcare la trascrizione corrente.

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

Strumento: sessions_spawn

Avvia un'esecuzione di sotto-agente 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"] o usa tools.profile: "coding" per gli agenti che devono delegare lavoro. Le policy canale/gruppo, provider, sandbox e allow/deny per agente 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: i sotto-agenti nativi ereditano il chiamante a meno che tu non imposti agents.defaults.subagents.model (o agents.list[].subagents.model per agente). Le generazioni del runtime ACP usano lo stesso modello di sotto-agente configurato quando presente; altrimenti l'harness ACP mantiene il proprio valore predefinito. Un sessions_spawn.model esplicito ha comunque la precedenza.
• Thinking: i sotto-agenti nativi ereditano il chiamante a meno che tu non imposti agents.defaults.subagents.thinking (o agents.list[].subagents.thinking per agente). Le generazioni del runtime ACP applicano anche agents.defaults.models["provider/model"].params.thinking per il modello selezionato. Un sessions_spawn.thinking esplicito ha comunque la precedenza.
• Timeout esecuzione: OpenClaw usa agents.defaults.subagents.runTimeoutSeconds quando impostato; altrimenti ripiega su 0 (nessun timeout). sessions_spawn non accetta override di timeout per chiamata.
• Consegna attività: i sotto-agenti nativi ricevono l'attività delegata nel loro primo messaggio [Subagent Task] visibile. Il prompt di sistema del sotto-agente contiene regole di runtime e contesto di routing, non un duplicato nascosto dell'attività.

Le generazioni di sotto-agenti nativi accettate includono i metadati del modello figlio risolto nel risultato dello strumento: resolvedModel contiene il riferimento del modello applicato e resolvedProvider contiene il prefisso del provider quando il riferimento ne ha uno.

Modalità del prompt di delega

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

• suggest (predefinito): mantiene il suggerimento standard del prompt di usare sotto-agenti per lavori più grandi o più lenti.
• prefer: dice all'agente principale di rimanere reattivo e delegare tramite sessions_spawn qualunque cosa più articolata di una risposta diretta.

Gli override per agente 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 visibile al modello per l'orchestrazione, non una chiave di sessione. Usalo per nomi child stabili come review_subagents, linux_validation o docs_update quando un coordinatore potrebbe dover ispezionare quel child in seguito.

La risoluzione dei target accetta corrispondenze esatte di taskName e prefissi non ambigui. La corrispondenza è limitata alla stessa finestra di target attivi/recenti usata dai target numerati /subagents, quindi un child completato obsoleto non rende ambiguo un handle riutilizzato. Se due child attivi o recenti condividono lo stesso taskName, il target è ambiguo; usare invece l'indice della lista, la chiave di sessione o l'id di 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 runtime, principalmente gli eventi di completamento dei sotto-agenti, arrivino come messaggio successivo. Usalo dopo aver generato il lavoro child richiesto quando il richiedente non può produrre una risposta finale finché non arrivano quei completamenti.

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 child.

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 quel caso, non inventare un ciclo di polling solo per attendere il completamento.

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

Strumento: subagents

Elenca le esecuzioni di sotto-agenti generate e possedute dalla sessione richiedente. È limitato al richiedente corrente; un child può vedere solo i propri child controllati.

Usa subagents per stato e debug su richiesta. 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ò restare associato a un thread, così i messaggi utente di follow-up in quel thread continuano a essere instradati alla stessa sessione di sotto-agente.

Canali che supportano i thread

Qualsiasi canale con un adapter di associazione sessione può supportare sessioni persistenti di sotto-agente associate a thread (sessions_spawn con thread: true). Gli adapter inclusi attualmente comprendono i thread Discord, i thread Matrix, gli argomenti forum Telegram e le associazioni alla conversazione corrente per Feishu. Usa le chiavi di configurazione threadBindings per canale per l'abilitazione, i timeout e 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 di associazione automatica alla generazione sono specifiche dell'adapter. Vedi Canali che supportano i thread sopra.

Vedi Riferimento di configurazione e Comandi slash per i dettagli correnti degli adapter.

Allowlist

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

Rilevamento

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

Le voci allowAgents devono puntare a id agente configurati in agents.list[]. ["*"] indica qualsiasi agente target configurato più il richiedente. Se una configurazione agente viene eliminata ma il suo id resta in allowAgents, sessions_spawn rifiuta quell'id e agents_list lo omette. Esegui openclaw doctor --fix per pulire le voci allowlist obsolete, oppure aggiungi una voce minima agents.list[] quando il target deve restare generabile ereditando i valori predefiniti.

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 (conserva comunque la trascrizione tramite rinomina).
• L'archiviazione automatica è best-effort; i timer in sospeso vengono persi se il gateway si riavvia.
• I timeout di esecuzione configurati non archiviano automaticamente; interrompono solo l'esecuzione. La sessione resta fino all'archiviazione automatica.
• L'archiviazione automatica si applica allo stesso modo 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 quando l'esecuzione termina, anche se il record di trascrizione/sessione viene conservato.

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: main → 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 (0 = no timeout)        announceTimeoutMs: 120000, // per-call gateway announce timeout      },    },  },}

Livelli di profondità

Catena di annuncio

I risultati risalgono la catena:

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

Ogni livello vede solo gli annunci dei propri figli diretti.

Criterio degli strumenti per profondità

• Ruolo e ambito di controllo vengono scritti nei metadati della sessione al momento dello spawn. Questo impedisce a chiavi di sessione piatte o ripristinate di riottenere accidentalmente privilegi da orchestratore.
• Profondità 1 (orchestratore, quando maxSpawnDepth >= 2): riceve sessions_spawn, subagents, sessions_list, sessions_history così può generare figli e ispezionarne lo stato. 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 a 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 un fan-out incontrollato 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 main arresta tutti gli agenti di profondità 1 e si propaga ai loro figli di profondità 2.

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 main vengono uniti come fallback; i profili agente sovrascrivono i profili main in caso di conflitti.

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

Annuncio

I sotto-agenti riportano i risultati 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 il testo assistant più recente è il token silenzioso esatto NO_REPLY / no_reply, l'output dell'annuncio viene soppresso anche se in precedenza esistevano progressi visibili.

La consegna dipende dalla profondità del richiedente:

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

Per le sessioni richiedenti di primo livello, la consegna diretta in modalità completamento prima risolve qualsiasi route di conversazione/thread associata e override dell'hook, poi completa i campi channel-target 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 figlio è limitata all'esecuzione corrente del richiedente quando si costruiscono i risultati di completamento annidati, impedendo agli output figlio di esecuzioni precedenti obsolete di trapelare nell'annuncio corrente. Le risposte di annuncio preservano il routing 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 non riuscite riportano lo stato di errore senza riprodurre il testo di risposta acquisito. L'output tool/toolResult non viene promosso a testo del risultato figlio.

Riga delle statistiche

I payload di annuncio includono una riga di statistiche alla fine (anche quando wrappati):

• Runtime (per esempio runtime 5m12s).
• Uso dei token (input/output/totale).
• Costo stimato quando il prezzo del modello è configurato (models.providers.*.models[].cost).
• sessionKey, sessionId e percorso della trascrizione così l'agente main 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 nella normale voce assistant.

Perché preferire sessions_history

sessions_history è il percorso di orchestrazione più sicuro:

• Il richiamo assistant viene prima normalizzato: tag di ragionamento rimossi; scaffolding <relevant-memories> / <relevant_memories> rimosso; blocchi di payload XML di chiamata strumento in testo semplice (<tool_call>, <function_call>, <tool_calls>, <function_calls>) rimossi, inclusi payload troncati che non si chiudono correttamente; scaffolding tool-call/result declassato e marcatori di contesto storico rimossi; token di controllo del modello trapelati (<|assistant|>, altri ASCII <|...|>, full-width <｜...｜>) rimossi; XML di chiamata strumento MiniMax malformato rimosso.
• Il testo simile a credenziali/token viene redatto.
• I blocchi lunghi possono essere troncati.
• Le cronologie molto grandi possono eliminare righe più vecchie o sostituire una riga sovradimensionata con [sessions_history omitted: message too large].
• Usa nextOffset quando presente per sfogliare all'indietro finestre di trascrizione più vecchie.
• L'ispezione della trascrizione grezza su disco è il fallback quando serve la trascrizione completa 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, OpenClaw applica il livello di restrizione del sotto-agente.

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

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn
• message

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

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 il set 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 del 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 lane dedicata in coda in-process:

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

Liveness e ripristino

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

Dopo un riavvio del Gateway, le esecuzioni ripristinate obsolete e non terminate vengono eliminate a meno che la loro sessione figlia sia marcata abortedLastRun: true. Quelle sessioni figlie interrotte dal riavvio restano recuperabili tramite il flusso di recupero orfani dei sotto-agenti, 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 orfani dentro la finestra rapida di nuovo blocco, OpenClaw persiste una tombstone di recupero su quella 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 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 qualsiasi esecuzione sotto-agente attiva generata da essa, propagandosi ai figli annidati.

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 come una valvola di sicurezza.
• sessions_spawn è sempre non bloccante: restituisce { status: "accepted", runId, childSessionKey } immediatamente.
• Il contesto del sotto-agente inietta solo AGENTS.md e TOOLS.md (nessun SOUL.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md o BOOTSTRAP.md). I sotto-agenti nativi Codex seguono lo stesso confine: TOOLS.md resta nelle istruzioni del thread Codex ereditate, mentre i file persona, identità e utente solo del genitore vengono iniettati come istruzioni di collaborazione limitate al turno così i figli non li clonano.
• 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