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 ACP Codex viene predisposto con il plugin acpx e avviato localmente quando possibile.
• Codex ACP viene eseguito con un CODEX_HOME isolato; OpenClaw copia solo le voci di progetto attendibili dalla configurazione Codex dell'host e considera attendibile il workspace attivo, lasciando auth, notifiche e hook sulla configurazione host.
• Altri adapter harness target possono ancora essere recuperati su richiesta con npx la prima volta che li usi.
• L'auth del vendor deve comunque esistere sull'host per quell'harness.
• Se l'host non ha npm o accesso di rete, i recuperi degli adapter alla prima esecuzione falliscono finché le cache non vengono preriscaldate o l'adapter non viene installato in un altro modo.

ACP avvia un vero processo 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 attribuire il problema a OpenClaw, verifica:

• /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'auth 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 suo predefinito.
• La modalità dei 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 necessitano di un profilo permessi ACPX che possa procedere headless.

• Lo spawn crea o riprende una sessione runtime ACP, registra metadati ACP nello store sessioni OpenClaw e può creare un'attività in background quando l'esecuzione è posseduta dal parent.
• Le sessioni ACP possedute dal parent sono trattate come lavoro in background anche quando la sessione runtime è persistente; completamento e consegna cross-surface passano dal notificatore attività parent invece di comportarsi come una normale sessione chat rivolta all'utente.
• La manutenzione attività chiude le sessioni ACP one-shot terminali o orfane possedute dal parent. Le sessioni ACP persistenti sono preservate finché resta un'associazione 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, sfocata, reimpostata o scaduta.
• 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 né i metadati della sessione.
• close termina la sessione ACP dal punto di vista di OpenClaw e rimuove l'associazione. Un harness può comunque conservare la propria cronologia upstream se supporta la ripresa.
• Il plugin acpx pulisce i wrapper posseduti da OpenClaw e gli alberi di processi adapter dopo close, e raccoglie gli orfani ACPX obsoleti posseduti da OpenClaw durante l'avvio del Gateway.
• I worker runtime inattivi sono idonei alla pulizia dopo acp.runtime.ttlMinutes; i metadati di sessione memorizzati restano disponibili per /acp sessions.

Trigger in linguaggio naturale che dovrebbero 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, poi associa questo."

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 inietta 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 resta volutamente conservativo: non modifica gli argomenti degli strumenti nativi di Codex né riscrive i record dei thread di Codex. Usa ACP esplicito solo quando vuoi il modello runtime/sessione ACP. Il confine di supporto di Codex incorporato è documentato nel contratto di supporto del harness Codex v1.

