Agentes ACP

• Si plugins.allow está definido, es un inventario restrictivo de plugins y debe incluir acpx; de lo contrario, el backend ACP instalado queda bloqueado intencionadamente y /acp doctor informa de la entrada faltante en la lista de permitidos.
• El adaptador ACP de Codex se prepara con el Plugin acpx y se inicia localmente cuando es posible.
• Codex ACP se ejecuta con un CODEX_HOME aislado; OpenClaw copia solo las entradas de proyecto confiables desde la configuración de Codex del host y confía en el espacio de trabajo activo, dejando la autenticación, las notificaciones y los hooks en la configuración del host.
• Otros adaptadores de arnés de destino aún pueden obtenerse bajo demanda con npx la primera vez que los uses.
• La autenticación del proveedor aún debe existir en el host para ese arnés.
• Si el host no tiene npm ni acceso a la red, las obtenciones de adaptadores en la primera ejecución fallan hasta que las cachés se preparen previamente o el adaptador se instale de otra manera.

ACP inicia un proceso real de arnés externo. OpenClaw es propietario del enrutamiento, el estado de las tareas en segundo plano, la entrega, las vinculaciones y la política; el arnés es propietario de su inicio de sesión del proveedor, catálogo de modelos, comportamiento del sistema de archivos y herramientas nativas.

Antes de culpar a OpenClaw, verifica:

• /acp doctor informa de un backend habilitado y saludable.
• El id de destino está permitido por acp.allowedAgents cuando esa lista de permitidos está definida.
• El comando del arnés puede iniciarse en el host del Gateway.
• La autenticación del proveedor está presente para ese arnés (claude, codex, gemini, opencode, droid, etc.).
• El modelo seleccionado existe para ese arnés; los ids de modelo no son portables entre arneses.
• El cwd solicitado existe y es accesible, o se omite cwd y se deja que el backend use su valor predeterminado.
• El modo de permisos coincide con el trabajo. Las sesiones no interactivas no pueden hacer clic en prompts de permisos nativos, por lo que las ejecuciones de codificación con muchas escrituras/ejecuciones normalmente necesitan un perfil de permisos ACPX que pueda continuar sin intervención.

• La creación crea o reanuda una sesión de entorno de ejecución ACP, registra metadatos ACP en el almacén de sesiones de OpenClaw y puede crear una tarea en segundo plano cuando la ejecución pertenece al padre.
• Las sesiones ACP pertenecientes al padre se tratan como trabajo en segundo plano incluso cuando la sesión de entorno de ejecución es persistente; la finalización y la entrega entre superficies pasan por el notificador de tareas padre en lugar de actuar como una sesión de chat normal visible para el usuario.
• El mantenimiento de tareas cierra sesiones ACP puntuales terminales o huérfanas pertenecientes al padre. Las sesiones ACP persistentes se conservan mientras quede una vinculación de conversación activa; las sesiones persistentes obsoletas sin una vinculación activa se cierran para que no puedan reanudarse silenciosamente después de que la tarea propietaria haya terminado o su registro de tarea haya desaparecido.
• Los mensajes de seguimiento vinculados van directamente a la sesión ACP hasta que la vinculación se cierre, pierda el foco, se restablezca o caduque.
• Los comandos del Gateway permanecen locales. /acp ..., /status y /unfocus nunca se envían como texto normal de prompt a un arnés ACP vinculado.
• cancel aborta el turno activo cuando el backend admite cancelación; no elimina la vinculación ni los metadatos de sesión.
• close finaliza la sesión ACP desde el punto de vista de OpenClaw y elimina la vinculación. Un arnés aún puede conservar su propio historial ascendente si admite reanudación.
• El Plugin acpx limpia los árboles de procesos de envoltorio y adaptador propiedad de OpenClaw después de close, y recolecta huérfanos ACPX obsoletos propiedad de OpenClaw durante el inicio del Gateway.
• Los workers de entorno de ejecución inactivos son aptos para limpieza después de acp.runtime.ttlMinutes; los metadatos de sesión almacenados siguen disponibles para /acp sessions.

