ACP

​

Cosa non è

• se l’editor/client deve comunicare tramite ACP con OpenClaw: usa openclaw acp
• se OpenClaw deve avviare Codex/Claude/Gemini come harness ACP: usa /acp spawn e agenti ACP

​

Matrice di compatibilità

​

Limitazioni note

• loadSession riproduce la cronologia completa del registro eventi ACP solo per le sessioni create dal bridge. Le sessioni precedenti o prive di registro usano il ripiego sulla trascrizione e non ricostruiscono le chiamate storiche agli strumenti né gli avvisi di sistema.
• Se più client ACP condividono la stessa chiave di sessione del Gateway, l’instradamento degli eventi e degli annullamenti è basato sul massimo sforzo anziché essere rigorosamente isolato per client. Quando servono turni locali dell’editor nettamente separati, preferisci le sessioni isolate predefinite acp-bridge:<uuid>.
• Gli stati di arresto del Gateway vengono tradotti in motivi di arresto ACP, ma questa associazione è meno espressiva rispetto a un runtime completamente nativo ACP.
• I controlli di sessione espongono un sottoinsieme mirato delle opzioni del Gateway: livello di pensiero, verbosità degli strumenti, ragionamento, dettagli di utilizzo e azioni con privilegi elevati. La selezione del modello e i controlli dell’host di esecuzione non sono esposti come opzioni di configurazione ACP.
• session_info_update e usage_update derivano dalle istantanee delle sessioni del Gateway, non dalla contabilizzazione in tempo reale di un runtime nativo ACP. L’utilizzo è approssimativo, non include dati sui costi e viene emesso solo quando il Gateway contrassegna come aggiornati i dati sui token totali.
• I dati di accompagnamento degli strumenti sono basati sul massimo sforzo: il bridge espone i percorsi dei file presenti negli argomenti/risultati noti degli strumenti, ma non emette terminali ACP né differenze strutturate dei file.
• L’inoltro dell’approvazione dell’esecuzione è limitato al turno attivo del prompt ACP; le approvazioni provenienti da altre sessioni del Gateway vengono ignorate.

​

Utilizzo

openclaw acp

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

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

# Collegamento a una chiave di sessione esistente
openclaw acp --session agent:main:main

# Collegamento tramite etichetta (deve esistere già)
openclaw acp --session-label "support inbox"

# Reimpostazione della chiave di sessione prima del primo prompt
openclaw acp --session agent:main:main --reset-session

​

Client ACP (debug)

openclaw acp client

# Indirizza il bridge avviato a un Gateway remoto
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Sostituisce il comando del server (predefinito: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

• L’approvazione automatica si basa su un elenco consentito e si applica solo agli ID attendibili degli strumenti principali.
• L’approvazione automatica di read è limitata alla directory di lavoro corrente (--cwd se impostato).
• ACP approva automaticamente solo categorie ristrette di sola lettura: chiamate read limitate alla directory di lavoro corrente attiva, oltre agli strumenti di ricerca di sola lettura (search, web_search, memory_search). Gli strumenti sconosciuti/non principali, le letture fuori ambito, gli strumenti con capacità di esecuzione, gli strumenti del piano di controllo, gli strumenti che apportano modifiche e i flussi interattivi richiedono sempre l’approvazione esplicita del prompt.
• Il valore toolCall.kind fornito dal server viene trattato come metadato non attendibile, non come fonte di autorizzazione.
• Questa politica del bridge ACP è distinta dalle autorizzazioni dell’harness ACPX. Se esegui OpenClaw tramite il backend acpx, plugins.entries.acpx.config.permissionMode=approve-all è l’interruttore di emergenza “yolo” per quella sessione dell’harness.

​

Test rapido del protocollo

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

​

Come usarlo

1. Assicurati che il Gateway sia in esecuzione (locale o remoto).
2. Configura la destinazione del Gateway (configurazione o flag).
3. Configura il tuo IDE affinché esegua openclaw acp tramite stdio.

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>
# preferibile per la sicurezza del processo locale
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

​

Selezione degli agenti

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

​

Utilizzo da acpx (Codex, Claude, altri client ACP)

1. Avvia il Gateway e assicurati che il bridge ACP possa raggiungerlo.
2. Indirizza acpx openclaw verso openclaw acp.
3. Specifica la chiave di sessione OpenClaw che vuoi far usare all’agente di programmazione.

# 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."

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

​

Configurazione dell’editor Zed

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

​

Associazione delle sessioni

• --session <key>: usa una chiave di sessione Gateway specifica.
• --session-label <label>: risolvi una sessione esistente tramite etichetta.
• --reset-session: genera un nuovo ID di sessione per quella chiave (stessa chiave, nuova trascrizione).

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

​

Opzioni

• --url <url>: URL WebSocket del Gateway (il valore predefinito è gateway.remote.url, se configurato).
• --token <token>: token di autenticazione del Gateway.
• --token-file <path>: legge il token di autenticazione del Gateway da un file.
• --password <password>: password di autenticazione del Gateway.
• --password-file <path>: legge la password di autenticazione del Gateway da un file.
• --session <key>: chiave di sessione predefinita.
• --session-label <label>: etichetta di sessione predefinita da risolvere.
• --require-existing: genera un errore se la chiave o l’etichetta di sessione non esiste.
• --reset-session: reimposta la chiave di sessione prima del primo utilizzo.
• --no-prefix-cwd: non anteporre la directory di lavoro ai prompt.
• --provenance <off|meta|meta+receipt>: include i metadati o le ricevute di provenienza ACP.
• --verbose, -v: registrazione dettagliata su stderr.

• --token e --password possono essere visibili negli elenchi dei processi locali su alcuni sistemi. Preferisci --token-file/--password-file o le variabili d’ambiente (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD).
• La risoluzione dell’autenticazione del Gateway segue il contratto condiviso utilizzato dagli altri client Gateway:
  • modalità locale: variabili d’ambiente (OPENCLAW_GATEWAY_*), quindi gateway.auth.*, con ripiego su gateway.remote.* solo quando gateway.auth.* non è impostato (un SecretRef locale configurato ma non risolto interrompe l’operazione in modo sicuro anziché ricorrere silenziosamente al ripiego)
  • modalità remota: gateway.remote.* con ripiego su variabili d’ambiente/configurazione secondo le regole di precedenza remota
  • --url è sicuro come sovrascrittura e non riutilizza credenziali implicite provenienti dalla configurazione o dalle variabili d’ambiente; passa esplicitamente --token/--password (o le varianti basate su file)

​

Opzioni di acp client

• --cwd <dir>: directory di lavoro per la sessione ACP.
• --server <command>: comando del server ACP (predefinito: openclaw).
• --server-args <args...>: argomenti aggiuntivi passati al server ACP.
• --server-verbose: abilita la registrazione dettagliata sul server ACP.
• --verbose, -v: registrazione dettagliata del client.
• openclaw acp client imposta OPENCLAW_SHELL=acp-client nel processo bridge avviato, che può essere utilizzato per regole della shell o del profilo specifiche del contesto.

​

Contenuti correlati

• Riferimento della CLI
• Agenti ACP