Agentes ACP

• Si plugins.allow está configurado, 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 ACP de Codex se prepara con el Plugin acpx y se inicia localmente cuando es posible.
• Otros adaptadores de arneses de destino todavía pueden descargarse 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 o acceso a la red, las descargas de adaptadores de primera ejecución fallan hasta que las cachés se preparen previamente o el adaptador se instale de otra forma.

ACP inicia un proceso real de arnés externo. OpenClaw posee el enrutamiento, el estado de tareas en segundo plano, la entrega, las vinculaciones y la política; el arnés posee el inicio de sesión de su proveedor, el catálogo de modelos, el comportamiento del sistema de archivos y las 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á configurada.
• El comando del arnés puede iniciarse en el host 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, u omite cwd y 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 avisos de permisos nativos, por lo que las ejecuciones de codificación con muchas escrituras/ejecuciones suelen necesitar un perfil de permisos ACPX que pueda avanzar sin intervención.

• La creació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 pertenecientes 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 la tarea padre en lugar de actuar como una sesión de chat normal orientada al usuario.
• El mantenimiento de tareas cierra sesiones ACP puntuales, terminales o huérfanas, pertenecientes al padre. Las sesiones ACP persistentes se conservan mientras permanezca 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 termine o su registro de tarea desaparezca.
• 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 expire.
• Los comandos de 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 upstream si admite reanudación.
• Los trabajadores de runtime inactivos son aptos para limpieza después de acp.runtime.ttlMinutes; los metadatos de sesión almacenados siguen disponibles para /acp sessions.

Activadores en lenguaje natural que deberían 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 de conversaciones nativa de Codex es la ruta predeterminada de control de chat. Las herramientas dinámicas de OpenClaw siguen ejecutándose mediante OpenClaw, mientras que las herramientas nativas de Codex, como shell/apply-patch, se ejecutan dentro de Codex. Para eventos de herramientas nativas de Codex, OpenClaw inyecta un relay de hooks nativo por turno para que los hooks de Plugin puedan bloquear before_tool_call, observar after_tool_call y enrutar eventos PermissionRequest de Codex mediante aprobaciones de OpenClaw. Los hooks Stop de Codex se retransmiten a before_agent_finalize de OpenClaw, donde los plugins pueden solicitar un pase más del modelo antes de que Codex finalice su respuesta. El relay sigue siendo deliberadamente conservador: no muta los argumentos de herramientas nativas de Codex ni reescribe registros de hilos de Codex. Usa ACP explícito solo cuando quieras el modelo de runtime/sesión de ACP. El límite de soporte embebido de Codex está documentado en el contrato de soporte del arnés Codex v1.

• openai-codex/* - ruta de OAuth/suscripción de PI Codex.
• openai/* más agentRuntime.id: "codex" - runtime integrado nativo del servidor de aplicaciones Codex.
• /codex ... - control de conversación nativo de Codex.
• /acp ... o runtime: "acp" - control explícito de ACP/acpx.

Activadores que deberían dirigirse al runtime de 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 seguimientos en ese mismo hilo."
• "Ejecuta Codex mediante ACP en un hilo en segundo plano."

OpenClaw elige runtime: "acp", resuelve el agentId del arnés, se vincula a la conversación o hilo actual cuando se admite, y dirige los seguimientos a esa sesión hasta su cierre/caducidad. 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 se ha cargado un backend de runtime de ACP. acp.dispatch.enabled=false pausa el despacho automático de hilos de ACP, pero no oculta ni bloquea las llamadas explícitas a sessions_spawn({ runtime: "acp" }). Apunta a ids de arnés de 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 predeterminado de subagente. Cuando un agente de OpenClaw está configurado con runtime.type="acp", OpenClaw usa runtime.acp.agent como el id de arnés subyacente.

• --bind here y --thread ... son mutuamente excluyentes.
• --bind here solo funciona en canales que anuncian vinculación de conversación actual; de lo contrario, OpenClaw devuelve un mensaje claro de no admitido. Las vinculaciones persisten tras reinicios del gateway.
• En Discord, spawnSessions controla la creación de hilos hijos para --thread auto|here, no --bind here.
• Si inicias un agente ACP diferente sin --cwd, OpenClaw hereda de forma predeterminada el espacio de trabajo del agente de destino. Las rutas heredadas faltantes (ENOENT/ENOTDIR) vuelven al valor predeterminado del backend; otros errores de acceso (por ejemplo, EACCES) aparecen como errores de inicio.
• 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 dirige 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 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 dirigen a la sesión ACP vinculada.
• La salida de ACP se entrega de vuelta al mismo hilo.
• Desenfocar/cerrar/archivar/tiempo de espera por inactividad o caducidad por edad máxima elimina la vinculación.
• /acp close, /acp cancel, /acp status, /status y /unfocus son comandos de Gateway, no prompts para el arnés ACP.

Indicadores de características 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 de ACP; las llamadas explícitas a sessions_spawn({ runtime: "acp" }) siguen funcionando).
• Inicio de sesiones de hilo del adaptador de canal habilitado (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 añadir 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 del canal a la sesión ACP.
• Las bindings[].type="acp" persistentes configuradas 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 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 despacho ACP.
• Los eventos de finalización generados por el runtime se materializan por destino. Los agentes de OpenClaw reciben el sobre interno de contexto de runtime de OpenClaw; los harnesses ACP externos reciben un prompt sin formato 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 desencadenador visible para el usuario o el prompt de finalización sin formato. 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 generadas 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 los spawns nativos de subagentes, así que un harness ACP lento no bloquea el trabajo no relacionado de la sesión principal.
• La finalización se informa mediante la ruta de anuncio de finalización de tarea. OpenClaw convierte los metadatos internos de finalización en un prompt ACP sin formato antes de enviarlo 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 del spawn. Para sesiones pares 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 una cantidad limitada 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 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 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 que ocurrió antes.

{
  "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 de Codex de tu portátil 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 que fue interrumpido por un reinicio del gateway o un tiempo de espera por inactividad.

Notas:

• resumeSessionId solo se aplica cuando runtime: "acp"; el runtime predeterminado de subagente ignora este campo exclusivo de ACP.
• streamTo solo se aplica cuando runtime: "acp"; el runtime 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 spawn ACP y la política del agente de destino antes del despacho, mientras que el backend o harness ACP posee la autorización para cargar 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, 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, el spawn falla con un error claro: no hay recurso silencioso a una sesión nueva.

Después de un despliegue de gateway, ejecuta una comprobación integral en vivo en lugar de confiar en las 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. Pídele 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 puerta en mode: "run" y omite streamTo: "parent": las rutas de mode: "session" vinculadas a hilos y de retransmisión de streaming son pasadas de integración más completas y separadas.