Subagenten

Sub-agents zijn agentruns op de achtergrond die vanuit een bestaande agentrun worden gestart. Elke sub-agent draait in een eigen sessie (agent:<agentId>:subagent:<uuid>) en kondigt na voltooiing het resultaat aan in het chatkanaal van de aanvrager. Elke sub-agentrun wordt bijgehouden als een achtergrondtaak.

Doelen:

• Onderzoek, langdurige taken en traag toolwerk parallel uitvoeren zonder de hoofdrun te blokkeren.
• Sub-agents standaard geïsoleerd houden (gescheiden sessies, optionele sandboxing).
• Zorgen dat de toolset moeilijk verkeerd te gebruiken is: sub-agents krijgen standaard geen sessie- of berichttools.
• Configureerbare nestingsdiepte voor orchestratorpatronen ondersteunen.

Slash-opdracht

/subagents inspecteert sub-agentruns voor de huidige sessie:

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

/subagents info toont metadata van de run (status, tijdstempels, sessie-id, transcriptpad, opschoning). /subagents log toont recente chatbeurten van een run; voeg het token tools toe om berichten van toolaanroepen en -resultaten op te nemen (standaard weggelaten). Gebruik sessions_history voor een begrensde, op veiligheid gefilterde terugblik vanuit een agentbeurt, of inspecteer het transcriptpad op schijf voor het onbewerkte volledige transcript.

Besturing voor threadbinding

Deze opdrachten werken in kanalen met persistente threadbindingen. Zie Kanalen die threads ondersteunen hieronder.

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

Startgedrag

Agents starten sub-agents op de achtergrond met de tool sessions_spawn. Voltooiingen keren terug als interne gebeurtenissen van de bovenliggende sessie; de bovenliggende/aanvragende agent beslist of een zichtbare update voor de gebruiker nodig is.

Contextmodi

Native sub-agents starten geïsoleerd, tenzij de aanroeper expliciet vraagt om het huidige transcript te vertakken.

Gebruik fork spaarzaam. Het is bedoeld voor contextgevoelige delegatie, niet als vervanging voor het schrijven van een duidelijke taakprompt.

Tool: sessions_spawn

Start een sub-agentrun met deliver: false op de algemene subagent-lane, voert vervolgens een aankondigingsstap uit en plaatst het aankondigingsantwoord in het chatkanaal van de aanvrager.

De beschikbaarheid hangt af van het effectieve toolbeleid van de aanroeper. Het ingebouwde profiel coding bevat sessions_spawn; messaging en minimal niet. full staat elke tool toe. Voeg tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"] toe, of gebruik tools.profile: "coding", voor agents met een beperkter profiel die toch werk moeten kunnen delegeren. Beleid voor kanalen/groepen, providers, sandboxen en toestaan/weigeren per agent kan de tool na de profielfase nog steeds verwijderen. Gebruik /tools vanuit dezelfde sessie om de effectieve toollijst te bevestigen.

Standaardwaarden:

• Model: native sub-agents nemen het model van de aanroeper over, tenzij je agents.defaults.subagents.model instelt (of agents.list[].subagents.model per agent). Starts met de ACP-runtime gebruiken hetzelfde geconfigureerde sub-agentmodel wanneer dat aanwezig is; anders behoudt de ACP-harness zijn eigen standaardwaarde. Een expliciete sessions_spawn.model heeft nog steeds voorrang.
• Denkproces: native sub-agents nemen het denkproces van de aanroeper over, tenzij je agents.defaults.subagents.thinking instelt (of agents.list[].subagents.thinking per agent). Starts met de ACP-runtime passen ook agents.defaults.models["provider/model"].params.thinking toe voor het geselecteerde model. Een expliciete sessions_spawn.thinking heeft nog steeds voorrang.
• Runtimelimiet: OpenClaw gebruikt agents.defaults.subagents.runTimeoutSeconds wanneer dit is ingesteld; anders valt het terug op 0 (geen limiet). sessions_spawn accepteert geen overschrijvingen van de limiet per aanroep.
• Taakaflevering: native sub-agents ontvangen de gedelegeerde taak in hun eerste zichtbare bericht [Subagent Task]. De systeemprompt van de sub-agent bevat runtimeregels en routeringscontext, niet een verborgen duplicaat van de taak.

