Skip to main content
Le sessioni Agent Client Protocol (ACP) consentono a OpenClaw di eseguire ambienti di programmazione esterni (Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI e altri ambienti ACPX supportati) tramite un plugin di backend ACP. Ogni avvio viene monitorato come attività in background.
ACP è il percorso per gli ambienti esterni, non il percorso Codex predefinito. Il plugin app-server nativo di Codex gestisce i comandi /codex ... e il runtime incorporato openai/gpt-* predefinito per i turni dell’agente; ACP gestisce i comandi /acp ... e le sessioni sessions_spawn({ runtime: "acp" }).Per consentire a Codex o Claude Code di connettersi direttamente come client MCP esterno alle conversazioni esistenti dei canali OpenClaw, usa openclaw mcp serve anziché ACP.

Quale pagina mi serve?

Funziona senza configurazione aggiuntiva?

Sì, dopo aver installato il plugin runtime ACP ufficiale:
I checkout del codice sorgente possono usare il plugin locale dell’area di lavoro extensions/acpx dopo pnpm install. Esegui /acp doctor per una verifica dell’idoneità. OpenClaw informa gli agenti sulla generazione di sessioni ACP solo quando ACP è realmente utilizzabile: ACP deve essere abilitato, l’invio non deve essere disabilitato, la sessione corrente non deve essere bloccata dalla sandbox e deve essere caricato e integro un backend runtime. Se una qualsiasi condizione non è soddisfatta, le Skills ACP e le indicazioni ACP di sessions_spawn restano nascoste, affinché l’agente non suggerisca un backend non disponibile.
  • Se plugins.allow è impostato, costituisce un inventario restrittivo dei plugin e deve includere acpx; in caso contrario, il backend ACP installato viene intenzionalmente bloccato (/acp doctor segnala la voce mancante nell’elenco consentito).
  • L’adattatore Codex ACP è incluso nel plugin acpx e, quando possibile, viene avviato localmente.
  • Codex ACP viene eseguito con un CODEX_HOME isolato. OpenClaw copia dalla configurazione Codex dell’host le voci attendibili relative all’attendibilità del progetto e la configurazione sicura per l’instradamento di modelli/provider (model, model_provider, model_reasoning_effort, sandbox_mode e i campi sicuri model_providers.<name>); autenticazione, notifiche e hook restano esclusivamente nella configurazione dell’host.
  • Gli adattatori per altri ambienti di destinazione possono essere scaricati su richiesta con npx al primo utilizzo.
  • L’autenticazione del fornitore per quell’ambiente deve essere già presente sull’host.
  • Se l’host non dispone di npm o dell’accesso alla rete, il recupero degli adattatori al primo avvio non riesce finché le cache non vengono preriscaldate o l’adattatore non viene installato in altro modo.
ACP avvia un vero processo di ambiente esterno. OpenClaw gestisce instradamento, stato delle attività in background, consegna, associazioni e criteri; l’ambiente gestisce l’accesso al proprio provider, il catalogo dei modelli, il comportamento del file system e gli strumenti nativi.Prima di attribuire il problema a OpenClaw, verifica quanto segue:
  • /acp doctor segnala un backend abilitato e integro.
  • L’id di destinazione è consentito da acp.allowedAgents quando tale elenco consentito è impostato.
  • Il comando dell’ambiente può essere avviato sull’host del Gateway.
  • L’autenticazione del provider è presente per tale ambiente (claude, codex, gemini, opencode, droid e così via).
  • Il modello selezionato esiste per tale ambiente: gli id dei modelli non sono trasferibili tra ambienti.
  • Il cwd richiesto esiste ed è accessibile; in alternativa, ometti cwd e lascia che il backend utilizzi il valore predefinito.
  • La modalità dei permessi è adatta al lavoro. Le sessioni non interattive non possono confermare le richieste native di autorizzazione, pertanto le esecuzioni di programmazione che richiedono molte operazioni di scrittura/esecuzione necessitano in genere di un profilo di permessi ACPX che possa procedere senza interfaccia interattiva.
Gli strumenti dei plugin OpenClaw e gli strumenti OpenClaw integrati non vengono esposti per impostazione predefinita agli ambienti ACP. Abilita i bridge MCP espliciti in Agenti ACP - configurazione solo quando l’ambiente deve richiamare direttamente tali strumenti.

