2026 Linux-Cloud-VPS Multi-Agent-Pipelines: LangGraph-Orchestrierung vs OpenClaw Gateway, systemd und gestufte Fehleranalyse FAQ

Letzte Woche hat ein Team die Supervisor-Worker-Topologie aus unserem Artikel zur Multi-Agent-Pipeline-Architektur auf einen Linux VPS übertragen. Im Test lief alles sauber: Slack-Events kamen an, Antworten wurden generiert, die Demo wirkte stabil. Nach einem geplanten Reboot am Wochenende zeigte sich jedoch das typische Produktionsbild: Freigabe-Interrupts waren weg, alte checkpoint-Zweige wurden erneut gestartet, Cron-Jobs liefen doppelt, und die Kanalebene meldete "ok", obwohl die Graph-Ausführung inkonsistent war. Der Fehler lag nicht beim Modell, sondern in der Betriebsarchitektur.

In der Praxis gilt: Multi-Agent bedeutet nicht "mehr Python-Prozesse". Entscheidend ist eine klare Trennung der Verantwortlichkeiten. LangGraph steuert Zustandsübergänge, Kantenlogik, checkpoint-Persistenz und Wiederaufnahme per thread_id/interrupt. OpenClaw Gateway steuert Ingress (IM/Webhook), Zeitplanung, Zugriffsgrenzen und 24x7-Betriebsbeobachtung. Dieser Leitfaden konzentriert sich auf belastbare Umsetzung auf Linux VPS: Entscheidungs-Matrix, Minimal-Topologie, Übergabevertrag, systemd-Basis und L0-L3-Fehlersuche. Für Gateway-Betrieb inkl. Logs siehe OpenClaw Linux Troubleshooting FAQ; für Budget und Token-Steuerung ergänzend den Beitrag zur Agent-Kostenrechnung.

Warum man auf VPS Orchestrierung und Execution Layer trennen muss

Auf localhost funktioniert eine lineare Pipeline (Planner -> Coder -> Reviewer) oft überraschend gut. Unter realer Last auf einem Linux VPS kommen aber mehrere Produktionsanforderungen zusammen:

• Heterogene Eingänge - Slash-Commands, Direktnachrichten, Webhooks und Cron-Ereignisse erfordern saubere Ingress-Regeln.
• Lange Pausen - menschliche Freigaben können Stunden dauern; checkpoint muss Reboots überleben.
• Rechte-Trennung - der öffentliche Gateway-Prozess darf keine vollprivilegierten MCP-Schlüssel tragen.
• Getrennte Beobachtbarkeit - TLS/403 sind Gateway-Themen, Schleifen/State-Konflikte sind Graph-Themen.

Darum empfehlen wir als Standard: LangGraph intern binden (private Adresse), OpenClaw Gateway als separaten Dienst betreiben. Gateway normalisiert eingehende Ereignisse und ruft den Graph kontrolliert auf; LangGraph bleibt alleinige Quelle für Workflow-Status. Diese Trennung reduziert Risiken bei Deployments, vereinfacht Audits und verkürzt die Incident-Zeit, weil jede Ebene eine klare Diagnosegrenze hat.

Topologie-Matrix: drei typische VPS-Betriebsformen

In Projekten sehen wir regelmäßig drei stabile Muster. Die Auswahl hängt von Kanalanforderungen, Persistenzbedarf und Tool-Schwere ab:

Form A ist der häufigste Einstieg, aber nur stabil mit sauberer Persistenz. Form B ist meist die bessere Produktionswahl, sobald rechenintensive Tools benötigt werden: Das VPS bleibt schlank für Ingress plus Orchestrierung, schwere Ausführung wandert auf Cloud-Mac-Ressourcen. Form C passt zu einfachen Abläufen, sollte aber nicht überdehnt werden, wenn komplexe Freigabe- und Parallelpfade wachsen.

Zu Modellierung und Agent-Handoffs siehe die LangGraph Multi-Agent-Konzepte. Zu Ingress- und Gateway-Parametern siehe OpenClaw Gateway Configuration.

