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

Die Stärke von KI-Agenten zeigt sich besonders dann, wenn sie Arbeit sinnvoll aufteilen. OpenClaw unterstützt dafür zwei unterschiedliche Konzepte:

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

In diesem achten Teil der Serie richtest du beide Varianten kontrolliert ein. Du startest einen einzelnen Sub-Agenten, prüfst seinen Lauf und übernimmst das Ergebnis nach dieser Kontrolle in die Hauptaufgabe. 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. Behebe gemeldete Schemafehler, bevor du Agenten- oder Modellwerte änderst.

Zusätzlich brauchst du:

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

Mit /tools kannst du in derselben Session prüfen, ob sessions_spawn zur effektiven Tool-Auswahl gehört. Fehlt es dort, löst eine bloße Aufforderung keinen nativen Sub-Agent-Run aus. Kontrolliere in diesem Fall die Tool-Policy des Agenten.

Wenn OPENCLAW_NIX_MODE=1 gesetzt ist, behandelt OpenClaw openclaw.json als unveränderlich und verweigert schreibende Config-Befehle. Ändere dann die Nix-Quelle der Installation und validiere anschließend erneut.

Sub-Agent oder persistenter Agent?

Ein Sub-Agent wird aus einem laufenden Agententurn gestartet. Er erhält einen begrenzten Auftrag, arbeitet in einer eigenen Session und übergibt seine Completion an die anfragende Session. Der Haupt-Agent prüft diese Rückgabe und formuliert daraus die sichtbare Antwort. Das Child-Ergebnis ist also nicht automatisch die fertige Nutzerantwort.

Typische Aufgaben für Sub-Agenten sind:

• zwei Quellenbestände getrennt untersuchen,
• einen Entwurf unabhängig gegenlesen,
• strukturierte Daten aus mehreren Dokumenten extrahieren,
• langsame Tool-Arbeit im Hintergrund erledigen.

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 etwa 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.

Einen Sub-Agenten reproduzierbar starten

sessions_spawn ist ein Agent-Tool und kein Shell-Befehl. Der Haupt-Agent ruft es innerhalb seines Turns auf. Ein minimaler Auftrag besteht aus task; mit taskName erhält der Lauf zusätzlich einen stabilen Namen, anhand dessen du ihn in der Statusübersicht wiedererkennst.

Eine passende Anweisung an den Haupt-Agenten lautet:

Starte mit sessions_spawn genau einen nativen Sub-Agenten.
Verwende taskName "summary_test".
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.

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.",
  "taskName": "summary_test",
  "mode": "run"
}

Ein angenommener Spawn liefert eine Child- oder Session-Referenz zurück. Die Referenz bestätigt, dass der Background-Run angelegt wurde. Inhaltlich abgeschlossen ist der Auftrag, sobald die Completion an die anfragende Session übergeben und vom Haupt-Agenten geprüft wurde.

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 zunächst /subagents list auf und suche in der Ausgabe nach summary_test. Übernimm für die folgenden Befehle die dort angezeigte Run-ID oder Listennummer. Ersetze <id|#> durch genau diesen Wert.

/subagents info zeigt Status, Zeitstempel, Session-ID und Cleanup-Angaben. /subagents log gibt die letzten Chat-Turns des gewählten Laufs aus. Mit einer Listennummer könnte die Kontrolle beispielsweise so aussehen:

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

Das optionale tools-Argument nimmt Tool-Aufrufe und deren Ergebnisse in die Log-Ausgabe auf.

Wenn der Haupt-Agent das Child-Ergebnis für seine aktuelle Synthese benötigt, ist sessions_yield der dokumentierte Weg, den Turn zu beenden und auf die zurückgemeldete Completion zu warten. Das ist ebenfalls ein internes Agent-Tool, kein Terminal-Befehl.

Ein erfolgreicher Test erfüllt vier Bedingungen:

1. sessions_spawn wurde tatsächlich aufgerufen.
2. Der Aufruf lieferte eine Child- oder Session-Referenz.
3. /subagents list führt den Lauf auf und /subagents info <id|#> zeigt ihn als abgeschlossen an.
4. Der Haupt-Agent prüft die Completion und erstellt daraus die sichtbare Antwort.

Fehlt nur die sichtbare Antwort, ermittle mit /subagents list die Run-ID oder Listennummer und kontrolliere dann /subagents info <id|#> sowie /subagents log <id|#>. Vermeide einen sofortigen identischen Wiederholungslauf: Der vorhandene Run kann bereits abgeschlossen sein, während die Übergabe oder Synthese noch aussteht.

Aufträge eng begrenzen

Ein Sub-Agent arbeitet zuverlässiger, 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 nicht überschneiden. Ein Worker kann technische Implementierungen untersuchen, während ein zweiter Governance- und Sicherheitsfragen prüft. Der Haupt-Agent dedupliziert anschließend 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.

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

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

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 hat Vorrang vor dem konfigurierten Sub-Agent-Standard:

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

Prüfe verfügbare Modellreferenzen 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 sollte das gewählte Modell widersprüchliche Quellen und Unsicherheit verarbeiten können. Begrenze außerdem die Zahl paralleler Worker und die Länge ihrer Rückgaben.

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

Persistente Agenten und Bindings verwalten

Für eine dauerhafte Rolle legst du einen eigenen Agenten an. Verwende dafür den dokumentierten CLI-Helfer statt eines ungeprüften manuellen Eintrags in agents.list:

openclaw agents add research

Der Helfer führt durch die benötigten Angaben für den Agenten. 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 davor, denselben State-Pfad für mehrere Agenten zu verwenden, weil Auth- und Session-Zustände dadurch kollidieren können.

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

Nach einer Config-Änderung folgt openclaw config validate. Schlägt die Validierung fehl, übernimm die Änderung nicht in den produktiven Gateway-Betrieb. Nutze bei manuellen Anpassungen eine vorherige Kopie der aktiven Config oder korrigiere gezielt den gemeldeten Pfad; ersetze nicht die gesamte Datei durch ein älteres Beispiel.

Drei Schutzebenen auseinanderhalten

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

Die Schutzebenen erfüllen verschiedene Aufgaben. Die Workspace-Trennung reduziert die Vermischung von Arbeitsständen und Agentenregeln. Eine aktivierte Sandbox begrenzt den technisch erreichbaren Ausführungs- und Dateikontext entsprechend ihrer Konfiguration. Die Tool-Policy entscheidet, welche Werkzeuge ein Agent oder Sub-Agent 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 verwirft 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 Ergebnisse der vorherigen Stufe und ein enges Rückgabeformat. Dieses Muster benötigt zusätzliche Übergaben, bietet dafür klar definierte 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 technische Claims 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 Belege und schreibt die finale Fassung selbst.

Die beiden Worker erhalten klar 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.

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

Fehler erkennen und beheben

sessions_spawn fehlt: Prüfe /tools 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 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 die geprüften Änderungen danach 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, klar benannten Sub-Agenten und einer ungefährlichen Leseaufgabe. Kontrolliere Spawn, Status, Log und Completion, bevor du Parallelität erhöhst.

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 versehentlich zu einer dauerhaften Sicherheits- oder Routing-Entscheidung wird.