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 mancante nella allowlist.
• L’adapter ACP di Codex è fornito con il plugin acpx e avviato localmente quando possibile.
• Altri adapter harness di destinazione possono comunque essere scaricati su richiesta con npx la prima volta che li usi.
• L’autenticazione del vendor deve comunque esistere sull’host per quell’harness.
• Se l’host non ha npm o accesso alla rete, i download degli adapter al primo avvio falliscono finché le cache non vengono pre-riscaldate 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, recapito, associazioni e policy; l’harness possiede il login del provider, il catalogo modelli, il comportamento del filesystem e gli strumenti nativi.

Prima di dare la colpa a OpenClaw, verifica:

• /acp doctor segnala un backend abilitato e integro.
• L’id di destinazione è consentito da acp.allowedAgents quando quella allowlist è impostata.
• Il comando harness può avviarsi sull’host Gateway.
• L’autenticazione del provider è presente per quell’harness (claude, codex, gemini, opencode, droid, ecc.).
• Il modello selezionato esiste per quell’harness - gli id dei modelli non sono portabili tra harness.
• Il cwd richiesto esiste ed è accessibile, oppure ometti cwd e lascia che il backend usi il suo valore predefinito.
• La modalità di autorizzazione corrisponde al lavoro. Le sessioni non interattive non possono fare clic sui prompt di autorizzazione nativi, quindi le esecuzioni di coding con molte scritture/esecuzioni di solito richiedono un profilo di autorizzazione ACPX che possa procedere senza interazione.

• L’avvio crea o riprende una sessione runtime ACP, registra metadati ACP nello store delle 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 recapito tra superfici passano dal notificatore dell’attività parent invece di comportarsi come una normale sessione chat rivolta all’utente.
• La manutenzione delle attività chiude sessioni ACP one-shot terminali o orfane possedute dal parent. Le sessioni ACP persistenti sono conservate finché rimane un’associazione attiva alla conversazione; le sessioni persistenti obsolete senza associazione attiva vengono chiuse così non possono essere riprese silenziosamente dopo che l’attività proprietaria è terminata o il suo record attività è scomparso.
• 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 di prompt a un harness 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 harness può comunque mantenere la propria cronologia upstream se supporta il resume.
• I worker runtime inattivi possono essere ripuliti dopo acp.runtime.ttlMinutes; i metadati di sessione memorizzati restano disponibili per /acp sessions.

Trigger in linguaggio naturale che dovrebbero instradare 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 di conversazioni Codex native è il percorso di controllo chat predefinito. Gli strumenti dinamici OpenClaw vengono comunque eseguiti tramite OpenClaw, mentre gli strumenti nativi Codex come shell/apply-patch vengono eseguiti dentro Codex. Per gli eventi degli strumenti nativi Codex, OpenClaw inietta un relay 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 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 deliberatamente conservativo: non modifica gli argomenti degli strumenti nativi Codex né riscrive i record dei thread Codex. Usa ACP esplicito solo quando vuoi il modello runtime/sessione ACP. Il confine di supporto Codex incorporato è documentato nel contratto di supporto harness Codex v1.

• openai-codex/* - route OAuth/abbonamento PI Codex.
• openai/* più agentRuntime.id: "codex" - runtime incorporato nativo dell'app-server Codex.
• /codex ... - controllo nativo della conversazione Codex.
• /acp ... o runtime: "acp" - controllo ACP/acpx esplicito.

Trigger che devono instradare al runtime ACP:

• "Esegui questo come sessione ACP Claude Code 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'harness agentId, 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" }). Ha come destinazione 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 di sottoagente predefinito. 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 l'associazione alla conversazione corrente; altrimenti OpenClaw restituisce un chiaro messaggio di non supportato. 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 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 al 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 ... vengono 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 adapter 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 riconsegnato allo stesso thread.
• Unfocus/chiusura/archiviazione/timeout per inattività o 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 (impostalo a false per mettere in pausa il dispatch automatico dei thread ACP; le chiamate esplicite sessions_spawn({ runtime: "acp" }) continuano a funzionare).
• Spawn di sessioni thread dell'adapter di canale abilitati (predefinito: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

Il supporto dell'associazione di thread è specifico dell'adapter. Se l'adapter del canale attivo non supporta le associazioni di thread, OpenClaw restituisce un chiaro messaggio di non supportato/non disponibile.

• Qualsiasi adapter di canale che espone la capacità di associazione sessione/thread.
• Supporto integrato corrente: 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 associa la conversazione corrente alla sessione ACP.
• /acp spawn ... --thread ... associa un thread/topic del canale alla sessione ACP.
• Le bindings[].type="acp" persistenti configurate 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 recapitato di nuovo allo stesso canale/thread/topic.

Cosa invia OpenClaw all'harness:

• I normali follow-up associati vengono inviati come testo del prompt, più allegati solo quando l'harness/backend li supporta.
• I comandi di gestione /acp e i comandi locali del Gateway vengono intercettati prima del dispatch ACP.
• Gli eventi di completamento generati dal runtime vengono materializzati per destinazione. Gli agenti OpenClaw ricevono l'envelope di contesto runtime interno 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 dovrebbe mai essere inviata agli harness esterni o persistita come testo di trascrizione utente ACP.
• Le voci della trascrizione ACP usano il testo trigger visibile all'utente o il prompt di completamento semplice. I metadati evento interni restano strutturati in OpenClaw dove possibile e non vengono trattati come contenuto chat scritto dall'utente.

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

• Il genitore richiede il lavoro con sessions_spawn({ runtime: "acp", mode: "run" }).
• Il figlio viene eseguito nella propria sessione harness ACP.
• I turni figli vengono eseguiti sulla stessa corsia in background usata dagli spawn nativi dei sotto-agenti, quindi un harness ACP lento non blocca il lavoro non correlato della sessione principale.
• Il completamento viene riportato tramite il percorso di annuncio di completamento attività. OpenClaw converte i metadati di completamento interni in un prompt ACP semplice prima di inviarlo a un harness esterno, quindi gli harness non vedono marker di contesto runtime solo OpenClaw.
• Il genitore riscrive il risultato del figlio con la normale voce dell'assistente quando è utile una risposta rivolta 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ò scegliere come destinazione 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.
• Consegna quell'annuncio al canale o thread visibile.

Quel percorso A2A è un fallback per 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 tools.sessions.visibility ampie.

OpenClaw salta il follow-up A2A solo quando il richiedente è il genitore del proprio figlio ACP monouso di proprietà del genitore. In quel caso, eseguire A2A sopra il completamento attività può risvegliare il genitore con il risultato del figlio, inoltrare la risposta del genitore di nuovo nel figlio e creare un ciclo 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 iniziarne una nuova. 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:

• Passare una sessione Codex dal laptop al telefono: chiedi al tuo agente di riprendere da dove avevi lasciato.
• Continuare una sessione di coding avviata interattivamente nella CLI, ora in modalità headless 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 sotto-agenti ignora questo campo solo ACP.
• streamTo si applica solo quando runtime: "acp"; il runtime predefinito dei sotto-agenti ignora questo campo solo ACP.
• resumeSessionId è un ID di ripresa ACP/harness locale all'host, non una chiave di sessione di canale OpenClaw; OpenClaw controlla comunque i criteri di spawn ACP e i criteri 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 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 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 childSessionKey reale e nessun errore di validazione.
5. Pulisci la sessione bridge temporanea.

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