Promise.all, while en if om werk uit te waaieren, resultaten te verzamelen
en beslissingen te nemen.
Er is geen grafiek-DSL en geen afzonderlijke workflowindeling. Het programma is de
orkestratie. Swarm voegt wachtbare collector-kinderen, gestructureerde resultaten,
begrensde gelijktijdigheid en voortgangsrapportage toe aan dat programma.
Swarm inschakelen
Het aanbevolen pad is Settings → Labs → Swarm in de Control UI. De schakelaar wordt onmiddellijk van kracht en schrijfttools.swarm.enabled naar je
configuratie.
Je kunt Swarm ook rechtstreeks inschakelen in openclaw.json:
Numerieke waarden moeten positieve gehele getallen zijn. OpenClaw begrenst
maxConcurrent tot 1–1000, maxChildrenPerGroup tot 1–10000,
maxTotalPerGroup tot 1–100000 en waitTimeoutSecondsMax tot
1–86400.
Je kunt Swarm voor één geconfigureerde agent overschrijven met
agents.entries.*.tools.swarm. Het object per agent wordt over het object
tools.swarm op het hoogste niveau samengevoegd.
Vereisten
De gastglobalenagents.run, phase en log vereisen zowel Swarm als
OpenClaw Code Mode:
sessions_spawn. Toolprofielen,
toestaan/weigeren-beleid, providerregels en sandboxbeleid kunnen die tool verwijderen.
Zie Code Mode activeren en
Subagents als een script meldt dat sessions_spawn niet
beschikbaar is.
defaultAgentId en agentId-waarden per uitvoering moeten een geconfigureerd doel benoemen
dat is toegestaan door het subagents.allowAgents-beleid van de aanvrager. OpenClaw weigert
een onbekend of niet-toegestaan doel in plaats van terug te vallen op een andere agent.
Een Swarm-script schrijven
Wanneer Swarm is ingeschakeld, stelt Code Mode deze gast-API beschikbaar:schema wordt agents.run() omgezet in de uiteindelijke tekst van het kind. Met een
JSON Schema wordt de waarde gebruikt die via de tool structured_output van het kind
is ingediend. Een mislukt, beëindigd, verlopen of schema-ongeldig kind
wijst de promise af met een SwarmAgentError. Lees de exact gegenereerde
declaraties en korte orkestratiepatronen in API.read("agents.d.ts")
binnen Code Mode.
Gebruik label voor een herkenbare kindnaam in het dashboard en de zijbalk. Gebruik
phase in de opties om een fase te publiceren vlak voordat dat kind
begint, of roep phase() aan wanneer meerdere kinderen tot dezelfde fase behoren.
log() publiceert een korte voortgangsmelding. Voortgangsaanroepen zijn fire-and-forget;
ze vertragen het script niet als de UI niet beschikbaar is.
Parallel uitwaaieren met gestructureerde resultaten
Dit voorbeeld start één onderzoeker per onderwerp, wacht op alle onderzoekers en vraagt vervolgens een laatste kind om hun gestructureerde rapporten samen te voegen:Promise.all is de grens voor uitwaaieren en weer samenkomen. OpenClaw start maximaal
maxConcurrent kinderen voor de groep en plaatst de rest in de volgorde van indiening
in de wachtrij.
Code Mode begrenst gelijktijdige aanroepen van de gastbridge afzonderlijk met
tools.codeMode.maxPendingToolCalls (standaard 16, maximaal 128). Start voor zeer
grote groepen begrensde batches onder die limiet en houd ruimte over voor
phase(), log() en wachtovergangen van kinderen. maxConcurrent beperkt uitgevoerde
kinderen; het verhoogt de limiet voor gastbridge-aanroepen niet.
Een beslissingspoort herhaaldelijk controleren
Gebruik een begrensdewhile-lus wanneer elke doorgang bepaalt of nog een doorgang
nodig is:
maxTotalPerGroup is de laatste veiligheidsgrens,
geen vervanging voor een duidelijke stopvoorwaarde.
Het eerste kind verwerken dat klaar is
agents.run() retourneert een gewone promise, zodat Promise.race kan reageren op het
eerste Code Mode-kind. Voor harnesses die de tools op lager niveau aanroepen,
biedt agents_wait dezelfde grens voor de eerste voltooiing: deze retourneert zodra
ten minste één aangevraagde uitvoering is voltooid, of wanneer de begrensde time-out verloopt.
Zie Swarm vanuit andere harnesses gebruiken voor de
volledige afhandelingslus.
Gedrag van collector-kinderen
Collector-kinderen zijn gewone geïsoleerde subagentsessies met een ander voltooiingspad. Ze schrijven een duurzaam collectorresultaat waarop de ouder kan wachten, in plaats van een antwoord terug naar de oudersessie aan te kondigen of te sturen. De doelagent wordt in deze volgorde bepaald:agentIdbij de spawn ofagents.run()-aanroep.tools.swarm.defaultAgentId.- De aanvragende agent.
worker; configureer er een voordat je deze als standaard benoemt.
Versterk die worker met tools.swarm: false in de configuratie per agent, zodat
deze kan worden gestart maar geen swarms kan starten vanuit zijn eigen sessies op het hoogste niveau:
structured_output toe aan
het kind en valideert de payload ervan aan de hand van het opgegeven JSON Schema. Een
ongeldige of ontbrekende payload krijgt één corrigerende aansporing. Als de nieuwe poging nog steeds
niet valideert, behoudt de collectorvoltooiing de onbewerkte tekst van het kind, laat
structured oningesteld en neemt schemaError op. Het resultaat agents_wait op
laag niveau stelt die velden beschikbaar voor expliciete herstellogica.
Kinderen zijn bladeren
Swarm-kinderen zijn standaard bladeren. De universele beveiligingagents.defaults.subagents.maxSpawnDepth voorkomt dat een kind zijn
eigen kinderen start bij de standaarddiepte van 1. Het gebruikelijke orkestratiepatroon is
om werk terug te geven aan de ouder, niet om meer werk vanuit een kind te starten:
agents.defaults.subagents.maxSpawnDepth en worden afgeraden voor Swarm.
Groepslimieten, budgetten en observeerbaarheid gaan allemaal uit van platte collectorgroepen.
Elk kind heeft één toelatingseigenaar. Aankondigings- en interactieve kinderen gebruiken
agents.defaults.subagents.maxChildrenPerAgent (standaard 5) en tellen
collector-kinderen niet mee. Collector-kinderen gebruiken alleen maxChildrenPerGroup en
maxTotalPerGroup; ze verbruiken het kindbudget per sessie niet. De beveiliging voor
spawndiepte blijft voor beide modi gelden.
Na toelating worden kinderen boven maxConcurrent in FIFO-volgorde in de wachtrij geplaatst binnen hun Swarm-
groep, genest in de globale subagentbaan. Deze gelijktijdigheidslagen plaatsen
werk in een wachtrij in plaats van het te weigeren. Een collectorspawn die een van beide groepslimieten
overschrijdt, wordt geweigerd met de relevante configuratiesleutel in de foutmelding.
Een Swarm observeren
Open het dashboard van de oudersessie in de Control UI terwijl een Swarm actief is. De Swarm-widget geeft elke actieve collectorgroep weer als één stip per kind, met de status in wachtrij, actief, voltooid of mislukt. Labels verschijnen in knopinfo bij stippen, waardoor korte, stabiele labels grotere swarms gemakkelijker leesbaar maken. De sessiezijbalk behoudt de normale ouder/kind-boom. Vouw de ouderrij uit om een collector-kind te bekijken of het transcript ervan te openen zonder de Swarm- hiërarchie te verliezen. Collectorresultaten blijven beschikbaar om op te wachten totdat hun groep is gearchiveerd. Nadat elk lid zijn bewaartermijn heeft bereikt, archiveert OpenClaw de onderliggende processen van de groep als batch, zodat voltooide swarms niet in de actieve sessiestructuur blijven staan.Swarm gebruiken vanuit andere harnassen
Je kunt Swarm gebruiken zonder OpenClaw Code Mode. De kerntools zijn onafhankelijk van het harnas: start onderliggende collectorprocessen metsessions_spawn({ collect: true }) en haal hun resultaten op met begrensde agents_wait-
aanroepen.
Codex Code Mode stelt geschikte dynamische OpenClaw-tools automatisch beschikbaar onder
tools.*. Het gebruikt niet de QuickJS-gast-API van OpenClaw en vereist
tools.codeMode niet, maar tools.swarm moet nog steeds zijn ingeschakeld. agents_wait-
aanroepen van het Codex-harnas ondersteunen de volledige time-out van 600 seconden.
Met de momenteel ondersteunde Codex-runtime bereiken resultaten van dynamische OpenClaw-tools
Code Mode als JSON-tekst. Parseer elk resultaat voordat je velden uitleest. Codex
serialiseert dynamische toolaanroepen ook, zodat Promise.all niet meerdere
sessions_spawn-aanroepen gelijktijdig indient. Start collectors in een begrensde lus;
reeds geaccepteerde onderliggende processen kunnen blijven draaien terwijl latere starts worden ingediend.
agents_wait-aanroep accepteert 1–1000 uitvoerings-id’s. De aanroep retourneert:
pending leeg is. De collectormodus ondersteunt native
OpenClaw-sub-agents; deze ondersteunt geen ACP-runtime, threadbinding, zichtbare
sessies of persistente sessiemodus.
Limieten en roadmap
Swarm v1 voert eenmalige onderliggende collectorprocessen uit; de geplandeagents.session()-API
voegt stateful workers met meerdere beurten toe. Onderliggende processen worden momenteel uitgevoerd op de
sub-agentbaan van de lokale Gateway; cloudplaatsing is gepland als een expliciete
startoptie. Opgeslagen workflowdefinities en een grafiek-DSL maken geen deel uit van de
huidige richting van Swarm.
Gerelateerd
- Code Mode voor de QuickJS-gastruntime en activeringsregels
- Sub-agents voor beleid voor onderliggende processen, isolatie en sessiegedrag
- Sandboxtools voor meerdere agents voor beperkingen per agent
- Tooloverzicht voor toolprofielen en beleidsroutering