Geaccepteerde starts van native sub-agents bevatten de opgeloste metadata van het child-model in het toolresultaat: resolvedModel bevat de toegepaste modelreferentie en resolvedProvider bevat het providerprefix wanneer de referentie er een heeft.

Modus voor delegatieprompts

agents.defaults.subagents.delegationMode bepaalt alleen de promptrichtlijnen; het wijzigt het toolbeleid niet en dwingt delegatie niet af.

• suggest (standaard): behoud de standaardaanwijzing in de prompt om sub-agents te gebruiken voor groter of trager werk.
• prefer: draag de hoofdagent op responsief te blijven en alles wat meer omvat dan een direct antwoord via sessions_spawn te delegeren.

Overschrijving per agent: agents.list[].subagents.delegationMode.

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

Toolparameters

Taaknamen en doelbepaling

taskName is een modelgerichte aanduiding voor orkestratie, geen sessiesleutel. Gebruik deze voor stabiele namen van onderliggende processen, zoals review_subagents, linux_validation of docs_update, wanneer een coördinator dat onderliggende proces later mogelijk moet inspecteren.

Doelresolutie accepteert exacte overeenkomsten met taskName en eenduidige voorvoegsels. Overeenkomsten zijn beperkt tot hetzelfde venster met actieve/recente doelen dat wordt gebruikt door genummerde /subagents-doelen, zodat een verouderd voltooid onderliggend proces een hergebruikte aanduiding niet dubbelzinnig maakt. Als twee actieve of recente onderliggende processen dezelfde taskName delen, is het doel dubbelzinnig; gebruik in plaats daarvan de lijstindex, sessiesleutel of uitvoerings-id.

De gereserveerde doelen last en all zijn geen geldige taskName-waarden, omdat ze al een besturingsbetekenis hebben.

Hulpmiddel: sessions_yield

Beëindigt de huidige modelbeurt en wacht tot runtimegebeurtenissen, voornamelijk voltooiingsgebeurtenissen van subagents, als het volgende bericht binnenkomen. Gebruik dit na het starten van vereist onderliggend werk wanneer de aanvrager geen definitief antwoord kan geven voordat die voltooiingen zijn binnengekomen.

sessions_yield is het wachtmechanisme. Vervang dit niet door pollinglussen over subagents, sessions_list, sessions_history, shellopdrachten met sleep of procespolling, alleen om de voltooiing van een onderliggend proces te detecteren.

Gebruik sessions_yield alleen wanneer de effectieve hulpmiddelenlijst van de sessie dit bevat. Sommige minimale of aangepaste hulpmiddelprofielen kunnen sessions_spawn en subagents beschikbaar stellen zonder sessions_yield; bedenk in dat geval geen pollinglus alleen om op voltooiing te wachten.

Wanneer er actieve onderliggende processen zijn, voegt OpenClaw een compact, door de runtime gegenereerd promptblok Active Subagents toe aan normale beurten, zodat de aanvrager de huidige onderliggende sessies, uitvoerings-id's, statussen, labels, taken en taskName-aliassen kan zien zonder polling. De taak- en labelvelden in dat blok worden als gegevens aangehaald, niet als instructies, omdat ze afkomstig kunnen zijn uit door de gebruiker of het model verstrekte startargumenten.

Hulpmiddel: subagents

Toont gestarte uitvoeringen van subagents die eigendom zijn van de aanvragende sessie. Dit is beperkt tot de huidige aanvrager; een onderliggend proces kan alleen zijn eigen aangestuurde onderliggende processen zien.

Gebruik subagents voor statuscontroles en foutopsporing op aanvraag. Gebruik sessions_yield om op voltooiingsgebeurtenissen te wachten.

Aan threads gekoppelde sessies

