Skip to main content
Las sesiones del Protocolo de cliente de agentes (ACP) permiten que OpenClaw ejecute entornos externos de programación (Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI y otros entornos ACPX compatibles) mediante un plugin de backend ACP. Cada ejecución se registra como una tarea en segundo plano.
ACP es la vía para entornos externos, no la vía predeterminada de Codex. El plugin nativo del servidor de aplicaciones de Codex gestiona los controles /codex ... y el entorno de ejecución integrado openai/gpt-* predeterminado para los turnos del agente; ACP gestiona los controles /acp ... y las sesiones sessions_spawn({ runtime: "acp" }).Para permitir que Codex o Claude Code se conecten directamente como clientes MCP externos a conversaciones existentes de canales de OpenClaw, se debe usar openclaw mcp serve en lugar de ACP.

¿Qué página necesito?

¿Funciona sin configuración adicional?

Sí, después de instalar el plugin oficial del entorno de ejecución ACP:
Los repositorios de código fuente pueden usar el plugin local del espacio de trabajo extensions/acpx después de pnpm install. Se debe ejecutar /acp doctor para comprobar que esté preparado. OpenClaw solo informa a los agentes sobre la creación de procesos ACP cuando ACP es realmente utilizable: ACP debe estar habilitado, el despacho no debe estar deshabilitado, la sesión actual no debe estar bloqueada por el entorno aislado y debe haber un backend de ejecución cargado y en buen estado. Si alguna condición no se cumple, las Skills de ACP y las instrucciones de ACP de sessions_spawn permanecen ocultas para que el agente no sugiera un backend no disponible.
  • 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.
Las herramientas de plugins de OpenClaw y las herramientas integradas de OpenClaw no se exponen de forma predeterminada a los entornos ACP. Los puentes MCP explícitos solo deben habilitarse en Agentes ACP: configuración cuando el entorno deba invocar esas herramientas directamente.

Entornos de destino compatibles

Con el backend acpx, se deben usar estos identificadores como destinos /acp spawn <id> o sessions_spawn({ runtime: "acp", agentId: "<id>" }): pi (pi-acp) también está registrado en el backend acpx, pero no es un entorno de programación en el mismo sentido que los anteriores. Los alias personalizados de agentes acpx pueden configurarse en el propio acpx, pero la política de OpenClaw sigue comprobando acp.allowedAgents y cualquier asignación de agents.entries.*.runtime.acp.agent antes del despacho.

Guía operativa

Flujo rápido de /acp desde el chat:
1

Iniciar

/acp spawn claude --bind here, /acp spawn gemini --mode persistent --thread auto o /acp spawn codex --bind here explícito.
2

Trabajar

Se continúa en la conversación o el hilo vinculados (o se especifica explícitamente la clave de sesión).
3

Comprobar el estado

/acp status
4

Ajustar

/acp model <provider/model>, /acp permissions <profile>, /acp timeout <seconds>.
5

Orientar

Sin reemplazar el contexto: /acp steer tighten logging and continue.
6

Detener

/acp cancel (turno actual) o /acp close (sesión y vinculaciones).
  • 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.

ACP frente a subagentes

Utilice ACP cuando necesite un entorno de ejecución externo. Utilice el servidor de aplicaciones nativo de Codex para vincular/controlar conversaciones de Codex cuando el plugin codex esté habilitado. Utilice subagentes cuando necesite ejecuciones delegadas nativas de OpenClaw. Consulte también Subagentes.

Cómo ejecuta ACP Claude Code

Para Claude Code mediante ACP, la pila es:
  1. Plano de control de sesiones ACP de OpenClaw.
  2. Plugin oficial del entorno de ejecución @openclaw/acpx.
  3. Adaptador ACP de Claude.
  4. Mecanismos de entorno de ejecución/sesión del lado de Claude.
Claude mediante ACP es una sesión de entorno con controles ACP, reanudación de sesiones, seguimiento de tareas en segundo plano y vinculación opcional de conversaciones/hilos. Los backends de CLI son entornos de ejecución locales alternativos independientes y solo de texto; consulte Backends de CLI. Para los operadores, la regla práctica es:
  • ¿Necesita /acp spawn, sesiones vinculables, controles del entorno de ejecución o trabajo persistente del entorno? Utilice ACP.
  • ¿Necesita una alternativa local sencilla de texto mediante la CLI sin procesar? Utilice backends de CLI.

