Agentes ACP

• Si plugins.allow está definido, es un inventario restrictivo de plugins y debe incluir acpx; de lo contrario, el backend ACP instalado se bloquea intencionadamente y /acp doctor informa la entrada faltante en la lista de permitidos.
• El adaptador Codex ACP se prepara con el plugin acpx y se inicia localmente cuando es posible.
• Codex ACP se ejecuta con un CODEX_HOME aislado; OpenClaw copia entradas de proyectos de confianza y configuración segura de enrutamiento de modelo/proveedor desde la configuración de Codex del host, mientras que la autenticación, las notificaciones y los hooks permanecen en la configuración del host.
• Otros adaptadores de arneses de destino todavía pueden obtenerse bajo demanda con npx la primera vez que los uses.
• La autenticación del proveedor todavía 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 precalienten o el adaptador se instale de otra forma.

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

Antes de culpar a OpenClaw, verifica:

• /acp doctor informa 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 ID de modelo no son portátiles entre arneses.
• El cwd solicitado existe y es accesible, o omite cwd y permite 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 mucha escritura/ejecución suelen necesitar un perfil de permisos ACPX que pueda avanzar sin interfaz.

• La generación crea o reanuda una sesión de runtime 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 que pertenecen al padre se tratan como trabajo en segundo plano incluso cuando la sesión de runtime es persistente; la finalización y la entrega entre superficies pasan por el notificador de tareas padre en lugar de comportarse como una sesión de chat normal visible para el usuario.
• El mantenimiento de tareas cierra sesiones ACP de un solo uso, terminales o huérfanas, que pertenecen al padre. Las sesiones ACP persistentes se conservan mientras exista una vinculación activa de conversación; las sesiones persistentes obsoletas sin una vinculación activa se cierran para que no puedan reanudarse silenciosamente después de que la tarea propietaria termine o desaparezca su registro de tarea.
• 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 de Gateway permanecen locales. /acp ..., /status y /unfocus nunca se envían como texto de prompt normal 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 todavía 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 de Gateway.
• Los workers de runtime inactivos son elegibles para limpieza después de acp.runtime.ttlMinutes; los metadatos de sesión almacenados permanecen 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 de chat. Las herramientas dinámicas de OpenClaw se siguen ejecutando mediante 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 relé de hook nativo por turno para que los hooks de Plugin puedan bloquear before_tool_call, observar after_tool_call y enrutar los eventos PermissionRequest de Codex mediante las aprobaciones de OpenClaw. Los hooks Stop de Codex se retransmiten 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 relé sigue siendo deliberadamente conservador: no muta los argumentos de herramientas nativas de Codex ni reescribe los registros de hilo de Codex. Usa ACP explícito solo cuando quieras el modelo de runtime/sesión de ACP. El límite de soporte de Codex embebido está documentado en el contrato de soporte del harness de Codex v1.

