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

Die Stärke von KI-Agenten zeigt sich nicht erst dann, wenn sie mehr Text ausspucken oder mehr Tickets beantworten. Wirklich interessant wird es, wenn sie Arbeit aufteilen können. Manche Aufgaben werden erst mit mehreren spezialisierten Agenten handhabbar: Recherche parallelisieren, Entwürfe gegenprüfen, lange Analysen auslagern oder Kommunikationskanäle sauber trennen.

In diesem achten Teil der OpenClaw-Serie geht es um zwei Muster, die leicht verwechselt werden:

Sub-Agenten: kurzlebige Worker für einzelne Teilaufgaben.
Persistente Multi-Agent-Setups: dauerhaft konfigurierte Agenten mit eigener Arbeitsumgebung, eigenem Zustand und eigenen Routing-Regeln.

Die entscheidende Frage ist also nicht, ob OpenClaw “irgendwie mehrere Agenten” kann. Entscheidend ist, wann dir ein einmaliger Worker reicht und wann du eine dauerhafte Rolle mit eigener Identität, eigenem Verlauf und eigenem Scope brauchst.

Vor dem Testlauf

Bevor du mit Sub-Agenten oder persistenten Multi-Agenten arbeitest, sollte die OpenClaw-Basis sauber stehen:

openclaw models status
openclaw models list
openclaw config validate

Wichtig sind außerdem:

ein konfigurierter Standard-Agent oder ein klar ausgewählter Ziel-Agent,
ein funktionierender Modellanbieter,
bekannte Kosten- und Rate-Limit-Grenzen deines Providers,
ein sauberer Workspace ohne uncommitted Experimente, falls Agenten Dateien ändern dürfen,
ein klares Verständnis dafür, welche Tools ein Agent ausführen darf.

Wenn du OpenClaw im Nix-Modus betreibst (OPENCLAW_NIX_MODE=1), sind schreibende openclaw config set-Operationen dokumentiert blockiert. Dann änderst du nicht direkt openclaw.json, sondern die Nix-Quelle dahinter.

Zwei Muster: Sub-Agenten vs. persistente Agenten

OpenClaw trennt praktisch zwischen kurzlebiger Delegation und dauerhaftem Multi-Agent-Routing.

Sub-Agenten

Sub-Agenten sind Background-Agent-Runs, die aus einem bestehenden Lauf heraus gestartet werden. Sie laufen in einer eigenen Session. Das dokumentierte Session-Muster sieht so aus:

agent:<agentId>:subagent:<uuid>

Ein Sub-Agent wird als Background-Task verfolgt und meldet sein Ergebnis nach Abschluss zurück an den anfragenden Chat-Kanal.

Das ist nützlich für Aufgaben wie:

parallele Recherche,
längere Analysejobs,
Zusammenfassungen,
unabhängige Reviews,
Extraktion strukturierter Informationen.

Persistente Agenten

Persistente Agenten sind dagegen dauerhaft konfigurierte Einheiten. Die Multi-Agent-Routing-Dokumentation beschreibt sie als isolierte Agenten mit eigener Workspace-Struktur, eigenem Zustand, eigener Session-History und eigenen Auth-Profilen.

Wichtige dokumentierte Pfade sind:

~/.openclaw/agents/<agentId>/
~/.openclaw/agents/<agentId>/sessions
~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Ein Binding ordnet dabei einen Channel-Account, zum Beispiel einen Slack-Workspace oder eine WhatsApp-Nummer, einem Agenten zu.

Als Faustregel taugt:

Nutze Sub-Agenten, wenn eine konkrete Teilaufgabe parallel oder isoliert erledigt werden soll.
Nutze persistente Agenten, wenn eine Rolle dauerhaft existieren soll, etwa Support, Redaktion, Recherche oder ein Agent pro Kanal.

Nicht jede lokale Komfortfunktion ist ein API-Vertrag

OpenClaw entwickelt sich schnell. Darum solltest du sauber trennen zwischen belastbar dokumentierten Konzepten und lokal verfügbaren Komfortbefehlen.

Verlass dich nicht blind darauf, dass Bezeichner wie diese in jeder Installation als stabile öffentliche Schnittstelle auftauchen:

/subagents spawn
/subagents list
/subagents log
/subagents send
sessions_spawn
sessions_yield

Wenn deine Installation solche Befehle oder Tools anbietet, prüfe zuerst lokale Help-Ausgabe, Tool-Beschreibung oder die aktuell installierte Dokumentation. Alte Blog-Beispiele taugen nicht als stillschweigender API-Vertrag.

