Agentes ACP

• Si se ha definido plugins.allow, funciona como un inventario restrictivo de plugins y debe incluir acpx; de lo contrario, el backend ACP instalado se bloquea de manera intencionada (/acp doctor informa de que falta la entrada en la lista de permitidos).
• El adaptador ACP de Codex se distribuye con el plugin acpx y se inicia localmente cuando es posible.
• Codex ACP se ejecuta con un CODEX_HOME aislado. OpenClaw copia desde la configuración de Codex del anfitrión las entradas de confianza de proyectos y la configuración segura de enrutamiento de modelos/proveedores (model, model_provider, model_reasoning_effort, sandbox_mode y los campos seguros de model_providers.<name>); la autenticación, las notificaciones y los enlaces permanecen únicamente en la configuración del anfitrión.
• Otros adaptadores de entornos de destino pueden descargarse bajo demanda mediante npx durante el primer uso.
• La autenticación del proveedor ya debe existir en el anfitrión para ese entorno.
• Si el anfitrión no tiene npm ni acceso a la red, las descargas de adaptadores durante la primera ejecución fallarán hasta que las cachés se precarguen o el adaptador se instale de otra manera.

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

Antes de responsabilizar a OpenClaw, verifica lo siguiente:

• /acp doctor informa de un backend habilitado y en buen estado.
• El identificador de destino está permitido por acp.allowedAgents cuando se ha definido esa lista de permitidos.
• El comando del entorno puede iniciarse en el anfitrión del Gateway.
• La autenticación del proveedor está disponible para ese entorno (claude, codex, gemini, opencode, droid, etc.).
• El modelo seleccionado existe para ese entorno; los identificadores de modelos no son intercambiables entre entornos.
• El cwd solicitado existe y es accesible; de lo contrario, 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 solicitudes nativas de permisos, por lo que las ejecuciones de programación que realizan muchas operaciones de escritura o ejecución suelen necesitar un perfil de permisos ACPX que pueda continuar sin interfaz interactiva.

• El inicio crea o reanuda una sesión del entorno ACP, registra los metadatos de ACP en el almacén de sesiones de OpenClaw y puede crear una tarea en segundo plano cuando la ejecución pertenece a la tarea principal.
• Las sesiones ACP que pertenecen a la tarea principal se tratan como trabajo en segundo plano incluso cuando la sesión del entorno es persistente; la finalización y la entrega entre superficies pasan por el notificador de la tarea principal en lugar de comportarse como una sesión de chat normal visible para el usuario.
• El mantenimiento de tareas cierra las sesiones ACP de una sola ejecución, terminales o huérfanas, que pertenecen a la tarea principal. Las sesiones ACP persistentes se conservan mientras exista una vinculación activa con una conversación; las sesiones persistentes obsoletas sin una vinculación activa se cierran para impedir que se reanuden de forma silenciosa después de que termine la tarea propietaria o desaparezca su registro.
• Los mensajes posteriores 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 en el ámbito local. /acp ..., /status y /unfocus nunca se envían como texto normal de una solicitud a un entorno ACP vinculado.
• cancel cancela el turno activo cuando el backend admite la cancelación; no elimina la vinculación ni los metadatos de la sesión.
• close finaliza la sesión ACP desde el punto de vista de OpenClaw y elimina la vinculación. Un entorno puede conservar su propio historial en el servicio de origen si admite la reanudación.
• El plugin acpx limpia los árboles de procesos contenedores y adaptadores propiedad de OpenClaw después de close, y elimina los procesos ACPX huérfanos y obsoletos propiedad de OpenClaw durante el inicio del Gateway.
• Los procesos inactivos del entorno pueden eliminarse después de acp.runtime.ttlMinutes; los metadatos almacenados de la sesión siguen disponibles para /acp sessions.

Activadores en lenguaje natural que deben dirigirse al plugin nativo de Codex cuando esté habilitado:

• "Vincula este canal de Discord con Codex".
• "Asocia este chat al hilo <id> de Codex".
• "Muestra los hilos de Codex y después 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 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 hooks nativos por turno para que los hooks de los plugins 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 adicional del modelo antes de que Codex finalice su respuesta. El relé se mantiene deliberadamente conservador: no modifica los argumentos de las herramientas nativas de Codex ni reescribe los registros de hilos de Codex. Usa ACP explícitamente solo cuando quieras el modelo de entorno de ejecución/sesión de ACP. El límite de compatibilidad integrada con Codex se documenta en el contrato de compatibilidad v1 del entorno de Codex.