Sesiones vinculadas

Modelo mental

  • Superficie de chat: donde las personas continúan hablando (canal de Discord, tema de Telegram, chat de iMessage).
  • Sesión ACP: el estado duradero del entorno de ejecución de Codex/Claude/Gemini al que OpenClaw dirige los mensajes.
  • Hilo/tema secundario: una superficie de mensajería adicional opcional creada únicamente por --thread ....
  • Espacio de trabajo del entorno de ejecución: la ubicación del sistema de archivos (cwd, copia de trabajo del repositorio, espacio de trabajo del backend) donde se ejecuta el entorno. Es independiente de la superficie de chat.

Vinculaciones con la conversación actual

/acp spawn <harness> --bind here fija la conversación actual a la sesión ACP creada: sin hilo secundario y en la misma superficie de chat. OpenClaw sigue controlando el transporte, la autenticación, la seguridad y la entrega. Los mensajes de seguimiento de esa conversación se dirigen a la misma sesión; /new y /reset restablecen la sesión sin sustituirla; /acp close elimina la vinculación. Ejemplos:
  • --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.

Vinculaciones persistentes de canales

Para flujos de trabajo no efímeros, configure vinculaciones ACP persistentes en las entradas bindings[] del nivel superior.

Modelo de vinculación

"acp"
Marca una vinculación persistente de conversación ACP.
object
Identifica la conversación de destino. Formas específicas de cada canal:
  • Canal/hilo de Discord: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Canal/MD de Slack: match.channel="slack" + match.peer.id="<channelId|channel:<channelId>|#<channelId>|userId|user:<userId>|slack:<userId>|<@userId>>". Se prefieren los identificadores estables de Slack; las vinculaciones de canales también coinciden con las respuestas dentro de los hilos de ese canal.
  • Tema de foro de Telegram: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • MD/grupo de WhatsApp: match.channel="whatsapp" + match.peer.id="<E.164|group JID>". Se deben usar números E.164 como +15555550123 para chats directos y JID de grupos de WhatsApp como 120363424282127706@g.us para grupos.
  • MD/grupo de iMessage: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>". Se prefiere chat_id:* para vinculaciones estables de grupos.
string
El identificador del agente de OpenClaw propietario.
"persistent" | "oneshot"
Anulación opcional de ACP.
string
Etiqueta opcional visible para el operador.
string
Directorio de trabajo opcional del entorno de ejecución.
string
Anulación opcional del backend.

Valores predeterminados del entorno de ejecución por agente

Se debe usar agents.entries.*.runtime para definir los valores predeterminados de ACP una vez por agente:
  • agents.entries.*.runtime.type="acp"
  • agents.entries.*.runtime.acp.agent (identificador del arnés, p. ej., codex o claude)
  • agents.entries.*.runtime.acp.backend
  • agents.entries.*.runtime.acp.mode
  • agents.entries.*.runtime.acp.cwd
Precedencia de anulaciones para sesiones vinculadas de ACP:
  1. bindings[].acp.*
  2. agents.entries.*.runtime.acp.*
  3. Valores predeterminados globales de ACP (p. ej., acp.backend)

Ejemplo

Comportamiento

  • OpenClaw garantiza que la sesión de ACP configurada exista después de la admisión específica del canal y antes de usarla.
  • Los mensajes de ese canal, tema o chat se enrutan a la sesión de ACP configurada.
  • Las vinculaciones de ACP configuradas controlan la ruta de su sesión. La distribución de difusión del canal no sustituye la sesión de ACP configurada para una vinculación coincidente.
  • En las conversaciones vinculadas, /new y /reset restablecen en el mismo lugar la misma clave de sesión de ACP.
  • Las vinculaciones temporales del entorno de ejecución (por ejemplo, las creadas por flujos de enfoque de hilos) siguen aplicándose cuando están presentes.
  • Para generaciones de ACP entre agentes sin un cwd explícito, OpenClaw hereda el espacio de trabajo del agente de destino de la configuración del agente.
  • Si faltan las rutas heredadas del espacio de trabajo, se utiliza el cwd predeterminado del backend; los errores de acceso a rutas existentes se presentan como errores de generación.

