Naar hoofdinhoud gaan
Voer de Agent Client Protocol (ACP)-bridge uit die met een OpenClaw Gateway praat. Deze opdracht spreekt ACP via stdio voor IDE’s en stuurt prompts door naar de Gateway via WebSocket. Sessies van ACP blijven gekoppeld aan sessiesleutels van de Gateway. openclaw acp is een door de Gateway ondersteunde ACP-bridge, geen volledige ACP-native editor- runtime. De focus ligt op sessierouting, promptaflevering en eenvoudige streaming- updates. Als je wilt dat een externe MCP-client rechtstreeks met OpenClaw-kanaal- gesprekken praat in plaats van een ACP-harnessessie te hosten, gebruik dan openclaw mcp serve.

​
Wat dit niet is

Deze pagina wordt vaak verward met ACP-harnessessies. openclaw acp betekent:
  • OpenClaw fungeert als ACP-server
  • een IDE of ACP-client maakt verbinding met OpenClaw
  • OpenClaw stuurt dat werk door naar een Gateway-sessie
Dit verschilt van ACP Agents, waarbij OpenClaw een externe harness zoals Codex of Claude Code via acpx uitvoert. Snelle regel:
  • editor/client wil via ACP met OpenClaw praten: gebruik openclaw acp
  • OpenClaw moet Codex/Claude/Gemini starten als ACP-harness: gebruik /acp spawn en ACP Agents

​
Compatibiliteitsmatrix

