OpenClaw-Claude-Code: Headless-Coding-Engine als Plugin

Coding-CLIs wie Claude Code oder Codex sind mächtige Werkzeuge, stoßen aber an ihre Grenzen, wenn sie nicht von Menschen, sondern von KI-Agenten gesteuert werden sollen. Wer automatisierte Workflows mit persistenten Sessions, koordinierten Agenten-Teams und dynamischen Modellwechseln aufbauen will, benötigt eine programmierbare Schnittstelle. Genau hier setzt OpenClaw-Claude-Code an: Das Plugin verwandelt interaktive CLIs in eine programmierbare „headless“ Coding-Engine für komplexe Agenten-Systeme.

Claude Code ist beispielsweise für interaktives Coding entwickelt, Codex für generatives Wissen. In Agent-Umgebungen bleibt oft die visuelle CLI-Presenz nutzlos. OpenClaw-Claude-Code umgeht dies durch das Dekorieren von Claude Code CLI als Headless-Engine. Das erlaubt Agenten, über standardisierte APIs Aufgaben zu übermitteln, Chat-History zu verwalten, Streaming-Responses zu kontrollieren und Sessions mit dynamischen Timeout-Strategien zu betreiben. Das System unterstützt auf dieser Basis das Orchestrieren von Multi-Engine-Workflows, Multi-Agent-Councils und dynamischem Runtime-Scaling.

Das Plugin steht als NPM-Paket @enderfga/openclaw-claude-code zur Verfügung und nutzt OpenClaws Plugin-Infrastruktur. Dadurch lassen sich Claude Code Sessions persistenzfähig in bestehende Agent-Systeme einspeisen. Codex wird jedoch primär über die Engine-Verschnittstelle integriert; der Schwerpunkt liegt auf Claude Code CLI als dynamischem Coding-Backend. Das Interface erlaubt Agenten, Sessions zu starten, Aufgaben zu senden und zu stoppen, während die interne Engine-Nutzung für Agenten transparent bleibt. Das System unterstützt OpenAI-kompatible Endpunkte, mit zusätzlichen Methoden .startSession() für persistente CLIs, .sendTask() für asynchrone Aufgabenübermittlung, .stopSession() für Session-Ende, .listSessions() für Abfrage aller laufenden Sessions. Zudem erlaubt die Engine dynamisches Modell-Scaling und Streaming-Proxy-Timeout-Optimierung. Version 2.9.0 hat die max_tokens-Validierung auf das Level gesteigert, dass Token-Limits nicht mehr zu Fehlern im Backend führen (Parameter ohne positive Werte werden mit 400 abgelehnt).

Kernfunktionen der Headless-Architektur

Persistente Sessions und Headless-Betrieb Die CLI wird vollständig über standardisierte APIs gesteuert. Dabei existiert für jede Session eine isolierte Umgebung mit eigenem Chat-History-Store und Status. Sessions können persistent über weite Zeitstrecken hinweg führen, etwa für langlaufende Monitoring-Rundläufe oder fortlaufende Abläufe, bei denen der Kontext zwischendurch aktiv genutzt oder zurückgesetzt werden muss. Agenten können Aufgaben übermitteln und den Kontext dynamisch verändern, ohne die gesamte Umgebung neu initialisieren zu müssen. Das vereinfacht das Orchestrieren komplexer Flows: etwa das Beginnen eines Codings, mehrere Iterationen mit zwischenzeitlichen Agent-Entscheidungen, und schlussendliches Beenden. Die Persistenz macht das System auch anwendbar für wiederholbare Audit-Workflows (Replay, Audit, Wiederholung ohne manuellen Replay).

Dynamische Orchestrierung und Multi-Agenten-Teams Das System beschränkt sich nicht auf ein einzelnes Modell. Agenten können zur Laufzeit zwischen verschiedenen Engines wechseln – beispielsweise von einem niedriger-latenten Modell für einfache Analysen zu einem höherqualitativen Modell für komplexes Refactoring. Dabei ist der Switch vollständig agentenseitig gesteuert; OpenClaw kümmert sich um die interne Umschaltung der Engine-Dienste. Zudem lassen sich sogenannte Councils bilden: Teams aus spezialisierten Agenten, die gemeinsam an einem Code-Prozess arbeiten. So kann ein Aggregator Aufgaben verteilen, während ein Prozessor den Code schreibt und eine Feedback-Routine die Ergebnisse bewertet. Die Council-Orchestrierung ist vollständig dynamisch: Agenten können Teams neu zusammensetzen, Aufgaben übergeben und Feedback generieren, während die Engine den generierten Code an den weiterlaufenden Prozess weitergibt. Das erlaubt komplexe Multi-Agent-Aufgaben, etwa „Analyse — Refaktorisierung — Testen — Deployment“ in einer einzigen Session.

