Agenti ACP

• Se plugins.allow è impostato, è un inventario plugin restrittivo e deve includere acpx; altrimenti il backend ACP installato viene bloccato intenzionalmente e /acp doctor segnala la voce allowlist mancante.
• L'adapter Codex ACP viene preparato con il plugin acpx e avviato localmente quando possibile.
• Codex ACP viene eseguito con un CODEX_HOME isolato; OpenClaw copia le voci di progetto attendibili più la configurazione sicura di routing modello/provider dalla configurazione Codex host, mentre auth, notifiche e hook restano nella configurazione host.
• Altri adapter di harness target possono comunque essere recuperati su richiesta con npx la prima volta che li usi.
• L'autenticazione del fornitore deve comunque esistere sull'host per quell'harness.
• Se l'host non ha npm o accesso di rete, i recuperi degli adapter al primo avvio falliscono finché le cache non vengono preriscaldate o l'adapter non viene installato in un altro modo.

ACP avvia un vero processo di harness esterno. OpenClaw possiede routing, stato delle attività in background, consegna, associazioni e policy; l'harness possiede il proprio login provider, catalogo modelli, comportamento del filesystem e strumenti nativi.

Prima di dare la colpa a OpenClaw, verifica che:

• /acp doctor segnali un backend abilitato e sano.
• L'id target sia consentito da acp.allowedAgents quando quella allowlist è impostata.
• Il comando harness possa avviarsi sull'host Gateway.
• L'autenticazione provider sia presente per quell'harness (claude, codex, gemini, opencode, droid, ecc.).
• Il modello selezionato esista per quell'harness: gli id modello non sono portabili tra harness.
• Il cwd richiesto esista e sia accessibile, oppure ometti cwd e lascia che il backend usi il proprio predefinito.
• La modalità permessi corrisponda al lavoro. Le sessioni non interattive non possono fare clic sui prompt di permesso nativi, quindi le esecuzioni di coding con molte scritture/esecuzioni di solito richiedono un profilo permessi ACPX che possa procedere senza intervento.

• L'avvio crea o riprende una sessione runtime ACP, registra i metadati ACP nello store delle sessioni OpenClaw e può creare un'attività in background quando l'esecuzione è posseduta dal genitore.
• Le sessioni ACP possedute dal genitore vengono trattate come lavoro in background anche quando la sessione runtime è persistente; completamento e consegna tra superfici passano dal notificatore dell'attività genitore invece di comportarsi come una normale sessione chat visibile all'utente.
• La manutenzione delle attività chiude le sessioni ACP one-shot terminali o orfane possedute dal genitore. Le sessioni ACP persistenti vengono preservate mentre resta un'associazione di conversazione attiva; le sessioni persistenti obsolete senza associazione attiva vengono chiuse, così non possono essere riprese silenziosamente dopo che l'attività proprietaria è terminata o il relativo record attività è sparito.
• I messaggi di follow-up associati vanno direttamente alla sessione ACP finché l'associazione non viene chiusa, non perde il focus, viene reimpostata o scade.
• I comandi Gateway restano locali. /acp ..., /status e /unfocus non vengono mai inviati come normale testo prompt a un harness ACP associato.
• cancel interrompe il turno attivo quando il backend supporta la cancellazione; non elimina l'associazione o i metadati sessione.
• close termina la sessione ACP dal punto di vista di OpenClaw e rimuove l'associazione. Un harness può comunque mantenere la propria cronologia upstream se supporta la ripresa.
• Il plugin acpx pulisce gli alberi di processi wrapper e adapter posseduti da OpenClaw dopo close e raccoglie gli orfani ACPX posseduti da OpenClaw durante l'avvio del Gateway.
• I worker runtime inattivi sono idonei alla pulizia dopo acp.runtime.ttlMinutes; i metadati sessione archiviati restano disponibili per /acp sessions.

Trigger in linguaggio naturale che devono essere instradati al plugin Codex nativo quando è abilitato:

• "Bind this Discord channel to Codex."
• "Attach this chat to Codex thread <id>."
• "Show Codex threads, then bind this one."

L’associazione nativa delle conversazioni Codex è il percorso di controllo chat predefinito. Gli strumenti dinamici di OpenClaw continuano a essere eseguiti tramite OpenClaw, mentre gli strumenti nativi di Codex come shell/apply-patch vengono eseguiti dentro Codex. Per gli eventi degli strumenti nativi di Codex, OpenClaw inserisce un relay di hook nativo per turno, così gli hook dei plugin possono bloccare before_tool_call, osservare after_tool_call e instradare gli eventi Codex PermissionRequest tramite le approvazioni di OpenClaw. Gli hook Codex Stop vengono inoltrati a OpenClaw before_agent_finalize, dove i plugin possono richiedere un ulteriore passaggio del modello prima che Codex finalizzi la risposta. Il relay rimane deliberatamente conservativo: non modifica gli argomenti degli strumenti nativi di Codex né riscrive i record dei thread Codex. Usa ACP esplicito solo quando vuoi il modello runtime/sessione ACP. Il confine di supporto Codex integrato è documentato nel contratto di supporto v1 dell’harness Codex.

