OpenClaw ACP Bridge

Das hilfreiche Grundbild ist simpel: openclaw acp ist eine Brücke in OpenClaw hinein, keine kleine Editor-Runtime, die darin wohnt.

Stell es dir wie eine Vermittlungsstelle vor. Dein Editor oder ACP-Client ruft die Brücke an, die Brücke verbindet sich mit dem OpenClaw Gateway, und das Gateway routet die Arbeit in eine Session. Nützlich, direkt und deutlich weniger mystisch, als viele erwarten.

Laut der offiziellen OpenClaw ACP Doku spricht die Brücke ACP über stdio, leitet Prompts per WebSocket an das Gateway weiter und hält ACP-Sessions auf Gateway-Session-Keys abgebildet. Die offizielle MCP Doku beschreibt noch einmal eine andere Fläche. Genau diese Trennung ist hier der Kern.

Was die ACP-Brücke wirklich ist

Im Bridge-Modus agiert OpenClaw als ACP-Server. Ein IDE oder ein anderer ACP-fähiger Client verbindet sich mit openclaw acp. OpenClaw leitet diese Arbeit dann in eine Gateway-Session weiter.

Das heißt: Die Brücke ist vor allem für Session-Routing, Prompt-Weitergabe und grundlegende Streaming-Updates da. Sie versucht nicht, jede editor-native ACP-Funktion nachzubauen. Die Doku sagt das ziemlich klar, was angenehm ehrlich ist.

# lokales Gateway
openclaw acp

# Remote-Gateway
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# an eine bestimmte Session binden
openclaw acp --session agent:main:main

Die drei Flächen, die ständig verwechselt werden

Wenn du dir nur eine Sache merkst, dann die Richtung. ACP-Bridge heißt: Der Client spricht nach innen zu OpenClaw. ACP-Harness-Modus heißt: OpenClaw spricht nach außen zu einer anderen Runtime. MCP serve ist noch einmal ein anderes Protokoll mit einem anderen Betriebsmodell.

ACP-Brücke vs. ACP-Harness-Sessions

Genau hier beginnen die meisten falschen Setups. Die Wörter sehen ähnlich aus, also nehmen viele ähnliches Verhalten an. Das stimmt nicht.

Bei der Brücke fragt dein Editor OpenClaw nach einer ACP-Session-Fläche. Bei ACP-Agents startet OpenClaw selbst ein externes Harness über das ACP-Backend-Plugin, meist acpx. Dieses Harness bringt seine eigene Provider-Auth, seinen Modellkatalog, sein Dateisystemverhalten und seine nativen Tools mit.

• Bridge-Modus: sinnvoll, wenn ein ACP-fähiger Editor einen OpenClaw-Agenten nutzen soll
• Harness-Modus: sinnvoll, wenn OpenClaw Claude Code, Gemini CLI, explizites Codex ACP oder eine andere externe Coding-Runtime starten soll
• Sub-Agenten: sinnvoll, wenn du OpenClaw-native Delegation ohne externe Harness-Runtime willst

Noch ein praktischer Unterschied: Die Doku warnt ausdrücklich davor, ACP als Standardweg für Codex zu sehen. Wenn natives Codex-Binding verfügbar ist und genau das dein Ziel ist, ist ACP nicht automatisch die beste Wahl.

ACP-Brücke vs. openclaw mcp serve

Viele stellen hier die falsche Frage. Sie fragen: „Was ist besser?“ Die echte Frage lautet: „Welches Protokoll erwartet mein Client, und wer soll die Gesprächsfläche besitzen?“

Nutze openclaw acp, wenn der Client ACP spricht und eine ACP-Session-Struktur erwartet. Nutze openclaw mcp serve, wenn der Client MCP spricht und Gesprächswerkzeuge wie Transcript-Lesen, Event-Warten und Antworten über bestehende Channel-Routen braucht.

MCP serve ist kein austauschbarer ACP-Ersatz mit anderem Etikett. Die Doku beschreibt es als MCP-Server, der OpenClaw-gestützte Gespräche freigibt. Das ist ein anderer Vertrag.

Was im Bridge-Modus heute schon gut funktioniert

Die Brücke ist schon heute nützlich. Die Doku listet Kernsupport für Session-Erstellung, Prompts, Abbruch, Session-Listen und Slash-Commands. Das deckt den Hauptpfad ab, den die meisten zuerst brauchen.