Laufzeitkontrolle und Stabilität Im Headless-Modus greifen Agenten aktiv in die Session ein. Sie steuern die Streaming-Ausgabe, passen Timeouts dynamisch an und reagieren auf Fehler, indem sie beispielsweise selbstständig die Engine wechseln. Die Runtime-Kontrolle erlaubt Agenten, Echtzeit-Eingriffe: etwa das Stoppen einer Streaming-Antwort, wenn die Latenz zu hoch ist, oder das Erniedrigen des Timeouts bei wiederholten Fehlern. Das macht sich die Programmierbarkeit der Headless-Engine zunutze und lässt das System sicheres Aushalten komplexer Flows ermöglichen.

Laut den Entwicklern wurden mit der Version 2.9.0 zudem umfangreiche Code-Quality-Audits umgesetzt. Das Release behebt unter anderem Race Conditions bei der Session-Erstellung (concurrent startSession() Calls werden dedupliziert), optimiert die Timeout-Logik (Streaming-Proxy nutzt fetchWithRetry statt bare fetch), validiert Token-Limits für OpenAI-kompatible Endpunkte (non-positive max_tokens werden mit 400 abgelehnt), ignorierte Fehler im catch-Block von PersistentClaudeSession (7 swallowed errors werden jetzt via SESSION_EVENT.LOG protokolliert), Hook-Fehler loggen statt stillschweigend zu schlucken, und entfernt unsichere Type-Casts (Double-Casts as unknown werden durch validierte typed fields ersetzt). Die Release-Bemerkung erwähnt zudem: „This completes all findings from the v2.9.0 code quality audit. No remaining known issues.“

Das unter MIT-Lizenz stehende Projekt lässt sich damit flexibel und stabil in eigene Agenten-Systeme integrieren. Aufgrund der offenen Architektur können Entwickler benutzerdefinierte Middleware für Logging, Monitoring oder Compliance hinzufügen.

Implementierung und Internes Design

OpenClaw-Claude-Code nutzt eine Plugin-Architektur innerhalb der OpenClaw-Umgebung. Unter der Haube wird die Claude Code CLI als Headless-Engine dekoriiert: Anstatt direkter CLI-Aufrufe werden API-Calls in eine Wrapper-Klasse verpackt, die Zustandsverwaltung und Streaming-Handling übernimmt. Die Engine-Integration erlaubt das Wechseln zwischen verschiedenen OpenAI-kompatiblen Modellen sowie das Anpassen von Timeout-Werten und Streaming-Settings. Sessions werden persistent gespeichert und über .listSessions() abfragbar, was das Wiederholen und Auditieren von Workflows ermöglicht. Versions 2.9.0 hat sämtliche Code Quality Audits erfolgreich abgeschlossen, inklusive Race Condition Fixes, Timeout-Optimierung, max_tokens-Validierung, Fehlerbehandlung (swallowed errors, hook errors, type casts) und Logging-Verbesserungen.

Bei der Integration ist darauf zu achten, dass Sessions von Agenten korrekt startet, Aufgaben zugewiesen und Sessions beendet werden, um keine Ressourcenlecks zu verursachen. Die API bietet Methoden .startSession(), .sendTask(), .stopSession(), .listSessions() sowie .setModel() für dynamisches Modell-Scaling. Das Plugin läuft nicht nur lokal, sondern kann auch in Cloud-basierten OpenClaw-Instanzen deployt werden, solange die Engine-Endpunkte erreichbar sind.

Einordnung: Autonome Workflows in der Praxis

Wie das Zusammenspiel funktioniert, zeigt ein typisches DevOps-Szenario: Ein Infrastruktur-Monitor meldet periodische Fehler an einen Agenten. Dieser startet eine persistente Session mit der Headless-Engine. Zunächst wählt der Agent ein niedriger-latentes Modell für die Fehleranalyse-Skript-Erstellung.

Anschließend übernimmt das Multi-Agenten-Council: Ein Aggregator wertet die Fehlermeldungen aus, ein Refactoring-Agent optimiert den Code und ein Test-Agent verifiziert die Lösung. Steigt die Komplexität der Aufgabe, wechselt das System dynamisch auf ein höherqualitatives Modell. Sobald die Tests erfolgreich durchlaufen, wird die Lösung an die Infrastruktur übergeben und die Session beendet. Solche Prozesse laufen über Stunden hinweg völlig autonom ab, ohne dass ein manueller Eingriff in die Kommandozeile nötig ist.