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 orkestratiepatronen 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, transcriptiepad, opschoning). /subagents log toont recente chatbeurten voor een run; voeg het token tools toe om berichten voor toolaanroepen en -resultaten op te nemen (standaard weggelaten). Gebruik sessions_history voor een begrensde, op veiligheid gefilterde weergave vanuit een agentbeurt, of inspecteer het transcriptiepad op schijf voor de onbewerkte volledige transcriptie.

In de Control UI hebben bovenliggende sessies met recente onderliggende runs een uitvouwbare zijbalkrij. De geneste rijen tonen de status en looptijd van onderliggende agents, en wanneer je er een selecteert, wordt de chat van die onderliggende agent geopend met behoud van de bovenliggende hiërarchie.

Besturing voor threadbinding

Deze opdrachten werken op 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 worden als interne gebeurtenissen in de bovenliggende sessie teruggestuurd; 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 de huidige transcriptie 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 globale 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 coding-profiel bevat sessions_spawn; messaging en minimal bevatten dit 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 kanaal/groep, provider, sandbox en toestaan/weigeren per agent kan de tool na de profielfase nog steeds verwijderen. Gebruik /tools vanuit dezelfde sessie om de effectieve lijst met tools 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). Spawns van de ACP-runtime gebruiken hetzelfde geconfigureerde sub-agentmodel wanneer dit aanwezig is; anders behoudt de ACP-harness zijn eigen standaardwaarde. Een expliciete sessions_spawn.model heeft nog steeds voorrang.
• Redeneren: native sub-agents nemen de instelling van de aanroeper over, tenzij je agents.defaults.subagents.thinking instelt (of agents.list[].subagents.thinking per agent). Spawns van 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.
• Time-out van run: OpenClaw gebruikt agents.defaults.subagents.runTimeoutSeconds wanneer dit is ingesteld; anders valt het terug op 0 (geen time-out). sessions_spawn accepteert geen time-outoverschrijvingen per aanroep.
• Taaklevering: native sub-agents ontvangen de gedelegeerde taak in hun eerste zichtbare [Subagent Task]-bericht. De systeemprompt van de sub-agent bevat runtimeregels en routeringscontext, geen verborgen duplicaat van de taak.

Geaccepteerde spawns van native sub-agents bevatten de vastgestelde modelmetadata van de onderliggende agent in het toolresultaat: resolvedModel bevat de toegepaste modelreferentie en resolvedProvider bevat het providerprefix wanneer de referentie er een heeft.

Modus voor delegatieprompt

agents.defaults.subagents.delegationMode bepaalt alleen de promptrichtlijnen; dit 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 uitgebreider is dan een direct antwoord via sessions_spawn te delegeren.

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

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

Toolparameters

Taaknamen en doelen

taskName is een modelgerichte naam voor orkestratie, geen sessiesleutel. Gebruik deze voor stabiele kindnamen zoals review_subagents, linux_validation of docs_update wanneer een coördinator dat kind later mogelijk moet inspecteren.

Doelresolutie accepteert exacte overeenkomsten met taskName en eenduidige voorvoegsels. Overeenkomsten zijn beperkt tot hetzelfde actieve/recente doelvenster dat wordt gebruikt door genummerde /subagents-doelen, zodat een verouderd voltooid kind een hergebruikte naam niet dubbelzinnig maakt. Als twee actieve of recente kinderen dezelfde taskName delen, is het doel dubbelzinnig; gebruik dan de lijstindex, sessiesleutel of uitvoerings-id.

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

Tool: sessions_yield

Beëindigt de huidige modelbeurt en wacht tot runtimegebeurtenissen, voornamelijk voltooiingsgebeurtenissen van subagenten, als het volgende bericht binnenkomen. Gebruik dit na het starten van vereist kindwerk wanneer de aanvrager geen definitief antwoord kan geven totdat deze voltooiingen zijn binnengekomen.

sessions_yield is het wachtmechanisme. Vervang dit niet door pollinglussen over subagents, sessions_list, sessions_history, shell- sleep of procespolling alleen om te detecteren dat een kind is voltooid.

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

Wanneer er actieve kinderen bestaan, voegt OpenClaw een compact, door de runtime gegenereerd Active Subagents-promptblok toe aan normale beurten, zodat de aanvrager de huidige kindsessies, 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 opgegeven startargumenten.

Tool: subagents

Geeft een overzicht van gestarte subagentuitvoeringen die eigendom zijn van de aanvragende sessie. Het bereik is beperkt tot de huidige aanvrager; een kind kan alleen zijn eigen beheerde kinderen zien.

Gebruik subagents voor status 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 gekoppeld blijven aan een thread, zodat vervolgberichten van gebruikers in die thread naar dezelfde subagentsessie blijven worden gerouteerd.

Kanalen met threadondersteuning

