acp

Startet die Agent Client Protocol (ACP)-Bridge, die mit einem OpenClaw Gateway kommuniziert.

Dieser Befehl spricht ACP \u00fcber stdio f\u00fcr IDEs und leitet Prompts per WebSocket an das Gateway weiter. Er h\u00e4lt ACP-Sessions den Gateway-Session-Keys zugeordnet.

openclaw acp ist eine Gateway-gest\u00fctzte ACP-Bridge, keine vollst\u00e4ndige ACP-native Editor-Runtime. Der Fokus liegt auf Session-Routing, Prompt-\u00dcbermittlung und einfachem Streaming von Updates.

Kompatibilit\u00e4tsmatrix

Bekannte Einschr\u00e4nkungen

• loadSession spielt gespeicherte User- und Assistenten-Texthistorie ab, rekonstruiert aber keine historischen Tool-Calls, System-Hinweise oder reichhaltigere ACP-native Event-Typen.
• Wenn mehrere ACP-Clients denselben Gateway-Session-Key teilen, sind Event- und Cancel-Routing bestm\u00f6glich statt strikt pro Client isoliert. Verwende die standardm\u00e4\u00dfigen isolierten acp:<uuid>-Sessions, wenn du saubere editor-lokale Turns brauchst.
• Gateway-Stop-States werden in ACP-Stop-Reasons \u00fcbersetzt, aber dieses Mapping ist weniger ausdrucksstark als eine vollst\u00e4ndig ACP-native Runtime.
• Initiale Session-Controls decken aktuell einen fokussierten Teil der Gateway-Einstellungen ab: Thought-Level, Tool-Verbosity, Reasoning, Usage-Detail und erh\u00f6hte Aktionen. Modellauswahl und Exec-Host-Controls werden noch nicht als ACP-Konfigurationsoptionen angeboten.
• session_info_update und usage_update werden aus Gateway-Session-Snapshots abgeleitet, nicht aus Live-ACP-native-Runtime-Accounting. Usage ist n\u00e4herungsweise, enth\u00e4lt keine Kostendaten und wird nur gesendet, wenn das Gateway die Token-Gesamtdaten als aktuell markiert.
• Tool-Follow-Along-Daten sind bestm\u00f6glich. Die Bridge kann Dateipfade anzeigen, die in bekannten Tool-Args/Results erscheinen, gibt aber noch keine ACP-Terminals oder strukturierten Datei-Diffs aus.

Verwendung

openclaw acp

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

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

# An eine bestehende Session anh\u00e4ngen
openclaw acp --session agent:main:main

# \u00dcber Label anh\u00e4ngen (muss bereits existieren)
openclaw acp --session-label "support inbox"

# Session-Key vor dem ersten Prompt zur\u00fccksetzen
openclaw acp --session agent:main:main --reset-session

ACP-Client (Debug)

Mit dem eingebauten ACP-Client kannst du die Bridge ohne IDE testen. Er startet die ACP-Bridge und l\u00e4sst dich interaktiv Prompts eingeben.

openclaw acp client

