Si ha ejecutado agentes de IA contra infraestructura real — despliegues de Azure, planes de Terraform, aprovisionamiento de red — se ha topado con el muro. Su agente lanza un comando CLI de larga duración, y todo el bucle principal se queda en silencio. Sin respuestas, sin actualizaciones de estado, sin forma de cancelar. Solo silencio hasta que esa llamada de red decide regresar. O no.
Este es el problema de confiabilidad más grande en los flujos de trabajo de agentes de IA en producción, y es por eso que he estado impulsando fuertemente el Agent Client Protocol (ACP) dentro de OpenClaw. ACP no hace que las operaciones lentas sean mágicamente rápidas. Lo que hace es aislarlas para que no puedan derribar a su agente con ellas.
Aquí está cómo funciona y cómo configurarlo.
Qué es Realmente ACP
El Agent Client Protocol es un estándar para hacer que los agentes de codificación sean interoperables entre diferentes clientes — IDEs, editores, orquestadores, lo que sea. En esencia, estandariza la comunicación entre una aplicación anfitriona y los agentes de codificación usando JSON-RPC sobre stdio. Los agentes locales se lanzan como subprocesos y se comunican a través de ese canal.
Esa es la descripción a nivel de especificación. Esto es lo que importa para nosotros: ACP le da a OpenClaw una forma de ejecutar plataformas de codificación externas — Claude Code, Codex, Gemini CLI — como procesos hijos supervisados en lugar de hacer todo en línea en el bucle principal del agente.
OpenClaw usa ACP en dos direcciones:
- Sesiones ACP dentro de OpenClaw — Ejecute plataformas externas a través del plugin de backend
acpx. OpenClaw supervisa el proceso, gestiona su ciclo de vida y puede matarlo si las cosas se desvían. - El puente ACP de OpenClaw (
openclaw acp) — Un comando CLI que habla ACP sobre stdio para que los IDEs puedan reenviar prompts a una sesión de Gateway de OpenClaw.
Para este artículo, nos importa el primero.
El Problema Central: Su Bucle de Agente es de un Solo Subproceso
Aquí está el modo de fallo que veo constantemente en producción. El turno del agente principal de OpenClaw invoca directamente una llamada de red de Azure de larga duración — por ejemplo, aprovisionando un emparejamiento de VNet o esperando un Terraform apply. Ese bucle de agente está serializado. Una operación a la vez. Mientras espera que esa API de Azure responda, el agente completo no responde.
Sin respuestas de chat. Sin capacidad de verificar otro trabajo. Sin botón de cancelar. Si esa llamada API se cuelga por 10 minutos, su agente se cuelga por 10 minutos. Si se cuelga para siempre — y las llamadas de red de Azure absolutamente pueden — su agente se cuelga para siempre.
La tentación es simplemente aumentar los tiempos de espera. Eso no es una solución; es una oración con fecha límite.
Cómo ACP Soluciona Esto
Cuando la gente dice “ACP evita que OpenClaw se cuelgue”, lo que quieren decir es: ejecute el trabajo riesgoso, lento y propenso a fallos en un proceso de plataforma externa que OpenClaw supervisa, en lugar de hacerlo en línea.
El backend acpx genera trabajo en procesos hijos supervisados. El runtime maneja el transporte, la cola, la cancelación y la reconexión. Incluso si Claude Code se queda atascado esperando una llamada de Azure que nunca regresará, ese trabajo atascado vive en un proceso diferente. El bucle principal de OpenClaw se mantiene responsivo. Puede:
- Cancelar la sesión atascada
- Cerrarla y dejar que el recolector TTL la limpie
- Generar una nueva sesión para hacer otra cosa
- Seguir chateando con el agente mientras el trabajo en segundo plano se ejecuta
Esto es aislamiento de procesos aplicado a la orquestación de agentes de IA. No es ciencia de la computación novedosa — es la misma razón por la que no ejecutamos servidores web como bucles de eventos de un solo subproceso sin procesos workers. Pero está sorprendentemente ausente en la mayoría de los frameworks de agentes.
Configurándolo
Prerrequisitos
Claude Code debe estar instalado de forma independiente. En Windows, use el script de instalación de PowerShell; en Linux/macOS, use curl. La primera ejecución le pedirá autenticación — resuelva eso antes de intentar conectarlo a ACP.
Instalar el Plugin acpx
openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true
Verifique que todo esté conectado:
/acp doctor
Esto ejecuta una verificación de salud del backend. Si falla, generalmente se trata de una instalación faltante de Claude Code o un problema de autenticación.
Configurar ACP
Los campos clave de configuración:
openclaw config set acp.enabled true
openclaw config set acp.backend "acpx"
openclaw config set acp.defaultAgent "claude-code"
openclaw config set acp.maxConcurrentSessions 8
También puede establecer acp.allowedAgents para restringir qué plataformas están disponibles, y runtime.ttlMinutes para recolectar automáticamente sesiones que sobreviven su utilidad.
Manejar Permisos (Esto le Afectará)
Las sesiones ACP se ejecutan de forma no interactiva — no hay TTY. Esto significa que el modelo de permisos predeterminado (aprobar lecturas, fallar en escrituras) lanzará AcpRuntimeError en el momento en que la plataforma intente escribir un archivo o ejecutar un comando.
Necesita configurar permissionMode y nonInteractivePermissions para que coincidan con su postura de seguridad. Para automatización de infraestructura, típicamente necesitará permisos de escritura y ejecución habilitados. Sea deliberado sobre esto — las sesiones ACP se ejecutan en el runtime del anfitrión, no en un sandbox.
Uso Diario
Comandos Slash
El flujo de trabajo del operador es directo:
/acp spawn— Iniciar una nueva sesión ACP/acp status— Verificar sesiones en ejecución/acp timeout <seconds>— Establecer tiempo de espera de sesión/acp steer— Enviar instrucciones adicionales a una sesión en ejecución/acp cancel— Matar una sesión atascada/acp close— Cierre limpio
Generación Programática
Para flujos de trabajo automatizados, use sessions_spawn con runtime: "acp". El parámetro agentId selecciona qué plataforma usar, y mode puede ser run (de un solo uso, ejecutar y devolver) o session (persistente, mantiene la plataforma activa para trabajo de seguimiento).
La vinculación de hilos también funciona — los hilos de Discord y los temas de foro de Telegram pueden vincularse a sesiones ACP específicas, para que su equipo tenga contextos de conversación aislados por tarea.
Patrones No Bloqueantes
Las sesiones ACP son una herramienta en un conjunto más amplio. Aquí están los cuatro patrones que uso para mantener los flujos de trabajo de agentes responsivos:
Opción A: Ejecución en Segundo Plano. La herramienta exec soporta un parámetro timeout (por defecto 1800 segundos) y ejecución en segundo plano automática mediante yieldMs. Lance un comando, déjelo en segundo plano después de unos segundos y consulte los resultados. Simple, efectivo para operaciones de duración conocida.
Opción B: Sesiones ACP. Para trabajo complejo de múltiples pasos que podría implicar uso de herramientas, operaciones de archivos y toma de decisiones — no solo un comando shell único — las sesiones ACP le dan aislamiento completo de la plataforma. La plataforma puede pensar, actuar y quedarse atascada sin afectar el bucle principal.
Opción C: Reconciliación por Cron. Configure trabajos cron de OpenClaw para verificar periódicamente el estado de la infraestructura. En lugar de esperar a que un despliegue se complete, programe una verificación de reconciliación cada pocos minutos. El agente se despierta, verifica el estado y actúa o vuelve a dormir.
Opción D: Webhooks. Para flujos de trabajo basados en eventos, use cron externo o callbacks de infraestructura que lleguen al endpoint de webhook de OpenClaw (/hooks/agent). Cuando su Terraform apply se complete o su despliegue de Azure finalice, dispare un webhook para despertar al agente. Sin sondeos, sin bloqueos.
En la práctica, combino los cuatro. Sesiones ACP para el trabajo pesado, ejecución en segundo plano para comandos rápidos, cron para reconciliación y webhooks para notificación de cambios de estado.
Solución de Problemas
Fallos de Permisos
Si ve AcpRuntimeError inmediatamente después de generar una sesión, casi siempre son los valores predeterminados de permisos no interactivos. Verifique su configuración de permissionMode y nonInteractivePermissions.
Sesiones Zombie
Las sesiones que completan su trabajo pero no se cierran correctamente consumirán sus espacios de concurrencia. Monitoree con /acp status y establezca runtime.ttlMinutes para recolectar automáticamente sesiones obsoletas. Si está alcanzando los límites de acp.maxConcurrentSessions, verifique primero si hay zombies.
Distinguir Tipos de Bloqueos
No todos los bloqueos son iguales, y la solución depende del tipo que esté enfrentando:
- Bucle principal bloqueado en shell — El agente en sí está atascado esperando una llamada exec en línea. Este es el problema que resuelve ACP. Mueva el trabajo a una sesión.
- Sesión ACP estancada después de completarse — La plataforma terminó pero la sesión no se cerró limpiamente. Use
/acp closeo deje que TTL lo maneje. - Plataforma genuinamente colgada en red — Claude Code en sí está atascado esperando una API externa. Use
/acp cancelpara matar la sesión, luego investigue el problema de red subyacente.
Instalación y Autenticación de Claude Code
Esto atrapa a la gente más seguido de lo que piensa. Claude Code es una dependencia real — si no está instalado, no autenticado o el token de autenticación expiró, las sesiones ACP fallarán al generarse. Ejecute /acp doctor primero. Siempre.
Consideraciones de Seguridad
Las sesiones ACP se ejecutan en el runtime del anfitrión, no en un sandbox. Esto es por diseño — necesitan acceso a sus herramientas de infraestructura reales. Pero significa que necesita pensar en los límites de seguridad.
Para webhooks, mantenga los endpoints en loopback o detrás de un proxy Tailnet. Use tokens dedicados para la autenticación de webhooks, y restrinja el enrutamiento de agentes y sesiones para que los llamadores externos no puedan generar trabajo arbitrario.
Conclusión
Los bloqueos de agentes no son una molestia menor — son un problema de confiabilidad que hace que la automatización de IA no sea confiable para el trabajo de infraestructura en producción. ACP le da aislamiento de procesos, control de ciclo de vida y gestión de tiempos de espera para las operaciones con más probabilidades de bloquearse.
No es complicado de configurar. No es magia. Es una buena práctica de ingeniería aplicada a la orquestación de agentes: no permita que una operación lenta derribe todo su sistema.
Si está construyendo flujos de trabajo de agentes de IA para automatización de infraestructura y se encuentra con problemas de confiabilidad, hablemos. Este es exactamente el tipo de trabajo de endurecimiento de producción que hacemos en Big Hat Group.