Een kanaal ondersteunt permanente, 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 kindthread aan; Telegram en iMessage koppelen standaard het huidige gesprek. Gebruik de kanaalspecifieke threadBindings-configuratiesleutels voor inschakeling, time-outs en spawnSessions.

Snel proces

Handmatige besturing

Configuratieschakelaars

• Algemene standaardwaarde: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Kanaaloverschrijving en sleutels voor automatisch koppelen bij starten zijn adapterspecifiek. Zie Kanalen met threadondersteuning hierboven.

Zie Configuratiereferentie en Slash-opdrachten voor actuele adapterdetails.

Toegestane lijst

Als de aanvragende sessie in een sandbox wordt uitgevoerd, weigert sessions_spawn doelen die zonder sandbox zouden worden uitgevoerd.

Detectie

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

allowAgents-vermeldingen 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 agents.list[]-vermelding toe wanneer het doel beschikbaar moet blijven om te starten en daarbij standaardwaarden moet overnemen.

Automatisch archiveren

• Subagentsessies worden automatisch gearchiveerd na agents.defaults.subagents.archiveAfterMinutes (standaard 60).
• Bij 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 via hernoemen).
• Automatisch archiveren 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.
• Automatisch archiveren geldt in gelijke mate voor sessies op diepte 1 en diepte 2.
• Browseropschoning staat los van archiveringsopschoning: bijgehouden browsertabbladen/-processen worden naar beste vermogen gesloten wanneer de uitvoering is voltooid, zelfs als het transcript/de sessieregistratie wordt behouden.

Geneste subagenten

Subagenten kunnen standaard niet hun eigen subagenten starten (maxSpawnDepth: 1). Stel maxSpawnDepth: 2 in om één niveau van nesting in te schakelen — het orkestratorpatroon: hoofdagent → orkestrator-subagent → werker-subsubagenten.

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // sta toe dat subagenten kinderen starten (standaard: 1, bereik 1-5)        maxChildrenPerAgent: 5, // maximaal aantal actieve kinderen per agentsessie (standaard: 5, bereik 1-20)        maxConcurrent: 8, // algemene limiet voor gelijktijdige uitvoeringen (standaard: 8)        runTimeoutSeconds: 900, // standaardtime-out voor sessions_spawn (0 = geen time-out)        announceTimeoutMs: 120000, // Gateway-time-out per aanroep voor aankondigingen      },    },  },}

Diepteniveaus

Aankondigingsketen

Resultaten stromen terug omhoog door de keten:

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

Elk niveau ziet alleen aankondigingen van zijn directe kinderen.

Toolbeleid per diepte