Disparadores en lenguaje natural que deben enrutarse al Plugin nativo de Codex cuando está habilitado:

• "Vincula este canal de Discord a Codex."
• "Adjunta este chat al hilo de Codex <id>."
• "Muestra los hilos de Codex y luego vincula este."

La vinculación nativa de conversaciones de Codex es la ruta predeterminada de control del chat. Las herramientas dinámicas de OpenClaw siguen ejecutándose a través de OpenClaw, mientras que las herramientas nativas de Codex, como shell/apply-patch, se ejecutan dentro de Codex. Para los eventos de herramientas nativas de Codex, OpenClaw inyecta un reenvío nativo de ganchos por turno para que los ganchos de plugins puedan bloquear before_tool_call, observar after_tool_call y enrutar los eventos PermissionRequest de Codex mediante las aprobaciones de OpenClaw. Los ganchos Stop de Codex se reenvían a before_agent_finalize de OpenClaw, donde los plugins pueden solicitar una pasada más del modelo antes de que Codex finalice su respuesta. El reenvío sigue siendo deliberadamente conservador: no muta los argumentos de herramientas nativas de Codex ni reescribe los registros de hilos de Codex. Usa ACP explícito solo cuando quieras el modelo de entorno de ejecución/sesión de ACP. El límite de soporte de Codex integrado está documentado en el contrato de soporte v1 del arnés de Codex.

