Multi-Agent-Systeme: Wenn KIs zusammenarbeiten — Teil 4 der Serie „KI-Agenten in der Praxis“

Ein einzelner KI-Agent gerät bei großen Aufgaben leicht ins Schleudern: Der Kontext füllt sich, Zwischenergebnisse vermischen sich und eine Instanz mit vielen Werkzeugen kann mehr verändern als beabsichtigt. Ein Multi-Agent-Workflow verteilt die Arbeit auf begrenzte Rollen und macht Übergaben prüfbar.

OpenClaw bringt dafür inzwischen mehrere Laufzeitbausteine mit. Subagents und getrennte ACP-Läufe können Arbeit im Hintergrund ausführen. Background Tasks protokollieren solche abgekoppelten Läufe. Task Flow bildet darüber dauerhafte Abläufe ab. Diese Funktionen ersetzen jedoch keine fachliche Planung: Rollen, Eingabe- und Ausgabeformate, Tool-Rechte und Abbruchregeln musst du weiterhin bewusst festlegen.

Dieses Tutorial baut deshalb zuerst einen kleinen, lokalen Vertrags- und Validierungsschritt. Er startet noch keinen Agenten. Du erhältst damit ein reproduzierbares Gate, das sich später vor einen OpenClaw-Subagent, einen ACP-Lauf, einen CI-Job oder einen eigenen Task-Flow-Controller setzen lässt.

Voraussetzungen prüfen

Du brauchst:

• eine funktionierende OpenClaw-Installation,
• Zugriff auf mindestens ein nutzbares Modell,
• eine Shell in einem bewusst gewählten Test- oder Projektverzeichnis,
• python3 für den lokalen Validator.

Prüfe zunächst die aktive Konfiguration:

openclaw config file
openclaw config validate

openclaw config file gibt den Pfad der aktiven Konfigurationsdatei aus. Bei einer gültigen Konfiguration endet openclaw config validate erfolgreich. Für eine maschinenlesbare Prüfung kannst du openclaw config validate --json verwenden.

Wenn OPENCLAW_NIX_MODE=1 gesetzt ist, behandelt OpenClaw openclaw.json als unveränderlich. Lesende Befehle wie config file, config get, config schema und config validate funktionieren weiterhin. Schreibende Config-Befehle werden abgelehnt; Änderungen gehören dann in die Nix-Quelle des Setups.

Prüfe anschließend den Modellzugang:

openclaw models status
openclaw models list

openclaw models status zeigt die aufgelöste Primär- und Fallback-Konfiguration sowie den Authentifizierungsstatus. openclaw models list listet standardmäßig die konfigurierten Modelle. Wenn du absichtlich das Standardmodell ändern willst, lautet der dokumentierte Befehl:

openclaw models set <provider/model>

Ersetze den Platzhalter nur durch ein Modell, das in deiner Umgebung verfügbar und authentifiziert ist. Die lokale Demo selbst erfordert keine Änderung des Standardmodells.

Was OpenClaw übernimmt — und was nicht

Für dieses Muster sind drei OpenClaw-Ebenen relevant:

Agent- und Modellkonfiguration: agents.defaults definiert gemeinsame Vorgaben. agents.list enthält explizit konfigurierte Agenten mit stabilen IDs und möglichen Überschreibungen. Unter agents.defaults.model.primary liegt das Primärmodell; agents.defaults.model.fallbacks enthält die geordnete Liste der Modell-Fallbacks.

Abgekoppelte Arbeit: Subagent-, ACP- und Automationsläufe können als Background Tasks erfasst werden. Diese Tasks sind Aktivitätsdatensätze mit Zuständen wie queued, running und einem terminalen Ergebnis. Sie sind kein Scheduler und legen nicht selbst fest, wann ein Workflow startet.

Task Flow: Ein verwalteter Task Flow wird durch Plugin-Code gesteuert und kann mehrere Schritte mit dauerhaftem Status und verknüpften Tasks abbilden. Für abgekoppelte ACP- oder Subagent-Läufe kann OpenClaw außerdem automatisch einen gespiegelten Ein-Task-Flow anlegen. Ein solcher Spiegel macht den Lauf beobachtbar, entwirft aber noch keine mehrstufige Fachpipeline.