• refs de modelo de Codex heredadas - ruta de modelo OAuth/suscripción de Codex heredada reparada por doctor.
• openai/* - runtime embebido del servidor de aplicaciones nativo de Codex para turnos de agente de OpenAI.
• /codex ... - control de conversación nativo de Codex.
• /acp ... o runtime: "acp" - control ACP/acpx explícito.

Disparadores que deben enrutar al runtime de ACP:

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

OpenClaw elige runtime: "acp", resuelve el agentId del harness, se vincula a la conversación o hilo actual cuando se admite, y enruta los seguimientos a esa sesión hasta el cierre o la 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á en sandbox y hay cargado un backend de runtime 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" }). Apunta a ids de harness ACP como codex, claude, droid, gemini u opencode. No pases un id normal de agente 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 runtime de subagente predeterminado. Cuando un agente de OpenClaw está configurado con runtime.type="acp", OpenClaw usa runtime.acp.agent como el id de harness 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 admitido en caso contrario. Las vinculaciones persisten entre reinicios del Gateway.
• En Discord, spawnSessions controla la creación de hilos secundarios para --thread auto|here, no --bind here.
• Si generas hacia un agente ACP distinto 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 (por ejemplo, EACCES) aparecen como errores de spawn.
• Los comandos de administración del Gateway permanecen locales en conversaciones vinculadas: los comandos /acp ... los gestiona OpenClaw incluso cuando el texto normal de seguimiento se enruta a la sesión ACP vinculada; /status y /unfocus también permanecen locales siempre que el manejo de comandos esté habilitado para esa superficie.

Cuando las vinculaciones de hilo 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.
• Desenfoque/cierre/archivo/tiempo de inactividad o expiración por antigüedad máxima elimina la vinculación.
• /acp close, /acp cancel, /acp status, /status y /unfocus son comandos del Gateway, no prompts para el harness ACP.

Feature flags requeridos para ACP vinculado a hilos:

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

El soporte de vinculación de hilos es específico del adaptador. Si el adaptador de canal activo no admite vinculaciones de hilo, OpenClaw devuelve un mensaje claro de no admitido/no disponible.

• Cualquier adaptador de canal que exponga capacidad de vinculación de sesión/hilo.
• Soporte integrado actual: hilos/canales de Discord, temas de Telegram (temas de foro en grupos/supergrupos y temas de DM).
• Los canales de Plugin pueden agregar soporte 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 de seguimiento en la conversación vinculada se enrutan directamente a la sesión ACP, y la salida ACP se entrega de vuelta al mismo canal/hilo/tema.

Lo que OpenClaw envía al harness:

• Los seguimientos vinculados normales se envían como texto de prompt, más adjuntos solo cuando el harness/backend los admite.
• Los comandos de gestión /acp y los comandos locales del Gateway se interceptan antes del despacho ACP.
• Los eventos de finalización generados por runtime se materializan por destino. Los agentes de OpenClaw reciben el envoltorio interno de contexto de runtime de OpenClaw; los harnesses ACP externos reciben un prompt plano con el resultado hijo y la instrucción. El envoltorio sin procesar <<&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 activación visible para el usuario o el prompt de finalización plano. Los metadatos de eventos internos 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 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, así que un harness ACP lento no bloquea el trabajo no relacionado de la sesión principal.
• Los informes de finalización vuelven por la ruta de anuncio de finalización de tarea. OpenClaw convierte los metadatos internos de finalización en un prompt ACP plano antes de enviarlos a un harness externo, para que los harnesses no vean marcadores de contexto de runtime exclusivos de OpenClaw.
• El padre reescribe el resultado del hijo con voz normal de asistente cuando resulta útil una respuesta visible para el usuario.

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

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

• Espera la respuesta de la sesión de destino.
• Opcionalmente, permite que el solicitante y el 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 un recurso alternativo para envíos entre pares 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 un solo uso propiedad del padre. En ese caso, ejecutar A2A encima de la finalización de la 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 propiedad del padre porque la ruta de finalización ya es responsable del resultado.

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

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

Casos de uso comunes:

• Transferir una sesión de Codex de tu portátil a tu teléfono: dile a tu agente que retome donde lo dejaste.
• Continuar una sesión de programación que iniciaste interactivamente en la CLI, ahora sin interfaz mediante tu agente.
• Retomar trabajo interrumpido por un reinicio del gateway o un tiempo de espera por inactividad.

Notas:

• resumeSessionId solo se aplica cuando runtime: "acp"; el runtime de subagente predeterminado ignora este campo exclusivo de ACP.
• streamTo solo se aplica cuando runtime: "acp"; el runtime de subagente predeterminado 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 de ACP y la política del agente de destino antes del envío, mientras que el backend ACP o el harness son responsables de autorizar la carga de ese id ascendente.
• resumeSessionId restaura el historial de conversación ACP ascendente; thread y mode siguen aplicándose normalmente a la nueva sesión de OpenClaw que estás creando, por lo que mode: "session" aún requiere 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 alternativa silenciosa a una sesión nueva.

Después de desplegar un gateway, ejecuta una comprobación integral 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 puente ACPX temporal 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 puente temporal.

Mantén la compuerta en mode: "run" y omite streamTo: "parent": las rutas vinculadas a hilos con mode: "session" y de retransmisión de flujo son comprobaciones de integración más completas y separadas.