Destinazioni degli ambienti supportate

Con il backend acpx, usa questi id come destinazioni per /acp spawn <id> o sessions_spawn({ runtime: "acp", agentId: "<id>" }): Anche pi (pi-acp) è registrato nel backend acpx, ma non è un ambiente di programmazione nello stesso senso degli altri elencati sopra. Gli alias personalizzati degli agenti acpx possono essere configurati direttamente in acpx, ma i criteri di OpenClaw verificano comunque acp.allowedAgents e qualsiasi mappatura agents.list[].runtime.acp.agent prima dell’invio.

Procedura operativa

Flusso rapido di /acp dalla chat:
1

Avvia

/acp spawn claude --bind here, /acp spawn gemini --mode persistent --thread auto oppure, esplicitamente, /acp spawn codex --bind here.
2

Lavora

Continua nella conversazione o nel thread associato (oppure specifica esplicitamente la chiave della sessione).
3

Controlla lo stato

/acp status
4

Regola

/acp model <provider/model>, /acp permissions <profile>, /acp timeout <seconds>.
5

Orienta

Senza sostituire il contesto: /acp steer tighten logging and continue.
6

Arresta

/acp cancel (turno corrente) o /acp close (sessione + associazioni).
  • L’avvio crea o riprende una sessione runtime ACP, registra i metadati ACP nell’archivio delle sessioni OpenClaw e può creare un’attività in background quando l’esecuzione appartiene al genitore.
  • Le sessioni ACP appartenenti al genitore vengono trattate come lavoro in background anche quando la sessione runtime è persistente; il completamento e la consegna tra superfici passano attraverso il notificatore dell’attività genitore, anziché comportarsi come una normale sessione di chat visibile all’utente.
  • La manutenzione delle attività chiude le sessioni ACP monouso terminali o orfane appartenenti al genitore. Le sessioni ACP persistenti vengono conservate finché rimane attiva un’associazione a una conversazione; le sessioni persistenti obsolete prive di un’associazione attiva vengono chiuse, affinché non possano essere riprese silenziosamente dopo il completamento dell’attività proprietaria o la scomparsa del relativo record.
  • I messaggi successivi associati vengono inviati direttamente alla sessione ACP finché l’associazione non viene chiusa, privata dello stato attivo, reimpostata o scaduta.
  • I comandi del Gateway restano locali. /acp ..., /status e /unfocus non vengono mai inviati come normale testo del prompt a un ambiente ACP associato.
  • cancel interrompe il turno attivo quando il backend supporta l’annullamento; non elimina l’associazione né i metadati della sessione.
  • close termina la sessione ACP dal punto di vista di OpenClaw e rimuove l’associazione. Un ambiente può comunque conservare la propria cronologia upstream se supporta la ripresa.
  • Il plugin acpx pulisce gli alberi dei processi wrapper e adattatore appartenenti a OpenClaw dopo close e rimuove i processi ACPX orfani e obsoleti appartenenti a OpenClaw durante l’avvio del Gateway.
  • I worker runtime inattivi possono essere rimossi dopo acp.runtime.ttlMinutes; i metadati delle sessioni archiviati restano disponibili per /acp sessions.
Trigger in linguaggio naturale che devono essere instradati al plugin Codex nativo quando è abilitato:
  • “Associa questo canale Discord a Codex.”
  • “Collega questa chat al thread Codex <id>.”
  • “Mostra i thread Codex, quindi associa questo.”