Iniciar sesiones de ACP

Hay dos formas de iniciar una sesión de ACP:
Se debe usar runtime: "acp" para iniciar una sesión de ACP desde un turno del agente o una llamada a una herramienta.
runtime tiene como valor predeterminado subagent, por lo que se debe establecer runtime: "acp" explícitamente para las sesiones de ACP. Si se omite agentId, OpenClaw usa acp.defaultAgent cuando está configurado. mode: "session" requiere thread: true para mantener una conversación vinculada persistente.

Parámetros de sessions_spawn

string
requerido
Solicitud inicial enviada a la sesión de ACP.
"acp"
requerido
Debe ser "acp" para las sesiones de ACP.
string
Identificador del arnés de destino de ACP. Si se ha establecido, se utiliza acp.defaultAgent como alternativa.
boolean
predeterminado:"false"
Solicita el flujo de vinculación de hilos cuando sea compatible.
"run" | "session"
predeterminado:"run"
"run" es de una sola ejecución; "session" es persistente. Si se especifica thread: true y se omite mode, OpenClaw puede utilizar de forma predeterminada el comportamiento persistente según la ruta del entorno de ejecución. mode: "session" requiere thread: true.
string
Directorio de trabajo solicitado del entorno de ejecución (validado por la política del backend o del entorno de ejecución). Si se omite, la generación de ACP hereda el espacio de trabajo del agente de destino cuando está configurado; si faltan las rutas heredadas, se utilizan los valores predeterminados del backend, mientras que los errores de acceso reales se devuelven.
string
Etiqueta visible para el operador que se utiliza en el texto de la sesión o del banner.
string
Reanuda una sesión de ACP existente en lugar de crear una nueva. El agente reproduce su historial de conversación mediante session/load. Requiere runtime: "acp".
"parent"
"parent" transmite los resúmenes del progreso de la ejecución inicial de ACP a la sesión solicitante como eventos del sistema. OpenClaw registra el historial completo de la retransmisión en el estado SQLite del agente secundario y lo elimina junto con la sesión secundaria. De forma predeterminada, los flujos de progreso del padre muestran los comentarios del asistente y el progreso de estado de ACP, salvo que streaming.progress.commentary=false. Discord también usa de forma predeterminada el modo de progreso para las vistas previas del padre cuando no se configura ningún modo de transmisión. El progreso de estado sigue respetando acp.stream.tagVisibility, por lo que las etiquetas como plan permanecen ocultas salvo que se habiliten explícitamente.
Las ejecuciones sessions_spawn de ACP usan agents.defaults.subagents.runTimeoutSeconds como límite predeterminado de turnos secundarios. La herramienta no acepta anulaciones de tiempo de espera por llamada (runTimeoutSeconds/timeoutSeconds se rechazan con un error que indica que debe configurarse el valor predeterminado).
string
Anulación explícita del modelo para la sesión secundaria de ACP. Las generaciones de ACP de Codex normalizan las referencias de OpenAI, como openai/gpt-5.4, a la configuración de inicio de ACP de Codex antes de session/new; las formas con barra diagonal, como openai/gpt-5.4/high, también establecen el esfuerzo de razonamiento de ACP de Codex. Cuando se omite, sessions_spawn({ runtime: "acp" }) usa los valores predeterminados existentes del modelo de subagente (agents.defaults.subagents.model o agents.entries.*.subagents.model) cuando están configurados; de lo contrario, permite que el arnés de ACP use su propio modelo predeterminado. Los demás arneses deben anunciar la capacidad ACP models y ser compatibles con session/set_model; de lo contrario, OpenClaw/acpx falla claramente en lugar de utilizar silenciosamente el valor predeterminado del agente de destino.
string
Esfuerzo explícito de pensamiento o razonamiento. Para ACP de Codex, minimal se asigna a un esfuerzo bajo, low/medium/high/xhigh se asignan directamente y off omite la anulación del esfuerzo de razonamiento durante el inicio. Cuando se omite, las generaciones de ACP usan los valores predeterminados existentes de pensamiento del subagente y el valor agents.defaults.models["provider/model"].params.thinking por modelo para el modelo seleccionado.