• openai-codex/* - route modello Codex OAuth/subscription legacy riparata da doctor.
• openai/* - runtime incorporato nativo dell'app-server Codex per i turni degli agenti OpenAI.
• /codex ... - controllo conversazione nativo di Codex.
• /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 riepiloga 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 il agentId del 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 nativo di Codex 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 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 chiaro di non supporto. Le associazioni persistono tra i riavvii del Gateway.
• Su Discord, spawnSessions controlla la creazione di thread figli per --thread auto|here - non --bind here.
• Se avvii un agente ACP diverso senza --cwd, OpenClaw eredita per impostazione predefinita il workspace dell'agente target. I percorsi ereditati mancanti (ENOENT/ENOTDIR) ricadono sul valore predefinito del backend; altri errori di accesso (ad es. 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 testo normale 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 dei thread sono abilitate per un adapter di canale:

• OpenClaw associa un thread a una sessione ACP target.
• I messaggi di follow-up in quel thread vengono instradati alla sessione ACP associata.
• L'output ACP viene riconsegnato allo stesso thread.
• Unfocus/chiusura/archiviazione/timeout di inattività o scadenza per età massima rimuove l'associazione.
• /acp close, /acp cancel, /acp status, /status e /unfocus sono comandi Gateway, non prompt per il 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'adapter di canale abilitato (predefinito: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

Il supporto alle associazioni dei thread è specifico dell'adapter. Se l'adapter del canale attivo non supporta le associazioni dei thread, OpenClaw restituisce un messaggio chiaro di non supporto/non disponibilità.

• Qualsiasi adapter di canale che esponga la capability 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 di 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 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 consegnato di nuovo allo stesso canale/thread/argomento.

Cosa OpenClaw invia 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 interna di contesto runtime di OpenClaw; gli harness ACP esterni ricevono un prompt semplice con il risultato figlio e l'istruzione. L'envelope grezza <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> non deve mai essere inviata a harness esterni né persistita come testo di trascrizione utente ACP.
• Le voci di trascrizione ACP usano il testo di trigger visibile all'utente o il prompt di completamento semplice. I metadati degli eventi interni restano strutturati in OpenClaw dove possibile e non vengono trattati come contenuto chat scritto dall'utente.

Le sessioni ACP monouso generate da un'altra esecuzione agente sono figli in background, simili ai sotto-agenti:

• Il genitore richiede lavoro con sessions_spawn({ runtime: "acp", mode: "run" }).
• Il figlio viene eseguito nella propria sessione harness ACP.
• I turni figlio vengono eseguiti sulla stessa corsia in background usata dagli spawn di sotto-agenti nativi, quindi un harness ACP lento non blocca il lavoro non correlato della sessione principale.
• I report di completamento tornano attraverso il percorso di annuncio del completamento dell'attività. OpenClaw converte i metadati di completamento interni in un prompt ACP semplice prima di inviarli a un harness esterno, quindi gli harness non vedono i marker di contesto runtime solo di OpenClaw.
• Il genitore riscrive il risultato figlio con la normale voce dell'assistente quando è utile una risposta visibile all'utente.

Non trattare questo percorso come una chat peer-to-peer tra genitore e figlio. Il figlio ha già un canale di completamento verso il genitore.

sessions_send può prendere di mira 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 consenti a richiedente e destinazione di scambiare un numero limitato di turni di follow-up.
• Chiedi alla destinazione di produrre un messaggio di annuncio.
• Consegna quell'annuncio al canale o thread visibile.

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

OpenClaw salta il follow-up A2A solo quando il richiedente è il genitore del proprio figlio ACP monouso posseduto dal genitore. In quel caso, eseguire A2A sopra il completamento dell'attività può svegliare il genitore con il risultato del figlio, inoltrare la risposta del genitore di nuovo nel figlio e creare un loop di eco genitore/figlio. Il risultato di sessions_send riporta 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 ripartire da zero. L'agente riproduce la propria cronologia di 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 programmazione che hai avviato interattivamente nella CLI, ora in modalità headless tramite il tuo agente.
• Riprendi il lavoro interrotto da un riavvio del gateway o da un timeout per inattività.

Note:

• resumeSessionId si applica solo quando runtime: "acp"; il runtime sotto-agente predefinito ignora questo campo solo ACP.
• streamTo si applica solo quando runtime: "acp"; il runtime sotto-agente predefinito ignora questo campo solo ACP.
• resumeSessionId è un ID di ripresa ACP/harness locale dell'host, non una chiave di sessione 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 di conversazione ACP upstream; thread e mode si applicano comunque 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 fanno).
• Se l'ID sessione non viene trovato, lo spawn fallisce con un errore chiaro: nessun fallback silenzioso a una nuova sessione.

Dopo un deploy del Gateway, esegui un controllo live end-to-end invece di fidarti degli 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 quell'agente di chiamare sessions_spawn con runtime: "acp", agentId: "codex", mode: "run" e il task Reply with exactly LIVE-ACP-SPAWN-OK.
4. Verifica accepted=yes, un childSessionKey reale e nessun errore del validatore.
5. Pulisci la sessione bridge temporanea.

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