Il collegamento nativo delle conversazioni Codex è il percorso predefinito per il controllo della chat. Gli strumenti dinamici di OpenClaw continuano a essere eseguiti tramite OpenClaw, mentre gli strumenti nativi di Codex, come shell/apply-patch, vengono eseguiti all’interno di Codex. Per gli eventi degli strumenti nativi di Codex, OpenClaw inserisce a ogni turno un relay di hook nativo affinché gli hook dei plugin possano bloccare before_tool_call, osservare after_tool_call e instradare gli eventi PermissionRequest di Codex attraverso le approvazioni di OpenClaw. Gli hook Stop di Codex vengono inoltrati a before_agent_finalize di OpenClaw, dove i plugin possono richiedere un ulteriore passaggio del modello prima che Codex finalizzi la risposta. Il relay rimane volutamente prudente: non modifica gli argomenti degli strumenti nativi di Codex né riscrive i record dei thread di Codex. Usa ACP esplicito solo quando desideri il modello di runtime/sessione ACP. Il confine del supporto Codex incorporato è documentato nel contratto di supporto v1 dell’harness Codex.
  • riferimenti ai modelli Codex legacy - percorso legacy dei modelli Codex OAuth/abbonamento riparato da doctor.
  • openai/* - runtime incorporato nativo dell’app-server Codex per i turni degli agenti OpenAI.
  • /codex ... - controllo nativo delle conversazioni Codex.
  • /acp ... o runtime: "acp" - controllo ACP/acpx esplicito.
Trigger che devono instradare verso il runtime ACP:
  • “Esegui questa attività come sessione ACP Claude Code singola e riepiloga il risultato.”
  • “Usa Gemini CLI per questa attività in un thread, quindi mantieni i messaggi successivi nello stesso thread.”
  • “Esegui Codex tramite ACP in un thread in background.”
OpenClaw seleziona runtime: "acp", risolve l’agentId dell’harness, si collega alla conversazione o al thread corrente, quando supportato, e instrada i messaggi successivi a quella sessione fino alla chiusura/scadenza. Codex segue questo percorso solo quando ACP/acpx è esplicito o il plugin Codex nativo non è disponibile per l’operazione richiesta.Per sessions_spawn, runtime: "acp" viene proposto solo quando ACP è abilitato, il richiedente non è in sandbox ed è caricato un backend di runtime ACP. acp.dispatch.enabled=false sospende l’inoltro automatico dei thread ACP, ma non nasconde né blocca le chiamate esplicite sessions_spawn({ runtime: "acp" }). È destinato agli ID degli harness ACP, come codex, claude, droid, gemini o opencode. Non passare un normale ID agente della configurazione OpenClaw ottenuto da agents_list, a meno che tale voce non sia configurata esplicitamente con agents.list[].runtime.type="acp"; in caso contrario, usa il runtime predefinito dei sotto-agenti. Quando un agente OpenClaw è configurato con runtime.type="acp", OpenClaw usa runtime.acp.agent come ID dell’harness sottostante.

ACP rispetto ai sotto-agenti

Usa ACP quando desideri un runtime harness esterno. Usa l’app-server Codex nativo per il collegamento/controllo delle conversazioni Codex quando il plugin codex è abilitato. Usa i sotto-agenti quando desideri esecuzioni delegate native di OpenClaw. Vedi anche Sotto-agenti.

Come ACP esegue Claude Code

Per Claude Code tramite ACP, lo stack è:
  1. Piano di controllo delle sessioni ACP di OpenClaw.
  2. Plugin runtime ufficiale @openclaw/acpx.
  3. Adattatore ACP di Claude.
  4. Meccanismi di runtime/sessione sul lato Claude.
ACP Claude è una sessione harness con controlli ACP, ripresa della sessione, monitoraggio delle attività in background e collegamento facoltativo alla conversazione/al thread. I backend CLI sono runtime di ripiego locali separati e basati solo su testo: vedi Backend CLI. Per gli operatori, la regola pratica è:
  • Vuoi /acp spawn, sessioni collegabili, controlli del runtime o attività persistenti dell’harness? Usa ACP.
  • Vuoi un semplice ripiego locale basato su testo tramite la CLI grezza? Usa i backend CLI.

Sessioni collegate

Modello mentale

  • Superficie di chat - il luogo in cui le persone continuano a conversare (canale Discord, argomento Telegram, chat iMessage).
  • Sessione ACP - lo stato durevole del runtime Codex/Claude/Gemini verso cui OpenClaw instrada.
  • Thread/argomento figlio - un’ulteriore superficie di messaggistica facoltativa, creata solo da --thread ....
  • Area di lavoro del runtime - la posizione nel file system (cwd, checkout del repository, area di lavoro del backend) in cui viene eseguito l’harness. Indipendente dalla superficie di chat.

Collegamenti alla conversazione corrente

/acp spawn <harness> --bind here fissa la conversazione corrente alla sessione ACP avviata: nessun thread figlio, stessa superficie di chat. OpenClaw continua a gestire trasporto, autenticazione, sicurezza e recapito. I messaggi successivi in quella conversazione vengono instradati alla stessa sessione; /new e /reset reimpostano la sessione sul posto; /acp close rimuove il collegamento. Esempi:
  • --bind here e --thread ... si escludono a vicenda.
  • --bind here funziona solo sui canali che dichiarano il supporto al collegamento della conversazione corrente; in caso contrario, OpenClaw restituisce un messaggio chiaro che indica la mancata disponibilità del supporto. I collegamenti persistono tra i riavvii del Gateway.
  • Su Discord, spawnSessions controlla la creazione di thread figli per --thread auto|here, non per --bind here.
  • Se avvii un agente ACP diverso senza --cwd, OpenClaw eredita per impostazione predefinita l’area di lavoro dell’agente di destinazione. I percorsi ereditati mancanti (ENOENT/ENOTDIR) comportano il ripiego sul valore predefinito del backend; gli altri errori di accesso (ad esempio EACCES) vengono restituiti come errori di avvio.
  • I comandi di gestione del Gateway rimangono locali nelle conversazioni collegate: i comandi /acp ... vengono gestiti da OpenClaw anche quando il normale testo dei messaggi successivi viene instradato alla sessione ACP collegata; anche /status e /unfocus rimangono locali ogni volta che la gestione dei comandi è abilitata per quella superficie.
Quando i collegamenti ai thread sono abilitati per un adattatore di canale:
  • OpenClaw collega un thread a una sessione ACP di destinazione.
  • I messaggi successivi in quel thread vengono instradati alla sessione ACP collegata.
  • L’output ACP viene recapitato allo stesso thread.
  • La rimozione dello stato attivo, la chiusura, l’archiviazione, la scadenza per inattività o la scadenza per età massima rimuovono il collegamento.
  • /acp close, /acp cancel, /acp status, /status e /unfocus sono comandi del Gateway, non prompt per l’harness ACP.
Flag di funzionalità necessari per ACP collegato ai thread:
  • acp.enabled=true
  • acp.dispatch.enabled è attivo per impostazione predefinita (imposta false per sospendere l’inoltro automatico dei thread ACP; le chiamate esplicite sessions_spawn({ runtime: "acp" }) continuano a funzionare).
  • Avvio delle sessioni dei thread dell’adattatore di canale abilitato (impostazione predefinita: true):
    • Discord: channels.discord.threadBindings.spawnSessions=true
    • Telegram: channels.telegram.threadBindings.spawnSessions=true
Il supporto dei collegamenti ai thread dipende dall’adattatore. Se l’adattatore del canale attivo non supporta i collegamenti ai thread, OpenClaw restituisce un messaggio chiaro che indica che la funzionalità non è supportata/disponibile.
  • Qualsiasi adattatore di canale che esponga la funzionalità di collegamento a sessioni/thread.
  • Supporto integrato attuale: thread/canali Discord, argomenti Telegram (argomenti forum in gruppi/supergruppi e argomenti nei messaggi diretti).
  • I canali dei plugin possono aggiungere il supporto tramite la stessa interfaccia di collegamento.

Collegamenti persistenti dei canali

Per i flussi di lavoro non effimeri, configura collegamenti ACP persistenti nelle voci bindings[] di primo livello.

Modello di collegamento

"acp"
Contrassegna un collegamento persistente di una conversazione ACP.
object
Identifica la conversazione di destinazione. Formati specifici per canale:
  • Canale/thread Discord: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Canale/DM Slack: match.channel="slack" + match.peer.id="<channelId|channel:<channelId>|#<channelId>|userId|user:<userId>|slack:<userId>|<@userId>>". Preferisci ID Slack stabili; i collegamenti ai canali corrispondono anche alle risposte all’interno dei thread di quel canale.
  • Argomento forum Telegram: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • DM/gruppo WhatsApp: match.channel="whatsapp" + match.peer.id="<E.164|group JID>". Usa numeri E.164, come +15555550123, per le chat dirette e JID dei gruppi WhatsApp, come 120363424282127706@g.us, per i gruppi.
  • DM/gruppo iMessage: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>". Preferisci chat_id:* per collegamenti stabili ai gruppi.
string
L’ID dell’agente OpenClaw proprietario.
"persistent" | "oneshot"
Sostituzione ACP facoltativa.
string
Etichetta facoltativa rivolta all’operatore.
string
Directory di lavoro facoltativa del runtime.
string
Sostituzione facoltativa del backend.

Valori predefiniti del runtime per agente

Usa agents.list[].runtime per definire i valori predefiniti ACP una sola volta per agente:
  • agents.list[].runtime.type="acp"
  • agents.list[].runtime.acp.agent (ID dell’harness, ad esempio codex o claude)
  • agents.list[].runtime.acp.backend
  • agents.list[].runtime.acp.mode
  • agents.list[].runtime.acp.cwd
Precedenza delle sostituzioni per le sessioni ACP collegate:
  1. bindings[].acp.*
  2. agents.list[].runtime.acp.*
  3. Valori predefiniti ACP globali (ad esempio acp.backend)

Esempio

Comportamento

  • OpenClaw garantisce che la sessione ACP configurata esista dopo l’ammissione specifica del canale e prima dell’uso.
  • I messaggi in quel canale, argomento o chat vengono instradati alla sessione ACP configurata.
  • I binding ACP configurati sono proprietari dell’instradamento della propria sessione. La distribuzione broadcast del canale non sostituisce la sessione ACP configurata per un binding corrispondente.
  • Nelle conversazioni associate, /new e /reset reimpostano sul posto la stessa chiave di sessione ACP.
  • I binding di runtime temporanei, ad esempio quelli creati dai flussi di messa a fuoco dei thread, continuano ad applicarsi quando presenti.
  • Per gli avvii ACP tra agenti senza un cwd esplicito, OpenClaw eredita l’area di lavoro dell’agente di destinazione dalla configurazione dell’agente.
  • Se i percorsi ereditati dell’area di lavoro non esistono, viene usata come ripiego la directory di lavoro predefinita del backend; gli errori di accesso per percorsi esistenti vengono segnalati come errori di avvio.

Avviare sessioni ACP

Esistono due modi per avviare una sessione ACP:
Usa runtime: "acp" per avviare una sessione ACP da un turno dell’agente o da una chiamata a uno strumento.
Il valore predefinito di runtime è subagent, quindi imposta esplicitamente runtime: "acp" per le sessioni ACP. Se agentId viene omesso, OpenClaw usa acp.defaultAgent quando è configurato. mode: "session" richiede thread: true per mantenere una conversazione associata persistente.

Parametri di sessions_spawn

string
obbligatorio
Prompt iniziale inviato alla sessione ACP.
"acp"
obbligatorio
Deve essere "acp" per le sessioni ACP.
string
ID dell’harness ACP di destinazione. Se impostato, viene usato come ripiego acp.defaultAgent.
boolean
predefinito:"false"
Richiede il flusso di associazione al thread, dove supportato.
"run" | "session"
predefinito:"run"
"run" è un’esecuzione singola; "session" è persistente. Se thread: true e mode viene omesso, OpenClaw può adottare per impostazione predefinita un comportamento persistente in base al percorso di runtime. mode: "session" richiede thread: true.
string
Directory di lavoro del runtime richiesta, convalidata dai criteri del backend/runtime. Se omessa, l’avvio ACP eredita l’area di lavoro dell’agente di destinazione quando configurata; se i percorsi ereditati non esistono, vengono usati come ripiego i valori predefiniti del backend, mentre gli effettivi errori di accesso vengono restituiti.
string
Etichetta visibile all’operatore usata nel testo della sessione o del banner.
string
Riprende una sessione ACP esistente anziché crearne una nuova. L’agente riproduce la cronologia della conversazione tramite session/load. Richiede runtime: "acp".
"parent"
"parent" trasmette i riepiloghi iniziali dell’avanzamento dell’esecuzione ACP alla sessione richiedente come eventi di sistema. Le risposte accettate includono streamLogPath, che punta a un registro JSONL circoscritto alla sessione (<sessionId>.acp-stream.jsonl) che puoi seguire per ottenere l’intera cronologia di inoltro. Per impostazione predefinita, i flussi di avanzamento verso il genitore mostrano i commenti dell’assistente e l’avanzamento dello stato ACP, a meno che streaming.progress.commentary=false. Anche Discord usa per impostazione predefinita la modalità di avanzamento per le anteprime verso il genitore quando non è configurata alcuna modalità di flusso. L’avanzamento dello stato rispetta comunque acp.stream.tagVisibility, quindi tag come plan rimangono nascosti se non vengono abilitati esplicitamente.
Le esecuzioni ACP di sessions_spawn usano agents.defaults.subagents.runTimeoutSeconds come limite predefinito per il turno figlio. Lo strumento non accetta sostituzioni del timeout per singola chiamata (runTimeoutSeconds/timeoutSeconds vengono rifiutati con un errore che richiede di configurare il valore predefinito).
string
Sostituzione esplicita del modello per la sessione ACP figlia. Gli avvii ACP di Codex normalizzano riferimenti OpenAI come openai/gpt-5.4 nella configurazione di avvio ACP di Codex prima di session/new; le forme con barra, come openai/gpt-5.4/high, impostano anche l’intensità di ragionamento ACP di Codex. Quando viene omesso, sessions_spawn({ runtime: "acp" }) usa i valori predefiniti esistenti del modello del sottoagente (agents.defaults.subagents.model o agents.list[].subagents.model) quando configurati; altrimenti consente all’harness ACP di usare il proprio modello predefinito. Gli altri harness devono dichiarare i models ACP e supportare session/set_model; in caso contrario OpenClaw/acpx restituisce un errore chiaro anziché usare silenziosamente come ripiego il modello predefinito dell’agente di destinazione.
string
Intensità esplicita di pensiero/ragionamento. Per ACP di Codex, minimal corrisponde a un’intensità bassa, low/medium/high/xhigh vengono mappati direttamente e off omette la sostituzione dell’intensità di ragionamento all’avvio. Quando viene omesso, gli avvii ACP usano i valori predefiniti esistenti di pensiero del sottoagente e agents.defaults.models["provider/model"].params.thinking specifico per modello per il modello selezionato.

Modalità di associazione e thread per l’avvio

Note:
  • --bind here è il percorso più semplice per l’operatore per «fare in modo che questo canale o questa chat usi Codex».
  • --bind here non crea un thread figlio.
  • --bind here è disponibile solo sui canali che espongono il supporto per l’associazione alla conversazione corrente.
  • --bind e --thread non possono essere combinati nella stessa chiamata /acp spawn.

Modello di consegna

Le sessioni ACP possono essere aree di lavoro interattive oppure attività in background gestite dal genitore. Il percorso di consegna dipende da questa configurazione.
Le sessioni interattive sono concepite per continuare a conversare su una superficie di chat visibile:
  • /acp spawn ... --bind here associa la conversazione corrente alla sessione ACP.
  • /acp spawn ... --thread ... associa un thread/argomento del canale alla sessione ACP.
  • I bindings[].type="acp" configurati in modo persistente instradano le conversazioni corrispondenti alla stessa sessione ACP.
I messaggi successivi nella conversazione associata vengono instradati direttamente alla sessione ACP e l’output ACP viene restituito allo stesso canale/thread/argomento.Ciò che OpenClaw invia all’harness:
  • I normali messaggi successivi associati vengono inviati come testo del prompt, con gli allegati solo quando l’harness/backend li supporta.
  • I comandi di gestione /acp e i comandi locali del Gateway vengono intercettati prima dell’invio ACP.
  • Gli eventi di completamento generati dal runtime vengono materializzati per ciascuna destinazione. Gli agenti OpenClaw ricevono l’involucro del contesto di runtime interno di OpenClaw; gli harness ACP esterni ricevono un semplice prompt con il risultato figlio e l’istruzione. L’involucro grezzo <<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>> non deve mai essere inviato agli harness esterni né conservato come testo della trascrizione utente ACP.
  • Le voci della trascrizione ACP usano il testo di attivazione visibile all’utente o il semplice prompt di completamento. Quando possibile, i metadati interni degli eventi rimangono strutturati in OpenClaw e non vengono trattati come contenuto della chat scritto dall’utente.
Le sessioni ACP a esecuzione singola avviate da un’altra esecuzione dell’agente sono figli in background, analoghi ai sottoagenti:
  • Il genitore richiede un’attività con sessions_spawn({ runtime: "acp", mode: "run" }).
  • Il figlio viene eseguito nella propria sessione dell’harness ACP.
  • I turni figli vengono eseguiti sulla stessa corsia in background usata dagli avvii nativi dei sottoagenti, perciò un harness ACP lento non blocca le attività non correlate della sessione principale.
  • Il completamento viene comunicato tramite il percorso di annuncio del completamento dell’attività. OpenClaw converte i metadati interni di completamento in un semplice prompt ACP prima di inviarli a un harness esterno, affinché gli harness non vedano gli indicatori del contesto di runtime riservati a OpenClaw.
  • Il genitore riformula il risultato del figlio con il normale tono dell’assistente quando è utile una risposta destinata all’utente.
Non trattare questo percorso come una chat peer-to-peer tra genitore e figlio. Il figlio dispone già di un canale di completamento verso il genitore.
sessions_send può indirizzare un’altra sessione dopo l’avvio. Per le normali sessioni peer, OpenClaw usa un percorso di messaggi successivi da agente ad agente (A2A) dopo avere inserito il messaggio:
  • Attende la risposta della sessione di destinazione.
  • Facoltativamente consente al richiedente e alla destinazione di scambiarsi un numero limitato di turni successivi.
  • Chiede alla destinazione di produrre un messaggio di annuncio.
  • Consegna tale annuncio al canale o al thread visibile.
Quel percorso A2A è una soluzione di ripiego per gli invii tra peer in cui il mittente necessita di un aggiornamento successivo visibile. Rimane abilitato quando una sessione non correlata può vedere e inviare messaggi a una destinazione ACP, ad esempio con impostazioni tools.sessions.visibility ampie.OpenClaw salta l’aggiornamento successivo A2A solo quando il richiedente è il genitore del proprio processo figlio ACP one-shot, di proprietà del genitore. In tal caso, eseguire A2A oltre al completamento dell’attività può riattivare il genitore con il risultato del processo figlio, inoltrare la risposta del genitore al processo figlio e creare un ciclo di eco genitore/figlio. Il risultato di sessions_send riporta delivery.status="skipped" per il caso del processo figlio di proprietà, perché il percorso di completamento è già responsabile del risultato.
Usa resumeSessionId per continuare una sessione ACP precedente invece di iniziare da zero. L’agente riproduce la cronologia della conversazione tramite session/load, riprendendo quindi con il contesto completo di ciò che è avvenuto in precedenza.
Casi d’uso comuni:
  • Trasferire una sessione Codex dal portatile al telefono: chiedi all’agente di riprendere da dove avevi interrotto.
  • Continuare una sessione di programmazione avviata in modo interattivo nella CLI, ora senza interfaccia tramite il tuo agente.
  • Riprendere un lavoro interrotto da un riavvio del Gateway o da un timeout di inattività.
Note:
  • resumeSessionId si applica solo quando runtime: "acp"; il runtime predefinito dei sottoagenti ignora questo campo esclusivo di ACP.
  • streamTo si applica solo quando runtime: "acp"; il runtime predefinito dei sottoagenti ignora questo campo esclusivo di ACP.
  • resumeSessionId è un ID di ripresa ACP/harness locale all’host, non una chiave di sessione del canale OpenClaw; OpenClaw verifica comunque i criteri di avvio ACP e quelli dell’agente di destinazione prima dell’invio, mentre il backend ACP o l’harness gestisce l’autorizzazione per il caricamento di tale ID upstream.
  • resumeSessionId ripristina la cronologia della conversazione ACP upstream; thread e mode continuano ad applicarsi normalmente alla nuova sessione OpenClaw che stai creando, quindi mode: "session" richiede comunque thread: true.
  • L’agente di destinazione deve supportare session/load (Codex e Claude Code lo supportano).
  • Se l’ID sessione non viene trovato, l’avvio non riesce con un errore chiaro, senza alcun ripiego silenzioso su una nuova sessione.
Dopo la distribuzione di un Gateway, esegui una verifica end-to-end dal vivo invece di affidarti agli unit test:
  1. Verifica la versione e il commit del Gateway distribuito sull’host di destinazione.
  2. Apri una sessione bridge ACPX temporanea verso un agente attivo.
  3. Chiedi a tale agente di chiamare sessions_spawn con runtime: "acp", agentId: "codex", mode: "run" e attività Reply with exactly LIVE-ACP-SPAWN-OK.
  4. Verifica accepted=yes, un childSessionKey reale e l’assenza di errori del validatore.
  5. Elimina la sessione bridge temporanea.
Mantieni il controllo su mode: "run" e ometti streamTo: "parent": il mode: "session" associato a un thread e i percorsi di inoltro del flusso sono verifiche di integrazione separate e più complete.

Compatibilità con la sandbox

Le sessioni ACP vengono attualmente eseguite nel runtime dell’host, non all’interno della sandbox di OpenClaw.
Confine di sicurezza:
  • L’harness esterno può leggere/scrivere in base alle proprie autorizzazioni CLI e al cwd selezionato.
  • I criteri della sandbox di OpenClaw non avvolgono l’esecuzione dell’harness ACP.
  • OpenClaw applica comunque i controlli di abilitazione delle funzionalità ACP, gli agenti consentiti, la proprietà delle sessioni, le associazioni ai canali e i criteri di consegna del Gateway.
  • Usa runtime: "subagent" per il lavoro nativo di OpenClaw soggetto all’applicazione della sandbox.
Limitazioni attuali:
  • Se la sessione richiedente è in sandbox, gli avvii ACP vengono bloccati sia per sessions_spawn({ runtime: "acp" }) sia per /acp spawn.
  • sessions_spawn con runtime: "acp" non supporta sandbox: "require".

Risoluzione della destinazione della sessione

La maggior parte delle azioni /acp accetta una destinazione di sessione facoltativa (session-key, session-id o session-label). Ordine di risoluzione:
  1. Argomento di destinazione esplicito (o --session per /acp steer)
    • prova prima la chiave
    • poi l’ID sessione in formato UUID
    • infine l’etichetta
  2. Associazione al thread corrente (se questa conversazione/thread è associata a una sessione ACP).
  3. Ripiego sulla sessione del richiedente corrente.
Sia le associazioni alla conversazione corrente sia quelle al thread partecipano al passaggio 2. Se non viene risolta alcuna destinazione, OpenClaw restituisce un errore chiaro (Unable to resolve session target: ...).

Controlli ACP

I controlli del runtime (spawn, cancel, steer, close, status, set-mode, set, cwd, permissions, timeout, model e reset-options) richiedono l’identità del proprietario dai canali esterni e operator.admin dai client interni del Gateway. I mittenti autorizzati non proprietari possono comunque usare sessions, doctor, install e help. /acp status mostra le opzioni effettive del runtime, oltre agli identificatori di sessione a livello di runtime e backend. Gli errori relativi ai controlli non supportati vengono mostrati chiaramente quando un backend non dispone di una funzionalità. /acp sessions legge l’archivio per la sessione attualmente associata o del richiedente; i token di destinazione (session-key, session-id o session-label) vengono risolti tramite il rilevamento delle sessioni del Gateway, incluse le directory radice session.store personalizzate per agente.

Mappatura delle opzioni del runtime

/acp dispone di comandi pratici e di un’impostazione generica. Operazioni equivalenti:

Harness acpx, configurazione dei Plugin e autorizzazioni

Per la configurazione dell’harness acpx (alias di Claude Code / Codex / Gemini CLI), i bridge MCP plugin-tools e OpenClaw-tools e le modalità di autorizzazione ACP, consulta Agenti ACP - configurazione.

Risoluzione dei problemi

Command blocked by PreToolUse hook: Native hook relay unavailable riguarda l’inoltro nativo degli hook di Codex, non ACP/acpx. In una chat Codex associata, avvia una nuova sessione con /new o /reset; se funziona una volta e poi l’errore si ripresenta alla successiva chiamata di uno strumento nativo, riavvia l’app-server di Codex o il Gateway di OpenClaw invece di ripetere /new. Consulta Risoluzione dei problemi dell’harness Codex.

Contenuti correlati