Agentes ACP de OpenClaw

Quieres manejar Claude Code o Gemini CLI desde un mensaje de Telegram en lugar de desde una terminal, y OpenClaw puede hacerlo mediante el Agent Client Protocol. Una sesión ACP lanza el arnés externo real como un proceso en el host del Gateway, sigue cada lanzamiento como una tarea en segundo plano y puede vincular una conversación o un hilo para que los mensajes siguientes sigan llegando al mismo arnés. Primero necesita un plugin de entorno de ejecución, y una breve lista de condiciones decide si a tu agente se le llega a decir que esa vía existe.

Instalar el plugin de entorno de ejecución acpx

• Las instalaciones empaquetadas usan el plugin oficial de entorno de ejecución acpx, publicado bajo el scope openclaw en npm, y son dos comandos: openclaw plugins install, indicando ese paquete con scope, y después openclaw config set plugins.entries.acpx.enabled true. Las copias del código fuente pueden usar en su lugar el plugin local del espacio de trabajo extensions/acpx después de pnpm install. Ejecuta /acp doctor a continuación para comprobar que todo está listo, o /acp install para que OpenClaw muestre los pasos deterministas de instalación y activación.
• Si plugins.allow está definido, es un inventario restrictivo de plugins y no una sugerencia, y debe incluir acpx o el backend ACP instalado queda bloqueado intencionadamente. Es el fallo de primera ejecución que más a menudo se confunde con una instalación rota, y aparece como el error que dice que el backend del entorno de ejecución ACP no está configurado; /acp doctor informa de la entrada que falta en la lista de permitidos en lugar de dejarte adivinar.
• El plugin acpx integra directamente el entorno de ejecución ACP, así que no hay un binario acpx aparte ni una versión que configurar. Registra el backend integrado durante el arranque del Gateway y espera a una sonda de salud antes de la señal ready del gateway, y esa sonda también aporta los diagnósticos de fallo. Está limitada por plugins.entries.acpx.config.timeoutSeconds, cuyo valor predeterminado es 120 segundos para que arneses más lentos como Gemini CLI puedan terminar el arranque y la inicialización de ACP.
• El adaptador ACP de Codex viene con el plugin acpx y se inicia localmente cuando es posible, con un CODEX_HOME aislado en el que OpenClaw copia las entradas de confianza de los proyectos marcados como confiables, además de una configuración segura de enrutamiento de modelos y proveedores, mientras que la autenticación, las notificaciones y los hooks permanecen solo en la configuración del host. Otros adaptadores de arnés pueden descargarse bajo demanda con npx en el primer uso, así que en un host sin npm o sin acceso a la red esas descargas fallan hasta que las cachés se precalientan o el adaptador se instala de otra forma.

Si alguna condición falla, las skills de ACP y las indicaciones de ACP de sessions_spawn permanecen ocultas para que el agente no sugiera un backend no disponible.

Por qué las skills de ACP pueden ser invisibles

Las condiciones están enumeradas por completo: ACP debe estar activado, el despacho no debe estar desactivado, la sesión actual no debe estar bloqueada por el entorno aislado y debe haber un backend de ejecución cargado y en buen estado. Un agente que nunca te ha ofrecido un lanzamiento ACP suele estar informando con precisión de su propia configuración, no ignorándote. Las dos mitades fallan de forma distinta: acp.dispatch.enabled=false pausa el despacho automático de hilos ACP sin ocultar ni bloquear una llamada explícita a sessions_spawn con runtime acp, mientras que un solicitante en entorno aislado se rechaza directamente porque el entorno de ejecución ACP funciona del lado del host. Desde una sesión en entorno aislado, la respuesta documentada es el runtime subagent.

La lista de requisitos previos

