Agentes ACP

• Si se establece plugins.allow, este constituye un inventario restrictivo de plugins y debe incluir acpx; de lo contrario, el backend ACP instalado queda bloqueado intencionadamente (/acp doctor informa de la entrada ausente en la lista de permitidos).
• El adaptador ACP de Codex se incluye 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 host las entradas de confianza de proyectos fiables 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 hooks permanecen únicamente en la configuración del host.
• Los adaptadores de otros entornos de destino pueden descargarse bajo demanda con npx durante el primer uso.
• La autenticación del proveedor ya debe existir en el host para ese entorno.
• Si el host no tiene npm ni acceso a la red, las descargas de adaptadores durante la primera ejecución fallan hasta que las cachés se hayan preparado previamente o el adaptador se instale de otra forma.

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

Antes de atribuir el problema a OpenClaw, se debe comprobar lo siguiente:

• /acp doctor informa de un backend habilitado y en buen estado.
• El identificador de destino está permitido por acp.allowedAgents cuando se establece esa lista de permitidos.
• El comando del entorno puede iniciarse en el host 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 transferibles entre entornos.
• El cwd solicitado existe y es accesible; de lo contrario, se puede omitir cwd para que el backend use su valor predeterminado.
• El modo de permisos se ajusta al trabajo. Las sesiones no interactivas no pueden responder a solicitudes nativas de permisos, por lo que las ejecuciones de programación con muchas operaciones de escritura o ejecución suelen necesitar un perfil de permisos ACPX que pueda continuar sin interacción.

• La creación inicia o reanuda una sesión de entorno de ejecución 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 al proceso principal.
• Las sesiones ACP que pertenecen al proceso principal se tratan como trabajo en segundo plano incluso cuando la sesión del entorno de ejecución es persistente; la finalización y la entrega entre superficies pasan por el notificador de tareas del proceso principal, en lugar de comportarse como una sesión de chat normal orientada al usuario.
• El mantenimiento de tareas cierra las sesiones ACP de una sola ejecución, terminales o huérfanas, que pertenecen al proceso principal. Las sesiones ACP persistentes se conservan mientras exista 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 finalice la tarea propietaria o desaparezca su registro.
• Los mensajes de seguimiento vinculados se envían directamente a la sesión ACP hasta que la vinculación se cierra, pierde el foco, se restablece o caduca.
• Los comandos del Gateway permanecen locales. /acp ..., /status y /unfocus nunca se envían como texto normal de una instrucción a un entorno ACP vinculado.
• cancel cancela el turno activo cuando el backend admite 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 aún puede conservar su propio historial ascendente 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 huérfanos ACPX obsoletos propiedad de OpenClaw durante el inicio del Gateway.
• Los procesos de trabajo inactivos del entorno de ejecución pueden limpiarse después del periodo de inactividad integrado; 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 con el hilo de Codex <id>."
• "Muestra los hilos de Codex y, después, vincula este."

La vinculación de conversaciones nativas 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 dirigir los eventos de Codex PermissionRequest mediante las aprobaciones de OpenClaw. Los hooks de Codex Stop 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 los hilos de Codex. Utilice ACP explícito solo cuando necesite 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 de modelos heredados 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 de ACP/acpx.

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

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

OpenClaw selecciona runtime: "acp", resuelve el entorno agentId, lo vincula con la conversación o el hilo actual cuando se admite y dirige los mensajes de seguimiento a esa sesión hasta que se cierre o caduque. Codex solo sigue esta ruta cuando ACP/acpx se solicita explícitamente 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 hay cargado un backend de entorno de ejecución ACP. acp.dispatch.enabled=false pausa el envío automático de hilos 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 o opencode. No proporcione un identificador normal de agente de configuración de OpenClaw procedente de agents_list a menos que esa entrada esté configurada explícitamente con agents.entries.*.runtime.type="acp"; en caso contrario, utilice el entorno de ejecución predeterminado de subagentes. Cuando un agente de OpenClaw está configurado con runtime.type="acp", OpenClaw utiliza runtime.acp.agent como identificador del entorno subyacente.

• --bind here y --thread ... son mutuamente excluyentes.
• --bind here solo funciona en canales que anuncian la vinculación con la conversación actual; en caso contrario, OpenClaw devuelve un mensaje claro que indica la falta de compatibilidad. Las vinculaciones persisten tras reiniciar el Gateway.
• En Discord, spawnSessions controla la creación de hilos secundarios para --thread auto|here, no para --bind here.
• Si crea una sesión para otro agente ACP sin --cwd, OpenClaw hereda de forma predeterminada el espacio de trabajo del agente de destino. Las rutas heredadas que faltan (ENOENT/ENOTDIR) recurren al 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 con una sesión ACP de destino.
• Los mensajes de seguimiento de ese hilo se dirigen a la sesión ACP vinculada.
• La salida de ACP se entrega de vuelta al mismo hilo.
• La pérdida de foco, el cierre, el archivado, el tiempo de espera por inactividad o la caducidad por antigüedad máxima eliminan la vinculación.
• /acp close, /acp cancel, /acp status, /status y /unfocus son comandos del Gateway, no instrucciones para el entorno ACP.

Indicadores de funcionalidad necesarios para ACP vinculado a hilos:

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