Preflight: Modelle und Config prüfen

Starte mit den Modell- und Config-Prüfungen:

openclaw models status
openclaw models list
openclaw config file
openclaw config validate

openclaw models status zeigt den aufgelösten Standard, Fallbacks und eine Auth-Übersicht. openclaw models list ist laut CLI-Dokumentation lesend und schreibt den Modellkatalog nicht um.

Für Konfigurationsarbeit helfen diese Befehle:

openclaw config schema
openclaw config get agents.defaults.model --json
openclaw config get agents.defaults.models --json
openclaw config get agents.list --json

Wenn agents.list leer ist, heißt das nicht automatisch, dass OpenClaw nicht funktioniert. Es kann schlicht bedeuten, dass du bisher nur mit Defaults arbeitest. Für persistente Multi-Agent-Setups solltest du aber bewusst prüfen, welche Agenten tatsächlich konfiguriert sind.

Sub-Agenten kontrolliert testen

Der sichere Einstieg ist kein großer Agenten-Schwarm, sondern ein einzelner ungefährlicher Testauftrag.

Öffne eine funktionierende OpenClaw-Interaktion und formuliere den Auftrag so, dass der Haupt-Agent nur dann einen Sub-Agenten startet, wenn deine Installation die Capability wirklich anbietet:

Wenn in dieser OpenClaw-Installation Sub-Agenten verfügbar sind, starte bitte genau einen Sub-Agenten für folgende Aufgabe: Fasse diese Unterhaltung in fünf Bulletpoints zusammen und liste offene Entscheidungen separat. Gib mir anschließend die Task- oder Session-ID und das Ergebnis zurück. Wenn keine Sub-Agent-Capability verfügbar ist, sage das ausdrücklich und führe die Aufgabe nicht als normalen Ersatzlauf aus.

Woran du einen sauberen Test erkennst:

Der Haupt-Agent meldet, dass ein Sub-Agent oder Background-Task gestartet wurde.
Es gibt eine erkennbare Task-, Run- oder Session-Referenz.
Das Ergebnis kommt nach Abschluss zurück in den anfragenden Chat.
Der Auftrag wurde nicht heimlich ohne Sub-Agent als normale Antwort erledigt.

Wenn deine Oberfläche oder Chat-Umgebung zusätzlich Help- oder Detailfunktionen für Sub-Agenten anzeigt, nutze diese lokale Hilfe. Verlasse dich aber nicht auf Syntax aus älteren Beispielen, solange sie nicht in deiner Installation bestätigt ist.

Gute Aufträge für Sub-Agenten formulieren

Sub-Agenten liefern bessere Ergebnisse, wenn Auftrag und Rückgabeformat eng begrenzt sind.

Schlecht:

Recherchiere Kubernetes-Agenten.

Besser:

Recherchiere Kubernetes-Agenten. Liefere maximal 8 Bulletpoints. Jeder Bulletpoint soll Name, Zweck, Reifegrad und ein technisches Risiko enthalten. Keine langen Erklärtexte.

Noch besser für parallele Arbeit:

Bearbeite nur Open-Source-Projekte. Ignoriere SaaS-only-Angebote. Liefere maximal 8 Bulletpoints mit Projektname, Repository-Hinweis, Nutzen, Reifegrad und Risiko.

Der Haupt-Agent kann die Ergebnisse anschließend vergleichen, deduplizieren und in ein finales Ergebnis überführen. Praktisch bewährt haben sich kurze, strukturierte Rückgaben statt langer Fließtexte.

Ergebnisse sauber zusammenführen

Ein gutes Multi-Agent-Setup braucht klare Fan-In-Regeln. Der Haupt-Agent sollte Sub-Agent-Ergebnisse nicht einfach zusammenkleben, sondern prüfen:

widersprechen sich Aussagen?
fehlen Quellen, Dateipfade oder Annahmen?
sind Punkte doppelt?
ist ein Worker vom Auftrag abgewichen?
sind kritische Aussagen überprüfbar?

Für technische Reviews ist ein einheitliches Rückgabeformat hilfreich:

Gib dein Ergebnis in diesen Abschnitten zurück:
1. Befund
2. Beleg oder Datei-/Quellenhinweis
3. Risiko
4. Empfohlene Aktion

Für Schreibarbeit reicht oft ein kompakteres Format:

Gib maximal 6 Bulletpoints zurück. Markiere unsichere Aussagen mit UNSICHER. Nenne keine erfundenen Quellen.

Kostenmanagement durch Modellauswahl

