Agenti ACP di OpenClaw

Vuoi pilotare Claude Code o Gemini CLI da un messaggio Telegram invece che da un terminale, e OpenClaw può farlo tramite l’Agent Client Protocol. Una sessione ACP avvia il vero harness esterno come processo sull’host del Gateway, monitora ogni avvio come attività in background e può vincolare una conversazione o un thread, così i messaggi successivi continuano a raggiungere lo stesso harness. Prima serve un plugin di runtime, e un breve elenco di condizioni decide se al tuo agente verrà mai detto che questo percorso esiste.

Installare il plugin di runtime acpx

• Le installazioni pacchettizzate usano il plugin di runtime ufficiale acpx, pubblicato su npm sotto lo scope openclaw, e bastano due comandi: openclaw plugins install, indicando quel pacchetto con scope, poi openclaw config set plugins.entries.acpx.enabled true. Chi lavora da un checkout dei sorgenti può invece usare il plugin locale del workspace extensions/acpx dopo pnpm install. Esegui poi /acp doctor per un controllo di prontezza, oppure /acp install per far stampare a OpenClaw i passaggi deterministici di installazione e attivazione.
• Se plugins.allow è impostato, è un inventario restrittivo dei plugin e non un suggerimento, e deve includere acpx, altrimenti il backend ACP installato viene bloccato di proposito. È l’errore del primo avvio più spesso scambiato per un’installazione difettosa, e si presenta come l’errore secondo cui il backend di runtime ACP non è configurato; /acp doctor segnala la voce mancante nell’elenco degli autorizzati invece di lasciarti tirare a indovinare.
• Il plugin acpx incorpora direttamente il runtime ACP, quindi non c’è un binario acpx separato né una versione da configurare. Registra il backend incorporato durante l’avvio del Gateway e attende un controllo di integrità prima del segnale ready del gateway, e quel controllo fornisce anche la diagnostica degli errori. È limitato da plugins.entries.acpx.config.timeoutSeconds, che per impostazione predefinita vale 120 secondi, così gli harness più lenti come Gemini CLI riescono a completare l’avvio e l’inizializzazione ACP.
• L’adattatore ACP di Codex viene fornito con il plugin acpx e si avvia in locale quando possibile, con un CODEX_HOME isolato in cui OpenClaw copia le voci di attendibilità dei progetti fidati più la configurazione sicura di instradamento di modelli e provider, mentre autenticazione, notifiche e hook restano solo nella configurazione dell’host. Gli altri adattatori degli harness possono essere scaricati su richiesta con npx al primo utilizzo, quindi su un host senza npm o senza accesso alla rete quei download falliscono finché le cache non vengono preriscaldate o l’adattatore non viene installato in un altro modo.

Se una qualsiasi condizione non è soddisfatta, le skill ACP e le indicazioni ACP di sessions_spawn restano nascoste, così l’agente non propone un backend non disponibile.

Perché le skill ACP possono essere invisibili

Le condizioni sono elencate per intero: ACP deve essere abilitato, lo smistamento non deve essere disabilitato, la sessione corrente non deve essere bloccata dalla sandbox e un backend di runtime deve essere caricato e integro. Un agente che non ha mai proposto nemmeno una volta un avvio ACP di solito sta descrivendo con precisione la propria configurazione, non ti sta ignorando. Le due metà falliscono in modo diverso: acp.dispatch.enabled=false mette in pausa lo smistamento automatico ACP nei thread senza nascondere né bloccare una chiamata esplicita a sessions_spawn con runtime acp, mentre un richiedente in sandbox viene rifiutato senza appello perché il runtime ACP gira lato host. Da una sessione in sandbox la risposta documentata è il runtime subagent.

La checklist dei prerequisiti