• riferimenti modello Codex legacy - route modello Codex OAuth/abbonamento legacy riparata da doctor.
• openai/* - runtime incorporato app-server Codex nativo per i turni agente OpenAI.
• /codex ... - controllo conversazione Codex nativo.
• /acp ... o runtime: "acp" - controllo ACP/acpx esplicito.

Trigger che dovrebbero instradare al runtime ACP:

• "Esegui questo come sessione Claude Code ACP one-shot e riassumi il risultato."
• "Usa Gemini CLI per questa attività in un thread, poi mantieni i follow-up nello stesso thread."
• "Esegui Codex tramite ACP in un thread in background."

OpenClaw sceglie runtime: "acp", risolve l’agentId dell’harness, si associa alla conversazione o al thread corrente quando supportato e instrada i follow-up a quella sessione fino a 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 pubblicizzato solo quando ACP è abilitato, il richiedente non è in sandbox e un backend runtime ACP è caricato. acp.dispatch.enabled=false mette in pausa il dispatch automatico dei thread ACP, ma non nasconde né blocca le chiamate esplicite sessions_spawn({ runtime: "acp" }). Punta a id di harness ACP come codex, claude, droid, gemini o opencode. Non passare un normale id agente di configurazione OpenClaw da agents_list, a meno che quella voce sia configurata esplicitamente con agents.list[].runtime.type="acp"; altrimenti usa il runtime sub-agent predefinito. Quando un agente OpenClaw è configurato con runtime.type="acp", OpenClaw usa runtime.acp.agent come id harness sottostante.

• --bind here e --thread ... si escludono a vicenda.
• --bind here funziona solo sui canali che pubblicizzano l’associazione alla conversazione corrente; altrimenti OpenClaw restituisce un messaggio di non supporto chiaro. Le associazioni persistono tra riavvii del Gateway.
• Su Discord, spawnSessions controlla la creazione di thread figli per --thread auto|here - non --bind here.
• Se esegui lo spawn verso un agente ACP diverso senza --cwd, OpenClaw eredita per impostazione predefinita il workspace dell’agente di destinazione. I percorsi ereditati mancanti (ENOENT/ENOTDIR) ricadono sul valore predefinito del backend; altri errori di accesso (ad esempio EACCES) emergono come errori di spawn.
• I comandi di gestione del Gateway restano locali nelle conversazioni associate - i comandi /acp ... sono gestiti da OpenClaw anche quando il normale testo di follow-up viene instradato alla sessione ACP associata; anche /status e /unfocus restano locali ogni volta che la gestione dei comandi è abilitata per quella superficie.

Quando le associazioni di thread sono abilitate per un adattatore di canale:

• OpenClaw associa un thread a una sessione ACP di destinazione.
• I messaggi di follow-up in quel thread vengono instradati alla sessione ACP associata.
• L’output ACP viene consegnato allo stesso thread.
• Unfocus/close/archive/idle-timeout o la scadenza per età massima rimuove l’associazione.
• /acp close, /acp cancel, /acp status, /status e /unfocus sono comandi Gateway, non prompt per l’harness ACP.

Feature flag richiesti per ACP associato a thread:

• acp.enabled=true
• acp.dispatch.enabled è attivo per impostazione predefinita (imposta false per mettere in pausa il dispatch automatico dei thread ACP; le chiamate esplicite sessions_spawn({ runtime: "acp" }) continuano a funzionare).
• Spawn delle sessioni thread dell’adattatore di canale abilitato (predefinito: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

Il supporto dell’associazione di thread è specifico dell’adattatore. Se l’adattatore del canale attivo non supporta le associazioni di thread, OpenClaw restituisce un messaggio chiaro di non supporto/non disponibilità.

• Qualsiasi adattatore di canale che espone la capacità di associazione sessione/thread.
• Supporto integrato attuale: thread/canali Discord, topic Telegram (topic forum in gruppi/supergruppi e topic DM).
• I canali plugin possono aggiungere supporto tramite la stessa interfaccia di associazione.

Le sessioni interattive sono pensate per continuare a conversare su una superficie chat visibile:

• /acp spawn ... --bind here vincola la conversazione corrente alla sessione ACP.
• /acp spawn ... --thread ... vincola un thread/argomento del canale alla sessione ACP.
• I bindings[].type="acp" configurati e persistenti instradano le conversazioni corrispondenti alla stessa sessione ACP.

I messaggi successivi nella conversazione vincolata vengono instradati direttamente alla sessione ACP e l'output ACP viene recapitato di nuovo allo stesso canale/thread/argomento.

Cosa invia OpenClaw all'harness:

• I normali follow-up vincolati vengono inviati come testo del prompt, più allegati solo quando l'harness/backend li supporta.
• I comandi di gestione /acp e i comandi Gateway locali vengono intercettati prima del dispatch ACP.
• Gli eventi di completamento generati dal runtime vengono materializzati per destinazione. Gli agenti OpenClaw ricevono l'envelope interno runtime-context di OpenClaw; gli harness ACP esterni ricevono un prompt semplice con il risultato child e l'istruzione. L'envelope grezza <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> non deve mai essere inviata a harness esterni o persistita come testo di trascrizione utente ACP.
• Le voci della trascrizione ACP usano il testo del trigger visibile all'utente o il prompt di completamento semplice. I metadati interni degli eventi restano strutturati in OpenClaw dove possibile e non vengono trattati come contenuto chat scritto dall'utente.

Le sessioni ACP one-shot generate da un'altra run agente sono child in background, simili ai sub-agent:

• Il parent richiede lavoro con sessions_spawn({ runtime: "acp", mode: "run" }).
• Il child viene eseguito nella propria sessione harness ACP.
• I turni child vengono eseguiti sulla stessa lane in background usata dagli spawn sub-agent nativi, quindi un harness ACP lento non blocca il lavoro non correlato della sessione principale.
• I completamenti vengono riportati tramite il percorso di annuncio del completamento del task. OpenClaw converte i metadati interni di completamento in un prompt ACP semplice prima di inviarli a un harness esterno, così gli harness non vedono marcatori di contesto runtime esclusivi di OpenClaw.
• Il parent riscrive il risultato child con una normale voce da assistente quando è utile una risposta visibile all'utente.

Non trattare questo percorso come una chat peer-to-peer tra parent e child. Il child dispone già di un canale di completamento verso il parent.

sessions_send può indirizzare un'altra sessione dopo lo spawn. Per le normali sessioni peer, OpenClaw usa un percorso di follow-up agent-to-agent (A2A) dopo aver iniettato il messaggio:

• Attendi la risposta della sessione di destinazione.
• Facoltativamente, lascia che richiedente e destinazione scambino un numero limitato di turni di follow-up.
• Chiedi alla destinazione di produrre un messaggio di annuncio.
• Recapita quell'annuncio al canale o thread visibile.

Quel percorso A2A è un fallback per gli invii peer in cui il mittente necessita di un follow-up visibile. Rimane abilitato quando una sessione non correlata può vedere e inviare messaggi a una destinazione ACP, ad esempio con impostazioni ampie di tools.sessions.visibility.

OpenClaw salta il follow-up A2A solo quando il richiedente è il genitore del proprio figlio ACP one-shot posseduto dal genitore. In quel caso, eseguire A2A sopra il completamento dell'attività può risvegliare il genitore con il risultato del figlio, inoltrare la risposta del genitore di nuovo al figlio e creare un ciclo di eco genitore/figlio. Il risultato di sessions_send segnala delivery.status="skipped" per quel caso di figlio posseduto perché il percorso di completamento è già responsabile del risultato.

Usa resumeSessionId per continuare una sessione ACP precedente invece di ricominciare da zero. L'agente riproduce la cronologia della conversazione tramite session/load, quindi riprende con il contesto completo di ciò che è avvenuto prima.

{  "task": "Continue where we left off - fix the remaining test failures",  "runtime": "acp",  "agentId": "codex",  "resumeSessionId": "<previous-session-id>"}

Casi d'uso comuni:

• Passa una sessione Codex dal laptop al telefono: dì al tuo agente di riprendere da dove eri rimasto.
• Continua una sessione di codifica avviata interattivamente nella CLI, ora in modalità headless tramite il tuo agente.
• Riprendi il lavoro interrotto da un riavvio del gateway o da un timeout di inattività.

Note:

• resumeSessionId si applica solo quando runtime: "acp"; il runtime predefinito del sotto-agente ignora questo campo solo ACP.
• streamTo si applica solo quando runtime: "acp"; il runtime predefinito del sotto-agente ignora questo campo solo ACP.
• resumeSessionId è un id di ripresa ACP/harness locale all'host, non una chiave di sessione del canale OpenClaw; OpenClaw controlla comunque la policy di spawn ACP e la policy dell'agente di destinazione prima del dispatch, mentre il backend ACP o l'harness possiede l'autorizzazione per caricare quell'id upstream.
• resumeSessionId ripristina la cronologia della conversazione ACP upstream; thread e mode si applicano comunque normalmente alla nuova sessione OpenClaw che stai creando, quindi mode: "session" richiede ancora thread: true.
• L'agente di destinazione deve supportare session/load (Codex e Claude Code lo supportano).
• Se l'id di sessione non viene trovato, lo spawn fallisce con un errore chiaro: nessun fallback silenzioso a una nuova sessione.

Dopo una distribuzione del Gateway, esegui un controllo end-to-end live invece di fidarti dei test unitari:

1. Verifica la versione e il commit del Gateway distribuito sull'host di destinazione.
2. Apri una sessione bridge ACPX temporanea verso un agente live.
3. Chiedi a quell'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 vero childSessionKey e nessun errore del validatore.
5. Pulisci la sessione bridge temporanea.

Mantieni il gate su mode: "run" e salta streamTo: "parent": i percorsi mode: "session" legati al thread e di stream-relay sono passaggi di integrazione separati e più ricchi.