OpenClaw Tutorial Part 8: Multi-Agent-Setup & Sub-Agenten – Praxis-Guide zur Agenten-Orchestrierung

OpenClaw unterstützt zwei unterschiedliche Formen der Arbeitsaufteilung:

• Sub-Agenten sind kurzlebige Background-Runs für begrenzte Teilaufgaben.
• Persistente Agenten besitzen dauerhaft eigene Arbeitsbereiche, Zustände, Sessions und Routing-Regeln.

In diesem achten Teil der Serie startest du einen einzelnen Sub-Agenten, kontrollierst seinen Lauf und lässt den Haupt-Agenten das Ergebnis prüfen. Anschließend siehst du, wann ein dauerhaft konfigurierter Agent mit Channel-Binding sinnvoller ist.

Voraussetzungen prüfen

Prüfe Modelle, Authentifizierung und Konfiguration vor dem Testlauf:

openclaw models status
openclaw models list
openclaw config validate

openclaw models status zeigt den konfigurierten Modellzustand und die verfügbaren Auth-Profile. openclaw models list führt die konfigurierten Modelle auf. openclaw config validate prüft die aktive Konfiguration gegen das installierte Schema, ohne dafür den Gateway starten zu müssen.

Behebe gemeldete Auth- oder Schemafehler, bevor du Agenten- oder Modellwerte änderst. Zusätzlich brauchst du:

• eine funktionierende OpenClaw-Session,
• Zugriff auf eine Oberfläche, in der der Haupt-Agent sessions_spawn verwenden darf,
• ein Modell mit ausreichendem Provider-Limit,
• eine passende Tool-Policy für Datei-, Shell- oder Netzwerkzugriffe.

Prüfe in der Tool-Übersicht deiner verwendeten Oberfläche oder in der effektiven Agenten-Tool-Policy, ob sessions_spawn verfügbar ist. Fehlt das Tool, erzeugt eine bloße Aufforderung keinen nativen Sub-Agent-Run.

Wenn OPENCLAW_NIX_MODE=1 gesetzt ist, behandelt OpenClaw openclaw.json als unveränderlich. Lesende Config-Befehle funktionieren weiterhin, schreibende Befehle werden jedoch abgelehnt. Ändere in diesem Fall die Nix-Quelle der Installation und validiere danach erneut.

Sub-Agent oder persistenter Agent?

Ein Sub-Agent wird aus einem laufenden Agententurn gestartet. Er bearbeitet einen begrenzten Auftrag in einer eigenen Session. Nach Abschluss meldet OpenClaw die Completion an die anfragende Session zurück. Der Haupt-Agent entscheidet anschließend, wie er den Befund prüft und für die sichtbare Antwort verwendet.

Typische Aufgaben für Sub-Agenten sind getrennte Quellenprüfungen, ein unabhängiges Review oder die Extraktion strukturierter Daten aus mehreren Dokumenten.

Ein persistenter Agent ist dagegen eine dauerhaft konfigurierte Einheit. Er kann einen eigenen Workspace, einen eigenen agentDir, eigene Sessions, Auth-Profile, Regeln und Channel-Bindings besitzen. Das passt beispielsweise für eine dauerhaft getrennte Redaktion, einen Support-Agenten oder unterschiedliche Channel-Identitäten.

Nutze einen Sub-Agenten, wenn die Rolle nach dem Auftrag nicht weiterbestehen muss. Richte einen persistenten Agenten ein, wenn Identität, Verlauf, Berechtigungen oder Routing dauerhaft getrennt bleiben sollen.

Den richtigen Gesprächskontext wählen

Sub-Agenten laufen in einer eigenen Session. Sie erhalten deshalb nicht zwangsläufig den bisherigen Gesprächsverlauf.

Für einen isolierten Auftrag, der alle benötigten Informationen bereits im Tasktext enthält, ist der Standardkontext passend. Benötigt das Child dagegen die aktuelle Unterhaltung, muss der Spawn den Gesprächskontext ausdrücklich mit context: "fork" verzweigen.

