---
read_when:
- Ejecutar arneses de codificación mediante ACP
- Configurar sesiones ACP vinculadas a conversaciones en canales de mensajería
- Vincular una conversación de canal de mensajes a una sesión ACP persistente
- Solución de problemas del backend ACP, el cableado de plugins o la entrega de finalización
- Operar comandos /acp desde el chat
sidebarTitle: ACP agents
summary: Ejecuta arneses de codificación externos (Claude Code, Cursor, Gemini CLI, ACP explícito de Codex, ACP de OpenClaw, OpenCode) mediante el backend ACP
title: Agentes ACP
x-i18n:
generated_at: "2026-06-30T13:48:46Z"
model: gpt-5.5
postprocess_version: locale-links-v1
provider: openai
source_hash: c61edbc3b5a8303dc88e27a1315fe996da70eeee7aa211877d5680eb150e36cb
source_path: tools/acp-agents.md
workflow: 16
---
Las sesiones de [Agent Client Protocol (ACP)](https://agentclientprotocol.com/)
permiten que OpenClaw ejecute arneses de codificación externos (por ejemplo,
Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI y otros
arneses ACPX compatibles) mediante un plugin de backend ACP.
Cada generación de sesión ACP se rastrea como una [tarea en segundo plano](/es/automation/tasks).
**ACP es la ruta de arneses externos, no la ruta predeterminada de Codex.** El
plugin nativo de servidor de aplicaciones Codex es propietario de los controles
`/codex ...` y del runtime integrado `openai/gpt-*` predeterminado para los
turnos de agente; ACP es propietario de los controles `/acp ...` y de las
sesiones `sessions_spawn({ runtime: "acp" })`.
Si quieres que Codex o Claude Code se conecten como cliente MCP externo
directamente a conversaciones existentes de canales de OpenClaw, usa
[`openclaw mcp serve`](/es/cli/mcp) en lugar de ACP.
## ¿Qué página necesito?
| Quieres… | Usa esto | Notas |
| ---------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Vincular o controlar Codex en la conversación actual | `/codex bind`, `/codex threads` | Ruta nativa del servidor de aplicaciones Codex cuando el plugin `codex` está habilitado; incluye respuestas de chat vinculadas, reenvío de imágenes, modelo/rápido/permisos, detener y controles de dirección. ACP es una alternativa explícita |
| Ejecutar Claude Code, Gemini CLI, Codex ACP explícito u otro arnés externo _a través_ de OpenClaw | Esta página | Sesiones vinculadas al chat, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, tareas en segundo plano, controles de runtime |
| Exponer una sesión de OpenClaw Gateway _como_ servidor ACP para un editor o cliente | [`openclaw acp`](/es/cli/acp) | Modo puente. El IDE/cliente habla ACP con OpenClaw mediante stdio/WebSocket |
| Reutilizar una CLI de IA local como modelo de respaldo solo de texto | [Backends de CLI](/es/gateway/cli-backends) | No es ACP. Sin herramientas de OpenClaw, sin controles ACP, sin runtime de arnés |
## ¿Funciona directamente?
Sí, después de instalar el plugin oficial de runtime ACP:
```bash
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
```
Los checkouts de código fuente pueden usar el plugin local del workspace
`extensions/acpx` después de `pnpm install`. Ejecuta `/acp doctor` para una
comprobación de preparación.
OpenClaw solo informa a los agentes sobre la generación 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 sandbox y debe
haberse cargado un backend de runtime. Si esas condiciones no se cumplen, las
Skills del plugin ACP y la guía ACP de `sessions_spawn` permanecen ocultas para
que el agente no sugiera un backend no disponible.
- Si `plugins.allow` está definido, es un inventario restrictivo de plugins y **debe** incluir `acpx`; de lo contrario, el backend ACP instalado se bloquea intencionadamente y `/acp doctor` informa la entrada faltante en la lista de permitidos.
- El adaptador Codex ACP se prepara con el plugin `acpx` y se inicia localmente cuando es posible.
- Codex ACP se ejecuta con un `CODEX_HOME` aislado; OpenClaw copia entradas de proyectos de confianza y configuración segura de enrutamiento de modelo/proveedor desde la configuración de Codex del host, mientras que la autenticación, las notificaciones y los hooks permanecen en la configuración del host.
- Otros adaptadores de arneses de destino todavía pueden obtenerse bajo demanda con `npx` la primera vez que los uses.
- La autenticación del proveedor todavía debe existir en el host para ese arnés.
- Si el host no tiene npm ni acceso a la red, las obtenciones de adaptadores en la primera ejecución fallan hasta que las cachés se precalienten o el adaptador se instale de otra forma.
ACP inicia un proceso real de arnés externo. OpenClaw es propietario del
enrutamiento, el estado de tareas en segundo plano, la entrega, las
vinculaciones y la política; el arnés es propietario de su inicio de sesión
de proveedor, catálogo de modelos, comportamiento del sistema de archivos y
herramientas nativas.
Antes de culpar a OpenClaw, verifica:
- `/acp doctor` informa un backend habilitado y saludable.
- El ID de destino está permitido por `acp.allowedAgents` cuando esa lista de permitidos está definida.
- El comando del arnés puede iniciarse en el host del Gateway.
- La autenticación del proveedor está presente para ese arnés (`claude`, `codex`, `gemini`, `opencode`, `droid`, etc.).
- El modelo seleccionado existe para ese arnés; los ID de modelo no son portátiles entre arneses.
- El `cwd` solicitado existe y es accesible, o 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 prompts de permisos nativos, por lo que las ejecuciones de codificación con mucha escritura/ejecución suelen necesitar un perfil de permisos ACPX que pueda avanzar sin interfaz.
Las herramientas de plugins de OpenClaw y las herramientas integradas de
OpenClaw **no** se exponen a los arneses ACP de forma predeterminada. Habilita
los puentes MCP explícitos en [Agentes ACP: configuración](/es/tools/acp-agents-setup)
solo cuando el arnés deba llamar a esas herramientas directamente.
## Objetivos de arnés compatibles
Con el backend `acpx`, usa estos ID de arnés como objetivos de
`/acp spawn ` o `sessions_spawn({ runtime: "acp", agentId: "" })`:
| ID de arnés | Backend habitual | Notas |
| ----------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
| `claude` | Adaptador Claude Code ACP | Requiere autenticación de Claude Code en el host. |
| `codex` | Adaptador Codex ACP | Alternativa ACP explícita solo cuando `/codex` nativo no está disponible o se solicita ACP. |
| `copilot` | Adaptador GitHub Copilot ACP | Requiere autenticación de CLI/runtime de Copilot. |
| `cursor` | Cursor CLI ACP (`cursor-agent acp`) | Sobrescribe el comando acpx si una instalación local expone un punto de entrada ACP diferente. |
| `droid` | Factory Droid CLI | Requiere autenticación de Factory/Droid o `FACTORY_API_KEY` en el entorno del arnés. |
| `gemini` | Adaptador Gemini CLI ACP | Requiere autenticación de Gemini CLI o configuración de clave de API. |
| `iflow` | iFlow CLI | La disponibilidad del adaptador y el control del modelo dependen de la CLI instalada. |
| `kilocode` | Kilo Code CLI | La disponibilidad del adaptador y el control del modelo dependen de la CLI instalada. |
| `kimi` | Kimi/Moonshot CLI | Requiere autenticación de Kimi/Moonshot en el host. |
| `kiro` | Kiro CLI | La disponibilidad del adaptador y el control del modelo dependen de la CLI instalada. |
| `opencode` | Adaptador OpenCode ACP | Requiere autenticación de CLI/proveedor de OpenCode. |
| `openclaw` | Puente de OpenClaw Gateway mediante `openclaw acp` | Permite que un arnés compatible con ACP hable de vuelta con una sesión de OpenClaw Gateway. |
| `qwen` | Qwen Code / Qwen CLI | Requiere autenticación compatible con Qwen en el host. |
Los alias personalizados de agentes acpx pueden configurarse en acpx, pero la
política de OpenClaw todavía comprueba `acp.allowedAgents` y cualquier mapeo
`agents.list[].runtime.acp.agent` antes del despacho.
## Runbook del operador
Flujo rápido de `/acp` desde el chat:
`/acp spawn claude --bind here`,
`/acp spawn gemini --mode persistent --thread auto` o
`/acp spawn codex --bind here` explícito.
Continúa en la conversación o el hilo vinculado (o dirige la sesión
mediante la clave explícitamente).
`/acp status`
`/acp model `,
`/acp permissions `,
`/acp timeout `.
Sin reemplazar el contexto: `/acp steer tighten logging and continue`.
`/acp cancel` (turno actual) o `/acp close` (sesión + vinculaciones).
- La generación crea o reanuda una sesión de runtime ACP, registra metadatos ACP en el almacén de sesiones de OpenClaw y puede crear una tarea en segundo plano cuando la ejecución pertenece al padre.
- Las sesiones ACP que pertenecen al padre se tratan como trabajo en segundo plano incluso cuando la sesión de runtime es persistente; la finalización y la entrega entre superficies pasan por el notificador de tareas padre en lugar de comportarse como una sesión de chat normal visible para el usuario.
- El mantenimiento de tareas cierra sesiones ACP de un solo uso, terminales o huérfanas, que pertenecen al padre. Las sesiones ACP persistentes se conservan mientras exista una vinculación activa de conversación; las sesiones persistentes obsoletas sin una vinculación activa se cierran para que no puedan reanudarse silenciosamente después de que la tarea propietaria termine o desaparezca su registro de tarea.
- Los mensajes de seguimiento vinculados van directamente a la sesión ACP hasta que la vinculación se cierre, pierda el foco, se restablezca o caduque.
- Los comandos de Gateway permanecen locales. `/acp ...`, `/status` y `/unfocus` nunca se envían como texto de prompt normal a un arnés ACP vinculado.
- `cancel` aborta el turno activo cuando el backend admite cancelación; no elimina la vinculación ni los metadatos de sesión.
- `close` finaliza la sesión ACP desde el punto de vista de OpenClaw y elimina la vinculación. Un arnés todavía puede conservar su propio historial ascendente si admite reanudación.
- El plugin acpx limpia los árboles de procesos de envoltorio y adaptador propiedad de OpenClaw después de `close`, y recolecta huérfanos ACPX obsoletos propiedad de OpenClaw durante el inicio de Gateway.
- Los workers de runtime inactivos son elegibles para limpieza después de `acp.runtime.ttlMinutes`; los metadatos de sesión almacenados permanecen disponibles para `/acp sessions`.
Disparadores en lenguaje natural que deben enrutarse al **plugin nativo de
Codex** cuando está habilitado:
- "Vincula este canal de Discord a Codex."
- "Adjunta este chat al hilo de Codex ``."
- "Muestra los hilos de Codex y luego vincula este."
La vinculación nativa de conversaciones de Codex es la ruta predeterminada de control de chat.
Las herramientas dinámicas de OpenClaw se siguen ejecutando 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 hook nativo
por turno para que los hooks de Plugin 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 más
del modelo antes de que Codex finalice su respuesta. El relé sigue siendo
deliberadamente conservador: no muta los argumentos de herramientas nativas de Codex
ni reescribe los registros de hilo de Codex. Usa ACP explícito solo
cuando quieras el modelo de runtime/sesión de ACP. El límite de soporte de Codex
embebido está documentado en el
[contrato de soporte del harness de Codex v1](/es/plugins/codex-harness-runtime#v1-support-contract).
- refs de modelo de Codex heredadas - ruta de modelo OAuth/suscripción de Codex heredada reparada por doctor.
- `openai/*` - runtime embebido del servidor de aplicaciones nativo de Codex para turnos de agente de OpenAI.
- `/codex ...` - control de conversación nativo de Codex.
- `/acp ...` o `runtime: "acp"` - control ACP/acpx explícito.
Disparadores que deben enrutar al runtime de ACP:
- "Ejecuta esto como una sesión ACP de Claude Code de una sola vez y resume el resultado."
- "Usa Gemini CLI para esta tarea en un hilo y luego mantén los seguimientos en ese mismo hilo."
- "Ejecuta Codex mediante ACP en un hilo en segundo plano."
OpenClaw elige `runtime: "acp"`, resuelve el `agentId` del harness,
se vincula a la conversación o hilo actual cuando se admite, y
enruta los seguimientos a esa sesión hasta el cierre o la expiración. Codex solo
sigue esta ruta cuando ACP/acpx es explícito o el plugin nativo de Codex
no está disponible para la operación solicitada.
Para `sessions_spawn`, `runtime: "acp"` se anuncia solo cuando ACP
está habilitado, el solicitante no está en sandbox y hay cargado un backend
de runtime ACP. `acp.dispatch.enabled=false` pausa el despacho automático
de hilos ACP, pero no oculta ni bloquea las llamadas explícitas a
`sessions_spawn({ runtime: "acp" })`. Apunta a ids de harness ACP como `codex`,
`claude`, `droid`, `gemini` u `opencode`. No pases un id normal
de agente de configuración de OpenClaw desde `agents_list` a menos que esa entrada esté
configurada explícitamente con `agents.list[].runtime.type="acp"`;
de lo contrario, usa el runtime de subagente predeterminado. Cuando un agente de OpenClaw
está configurado con `runtime.type="acp"`, OpenClaw usa
`runtime.acp.agent` como el id de harness subyacente.
## ACP frente a subagentes
Usa ACP cuando quieras un runtime de harness externo. Usa el **servidor de aplicaciones
nativo de Codex** para la vinculación/control de conversaciones de Codex cuando el plugin
`codex` esté habilitado. Usa **subagentes** cuando quieras ejecuciones delegadas
nativas de OpenClaw.
| Área | Sesión ACP | Ejecución de subagente |
| ------------------ | --------------------------------------- | ----------------------------------- |
| Runtime | Plugin de backend ACP (por ejemplo acpx) | Runtime de subagente nativo de OpenClaw |
| Clave de sesión | `agent::acp:` | `agent::subagent:` |
| Comandos principales | `/acp ...` | `/subagents ...` |
| Herramienta de spawn | `sessions_spawn` con `runtime:"acp"` | `sessions_spawn` (runtime predeterminado) |
Consulta también [Subagentes](/es/tools/subagents).
## Cómo ACP ejecuta Claude Code
Para Claude Code mediante ACP, la pila es:
1. Plano de control de sesión ACP de OpenClaw.
2. Plugin de runtime oficial `@openclaw/acpx`.
3. Adaptador ACP de Claude.
4. Maquinaria de runtime/sesión del lado de Claude.
ACP Claude es una **sesión de harness** con controles ACP, reanudación de sesión,
seguimiento de tareas en segundo plano y vinculación opcional de conversación/hilo.
Los backends de CLI son runtimes de fallback locales separados, solo de texto; consulta
[Backends de CLI](/es/gateway/cli-backends).
Para los operadores, la regla práctica es:
- **¿Quieres `/acp spawn`, sesiones vinculables, controles de runtime o trabajo persistente de harness?** Usa ACP.
- **¿Quieres un fallback local simple de texto mediante la CLI sin procesar?** Usa backends de CLI.
## Sesiones vinculadas
### Modelo mental
- **Superficie de chat** - donde las personas siguen hablando (canal de Discord, tema de Telegram, chat de iMessage).
- **Sesión ACP** - el estado de runtime duradero de Codex/Claude/Gemini al que OpenClaw enruta.
- **Hilo/tema secundario** - una superficie de mensajería adicional opcional creada solo por `--thread ...`.
- **Espacio de trabajo de runtime** - la ubicación del sistema de archivos (`cwd`, checkout del repositorio, espacio de trabajo del backend) donde se ejecuta el harness. Independiente de la superficie de chat.
### Vinculaciones de conversación actual
`/acp spawn --bind here` fija la conversación actual a la
sesión ACP generada: sin hilo secundario, misma superficie de chat. OpenClaw sigue
siendo dueño del transporte, la autenticación, la seguridad y la entrega. Los mensajes de seguimiento en esa
conversación se enrutan a la misma sesión; `/new` y `/reset` restablecen la
sesión en el lugar; `/acp close` elimina la vinculación.
Ejemplos:
```text
/codex bind # native Codex bind, route future messages here
/codex model gpt-5.4 # tune the bound native Codex thread
/codex stop # control the active native Codex turn
/acp spawn codex --bind here # explicit ACP fallback for Codex
/acp spawn codex --thread auto # may create a child thread/topic and bind there
/acp spawn codex --bind here --cwd /workspace/repo # same chat binding, Codex runs in /workspace/repo
```
- `--bind here` y `--thread ...` son mutuamente excluyentes.
- `--bind here` solo funciona en canales que anuncian vinculación de conversación actual; OpenClaw devuelve un mensaje claro de no admitido en caso contrario. Las vinculaciones persisten entre reinicios del Gateway.
- En Discord, `spawnSessions` controla la creación de hilos secundarios para `--thread auto|here`, no `--bind here`.
- Si generas hacia un agente ACP distinto sin `--cwd`, OpenClaw hereda el espacio de trabajo del **agente de destino** de forma predeterminada. Las rutas heredadas faltantes (`ENOENT`/`ENOTDIR`) recurren al valor predeterminado del backend; otros errores de acceso (por ejemplo, `EACCES`) aparecen como errores de spawn.
- Los comandos de administración del Gateway permanecen locales en conversaciones vinculadas: los comandos `/acp ...` los gestiona OpenClaw incluso cuando el texto normal de seguimiento se enruta a la sesión ACP vinculada; `/status` y `/unfocus` también permanecen locales siempre que el manejo de comandos esté habilitado para esa superficie.
Cuando las vinculaciones de hilo están habilitadas para un adaptador de canal:
- OpenClaw vincula un hilo a una sesión ACP de destino.
- Los mensajes de seguimiento en ese hilo se enrutan a la sesión ACP vinculada.
- La salida de ACP se entrega de vuelta al mismo hilo.
- Desenfoque/cierre/archivo/tiempo de inactividad o expiración por antigüedad máxima elimina la vinculación.
- `/acp close`, `/acp cancel`, `/acp status`, `/status` y `/unfocus` son comandos del Gateway, no prompts para el harness ACP.
Feature flags requeridos para ACP vinculado a hilos:
- `acp.enabled=true`
- `acp.dispatch.enabled` está activado de forma predeterminada (establece `false` para pausar el despacho automático de hilos ACP; las llamadas explícitas a `sessions_spawn({ runtime: "acp" })` siguen funcionando).
- Spawns de sesión de hilo del adaptador de canal habilitados (predeterminado: `true`):
- Discord: `channels.discord.threadBindings.spawnSessions=true`
- Telegram: `channels.telegram.threadBindings.spawnSessions=true`
El soporte de vinculación de hilos es específico del adaptador. Si el adaptador
de canal activo no admite vinculaciones de hilo, OpenClaw devuelve un mensaje claro
de no admitido/no disponible.
- Cualquier adaptador de canal que exponga capacidad de vinculación de sesión/hilo.
- Soporte integrado actual: hilos/canales de **Discord**, temas de **Telegram** (temas de foro en grupos/supergrupos y temas de DM).
- Los canales de Plugin pueden agregar soporte mediante la misma interfaz de vinculación.
## Vinculaciones persistentes de canal
Para flujos de trabajo no efímeros, configura vinculaciones ACP persistentes en
entradas de nivel superior `bindings[]`.
### Modelo de vinculación
Marca una vinculación persistente de conversación ACP.
Identifica la conversación de destino. Formas por canal:
- **Canal/hilo de Discord:** `match.channel="discord"` + `match.peer.id=""`
- **Canal/DM de Slack:** `match.channel="slack"` + `match.peer.id="|#|userId|user:|slack:|<@userId>>"`. Prefiere ids estables de Slack; las vinculaciones de canal también coinciden con respuestas dentro de los hilos de ese canal.
- **Tema de foro de Telegram:** `match.channel="telegram"` + `match.peer.id=":topic:"`
- **DM/grupo de WhatsApp:** `match.channel="whatsapp"` + `match.peer.id=""`. Usa números E.164 como `+15555550123` para chats directos y JIDs de grupo de WhatsApp como `120363424282127706@g.us` para grupos.
- **DM/grupo de iMessage:** `match.channel="imessage"` + `match.peer.id=""`. Prefiere `chat_id:*` para vinculaciones de grupo estables.
El id del agente propietario de OpenClaw.
Anulación ACP opcional.
Etiqueta opcional orientada al operador.
Directorio de trabajo de runtime opcional.
Anulación de backend opcional.
### Valores predeterminados de runtime por agente
Usa `agents.list[].runtime` para definir valores predeterminados de ACP una vez por agente:
- `agents.list[].runtime.type="acp"`
- `agents.list[].runtime.acp.agent` (id de harness, por ejemplo `codex` o `claude`)
- `agents.list[].runtime.acp.backend`
- `agents.list[].runtime.acp.mode`
- `agents.list[].runtime.acp.cwd`
**Precedencia de anulación para sesiones vinculadas ACP:**
1. `bindings[].acp.*`
2. `agents.list[].runtime.acp.*`
3. Valores predeterminados globales de ACP (por ejemplo `acp.backend`)
### Ejemplo
```json5
{
agents: {
list: [
{
id: "codex",
runtime: {
type: "acp",
acp: {
agent: "codex",
backend: "acpx",
mode: "persistent",
cwd: "/workspace/openclaw",
},
},
},
{
id: "claude",
runtime: {
type: "acp",
acp: { agent: "claude", backend: "acpx", mode: "persistent" },
},
},
],
},
bindings: [
{
type: "acp",
agentId: "codex",
match: {
channel: "discord",
accountId: "default",
peer: { kind: "channel", id: "222222222222222222" },
},
acp: { label: "codex-main" },
},
{
type: "acp",
agentId: "claude",
match: {
channel: "telegram",
accountId: "default",
peer: { kind: "group", id: "-1001234567890:topic:42" },
},
acp: { cwd: "/workspace/repo-b" },
},
{
type: "route",
agentId: "main",
match: { channel: "discord", accountId: "default" },
},
{
type: "route",
agentId: "main",
match: { channel: "telegram", accountId: "default" },
},
],
channels: {
discord: {
guilds: {
"111111111111111111": {
channels: {
"222222222222222222": { requireMention: false },
},
},
},
},
telegram: {
groups: {
"-1001234567890": {
topics: { "42": { requireMention: false } },
},
},
},
},
}
```
### Comportamiento
- OpenClaw garantiza que la sesión ACP configurada exista después de la admisión específica del canal y antes de su uso.
- Los mensajes en ese canal, tema o chat se enrutan a la sesión ACP configurada.
- Los enlaces ACP configurados son propietarios de su ruta de sesión. La difusión ramificada del canal no reemplaza la sesión ACP configurada para un enlace coincidente.
- En conversaciones vinculadas, `/new` y `/reset` restablecen la misma clave de sesión ACP en el mismo lugar.
- Los enlaces temporales de runtime (por ejemplo, creados por flujos de enfoque de hilo) siguen aplicándose donde estén presentes.
- Para creaciones ACP entre agentes sin un `cwd` explícito, OpenClaw hereda el espacio de trabajo del agente de destino desde la configuración del agente.
- Las rutas de espacio de trabajo heredadas que faltan recurren al cwd predeterminado del backend; los errores de acceso no faltantes se muestran como errores de creación.
## Iniciar sesiones ACP
Dos formas de iniciar una sesión ACP:
Usa `runtime: "acp"` para iniciar una sesión ACP desde un turno de agente o
una llamada de herramienta.
```json
{
"task": "Open the repo and summarize failing tests",
"runtime": "acp",
"agentId": "codex",
"thread": true,
"mode": "session"
}
```
`runtime` tiene como valor predeterminado `subagent`, así que establece `runtime: "acp"` explícitamente
para las sesiones ACP. Si se omite `agentId`, OpenClaw usa
`acp.defaultAgent` cuando está configurado. `mode: "session"` requiere
`thread: true` para mantener una conversación vinculada persistente.
Usa `/acp spawn` para un control explícito del operador desde el chat.
```text
/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --bind here
/acp spawn codex --thread here
```
Flags clave:
- `--mode persistent|oneshot`
- `--bind here|off`
- `--thread auto|here|off`
- `--cwd `
- `--label `
Consulta [Comandos slash](/es/tools/slash-commands).
### Parámetros de `sessions_spawn`
Prompt inicial enviado a la sesión ACP.
Debe ser `"acp"` para las sesiones ACP.
Id. del harness ACP de destino. Recurre a `acp.defaultAgent` si está definido.
Solicita el flujo de enlace de hilo donde sea compatible.
`"run"` es de una sola ejecución; `"session"` es persistente. Si `thread: true` y
se omite `mode`, OpenClaw puede usar de forma predeterminada un comportamiento persistente según la
ruta de runtime. `mode: "session"` requiere `thread: true`.
Directorio de trabajo de runtime solicitado (validado por la política de
backend/runtime). Si se omite, la creación ACP hereda el espacio de trabajo del agente
de destino cuando está configurado; las rutas heredadas que faltan recurren a los
valores predeterminados del backend, mientras que se devuelven los errores de acceso reales.
Etiqueta visible para el operador utilizada en el texto de sesión/banner.
Reanuda una sesión ACP existente en lugar de crear una nueva. El
agente reproduce su historial de conversación mediante `session/load`. Requiere
`runtime: "acp"`.
`"parent"` transmite los resúmenes de progreso de la ejecución ACP inicial de vuelta a la
sesión solicitante como eventos del sistema. Las respuestas aceptadas incluyen
`streamLogPath`, que apunta a un registro JSONL con ámbito de sesión
(`.acp-stream.jsonl`) que puedes seguir para ver el historial completo de retransmisión.
Las transmisiones de progreso al padre muestran comentarios del asistente y progreso de estado ACP de forma
predeterminada, salvo que `streaming.progress.commentary=false`. Discord también establece de forma predeterminada
las vistas previas del padre en modo de progreso cuando no hay un modo de transmisión configurado. El progreso de
estado sigue respetando `acp.stream.tagVisibility`, así que etiquetas como `plan`
permanecen ocultas salvo que se habiliten explícitamente.
Las ejecuciones ACP de `sessions_spawn` usan `agents.defaults.subagents.runTimeoutSeconds` para
su límite predeterminado de turno hijo. La herramienta no acepta anulaciones de tiempo de espera
por llamada.
Anulación explícita del modelo para la sesión ACP hija. Las creaciones ACP de Codex
normalizan referencias de OpenAI como `openai/gpt-5.4` a la configuración de inicio de Codex ACP
antes de `session/new`; las formas slash como `openai/gpt-5.4/high`
también establecen el esfuerzo de razonamiento de Codex ACP.
Cuando se omite, `sessions_spawn({ runtime: "acp" })` usa los valores predeterminados de
modelo de subagente existentes (`agents.defaults.subagents.model` o
`agents.list[].subagents.model`) cuando están configurados; de lo contrario, permite que el
harness ACP use su propio modelo predeterminado.
Otros harnesses deben anunciar `models` ACP y admitir
`session/set_model`; de lo contrario, OpenClaw/acpx falla con claridad en lugar de
recurrir silenciosamente al valor predeterminado del agente de destino.
Esfuerzo explícito de pensamiento/razonamiento. Para Codex ACP, `minimal` se asigna a
esfuerzo bajo, `low`/`medium`/`high`/`xhigh` se asignan directamente, y `off`
omite la anulación de esfuerzo de razonamiento de inicio.
Cuando se omite, las creaciones ACP usan los valores predeterminados de pensamiento de subagente existentes y
`agents.defaults.models["provider/model"].params.thinking` por modelo
para el modelo seleccionado.
## Modos de enlace y de hilo para spawn
| Modo | Comportamiento |
| ------ | ---------------------------------------------------------------------- |
| `here` | Vincula la conversación activa actual en el mismo lugar; falla si no hay ninguna activa. |
| `off` | No crea un enlace de conversación actual. |
Notas:
- `--bind here` es la ruta de operador más sencilla para "hacer que este canal o chat esté respaldado por Codex".
- `--bind here` no crea un hilo hijo.
- `--bind here` solo está disponible en canales que exponen compatibilidad de enlace de conversación actual.
- `--bind` y `--thread` no pueden combinarse en la misma llamada a `/acp spawn`.
| Modo | Comportamiento |
| ------ | --------------------------------------------------------------------------------------------------- |
| `auto` | En un hilo activo: vincula ese hilo. Fuera de un hilo: crea/vincula un hilo hijo cuando sea compatible. |
| `here` | Requiere un hilo activo actual; falla si no está en uno. |
| `off` | Sin enlace. La sesión empieza sin vincular. |
Notas:
- En superficies sin enlace de hilo, el comportamiento predeterminado es efectivamente `off`.
- La creación vinculada a hilo requiere compatibilidad de política del canal:
- Discord: `channels.discord.threadBindings.spawnSessions=true`
- Telegram: `channels.telegram.threadBindings.spawnSessions=true`
- Usa `--bind here` cuando quieras fijar la conversación actual sin crear un hilo hijo.
## Modelo de entrega
Las sesiones ACP pueden ser espacios de trabajo interactivos o trabajo en segundo plano
propiedad del padre. La ruta de entrega depende de esa forma.
Las sesiones interactivas están pensadas para seguir conversando en una superficie de chat
visible:
- `/acp spawn ... --bind here` vincula la conversación actual a la sesión ACP.
- `/acp spawn ... --thread ...` vincula un hilo/tema de canal a la sesión ACP.
- Los `bindings[].type="acp"` configurados de forma persistente enrutan las conversaciones coincidentes a la misma sesión ACP.
Los mensajes de seguimiento en la conversación vinculada se enrutan directamente a la
sesión ACP, y la salida ACP se entrega de vuelta al mismo
canal/hilo/tema.
Lo que OpenClaw envía al harness:
- Los seguimientos vinculados normales se envían como texto de prompt, más adjuntos solo cuando el harness/backend los admite.
- Los comandos de gestión `/acp` y los comandos locales del Gateway se interceptan antes del despacho ACP.
- Los eventos de finalización generados por runtime se materializan por destino. Los agentes de OpenClaw reciben el envoltorio interno de contexto de runtime de OpenClaw; los harnesses ACP externos reciben un prompt plano con el resultado hijo y la instrucción. El envoltorio sin procesar `<<>>` nunca debe enviarse a harnesses externos ni persistirse como texto de transcripción de usuario ACP.
- Las entradas de transcripción ACP usan el texto de activación visible para el usuario o el prompt de finalización plano. Los metadatos de eventos internos permanecen estructurados en OpenClaw cuando es posible y no se tratan como contenido de chat escrito por el usuario.
Las sesiones ACP de una sola ejecución creadas por otra ejecución de agente son hijos en segundo plano,
similares a subagentes:
- El padre solicita trabajo con `sessions_spawn({ runtime: "acp", mode: "run" })`.
- El hijo se ejecuta en su propia sesión de harness ACP.
- Los turnos hijos se ejecutan en el mismo carril en segundo plano usado por las creaciones de subagentes nativos, así que un harness ACP lento no bloquea el trabajo no relacionado de la sesión principal.
- Los informes de finalización vuelven por la ruta de anuncio de finalización de tarea. OpenClaw convierte los metadatos internos de finalización en un prompt ACP plano antes de enviarlos a un harness externo, para que los harnesses no vean marcadores de contexto de runtime exclusivos de OpenClaw.
- El padre reescribe el resultado del hijo con voz normal de asistente cuando resulta útil una respuesta visible para el usuario.
**No** trates esta ruta como un chat de igual a igual entre padre
e hijo. El hijo ya tiene un canal de finalización de vuelta al
padre.
`sessions_send` puede dirigirse a otra sesión después de la creación. Para sesiones
pares normales, 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.
- Opcionalmente, permite que el solicitante y el destino intercambien un número acotado de turnos de seguimiento.
- Pide al destino que produzca un mensaje de anuncio.
- Entrega ese anuncio al canal o hilo visible.
Esa ruta A2A es un recurso alternativo para envíos entre pares donde el remitente necesita un
seguimiento visible. Permanece habilitada cuando una sesión no relacionada puede
ver y enviar mensajes a un destino ACP, por ejemplo bajo configuraciones amplias de
`tools.sessions.visibility`.
OpenClaw omite el seguimiento A2A solo cuando el solicitante es el
padre de su propio hijo ACP de un solo uso propiedad del padre. En ese caso,
ejecutar A2A encima de la finalización de la tarea puede despertar al padre con el
resultado del hijo, reenviar la respuesta del padre de vuelta al hijo y
crear un bucle de eco padre/hijo. El resultado de `sessions_send` informa
`delivery.status="skipped"` para ese caso de hijo propiedad del padre porque la
ruta de finalización ya es responsable del resultado.
Usa `resumeSessionId` para continuar una sesión ACP anterior en lugar de
empezar desde cero. El agente reproduce su historial de conversación mediante
`session/load`, por lo que retoma con contexto completo de lo ocurrido antes.
```json
{
"task": "Continue where we left off - fix the remaining test failures",
"runtime": "acp",
"agentId": "codex",
"resumeSessionId": ""
}
```
Casos de uso comunes:
- Transferir una sesión de Codex de tu portátil a tu teléfono: dile a tu agente que retome donde lo dejaste.
- Continuar una sesión de programación que iniciaste interactivamente en la CLI, ahora sin interfaz mediante tu agente.
- Retomar trabajo interrumpido por un reinicio del gateway o un tiempo de espera por inactividad.
Notas:
- `resumeSessionId` solo se aplica cuando `runtime: "acp"`; el runtime de subagente predeterminado ignora este campo exclusivo de ACP.
- `streamTo` solo se aplica cuando `runtime: "acp"`; el runtime de subagente predeterminado ignora este campo exclusivo de ACP.
- `resumeSessionId` es un id de reanudación ACP/harness local del host, no una clave de sesión de canal de OpenClaw; OpenClaw aún comprueba la política de creación de ACP y la política del agente de destino antes del envío, mientras que el backend ACP o el harness son responsables de autorizar la carga de ese id ascendente.
- `resumeSessionId` restaura el historial de conversación ACP ascendente; `thread` y `mode` siguen aplicándose normalmente a la nueva sesión de OpenClaw que estás creando, por lo que `mode: "session"` aún requiere `thread: true`.
- El agente de destino debe admitir `session/load` (Codex y Claude Code lo hacen).
- Si no se encuentra el id de sesión, la creación falla con un error claro, sin alternativa silenciosa a una sesión nueva.
Después de desplegar un gateway, ejecuta una comprobación integral en vivo en lugar de
confiar en pruebas unitarias:
1. Verifica la versión y el commit del gateway desplegado en el host de destino.
2. Abre una sesión puente ACPX temporal hacia un agente en vivo.
3. Pide a ese agente que llame a `sessions_spawn` con `runtime: "acp"`, `agentId: "codex"`, `mode: "run"` y la tarea `Reply with exactly LIVE-ACP-SPAWN-OK`.
4. Verifica `accepted=yes`, un `childSessionKey` real y ningún error de validador.
5. Limpia la sesión puente temporal.
Mantén la compuerta en `mode: "run"` y omite `streamTo: "parent"`:
las rutas vinculadas a hilos con `mode: "session"` y de retransmisión de flujo son
comprobaciones de integración más completas y separadas.
## Compatibilidad con sandbox
Actualmente, las sesiones ACP se ejecutan en el runtime del host, **no** dentro del
sandbox de OpenClaw.
**Límite de seguridad:**
- El harness externo puede leer/escribir según sus propios permisos de CLI y el `cwd` seleccionado.
- La política de sandbox de OpenClaw **no** envuelve la ejecución del harness ACP.
- OpenClaw aún aplica las compuertas de funciones ACP, agentes permitidos, propiedad de sesión, enlaces de canal y política de entrega de Gateway.
- Usa `runtime: "subagent"` para trabajo nativo de OpenClaw con sandbox aplicado.
Limitaciones actuales:
- Si la sesión solicitante está en sandbox, las creaciones ACP se bloquean tanto para `sessions_spawn({ runtime: "acp" })` como para `/acp spawn`.
- `sessions_spawn` con `runtime: "acp"` no admite `sandbox: "require"`.
## Resolución de destino de sesión
La mayoría de las acciones `/acp` aceptan un destino de sesión opcional (`session-key`,
`session-id` o `session-label`).
**Orden de resolución:**
1. Argumento de destino explícito (o `--session` para `/acp steer`)
- prueba la clave
- luego el id de sesión con forma de UUID
- luego la etiqueta
2. Enlace del hilo actual (si esta conversación/hilo está vinculada a una sesión ACP).
3. Alternativa de sesión solicitante actual.
Los enlaces de conversación actual y los enlaces de hilo participan ambos en
el paso 2.
Si no se resuelve ningún destino, OpenClaw devuelve un error claro
(`Unable to resolve session target: ...`).
## Controles ACP
| Comando | Qué hace | Ejemplo |
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
| `/acp spawn` | Crea una sesión ACP; enlace actual o de hilo opcional. | `/acp spawn codex --bind here --cwd /repo` |
| `/acp cancel` | Cancela el turno en curso de la sesión de destino. | `/acp cancel agent:codex:acp:` |
| `/acp steer` | Envía una instrucción de orientación a la sesión en ejecución. | `/acp steer --session support inbox prioritize failing tests` |
| `/acp close` | Cierra la sesión y desvincula destinos de hilo. | `/acp close` |
| `/acp status` | Muestra backend, modo, estado, opciones de runtime y capacidades. | `/acp status` |
| `/acp set-mode` | Establece el modo de runtime para la sesión de destino. | `/acp set-mode plan` |
| `/acp set` | Escritura genérica de opción de configuración de runtime. | `/acp set model openai/gpt-5.4` |
| `/acp cwd` | Establece la anulación del directorio de trabajo del runtime. | `/acp cwd /Users/user/Projects/repo` |
| `/acp permissions` | Establece el perfil de política de aprobación. | `/acp permissions strict` |
| `/acp timeout` | Establece el tiempo de espera del runtime (segundos). | `/acp timeout 120` |
| `/acp model` | Establece la anulación del modelo de runtime. | `/acp model anthropic/claude-opus-4-6` |
| `/acp reset-options` | Elimina las anulaciones de opciones de runtime de sesión. | `/acp reset-options` |
| `/acp sessions` | Lista sesiones ACP recientes desde el almacén. | `/acp sessions` |
| `/acp doctor` | Salud del backend, capacidades y correcciones accionables. | `/acp doctor` |
| `/acp install` | Imprime pasos deterministas de instalación y habilitación. | `/acp install` |
Los controles de runtime (`spawn`, `cancel`, `steer`, `close`, `status`, `set-mode`,
`set`, `cwd`, `permissions`, `timeout`, `model` y `reset-options`) requieren
identidad de propietario desde canales externos y `operator.admin` desde clientes
Gateway internos. Los remitentes autorizados que no sean propietarios aún pueden usar `sessions`, `doctor`,
`install` y `help`.
`/acp status` muestra las opciones de runtime efectivas junto con identificadores de sesión
a nivel de runtime y de backend. Los errores de control no admitido aparecen
claramente cuando un backend carece de una capacidad. `/acp sessions` lee el
almacén para la sesión solicitante o vinculada actual; los tokens de destino
(`session-key`, `session-id` o `session-label`) se resuelven mediante el
descubrimiento de sesiones del gateway, incluidas raíces `session.store`
personalizadas por agente.
### Asignación de opciones de runtime
`/acp` tiene comandos de conveniencia y un setter genérico. Operaciones
equivalentes:
| Comando | Se asigna a | Notas |
| ---------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/acp model ` | clave de configuración de runtime `model` | Para Codex ACP, OpenClaw normaliza `openai/` al id de modelo del adaptador y asigna sufijos de razonamiento con barra como `openai/gpt-5.4/high` a `reasoning_effort`. |
| `/acp set thinking ` | opción canónica `thinking` | OpenClaw envía el equivalente anunciado por el backend cuando está presente, prefiriendo `thinking`, luego `effort`, `reasoning_effort` o `thought_level`. Para Codex ACP, el adaptador asigna los valores a `reasoning_effort`. |
| `/acp permissions ` | opción canónica `permissionProfile` | OpenClaw envía el equivalente anunciado por el backend cuando está presente, como `approval_policy`, `permission_profile`, `permissions` o `permission_mode`. |
| `/acp timeout ` | opción canónica `timeoutSeconds` | OpenClaw envía el equivalente anunciado por el backend cuando está presente, como `timeout` o `timeout_seconds`. |
| `/acp cwd ` | anulación de cwd de runtime | Actualización directa. |
| `/acp set ` | genérico | `key=cwd` usa la ruta de anulación de cwd. |
| `/acp reset-options` | borra todas las anulaciones de runtime | - |
## harness acpx, configuración de Plugin y permisos
Para la configuración del harness acpx (alias de Claude Code / Codex / Gemini CLI),
los puentes MCP plugin-tools y OpenClaw-tools, y los modos de permiso ACP,
consulta
[Agentes ACP: configuración](/es/tools/acp-agents-setup).
## Solución de problemas
| Síntoma | Causa probable | Solución |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ACP runtime backend is not configured` | Falta el Plugin de backend, está deshabilitado o está bloqueado por `plugins.allow`. | Instala y habilita el Plugin de backend, incluye `acpx` en `plugins.allow` cuando esa lista de permitidos esté configurada, y luego ejecuta `/acp doctor`. |
| `ACP is disabled by policy (acp.enabled=false)` | ACP está deshabilitado globalmente. | Configura `acp.enabled=true`. |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | El despacho automático desde mensajes normales de hilos está deshabilitado. | Configura `acp.dispatch.enabled=true` para reanudar el enrutamiento automático de hilos; las llamadas explícitas a `sessions_spawn({ runtime: "acp" })` siguen funcionando. |
| `ACP agent "" is not allowed by policy` | El agente no está en la lista de permitidos. | Usa un `agentId` permitido o actualiza `acp.allowedAgents`. |
| `/acp doctor` informa que el backend no está listo justo después del inicio | Falta el Plugin de backend, está deshabilitado, está bloqueado por una política de permitir/denegar, o su ejecutable configurado no está disponible. | Instala/habilita el Plugin de backend, vuelve a ejecutar `/acp doctor` e inspecciona el error de instalación del backend o de política si sigue sin estar saludable. |
| No se encuentra el comando del arnés | La CLI del adaptador no está instalada, falta el Plugin externo o falló la obtención de `npx` en la primera ejecución para un adaptador que no es Codex. | Ejecuta `/acp doctor`, instala/precalienta el adaptador en el host del Gateway o configura explícitamente el comando del agente acpx. |
| Modelo no encontrado desde el arnés | El id del modelo es válido para otro proveedor/arnés, pero no para este destino ACP. | Usa un modelo listado por ese arnés, configura el modelo en el arnés u omite la anulación. |
| Error de autenticación del proveedor desde el arnés | OpenClaw está saludable, pero la CLI/proveedor de destino no tiene una sesión iniciada. | Inicia sesión o proporciona la clave de proveedor requerida en el entorno del host del Gateway. |
| `Unable to resolve session target: ...` | Token de clave/id/etiqueta incorrecto. | Ejecuta `/acp sessions`, copia la clave/etiqueta exacta y vuelve a intentarlo. |
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` se usó sin una conversación activa que pueda vincularse. | Muévete al chat/canal de destino y vuelve a intentarlo, o usa una generación sin vincular. |
| `Conversation bindings are unavailable for .` | El adaptador carece de la capacidad de vinculación ACP de la conversación actual. | Usa `/acp spawn ... --thread ...` donde sea compatible, configura `bindings[]` de nivel superior o muévete a un canal compatible. |
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` se usó fuera de un contexto de hilo. | Muévete al hilo de destino o usa `--thread auto`/`off`. |
| `Only can rebind this channel/conversation/thread.` | Otro usuario posee el destino de vinculación activo. | Revincula como propietario o usa una conversación o hilo diferente. |
| `Thread bindings are unavailable for .` | El adaptador carece de capacidad de vinculación de hilos. | Usa `--thread off` o muévete a un adaptador/canal compatible. |
| `Sandboxed sessions cannot spawn ACP sessions ...` | El runtime ACP está del lado del host; la sesión solicitante está en sandbox. | Usa `runtime="subagent"` desde sesiones en sandbox, o ejecuta ACP spawn desde una sesión sin sandbox. |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Se solicitó `sandbox="require"` para el runtime ACP. | Usa `runtime="subagent"` para sandboxing obligatorio, o usa ACP con `sandbox="inherit"` desde una sesión sin sandbox. |
| `Cannot apply --model ... did not advertise model support` | El arnés de destino no expone el cambio genérico de modelo de ACP. | Usa un arnés que anuncie ACP `models`/`session/set_model`, usa referencias de modelo ACP de Codex, o configura el modelo directamente en el arnés si tiene su propia marca de inicio. |
| Faltan metadatos ACP para la sesión vinculada | Metadatos de sesión ACP obsoletos/eliminados. | Recrea con `/acp spawn` y luego revincula/enfoca el hilo. |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` bloquea escrituras/exec en una sesión ACP no interactiva. | Configura `plugins.entries.acpx.config.permissionMode` como `approve-all` y reinicia el Gateway. Consulta [Configuración de permisos](/es/tools/acp-agents-setup#permission-configuration). |
| La sesión ACP falla temprano con poca salida | Las solicitudes de permiso están bloqueadas por `permissionMode`/`nonInteractivePermissions`. | Revisa los registros del Gateway para `AcpRuntimeError`. Para permisos completos, configura `permissionMode=approve-all`; para degradación gradual, configura `nonInteractivePermissions=deny`. |
| La sesión ACP se queda bloqueada indefinidamente después de completar el trabajo | El proceso del arnés terminó, pero la sesión ACP no informó la finalización. | Actualiza OpenClaw; la limpieza actual de acpx elimina los procesos envoltorio y adaptador obsoletos propiedad de OpenClaw al cerrar y al iniciar el Gateway. |
| El arnés ve `<<>>` | El sobre de evento interno se filtró a través del límite ACP. | Actualiza OpenClaw y vuelve a ejecutar el flujo de finalización; los arneses externos deberían recibir solo prompts de finalización simples. |
`Command blocked by PreToolUse hook: Native hook relay unavailable` pertenece al
relé de hooks nativo de Codex, no a ACP/acpx. En un chat Codex vinculado, inicia una
sesión nueva con `/new` o `/reset`; si funciona una vez y luego vuelve en la siguiente
llamada de herramienta nativa, reinicia el servidor de la app Codex o el Gateway de OpenClaw en lugar de
repetir `/new`. Consulta [Solución de problemas del arnés de Codex](/es/plugins/codex-harness#troubleshooting).
## Relacionado
- [Agentes ACP: configuración](/es/tools/acp-agents-setup)
- [Envío a agente](/es/tools/agent-send)
- [Backends de CLI](/es/gateway/cli-backends)
- [Arnés de Codex](/es/plugins/codex-harness)
- [Runtime del arnés de Codex](/es/plugins/codex-harness-runtime)
- [Herramientas de sandbox multiagente](/es/tools/multi-agent-sandbox-tools)
- [`openclaw acp` (modo puente)](/es/cli/acp)
- [Subagentes](/es/tools/subagents)