Wanneer threadkoppelingen voor een kanaal zijn ingeschakeld, kan een subagent aan een thread gekoppeld blijven, zodat vervolgberichten van gebruikers in die thread naar dezelfde subagentsessie blijven worden doorgestuurd.

Kanalen die threads ondersteunen

Een kanaal ondersteunt blijvende, aan threads gekoppelde subagentsessies (sessions_spawn met thread: true) wanneer het een adapter voor gesprekskoppeling registreert. Meegeleverde kanalen met deze ondersteuning: Discord, iMessage, Matrix en Telegram. Discord en Matrix maken standaard een onderliggende thread; Telegram en iMessage koppelen standaard het huidige gesprek. Gebruik de threadBindings-configuratiesleutels per kanaal voor inschakeling, time-outs en spawnSessions.

Snelle werkwijze

Handmatige bediening

Configuratieschakelaars

• Algemene standaard: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Kanaaloverschrijvingen en sleutels voor automatische koppeling bij het starten zijn adapterspecifiek. Zie Kanalen die threads ondersteunen hierboven.

Zie Configuratiereferentie en Slash-opdrachten voor actuele adapterdetails.

Toegestane lijst

Als de aanvragende sessie in een sandbox draait, weigert sessions_spawn doelen die zonder sandbox zouden draaien.

Detectie

Gebruik agents_list om te zien welke agent-id's momenteel zijn toegestaan voor sessions_spawn. Het antwoord bevat het effectieve model en de ingebedde runtimemetadata van elke vermelde agent, zodat aanroepers onderscheid kunnen maken tussen OpenClaw, de Codex-appserver en andere geconfigureerde systeemeigen runtimes.

Vermeldingen in allowAgents moeten verwijzen naar geconfigureerde agent-id's in agents.list[]. ["*"] betekent elke geconfigureerde doelagent plus de aanvrager. Als een agentconfiguratie wordt verwijderd maar de id ervan in allowAgents blijft staan, weigert sessions_spawn die id en laat agents_list deze weg. Voer openclaw doctor --fix uit om verouderde vermeldingen uit de toegestane lijst op te schonen, of voeg een minimale vermelding aan agents.list[] toe wanneer het doel gestart moet kunnen blijven worden terwijl het de standaardwaarden erft.

Automatisch archiveren

• Subagentsessies worden automatisch gearchiveerd na agents.defaults.subagents.archiveAfterMinutes (standaard 60).
• Voor archivering wordt sessions.delete gebruikt en wordt het transcript hernoemd naar *.deleted.<timestamp> (dezelfde map).
• cleanup: "delete" archiveert onmiddellijk na de aankondiging (het transcript blijft behouden door het te hernoemen).
• Automatische archivering gebeurt naar beste vermogen; wachtende timers gaan verloren als de Gateway opnieuw wordt gestart.
• Geconfigureerde uitvoeringstime-outs archiveren niet automatisch; ze stoppen alleen de uitvoering. De sessie blijft bestaan tot automatische archivering.
• Automatische archivering is in gelijke mate van toepassing op sessies van diepte 1 en diepte 2.
• Browseropschoning staat los van archiveringsopschoning: bijgehouden browsertabbladen/-processen worden naar beste vermogen gesloten wanneer de uitvoering eindigt, zelfs als het transcript/de sessieregistratie behouden blijft.

Geneste subagents

Subagents kunnen standaard niet hun eigen subagents starten (maxSpawnDepth: 1). Stel maxSpawnDepth: 2 in om één niveau van nesting mogelijk te maken — het orkestratorpatroon: hoofdproces → orkestrator-subagent → onderliggende werkersubagents.

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1, range 1-5)        maxChildrenPerAgent: 5, // max active children per agent session (default: 5, range 1-20)        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      },    },  },}

Diepteniveaus

Aankondigingsketen

Resultaten stromen terug omhoog door de keten:

