Schwarm

Swarm ist eine experimentelle, optional aktivierbare Möglichkeit, viele Unteragenten aus einem Code-Modus-Skript zu orchestrieren. Verwenden Sie normale JavaScript- oder TypeScript- Kontrollflüsse wie 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 Fortschrittsberichte.

Swarm aktivieren

Der empfohlene Weg ist Einstellungen → Labs → Swarm in der Control UI. Der Schalter wird sofort wirksam und schreibt tools.swarm.enabled in Ihre Konfiguration.

Sie können Swarm auch direkt in openclaw.json aktivieren:

{  tools: {    swarm: {      enabled: true,      maxConcurrent: 8,      maxChildrenPerGroup: 50,      maxTotalPerGroup: 200,      waitTimeoutSecondsMax: 600,      defaultAgentId: "",    },  },}

Die boolesche Kurzform aktiviert oder deaktiviert die Funktion, wobei alle anderen Werte ihre Standardwerte behalten:

{  tools: {    swarm: true,  },}

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 übergeordnete tools.swarm-Objekt gelegt.

Voraussetzungen

Die Gast-Globals agents.run, phase und log erfordern sowohl Swarm als auch den OpenClaw-Code-Modus:

{  tools: {    codeMode: true,    swarm: true,  },}

Der Code-Modus muss außerdem effektiven Zugriff auf sessions_spawn haben. Tool-Profile, Zulassungs-/Verweigerungsrichtlinien, Provider-Regeln und Sandbox-Richtlinien können dieses Tool entfernen. Siehe Aktivierung des Code-Modus und Unteragenten, wenn ein Skript meldet, dass sessions_spawn nicht verfügbar ist.

defaultAgentId und die laufbezogenen agentId-Werte müssen ein konfiguriertes Ziel benennen, das durch die subagents.allowAgents-Richtlinie des Anfragenden zulässig ist. OpenClaw lehnt ein unbekanntes oder unzulässiges Ziel ab, anstatt auf einen anderen Agenten zurückzugreifen.

Ein Swarm-Skript schreiben

Wenn Swarm aktiviert ist, stellt der Code-Modus diese Gast-API bereit:

type AgentRunOptions = {  label?: string;  model?: string;  thinking?: string;  fastMode?: boolean | "auto";  agentId?: string;  schema?: Record<string, unknown>;  phase?: string;}; agents.run(prompt: string, options?: AgentRunOptions & { schema?: undefined }): Promise<string>;agents.run&lt;T&gt;(prompt: string, options: AgentRunOptions & { schema: Record<string, unknown> }): Promise&lt;T&gt;;phase(title: string): void;log(message: string): void;

Ohne schema wird agents.run() zum abschließenden 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, zeitüberschrittenen oder schemaungültigen Kind wird das Promise mit einem SwarmAgentError zurückgewiesen. Lesen Sie die exakten generierten Deklarationen und kurzen Orchestrierungsmuster aus API.read("agents.d.ts") im 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 Warten ausgelöst; sie verzögern das Skript nicht, wenn die UI nicht verfügbar ist.

Parallel auffächern und strukturierte Ergebnisse zusammenführen

Dieses Beispiel startet einen Recherche-Agenten pro Thema, wartet auf alle und beauftragt anschließend ein letztes Kind, deren strukturierte Berichte zusammenzuführen:

const reportSchema = {  type: "object",  properties: {    finding: { type: "string" },    evidence: { type: "array", items: { type: "string" } },    confidence: { type: "number" },  },  required: ["finding", "evidence", "confidence"],  additionalProperties: false,}; const topics = ["Authentifizierung", "Speicherung", "Wiederherstellung"];phase("Unabhängige Prüfung"); const reports = await Promise.all(  topics.map((topic) =>    agents.run(`Prüfen Sie den Pfad ${topic}. Geben Sie einen Befund mit Belegen zurück.`, {      label: `review-${topic}`,      thinking: "high",      fastMode: "auto",      schema: reportSchema,    }),  ),); phase("Zusammenführung");log(`${reports.length} unabhängige Berichte gesammelt.`); return await agents.run(  `Gleichen Sie diese Berichte ab und erläutern Sie Unstimmigkeiten:\n${JSON.stringify(reports)}`,  { label: "synthesis" },);

Promise.all ist die Grenze für Auffächerung und Zusammenführung. OpenClaw startet bis zu maxConcurrent Kinder für die Gruppe und reiht die übrigen in der Reihenfolge ihrer Übermittlung ein.

Der Code-Modus begrenzt gleichzeitig ausgeführte Gast-Bridge-Aufrufe separat mit 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.

Eine Entscheidungsschranke wiederholt prüfen

Verwenden Sie eine begrenzte while-Schleife, wenn jeder Durchlauf entscheidet, ob ein weiterer Durchlauf erforderlich ist:

const gateSchema = {  type: "object",  properties: {    ready: { type: "boolean" },    reason: { type: "string" },    nextAction: { type: "string" },  },  required: ["ready", "reason", "nextAction"],  additionalProperties: false,}; let pass = 0;let decision = { ready: false, reason: "Nicht geprüft", nextAction: "Prüfen" }; while (!decision.ready && pass < 4) {  pass += 1;  phase(`Entscheidungsdurchlauf ${pass}`);  decision = await agents.run(    `Prüfen Sie, ob die Release-Nachweise vollständig sind. Vorherige Entscheidung: ${JSON.stringify(decision)}`,    {      label: `release-gate-${pass}`,      schema: gateSchema,    },  );  log(decision.reason);} if (!decision.ready) {  throw new Error(`Schranke nach ${pass} Durchläufen weiterhin geschlossen: ${decision.nextAction}`);} return decision;

Begrenzen Sie Entscheidungsschleifen immer. maxTotalPerGroup ist die letzte Sicherheitsabsicherung, kein Ersatz für eine eindeutige Abbruchbedingung.

Das zuerst fertiggestellte 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 untergeordneten Tools aufrufen, stellt agents_wait dieselbe Grenze für den ersten Abschluss bereit: Der Aufruf kehrt zurück, sobald mindestens einer der angeforderten Läufe 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 Unteragentensitzungen mit einem anderen Abschlusspfad. Sie schreiben ein dauerhaftes Collector-Ergebnis, auf das das übergeordnete Element wartet, anstatt eine Antwort anzukündigen oder zurück in die übergeordnete Sitzung zu leiten.

Der Zielagent wird in dieser Reihenfolge bestimmt:

1. agentId beim Spawn- oder agents.run()-Aufruf.
2. tools.swarm.defaultAgentId.
3. Der anfragende Agent.

Ein dedizierter, schlanker Arbeitsagent ist nützlich, wenn Swarm-Kinder eine kleinere Tool-Oberfläche, ein günstigeres Modell oder eine strengere Sandbox-Richtlinie benötigen. OpenClaw liefert keine integrierte Agenten-ID worker aus; konfigurieren Sie eine solche ID, bevor Sie sie als Standardwert festlegen. Härten Sie diesen Arbeitsagenten mit tools.swarm: false in seiner agentenspezifischen Konfiguration ab, sodass er erzeugt werden kann, aber aus seinen eigenen übergeordneten Sitzungen keine Swarms starten kann:

{  tools: { swarm: { enabled: true, defaultAgentId: "worker" } },  agents: {    list: [      {        id: "main",        default: true,        subagents: { allowAgents: ["worker"] },      },      { id: "worker", tools: { swarm: false } },    ],  },}

Collector-Genehmigungen werden im Zweifel verweigert. Ein Kind öffnet niemals eine Genehmigungsaufforderung für Bedienende. Eine Tool-Aktion, die eine Genehmigung erfordern würde, wird verweigert, und das Kind kann diese Verweigerung in seinem Ergebnis melden, damit das Skript über das weitere Vorgehen entscheiden kann.

Für strukturierte Ausgaben fügt OpenClaw dem Kind ein synthetisches structured_output-Tool hinzu und validiert dessen Nutzdaten anhand des bereitgestellten JSON-Schemas. Bei ungültigen oder fehlenden Nutzdaten erfolgt eine einmalige Korrekturaufforderung. Wenn auch der erneute Versuch die Validierung nicht besteht, behält der Collector-Abschluss den Rohtext des Kindes bei, lässt structured ungesetzt und enthält schemaError. Das untergeordnete agents_wait- Ergebnis stellt diese Felder für eine explizite Wiederherstellungslogik bereit.

Kinder sind Blätter

Swarm-Kinder sind standardmäßig Blätter. Die universelle agents.defaults.subagents.maxSpawnDepth-Sperre verhindert, dass ein Kind bei der Standardtiefe 1 eigene Kinder erzeugt. Das übliche Orchestrierungsmuster besteht darin, Arbeit an das übergeordnete Element zurückzugeben, statt von einem Kind aus weitere Arbeit zu erzeugen:

const plan = await agents.run("Planen Sie diesen Auftrag als unabhängige Aufgaben.", {  schema: {    type: "object",    properties: { tasks: { type: "array", items: { type: "string" } } },    required: ["tasks"],    additionalProperties: false,  },});return await Promise.all(plan.tasks.map((task) => agents.run(task)));

Verschachtelte Unteragenten können durch Bedienende über agents.defaults.subagents.maxSpawnDepth optional aktiviert werden 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ündigungs- 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 sitzungsbezogene Kinderbudget. Die Begrenzung der 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 in der globalen Unteragentenspur. 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 mit einem Punkt pro Kind und dem Status „in Warteschlange“, „läuft“, „abgeschlossen“ oder „fehlgeschlagen“ dar. Labels werden in den Tooltips der Punkte angezeigt, sodass kurze, stabile Labels größere Swarms leichter lesbar machen.