La compatibilidad con la vinculación de hilos depende de cada adaptador. Si el adaptador de canal activo no admite vinculaciones de hilos, OpenClaw devuelve un mensaje claro que indica que no se admite o no está disponible.

• Cualquier adaptador de canal que exponga la capacidad de vinculación de 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 destinadas a mantener la conversación en una superficie de chat visible:

• /acp spawn ... --bind here vincula la conversación actual a la sesión de ACP.
• /acp spawn ... --thread ... vincula un hilo o tema del canal a la sesión de ACP.
• Las vinculaciones bindings[].type="acp" persistentes configuradas enrutan las conversaciones coincidentes a la misma sesión de ACP.

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

Lo que OpenClaw envía al arnés:

• Los seguimientos vinculados normales se envían como texto de prompt, además de archivos adjuntos solo cuando el arnés o el backend los admite.
• Los comandos de administración de /acp y los comandos locales del Gateway se interceptan antes del envío 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 de contexto de ejecución interno de OpenClaw; los arneses ACP externos reciben un prompt sin formato con el resultado secundario y la instrucción. El sobre <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> sin procesar nunca debe enviarse a arneses externos ni conservarse como texto de transcripción del usuario de ACP.
• Las entradas de transcripción de ACP usan el texto del desencadenador visible para el usuario o el prompt de finalización sin formato. Los metadatos de eventos internos permanecen estructurados en OpenClaw siempre que sea posible y no se tratan como contenido de chat escrito por el usuario.

Las sesiones ACP de ejecución única iniciadas por la ejecución de otro agente son procesos secundarios en segundo plano, similares a los subagentes:

• El agente principal solicita trabajo con sessions_spawn({ runtime: "acp", mode: "run" }).
• El proceso secundario se ejecuta en su propia sesión de arnés ACP.
• Los turnos del proceso secundario se ejecutan en el mismo canal en segundo plano que usan los inicios de subagentes nativos, por lo que un arnés ACP lento no bloquea el trabajo no relacionado de la sesión principal.
• La finalización se notifica mediante la ruta de anuncio de finalización de tareas. OpenClaw convierte los metadatos internos de finalización en un prompt ACP sin formato antes de enviarlos a un arnés externo, de modo que los arneses no ven marcadores de contexto de ejecución exclusivos de OpenClaw.
• El agente principal reformula el resultado del proceso secundario con el estilo normal del asistente cuando resulta útil una respuesta visible para el usuario.

No se debe tratar esta ruta como un chat entre pares entre el agente principal y el proceso secundario. El proceso secundario ya dispone de un canal de finalización de vuelta al agente principal.

sessions_send puede dirigirse a otra sesión después del inicio. Para las sesiones normales entre pares, OpenClaw usa una ruta de seguimiento de agente a agente (A2A) después de insertar el mensaje:

• Esperar la respuesta de la sesión de destino.
• Opcionalmente, permitir que el solicitante y el destino intercambien un número limitado de turnos de seguimiento.
• Pedir al destino que genere un mensaje de anuncio.
• Entregar 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 solo cuando el solicitante es el agente principal de su propio proceso secundario ACP de ejecución única que le pertenece. En ese caso, ejecutar A2A además de la finalización de la tarea puede activar al agente principal con el resultado del proceso secundario, reenviar la respuesta del agente principal al proceso secundario y crear un bucle de eco entre ambos. El resultado de sessions_send informa de delivery.status="skipped" en ese caso de proceso secundario propio porque la ruta de finalización ya es responsable del resultado.

Use resumeSessionId para continuar una sesión ACP anterior en lugar de comenzar de nuevo. 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": "Continuar donde lo dejamos: corregir los fallos de pruebas restantes",  "runtime": "acp",  "agentId": "codex",  "resumeSessionId": "<previous-session-id>"}

Casos de uso habituales:

• Transferir una sesión de Codex del portátil al teléfono: indique al agente que continúe donde se dejó.
• Continuar mediante el agente, ahora sin interfaz, una sesión de programación iniciada interactivamente en la CLI.
• Retomar el 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 de reanudación de ACP/arnés local al host, no una clave de sesión de canal de OpenClaw; OpenClaw sigue comprobando la política de inicio de ACP y la política del agente de destino antes del envío, mientras que el backend o el arnés de ACP controla la autorización para cargar ese identificador ascendente.
• resumeSessionId restaura el historial de conversación de ACP ascendente; thread y mode siguen aplicándose con normalidad a la nueva sesión de OpenClaw que se 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, el inicio falla con un error claro; no se recurre silenciosamente a una sesión nueva.

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

1. Verificar la versión y el commit del Gateway desplegado en el host de destino.
2. Abrir una sesión puente ACPX temporal con un agente real.
3. Pedir a ese agente que invoque sessions_spawn con runtime: "acp", agentId: "codex", mode: "run" y la tarea Reply with exactly LIVE-ACP-SPAWN-OK.
4. Verificar accepted=yes, un childSessionKey real y la ausencia de errores de validación.
5. Limpiar la sesión puente temporal.

Mantenga la puerta de control en mode: "run" y omita streamTo: "parent"; las rutas mode: "session" vinculadas a hilos y de retransmisión de flujos son pasadas de integración más completas e independientes.