1. Werker op diepte 2 is klaar → kondigt dit aan zijn ouder aan (orchestrator op diepte 1).
2. Orchestrator op diepte 1 ontvangt de aankondiging, voegt de resultaten samen, rondt af → kondigt dit aan de hoofdagent aan.
3. De hoofdagent ontvangt de aankondiging en levert deze aan de gebruiker.

Elk niveau ziet alleen aankondigingen van zijn directe kinderen.

Toolbeleid per diepte

• Rol en beheerbereik worden bij het starten in de sessiemetadata geschreven. Zo kunnen vlakke of herstelde sessiesleutels niet per ongeluk opnieuw orchestratorrechten krijgen.
• Diepte 1 (orchestrator, wanneer maxSpawnDepth >= 2): krijgt sessions_spawn, subagents, sessions_list, sessions_history, zodat deze kinderen kan starten en hun status kan controleren. Andere sessie-/systeemtools blijven geweigerd.
• Diepte 1 (eindwerker, wanneer maxSpawnDepth == 1): geen sessietools (huidig standaardgedrag).
• Diepte 2 (eindwerker): geen sessietools — sessions_spawn wordt op diepte 2 altijd geweigerd. Kan geen verdere kinderen starten.

Startlimiet per agent

Elke agentsessie (op elke diepte) kan maximaal maxChildrenPerAgent (standaard 5) actieve kinderen tegelijk hebben. Dit voorkomt ongecontroleerde vertakking vanuit één orchestrator.

Trapsgewijs stoppen

Als een orchestrator op diepte 1 wordt gestopt, worden automatisch al diens kinderen op diepte 2 gestopt:

• /stop in de hoofdchat stopt alle agenten op diepte 1 en laat dit doorwerken naar hun kinderen op diepte 2.

Authenticatie

Authenticatie van subagenten wordt bepaald op basis van agent-id, niet op basis van sessietype:

• De sessiesleutel van de subagent is agent:<agentId>:subagent:<uuid>.
• De authenticatieopslag wordt geladen vanuit de agentDir van die agent.
• De authenticatieprofielen van de hoofdagent worden als terugvaloptie samengevoegd; agentprofielen hebben bij conflicten voorrang op hoofdprofielen.

Het samenvoegen is additief, zodat hoofdprofielen altijd beschikbaar zijn als terugvaloptie. Volledig geïsoleerde authenticatie per agent wordt nog niet ondersteund.

Aankondiging

Subagenten rapporteren terug via een aankondigingsstap:

• De aankondigingsstap wordt uitgevoerd binnen de sessie van de subagent (niet binnen de sessie van de aanvrager).
• Als de subagent exact ANNOUNCE_SKIP antwoordt, wordt er niets geplaatst.
• Als de recentste assistenttekst exact het stille token NO_REPLY / no_reply is, wordt de aankondigingsuitvoer onderdrukt, zelfs als er eerder zichtbare voortgang was.

De aflevering is afhankelijk van de diepte van de aanvrager:

• Sessies van aanvragers op het hoogste niveau gebruiken een vervolgaanroep naar agent met externe aflevering (deliver=true).
• Geneste subagentsessies van aanvragers ontvangen een interne vervolginjectie (deliver=false), zodat de orchestrator de resultaten van kinderen binnen de sessie kan samenvoegen.
• Als een geneste subagentsessie van een aanvrager niet meer bestaat, valt OpenClaw waar mogelijk terug op de aanvrager van die sessie.

Voor sessies van aanvragers op het hoogste niveau bepaalt rechtstreekse aflevering in voltooiingsmodus eerst een eventueel gekoppelde gespreks-/threadroute en hook-overschrijving, en vult daarna ontbrekende kanaal-doelvelden aan vanuit de opgeslagen route van de aanvragerssessie. Zo blijven voltooiingen in de juiste chat/het juiste onderwerp, zelfs wanneer de oorsprong van de voltooiing alleen het kanaal identificeert.