• referencias heredadas de modelos de Codex - ruta heredada de modelos de suscripción/OAuth de Codex reparada por doctor.
• openai/* - entorno de ejecución integrado del servidor de aplicaciones nativo de Codex para los turnos del agente de OpenAI.
• /codex ... - control nativo de conversaciones de Codex.
• /acp ... o runtime: "acp" - control explícito mediante ACP/acpx.

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

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

OpenClaw selecciona runtime: "acp", resuelve el agentId del entorno, se vincula a la conversación o al hilo actuales cuando sea compatible y enruta los seguimientos a esa sesión hasta que se cierre o caduque. 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" solo se anuncia cuando ACP está habilitado, el solicitante no está aislado y se ha cargado un backend del entorno de ejecución de ACP. acp.dispatch.enabled=false pausa el envío automático de hilos de ACP, pero no oculta ni bloquea las llamadas explícitas a sessions_spawn({ runtime: "acp" }). Se dirige a identificadores de entornos ACP como codex, claude, droid, gemini u opencode. No pases un identificador normal de agente de configuración de OpenClaw obtenido de agents_list, salvo que esa entrada esté configurada explícitamente con agents.list[].runtime.type="acp"; de lo contrario, usa el entorno de ejecución predeterminado de subagentes. Cuando un agente de OpenClaw está configurado con runtime.type="acp", OpenClaw usa runtime.acp.agent como identificador del entorno subyacente.

• --bind here y --thread ... son mutuamente excluyentes.
• --bind here solo funciona en canales que anuncian compatibilidad con la vinculación a la conversación actual; de lo contrario, OpenClaw devuelve un mensaje claro de incompatibilidad. Las vinculaciones persisten tras reiniciar el Gateway.
• En Discord, spawnSessions controla la creación de hilos secundarios para --thread auto|here, pero no para --bind here.
• Si creas una sesión para otro agente ACP sin --cwd, OpenClaw hereda de forma predeterminada el espacio de trabajo del agente de destino. Si las rutas heredadas no existen (ENOENT/ENOTDIR), se utiliza el valor predeterminado del backend; otros errores de acceso (por ejemplo, EACCES) se muestran como errores de creación.
• Los comandos de administración del Gateway permanecen locales en las 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 hilos están habilitadas para un adaptador de canal:

• OpenClaw vincula un hilo a una sesión ACP de destino.
• Los mensajes posteriores de ese hilo se dirigen a la sesión ACP vinculada.
• La salida de ACP se entrega al mismo hilo.
• Al quitar el enfoque, cerrar, archivar o alcanzar el tiempo límite de inactividad o la antigüedad máxima, se elimina la vinculación.
• /acp close, /acp cancel, /acp status, /status y /unfocus son comandos del Gateway, no instrucciones para el entorno ACP.

Indicadores de función necesarios para ACP vinculado a hilos:

• acp.enabled=true
• acp.dispatch.enabled está activado de forma predeterminada (configúralo como false para pausar el envío automático de hilos de 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 la vinculación de hilos depende del adaptador. Si el adaptador de canal activo no admite vinculaciones de hilos, OpenClaw devuelve un mensaje claro indicando que no se admite o no está disponible.

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

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

• /acp spawn ... --bind here enlaza la conversación actual con la sesión ACP.
• /acp spawn ... --thread ... enlaza un hilo o tema del canal con la sesión ACP.
• Los bindings[].type="acp" persistentes configurados dirigen las conversaciones coincidentes a la misma sesión ACP.

Los mensajes posteriores de la conversación enlazada se dirigen directamente a la sesión ACP, y la salida de ACP se devuelve a ese mismo canal, hilo o tema.

Lo que OpenClaw envía al entorno:

• Los mensajes posteriores enlazados normales se envían como texto de instrucción, junto con archivos adjuntos solo cuando el entorno o el backend los admite.
• Los comandos de administración /acp y los comandos locales del Gateway se interceptan antes de enviarlos a ACP.
• Los eventos de finalización generados por el entorno de ejecución se materializan para cada destino. Los agentes de OpenClaw reciben el sobre interno de contexto del entorno de ejecución de OpenClaw; los entornos ACP externos reciben una instrucción sencilla con el resultado secundario y la indicación correspondiente. El sobre sin procesar <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> nunca debe enviarse a entornos externos ni conservarse como texto de la transcripción del usuario de ACP.
• Las entradas de la transcripción ACP usan el texto del desencadenante visible para el usuario o la instrucción sencilla de finalización. Los metadatos de eventos internos permanecen estructurados en OpenClaw siempre que sea posible y no se tratan como contenido de chat redactado por el usuario.

Las sesiones ACP de ejecución única creadas por otra ejecución de un agente son procesos secundarios en segundo plano, similares a los subagentes:

• El padre solicita trabajo con sessions_spawn({ runtime: "acp", mode: "run" }).
• El proceso secundario se ejecuta en su propia sesión del entorno ACP.
• Los turnos secundarios se ejecutan en el mismo carril en segundo plano que usan las creaciones nativas de subagentes, por lo que un entorno ACP lento no bloquea el trabajo no relacionado de la sesión principal.
• La finalización se comunica mediante la ruta de anuncio de finalización de tareas. OpenClaw convierte los metadatos internos de finalización en una instrucción ACP sencilla antes de enviarlos a un entorno externo, por lo que los entornos no ven los marcadores de contexto del entorno de ejecución exclusivos de OpenClaw.
• El padre reformula el resultado secundario con la voz normal del asistente cuando resulta útil ofrecer una respuesta al usuario.

No trates esta ruta como un chat entre pares entre el padre y el proceso secundario. El proceso secundario ya dispone de un canal de finalización hacia el padre.

sessions_send puede dirigirse a otra sesión después de la creación. Para las sesiones normales entre pares, 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.
• Permite opcionalmente que el solicitante y el destino intercambien un número limitado de turnos posteriores.
• Solicita al destino que genere un mensaje de anuncio.
• Entrega ese anuncio al canal o hilo visible.

Esa ruta A2A es una alternativa para los envíos entre pares en los que 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, con una configuración amplia de tools.sessions.visibility.

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

Use resumeSessionId para continuar una sesión ACP anterior en lugar de comenzar desde cero. El agente reproduce su historial de conversación mediante session/load, por lo que continúa con todo el contexto de lo ocurrido anteriormente.

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

Casos de uso habituales:

• Transfiera una sesión de Codex desde su portátil a su teléfono: indique a su agente que continúe donde la dejó.
• Continúe mediante su agente y sin interfaz una sesión de programación que inició de forma interactiva en la CLI.
• Retome un trabajo interrumpido por un reinicio del Gateway o un tiempo de espera por inactividad.

Notas:

• resumeSessionId solo se aplica cuando runtime: "acp"; el entorno de ejecución predeterminado de subagentes ignora este campo exclusivo de ACP.
• streamTo solo se aplica cuando runtime: "acp"; el entorno de ejecución predeterminado de subagentes ignora este campo exclusivo de ACP.
• resumeSessionId es un identificador local del host para reanudar ACP o el arnés, no una clave de sesión de canal de OpenClaw; OpenClaw sigue comprobando la política de creación de ACP y la política del agente de destino antes de enviar la solicitud, mientras que el backend de ACP o el arnés gestiona la autorización para cargar ese identificador ascendente.
• resumeSessionId restaura el historial de conversación de ACP ascendente; thread y mode se siguen aplicando normalmente a la nueva sesión de OpenClaw que está creando, por lo que mode: "session" sigue requiriendo thread: true.
• El agente de destino debe admitir session/load (Codex y Claude Code lo admiten).
• Si no se encuentra el identificador de sesión, la creación falla con un error claro, sin recurrir silenciosamente a una sesión nueva.

Después de desplegar un Gateway, ejecute una comprobación integral en vivo en lugar de confiar en las pruebas unitarias:

1. Verifique la versión y el commit del Gateway desplegado en el host de destino.
2. Abra una sesión puente ACPX temporal con un agente en vivo.
3. Pida 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. Verifique accepted=yes, un childSessionKey real y que no haya errores de validación.
5. Cierre la sesión puente temporal.

Mantenga la validación en mode: "run" y omita streamTo: "parent": el mode: "session" vinculado a un hilo y las rutas de retransmisión de flujo son pruebas de integración más completas e independientes.