Agenti ACP

• 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.

• 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.

• --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.

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 <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> 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.

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

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.