Das ist beim folgenden Test nötig: Der Sub-Agent soll die aktuelle Unterhaltung zusammenfassen und kann diese Aufgabe ohne den geforkten Kontext nicht zuverlässig ausführen.

Einen Sub-Agenten reproduzierbar starten

sessions_spawn ist ein Agent-Tool und kein Shell-Befehl. Bitte den Haupt-Agenten um genau einen ungefährlichen Testlauf:

Starte mit sessions_spawn genau einen nativen Sub-Agenten.
Verwende context "fork".
Aufgabe: Fasse die aktuelle Unterhaltung in höchstens fünf Bulletpoints zusammen und liste offene Entscheidungen separat.
Starte keinen Ersatzlauf im Haupt-Agenten, falls sessions_spawn nicht verfügbar ist.
Gib die vom Spawn zurückgelieferte Run-ID an.

Der sinngemäße Tool-Aufruf sieht so aus:

{
  "task": "Fasse die aktuelle Unterhaltung in höchstens fünf Bulletpoints zusammen und liste offene Entscheidungen separat.",
  "context": "fork",
  "mode": "run"
}

Ein angenommener Spawn liefert unmittelbar eine Run-ID zurück. Diese Rückgabe bestätigt, dass OpenClaw den Background-Run angelegt hat. Sie belegt noch nicht, dass der Child-Auftrag bereits abgeschlossen wurde.

Verwende context: "fork" nur, wenn der Child-Run den bisherigen Gesprächsverlauf tatsächlich benötigt. Ein isolierter Auftrag mit vollständig formuliertem Task hält den übergebenen Kontext kleiner und reduziert das Risiko, unnötige Inhalte weiterzugeben.

Lauf und Ergebnis kontrollieren

Die dokumentierten Slash-Commands beziehen sich auf Sub-Agenten der aktuellen Session:

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

Rufe zuerst /subagents list auf. Übernimm die dort angezeigte Run-ID oder Listennummer für die folgenden Befehle. Ersetze <id|#> durch genau diesen Wert.

/subagents info zeigt unter anderem Status, Zeitstempel, Session-ID und Cleanup-Angaben. /subagents log gibt die letzten Chat-Turns des ausgewählten Laufs aus. Mit einer Listennummer kann die Kontrolle so aussehen:

/subagents info #1
/subagents log #1 50 tools

Das optionale Argument tools nimmt Tool-Aufrufe und deren Ergebnisse in die Log-Ausgabe auf. Verwende diese ausführliche Ansicht nur, wenn du den Ablauf diagnostizieren musst; Tool-Ergebnisse können umfangreicher oder sensibler als die normalen Chat-Turns sein.

Benötigt der Haupt-Agent das Child-Ergebnis für seine aktuelle Synthese, ist sessions_yield der dokumentierte Weg, seinen Turn zu beenden und die Completion als nächstes Ereignis eintreffen zu lassen. Auch sessions_yield ist ein internes Agent-Tool und kein Terminal-Befehl.

Ein erfolgreicher Test erfüllt vier Bedingungen:

1. Der Haupt-Agent hat sessions_spawn tatsächlich aufgerufen.
2. Der Aufruf hat eine Run-ID zurückgegeben.
3. /subagents list führt den Lauf auf und /subagents info <id|#> zeigt einen erfolgreichen terminalen Status.
4. Der Haupt-Agent hat die Completion geprüft und daraus eine sichtbare Antwort formuliert.

Fehlt die sichtbare Antwort, starte nicht sofort denselben Auftrag erneut. Der Child-Run kann bereits abgeschlossen sein, während die Übergabe oder Parent-Synthese noch aussteht. Kontrolliere zunächst Status und Log des vorhandenen Runs.

Aufträge eng begrenzen

Ein Sub-Agent arbeitet nachvollziehbarer, wenn Aufgabe, Scope und Ausgabeformat feststehen.

Zu offen wäre:

Recherchiere Kubernetes-Agenten.

Präziser ist:

Untersuche ausschließlich Open-Source-Projekte für agentenbasierte Kubernetes-Automation. Liefere höchstens acht Bulletpoints. Nenne pro Projekt Zweck, Repository-Hinweis, Reifegrad und ein technisches Risiko. Markiere unbelegte Angaben mit UNSICHER.

Für parallele Recherche sollten sich die Aufgaben möglichst wenig überschneiden. Ein Worker kann technische Implementierungen untersuchen, während ein zweiter Governance- und Sicherheitsfragen prüft. Der Haupt-Agent dedupliziert die Befunde und klärt Widersprüche.

Ein einheitliches Rückgabeformat erleichtert diese Prüfung:

Gib jeden Befund mit diesen Feldern zurück:
- Aussage
- Beleg oder Dateipfad
- Unsicherheit
- empfohlene Prüfung

Modelle und Kosten kontrollieren

Jeder Sub-Agent besitzt einen eigenen Kontext und erzeugt eigenen Tokenverbrauch. Mehr parallele Runs senken deshalb nicht automatisch die Gesamtkosten.

Prüfe vor einer Änderung zunächst den vorhandenen Wert:

openclaw config get agents.defaults.subagents.model --json

Notiere die Ausgabe. Das Standardmodell für Sub-Agenten lässt sich über agents.defaults.subagents.model setzen. Kontrolliere die geplante Änderung zunächst mit einem Dry-Run:

openclaw config set agents.defaults.subagents.model "provider/model" --dry-run

Ersetze provider/model durch eine Modellreferenz aus openclaw models list. Ist die Prüfung erfolgreich, kannst du denselben Befehl ohne --dry-run ausführen und anschließend validieren:

openclaw config set agents.defaults.subagents.model "provider/model"
openclaw config validate

Ein einzelner sessions_spawn-Aufruf kann mit seinem model-Parameter ein anderes Modell wählen. Dieser explizite Wert überschreibt für diesen Run den konfigurierten Sub-Agent-Standard:

{
  "task": "Extrahiere aus den bereitgestellten Dokumenten ausschließlich Datums- und Versionsangaben.",
  "mode": "run",
  "model": "provider/model"
}

Prüfe verfügbare Modellreferenzen und den Auth-Zustand mit:

openclaw models list
openclaw models status

Für Extraktion und einfache Zusammenfassungen kann ein günstigeres Modell genügen. Bei Architekturentscheidungen oder der finalen Synthese muss das Modell auch widersprüchliche Quellen und Unsicherheit sinnvoll verarbeiten können. Begrenze zusätzlich die Zahl paralleler Worker und die Länge ihrer Rückgaben.

Modelländerung zurücknehmen

War vor dem Test bereits ein Wert konfiguriert, stelle ihn mit der zuvor gesicherten Modellreferenz wieder her:

openclaw config set agents.defaults.subagents.model "vorheriger/provider-wert"
openclaw config validate

War der Pfad vorher nicht gesetzt, entferne die Testeinstellung:

openclaw config unset agents.defaults.subagents.model
openclaw config validate

Wie Modellreferenzen und Defaults grundsätzlich eingerichtet werden, zeigt OpenClaw Tutorial Teil 3: Modelle konfigurieren.

Persistente Agenten und Bindings verwalten

Das Anlegen eines persistenten Agenten ist eine dauerhafte Konfigurationsentscheidung und kein notwendiger Bestandteil des vorigen Sub-Agent-Tests. Verwende eine Agent-ID deshalb nur, wenn die Rolle bestehen bleiben soll.

Für eine dauerhafte Research-Rolle legst du den Agenten mit dem dokumentierten CLI-Helfer an:

openclaw agents add research

Der Helfer führt durch die benötigten Angaben. Die lokale CLI unterstützt außerdem Optionen für Workspace, agentDir, Modell und Channel-Binding. Prüfe anschließend die vorhandenen Agenten und ihre Bindings:

openclaw agents list --bindings