Die Rollen- und Rechtearchitektur bleibt daher deine Aufgabe. OpenClaw kann Läufe, Konfiguration und Zustände verwalten; es kann nicht aus einem unpräzisen Auftrag automatisch einen sicheren Produktionsprozess ableiten.

Konfigurationspfade vor Änderungen verifizieren

Prüfe Schema und Ist-Zustand, bevor du agentenspezifische Werte änderst:

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

Die aktuellen Schema-Pfade unterscheiden zwischen:

• agents.defaults.model.primary für das Primärmodell,
• agents.defaults.model.fallbacks für geordnete Fallbacks,
• agents.defaults.models für den konfigurierten Modellkatalog und die Allowlist,
• agents.list für explizite Agenteneinträge.

agents.defaults.models ist keine vollständige Sicherheitsgrenze. Laut Modelldokumentation beschränkt ein Eintrag dort Modell-Overrides nicht automatisch. Werkzeugrechte, Agentenprofile und Laufzeitgrenzen musst du separat durchsetzen.

Ändere agents.list[0] außerdem nie nur aufgrund des Indexnamens. Lies zuerst die Liste aus und prüfe, welcher Agent an dieser Position steht. Nach einer tatsächlichen Änderung folgt immer:

openclaw config validate

Rollen klar schneiden

Ein belastbarer Workflow trennt Steuerung, Facharbeit und deterministische Übergaben.

Conductor oder Orchestrator: Diese Komponente zerlegt den Auftrag, erzeugt Task-Verträge, startet Arbeitsschritte und entscheidet anhand validierter Ergebnisse über den nächsten Schritt. Das kann Plugin-Code für einen verwalteten Task Flow, ein Skript, ein CI-Job oder ein manuell gestarteter Prozess sein.

Spezialisten: Ein Spezialist bearbeitet ein enges Teilproblem, etwa Recherche, Code-Änderung, Test, Review oder Dokumentation. Für jede Rolle legst du Eingaben, Werkzeuge, Arbeitsverzeichnis, Modell und Ausgabeformat fest.

Bridge-Schritte: Ein Bridge-Schritt ist meist ein deterministisches Skript. Es prüft JSON, normalisiert Felder oder überführt ein validiertes Ergebnis in das Format des nächsten Schritts. Für solche Aufgaben ist kein zusätzlicher LLM-Lauf nötig.

Strukturierte Task-Verträge verwenden

Übergib nicht den kompletten Chat-Verlauf an den nächsten Arbeitsschritt. Verwende ein Artefakt, das Rolle, Eingaben, Rechte und erwartete Ausgabe beschreibt:

{
  "task_id": "research-2026-04-01-mas-001",
  "role": "research",
  "input": {
    "topic": "Multi-Agent-Orchestrierung für Coding-Workflows",
    "urls": [
      "https://addyosmani.com/blog/code-agent-orchestra/",
      "https://docs.openclaw.ai/concepts/models.md"
    ]
  },
  "allowed_actions": [
    "read_url",
    "summarize",
    "extract_claims"
  ],
  "forbidden_actions": [
    "publish",
    "write_production_code",
    "modify_config"
  ],
  "output_schema": {
    "claims": "array",
    "sources": "array",
    "uncertainties": "array"
  },
  "timeout_seconds": 600
}

Dieses JSON dokumentiert die beabsichtigten Grenzen. Es erzwingt sie noch nicht. Wenn die ausführende Instanz technisch Zugriff auf Publishing- oder Config-Werkzeuge hat, verhindert forbidden_actions allein keinen Tool-Aufruf. Harte Grenzen gehören in Tool-Policies, getrennte Agentenprofile, Sandboxes, Betriebssystemrechte oder CI-Regeln.

Lokales Vertrags-Gate nachbauen

Führe die nächsten Befehle in einem Testverzeichnis aus. Der folgende Block bricht ab, falls dort bereits ein Eintrag namens mas-demo existiert. Dadurch überschreibt das Tutorial keinen früheren Versuch:

if [ -e mas-demo ]; then
  echo 'mas-demo already exists; choose another directory or inspect it first' >&2
  exit 1
fi

mkdir -p mas-demo/workflows/content-pipeline/tasks
mkdir -p mas-demo/workflows/content-pipeline/outputs/research
mkdir -p mas-demo/workflows/content-pipeline/outputs/writing
mkdir -p mas-demo/workflows/content-pipeline/outputs/review
mkdir -p mas-demo/workflows/content-pipeline/logs
cd mas-demo

Lege den Vertrag an:

cat > workflows/content-pipeline/tasks/research-task.json <<'JSON'
{
  "task_id": "research-2026-04-01-mas-001",
  "role": "research",
  "input": {
    "topic": "Multi-Agent-Orchestrierung für Coding-Workflows",
    "urls": [
      "https://addyosmani.com/blog/code-agent-orchestra/",
      "https://docs.openclaw.ai/concepts/models.md"
    ]
  },
  "allowed_actions": ["read_url", "summarize", "extract_claims"],
  "forbidden_actions": ["publish", "write_production_code", "modify_config"],
  "output_schema": {
    "claims": "array",
    "sources": "array",
    "uncertainties": "array"
  },
  "timeout_seconds": 600
}
JSON

Nun folgt der Validator:

cat > workflows/content-pipeline/validate_task.py <<'PY'
import json
import sys
from pathlib import Path

ALLOWED_ROLES = {'research', 'writing', 'review'}
ALLOWED_SCHEMA_TYPES = {'array', 'object', 'string', 'number', 'boolean'}
REQUIRED = {
    'task_id',
    'role',
    'input',
    'allowed_actions',
    'forbidden_actions',
    'output_schema',
    'timeout_seconds',
}


def fail(message):
    raise SystemExit('invalid task contract: ' + message)


if len(sys.argv) != 2:
    fail('usage: validate_task.py PATH')

path = Path(sys.argv[1])
try:
    data = json.loads(path.read_text(encoding='utf-8'))
except OSError as error:
    fail('cannot read file: ' + str(error))
except json.JSONDecodeError as error:
    fail('invalid JSON: ' + str(error))

if not isinstance(data, dict):
    fail('top level must be an object')

missing = sorted(REQUIRED - data.keys())
if missing:
    fail('missing required fields: ' + ', '.join(missing))

task_id = data['task_id']
if not isinstance(task_id, str) or not task_id.strip():
    fail('task_id must be a non-empty string')

role = data['role']
if not isinstance(role, str) or role not in ALLOWED_ROLES:
    fail('unsupported role: ' + repr(role))

if not isinstance(data['input'], dict) or not data['input']:
    fail('input must be a non-empty object')

for key in ('allowed_actions', 'forbidden_actions'):
    value = data[key]
    if not isinstance(value, list):
        fail(key + ' must be a list')
    if not all(isinstance(item, str) and item.strip() for item in value):
        fail(key + ' must contain non-empty strings only')
    if len(value) != len(set(value)):
        fail(key + ' must not contain duplicates')

overlap = sorted(set(data['allowed_actions']) & set(data['forbidden_actions']))
if overlap:
    fail('actions listed as allowed and forbidden: ' + ', '.join(overlap))

schema = data['output_schema']
if not isinstance(schema, dict) or not schema:
    fail('output_schema must be a non-empty object')
for field, declared in schema.items():
    if not isinstance(field, str) or not field.strip():
        fail('output_schema field names must be non-empty strings')
    if declared not in ALLOWED_SCHEMA_TYPES:
        fail('unsupported output type for ' + field + ': ' + repr(declared))

timeout = data['timeout_seconds']
if isinstance(timeout, bool) or not isinstance(timeout, int):
    fail('timeout_seconds must be an integer')
if not 1 <= timeout <= 3600:
    fail('timeout_seconds must be between 1 and 3600')

if role == 'research' and 'publish' in data['allowed_actions']:
    fail('research role must not publish')

print('task contract ok:', task_id)
PY