Die Sitzungsseitenleiste behält die normale Baumstruktur aus übergeordneten Elementen und Kindern bei. Erweitern Sie die Zeile des übergeordneten Elements, um ein Collector-Kind zu untersuchen oder dessen Transkript zu öffnen, ohne die Swarm- Hierarchie zu verlieren.

Collector-Ergebnisse bleiben abrufbar, bis ihre Gruppe archiviert wird. Nachdem jedes Mitglied seine Aufbewahrungsfrist erreicht hat, archiviert OpenClaw die untergeordneten Elemente der Gruppe als Batch, damit abgeschlossene Schwarme nicht im aktiven Sitzungsbaum verbleiben.

Swarm mit anderen Harnesses verwenden

Sie können Swarm ohne den OpenClaw Code Mode verwenden. Seine Kernwerkzeuge sind Harness-unabhängig: Starten Sie untergeordnete Collector-Prozesse mit sessions_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-Laufzeit 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 Collectors in einer begrenzten Schleife; bereits angenommene untergeordnete Prozesse können weiterlaufen, während spätere Starts übermittelt werden.

function parseToolResult(value) {  if (typeof value !== "string") return value;  return JSON.parse(value);} const tasks = [  "Prüfen Sie den Authentifizierungspfad.",  "Prüfen Sie den Speicherpfad.",  "Prüfen Sie den Wiederherstellungspfad.",];const launches = []; for (const [index, task] of tasks.entries()) {  const launch = parseToolResult(    await tools.sessions_spawn({      task,      collect: true,      label: `review-${index + 1}`,    }),  );  if (launch.status !== "accepted") {    throw new Error(launch.error ?? "Der Collector-Start wurde nicht angenommen.");  }  launches.push(launch);} const pending = new Set(launches.map((launch) => launch.runId));const completed = []; while (pending.size > 0) {  const ids = [...pending].slice(0, 1000);  const batch = parseToolResult(    await tools.agents_wait({      ids,      timeoutSeconds: 30,    }),  );   // Verschieben Sie dieses begrenzte Fenster hinter IDs, die noch nicht geprüft wurden.  for (const runId of ids) {    if (pending.delete(runId)) pending.add(runId);  }   for (const item of batch.completed) {    pending.delete(item.runId);    if (item.status !== "done") {      throw new Error(item.schemaError ?? item.result ?? `${item.runId}: ${item.status}`);    }    completed.push(item); // Verarbeiten Sie jedes Ergebnis, sobald es abgeschlossen ist.  }   for (const failure of batch.errors ?? []) {    pending.delete(failure.runId);    throw new Error(`${failure.runId}: ${failure.error}`);  }} return completed;

Jeder agents_wait-Aufruf akzeptiert 1–1000 Ausführungs-IDs. Er gibt Folgendes zurück:

type AgentsWaitResult = {  completed: Array<{    runId: string;    status: "done" | "failed" | "killed" | "timeout";    result: string;    structured?: unknown;    schemaError?: string;    sessionKey: string;    label?: string;    usage?: { inputTokens: number; outputTokens: number };  }>;  pending: string[];  errors?: Array<{    runId: string;    error: "not_found" | "not_owner";  }>;};

Der Aufruf kehrt sofort zurück, wenn ein angeforderter untergeordneter Prozess bereits abgeschlossen ist, wenn mindestens ein ausstehender untergeordneter Prozess abgeschlossen wird, wenn keine gültigen ausstehenden IDs mehr vorhanden sind oder wenn sein Zeitlimit abläuft. Abgeschlossene Datensätze sind idempotent, sodass die Übergabe einer bereits abgeschlossenen Ausführungs-ID deren Ergebnis erneut zurückgibt. Nur die startende Sitzung oder ihre autorisierte übergeordnete Kette kann auf einen Collector warten.

Dies ist begrenztes Long Polling und keine aktive Statusschleife. Übergeben Sie weiterhin nur die verbleibenden Ausführungs-IDs, bis pending leer ist. Der Collector-Modus unterstützt native OpenClaw-Unteragenten; er unterstützt weder die ACP-Laufzeit noch Thread-Bindung, sichtbare Sitzungen oder den persistenten Sitzungsmodus.

Grenzen und Roadmap

Swarm v1 führt einmalig ausgeführte untergeordnete Collector-Prozesse aus; die geplante agents.session()-API wird zustandsbehaftete Worker mit mehreren Dialogrunden hinzufügen. Untergeordnete Prozesse werden derzeit in der Unteragenten-Lane des lokalen Gateway ausgeführt; die Cloud-Platzierung 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-Gastlaufzeit und Aktivierungsregeln
• Unteragenten für Richtlinien, Isolation und Sitzungsverhalten untergeordneter Prozesse
• Multi-Agent-Sandbox-Werkzeuge für agentenspezifische Einschränkungen
• Werkzeugübersicht für Werkzeugprofile und Richtlinienrouting