• Prima di dare la colpa a OpenClaw, verifica che /acp doctor segnali un backend abilitato e integro, che l’ID di destinazione sia consentito da acp.allowedAgents quando quell’elenco degli autorizzati è impostato, e che il comando dell’harness possa davvero avviarsi sull’host del Gateway. Ognuno di questi punti ha un proprio testo di errore invece di un unico errore generico, quindi il messaggio che ricevi restringe già il campo delle cause.
• L’autenticazione del provider deve già esistere sull’host per l’harness che vuoi usare: claude, codex, gemini, opencode, droid e gli altri hanno ciascuno il proprio login. Un errore di autenticazione del fornitore significa che OpenClaw funziona e che la CLI o il provider di destinazione semplicemente non ha effettuato l’accesso, cosa che risolvi effettuando l’accesso o fornendo la chiave del provider nell’ambiente dell’host del Gateway, non modificando la configurazione di OpenClaw.
• Il modello selezionato deve esistere per quell’harness, perché gli ID dei modelli non sono portabili da un harness all’altro, e il controllo del modello dipende dalle capacità dell’adattatore: un harness che non dichiara né la capacità ACP models né un proprio flag del modello all’avvio non può essere forzato su un modello in alcun modo. La cwd richiesta deve esistere ed essere accessibile, altrimenti la ometti e lasci che il backend usi quella predefinita.

Una cosa decide la scelta prima ancora di scrivere qualsiasi configurazione: gli strumenti dei plugin di OpenClaw e gli strumenti integrati di OpenClaw non sono esposti agli harness ACP per impostazione predefinita, e i due bridge MCP che cambiano questo comportamento sono espliciti e disattivati per impostazione predefinita. Se ciò che vuoi è un’esecuzione delegata nativa di OpenClaw con gli strumenti propri di OpenClaw, quella è un’esecuzione dei sub-agent di OpenClaw, con una propria chiave di sessione e un proprio comando slash; se vuoi solo una CLI di IA locale come modello di fallback solo testo, i backend CLI di OpenClaw non sono né ACP né un runtime di harness, senza strumenti OpenClaw e senza controlli ACP.

I diciassette ID di destinazione degli harness

Con il backend acpx, questi sono gli ID da passare a /acp spawn o a sessions_spawn come agentId: claude, codex, copilot, cursor, droid, fast-agent, gemini, iflow, kilocode, kimi, kiro, mux, opencode, openclaw, qoder, qwen e trae. claude richiede l’autenticazione di Claude Code sull’host, copilot un login alla CLI o al runtime di Copilot, cursor esegue cursor-agent acp, droid richiede l’autenticazione Factory o Droid oppure FACTORY_API_KEY nell’ambiente dell’harness, gemini richiede l’autenticazione di Gemini CLI o la configurazione di una chiave API, opencode richiede l’autenticazione della CLI di OpenCode o del provider, e openclaw è il bridge del Gateway che permette a un harness compatibile con ACP di rispondere a una sessione del Gateway di OpenClaw. codex è il fallback ACP esplicito, usato solo quando il percorso nativo /codex non è disponibile o quando ACP viene richiesto per nome. Anche pi è registrato nel backend acpx, ma non è un harness di programmazione nello stesso senso. Ogni avvio finisce nelle attività in background di OpenClaw, e nelle modalità di permesso di OpenClaw si trovano le impostazioni a livello di harness accanto alle approvazioni exec di OpenClaw: una sessione ACP non ha una TTY interattiva, quindi un lavoro di programmazione con molte scritture ed esecuzioni di comandi di solito richiede un profilo in grado di procedere senza interazione.

Su Diali

Diali ospita OpenClaw per te, e ogni cliente esegue il proprio assistente invece di una porzione di uno condiviso. La configurazione del runtime viene generata dalla dashboard e sostituita a ogni rilascio, quindi le chiavi di policy vengono scritte per te invece di essere modificate a mano su una macchina che devi ricordarti di gestire. Lo stato risiede su un volume persistente, ed è questo che mantiene una sessione e la sua cronologia attraverso un aggiornamento; snapshot giornalieri e ripristino con un clic sono disponibili tramite il componente aggiuntivo Backup (incluso in Max). La pagina sull’hosting OpenClaw di Diali spiega cosa copre il runtime ospitato e la pagina dei prezzi elenca i piani.

• Due comandi installano acpx, poi /acp doctor prima di ogni altra cosa.
• Indicazioni ACP nascoste significano una condizione non soddisfatta, non una funzione mancante.
• Diciassette ID di harness, ognuno con il proprio login sull’host.