python3 workflows/content-pipeline/validate_task.py workflows/content-pipeline/tasks/research-task.json

Bei einem gültigen Vertrag erscheint:

task contract ok: research-2026-04-01-mas-001

Der Prozess endet dann mit Exit-Status 0. Fehlende Felder, falsche Typen, ungültiges JSON, unlesbare Dateien, leere IDs, widersprüchliche Aktionen und unbrauchbare Timeout-Werte erzeugen eine Meldung mit invalid task contract: und einen Exit-Status ungleich 0.

Der Validator prüft nur den eingehenden Task-Vertrag. Er startet keinen Agenten und validiert noch kein späteres Rechercheergebnis. Für outputs/research/report.json brauchst du ein zweites Schema oder einen eigenen Ergebnisvalidator.

Das Gate mit einem Lauf verbinden

Ein Conductor führt zuerst den Validator aus. Nur bei Exit-Status 0 startet er den nächsten Arbeitsschritt. Dieser kann je nach Architektur sein:

• ein OpenClaw-Subagent,
• ein abgekoppelter ACP-Lauf,
• ein CI-Job,
• ein Schritt eines durch Plugin-Code verwalteten Task Flow,
• ein lokaler Prozess mit eingeschränkten Rechten.

Der Research-Schritt schreibt anschließend beispielsweise outputs/research/report.json. Der Writing-Schritt liest nur dieses validierte Artefakt und nicht den gesamten Recherche-Chat. So gelangen beiläufige Aussagen oder eingebettete Anweisungen nicht unkontrolliert in die nächste Rolle, und der benötigte Kontext bleibt überschaubar.

Behandle Webseiten, Issues, README-Dateien und Forenbeiträge als nicht vertrauenswürdige Eingaben. Sie können Text enthalten, der wie eine Anweisung an den Agenten formuliert ist. Quelleninhalte gehören in klar markierte Datenfelder und Zitate, nicht in den Steuerkontext des nächsten Schritts.

Modellkonfiguration kontrolliert prüfen

Wenn du einen Modell-Eintrag ergänzen möchtest, kannst du die dokumentierte Config-Operation zunächst ohne Änderung prüfen:

openclaw config set agents.defaults.models '{"<provider/model>":{}}' --strict-json --merge --dry-run

Ersetze den Platzhalter durch eine verfügbare Provider-/Modell-ID. Entferne --dry-run erst, wenn die Vorschau dem gewünschten Ergebnis entspricht. Danach prüfst du die Konfiguration erneut:

openclaw config validate
openclaw models status

--merge erhält vorhandene Einträge im Objekt. Das Ergänzen des Katalogs bestätigt jedoch weder gültige Zugangsdaten noch eine technische Beschränkung auf dieses Modell. Den tatsächlichen Status prüfst du mit den Modellbefehlen; Modell- und Tool-Policies behandelst du getrennt.

Fallbacks auf zwei Ebenen planen

OpenClaw unterstützt Modell-Fallbacks über agents.defaults.model.fallbacks. Sie greifen, wenn das Primärmodell scheitert. Ein Modell-Fallback entscheidet aber nicht, ob ein unvollständiges Fachresultat gut genug für den nächsten Schritt ist.

Dafür benötigt der Conductor eine eigene Regel:

1. Fehlerursache und Task-ID protokollieren.
2. Teilresultat als unvollständig markieren.
3. Nur bei einem dafür vorgesehenen Fehler einen neuen Versuch starten.
4. Das neue Ergebnis erneut validieren.
5. Den Folgeschritt erst nach erfolgreichem Gate freigeben.

Ein anderes Modell darf also nicht automatisch eine bereits fehlgeschlagene Schema- oder Rechteprüfung umgehen.

Wenn etwas klemmt

Die OpenClaw-Konfiguration ist ungültig

Lass dir den aktiven Pfad anzeigen und prüfe die zuletzt veränderte Stelle:

openclaw config file
openclaw config validate --json

Bei einem Nix-Setup änderst du die deklarative Nix-Quelle statt openclaw.json direkt zu beschreiben.

