Agentes ACP

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

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

Flujo rápido del operador

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

1. Crear una sesión:
   • /acp spawn codex --mode persistent --thread auto
2. Trabaja en el hilo vinculado (o apunta explícitamente a esa clave de sesión).
3. Verifica 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. Redirige una sesión activa sin reemplazar el contexto:
   • /acp steer tighten logging and continue
6. Detén el trabajo:
   • /acp cancel (detener el turno actual), o
   • /acp close (cerrar sesión + eliminar vínculos)

Inicio rápido para humanos

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 un solo uso y resume el resultado.”
• “Usa Gemini CLI para esta tarea en un hilo, luego mantén los seguimientos en ese mismo hilo.”

Lo que OpenClaw debería hacer:

1. Elegir runtime: "acp".
2. Resolver el entorno objetivo solicitado (agentId, por ejemplo codex).
3. Si se solicita vinculación a hilo y el canal actual lo soporta, vincular la sesión ACP al hilo.
4. Enrutar los mensajes de seguimiento del hilo a esa misma sesión ACP hasta que se desenfoque/cierre/expire.

ACP versus sub-agentes

Usa ACP cuando quieras un runtime de entorno externo. Usa sub-agentes cuando quieras ejecuciones delegadas nativas de OpenClaw.

Consulta también Sub-agentes.

Sesiones vinculadas a hilos (agnóstico de canal)

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

• OpenClaw vincula un hilo a una sesión ACP objetivo.
• 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.
• Desenfocar/cerrar/archivar/expiración por inactividad o edad máxima elimina el vínculo.

El soporte de vinculación a hilos es específico del adaptador. Si el adaptador de canal activo no soporta vínculos de hilo, OpenClaw devuelve un mensaje claro de no soportado/no disponible.

Flags de características requeridos para ACP vinculado a hilos:

• acp.enabled=true
• acp.dispatch.enabled está activado por defecto (establece false para pausar el despacho ACP)
• Flag de creación de hilos ACP del adaptador de canal habilitado (específico del adaptador)
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

Canales que soportan hilos

• 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 en DM)
• Los canales de plugins pueden agregar soporte a través de la misma interfaz de vinculación.

Configuración específica del canal

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

Modelo de vinculación

• bindings[].type="acp" marca un vínculo de conversación ACP persistente.
• bindings[].match identifica la conversación objetivo:
  • 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 agente OpenClaw propietario.
• Las sobrecargas opcionales de ACP se encuentran bajo bindings[].acp:
  • mode (persistent o oneshot)
  • label
  • cwd
  • backend

Valores por defecto del runtime por agente

Usa agents.list[].runtime para definir valores por defecto de ACP una vez por agente:

• agents.list[].runtime.type="acp"
• agents.list[].runtime.acp.agent (id del entorno, por ejemplo codex o claude)
• agents.list[].runtime.acp.backend
• agents.list[].runtime.acp.mode
• agents.list[].runtime.acp.cwd

Precedencia de sobrecargas para sesiones vinculadas ACP:

1. bindings[].acp.*
2. agents.list[].runtime.acp.*
3. Valores por defecto 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 se asegura de 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 su lugar.
• Los vínculos temporales del runtime (por ejemplo creados por flujos de enfoque de hilo) siguen aplicándose donde estén presentes.

Iniciar sesiones ACP (interfaces)

Desde sessions_spawn

Usa runtime: "acp" para iniciar una sesión ACP desde un turno de agente o llamada a herramienta.

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

Notas:

• runtime tiene como valor por defecto subagent, así que establece runtime: "acp" explícitamente para 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.

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 entorno objetivo ACP. Recurre a acp.defaultAgent si está configurado.
• thread (opcional, por defecto false): solicitar flujo de vinculación a hilo donde sea soportado.
• mode (opcional): run (un solo uso) o session (persistente).
  • por defecto es run
  • si thread: true y se omite mode, OpenClaw puede usar comportamiento persistente por defecto según la ruta del runtime
  • mode: "session" requiere thread: true
• cwd (opcional): directorio de trabajo del runtime solicitado (validado por la política del backend/runtime).
• label (opcional): etiqueta orientada al operador usada en texto de sesión/banner.
• resumeSessionId (opcional): reanudar una sesión ACP existente en lugar de crear una nueva. El agente reproduce su historial de conversación vía session/load. Requiere runtime: "acp".
• streamTo (opcional): "parent" transmite resúmenes del progreso inicial de la ejecución ACP de vuelta a la sesión solicitante como eventos del sistema.
  • Cuando está disponible, las respuestas aceptadas incluyen streamLogPath apuntando a un log JSONL con alcance de sesión (<sessionId>.acp-stream.jsonl) que puedes seguir para el historial completo de retransmisión.

Reanudar una sesión existente

Usa resumeSessionId para continuar una sesión ACP anterior en lugar de empezar de cero. El agente reproduce su historial de conversación vía session/load, así que retoma con el contexto completo de lo que vino antes.

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

Casos de uso comunes:

• Trasladar una sesión de Codex de tu laptop a tu teléfono: dile a tu agente que retome donde lo dejaste
• Continuar una sesión de codificación que iniciaste interactivamente en el CLI, ahora de forma headless a través de tu agente
• Retomar trabajo que fue interrumpido por un reinicio del gateway o expiración por inactividad

Notas:

