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: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.
Problemi comuni al primo avvio
Problemi comuni al primo avvio
- Se
plugins.allowè impostato, costituisce un inventario restrittivo dei plugin e deve includereacpx; in caso contrario, il backend ACP installato viene intenzionalmente bloccato (/acp doctorsegnala la voce mancante nell’elenco consentito). - L’adattatore Codex ACP è incluso nel plugin
acpxe, quando possibile, viene avviato localmente. - Codex ACP viene eseguito con un
CODEX_HOMEisolato. 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_modee i campi sicurimodel_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
npxal 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.
Prerequisiti del runtime
Prerequisiti del runtime
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 doctorsegnala un backend abilitato e integro.- L’id di destinazione è consentito da
acp.allowedAgentsquando 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,droide così via). - Il modello selezionato esiste per tale ambiente: gli id dei modelli non sono trasferibili tra ambienti.
- Il
cwdrichiesto esiste ed è accessibile; in alternativa, ometticwde 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.
Destinazioni degli ambienti supportate
Con il backendacpx, 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 status4
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).Dettagli del ciclo di vita
Dettagli del ciclo di vita
- 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 ...,/statuse/unfocusnon vengono mai inviati come normale testo del prompt a un ambiente ACP associato. cancelinterrompe il turno attivo quando il backend supporta l’annullamento; non elimina l’associazione né i metadati della sessione.closetermina 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
closee 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.
Regole di instradamento native di Codex
Regole di instradamento native di Codex
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.”
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.Guida rapida alla selezione di modello / provider / runtime
Guida rapida alla selezione di modello / provider / runtime
- 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 ...oruntime: "acp"- controllo ACP/acpx esplicito.
Trigger in linguaggio naturale per l'instradamento ACP
Trigger in linguaggio naturale per l'instradamento ACP
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.”
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 plugincodex
è 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 è:- Piano di controllo delle sessioni ACP di OpenClaw.
- Plugin runtime ufficiale
@openclaw/acpx. - Adattatore ACP di Claude.
- Meccanismi di runtime/sessione sul lato Claude.
- 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:
Regole ed esclusività dei collegamenti
Regole ed esclusività dei collegamenti
--bind heree--thread ...si escludono a vicenda.--bind herefunziona 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,
spawnSessionscontrolla 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 esempioEACCES) 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/statuse/unfocusrimangono locali ogni volta che la gestione dei comandi è abilitata per quella superficie.
Sessioni collegate ai thread
Sessioni collegate ai thread
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,/statuse/unfocussono comandi del Gateway, non prompt per l’harness ACP.
acp.enabled=trueacp.dispatch.enabledè attivo per impostazione predefinita (impostafalseper sospendere l’inoltro automatico dei thread ACP; le chiamate esplicitesessions_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
- Discord:
Canali che supportano i thread
Canali che supportano i thread
- 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 vocibindings[] 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, come120363424282127706@g.us, per i gruppi. - DM/gruppo iMessage:
match.channel="imessage"+match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>". Preferiscichat_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
Usaagents.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 esempiocodexoclaude)agents.list[].runtime.acp.backendagents.list[].runtime.acp.modeagents.list[].runtime.acp.cwd
bindings[].acp.*agents.list[].runtime.acp.*- 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,
/newe/resetreimpostano 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
cwdesplicito, 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:- Da sessions_spawn
- Dal comando /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.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
- --bind here|off
- --thread auto|here|off
Note:
--bind hereè il percorso più semplice per l’operatore per «fare in modo che questo canale o questa chat usi Codex».--bind herenon crea un thread figlio.--bind hereè disponibile solo sui canali che espongono il supporto per l’associazione alla conversazione corrente.--binde--threadnon 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.Sessioni ACP interattive
Sessioni ACP interattive
Le sessioni interattive sono concepite per continuare a conversare su una superficie di chat visibile:
/acp spawn ... --bind hereassocia 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 normali messaggi successivi associati vengono inviati come testo del prompt, con gli allegati solo quando l’harness/backend li supporta.
- I comandi di gestione
/acpe 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.
Sessioni ACP a esecuzione singola gestite dal genitore
Sessioni ACP a esecuzione singola gestite dal genitore
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.
sessions_send e consegna A2A
sessions_send e consegna A2A
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.
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.Riprendere una sessione esistente
Riprendere una sessione esistente
Usa Casi d’uso comuni:
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.- 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à.
resumeSessionIdsi applica solo quandoruntime: "acp"; il runtime predefinito dei sottoagenti ignora questo campo esclusivo di ACP.streamTosi applica solo quandoruntime: "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.resumeSessionIdripristina la cronologia della conversazione ACP upstream;threademodecontinuano ad applicarsi normalmente alla nuova sessione OpenClaw che stai creando, quindimode: "session"richiede comunquethread: 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.
Test rapido successivo alla distribuzione
Test rapido successivo alla distribuzione
Dopo la distribuzione di un Gateway, esegui una verifica end-to-end dal vivo invece di affidarti
agli unit test:
- Verifica la versione e il commit del Gateway distribuito sull’host di destinazione.
- Apri una sessione bridge ACPX temporanea verso un agente attivo.
- Chiedi a tale agente di chiamare
sessions_spawnconruntime: "acp",agentId: "codex",mode: "run"e attivitàReply with exactly LIVE-ACP-SPAWN-OK. - Verifica
accepted=yes, unchildSessionKeyreale e l’assenza di errori del validatore. - Elimina la sessione bridge temporanea.
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. Limitazioni attuali:- Se la sessione richiedente è in sandbox, gli avvii ACP vengono bloccati sia per
sessions_spawn({ runtime: "acp" })sia per/acp spawn. sessions_spawnconruntime: "acp"non supportasandbox: "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:
- Argomento di destinazione esplicito (o
--sessionper/acp steer)- prova prima la chiave
- poi l’ID sessione in formato UUID
- infine l’etichetta
- Associazione al thread corrente (se questa conversazione/thread è associata a una sessione ACP).
- Ripiego sulla sessione del richiedente corrente.
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.