Minimal reproduzierbare Topologie (Form A)

Für einen belastbaren Erststart nutzen wir folgende Minimalstruktur:

1. LangGraph API - per FastAPI kapseln, auf 127.0.0.1:8123 binden, checkpoint auf persistentes Storage legen.
2. OpenClaw Gateway - gemäß OpenClaw CLI installieren, TLS am Reverse Proxy terminieren.
3. Bridge-Regel - Kanalereignis normalisieren und als strukturierten Run-Aufruf an den Graph übergeben.
4. systemd-Trennung - langgraph-api.service und openclaw.service separat mit Restart-Policy verwalten.

# /etc/systemd/system/langgraph-api.service
                [Unit]
                Description=LangGraph multi-agent API
                After=network-online.target

                [Service]
                User=deploy
                WorkingDirectory=/opt/langgraph-app
                Environment=CHECKPOINT_DIR=/var/lib/langgraph-checkpoints
                ExecStart=/opt/langgraph-app/.venv/bin/uvicorn main:app --host 127.0.0.1 --port 8123
                Restart=on-failure
                RestartSec=5

                [Install]
                WantedBy=multi-user.target

Nach dem Aktivieren der Units prüfen Sie mit ss -lntp, dass öffentlich nur 443 exponiert ist. Der Graph-Endpunkt gehört nicht ins Internet. Diese einfache Netzwerkhygiene verhindert eine ganze Klasse von Vorfällen und erleichtert spätere Audits deutlich.

Handoff-Vertrag: Welche Daten vom Gateway in den Graph?

Der häufigste Fehler in geteilten Architekturen ist ein unscharfer Übergabevertrag. Definieren Sie ein stabiles JSON-Schema:

• thread_id - stabiler Sitzungsanker zwischen Kanalthread und Graph-Statuslinie.
• intent - klarer Enum (new_task, approve, cancel, status) statt freier Interpretation.
• payload - strukturierte Aufgabenparameter, große Attachments als Objekt-Referenz.
• caller_scope - Kanal-/Benutzerkontext für zusätzliche Autorisierung im Graph.

LangGraphs Memory- und checkpoint-Modell ist für langlebige Workflows gebaut. Gateway sollte möglichst zustandsarm bleiben. Wenn beide Seiten eigene Sitzungslogik pflegen, entstehen Split-Brain-Zustände, die im Betrieb nur schwer nachvollziehbar sind.

L0-L3-Diagnose: erst Schicht, dann Fix

Bei "Bot antwortet nicht" nicht gleichzeitig alles ändern, sondern systematisch schichten:

L0: systemd und Ports

systemctl status openclaw langgraph-api prüfen, Socket-Status verifizieren. Ein ausgefallener Graph wirkt oft wie Kanalproblem, ist aber Upstream-Ausfall.

L1: OpenClaw-Kanal und Bridge-Logs

openclaw logs für Webhook-Eingang, Signaturprüfung und Ziel-URL nutzen. TLS/403/Retry gehören zuerst hierhin.

L2: LangGraph-Trace und checkpoint

Mit derselben thread_id den letzten stabilen Knoten und den Statuspfad prüfen. Falsche Berechtigungen oder Mounts führen häufig zu "jedes Mal neue Session".

L3: Externe Worker und MCP

Bei ausgelagerten Workern Netzwerk, NO_PROXY, Token-Ablauf und Host-Limits prüfen. Nicht vorschnell Gateway neu installieren, wenn die Ausführungsebene blockiert.

Go-live-Checkliste (30 Minuten)

• LangGraph nur intern binden, extern ausschließlich Gateway.
• checkpoint auf persistentes, gesichertes Storage legen.
• Gateway->Graph-Timeout unter Retry-Fenster des Kanals setzen.
• Tool-Rechte pro Knoten explizit begrenzen; Reviewer ohne Schreibrechte.
• Reboot-Test durchführen: interrupt muss sauber resume-fähig sein.
• Ein durchgehendes Trace-ID-Konzept vom Ingress bis Worker-Log etablieren.

FAQ