ACP-gebiedStatusOpmerkingen
initialize, newSession, prompt, cancelGeïmplementeerdKernbridgeflow via stdio naar Gateway chat/send + abort.
listSessions, slashopdrachtenGeïmplementeerdSessielijst werkt op basis van Gateway-sessiestatus met begrensde cursorpaginering en cwd-filtering waar Gateway-sessierijen werkruimtemetadata bevatten; opdrachten worden aangekondigd via available_commands_update.
Metadata voor sessieafstammingGeïmplementeerdSessielijsten en snapshots met sessie-info bevatten OpenClaw-ouder- en kindafstamming in _meta, zodat ACP-clients subagentgrafen kunnen renderen zonder private Gateway-zijkanalen.
resumeSession, closeSessionGeïmplementeerdHervatten koppelt een ACP-sessie opnieuw aan een bestaande Gateway-sessie zonder geschiedenis opnieuw af te spelen. Sluiten annuleert actief bridgewerk, rondt wachtende prompts af als geannuleerd en geeft bridgesessiestatus vrij.
loadSessionGedeeltelijkKoppelt de ACP-sessie opnieuw aan een Gateway-sessiesleutel en speelt ACP-eventledgergeschiedenis opnieuw af voor door de bridge aangemaakte sessies. Oudere sessies of sessies zonder ledger vallen terug op opgeslagen gebruiker-/assistenttekst.
Promptinhoud (text, ingesloten resource, afbeeldingen)GedeeltelijkTekst/resources worden afgevlakt tot chatinvoer; afbeeldingen worden Gateway-bijlagen.
SessiemodiGedeeltelijksession/set_mode wordt ondersteund en de bridge stelt initiële door de Gateway ondersteunde sessiebedieningselementen beschikbaar voor denkniveau, tool-verbositeit, reasoning, gebruiksdetails en verhoogde acties. Bredere ACP-native modus-/configuratieoppervlakken vallen nog buiten scope.
Sessie-info en gebruiksupdatesGedeeltelijkDe bridge verzendt session_info_update- en best-effort usage_update-meldingen vanuit gecachete Gateway-sessiesnapshots. Gebruik is bij benadering en wordt alleen verzonden wanneer Gateway-tokentotalen als vers zijn gemarkeerd.
ToolstreamingGedeeltelijktool_call- / tool_call_update-events bevatten ruwe I/O, tekstinhoud en best-effort bestandslocaties wanneer Gateway-toolargumenten/resultaten die tonen. Ingesloten terminals en rijkere diff-native uitvoer worden nog niet blootgesteld.
Exec-goedkeuringenGedeeltelijkGateway-execgoedkeuringsprompts tijdens actieve ACP-promptbeurten worden doorgestuurd naar de ACP-client met session/request_permission.
MCP-servers per sessie (mcpServers)Niet ondersteundBridgemodus wijst MCP-serververzoeken per sessie af. Configureer MCP in plaats daarvan op de OpenClaw Gateway of agent.
Clientbestandssysteemmethoden (fs/read_text_file, fs/write_text_file)Niet ondersteundDe bridge roept geen ACP-clientbestandssysteemmethoden aan.
Clientterminalmethoden (terminal/*)Niet ondersteundDe bridge maakt geen ACP-clientterminals aan en streamt geen terminal-id’s via toolaanroepen.
Sessieplannen / thought-streamingNiet ondersteundDe bridge verzendt momenteel uitvoertekst en toolstatus, geen ACP-plan- of thought-updates.

​
Bekende beperkingen

  • loadSession kan volledige ACP-eventledgergeschiedenis alleen opnieuw afspelen voor door de bridge aangemaakte sessies. Oudere sessies of sessies zonder ledger gebruiken nog steeds transcript- fallback en reconstrueren geen historische toolaanroepen of systeemmeldingen.
  • Als meerdere ACP-clients dezelfde Gateway-sessiesleutel delen, zijn event- en annulerings- routing best-effort in plaats van strikt per client geïsoleerd. Geef de voorkeur aan de standaard geïsoleerde acp:<uuid>-sessies wanneer je schone editorlokale beurten nodig hebt.
  • Gateway-stopstatussen worden vertaald naar ACP-stopredenen, maar die mapping is minder expressief dan een volledig ACP-native runtime.
  • Initiële sessiebedieningselementen tonen momenteel een gerichte subset van Gateway-knoppen: denkniveau, tool-verbositeit, reasoning, gebruiksdetails en verhoogde acties. Modelselectie en exec-hostbediening zijn nog niet beschikbaar als ACP- configuratieopties.
  • session_info_update en usage_update worden afgeleid van Gateway-sessie- snapshots, niet van live ACP-native runtimeboekhouding. Gebruik is bij benadering, bevat geen kostengegevens en wordt alleen verzonden wanneer de Gateway totale token- gegevens als vers markeert.
  • Tool-meekijkgegevens zijn best-effort. De bridge kan bestandspaden tonen die voorkomen in bekende toolargumenten/resultaten, maar verzendt nog geen ACP-terminals of gestructureerde bestandsdiffs.
  • Exec-goedkeuringsrelay is beperkt tot de actieve ACP-promptbeurt; goedkeuringen van andere Gateway-sessies worden genegeerd.

​
Gebruik

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)

Gebruik de ingebouwde ACP-client om de bridge zonder IDE op gezondheid te controleren. Deze start de ACP-bridge en laat je interactief prompts typen. 
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
Machtigingsmodel (clientdebugmodus):
  • Automatische goedkeuring is gebaseerd op een allowlist en geldt alleen voor vertrouwde kern-tool-ID’s.
  • Automatische goedkeuring voor read is beperkt tot de huidige werkdirectory (--cwd wanneer ingesteld).
  • ACP keurt alleen nauwe readonly-klassen automatisch goed: scoped read-aanroepen onder de actieve cwd plus readonly-zoektools (search, web_search, memory_search). Onbekende/niet-kern-tools, reads buiten scope, tools met exec-mogelijkheden, control-plane-tools, muterende tools en interactieve flows vereisen altijd expliciete promptgoedkeuring.
  • Door de server geleverde toolCall.kind wordt behandeld als niet-vertrouwde metadata (niet als autorisatiebron).
  • Dit ACP-bridgebeleid staat los van ACPX-harnessmachtigingen. Als je OpenClaw via de acpx-backend uitvoert, is plugins.entries.acpx.config.permissionMode=approve-all de noodschakelaar “yolo” voor die harnessessie.

​
Protocol-smoketesten

Voor debugging op protocolniveau start je een Gateway met geïsoleerde status en stuur je openclaw acp via stdio aan met een ACP JSON-RPC-client. Dek initialize, session/new, session/list met een absolute cwd, session/resume, session/close, dubbel sluiten en ontbrekend hervatten af. Het bewijs moet de geadverteerde lifecyclemogelijkheden, een door de Gateway ondersteunde sessierij, updatemeldingen en het Gateway-sessions.list-log bevatten: 
{
  "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] ready", "[ws] ⇄ res ✓ sessions.list 305ms"]
}
Vermijd openclaw gateway call sessions.list als enig ACP-bewijs. Dat CLI-pad kan een operator-scope-upgrade voor verse tokens aanvragen; correctheid van de ACP-bridge wordt bewezen met ACP-stdioframes plus het Gateway-sessions.list-log.

​
Hoe je dit gebruikt

Gebruik ACP wanneer een IDE (of andere client) Agent Client Protocol spreekt en je wilt dat deze een OpenClaw Gateway-sessie aanstuurt.
  1. Zorg dat de Gateway draait (lokaal of remote).
  2. Configureer het Gateway-doel (configuratie of flags).
  3. Laat je IDE openclaw acp via stdio uitvoeren.
Voorbeeldconfiguratie (blijvend opgeslagen): 
openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>
Voorbeeld van direct uitvoeren (zonder configuratie weg te schrijven): 
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 selecteren

ACP kiest agents niet rechtstreeks. Het routeert op basis van de Gateway-sessiesleutel. Gebruik agent-scoped sessiesleutels om een specifieke agent te targeten: 
openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123
Elke ACP-sessie wordt gekoppeld aan een enkele Gateway-sessiesleutel. Een agent kan veel sessies hebben; ACP gebruikt standaard een geisoleerde acp:<uuid>-sessie, tenzij je de sleutel of het label overschrijft. Per-sessie mcpServers worden niet ondersteund in bridgemodus. Als een ACP-client ze tijdens newSession of loadSession verzendt, retourneert de bridge een duidelijke fout in plaats van ze stilzwijgend te negeren. Als je wilt dat door ACPX ondersteunde sessies OpenClaw Plugin-tools of geselecteerde ingebouwde tools zoals cron zien, schakel dan de ACPX MCP-bridges aan de Gateway-kant in in plaats van te proberen per-sessie mcpServers door te geven. Zie ACP-agenten en OpenClaw-tools-MCP-bridge.

​
Gebruik vanuit acpx (Codex, Claude, andere ACP-clients)

Als je wilt dat een codeeragent zoals Codex of Claude Code via ACP met je OpenClaw-bot praat, gebruik dan acpx met het ingebouwde openclaw-doel. Typische flow:
  1. Start de Gateway en zorg dat de ACP-bridge deze kan bereiken.
  2. Richt acpx openclaw op openclaw acp.
  3. Richt je op de OpenClaw-sessiesleutel die je de codeeragent wilt laten gebruiken.
Voorbeelden: 
# 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."
Als je wilt dat acpx openclaw elke keer op een specifieke Gateway en sessiesleutel is gericht, overschrijf dan de openclaw-agentopdracht 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"
    }
  }
}
Gebruik voor een repo-lokale OpenClaw-checkout het directe CLI-entrypoint in plaats van de dev-runner, zodat de ACP-stream schoon blijft. Bijvoorbeeld: 
env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
Dit is de eenvoudigste manier om Codex, Claude Code of een andere ACP-bewuste client contextuele informatie uit een OpenClaw-agent te laten halen zonder een terminal te scrapen.

​
Zed-editor instellen

Voeg een aangepaste ACP-agent toe in ~/.config/zed/settings.json (of gebruik de instellingen-UI van Zed): 
{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": ["acp"],
      "env": {}
    }
  }
}
Om een specifieke Gateway of agent te richten: 
{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": [
        "acp",
        "--url",
        "wss://gateway-host:18789",
        "--token",
        "<token>",
        "--session",
        "agent:design:main"
      ],
      "env": {}
    }
  }
}
Open in Zed het Agent-paneel en selecteer “OpenClaw ACP” om een thread te starten.

​
Sessietoewijzing

Standaard krijgen ACP-sessies een geisoleerde Gateway-sessiesleutel met een acp:-voorvoegsel. Geef een sessiesleutel of label door om een bekende sessie opnieuw te gebruiken:
  • --session <key>: gebruik een specifieke Gateway-sessiesleutel.
  • --session-label <label>: los een bestaande sessie op via label.
  • --reset-session: maak een nieuwe sessie-id voor die sleutel aan (dezelfde sleutel, nieuw transcript).
Als je ACP-client metadata ondersteunt, kun je per sessie overschrijven: 
{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  }
}
Lees meer over sessiesleutels op /concepts/session.

​
Opties

  • --url <url>: Gateway WebSocket-URL (standaard gateway.remote.url wanneer geconfigureerd).
  • --token <token>: Gateway-authenticatietoken.
  • --token-file <path>: lees Gateway-authenticatietoken uit bestand.
  • --password <password>: Gateway-authenticatiewachtwoord.
  • --password-file <path>: lees Gateway-authenticatiewachtwoord uit bestand.
  • --session <key>: standaardsessiesleutel.
  • --session-label <label>: standaardsessielabel om op te lossen.
  • --require-existing: faal als de sessiesleutel/het label niet bestaat.
  • --reset-session: reset de sessiesleutel voor het eerste gebruik.
  • --no-prefix-cwd: voeg de werkdirectory niet als voorvoegsel toe aan prompts.
  • --provenance <off|meta|meta+receipt>: neem ACP-herkomstmetadata of ontvangstbewijzen op.
  • --verbose, -v: uitgebreide logging naar stderr.
Beveiligingsopmerking:
  • --token en --password kunnen op sommige systemen zichtbaar zijn in lokale proceslijsten.
  • Geef de voorkeur aan --token-file/--password-file of omgevingsvariabelen (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD).
  • Gateway-authenticatieresolutie volgt het gedeelde contract dat door andere Gateway-clients wordt gebruikt:
    • lokale modus: env (OPENCLAW_GATEWAY_*) -> gateway.auth.* -> gateway.remote.*-fallback alleen wanneer gateway.auth.* niet is ingesteld (geconfigureerde maar niet-opgeloste lokale SecretRefs falen gesloten)
    • externe modus: gateway.remote.* met env/config-fallback volgens de externe prioriteitsregels
    • --url is overschrijfveilig en hergebruikt geen impliciete config/env-credentials; geef expliciet --token/--password (of bestandsvarianten) door
  • ACP-runtimebackend-childprocessen ontvangen OPENCLAW_SHELL=acp, wat kan worden gebruikt voor contextspecifieke shell-/profielregels.
  • openclaw acp client stelt OPENCLAW_SHELL=acp-client in op het gestarte bridgeproces.

​
Opties voor acp client

  • --cwd <dir>: werkdirectory voor de ACP-sessie.
  • --server <command>: ACP-serveropdracht (standaard: openclaw).
  • --server-args <args...>: extra argumenten die aan de ACP-server worden doorgegeven.
  • --server-verbose: schakel uitgebreide logging op de ACP-server in.
  • --verbose, -v: uitgebreide clientlogging.

​
Gerelateerd