• resumeSessionId requiere runtime: "acp" — devuelve un error si se usa con el runtime de sub-agentes.
• resumeSessionId restaura el historial de conversación ACP upstream; thread y mode siguen aplicándose normalmente a la nueva sesión de OpenClaw que estás creando, así que mode: "session" sigue requiriendo thread: true.
• El agente objetivo debe soportar 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 recurso silencioso a una nueva sesión.

Prueba de humo del operador

Usa esto después de un despliegue del gateway cuando quieras una verificación rápida en vivo de que la creación ACP realmente funciona de extremo a extremo, no solo pasando pruebas unitarias.

Verificación recomendada:

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

Prompt de ejemplo para el agente 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 esta prueba de humo en mode: "run" a menos que estés probando intencionalmente sesiones ACP persistentes vinculadas a hilos.
• No requieras streamTo: "parent" para la verificación básica. Esa ruta depende de las capacidades del solicitante/sesión y es una verificación de integración separada.
• Trata las pruebas de mode: "session" vinculadas a hilos como un segundo pase de integración más completo desde un hilo real de Discord o tema de Telegram.

Compatibilidad con sandbox

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

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.
  • 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 ejecución con sandbox obligatorio.

Desde el comando /acp

Usa /acp spawn para 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 clave:

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

Consulta Comandos de barra.

Resolución del objetivo de sesión

La mayoría de las acciones /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 clave
   • luego UUID como id de sesión
   • luego etiqueta
2. Vínculo de hilo actual (si esta conversación/hilo está vinculado a una sesión ACP)
3. Respaldo a la sesión del solicitante actual

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

Modos de hilo en la creación

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

Notas:

• En superficies sin vinculación de hilos, el comportamiento por defecto es efectivamente off.
• La creación vinculada a hilos requiere soporte de política del canal:
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

Controles ACP

Familia de comandos disponible:

• /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 efectivas del runtime y, cuando está disponible, tanto los identificadores de sesión 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.

Recetario de comandos ACP

/acp sessions lee el almacén para la sesión vinculada o solicitante actual. Los comandos que aceptan tokens session-key, session-id o session-label resuelven objetivos a través del descubrimiento de sesiones del gateway, incluyendo raíces session.store personalizadas por agente.

Mapeo de opciones del runtime

/acp tiene comandos de conveniencia y un setter genérico.

Operaciones equivalentes:

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

Soporte de entornos acpx (actual)

Alias de entornos integrados en acpx actualmente:

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

Cuando OpenClaw usa el backend acpx, prefiere estos valores para agentId a menos que tu configuración de acpx defina aliases de agente personalizados.

El uso directo del CLI de acpx también puede apuntar a adaptadores arbitrarios vía --agent <command>, pero esa vía de escape directa es una función del CLI de acpx (no la ruta normal de agentId de OpenClaw).

Configuración requerida

Base ACP fundamental:

{
  acp: {
    enabled: true,
    // Opcional. Por defecto es true; establece false para pausar el despacho ACP manteniendo los controles /acp.
    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 vinculación a hilos es específica del adaptador de canal. Ejemplo para Discord:

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

Si la creación ACP vinculada a hilos no funciona, verifica primero el flag de característica del adaptador:

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

Consulta Referencia de configuración.

Configuración del plugin para backend acpx

Instala y habilita el plugin:

openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true

Instalación local en el workspace durante el desarrollo:

openclaw plugins install ./extensions/acpx

Luego verifica la salud del backend:

/acp doctor

Configuración del comando y versión de acpx

Por defecto, el plugin acpx (publicado como @openclaw/acpx) usa el binario fijado local del plugin:

1. El comando tiene como valor por defecto extensions/acpx/node_modules/.bin/acpx.
2. La versión esperada tiene como valor por defecto el pin de la extensión.
3. Al inicio se registra el backend ACP inmediatamente como no listo.
4. Un trabajo de verificación en segundo plano comprueba acpx --version.
5. Si el binario local del plugin falta o no coincide, ejecuta: npm install --omit=dev --no-save acpx@<pinned> y vuelve a verificar.

Puedes sobrecargar comando/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, ruta relativa o nombre de comando (acpx).
• Las rutas relativas se resuelven desde el directorio del workspace de OpenClaw.
• expectedVersion: "any" deshabilita la coincidencia estricta de versión.
• Cuando command apunta a un binario/ruta personalizado, la auto-instalación local del plugin se deshabilita.
• El inicio de OpenClaw permanece no bloqueante mientras se ejecuta la verificación de salud del backend.

Consulta Plugins.

Configuración de permisos

Las sesiones ACP se ejecutan de forma no interactiva — no hay TTY para aprobar o denegar prompts de permisos de escritura de archivos y ejecución de shell. El plugin acpx proporciona dos claves de configuración que controlan cómo se manejan los permisos:

permissionMode

Controla qué operaciones puede realizar el agente del entorno sin preguntar.

nonInteractivePermissions

Controla qué sucede cuando se mostraría un prompt de permisos pero no hay TTY interactivo disponible (que siempre es el caso para sesiones ACP).

Configuración

Establece vía configuración del plugin:

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 actualmente usa por defecto permissionMode=approve-reads y nonInteractivePermissions=fail. En sesiones ACP no interactivas, cualquier escritura o ejecución que dispare un prompt de permisos puede fallar con AcpRuntimeError: Permission prompt unavailable in non-interactive mode.

Si necesitas restringir permisos, establece nonInteractivePermissions a deny para que las sesiones se degraden elegantemente en lugar de fallar.

Solución de problemas