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: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.
Problemas habituales de la primera ejecución
Problemas habituales de la primera ejecución
- Si se establece
plugins.allow, este constituye un inventario restrictivo de plugins y debe incluiracpx; de lo contrario, el backend ACP instalado queda bloqueado intencionadamente (/acp doctorinforma de la entrada ausente en la lista de permitidos). - El adaptador ACP de Codex se incluye con el plugin
acpxy se inicia localmente cuando es posible. - Codex ACP se ejecuta con un
CODEX_HOMEaislado. 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_modey los campos seguros demodel_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
npxdurante 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.
Requisitos previos del entorno de ejecución
Requisitos previos del entorno de ejecución
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 doctorinforma de un backend habilitado y en buen estado.- El identificador de destino está permitido por
acp.allowedAgentscuando 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
cwdsolicitado existe y es accesible; de lo contrario, se puede omitircwdpara 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.
Entornos de destino compatibles
Con el backendacpx, 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 status4
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).Detalles del ciclo de vida
Detalles del ciclo de vida
- 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 ...,/statusy/unfocusnunca se envían como texto normal de una instrucción a un entorno ACP vinculado. cancelcancela el turno activo cuando el backend admite cancelación; no elimina la vinculación ni los metadatos de la sesión.closefinaliza 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.
Reglas de enrutamiento nativo de Codex
Reglas de enrutamiento nativo de Codex
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.”
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.Guía rápida para seleccionar modelo, proveedor y entorno de ejecución
Guía rápida para seleccionar modelo, proveedor y entorno de ejecución
- 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 ...oruntime: "acp": control explícito de ACP/acpx.
Activadores en lenguaje natural para el enrutamiento de ACP
Activadores en lenguaje natural para el enrutamiento de ACP
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.”
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 plugincodex
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:- Plano de control de sesiones ACP de OpenClaw.
- Plugin oficial del entorno de ejecución
@openclaw/acpx. - Adaptador ACP de Claude.
- Mecanismos de entorno de ejecución/sesión del lado de Claude.
- ¿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:
Reglas de vinculación y exclusividad
Reglas de vinculación y exclusividad
--bind herey--thread ...son mutuamente excluyentes.--bind heresolo 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,
spawnSessionscontrola 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;/statusy/unfocustambién permanecen locales siempre que la gestión de comandos esté habilitada para esa superficie.
Sesiones vinculadas a hilos
Sesiones vinculadas a hilos
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,/statusy/unfocusson comandos del Gateway, no instrucciones para el entorno ACP.
acp.enabled=trueacp.dispatch.enabledestá activado de forma predeterminada (establezcafalsepara pausar el envío automático de hilos ACP; las llamadas explícitas asessions_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
- Discord/Telegram:
Canales compatibles con hilos
Canales compatibles con hilos
- 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 entradasbindings[] 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+15555550123para chats directos y JID de grupos de WhatsApp como120363424282127706@g.uspara grupos. - MD/grupo de iMessage:
match.channel="imessage"+match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>". Se prefierechat_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 usaragents.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.,codexoclaude)agents.entries.*.runtime.acp.backendagents.entries.*.runtime.acp.modeagents.entries.*.runtime.acp.cwd
bindings[].acp.*agents.entries.*.runtime.acp.*- 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,
/newy/resetrestablecen 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
cwdexplí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:- Desde sessions_spawn
- Desde el comando /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.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
- --bind here|off
- --thread auto|here|off
Notas:
--bind herees la ruta más sencilla para que un operador «haga que este canal o chat esté respaldado por Codex».--bind hereno crea un hilo secundario.--bind heresolo está disponible en canales que admiten la vinculación con la conversación actual.--bindy--threadno 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.Sesiones interactivas de ACP
Sesiones interactivas de ACP
Las sesiones interactivas están destinadas a mantener la conversación en una superficie de chat visible:
/acp spawn ... --bind herevincula 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 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
/acpy 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.
Sesiones ACP de ejecución única propiedad del agente principal
Sesiones ACP de ejecución única propiedad del agente principal
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.
sessions_send y entrega A2A
sessions_send y entrega A2A
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.
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.Reanudar una sesión existente
Reanudar una sesión existente
Use Casos de uso habituales:
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.- 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.
resumeSessionIdsolo se aplica cuandoruntime: "acp"; el entorno de ejecución predeterminado de subagentes ignora este campo exclusivo de ACP.streamTosolo se aplica cuandoruntime: "acp"; el entorno de ejecución predeterminado de subagentes ignora este campo exclusivo de ACP.resumeSessionIdes 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.resumeSessionIdrestaura el historial de conversación de ACP ascendente;threadymodesiguen aplicándose con normalidad a la nueva sesión de OpenClaw que se está creando, por lo quemode: "session"sigue requiriendothread: 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.
Prueba de humo posterior al despliegue
Prueba de humo posterior al despliegue
Después de desplegar un Gateway, ejecute una comprobación integral real en lugar de confiar
en las pruebas unitarias:
- Verificar la versión y el commit del Gateway desplegado en el host de destino.
- Abrir una sesión puente ACPX temporal con un agente real.
- Pedir a ese agente que invoque
sessions_spawnconruntime: "acp",agentId: "codex",mode: "run"y la tareaReply with exactly LIVE-ACP-SPAWN-OK. - Verificar
accepted=yes, unchildSessionKeyreal y la ausencia de errores de validación. - Limpiar la sesión puente temporal.
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. 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_spawnconruntime: "acp"no admitesandbox: "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:
- El argumento de destino explícito (o
--sessionpara/acp steer)- prueba primero la clave
- después, el identificador de sesión con formato UUID
- y, por último, la etiqueta
- La vinculación del hilo actual (si esta conversación o hilo está vinculado a una sesión ACP).
- La sesión solicitante actual como alternativa.
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.