• Rol en besturingsbereik worden bij het starten in de sessiemetagegevens vastgelegd. Daardoor krijgen platte of herstelde sessiesleutels niet per ongeluk opnieuw orchestratorrechten.
• Diepte 1 (orchestrator, wanneer maxSpawnDepth >= 2): krijgt sessions_spawn, subagents, sessions_list, sessions_history zodat deze kinderen kan starten en hun status kan bekijken. Andere sessie-/systeemtools blijven geweigerd.
• Diepte 1 (eindagent, 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 onbeheerste 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 agents op diepte 1 en stopt trapsgewijs hun kinderen op diepte 2.

Authenticatie

Authenticatie voor subagents 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.

De samenvoeging is additief, zodat hoofdprofielen altijd als terugvalopties beschikbaar zijn. Volledig geïsoleerde authenticatie per agent wordt nog niet ondersteund.

Aankondiging

Subagents rapporteren terug via een aankondigingsstap:

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

De levering is afhankelijk van de diepte van de aanvrager:

• Aanvragersessies op het hoogste niveau gebruiken een vervolgaanroep naar agent met externe levering (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 aanvragersessies op het hoogste niveau bepaalt rechtstreekse levering in voltooiingsmodus eerst een eventuele gekoppelde conversatie-/threadroute en hook-override, en vult daarna ontbrekende kanaal-doelvelden aan vanuit de opgeslagen route van de aanvragersessie. Daardoor komen voltooiingen in de juiste chat/het juiste onderwerp terecht, 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 thread-/onderwerproutering op kanaaladapters.

Aankondigingscontext

De aankondigingscontext wordt genormaliseerd tot een stabiel intern gebeurtenisblok:

Mislukte beëindigde uitvoeringen rapporteren een foutstatus zonder vastgelegde antwoordtekst opnieuw af te spelen. Uitvoer van tools/toolResult wordt niet gepromoveerd tot resultaattekst van het kind.

Statistiekenregel

Aankondigingspayloads bevatten aan het einde een statistiekenregel (ook wanneer ze zijn omwikkeld):

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

Interne metagegevens zijn alleen bedoeld voor orchestratie; gebruikersgerichte antwoorden moeten worden herschreven in de normale assistentstijl.

Waarom sessions_history de voorkeur heeft

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

• Censureert tekst die op inloggegevens/tokens lijkt, zelfs wanneer algemene logcensurering 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 indien aanwezig om achterwaarts door oudere transcriptvensters te bladeren.
• sessions_history verwijdert geen redeneringstags, <relevant-memories>-steigerwerk of toolaanroep-XML uit berichttekst — het retourneert gestructureerde inhoudsblokken die dicht bij de ruwe transcriptvorm liggen, maar gecensureerd en in omvang begrensd. /subagents log past de zwaardere prozareiniger toe (verwijdert redeneringstags, geheugensteigerwerk en toolaanroep-XML), omdat deze 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

Subagents gebruiken eerst dezelfde profiel- en toolbeleidspijplijn als de bovenliggende of doelagent. Daarna past OpenClaw de beperkingslaag voor subagents toe.

Subagents 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). Eindsubagents (standaardgedrag op diepte 1, en altijd op diepte 2) verliezen daarnaast subagents, sessions_list, sessions_history en sessions_spawn. Subagents krijgen nooit de tool message — deze wordt bij het starten uitgeschakeld, niet door deze weigeringslijst gefilterd — en sessions_send blijft geweigerd, zodat subagents uitsluitend via de aankondigingsketen communiceren.

sessions_history blijft ook hier een begrensde, opgeschoonde herinneringsweergave — het is geen ruwe transcriptdump.

Wanneer maxSpawnDepth >= 2, ontvangen orchestrator-subagents 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: {        // weigeren heeft voorrang        deny: ["gateway", "cron"],        // als toestaan is ingesteld, wordt dit uitsluitend-toestaan (weigeren heeft nog steeds voorrang)        // allow: ["read", "exec", "process"]      },    },  },}

tools.subagents.tools.allow is een definitief uitsluitend-toestaan-filter. Het kan de reeds bepaalde toolset beperken, maar kan geen tool terugtoevoegen die door tools.profile is verwijderd. tools.profile: "coding" bevat bijvoorbeeld web_search/web_fetch, maar niet de tool browser. Als subagents met een codeerprofiel browserautomatisering mogen gebruiken, voeg je 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

Subagents gebruiken een speciale wachtrijstrook binnen het proces:

• Naam van strook: subagent
• Gelijktijdigheid: agents.defaults.subagents.maxConcurrent (standaard 8)

Beschikbaarheid 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 behandeling 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 als abortedLastRun: true. Door een herstart afgebroken uitvoeringen blijven geregistreerd voor de herstelstroom voor verweesde subagents: verouderde uitvoeringen worden zonder hervatting afgerond, 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 snel opnieuw vastlopen herhaaldelijk voor herstel van verweesde processen wordt geaccepteerd, slaat OpenClaw een herstelgrafsteen voor die sessie op en stopt het bij latere herstarts met automatisch hervatten. Voer openclaw tasks maintenance --apply uit om de taakregistratie te vereffenen, of openclaw doctor --fix om verouderde afgebroken herstelmarkeringen te wissen voor sessies met een grafsteen.

Stoppen

• Door /stop in de chat van de aanvrager te verzenden, wordt de sessie van de aanvrager afgebroken en worden alle actieve sub-agentuitvoeringen gestopt die vanuit deze sessie zijn gestart, inclusief geneste onderliggende uitvoeringen.

Beperkingen

• Aankondigingen van sub-agents worden naar beste vermogen uitgevoerd. Als de Gateway opnieuw wordt gestart, gaan openstaande taken voor 'terugmelden' verloren.
• Sub-agents delen nog steeds dezelfde procesresources van de Gateway; beschouw maxConcurrent als een veiligheidsklep.
• sessions_spawn is altijd niet-blokkerend: deze retourneert onmiddellijk { status: "accepted", runId, childSessionKey }.
• De context van een sub-agent injecteert alleen AGENTS.md en TOOLS.md (geen SOUL.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md of BOOTSTRAP.md). Codex-native sub-agents volgen dezelfde grens: TOOLS.md blijft in de overgenomen Codex-threadinstructies, terwijl persona-, identiteits- en gebruikersbestanden die alleen voor de ouder gelden, worden geïnjecteerd als samenwerkingsinstructies voor de huidige beurt, zodat onderliggende agents deze niet klonen.
• De maximale nestingsdiepte is 5 (bereik van maxSpawnDepth: 1-5). Diepte 2 wordt aanbevolen voor de meeste gebruikssituaties.
• maxChildrenPerAgent beperkt het aantal actieve onderliggende agents per sessie (standaard 5, bereik 1-20).

Gerelateerd

• Sessietools en statuswijzigingen
• ACP-agents
• Agent verzenden
• Achtergrondtaken
• Sandbox-tools voor meerdere agents