Bij het opbouwen van geneste voltooiingsbevindingen wordt de aggregatie van voltooiingen van kinderen beperkt tot de huidige uitvoering van de aanvrager, zodat verouderde uitvoer van kinderen uit eerdere uitvoeringen niet in de huidige aankondiging terechtkomt. Aankondigingsantwoorden behouden waar beschikbaar de routering van threads/onderwerpen via kanaaladapters.

Aankondigingscontext

De aankondigingscontext wordt genormaliseerd naar een stabiel intern gebeurtenisblok:

Mislukte definitieve uitvoeringen rapporteren de foutstatus zonder vastgelegde antwoordtekst opnieuw af te spelen. Uitvoer van tools/toolResult wordt niet opgenomen in de resultaattekst van het kind.

Statistiekregel

Aankondigingspayloads bevatten aan het einde een statistiekregel (ook wanneer ze zijn ingepakt):

• Uitvoeringstijd (bijvoorbeeld runtime 5m12s).
• Tokengebruik (invoer/uitvoer/totaal).
• Geschatte kosten wanneer modelprijzen zijn geconfigureerd (models.providers.*.models[].cost).
• sessionKey, sessionId en het transcriptpad, zodat de hoofdagent de geschiedenis via sessions_history kan ophalen of het bestand op schijf kan inspecteren.

Interne metadata zijn uitsluitend bedoeld voor orchestratie; gebruikersgerichte antwoorden moeten in normale assistenttaal worden herschreven.

Waarom sessions_history de voorkeur heeft

sessions_history is het veiligere orchestratiepad om binnen een agentbeurt het transcript van een kind te lezen:

• Maskeert tekst die op aanmeldgegevens/tokens lijkt, zelfs wanneer algemene logmaskering is uitgeschakeld.
• Kapt lange tekstblokken af (4000 tekens per blok) en verwijdert denksignaturen, payloads voor het opnieuw afspelen van redeneringen en inline afbeeldingsgegevens.
• Dwingt een responslimiet van 80 KB af; te grote rijen worden vervangen door [sessions_history omitted: message too large].
• Gebruik nextOffset wanneer dit aanwezig is om terug te bladeren door oudere transcriptvensters.
• sessions_history verwijdert geen redeneringstags, <relevant-memories>-structuren of XML van toolaanroepen uit berichttekst — het retourneert gestructureerde inhoudsblokken die dicht bij de ruwe transcriptvorm blijven, maar dan gemaskeerd en in omvang begrensd. /subagents log past de zwaardere prozafilter toe (verwijdert redeneringstags, geheugenstructuren en XML van toolaanroepen), omdat het gewone chatregels weergeeft in plaats van gestructureerde blokken.
• Inspectie van het ruwe transcript op schijf is de terugvaloptie wanneer je het volledige byte-voor-byte-transcript nodig hebt.

Toolbeleid

Subagenten gebruiken eerst dezelfde profiel- en toolbeleidspijplijn als de ouder- of doelagent. Daarna past OpenClaw de beperkingslaag voor subagenten toe.

Subagenten verliezen altijd gateway, agents_list, session_status en cron, ongeacht diepte of rol (tools op systeemniveau/interactieve tools, of tools die de hoofdagent moet coördineren). Subagenten die eindwerker zijn (standaardgedrag op diepte 1 en altijd op diepte 2) verliezen daarnaast subagents, sessions_list, sessions_history en sessions_spawn. Subagenten krijgen nooit de tool message — deze wordt tijdens het starten uitgeschakeld en niet door deze weigeringslijst gefilterd — en sessions_send blijft geweigerd, zodat subagenten uitsluitend via de aankondigingsketen communiceren.

sessions_history blijft ook hier een begrensde, opgeschoonde weergave om informatie terug te halen — het is geen ruwe transcriptdump.

Wanneer maxSpawnDepth >= 2 ontvangen orchestrator-subagenten op diepte 1 daarnaast sessions_spawn, subagents, sessions_list en sessions_history, zodat ze hun kinderen kunnen beheren.

Overschrijven via configuratie