• Antes de culpar a OpenClaw, confirma que /acp doctor informa de un backend activado y en buen estado, que el identificador de destino está permitido por acp.allowedAgents cuando esa lista de permitidos está definida, y que el comando del arnés puede arrancar de verdad en el host del Gateway. Cada una de esas comprobaciones tiene su propio texto de error en lugar de un fallo genérico, así que el mensaje que recibes ya acota la causa.
• La autenticación del proveedor debe existir ya en el host para el arnés al que apuntas: claude, codex, gemini, opencode, droid y el resto tienen cada uno su propio inicio de sesión. Un error de autenticación del proveedor significa que OpenClaw está en buen estado y que la CLI o el proveedor de destino simplemente no tiene la sesión iniciada, lo que se soluciona iniciando sesión o proporcionando la clave del proveedor en el entorno del host del Gateway, no editando la configuración de OpenClaw.
• El modelo seleccionado debe existir para ese arnés, porque los identificadores de modelo no son portables entre arneses, y el control del modelo depende de las capacidades del adaptador: un arnés que no anuncia ni la capacidad models de ACP ni su propio flag de modelo de arranque no se puede forzar a usar ningún modelo. El cwd solicitado debe existir y ser accesible, o bien lo omites y dejas que el backend use su valor predeterminado.

Hay algo que decide la elección antes de escribir ninguna configuración: las herramientas de plugins de OpenClaw y las herramientas integradas de OpenClaw no se exponen a los arneses ACP de forma predeterminada, y los dos puentes MCP que cambian eso son explícitos y están desactivados por defecto. Si lo que quieres es una ejecución delegada nativa de OpenClaw con las propias herramientas de OpenClaw, eso es una ejecución de subagentes de OpenClaw, con su propia clave de sesión y su propio comando de barra; si solo quieres una CLI de IA local como modelo de respaldo de solo texto, los backends de CLI de OpenClaw no son ni ACP ni un entorno de ejecución de arneses, sin herramientas de OpenClaw y sin controles ACP.

Los diecisiete identificadores de destino de los arneses

Con el backend acpx, estos son los identificadores que pasas a /acp spawn o a sessions_spawn como agentId: claude, codex, copilot, cursor, droid, fast-agent, gemini, iflow, kilocode, kimi, kiro, mux, opencode, openclaw, qoder, qwen y trae. claude necesita la autenticación de Claude Code en el host, copilot un inicio de sesión en la CLI o el entorno de ejecución de Copilot, cursor ejecuta cursor-agent acp, droid necesita autenticación de Factory o Droid, o FACTORY_API_KEY en el entorno del arnés, gemini necesita autenticación de Gemini CLI o configurar una clave de API, opencode necesita autenticación de OpenCode CLI o del proveedor, y openclaw es el puente del Gateway que permite a un arnés compatible con ACP responder a una sesión del Gateway de OpenClaw. codex es el respaldo ACP explícito, que solo se usa cuando la vía nativa /codex no está disponible o cuando se pide ACP por su nombre. pi también está registrado en el backend acpx, pero no es un arnés de programación en el mismo sentido. Cada lanzamiento aparece en las tareas en segundo plano de OpenClaw, y en los modos de permiso de OpenClaw es donde se sitúan los ajustes a nivel de arnés junto a las aprobaciones de ejecución de OpenClaw: una sesión ACP no tiene TTY interactivo, así que la programación con mucha escritura y ejecución de comandos suele necesitar un perfil que pueda avanzar sin interacción.

En Diali

Diali aloja OpenClaw por ti, y cada cliente ejecuta su propio asistente en lugar de una parte de uno compartido. La configuración del entorno de ejecución se genera desde el panel y se reemplaza en cada versión, así que las claves de política se escriben por ti en lugar de editarse a mano en una máquina que tienes que recordar. El estado vive en un volumen persistente, que es lo que conserva una sesión y su historial tras una actualización; las instantáneas diarias y la restauración con un clic están disponibles con el complemento Copias de seguridad (incluido en Max). OpenClaw alojado en Diali detalla lo que cubre el entorno de ejecución alojado y la página de precios de Diali recoge los planes.

• Dos comandos instalan acpx; después, /acp doctor antes que nada.
• Unas indicaciones ACP ocultas significan una condición fallida, no una función ausente.
• Diecisiete identificadores de arnés, cada uno con su propio inicio de sesión en el host.