Kein Modell ist nutzbar

Prüfe Status und konfigurierte Modelle:

openclaw models status
openclaw models list

Richte anschließend die passende Provider-Authentifizierung ein. Starte den Multi-Agent-Lauf erst, wenn der Status den benötigten Modellzugang bestätigt.

mas-demo existiert bereits

Der Setup-Block bricht absichtlich ab. Wechsle in ein anderes Testverzeichnis, wähle einen neuen Namen oder untersuche den vorhandenen Ordner. Lösche ihn nicht ungeprüft: Er kann Ergebnisse eines früheren Laufs enthalten.

Der Vertrag wird abgelehnt

Die Meldung hinter invalid task contract: nennt die verletzte Regel. Repariere das JSON und führe denselben Validator erneut aus. Lockere das Gate nicht nur, um den nächsten Schritt starten zu können.

Der Vertrag ist gültig, das Agentenergebnis aber unbrauchbar

Das Vertrags-Gate bestätigt nur den Startauftrag. Prüfe das Ergebnis mit einem getrennten Ausgabeschema, bevor Writing, Code-Änderung oder Publishing beginnen. Ohne dieses zweite Gate bleibt die zentrale Übergabe ungeschützt.

Praxisbezug: Code Agent Orchestra

Addy Osmani beschreibt mit dem Code Agent Orchestra ein Muster für spezialisierte Coding-Agenten mit klaren Zuständigkeiten, Artefakten und Feedback-Schleifen. Der relevante Punkt ist nicht die Anzahl gleichzeitig laufender Instanzen. Entscheidend ist, ob jede Rolle eine abgegrenzte Aufgabe erhält und ob nachgelagerte Schritte die Ergebnisse prüfen können.

Für OpenClaw heißt das heute: Nutze Agent-Konfiguration, Subagents, Background Tasks und Task Flow dort, wo sie zum gewünschten Laufmodell passen. Ergänze diese Infrastruktur um Task-Verträge, technische Tool-Grenzen und Ergebnisvalidatoren. Ein automatisch erfasster Task oder gespiegelter Flow ist beobachtbar, aber noch keine sichere Fachpipeline.

Die Framework-Perspektive behandelt der Vergleich zwischen LangChain, CrewAI und AutoGen. Die praktische Konfigurationsseite vertieft der Artikel zur OpenClaw-Gateway-Konfiguration.

Sicherheitsregeln für Multi-Agent-Workflows

• Recherche- und Analyse-Rollen erhalten keine Schreib-, Deploy- oder Publishing-Rechte.
• Secrets gehören weder in Task-JSON noch in Agenten-Prompts oder Ergebnisartefakte.
• Konfigurationsänderungen werden zuerst geprüft und danach mit openclaw config validate validiert.
• Task-ID, Modell, Eingabe, Ausgabe und Exit-Status werden pro Übergabe protokolliert.
• Externe Quellen und LLM-Ausgaben gelten bis zur Validierung als nicht vertrauenswürdig.
• Werkzeuggrenzen werden in Agent-Konfiguration, Laufzeit, Sandbox, CI oder Betriebssystemrechten erzwungen.
• Schreibende Rollen arbeiten in getrennten Arbeitsverzeichnissen oder Sandboxes.
• Ein Modell-Fallback darf kein fehlgeschlagenes Vertrags-, Rechte- oder Ergebnis-Gate überspringen.

Kernpunkte

Multi-Agent-Systeme werden belastbar, wenn Rollen, Übergaben und Rechte explizit sind. OpenClaw stellt dafür inzwischen Agentenläufe, Background Tasks, Task Flow sowie Modell- und Gateway-Konfiguration bereit. Die fachlichen Verträge und Sicherheitsgrenzen entstehen trotzdem nicht automatisch.

Ein prüfbarer Schritt hat eine klar benannte Rolle, strukturierte Eingaben, technisch begrenzte Werkzeuge, eine validierte Ausgabe und ein protokolliertes Ergebnis. Erst wenn dieses Gate erfolgreich ist, darf der nächste Agent oder Prozess übernehmen.