ACP

​

Was dies nicht ist

• Editor/Client soll über ACP mit OpenClaw kommunizieren: Verwenden Sie openclaw acp
• OpenClaw soll Codex/Claude/Gemini als ACP-Harness starten: Verwenden Sie /acp spawn und ACP-Agenten

​

Kompatibilitätsmatrix

​

Bekannte Einschränkungen

• loadSession gibt den vollständigen ACP-Ereignisjournalverlauf nur für von der Bridge erstellte Sitzungen wieder. Ältere Sitzungen bzw. Sitzungen ohne Journal verwenden den Transkript-Fallback und rekonstruieren keine historischen Werkzeugaufrufe oder Systemhinweise.
• Wenn mehrere ACP-Clients denselben Gateway-Sitzungsschlüssel gemeinsam verwenden, erfolgen Ereignis- und Abbruchrouting nach bestem Bemühen und sind nicht strikt pro Client isoliert. Bevorzugen Sie die standardmäßig isolierten acp-bridge:<uuid>-Sitzungen, wenn saubere editorlokale Durchläufe erforderlich sind.
• Gateway-Stoppzustände werden in ACP-Stoppgründe übersetzt, diese Zuordnung ist jedoch weniger ausdrucksstark als bei einer vollständig ACP-nativen Laufzeit.
• Sitzungssteuerungen stellen eine gezielte Teilmenge der Gateway-Optionen bereit: Denkstufe, Werkzeugausführlichkeit, Schlussfolgerung, Nutzungsdetails und privilegierte Aktionen. Modellauswahl und Steuerungen des Ausführungshosts werden nicht als ACP-Konfigurationsoptionen bereitgestellt.
• session_info_update und usage_update werden aus Gateway-Sitzungsmomentaufnahmen abgeleitet und nicht aus einer laufenden ACP-nativen Laufzeitabrechnung. Die Nutzung ist näherungsweise, enthält keine Kostendaten und wird nur ausgegeben, wenn das Gateway die Gesamttokendaten als aktuell markiert.
• Begleitdaten zu Werkzeugen werden nach bestem Bemühen bereitgestellt: Die Bridge gibt Dateipfade aus, die in bekannten Werkzeugargumenten/-ergebnissen vorkommen, gibt jedoch keine ACP-Terminals oder strukturierten Datei-Diffs aus.
• Die Weiterleitung von Ausführungsgenehmigungen ist auf den aktiven ACP-Prompt-Durchlauf beschränkt; Genehmigungen aus anderen Gateway-Sitzungen werden ignoriert.

​

Verwendung

openclaw acp

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

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

# Mit einem vorhandenen Sitzungsschlüssel verbinden
openclaw acp --session agent:main:main

# Anhand der Bezeichnung verbinden (muss bereits vorhanden sein)
openclaw acp --session-label "support inbox"

# Sitzungsschlüssel vor dem ersten Prompt zurücksetzen
openclaw acp --session agent:main:main --reset-session

​

ACP-Client (Debugging)

openclaw acp client

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

# Serverbefehl überschreiben (Standard: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

• Die automatische Genehmigung basiert auf einer Zulassungsliste und gilt nur für vertrauenswürdige zentrale Werkzeug-IDs.
• Die automatische Genehmigung von read ist auf das aktuelle Arbeitsverzeichnis beschränkt (--cwd, wenn festgelegt).
• ACP genehmigt nur eng begrenzte schreibgeschützte Klassen automatisch: begrenzte read-Aufrufe innerhalb des aktiven Arbeitsverzeichnisses sowie schreibgeschützte Suchwerkzeuge (search, web_search, memory_search). Unbekannte/nicht zentrale Werkzeuge, Lesezugriffe außerhalb des Geltungsbereichs, ausführungsfähige Werkzeuge, Steuerungsebenenwerkzeuge, verändernde Werkzeuge und interaktive Abläufe erfordern immer eine ausdrückliche Genehmigung nach Aufforderung.
• Das vom Server bereitgestellte toolCall.kind wird als nicht vertrauenswürdige Metadaten behandelt, nicht als Autorisierungsquelle.
• Diese ACP-Bridge-Richtlinie ist von ACPX-Harness-Berechtigungen getrennt. Wenn Sie OpenClaw über das acpx-Backend ausführen, ist plugins.entries.acpx.config.permissionMode=approve-all der „Yolo“-Notfallschalter für diese Harness-Sitzung.

​

Protokoll-Smoke-Test

{
  "initialize": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionCapabilities": {
        "list": {},
        "resume": {},
        "close": {}
      }
    }
  },
  "listSessions": {
    "sessions": [
      {
        "sessionId": "agent:main:acp-smoke",
        "cwd": "/path/to/workspace",
        "_meta": {
          "sessionKey": "agent:main:acp-smoke",
          "kind": "direct"
        }
      }
    ],
    "nextCursor": null
  },
  "notifications": ["session_info_update", "available_commands_update", "usage_update"],
  "gatewayLogTail": ["[gateway] bereit", "[ws] ⇄ res ✓ sessions.list 305ms"]
}