• openai-codex/* - ruta heredada de modelo OAuth/suscripción de Codex reparada por doctor.
• openai/* - entorno de ejecución integrado en el servidor de aplicación nativo de Codex para turnos de agente de OpenAI.
• /codex ... - control nativo de conversación de Codex.
• /acp ... o runtime: "acp" - control explícito de ACP/acpx.

Activadores que deben enrutarse al entorno de ejecución ACP:

• "Ejecuta esto como una sesión ACP de Claude Code de una sola ejecución y resume el resultado."
• "Usa Gemini CLI para esta tarea en un hilo y luego mantén los mensajes de seguimiento en ese mismo hilo."
• "Ejecuta Codex mediante ACP en un hilo en segundo plano."

OpenClaw selecciona runtime: "acp", resuelve el agentId del arnés, se vincula a la conversación o el hilo actuales cuando sea compatible, y enruta los mensajes de seguimiento a esa sesión hasta su cierre/expiración. Codex solo sigue esta ruta cuando ACP/acpx es explícito o el Plugin nativo de Codex no está disponible para la operación solicitada.

Para sessions_spawn, runtime: "acp" se anuncia solo cuando ACP está habilitado, el solicitante no está aislado, y hay cargado un backend de entorno de ejecución ACP. acp.dispatch.enabled=false pausa el despacho automático de hilos ACP, pero no oculta ni bloquea las llamadas explícitas a sessions_spawn({ runtime: "acp" }). Tiene como destino ids de arnés ACP como codex, claude, droid, gemini u opencode. No pases un id de agente normal de configuración de OpenClaw desde agents_list a menos que esa entrada esté configurada explícitamente con agents.list[].runtime.type="acp"; de lo contrario, usa el entorno de ejecución de sub-agente predeterminado. Cuando un agente de OpenClaw está configurado con runtime.type="acp", OpenClaw usa runtime.acp.agent como id del arnés subyacente.

• --bind here y --thread ... son mutuamente excluyentes.
• --bind here solo funciona en canales que anuncian vinculación de conversación actual; OpenClaw devuelve un mensaje claro de no compatibilidad en caso contrario. Las vinculaciones persisten entre reinicios del Gateway.
• En Discord, spawnSessions condiciona la creación de hilos secundarios para --thread auto|here - no para --bind here.
• Si creas una sesión en un agente ACP diferente sin --cwd, OpenClaw hereda el espacio de trabajo del agente de destino de forma predeterminada. Las rutas heredadas faltantes (ENOENT/ENOTDIR) recurren al valor predeterminado del backend; otros errores de acceso (p. ej. EACCES) se exponen como errores de creación.
• Los comandos de gestión del Gateway permanecen locales en conversaciones vinculadas - OpenClaw gestiona los comandos /acp ... incluso cuando el texto normal de seguimiento se enruta a la sesión ACP vinculada; /status y /unfocus también permanecen locales siempre que la gestión de comandos esté habilitada para esa superficie.

Cuando las vinculaciones de hilos están habilitadas para un adaptador de canal:

• OpenClaw vincula un hilo a una sesión ACP de destino.
• Los mensajes de seguimiento en ese hilo se enrutan a la sesión ACP vinculada.
• La salida de ACP se entrega de vuelta al mismo hilo.
• Quitar foco/cerrar/archivar/tiempo de espera por inactividad o expiración por edad máxima elimina la vinculación.
• /acp close, /acp cancel, /acp status, /status y /unfocus son comandos de Gateway, no instrucciones para el arnés ACP.

Marcas de función requeridas para ACP vinculado a hilos:

• acp.enabled=true
• acp.dispatch.enabled está activado de forma predeterminada (configúralo en false para pausar el despacho automático de hilos ACP; las llamadas explícitas a sessions_spawn({ runtime: "acp" }) siguen funcionando).
• Creación de sesiones de hilo del adaptador de canal habilitada (valor predeterminado: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

La compatibilidad con vinculación de hilos es específica de cada adaptador. Si el adaptador de canal activo no admite vinculaciones de hilos, OpenClaw devuelve un mensaje claro de no compatibilidad/no disponibilidad.

• Cualquier adaptador de canal que exponga la capacidad de vinculación de sesión/hilo.
• Compatibilidad integrada actual: hilos/canales de Discord, temas de Telegram (temas de foro en grupos/supergrupos y temas de mensajes directos).
• Los canales de plugins pueden agregar compatibilidad mediante la misma interfaz de vinculación.

Las sesiones interactivas están pensadas para seguir conversando en una superficie de chat visible:

• /acp spawn ... --bind here vincula la conversación actual a la sesión ACP.
• /acp spawn ... --thread ... vincula un hilo/tema de canal a la sesión ACP.
• Los bindings[].type="acp" configurados de forma persistente enrutan las conversaciones coincidentes a la misma sesión ACP.

Los mensajes posteriores en la conversación vinculada se enrutan directamente a la sesión ACP, y la salida ACP se entrega de vuelta a ese mismo canal/hilo/tema.

Lo que OpenClaw envía al harness:

• Los seguimientos vinculados normales se envían como texto de prompt, además de adjuntos solo cuando el harness/backend los admite.
• Los comandos de gestión /acp y los comandos locales del Gateway se interceptan antes del envío ACP.
• Los eventos de finalización generados en tiempo de ejecución se materializan por destino. Los agentes de OpenClaw reciben el sobre de contexto de tiempo de ejecución interno de OpenClaw; los harnesses ACP externos reciben un prompt simple con el resultado hijo y la instrucción. El sobre bruto <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> nunca debe enviarse a harnesses externos ni persistirse como texto de transcripción de usuario ACP.
• Las entradas de transcripción ACP usan el texto de disparador visible para el usuario o el prompt de finalización simple. Los metadatos internos de eventos permanecen estructurados en OpenClaw cuando es posible y no se tratan como contenido de chat escrito por el usuario.

Las sesiones ACP de una sola ejecución creadas por otra ejecución de agente son hijos en segundo plano, similares a los subagentes:

• El padre solicita trabajo con sessions_spawn({ runtime: "acp", mode: "run" }).
• El hijo se ejecuta en su propia sesión de harness ACP.
• Los turnos hijos se ejecutan en el mismo carril en segundo plano usado por las creaciones de subagentes nativos, por lo que un harness ACP lento no bloquea el trabajo no relacionado de la sesión principal.
• La finalización informa de vuelta mediante la ruta de anuncio de finalización de tarea. OpenClaw convierte los metadatos internos de finalización en un prompt ACP simple antes de enviarlos a un harness externo, por lo que los harnesses no ven marcadores de contexto de tiempo de ejecución exclusivos de OpenClaw.
• El padre reescribe el resultado hijo en una voz normal de asistente cuando una respuesta visible para el usuario es útil.

No trates esta ruta como un chat peer-to-peer entre padre e hijo. El hijo ya tiene un canal de finalización de vuelta al padre.

sessions_send puede apuntar a otra sesión después de la creación. Para sesiones peer normales, OpenClaw usa una ruta de seguimiento agente a agente (A2A) después de inyectar el mensaje:

• Espera la respuesta de la sesión de destino.
• Opcionalmente permite que solicitante y destino intercambien un número acotado de turnos de seguimiento.
• Pide al destino que produzca un mensaje de anuncio.
• Entrega ese anuncio al canal o hilo visible.

Esa ruta A2A es una alternativa para envíos peer donde el remitente necesita un seguimiento visible. Permanece habilitada cuando una sesión no relacionada puede ver y enviar mensajes a un destino ACP, por ejemplo bajo configuraciones amplias de tools.sessions.visibility.

OpenClaw omite el seguimiento A2A solo cuando el solicitante es el padre de su propio hijo ACP de una sola ejecución propiedad del padre. En ese caso, ejecutar A2A además de la finalización de tarea puede despertar al padre con el resultado del hijo, reenviar la respuesta del padre de vuelta al hijo y crear un bucle de eco padre/hijo. El resultado de sessions_send informa delivery.status="skipped" para ese caso de hijo propio porque la ruta de finalización ya es responsable del resultado.

Usa resumeSessionId para continuar una sesión ACP anterior en lugar de empezar de cero. El agente reproduce su historial de conversación mediante session/load, así que retoma con el contexto completo de lo anterior.

{  "task": "Continue where we left off - fix the remaining test failures",  "runtime": "acp",  "agentId": "codex",  "resumeSessionId": "<previous-session-id>"}

Casos de uso comunes:

• Transfiere una sesión Codex desde tu laptop a tu teléfono: dile a tu agente que retome donde lo dejaste.
• Continúa una sesión de programación que iniciaste interactivamente en la CLI, ahora sin interfaz mediante tu agente.
• Retoma trabajo interrumpido por un reinicio del gateway o un tiempo de espera por inactividad.

Notas:

• resumeSessionId solo aplica cuando runtime: "acp"; el tiempo de ejecución predeterminado de subagente ignora este campo exclusivo de ACP.
• streamTo solo aplica cuando runtime: "acp"; el tiempo de ejecución predeterminado de subagente ignora este campo exclusivo de ACP.
• resumeSessionId es un id. de reanudación ACP/harness local del host, no una clave de sesión de canal de OpenClaw; OpenClaw aún comprueba la política de creación ACP y la política del agente de destino antes del envío, mientras que el backend ACP o harness posee la autorización para cargar ese id. upstream.
• resumeSessionId restaura el historial de conversación ACP upstream; thread y mode siguen aplicándose normalmente a la nueva sesión de OpenClaw que estás creando, así que mode: "session" sigue requiriendo thread: true.
• El agente de destino debe admitir session/load (Codex y Claude Code lo hacen).
• Si no se encuentra el id. de sesión, la creación falla con un error claro: sin fallback silencioso a una sesión nueva.

Después de un despliegue del gateway, ejecuta una comprobación end-to-end en vivo en lugar de confiar en pruebas unitarias:

1. Verifica la versión y el commit del Gateway desplegado en el host de destino.
2. Abre una sesión temporal de puente ACPX hacia un agente en vivo.
3. Pide a ese agente que llame a sessions_spawn con runtime: "acp", agentId: "codex", mode: "run" y la tarea Reply with exactly LIVE-ACP-SPAWN-OK.
4. Verifica accepted=yes, un childSessionKey real y ningún error de validador.
5. Limpia la sesión temporal de puente.

Mantén la compuerta en mode: "run" y omite streamTo: "parent": las rutas de mode: "session" vinculadas al hilo y de retransmisión de flujo son pases de integración más completos independientes.