Ir al contenido

Configura sesiones ACP en OpenClaw: Guía rápida

Las sesiones del Agent Client Protocol (ACP) permiten que OpenClaw ejecute entornos de coding harness externos (por ejemplo, Pi, Claude Code, Codex, OpenCode y Gemini CLI) a través de un ACP backend plugin.

Si le pides a OpenClaw en lenguaje natural que “ejecute esto en Codex” o “inicie Claude Code en un hilo”, OpenClaw debería dirigir esa solicitud al runtime de ACP (no al runtime nativo de sub-agentes).

Usa esto cuando necesites un runbook práctico de /acp:

  1. Inicia una sesión:
    • /acp spawn codex --mode persistent --thread auto
  2. Trabaja en el hilo vinculado (o apunta a esa clave de sesión explícitamente).
  3. Revisa el estado del runtime:
    • /acp status
  4. Ajusta las opciones del runtime según sea necesario:
    • /acp model <provider/model>
    • /acp permissions <profile>
    • /acp timeout <seconds>
  5. Ajusta una sesión activa sin reemplazar el contexto:
    • /acp steer tighten logging and continue
  6. Detén el trabajo:
    • /acp cancel (detiene el turno actual), o
    • /acp close (cierra la sesión y elimina los vínculos)

Ejemplos de solicitudes naturales:

  • “Inicia una sesión persistente de Codex en un hilo aquí y mantenla enfocada.”
  • “Ejecuta esto como una sesión ACP de Claude Code de tipo one-shot y resume el resultado.”
  • “Usa Gemini CLI para esta tarea en un hilo, luego mantén el seguimiento en ese mismo hilo.”

Lo que OpenClaw debe hacer:

  1. Seleccionar runtime: "acp".
  2. Resolver el destino del harness solicitado (agentId, por ejemplo codex).
  3. Si se solicita la vinculación de hilos y el canal actual lo admite, vincular la sesión ACP al hilo.
  4. Dirigir los mensajes de seguimiento del hilo a esa misma sesión ACP hasta que se desenfoque, cierre o expire.

Usa ACP cuando quieras un runtime de un harness externo. Usa sub-agents cuando prefieras ejecuciones delegadas nativas de OpenClaw.

ÁreaSesión ACPEjecución de sub-agent
RuntimeACP backend plugin (por ejemplo acpx)Runtime nativo de sub-agentes de OpenClaw
Session keyagent:<agentId>:acp:<uuid>agent:<agentId>:subagent:<uuid>
Comandos principales/acp .../subagents ...
Herramienta de iniciosessions_spawn con runtime:"acp"sessions_spawn (runtime por defecto)

Consulta también Sub-agents.

Sesiones vinculadas a hilos (independientes del canal)

Sección titulada «Sesiones vinculadas a hilos (independientes del canal)»

Cuando los vínculos de hilos están habilitados para un adaptador de canal, las sesiones ACP pueden vincularse a hilos:

  • OpenClaw vincula un hilo a una sesión ACP de destino.
  • Los mensajes de seguimiento en ese hilo se dirigen a la sesión ACP vinculada.
  • La salida de ACP se entrega de vuelta al mismo hilo.
  • Al desenfocar, cerrar, archivar o por tiempo de espera de inactividad o expiración de antigüedad máxima, se elimina el vínculo.

El soporte para la vinculación de hilos depende del adaptador. Si el adaptador de canal activo no admite vínculos de hilos, OpenClaw devuelve un mensaje claro de que no es compatible o no está disponible.

Feature flags requeridos para ACP vinculado a hilos:

acp.enabled=true
acp.dispatch.enabled (activado por defecto; ponlo en false para pausar el despacho de ACP)
Channel-adapter ACP thread-spawn flag enabled (específico del adaptador)
- Discord: channels.discord.threadBindings.spawnAcpSessions=true
- Telegram: channels.telegram.threadBindings.spawnAcpSessions=true
  • Cualquier adaptador de canal que exponga la capacidad de vinculación de sesiones o hilos.
  • Soporte integrado actual:
    • Hilos y canales de Discord.
    • Temas (topics) de Telegram (temas de foro en grupos/supergrupos y temas de mensajes directos).
  • Los canales de plugins pueden añadir soporte a través de la misma interfaz de vinculación.

