Promise.all, while und if, um Arbeit aufzufächern, Ergebnisse zu sammeln
und Entscheidungen zu treffen.
Es gibt weder eine Graph-DSL noch ein separates Workflow-Format. Das Programm ist die
Orchestrierung. Swarm ergänzt dieses Programm um erwartbare Collector-Kinder, strukturierte Ergebnisse,
begrenzte Nebenläufigkeit und Fortschrittsmeldungen.
Swarm aktivieren
Der empfohlene Weg ist Einstellungen → Labs → Swarm in der Control UI. Der Schalter wird sofort wirksam und schreibttools.swarm.enabled in Ihre
Konfiguration.
Sie können Swarm auch direkt in openclaw.json aktivieren:
Numerische Werte müssen positive Ganzzahlen sein. OpenClaw begrenzt
maxConcurrent auf 1–1000, maxChildrenPerGroup auf 1–10000,
maxTotalPerGroup auf 1–100000 und waitTimeoutSecondsMax auf
1–86400.
Sie können Swarm für einen einzelnen konfigurierten Agenten mit
agents.entries.*.tools.swarm überschreiben. Das agentenspezifische Objekt wird über das
tools.swarm-Objekt der obersten Ebene gelegt.
Voraussetzungen
Die Gast-Globalsagents.run, phase und log erfordern sowohl Swarm als auch den
OpenClaw-Code-Modus:
sessions_spawn haben. Tool-Profile,
Zulassungs-/Ablehnungsrichtlinien, Provider-Regeln und Sandbox-Richtlinien können dieses Tool entfernen.
Weitere Informationen finden Sie unter Aktivierung des Code-Modus und
Sub-Agenten, wenn ein Skript meldet, dass sessions_spawn
nicht verfügbar ist.
defaultAgentId und die Werte von agentId pro Ausführung müssen ein konfiguriertes Ziel
benennen, das gemäß der subagents.allowAgents-Richtlinie des Anfordernden zulässig ist. OpenClaw lehnt
ein unbekanntes oder unzulässiges Ziel ab, statt auf einen anderen Agenten zurückzugreifen.
Ein Swarm-Skript schreiben
Wenn Swarm aktiviert ist, stellt der Code-Modus diese Gast-API bereit:schema wird agents.run() zum endgültigen Text des Kindes aufgelöst. Mit einem
JSON-Schema wird es zu dem Wert aufgelöst, der über das structured_output-Tool des Kindes
übermittelt wurde. Bei einem fehlgeschlagenen, beendeten, abgelaufenen oder schemaungültigen Kind
wird das Promise mit einem SwarmAgentError abgelehnt. Die genauen generierten
Deklarationen und kurzen Orchestrierungsmuster finden Sie in API.read("agents.d.ts")
innerhalb des Code-Modus.
Verwenden Sie label für einen leicht erkennbaren Namen des Kindes im Dashboard und in der Seitenleiste. Verwenden Sie
phase in den Optionen, um unmittelbar vor dem Start dieses Kindes eine Phase zu veröffentlichen,
oder rufen Sie phase() auf, wenn mehrere Kinder zur selben Phase gehören.
log() veröffentlicht eine kurze Fortschrittsmeldung. Fortschrittsaufrufe werden ohne Abwarten ausgeführt;
sie verzögern das Skript nicht, wenn die UI nicht verfügbar ist.
Paralleles Auffächern mit strukturierten Ergebnissen
Dieses Beispiel startet pro Thema einen Recherche-Agenten, wartet auf alle und fordert anschließend ein letztes Kind auf, ihre strukturierten Berichte zusammenzuführen:Promise.all ist die Grenze für Auffächerung und Zusammenführung. OpenClaw startet bis zu
maxConcurrent Kinder für die Gruppe und reiht den Rest in der Reihenfolge der Übermittlung
ein.
Der Code-Modus begrenzt gleichzeitig ausgeführte Gast-Bridge-Aufrufe separat durch
tools.codeMode.maxPendingToolCalls (Standardwert 16, Maximum 128). Starten Sie bei sehr
großen Gruppen begrenzte Batches unterhalb dieses Limits und lassen Sie Spielraum für
phase(), log() und Übergänge beim Warten auf Kinder. maxConcurrent begrenzt laufende
Kinder; es erhöht nicht das Limit für Gast-Bridge-Aufrufe.
Schleife an einem Entscheidungsgate
Verwenden Sie eine begrenztewhile-Schleife, wenn jeder Durchlauf entscheidet, ob ein weiterer Durchlauf
erforderlich ist:
maxTotalPerGroup ist die letzte Sicherheitsabsicherung,
kein Ersatz für eine klare Abbruchbedingung.
Das zuerst abgeschlossene Kind verarbeiten
agents.run() gibt ein gewöhnliches Promise zurück, sodass Promise.race auf das
erste Kind des Code-Modus reagieren kann. Für Testumgebungen, die die Tools der unteren Ebene aufrufen,
stellt agents_wait dieselbe Grenze für den ersten Abschluss bereit: Der Aufruf kehrt zurück, sobald
mindestens eine angeforderte Ausführung abgeschlossen ist oder das begrenzte Timeout abläuft.
Die vollständige Drain-Schleife finden Sie unter Swarm aus anderen Testumgebungen verwenden.
Verhalten von Collector-Kindern
Collector-Kinder sind gewöhnliche isolierte Sub-Agent-Sitzungen mit einem anderen Abschlussweg. Sie schreiben ein dauerhaftes Collector-Ergebnis, auf das das übergeordnete Element wartet, statt eine Antwort anzukündigen oder zurück in die übergeordnete Sitzung zu lenken. Der Ziel-Agent wird in dieser Reihenfolge ermittelt:agentIdbeim Spawn- oderagents.run()-Aufruf.tools.swarm.defaultAgentId.- Der anfordernde Agent.
worker aus; konfigurieren Sie eine, bevor Sie sie als Standardwert festlegen.
Härten Sie diesen Worker mit tools.swarm: false in seiner agentenspezifischen Konfiguration, damit
er gestartet werden kann, aber aus seinen eigenen Sitzungen der obersten Ebene keine Swarms starten kann:
structured_output-Tool hinzu
und validiert dessen Nutzdaten anhand des bereitgestellten JSON-Schemas. Bei ungültigen oder fehlenden
Nutzdaten erfolgt ein korrigierender Hinweis. Wenn auch der erneute Versuch nicht validiert werden kann,
behält der Collector-Abschluss den Rohtext des Kindes bei, lässt structured
nicht gesetzt und enthält schemaError. Das Ergebnis agents_wait der unteren Ebene
stellt diese Felder für eine explizite Wiederherstellungslogik bereit.
Kinder sind Blätter
Swarm-Kinder sind standardmäßig Blätter. Die universelleagents.defaults.subagents.maxSpawnDepth-Schutzvorrichtung verhindert, dass ein Kind
bei der Standardtiefe 1 eigene Kinder startet. Das übliche Orchestrierungsmuster besteht darin,
Arbeit an das übergeordnete Element zurückzugeben, statt weitere Arbeit von einem Kind aus zu starten:
agents.defaults.subagents.maxSpawnDepth und werden für Swarm nicht empfohlen.
Gruppenlimits, Budgets und Beobachtbarkeit setzen flache Collector-Gruppen voraus.
Jedes Kind hat genau einen Verantwortlichen für die Zulassung. Ankündigende und interaktive Kinder verwenden
agents.defaults.subagents.maxChildrenPerAgent (Standardwert 5) und zählen
Collector-Kinder nicht mit. Collector-Kinder verwenden ausschließlich maxChildrenPerGroup und
maxTotalPerGroup; sie verbrauchen nicht das sitzungsspezifische Kinderbudget. Die Schutzvorrichtung für die Spawn-
Tiefe gilt weiterhin für beide Modi.
Nach der Zulassung werden Kinder oberhalb von maxConcurrent innerhalb ihrer Swarm-
Gruppe in FIFO-Reihenfolge eingereiht, verschachtelt innerhalb der globalen Sub-Agent-Spur. Diese Nebenläufigkeitsebenen reihen
Arbeit ein, statt sie abzulehnen. Ein Collector-Spawn, der eines der Gruppenlimits
überschreitet, wird mit dem entsprechenden Konfigurationsschlüssel in der Fehlermeldung abgelehnt.
Einen Swarm beobachten
Öffnen Sie das Dashboard der übergeordneten Sitzung in der Control UI, während ein Swarm aktiv ist. Das Swarm-Widget stellt jede aktive Collector-Gruppe als einen Punkt pro Kind mit dem Status „eingereiht“, „laufend“, „abgeschlossen“ oder „fehlgeschlagen“ dar. Beschriftungen erscheinen in den Tooltips der Punkte, sodass kurze, stabile Beschriftungen größere Swarms leichter lesbar machen. Die Sitzungsseitenleiste behält die normale Hierarchie aus übergeordneten und untergeordneten Elementen bei. Erweitern Sie die Zeile des übergeordneten Elements, um ein Collector-Kind zu prüfen oder sein Transkript zu öffnen, ohne die Swarm- Hierarchie zu verlieren. Sammlerergebnisse bleiben abrufbar, bis ihre Gruppe archiviert wird. Nachdem jedes Mitglied seine Aufbewahrungsfrist erreicht hat, archiviert OpenClaw die untergeordneten Elemente der Gruppe als Stapel, damit abgeschlossene Swarms nicht im aktiven Sitzungsbaum verbleiben.Swarm aus anderen Harnesses verwenden
Sie können Swarm ohne den OpenClaw Code Mode verwenden. Seine Kernwerkzeuge sind Harness-unabhängig: Starten Sie untergeordnete Sammler mitsessions_spawn({ collect: true }) und rufen Sie deren Ergebnisse mit begrenzten agents_wait-Aufrufen
ab.
Der Codex Code Mode stellt geeignete dynamische OpenClaw-Werkzeuge automatisch unter
tools.* bereit. Er verwendet weder die QuickJS-Gast-API von OpenClaw noch benötigt er
tools.codeMode, aber tools.swarm muss weiterhin aktiviert sein. agents_wait-Aufrufe
des Codex-Harness unterstützen das vollständige Zeitlimit von 600 Sekunden.
Mit der derzeit unterstützten Codex-Runtime erreichen Ergebnisse dynamischer OpenClaw-Werkzeuge den
Code Mode als JSON-Text. Parsen Sie jedes Ergebnis, bevor Sie Felder auslesen. Codex
serialisiert außerdem dynamische Werkzeugaufrufe, sodass Promise.all nicht mehrere
sessions_spawn-Aufrufe gleichzeitig übermittelt. Starten Sie Sammler in einer begrenzten Schleife;
bereits akzeptierte untergeordnete Prozesse können weiter ausgeführt werden, während spätere Starts übermittelt werden.
agents_wait-Aufruf akzeptiert 1–1000 Ausführungs-IDs. Er gibt Folgendes zurück:
pending leer ist. Der Sammlermodus unterstützt native
OpenClaw-Unteragenten; er unterstützt weder die ACP-Runtime noch Thread-Bindung, sichtbare
Sitzungen oder den persistenten Sitzungsmodus.
Beschränkungen und Roadmap
Swarm v1 führt einmalig ausgeführte untergeordnete Sammler aus; die geplanteagents.session()-API
wird zustandsbehaftete Worker mit mehreren Interaktionsrunden hinzufügen. Untergeordnete Prozesse werden derzeit in der
Unteragenten-Lane des lokalen Gateway ausgeführt; die Platzierung in der Cloud ist als explizite Startoption
geplant. Gespeicherte Workflow-Definitionen und eine Graph-DSL gehören nicht zur
aktuellen Ausrichtung von Swarm.
Verwandte Themen
- Code Mode für die QuickJS-Gast-Runtime und Aktivierungsregeln
- Unteragenten für Richtlinien, Isolation und Sitzungsverhalten untergeordneter Prozesse
- Multi-Agent-Sandbox-Werkzeuge für Einschränkungen pro Agent
- Werkzeugübersicht für Werkzeugprofile und Richtlinienrouting