Jeder Sub-Agent verbraucht eigene Tokens. Parallelisierung beschleunigt Aufgaben, kann aber Kosten und Rate-Limit-Druck deutlich erhöhen.

OpenClaw verwendet Modell-Referenzen im Format:

provider/model

Prüfe verfügbare und konfigurierte Modelle mit:

openclaw models status
openclaw models list

Das Setzen eines globalen Standardmodells erfolgt dokumentiert über:

openclaw models set provider/model

Setze das globale Modell aber nicht leichtfertig nur für einen Testlauf um. Prüfe zuerst, ob deine konkrete Sub-Agent-Oberfläche oder dein lokaler Agenten-Workflow pro Auftrag eine Modellwahl unterstützt. Wenn nicht, plane die Kosten über kleinere Aufgaben, weniger Parallelität und kürzere Rückgabeformate.

Praktische Strategie:

günstigeres Modell für Vorarbeit, Extraktion und Zusammenfassung,
stärkeres Modell für finale Synthese, Architekturentscheidungen oder kritische Reviews,
harte Begrenzung der parallelen Worker,
kurze Ergebnisformate statt unkontrollierter Langantworten,
keine Massentests gegen produktive Provider-Limits.

Persistente Multi-Agent-Setups konfigurieren

Dauerhafte Multi-Agent-Setups gehören in die OpenClaw-Konfiguration. Die Live-Dokumentation verweist auf openclaw.json, agents.*, multiAgent.*, session.* und die openclaw config-Hilfsbefehle.

Verwende deshalb keine alten YAML-Beispiele und schreibe nicht blind in Config-Dateien. Prüfe das aktive Schema deiner Installation:

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

Die Multi-Agent-Routing-Dokumentation beschreibt einen Agenten als vollständigen Scope mit:

Workspace-Dateien,
Persona- und Regeldateien wie AGENTS.md, SOUL.md oder USER.md, sofern verwendet,
eigenem agentDir,
eigener Session-History,
eigenen Auth-Profilen,
eigener Modell- und Provider-Konfiguration.

Sicherer Ablauf für Änderungen:

Aktive Config-Datei anzeigen:

openclaw config file

Schema ausgeben und passende Felder prüfen:

openclaw config schema

Bestehende Agentenliste lesen:

openclaw config get agents.list --json

Änderung als Patch oder in einer Kopie vorbereiten.
Validierung ausführen:

openclaw config validate

Erst wenn die Validierung sauber ist, sollte der Agent produktiv an Kanäle oder Automationen gebunden werden.

Bewährte Orchestrierungs-Muster

Je nach Anwendungsfall haben sich drei Muster bewährt.

Fan-Out / Fan-In

Viele unabhängige Teilaufgaben werden parallel bearbeitet und anschließend zusammengeführt. Beispiel: Zehn Dokumente werden von mehreren Workern zusammengefasst; der Haupt-Agent erstellt daraus eine priorisierte Gesamtauswertung.

Achte dabei auf:

maximale Parallelität,
einheitliches Rückgabeformat,
Deduplizierung,
Quellen- oder Dateireferenzen pro Ergebnis,
klare Abbruchregeln, wenn ein Worker scheitert.

Pipeline-Processing

Mehrere Agenten arbeiten nacheinander:

Recherche → Outline → Entwurf → Review → finale Fassung

Dieses Muster ist langsamer als reines Fan-Out, aber besser kontrollierbar. Es eignet sich besonders für Analyse-, Schreib- und Review-Prozesse.

Supervisor-Worker

Ein Haupt-Agent plant und überwacht mehrere Worker. Die Worker führen nur Teilaufgaben aus und treffen keine endgültigen Entscheidungen. Dieses Muster ist sinnvoll, wenn Qualitätssicherung wichtiger ist als maximale Geschwindigkeit.

Praxisbeispiel: Schreib- und Recherche-Workflow

Ein robuster Workflow kann so aussehen:

Supervisor definiert Thema und Qualitätskriterien.
Zwei Research-Sub-Agenten recherchieren getrennte Perspektiven.
Ein Outline-Schritt strukturiert die Ergebnisse.
Ein Writing-Schritt erstellt einen Arbeitsentwurf.
Der Supervisor prüft Konsistenz, Quellenlage und Tonalität.

Beispielhafte Aufträge für zwei getrennte Worker:

Worker A: Recherchiere technische Fakten zum Thema. Liefere 8 Bulletpoints mit Risiko-Hinweisen. Markiere unsichere Aussagen ausdrücklich.

Worker B: Recherchiere Zielgruppen- und Nutzenargumente. Liefere 8 Bulletpoints ohne Werbesprache. Trenne belegbare Fakten von Annahmen.