Para flujos de trabajo que no sean efímeros, configura bindings de ACP persistentes en las entradas bindings[] de nivel superior.

  • bindings[].type="acp" marca un binding de conversación ACP persistente.
  • bindings[].match identifica la conversación de destino:
    • Canal o hilo de Discord: match.channel="discord" + match.peer.id="<channelOrThreadId>"
    • Tema de foro de Telegram: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • bindings[].agentId es el ID del agent de OpenClaw propietario.
  • Los overrides opcionales de ACP se encuentran bajo bindings[].acp:
    • mode (persistent o oneshot)
    • label
    • cwd
    • backend

Valores predeterminados de runtime por agent

Sección titulada «Valores predeterminados de runtime por agent»

Usa agents.list[].runtime para definir los valores predeterminados de ACP una vez por cada agent:

  • agents.list[].runtime.type="acp"
  • agents.list[].runtime.acp.agent (ID del 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 a ACP:

  1. bindings[].acp.*
  2. agents.list[].runtime.acp.*
  3. Valores predeterminados globales de ACP (por ejemplo, acp.backend)

Ejemplo:

{
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 antes de usarla.
  • Los mensajes en ese canal o tema se enrutan a la sesión ACP configurada.
  • En conversaciones vinculadas, /new y /reset reinician la misma clave de sesión ACP en el lugar.
  • Los bindings de runtime temporales (por ejemplo, creados por flujos de enfoque en hilos) se siguen aplicando cuando están presentes.

Usa runtime: "acp" para iniciar una sesión ACP desde un turno del agent o una llamada a una tool.

{
"task": "Open the repo and summarize failing tests",
"runtime": "acp",
"agentId": "codex",
"thread": true,
"mode": "session"
}

Notas:

  • El runtime por defecto es subagent, así que establece runtime: "acp" explícitamente para sesiones ACP.
  • Si omites agentId, OpenClaw usa acp.defaultAgent si está configurado.
  • mode: "session" requiere thread: true para mantener una conversación vinculada persistente.

Detalles de la interfaz:

  • task (requerido): prompt inicial enviado a la sesión ACP.
  • runtime (requerido para ACP): debe ser "acp".
  • agentId (opcional): ID del harness de destino de ACP. Recurre a acp.defaultAgent si está definido.
  • thread (opcional, por defecto false): solicita el flujo de binding de hilos donde sea compatible.
  • mode (opcional): run (un solo uso) o session (persistente).
    • El valor por defecto es run.
    • Si thread: true y se omite el modo, OpenClaw puede usar por defecto el comportamiento persistente según la ruta del runtime.
    • mode: "session" requiere thread: true.
  • cwd (optional): directorio de trabajo del runtime solicitado (validado por la política de backend/runtime).
  • label (opcional): etiqueta para el operador utilizada en el texto de la sesión o banner.
  • resumeSessionId (opcional): reanuda una sesión ACP existente en lugar de crear una nueva. El agent reproduce su historial de conversación mediante session/load. Requiere runtime: "acp".
  • streamTo (opcional): "parent" transmite resúmenes del progreso inicial de la ejecución de ACP a la sesión solicitante como eventos del sistema.
    • Cuando esté disponible, las respuestas aceptadas incluyen streamLogPath, que apunta a un log JSONL con alcance de sesión (<sessionId>.acp-stream.jsonl) que puedes seguir para ver el historial completo de retransmisión.

Usa resumeSessionId para continuar una sesión ACP anterior en lugar de empezar de cero. El agent reproduce su historial de conversación mediante session/load, por lo que retoma el trabajo con todo el contexto previo.

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

Casos de uso comunes:

  • Pasa una sesión de Codex de tu laptop a tu teléfono: dile a tu agent que continúe donde lo dejaste.
  • Continúa una sesión de programación que empezaste de forma interactiva en la CLI, ahora sin interfaz a través de tu agent.
  • Retoma el trabajo que fue interrumpido por un reinicio del Gateway o un tiempo de espera por inactividad.

Notas:

  • resumeSessionId requiere runtime: "acp"; devuelve un error si se usa con el runtime de sub-agent.
  • resumeSessionId restaura el historial de conversación de ACP ascendente; thread y mode se siguen aplicando normalmente a la nueva sesión de OpenClaw que estás creando, por lo que mode: "session" sigue requiriendo thread: true.
  • El agent de destino debe soportar session/load (Codex y Claude Code lo hacen).
  • Si no se encuentra el ID de sesión, el spawn falla con un error claro; no hay una transición silenciosa a una nueva sesión.

Usa esto después de un despliegue del Gateway cuando quieras una comprobación rápida en vivo de que el spawn de ACP funciona de extremo a extremo, no solo pasando pruebas unitarias.

Pasos recomendados:

  1. Verifica la versión/commit del Gateway desplegado en el host de destino.
  2. Confirma que el código fuente desplegado incluya la aceptación de linaje ACP en src/gateway/sessions-patch.ts (sesiones subagent:* o acp:*).
  3. Abre una sesión de puente ACPX temporal con un agent en vivo (por ejemplo, razor(main) en jpclawhq).
  4. Pide a ese agent que llame a sessions_spawn con:
    • runtime: "acp"
    • agentId: "codex"
    • mode: "run"
    • task: Reply with exactly LIVE-ACP-SPAWN-OK
  5. Verifica que el agent informe:
    • accepted=yes
    • un childSessionKey real
    • sin errores de validación
  6. Limpia la sesión de puente ACPX temporal.

Ejemplo de prompt para el agent en vivo:

Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
Set the task to: "Reply with exactly LIVE-ACP-SPAWN-OK".
Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exact text or none>.

Notas:

  • Mantén este smoke test en mode: "run" a menos que estés probando intencionalmente sesiones ACP persistentes vinculadas a hilos.
  • No requieras streamTo: "parent" para la comprobación básica. Esa ruta depende de las capacidades del solicitante/sesión y es una verificación de integración independiente.
  • Trata las pruebas de mode: "session" vinculadas a hilos como una segunda fase de integración más completa desde un hilo real de Discord o un tema de Telegram.

Las sesiones ACP se ejecutan actualmente en el runtime del host, no dentro del sandbox de OpenClaw.

Limitaciones actuales:

  • Si la sesión del solicitante está en un sandbox, los spawns de ACP se bloquean tanto para sessions_spawn({ runtime: "acp" }) como para /acp spawn.
    • Error: Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.
  • sessions_spawn con runtime: "acp" no soporta sandbox: "require".
    • Error: sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".

Usa runtime: "subagent" cuando necesites una ejecución forzada por sandbox.

Usa /acp spawn para un control explícito del operador desde el chat cuando sea necesario.

/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --thread here

Flags principales:

  • --mode persistent|oneshot
  • --thread auto|here|off
  • --cwd <absolute-path>
  • --label <name>

Consulta Slash Commands.

La mayoría de las acciones de /acp aceptan un objetivo de sesión opcional (session-key, session-id o session-label).

Orden de resolución:

  1. Argumento de objetivo explícito (o --session para /acp steer)
    • intenta con la clave (key)
    • luego con el ID de sesión con formato UUID
    • finalmente con la etiqueta (label)
  2. Binding del hilo actual (si esta conversación/hilo está vinculado a una sesión ACP)
  3. Fallback a la sesión del solicitante actual

Si no se resuelve ningún objetivo, OpenClaw devuelve un error claro (Unable to resolve session target: ...).

/acp spawn admite --thread auto|here|off.

ModoComportamiento
autoEn un thread activo: vincula ese thread. Fuera de un thread: crea/vincula un thread hijo cuando sea compatible.
hereRequiere un thread activo actual; falla si no estás en uno.
offSin vinculación. La sesión comienza sin estar vinculada.

Notas:

  • En superficies que no permiten vinculación de threads, el comportamiento por defecto es básicamente off.
  • El spawn vinculado a threads requiere soporte en la política del canal:
    • Discord: channels.discord.threadBindings.spawnAcpSessions=true
    • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

Familia de comandos disponibles:

  • /acp spawn
  • /acp cancel
  • /acp steer
  • /acp close
  • /acp status
  • /acp set-mode
  • /acp set
  • /acp cwd
  • /acp permissions
  • /acp timeout
  • /acp model
  • /acp reset-options
  • /acp sessions
  • /acp doctor
  • /acp install

/acp status muestra las opciones de runtime efectivas y, cuando están disponibles, los identificadores de sesión tanto a nivel de runtime como de backend.

Algunos controles dependen de las capacidades del backend. Si un backend no soporta un control, OpenClaw devuelve un error claro de control no soportado.

ComandoQué haceEjemplo
/acp spawnCrea una sesión de ACP; vinculación de hilos opcional./acp spawn codex --mode persistent --thread auto --cwd /repo
/acp cancelCancela el turno en curso para la sesión seleccionada./acp cancel agent:codex:acp:<uuid>
/acp steerEnvía una instrucción de guía a la sesión activa./acp steer --session support inbox prioritize failing tests
/acp closeCierra la sesión y desvincula los hilos./acp close
/acp statusMuestra el backend, modo, estado, opciones de runtime y capacidades./acp status
/acp set-modeConfigura el modo de runtime para la sesión seleccionada./acp set-mode plan
/acp setEscritura genérica de opciones de configuración de runtime./acp set model openai/gpt-5.2
/acp cwdDefine una ruta específica para el directorio de trabajo (cwd) del runtime./acp cwd /Users/user/Projects/repo
/acp permissionsConfigura el perfil de la política de aprobación./acp permissions strict
/acp timeoutConfigura el tiempo de espera (timeout) del runtime en segundos./acp timeout 120
/acp modelDefine un modelo específico para el runtime./acp model anthropic/claude-opus-4-5
/acp reset-optionsElimina las personalizaciones de las opciones de runtime de la sesión./acp reset-options
/acp sessionsLista las sesiones de ACP recientes del almacenamiento./acp sessions
/acp doctorEstado del backend, capacidades, salud del sistema y soluciones recomendadas./acp doctor
/acp installMuestra los pasos deterministas de instalación y activación./acp install

/acp tiene comandos directos y un configurador genérico.

Operaciones equivalentes:

  • /acp model <id> se mapea a la clave de configuración de runtime model.
  • /acp permissions <profile> se mapea a la clave de configuración de runtime approval_policy.
  • /acp timeout <seconds> se mapea a la clave de configuración de runtime timeout.
  • /acp cwd <path> actualiza directamente la ruta del cwd del runtime.
  • /acp set <key> <value> es la ruta genérica.
    • Caso especial: key=cwd utiliza la ruta de anulación de cwd.
  • /acp reset-options borra todas las personalizaciones de runtime para la sesión seleccionada.

Estos son los alias integrados que puedes usar actualmente en acpx harness:

  • pi
  • claude
  • codex
  • opencode
  • gemini
  • kimi

Cuando OpenClaw utiliza el backend de acpx, te recomiendo usar estos valores para el agentId, a menos que tu configuración de acpx defina alias de agentes personalizados.

El uso directo de la CLI de acpx permite apuntar a adapters arbitrarios mediante --agent <command>, pero este atajo es una función específica de la CLI de acpx y no forma parte del flujo normal de agentId en OpenClaw.

Esta es la base necesaria para el ACP core:

{
acp: {
enabled: true,
// Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
dispatch: { enabled: true },
backend: "acpx",
defaultAgent: "codex",
allowedAgents: ["pi", "claude", "codex", "opencode", "gemini", "kimi"],
maxConcurrentSessions: 8,
stream: {
coalesceIdleMs: 300,
maxChunkChars: 1200,
},
runtime: {
ttlMinutes: 120,
},
},
}

La configuración de thread binding es específica para cada channel-adapter. Aquí tienes un ejemplo para Discord:

{
session: {
threadBindings: {
enabled: true,
idleHours: 24,
maxAgeHours: 0,
},
},
channels: {
discord: {
threadBindings: {
enabled: true,
spawnAcpSessions: true,
},
},
},
}

Si el inicio de ACP vinculado a hilos no funciona, verifica primero el feature flag del adapter:

  • Discord: channels.discord.threadBindings.spawnAcpSessions=true

Consulta la Configuration Reference.

Configuración del plugin para el backend acpx

Sección titulada «Configuración del plugin para el backend acpx»

Instala y habilita el plugin:

Ventana de terminal
openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true

Instalación en el workspace local durante el desarrollo:

Ventana de terminal
openclaw plugins install ./extensions/acpx

Después, verifica la salud del backend:

/acp doctor

Configuración del comando acpx y su versión

Sección titulada «Configuración del comando acpx y su versión»

Por defecto, el plugin acpx (publicado como @openclaw/acpx) utiliza el binary fijado localmente al plugin:

  1. El comando apunta por defecto a extensions/acpx/node_modules/.bin/acpx.
  2. La versión esperada coincide por defecto con la fijada en la extensión.
  3. Al arrancar, registra el backend ACP inmediatamente como “not-ready”.
  4. Un proceso en segundo plano verifica acpx --version.
  5. Si el binary local del plugin falta o no coincide, ejecuta: npm install --omit=dev --no-save acpx@<pinned> y vuelve a verificar.

Puedes sobrescribir el comando o la versión en la configuración del plugin:

{
"plugins": {
"entries": {
"acpx": {
"enabled": true,
"config": {
"command": "../acpx/dist/cli.js",
"expectedVersion": "any"
}
}
}
}
}

Notas:

  • command acepta una ruta absoluta, una ruta relativa o el nombre del comando (acpx).
  • Las rutas relativas se resuelven desde el directorio del workspace de OpenClaw.
  • expectedVersion: "any" desactiva la comprobación estricta de versión.
  • Cuando command apunta a un binary o ruta personalizada, la autoinstalación local del plugin se desactiva.
  • El inicio de OpenClaw no se bloquea mientras se ejecuta el chequeo de salud del backend.

Consulta Plugins.

Las sesiones ACP se ejecutan de forma no interactiva; no existe un TTY para aprobar o denegar las solicitudes de escritura de archivos (file-write) o ejecución de comandos (shell-exec). El plugin acpx ofrece dos claves de configuración para controlar cómo se gestionan estos permisos:

Controla qué operaciones puede realizar el harness agent sin necesidad de preguntar.

ValorComportamiento
approve-allAprueba automáticamente todas las escrituras de archivos y comandos shell.
approve-readsAprueba automáticamente solo las lecturas; escrituras y exec piden permiso.
deny-allDeniega todas las solicitudes de permiso.

Controla qué sucede cuando se debería mostrar una solicitud de permiso pero no hay un TTY interactivo disponible (que es lo que ocurre siempre en las sesiones ACP).

ValorComportamiento
failAborta la sesión con un AcpRuntimeError. (por defecto)
denyDeniega el permiso silenciosamente y continúa (degradación controlada).

Configúralo a través de la configuración del plugin:

Ventana de terminal
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

Reinicia el Gateway después de cambiar estos valores.

Importante: OpenClaw utiliza actualmente por defecto permissionMode=approve-reads y nonInteractivePermissions=fail. En sesiones ACP no interactivas, cualquier escritura o ejecución que active una solicitud de permiso puede fallar con AcpRuntimeError: Permission prompt unavailable in non-interactive mode.

Si necesitas restringir permisos, establece nonInteractivePermissions en deny para que las sesiones se degraden correctamente en lugar de cerrarse inesperadamente.

SíntomaCausa probableSolución
ACP runtime backend is not configuredEl plugin del backend falta o está desactivado.Instala y habilita el plugin del backend, luego ejecuta /acp doctor.
ACP is disabled by policy (acp.enabled=false)ACP desactivado globalmente.Configura acp.enabled=true.
ACP dispatch is disabled by policy (acp.dispatch.enabled=false)El despacho desde mensajes normales de hilos está desactivado.Configura acp.dispatch.enabled=true.
ACP agent "<id>" is not allowed by policyEl agente no está en la allowlist.Usa un agentId permitido o actualiza acp.allowedAgents.
Unable to resolve session target: ...Token de clave/id/etiqueta incorrecto.Ejecuta /acp sessions, copia la clave o etiqueta exacta y reintenta.
--thread here requires running /acp spawn inside an active ... threadSe usó --thread here fuera del contexto de un hilo.Muévete al hilo de destino o usa --thread auto/off.
Only <user-id> can rebind this thread.Otro usuario es el propietario del vínculo del hilo.Vincula de nuevo como propietario o usa un hilo diferente.
Thread bindings are unavailable for <channel>.El adapter carece de capacidad para vincular hilos.Usa --thread off o muévete a un adapter/channel compatible.
Sandboxed sessions cannot spawn ACP sessions ...El runtime de ACP está en el lado del host; la sesión solicitante está en sandbox.Usa runtime="subagent" desde sesiones con 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" si requieres sandboxing, o usa ACP con sandbox="inherit" desde una sesión sin sandbox.
Falta metadata de ACP para la sesión vinculadaMetadata de la sesión ACP obsoleta o eliminada.Vuelve a crear con /acp spawn, luego vincula o enfoca el hilo.
AcpRuntimeError: Permission prompt unavailable in non-interactive modepermissionMode bloquea escrituras/exec en sesión ACP no interactiva.Configura plugins.entries.acpx.config.permissionMode como approve-all y reinicia el Gateway. Mira Configuración de permisos.
La sesión ACP falla pronto con poca salidaLas solicitudes de permiso están bloqueadas por permissionMode.Revisa los logs del Gateway para ver si hay un AcpRuntimeError. Para permisos totales, usa approve-all; para degradación controlada, usa nonInteractivePermissions=deny.
La sesión ACP se detiene indefinidamente tras completar el trabajoEl proceso harness terminó pero la sesión ACP no reportó la finalización.Monitoriza con ps aux | grep acpx; mata los procesos obsoletos manualmente.
OpenClaw

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.