# Die gestartete Bridge auf ein Remote Gateway zeigen
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Server-Befehl \u00fcberschreiben (Standard: 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\u00fcr vertrauensw\u00fcrdige Core-Tool-IDs.
• read-Auto-Approval ist auf das aktuelle Arbeitsverzeichnis beschr\u00e4nkt (--cwd falls gesetzt).
• Unbekannte/Nicht-Core-Tool-Namen, Reads au\u00dferhalb des Scopes und gef\u00e4hrliche Tools erfordern immer eine explizite Prompt-Best\u00e4tigung.
• Server-seitiger toolCall.kind wird als nicht vertrauensw\u00fcrdige Metadaten behandelt (keine Autorisierungsquelle).

So verwendest du das

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

1. Stelle sicher, dass das Gateway l\u00e4uft (lokal oder remote).
2. Konfiguriere das Gateway-Ziel (Konfig oder Flags).
3. Richte deine IDE so ein, dass sie openclaw acp \u00fcber stdio aufruft.

Beispielkonfiguration (persistent):

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

Beispiel Direktaufruf (ohne Config-Schreibvorgang):

openclaw acp --url wss://gateway-host:18789 --token <token>
# bevorzugt f\u00fcr lokale Prozesssicherheit
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

Agents ausw\u00e4hlen

ACP w\u00e4hlt Agents nicht direkt aus. Es routet \u00fcber den Gateway-Session-Key.

Verwende agent-bezogene Session-Keys, um einen bestimmten Agent anzusteuern:

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

Jede ACP-Session wird einem einzelnen Gateway-Session-Key zugeordnet. Ein Agent kann viele Sessions haben; ACP verwendet standardm\u00e4\u00dfig eine isolierte acp:<uuid>-Session, es sei denn, du \u00fcberschreibst den Key oder das Label.

Per-Session mcpServers werden im Bridge-Modus nicht unterst\u00fctzt. Wenn ein ACP-Client sie bei newSession oder loadSession sendet, gibt die Bridge einen klaren Fehler zur\u00fcck, anstatt sie stillschweigend zu ignorieren.

Nutzung \u00fcber acpx (Codex, Claude, andere ACP-Clients)

Wenn du einen Coding-Agent wie Codex oder Claude Code mit deinem OpenClaw-Bot \u00fcber ACP kommunizieren lassen willst, verwende acpx mit dem eingebauten openclaw-Target.

Typischer Ablauf:

1. Starte das Gateway und stelle sicher, dass die ACP-Bridge es erreichen kann.
2. Richte acpx openclaw auf openclaw acp.
3. W\u00e4hle den OpenClaw-Session-Key, den der Coding-Agent verwenden soll.

Beispiele:

# Einmal-Anfrage in deine Standard-OpenClaw-ACP-Session
acpx openclaw exec "Summarize the active OpenClaw session state."

# Persistente benannte Session f\u00fcr Folge-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."

Wenn acpx openclaw jedes Mal ein bestimmtes Gateway und einen Session-Key verwenden soll, \u00fcberschreibe den openclaw-Agent-Befehl in ~/.acpx/config.json:

{
  "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\u00fcr ein repo-lokales OpenClaw-Checkout verwende den direkten CLI-Einstiegspunkt statt des Dev-Runners, 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, Codex, Claude Code oder einen anderen ACP-f\u00e4higen Client kontextuelle Informationen von einem OpenClaw-Agent abrufen zu lassen, ohne ein Terminal zu scrapen.

Zed-Editor-Einrichtung

F\u00fcge einen benutzerdefinierten ACP-Agent in ~/.config/zed/settings.json hinzu (oder verwende die Zed-Einstellungs-UI):

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

Um ein bestimmtes Gateway oder einen Agent anzusteuern:

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

\u00d6ffne in Zed das Agent-Panel und w\u00e4hle “OpenClaw ACP”, um einen Thread zu starten.

Session-Mapping

Standardm\u00e4\u00dfig erhalten ACP-Sessions einen isolierten Gateway-Session-Key mit acp:-Pr\u00e4fix. Um eine bekannte Session wiederzuverwenden, gib einen Session-Key oder ein Label an:

• --session <key>: Einen bestimmten Gateway-Session-Key verwenden.
• --session-label <label>: Eine bestehende Session \u00fcber Label aufl\u00f6sen.
• --reset-session: Eine neue Session-ID f\u00fcr diesen Key erstellen (gleicher Key, neues Transkript).

Wenn dein ACP-Client Metadaten unterst\u00fctzt, kannst du pro Session \u00fcberschreiben:

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

Mehr \u00fcber 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>: Gateway-Auth-Token aus Datei lesen.
• --password <password>: Gateway-Auth-Passwort.
• --password-file <path>: Gateway-Auth-Passwort aus Datei lesen.
• --session <key>: Standard-Session-Key.
• --session-label <label>: Standard-Session-Label zum Aufl\u00f6sen.
• --require-existing: Fehlschlagen, wenn der Session-Key/das Label nicht existiert.
• --reset-session: Session-Key vor der ersten Nutzung zur\u00fccksetzen.
• --no-prefix-cwd: Prompts nicht mit dem Arbeitsverzeichnis pr\u00e4fixen.
• --verbose, -v: Ausf\u00fchrliches Logging nach stderr.

Sicherheitshinweis:

• --token und --password k\u00f6nnen auf manchen Systemen in lokalen Prozesslisten sichtbar sein.
• Bevorzuge --token-file/--password-file oder Umgebungsvariablen (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD).
• Die Gateway-Auth-Aufl\u00f6sung folgt dem gemeinsamen Vertrag anderer Gateway-Clients:
  • Lokaler Modus: env (OPENCLAW_GATEWAY_*) -> gateway.auth.* -> gateway.remote.*-Fallback nur wenn gateway.auth.* nicht gesetzt ist (konfigurierte aber nicht aufgel\u00f6ste lokale SecretRefs schlagen geschlossen fehl)
  • Remote-Modus: gateway.remote.* mit env/config-Fallback gem\u00e4\u00df Remote-Vorrangregeln
  • --url ist \u00fcberschreibungssicher und verwendet keine impliziten config/env-Anmeldeinformationen; \u00fcbergib explizit --token/--password (oder Datei-Varianten)
• ACP-Runtime-Backend-Kindprozesse erhalten OPENCLAW_SHELL=acp, was f\u00fcr kontextspezifische Shell/Profil-Regeln genutzt werden kann.
• openclaw acp client setzt OPENCLAW_SHELL=acp-client f\u00fcr den gestarteten Bridge-Prozess.

acp client-Optionen

• --cwd <dir>: Arbeitsverzeichnis f\u00fcr die ACP-Session.
• --server <command>: ACP-Server-Befehl (Standard: openclaw).
• --server-args <args...>: Zus\u00e4tzliche Argumente f\u00fcr den ACP-Server.
• --server-verbose: Ausf\u00fchrliches Logging f\u00fcr den ACP-Server aktivieren.
• --verbose, -v: Ausf\u00fchrliches Client-Logging.