Das erwartete Ergebnis ist ein Eintrag für research. Ein Binding erscheint nur, wenn der Agent bereits einem Channel-Account oder einer passenden Routing-Regel zugeordnet wurde.

Das aktuelle Schema und die aufgelöste Agentenliste kannst du zusätzlich lesend prüfen:

openclaw config schema
openclaw config get agents.list --json
openclaw config validate

Verwende für jeden persistenten Agenten einen eigenen agentDir. Die offizielle Multi-Agent-Dokumentation warnt ausdrücklich davor, denselben State-Pfad für mehrere Agenten wiederzuverwenden, weil dadurch Auth- und Session-Zustände kollidieren können.

Kontrolliere vor einer produktiven Channel-Zuordnung die Agent-ID, den Workspace, den agentDir, das Auth-Profil und das konkrete Binding-Ziel. Prüfe außerdem die effektive Modell- und Tool-Policy.

Nach einer Config-Änderung folgt openclaw config validate. Schlägt die Validierung fehl, nimm den fehlerhaften Stand nicht in den produktiven Gateway-Betrieb. Korrigiere gezielt den gemeldeten Pfad, statt die gesamte Config durch ein älteres Beispiel zu ersetzen.

Drei Schutzebenen auseinanderhalten

Ein eigener Workspace ist keine harte Sandbox. Er bestimmt das Standard-Arbeitsverzeichnis und trennt Arbeitsdateien sowie Persona-Regeln.

Eine aktivierte Sandbox begrenzt den technisch erreichbaren Ausführungs- und Dateikontext entsprechend ihrer Konfiguration. Die Tool-Policy entscheidet zusätzlich, welche Werkzeuge ein Agent oder Sub-Agent überhaupt aufrufen darf.

Ein separater Workspace ersetzt weder Sandbox noch Tool-Beschränkungen. Gib einem Research-Worker ohne Schreibauftrag deshalb keine Dateischreib- oder Shell-Werkzeuge. Kopiere außerdem keine Secrets in den Tasktext. Child-Ergebnisse sind wie nicht vertrauenswürdige Eingaben zu prüfen, besonders wenn sie Inhalte aus dem Web oder aus fremden Dokumenten enthalten.

Die Einrichtung von Workspace-Dateien und Persona-Regeln behandelt OpenClaw Tutorial Teil 6: Workspace einrichten.

Orchestrierungsmuster für die Praxis

Fan-out und Fan-in

Mehrere Worker bearbeiten unabhängige Teilmengen. Der Haupt-Agent wartet auf die benötigten Completions, vergleicht sie und erstellt eine gemeinsame Auswertung.

Beispiel: Worker A prüft die technische Dokumentation, Worker B untersucht bekannte Einschränkungen. Beide liefern dasselbe strukturierte Format. Der Haupt-Agent entfernt Dubletten und markiert ungeklärte Widersprüche.

Pipeline

Die Arbeit läuft in festgelegter Reihenfolge:

Recherche → Gliederung → Entwurf → Review → Freigabe

Jede Stufe erhält die geprüften Ergebnisse der vorherigen Stufe und ein enges Rückgabeformat. Das erzeugt zusätzliche Übergaben, schafft aber klar erkennbare Prüfpunkte.

Supervisor und Worker

Der Haupt-Agent zerlegt den Auftrag, startet begrenzte Child-Runs und behält die Entscheidungshoheit. Worker liefern Befunde. Produktive Änderungen und die finale Antwort bleiben bis zur Prüfung beim Haupt-Agenten.

Praxisbeispiel: Redaktions-Workflow

Ein kontrollierter Ablauf für einen technischen Artikel sieht so aus:

1. Der Haupt-Agent definiert Fragestellung, Quellenanforderungen und Ausgabeformat.
2. Ein Sub-Agent prüft Commands, Config-Schlüssel und Versionsangaben gegen die offizielle Dokumentation.
3. Ein zweiter Sub-Agent untersucht Voraussetzungen, Sicherheitsrisiken und Fehlerpfade.
4. Der Haupt-Agent ermittelt die Run-IDs oder Listennummern mit /subagents list und kontrolliert beide Läufe über /subagents info <id|#> sowie bei Bedarf /subagents log <id|#>.
5. Er vergleicht die Ergebnisse, prüft die Belege und schreibt die finale Fassung selbst.