Dazu kommen einige teilweise unterstützte Flächen, die praktisch zählen, etwa loadSession, Bildanhänge, Session-Modi, Best-Effort-Usage-Updates und Tool-Streaming. Das reicht, damit es sich wie eine echte Brücke anfühlt und nicht wie Spielzeug.

Was die Brücke nicht verspricht

Das ist der Teil, den du lesen solltest, bevor du sie in einen Editor einbaust und später die falsche Schicht beschuldigst.

• loadSession ist teilweise unterstützt: Texthistorie kommt zurück, aber historische Tool-Calls und reichere Events werden nicht vollständig rekonstruiert
• Per-Session mcpServers sind nicht unterstützt: konfiguriere MCP stattdessen auf Gateway- oder Agent-Seite
• Client-Dateisystemmethoden sind nicht unterstützt: die Brücke ruft keine ACP-Client-Datei-APIs auf
• Client-Terminalmethoden sind nicht unterstützt: keine ACP-nativen Terminal-Erstellungen oder Terminal-IDs im Stream
• Thought- und Plan-Streaming sind nicht unterstützt: die Brücke fokussiert sich auf Ausgabetext und Tool-Status statt auf volle ACP-native Reasoning-UX
• Usage-Updates sind Best-Effort: sie kommen aus gecachten Gateway-Snapshots, nicht aus perfekter ACP-nativer Abrechnung

Das macht die Brücke nicht schlecht. Es heißt nur, dass du sie als Routing-Fläche mit klarer Support-Grenze behandeln solltest, nicht als universelle Editor-Nachbildung.

Die Berechtigungsgrenzen sind absichtlich verschieden

Hier liegt eine subtile Falle. Menschen sehen ACP im Bridge-Modus und im Harness-Modus und nehmen an, das Berechtigungsmodell sei gleich. Laut Doku ist es das nicht.

Die Bridge-Policy ist ein eigenes System. Im ACP-Client-Debug-Modus gibt es zum Beispiel enge Auto-Approval-Regeln für vertrauenswürdige Read-Only-Klassen, während mutierende Tools und interaktive Flows weiter explizite Freigaben brauchen. ACPX-Harness-Berechtigungen sind wieder etwas anderes. Das ist wichtig, weil die Brücke in Gateway-Policies hineinleitet, während Harness-Sessions eine echte externe Runtime mit eigenem Verhalten und eigenem Permission-Profil starten.

Kurz gesagt: dasselbe Kürzel, andere Vertrauensgrenze.

Wann ACP der richtige Weg für Coding-Agent-Arbeit ist

Nutze ACP-Harness-Sessions, wenn du ausdrücklich das externe Harness willst. Meist heißt das eines von drei Dingen:

• du willst, dass Claude Code, Gemini CLI, Cursor, OpenCode oder ein anderes unterstütztes ACP-Harness die Arbeit erledigt
• du willst ACP-spezifische Session-Kontrollen, Bindings oder Thread-Verhalten
• du willst, dass OpenClaw eine externe Coding-Runtime orchestriert, statt den Run nativ zu erledigen

Wenn nichts davon zutrifft, zwing ACP nicht unnötig in die Architektur, nur weil es fortgeschritten klingt. Native Sub-Agenten sind sauberer für OpenClaw-native Delegation, und natives Codex bleibt laut Doku der Standardweg, wenn das Plugin aktiv ist und du in Wahrheit Codex-Binding willst.

# explizite ACP-Harness-Arbeit aus dem Chat
/acp spawn claude --bind here

# ACP-Harness-Arbeit aus Tools
sessions_spawn({
  runtime: "acp",
  agentId: "gemini",
  mode: "session",
  thread: true,
})

Eine einfache Entscheidungsregel

• Dein Editor will ACP in OpenClaw hinein → nutze openclaw acp
• OpenClaw soll ein externes Harness ausführen → nutze ACP-Agents oder runtime: "acp"
• Dein externer Client will MCP-Gespräche → nutze openclaw mcp serve

Diese kleine Regel spart erstaunlich viel Verwirrung.

Die Kurzfassung

Die ACP-Brücke ist eine Steuerfläche, keine komplette Editor-Runtime. Sie gibt ACP-fähigen Clients einen sauberen Weg in Gateway-Sessions. ACP-Harness-Sessions machen das Gegenteil: Sie lassen OpenClaw eine externe Coding-Runtime starten. MCP serve ist wieder eine eigene Sache.

Sobald du diese drei Wege nicht mehr wie Synonyme behandelst, werden die Setup-Entscheidungen deutlich ruhiger.