OpenClaw ACP Bridge: IDE-Anbindung in Minuten einrichten

Kompatibilitätsmatrix

ACP-Bereich	Status	Notizen
initialize, newSession, prompt, cancel	Implementiert	Core-Bridge-Flow über stdio zu Gateway Chat/Send + Abort.
listSessions, Slash-Commands	Implementiert	Session-Liste funktioniert mit dem Gateway-Session-Status; Befehle werden über available_commands_update angekündigt.
loadSession	Teilweise	Verbindet die ACP-Session erneut mit einem Gateway-Session-Key und spielt den gespeicherten Textverlauf von User und Assistant ab. Tool- oder System-Historie wird noch nicht rekonstruiert.
Prompt-Inhalt (text, eingebettete resource, Bilder)	Teilweise	Text und Resources werden in den Chat-Input eingebunden; Bilder werden zu Gateway-Anhängen.
Session-Modi	Teilweise	session/set_mode wird unterstützt. Die Bridge bietet erste Gateway-basierte Session-Controls für Thought-Level, Tool-Verbosity, Reasoning, Usage-Details und Elevated Actions. Weitergehende ACP-native Mode/Config-Oberflächen sind noch nicht enthalten.
Session-Info und Usage-Updates	Teilweise	Die Bridge sendet session_info_update und Best-Effort usage_update Benachrichtigungen aus Gateway-Session-Snapshots. Die Nutzung ist ein Schätzwert und wird nur gesendet, wenn die Token-Gesamtzahl im Gateway als aktuell markiert ist.
Tool-Streaming	Teilweise	tool_call / tool_call_update Events enthalten Raw I/O, Textinhalt, Best-Effort Dateipfade sowie zugehörige Argumente. Eingebettete Terminals und Rich-Diff-Outputs werden noch nicht unterstützt.
MCP-Server pro Session (mcpServers)	Nicht unterstützt	Der Bridge-Modus lehnt Anfragen für MCP-Server pro Session ab. Konfiguriere MCP stattdessen auf dem OpenClaw Gateway oder Agent.
Client-Dateisystem-Methoden (fs/read_text_file, fs/write_text_file)	Nicht unterstützt	Die Bridge ruft keine ACP-Client-Dateisystem-Methoden auf.
Client-Terminal-Methoden (terminal/*)	Nicht unterstützt	Die Bridge erstellt keine ACP-Client-Terminals und überträgt keine Terminal-IDs über Tool-Calls.
Session-Pläne / Thought-Streaming	Nicht unterstützt	Die Bridge gibt derzeit Output-Text und Tool-Status aus, aber keine ACP-Plan- oder Thought-Updates.

Bekannte Einschränkungen

• loadSession spielt den gespeicherten Textverlauf von User und Assistant ab, rekonstruiert aber keine historischen Tool-Calls, System-Benachrichtigungen, ACP-native Event-Typen sowie deren Metadaten.
• Wenn mehrere ACP

Nutzung

Hier erfährst du, wie du OpenClaw startest und konfigurierst. Am einfachsten geht es mit dem Standardbefehl, aber für Remote-Setups oder spezifische Sessions nutzt du einfach die passenden Flags.

openclaw acp

# Remote Gateway
openclaw acp --url wss://gateway-host:18789 --token <token>

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

# Attach to an existing session key
openclaw acp --session agent:main:main

# Attach by label (must already exist)
openclaw acp --session-label "support inbox"

# Reset the session key before the first prompt
openclaw acp --session agent:main:main --reset-session

ACP-Client (Debug)

Nutze den eingebauten ACP-Client, um die Bridge ohne eine IDE zu prüfen. Er startet die ACP-Bridge und du kannst Prompts direkt interaktiv eintippen. Das ist der beste Weg, um schnell zu checken, ob die Verbindung steht.

openclaw acp client

# Point the spawned bridge at a remote Gateway
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Override the server command (default: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

Berechtigungsmodell (Client-Debug-Modus):

• Auto-Approval basiert auf einer Allowlist und gilt nur für vertrauenswürdige Core-Tool-IDs.
• read Auto-Approval ist auf das aktuelle Arbeitsverzeichnis beschränkt (--cwd, falls gesetzt).
• ACP genehmigt nur einfache Read-Only-Klassen automatisch: Scoped read Aufrufe im aktiven Verzeichnis sowie Read-Only Such-Tools (search, web_search, memory_search). Unbekannte Tools, Zugriffe außerhalb des Verzeichnisses, Tools mit Exec-Rechten, Control-Plane-Tools oder schreibende Aktionen erfordern immer deine explizite Freigabe.
• Die vom Server bereitgestellte toolCall.kind wird als nicht vertrauenswürdige Metadaten behandelt und nicht als Autorisierungsquelle genutzt.
• Diese ACP-Bridge-Policy ist getrennt von den ACPX-Harness-Berechtigungen. Wenn du OpenClaw über das acpx Backend nutzt, ist plugins.entries.acpx.config.permissionMode=approve-all die Notlösung für diese Session.

AI Setup Assistant

Nächste Schritte

• Installation Guide
• Configuration Reference

So verwendest du es

Nutze ACP, wenn eine IDE (oder ein anderer Client) das Agent Client Protocol spricht und du damit eine OpenClaw Gateway Session steuern willst.

1. Stell sicher, dass das Gateway läuft (lokal oder remote).
2. Konfiguriere das Gateway-Ziel (über die Config oder Flags).
3. Verweise deine IDE darauf, openclaw acp über stdio auszuführen.

Beispiel-Konfiguration (persistent):

openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>

Beispiel für einen direkten Start (ohne die Config zu ändern):

openclaw acp --url wss://gateway-host:18789 --token <token>
# preferred for local process safety
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

Agents auswählen

ACP wählt Agents nicht direkt aus. Das Routing erfolgt über den Gateway Session Key.

Verwende am besten agent-scoped Session Keys, um einen spezifischen Agent anzusprechen:

openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123

Jede ACP Session wird genau einem Gateway Session Key zugeordnet. Ein Agent kann viele Sessions haben; ACP nutzt standardmäßig eine isolierte acp:<uuid> Session, außer du überschreibst den Key oder das Label.

Per-Session mcpServers werden im Bridge Mode nicht unterstützt. Wenn ein ACP Client diese während newSession oder loadSession sendet, gibt die Bridge einen deutlichen Fehler zurück, anstatt sie stillschweigend zu ignorieren.

Falls du möchtest, dass ACPX-basierte Sessions die OpenClaw Plugin Tools sehen, aktiviere die gateway-seitige ACPX Plugin Bridge, anstatt zu versuchen, mcpServers pro Session zu übergeben. Details dazu findest du unter ACP Agents.

Nutzung über acpx (Codex, Claude, andere ACP-Clients)

Wenn du möchtest, dass ein Coding-Agent wie Codex oder Claude Code über ACP mit deinem OpenClaw-Bot kommuniziert, verwende acpx mit dem integrierten openclaw Target.

Der typische Ablauf:

1. Starte das Gateway und stelle sicher, dass die ACP-Bridge es erreichen kann.
2. Verweise mit acpx openclaw auf openclaw acp.
3. Wähle den OpenClaw Session Key aus, den der Coding-Agent nutzen soll.

Beispiele:

# One-shot request into your default OpenClaw ACP session
acpx openclaw exec "Summarize the active OpenClaw session state."

# Persistent named session for follow-up turns
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
  "Ask my OpenClaw work agent for recent context relevant to this repo."

Falls acpx openclaw jedes Mal ein bestimmtes Gateway und einen Session Key ansteuern soll, kannst du den openclaw Agent-Befehl in der ~/.acpx/config.json überschreiben:

{
  "agents": {
    "openclaw": {
      "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"
    }
  }
}

Für einen lokalen OpenClaw-Checkout im Repo solltest du den direkten CLI-Entrypoint anstelle des Dev-Runners verwenden, damit der ACP-Stream sauber bleibt. Zum Beispiel:

env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...

Das ist der einfachste Weg, um Codex, Claude Code oder andere ACP-fähige Clients Kontext-Informationen von einem OpenClaw-Agenten abrufen zu lassen, ohne ein Terminal auszulesen.

Zed Editor Einrichtung

Füge einen benutzerdefinierten ACP-Agenten in der ~/.config/zed/settings.json hinzu (oder nutze das Settings-UI von Zed):

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": ["acp"],
      "env": {}
    }
  }
}

Um ein bestimmtes Gateway oder einen Agenten anzusteuern:

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": [
        "acp",
        "--url",
        "wss://gateway-host:18789",
        "--token",
        "<token>",
        "--session",
        "agent:design:main"
      ],
      "env": {}
    }
  }
}

Öffne in Zed das Agent-Panel und wähle „OpenClaw ACP“, um einen Thread zu starten.

AI Setup Assistant

Session-Mapping

Standardmäßig erhalten ACP-Sessions einen isolierten Gateway-Session-Key mit dem Präfix acp:. Um eine bekannte Session wiederzuverwenden, übergibst du einen Session-Key oder ein Label:

• --session <key>: Nutze einen spezifischen Gateway-Session-Key.
• --session-label <label>: Löse eine bestehende Session über ein Label auf.
• --reset-session: Erzeuge eine frische Session-ID für diesen Key (gleicher Key, neues Transcript).

Wenn dein ACP-Client Metadaten unterstützt, kannst du dies pro Session überschreiben:

{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  }
}

Erfahre mehr über Session-Keys unter /concepts/session.

Optionen

• --url <url>: Gateway WebSocket URL (Standard ist gateway.remote.url, falls konfiguriert).
• --token <token>: Gateway Auth-Token.
• --token-file <path>: Liest das Gateway Auth-Token aus einer Datei.
• --password <password>: Gateway Auth-Passwort.
• --password-file <path>: Liest das Gateway Auth-Passwort aus einer Datei.
• --session <key>: Standard Session-Key.
• --session-label <label>: Standard Session-Label zum Auflösen.
• --require-existing: Schlägt fehl, wenn der Session-Key oder das Label nicht existiert.
• --reset-session: Setzt den Session-Key vor der ersten Nutzung zurück.
• --no-prefix-cwd: Verhindert, dass Prompts das Arbeitsverzeichnis als Präfix voranstellen.
• --verbose, -v: Ausführliches Logging nach stderr.

Sicherheitshinweis:

• --token und --password können auf manchen Systemen in lokalen Prozesslisten sichtbar sein.
• Nutze bevorzugt --token-file/--password-file oder Umgebungsvariablen (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD).
• Die Gateway-Auth-Auflösung folgt dem geteilten Contract anderer Gateway-Clients:
  • Local Mode: env (OPENCLAW_GATEWAY_*) -> gateway.auth.* -> gateway.remote.* Fallback nur, wenn gateway.auth.* nicht gesetzt ist (konfigurierte, aber nicht aufgelöste lokale SecretRefs schlagen fehl).
  • Remote Mode: gateway.remote.* mit env/config Fallback gemäß den Remote-Prioritätsregeln.
  • --url ist sicher vor Überschreibungen und nutzt keine impliziten Config/Env-Credentials; übergib explizit --token/--password (oder Datei-Varianten).
• ACP-Runtime-Backend-Kindprozesse erhalten OPENCLAW_SHELL=acp, was für kontextspezifische Shell- oder Profil-Regeln genutzt werden kann.
• openclaw acp client setzt OPENCLAW_SHELL=acp-client für den gestarteten Bridge-Prozess.

acp client Optionen

• --cwd <dir>: Arbeitsverzeichnis für die ACP-Session.
• --server <command>: ACP-Server-Befehl (Standard: openclaw).
• --server-args <args...>: Zusätzliche Argumente für den ACP-Server.
• --server-verbose: Aktiviert ausführliches Logging auf dem ACP-Server.
• --verbose, -v: Ausführliches Client-Logging.