​

Verwendung

1. Stellen Sie sicher, dass das Gateway ausgeführt wird (lokal oder entfernt).
2. Konfigurieren Sie das Gateway-Ziel (Konfiguration oder Flags).
3. Konfigurieren Sie Ihre IDE so, dass sie openclaw acp über stdio ausführt.

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

openclaw acp --url wss://gateway-host:18789 --token <token>
# für die Sicherheit lokaler Prozesse bevorzugt
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

​

Agenten auswählen

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

​

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

1. Starten Sie das Gateway und stellen Sie sicher, dass die ACP-Bridge darauf zugreifen kann.
2. Richten Sie acpx openclaw auf openclaw acp aus.
3. Geben Sie den OpenClaw-Sitzungsschlüssel an, den der Coding-Agent verwenden soll.

# Einmalige Anfrage an Ihre standardmäßige OpenClaw-ACP-Sitzung
acpx openclaw exec "Fasse den Status der aktiven OpenClaw-Sitzung zusammen."

# Dauerhafte benannte Sitzung für weitere Nachrichten
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
  "Frage meinen OpenClaw-Arbeitsagenten nach aktuellem Kontext, der für dieses Repository relevant ist."

{
  "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"
    }
  }
}

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

​

Einrichtung des Zed-Editors

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

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

​

Sitzungszuordnung

• --session <key>: Einen bestimmten Gateway-Sitzungsschlüssel verwenden.
• --session-label <label>: Eine vorhandene Sitzung anhand ihrer Bezeichnung auflösen.
• --reset-session: Eine neue Sitzungs-ID für diesen Schlüssel erzeugen (gleicher Schlüssel, neues Transkript).

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

​

Optionen

• --url <url>: Gateway-WebSocket-URL (standardmäßig gateway.remote.url, wenn konfiguriert).
• --token <token>: Gateway-Authentifizierungstoken.
• --token-file <path>: Gateway-Authentifizierungstoken aus einer Datei lesen.
• --password <password>: Gateway-Authentifizierungspasswort.
• --password-file <path>: Gateway-Authentifizierungspasswort aus einer Datei lesen.
• --session <key>: Standardsitzungsschlüssel.
• --session-label <label>: Aufzulösende Standardsitzungsbezeichnung.
• --require-existing: Mit einem Fehler abbrechen, wenn der Sitzungsschlüssel oder die Sitzungsbezeichnung nicht vorhanden ist.
• --reset-session: Den Sitzungsschlüssel vor der ersten Verwendung zurücksetzen.
• --no-prefix-cwd: Prompts nicht das Arbeitsverzeichnis voranstellen.
• --provenance <off|meta|meta+receipt>: ACP-Herkunftsmetadaten oder Empfangsbestätigungen einschließen.
• --verbose, -v: Ausführliche Protokollierung nach stderr.

• --token und --password können auf einigen Systemen in lokalen Prozesslisten sichtbar sein. Verwenden Sie vorzugsweise --token-file/--password-file oder Umgebungsvariablen (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD).
• Die Auflösung der Gateway-Authentifizierung folgt dem gemeinsamen Vertrag, den auch andere Gateway-Clients verwenden:
  • Lokaler Modus: Umgebung (OPENCLAW_GATEWAY_*), dann gateway.auth.*; Rückgriff auf gateway.remote.* nur, wenn gateway.auth.* nicht gesetzt ist (eine konfigurierte, aber nicht auflösbare lokale SecretRef schlägt sicher fehl, statt stillschweigend auf eine Alternative zurückzugreifen)
  • Remote-Modus: gateway.remote.* mit Rückgriff auf Umgebung/Konfiguration gemäß den Remote-Prioritätsregeln
  • --url kann sicher überschrieben werden und verwendet keine impliziten Anmeldedaten aus Konfiguration oder Umgebung wieder; übergeben Sie explizit --token/--password (oder die Dateivarianten)

​

Optionen für acp client

• --cwd <dir>: Arbeitsverzeichnis für die ACP-Sitzung.
• --server <command>: ACP-Serverbefehl (Standard: openclaw).
• --server-args <args...>: Zusätzliche Argumente, die an den ACP-Server übergeben werden.
• --server-verbose: Ausführliche Protokollierung auf dem ACP-Server aktivieren.
• --verbose, -v: Ausführliche Client-Protokollierung.
• openclaw acp client setzt OPENCLAW_SHELL=acp-client für den gestarteten Bridge-Prozess; dies kann für kontextspezifische Shell-/Profilregeln verwendet werden.

​

Verwandte Themen

• CLI-Referenz
• ACP-Agenten