Die beiden Worker erhalten getrennte Aufgaben:

Worker A: Prüfe ausschließlich Commands, Config-Schlüssel und Versionsangaben. Liefere pro Claim Beleg, Status und mögliche Leserfolgen.

Worker B: Gehe die Anleitung als neuer Nutzer durch. Suche fehlende Voraussetzungen, unklare Erfolgskriterien und riskante Berechtigungen.

Benötigen die Worker nur die explizit genannten Quellen und Anweisungen, müssen sie nicht den gesamten bisherigen Chat erhalten. Übergib den Gesprächskontext mit context: "fork" nur dann, wenn Informationen aus der aktuellen Unterhaltung Teil ihres Auftrags sind.

Dieses Beispiel macht Parallelisierung sichtbar, ohne beiden Workern gleichzeitig Schreibzugriff auf dieselbe Datei zu geben.

Fehler erkennen und beheben

sessions_spawn fehlt: Prüfe die Tool-Übersicht deiner Oberfläche und die Tool-Policy des Haupt-Agenten. Eine normale Antwort auf den delegierten Prompt ist kein Ersatz für einen nativen Child-Run.

Der Spawn wird abgelehnt: Prüfe Modellzugriff, Provider-Authentifizierung, Parallelitätsgrenzen und die effektive Sub-Agent-Policy. Verwende /subagents list, bevor du den Auftrag erneut startest.

Der Child kennt den bisherigen Chat nicht: Prüfe, ob der Auftrag tatsächlich Gesprächsinhalte benötigt. Starte solche Runs mit context: "fork". Bei isolierten Aufgaben gehören alle notwendigen Informationen direkt in den Tasktext.

Der Run bleibt lange aktiv: Ermittle seine Run-ID oder Listennummer mit /subagents list. Öffne danach /subagents info <id|#> und /subagents log <id|#>. Begrenze zu große Aufgaben oder teile sie anhand unabhängiger Datenmengen auf.

Der Run ist fertig, aber die Synthese fehlt: Der Haupt-Agent muss die Completion empfangen und prüfen. Wenn sein aktueller Turn vom Ergebnis abhängt, sollte er sessions_yield verwenden.

Die Config ist ungültig: Lies den gemeldeten Pfad, gleiche ihn mit openclaw config schema ab und korrigiere nur die fehlerhafte Änderung. Im Nix-Modus gehört die Reparatur in die Nix-Quelle.

Mehrere Agenten schreiben dieselbe Datei: Stoppe weitere Schreibaufträge, prüfe den Arbeitsstand und ordne jedem Worker getrennte Dateien oder ausschließlich lesenden Zugriff zu. Der Haupt-Agent führt geprüfte Änderungen anschließend zusammen.

Weiterlesen

• Die Grundlagen zu Automationen stehen in OpenClaw Tutorial Teil 7: Cron-Jobs, Heartbeats & Automationen.
• Grundlagen zu Tool-Berechtigungen und Erweiterungen findest du in OpenClaw Tutorial Teil 5: Skills & Tools erweitern.

Der praktische Punkt

Beginne mit einem einzelnen Sub-Agenten und einer ungefährlichen Leseaufgabe. Kontrolliere Spawn, Status, Log und Completion, bevor du Parallelität erhöhst. Übergib den bisherigen Gesprächskontext nur, wenn der Auftrag ihn wirklich benötigt.

Persistente Agenten entstehen nicht durch größere Child-Prompts. Sie brauchen eigene Zustände, klar getrennte Verzeichnisse, überprüfte Bindings und passende Berechtigungen. Diese Trennung hält die Orchestrierung nachvollziehbar und verhindert, dass ein Parallelisierungstest unbeabsichtigt zu einer dauerhaften Sicherheits- oder Routing-Entscheidung wird.