Modos de vinculación y de hilo de la generación

Notas:
  • --bind here es la ruta más sencilla para que un operador «haga que este canal o chat esté respaldado por Codex».
  • --bind here no crea un hilo secundario.
  • --bind here solo está disponible en canales que admiten la vinculación con la conversación actual.
  • --bind y --thread no pueden combinarse en la misma llamada a /acp spawn.

Modelo de entrega

Las sesiones de ACP pueden ser espacios de trabajo interactivos o trabajo en segundo plano controlado por el padre. La ruta de entrega depende de esa modalidad.
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 <<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>> 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.
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.

Compatibilidad con el entorno aislado

Actualmente, las sesiones ACP se ejecutan en el entorno de ejecución del host, no dentro del entorno aislado de OpenClaw.
Límite de seguridad:
  • El arnés externo puede leer y escribir según sus propios permisos de la CLI y el cwd seleccionado.
  • La política del entorno aislado de OpenClaw no engloba la ejecución del arnés ACP.
  • OpenClaw sigue aplicando las puertas de funciones de ACP, los agentes permitidos, la propiedad de las sesiones, las vinculaciones de canales y la política de entrega del Gateway.
  • Use runtime: "subagent" para trabajos nativos de OpenClaw sujetos al entorno aislado.
Limitaciones actuales:
  • Si la sesión solicitante está aislada, los inicios de ACP se bloquean tanto para sessions_spawn({ runtime: "acp" }) como para /acp spawn.
  • sessions_spawn con runtime: "acp" no admite sandbox: "require".

Resolución del destino de sesión

La mayoría de las acciones de /acp aceptan un destino de sesión opcional (session-key, session-id o session-label). Orden de resolución:
  1. El argumento de destino explícito (o --session para /acp steer)
    • prueba primero la clave
    • después, el identificador de sesión con formato UUID
    • y, por último, la etiqueta
  2. La vinculación del hilo actual (si esta conversación o hilo está vinculado a una sesión ACP).
  3. La sesión solicitante actual como alternativa.
Tanto las vinculaciones de la conversación actual como las del hilo participan en el paso 2. Si no se resuelve ningún destino, OpenClaw devuelve un error claro (Unable to resolve session target: ...).

Controles de ACP

Los controles del entorno de ejecución (spawn, cancel, steer, close, status, set-mode, set, cwd, permissions, timeout, model y reset-options) requieren la identidad del propietario desde canales externos y operator.admin desde clientes internos del Gateway. Los remitentes autorizados que no sean propietarios aún pueden usar sessions, doctor, install y help. Para los remitentes que no sean propietarios, /acp sessions solo enumera la sesión vinculada actual o la sesión solicitante; la identidad del propietario y los clientes operator.admin ven todas las sesiones recientes. /acp status muestra las opciones efectivas del entorno de ejecución, además de los identificadores de sesión del nivel del entorno de ejecución y del nivel del backend. Los errores de controles no compatibles se muestran claramente cuando un backend carece de una capacidad. Los comandos que aceptan tokens de destino (session-key, session-id o session-label) los resuelven mediante el descubrimiento de sesiones del Gateway, incluidas las raíces session.store personalizadas de cada agente. /acp sessions no acepta ningún token de destino.

Asignación de opciones del entorno de ejecución

/acp dispone de comandos prácticos y un establecedor genérico. Operaciones equivalentes:

Entorno de pruebas acpx, configuración de plugins y permisos

Para conocer la configuración del entorno de pruebas acpx (alias de Claude Code, Codex y Gemini CLI), los puentes MCP de herramientas de plugins y herramientas de OpenClaw, y los modos de permisos de ACP, consulte Agentes ACP: configuración.

Solución de problemas

Command blocked by PreToolUse hook: Native hook relay unavailable pertenece al retransmisor de hooks nativo de Codex, no a ACP/acpx. En un chat de Codex vinculado, inicie una sesión nueva con /new o /reset; si funciona una vez y vuelve a aparecer en la siguiente llamada de herramienta nativa, reinicie el servidor de aplicaciones de Codex o el Gateway de OpenClaw en lugar de repetir /new. Consulte Solución de problemas del entorno de pruebas de Codex.

Temas relacionados