{  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 is een definitief filter dat alleen toestaat wat expliciet is toegestaan. Het kan de reeds bepaalde toolset beperken, maar kan geen tool terugtoevoegen die door tools.profile is verwijderd. Zo bevat tools.profile: "coding" web_search/web_fetch, maar niet de tool browser. Om subagenten met het coderingsprofiel browserautomatisering te laten gebruiken, voeg je de browser toe in de profielfase:

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

Gebruik agents.list[].tools.alsoAllow: ["browser"] per agent wanneer slechts één agent browserautomatisering mag krijgen.

Gelijktijdigheid

Subagenten gebruiken een afzonderlijke wachtrijbaan binnen het proces:

• Baannaam: subagent
• Gelijktijdigheid: agents.defaults.subagents.maxConcurrent (standaard 8)

Levendigheid en herstel

OpenClaw beschouwt het ontbreken van endedAt niet als permanent bewijs dat een subagent nog actief is. Niet-beëindigde uitvoeringen die ouder zijn dan het venster voor verouderde uitvoeringen (2 uur, of de geconfigureerde uitvoeringstime-out plus een korte respijtperiode, afhankelijk van welke langer is) tellen niet langer als actief/in afwachting in /subagents list, statusoverzichten, voltooiingsblokkering voor afstammelingen en gelijktijdigheidscontroles per sessie.

Na een herstart van de Gateway worden verouderde, niet-beëindigde herstelde uitvoeringen verwijderd, tenzij hun onderliggende sessie is gemarkeerd met abortedLastRun: true. Door een herstart afgebroken uitvoeringen blijven geregistreerd voor de herstelstroom voor verweesde subagenten: verouderde uitvoeringen worden definitief afgerond zonder hervatting, terwijl recente onderliggende sessies een synthetisch hervattingsbericht ontvangen voordat de afbreekmarkering wordt gewist.

Automatisch herstel na een herstart is per onderliggende sessie begrensd. Als hetzelfde subagentkind binnen het venster voor snelle herhaalde blokkering meermaals voor herstel van verweesde uitvoeringen wordt geaccepteerd, slaat OpenClaw een herstelgrafsteen op in die sessie en stopt het met automatisch hervatten bij latere herstarts. Voer openclaw tasks maintenance --apply uit om de taakregistratie te herstellen, of openclaw doctor --fix om verouderde afgebroken herstelmarkeringen te wissen voor sessies met een grafsteen.

Stoppen

• Het verzenden van /stop in de chat van de aanvrager breekt de aanvragerssessie af en stopt alle actieve subagentuitvoeringen die daaruit zijn gestart, waarbij dit doorwerkt naar geneste kinderen.

Beperkingen

• Aankondigingen van subagenten worden uitgevoerd op basis van best effort. Als de Gateway opnieuw wordt gestart, gaan wachtende taken voor 'terugmelden' verloren.
• Subagenten delen nog steeds dezelfde procesresources van de Gateway; beschouw maxConcurrent als een veiligheidsklep.
• sessions_spawn is altijd niet-blokkerend: het retourneert onmiddellijk { status: "accepted", runId, childSessionKey }.
• In de context van subagenten worden alleen AGENTS.md en TOOLS.md geïnjecteerd (geen SOUL.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md of BOOTSTRAP.md). Codex-eigen subagenten volgen dezelfde grens: TOOLS.md blijft in de overgenomen instructies van de Codex-thread, terwijl persona-, identiteits- en gebruikersbestanden die uitsluitend voor de ouder gelden, worden geïnjecteerd als samenwerkingsinstructies die tot de huidige beurt beperkt zijn, zodat onderliggende agenten ze niet klonen.
• De maximale nestingsdiepte is 5 (bereik van maxSpawnDepth: 1-5). Diepte 2 wordt voor de meeste toepassingen aanbevolen.
• maxChildrenPerAgent beperkt het aantal actieve onderliggende agenten per sessie (standaard 5, bereik 1-20).

Gerelateerd

• Sessietools en statuswijzigingen
• ACP-agenten
• Verzenden door agent
• Achtergrondtaken
• Sandboxtools voor meerdere agenten