ACP

Voer de Agent Client Protocol (ACP)-bridge uit die met een OmeniaClaw 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.

OmeniaClaw 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 OmeniaClaw-kanaal- gesprekken praat in plaats van een ACP-harnessessie te hosten, gebruik dan OmeniaClaw mcp serve.

Wat dit niet is

Deze pagina wordt vaak verward met ACP-harnessessies.

OmeniaClaw acp betekent:

• OmeniaClaw fungeert als ACP-server
• een IDE of ACP-client maakt verbinding met OmeniaClaw
• OmeniaClaw stuurt dat werk door naar een Gateway-sessie

Dit verschilt van ACP Agents, waarbij OmeniaClaw een externe harness zoals Codex of Claude Code via acpx uitvoert.

Snelle regel:

• editor/client wil via ACP met OmeniaClaw praten: gebruik OmeniaClaw acp
• OmeniaClaw moet Codex/Claude/Gemini starten als ACP-harness: gebruik /acp spawn en ACP Agents

Compatibiliteitsmatrix

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

OmeniaClaw acp # Remote GatewayOmeniaClaw acp --url wss://gateway-host:18789 --token <token> # Remote Gateway (token from file)OmeniaClaw acp --url wss://gateway-host:18789 --token-file ~/.OmeniaClaw/gateway.token # Attach to an existing session keyOmeniaClaw acp --session agent:main:main # Attach by label (must already exist)OmeniaClaw acp --session-label "support inbox" # Reset the session key before the first promptOmeniaClaw 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.

OmeniaClaw acp client # Point the spawned bridge at a remote GatewayOmeniaClaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.OmeniaClaw/gateway.token # Override the server command (default: OmeniaClaw)OmeniaClaw acp client --server "node" --server-args OmeniaClaw.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 OmeniaClaw 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 OmeniaClaw 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 OmeniaClaw 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 OmeniaClaw Gateway-sessie aanstuurt.

1. Zorg dat de Gateway draait (lokaal of remote).
2. Configureer het Gateway-doel (configuratie of flags).
3. Laat je IDE OmeniaClaw acp via stdio uitvoeren.

Voorbeeldconfiguratie (blijvend opgeslagen):

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

Voorbeeld van direct uitvoeren (zonder configuratie weg te schrijven):

OmeniaClaw acp --url wss://gateway-host:18789 --token <token># preferred for local process safetyOmeniaClaw acp --url wss://gateway-host:18789 --token-file ~/.OmeniaClaw/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:

OmeniaClaw acp --session agent:main:mainOmeniaClaw acp --session agent:design:mainOmeniaClaw 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 OmeniaClaw 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 OmeniaClaw-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 OmeniaClaw-bot praat, gebruik dan acpx met het ingebouwde OmeniaClaw-doel.

Typische flow:

1. Start de Gateway en zorg dat de ACP-bridge deze kan bereiken.
2. Richt acpx OmeniaClaw op OmeniaClaw acp.
3. Richt je op de OmeniaClaw-sessiesleutel die je de codeeragent wilt laten gebruiken.

Voorbeelden:

# One-shot request into your default OmeniaClaw ACP sessionacpx OmeniaClaw exec "Summarize the active OmeniaClaw session state." # Persistent named session for follow-up turnsacpx OmeniaClaw sessions ensure --name codex-bridgeacpx OmeniaClaw -s codex-bridge --cwd /path/to/repo \  "Ask my OmeniaClaw work agent for recent context relevant to this repo."

Als je wilt dat acpx OmeniaClaw elke keer op een specifieke Gateway en sessiesleutel is gericht, overschrijf dan de OmeniaClaw-agentopdracht in ~/.acpx/config.json:

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

Gebruik voor een repo-lokale OmeniaClaw-checkout het directe CLI-entrypoint in plaats van de dev-runner, zodat de ACP-stream schoon blijft. Bijvoorbeeld:

env OmeniaClaw_HIDE_BANNER=1 OmeniaClaw_SUPPRESS_NOTES=1 node OmeniaClaw.mjs acp ...

Dit is de eenvoudigste manier om Codex, Claude Code of een andere ACP-bewuste client contextuele informatie uit een OmeniaClaw-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": {    "OmeniaClaw ACP": {      "type": "custom",      "command": "OmeniaClaw",      "args": ["acp"],      "env": {}    }  }}

Om een specifieke Gateway of agent te richten:

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

Open in Zed het Agent-paneel en selecteer "OmeniaClaw 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 (OmeniaClaw_GATEWAY_TOKEN, OmeniaClaw_GATEWAY_PASSWORD).
• Gateway-authenticatieresolutie volgt het gedeelde contract dat door andere Gateway-clients wordt gebruikt:
  • lokale modus: env (OmeniaClaw_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 OmeniaClaw_SHELL=acp, wat kan worden gebruikt voor contextspecifieke shell-/profielregels.
• OmeniaClaw acp client stelt OmeniaClaw_SHELL=acp-client in op het gestarte bridgeproces.

Opties voor acp client

• --cwd <dir>: werkdirectory voor de ACP-sessie.
• --server <command>: ACP-serveropdracht (standaard: OmeniaClaw).
• --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

• CLI-referentie
• ACP-agenten