Danach sollte der Haupt-Agent aktiv prüfen:

widersprechen sich Aussagen?
fehlen Quellen oder Annahmen?
sind Punkte doppelt?
ist ein Worker offensichtlich vom Auftrag abgewichen?
braucht ein Punkt menschliche Nachprüfung?

Typische Fehlerquellen und Monitoring

Häufige Probleme:

Zu viele parallele Sub-Agenten: führt zu Rate Limits und unkontrollierten Kosten.
Unklare Aufgaben: Worker liefern lange, schwer vergleichbare Antworten.
Kein Fehlerpfad: ein einzelner fehlgeschlagener Worker blockiert den Ablauf.
Unkontrollierte Dateizugriffe: mehrere Agenten schreiben in dieselben Dateien.
Zu starke Modelle für triviale Aufgaben: unnötig teuer.
Verwechslung von Sub-Agenten und persistenten Agenten: kurzlebige Delegation ersetzt keine sauber konfigurierte Langzeitrolle.

Gegenmaßnahmen:

mit genau einem Sub-Agenten starten,
Parallelität erst nach erfolgreichen Tests erhöhen,
kurze strukturierte Rückgabeformate verlangen,
bei Dateiarbeit getrennte Pfade verwenden,
Logs, Background-Task-Status oder lokale Run-Details direkt nach jedem Testlauf prüfen,
Konfigurationsänderungen immer mit openclaw config validate absichern.

Sicherheit und Isolation

Multi-Agent-Setups erhöhen die Angriffs- und Fehlerfläche. Jeder zusätzliche Worker kann je nach Konfiguration Werkzeuge ausführen, Dateien lesen oder Tokens verbrauchen.

Praktische Sicherheitsregeln:

keine Secrets in Sub-Agent-Prompts kopieren,
Dateischreibrechte minimieren,
gefährliche Tools nur gezielt freigeben,
für Experimente separate Workspaces verwenden,
Logs nicht ungeprüft veröffentlichen,
Ergebnisse von Sub-Agenten wie untrusted Input behandeln,
bei persistenter Agententrennung Auth-Profile und Channel-Bindings bewusst prüfen.

Besonders wichtig: Ein Sub-Agent-Ergebnis ersetzt keine Prüfung. Kritische Aussagen müssen vom Haupt-Agenten oder von einem menschlichen Reviewer gegengecheckt werden.

Einstieg in die Praxis

Starte mit einem ungefährlichen Testauftrag:

Wenn Sub-Agenten verfügbar sind, starte genau einen Sub-Agenten: Fasse diese Unterhaltung in fünf Bulletpoints zusammen und liste offene Entscheidungen separat. Melde mir Task- oder Session-Referenz und Ergebnis. Wenn Sub-Agenten nicht verfügbar sind, brich ab und erkläre kurz warum.

Prüfe danach:

Wurde wirklich ein Background-Task oder Sub-Agent gestartet?
Kam eine Task- oder Session-Referenz zurück?
Ist das Ergebnis kurz und strukturiert?
Entspricht es exakt dem Auftrag?

Wenn das sauber funktioniert, teste einen zweiten Worker mit einer klar getrennten Aufgabe. Erst danach lohnt sich eine echte Pipeline.

Ein guter produktiver Anwendungsfall zum Einstieg ist ein Proofreading-Agent: Während du am Haupttext arbeitest, prüft ein Sub-Agent Rechtschreibung, Verständlichkeit und fehlende Übergänge. Der Nutzen der Parallelisierung wird sofort sichtbar, ohne dass du riskante Dateizugriffe oder komplexe Agentenketten brauchst.

Weiterlesen

Die Grundlagen zu Automationen stehen in Cron-Jobs, Heartbeats und Automationen.
Für spätere Praxis-Setups ergänzt Remote Nodes den Blick auf verteilte Agenten-Umgebungen.

Die praktische Konsequenz

Sub-Agenten sind in OpenClaw ein brauchbares Werkzeug für parallele, klar abgegrenzte Aufgaben. Laut Dokumentation laufen sie als eigene Background-Agent-Runs mit eigener Session und melden ihr Ergebnis an den anfragenden Chat zurück.

Für dauerhafte Multi-Agent-Setups gilt etwas anderes: Halte dich an das aktuelle openclaw.json-Schema, validiere jede Änderung und prüfe lokale Tool- oder Help-Schnittstellen, bevor du daraus Automationen baust. Dann bleibt dein Agenten-Orchester nachvollziehbar, bezahlbar und wartbar.