​

Agentes ACP

​

¿Qué página quiero?

​

¿Funciona de inmediato?

• Las instalaciones nuevas ahora incluyen el plugin de runtime empaquetado acpx habilitado de forma predeterminada.
• El plugin empaquetado acpx prefiere su binario acpx fijado localmente en el plugin.
• Al iniciarse, OpenClaw sondea ese binario y lo autorrepara si hace falta.
• Empieza con /acp doctor si quieres una comprobación rápida de preparación.

• Es posible que un adaptador del harness objetivo se descargue bajo demanda con npx la primera vez que uses ese harness.
• La autenticación del proveedor aún tiene que existir en el host para ese harness.
• Si el host no tiene acceso a npm/red, las descargas iniciales del adaptador pueden fallar hasta que las cachés se precalienten o el adaptador se instale de otro modo.

• /acp spawn codex: OpenClaw debería estar listo para iniciar acpx, pero el adaptador ACP de Codex puede seguir necesitando una descarga inicial.
• /acp spawn claude: lo mismo con el adaptador ACP de Claude, además de la autenticación del lado de Claude en ese host.

​

Flujo rápido para operadores

1. Crea una sesión:
   • /acp spawn codex --bind here
   • /acp spawn codex --mode persistent --thread auto
2. Trabaja en la conversación o hilo vinculado (o apunta explícitamente a esa clave de sesión).
3. Comprueba 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. Da una indicación a 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 personas

• “Vincula este canal de Discord a Codex.”
• “Inicia una sesión persistente de Codex en un hilo aquí y mantenla enfocada.”
• “Ejecuta esto como una sesión ACP puntual de Claude Code y resume el resultado.”
• “Vincula este chat de iMessage a Codex y mantén los seguimientos en el mismo espacio de trabajo.”
• “Usa Gemini CLI para esta tarea en un hilo y luego mantén los seguimientos en ese mismo hilo.”

1. Elegir runtime: "acp".
2. Resolver el harness objetivo solicitado (agentId, por ejemplo codex).
3. Si se solicita vinculación con la conversación actual y el canal activo la admite, vincular la sesión ACP a esa conversación.
4. En caso contrario, si se solicita vinculación con hilo y el canal actual la admite, vincular la sesión ACP al hilo.
5. Enrutar los mensajes de seguimiento vinculados a esa misma sesión ACP hasta que se desenfoque/cierre/caduca.

​

ACP frente a subagentes

​

Cómo ejecuta ACP Claude Code

1. Plano de control de sesiones ACP de OpenClaw
2. plugin de runtime empaquetado acpx
3. adaptador ACP de Claude
4. maquinaria de runtime/sesión del lado de Claude

• Claude vía ACP es una sesión de harness con controles ACP, reanudación de sesión, seguimiento de tareas en segundo plano y vinculación opcional a conversación/hilo.
• Los backends CLI son runtimes alternativos locales y separados, solo de texto. Consulta Backends CLI.

• si quieres /acp spawn, sesiones vinculables, controles de runtime o trabajo persistente del harness: usa ACP
• si quieres una alternativa local sencilla de texto mediante la CLI sin procesar: usa backends CLI

​

Sesiones vinculadas

​

Vinculaciones con la conversación actual

• OpenClaw sigue gestionando el transporte del canal, la autenticación, la seguridad y la entrega.
• La conversación actual queda fijada a la clave de sesión ACP creada.
• Los mensajes de seguimiento en esa conversación se enrutan a la misma sesión ACP.
• /new y /reset reinician la misma sesión ACP vinculada en el mismo lugar.
• /acp close cierra la sesión y elimina la vinculación de la conversación actual.

• --bind here mantiene la misma superficie de chat. En Discord, el canal actual sigue siendo el actual.
• --bind here puede seguir creando una sesión ACP nueva si estás iniciando trabajo desde cero. La vinculación adjunta esa sesión a la conversación actual.
• --bind here no crea por sí sola un hilo secundario de Discord ni un tema de Telegram.
• El runtime ACP puede seguir teniendo su propio directorio de trabajo (cwd) o espacio de trabajo administrado por backend en disco. Ese espacio de trabajo del runtime está separado de la superficie de chat y no implica un nuevo hilo de mensajería.
• Si creas una sesión para un agente ACP diferente y no pasas --cwd, OpenClaw hereda por defecto el espacio de trabajo del agente de destino, no el del solicitante.
• Si esa ruta heredada del espacio de trabajo no existe (ENOENT/ENOTDIR), OpenClaw recurre al cwd predeterminado del backend en lugar de reutilizar silenciosamente el árbol equivocado.
• Si el espacio de trabajo heredado existe pero no se puede acceder a él (por ejemplo EACCES), la creación devuelve el error real de acceso en lugar de omitir cwd.

• superficie de chat: donde la gente sigue hablando (canal de Discord, tema de Telegram, chat de iMessage)
• sesión ACP: el estado duradero del runtime de Codex/Claude/Gemini al que OpenClaw enruta
• hilo/tema secundario: una superficie adicional opcional de mensajería creada solo por --thread ...
• espacio de trabajo del runtime: la ubicación del sistema de archivos donde se ejecuta el harness (cwd, checkout del repositorio, espacio de trabajo del backend)

• /acp spawn codex --bind here: mantener este chat, crear o adjuntar una sesión ACP de Codex y enrutarle aquí los mensajes futuros
• /acp spawn codex --thread auto: OpenClaw puede crear un hilo/tema secundario y vincular allí la sesión ACP
• /acp spawn codex --bind here --cwd /workspace/repo: misma vinculación de chat que arriba, pero Codex se ejecuta en /workspace/repo

• Los canales de chat/mensajería que anuncian compatibilidad de vinculación con la conversación actual pueden usar --bind here mediante la ruta compartida de vinculación de conversaciones.
• Los canales con semánticas personalizadas de hilo/tema pueden seguir proporcionando canonicalización específica del canal detrás de la misma interfaz compartida.
• --bind here siempre significa “vincular la conversación actual en su lugar”.
• Las vinculaciones genéricas con la conversación actual usan el almacén compartido de vinculaciones de OpenClaw y sobreviven a los reinicios normales del gateway.

• --bind here y --thread ... son mutuamente excluyentes en /acp spawn.
• En Discord, --bind here vincula el canal o hilo actual en su lugar. spawnAcpSessions solo es necesario cuando OpenClaw tiene que crear un hilo secundario para --thread auto|here.
• Si el canal activo no expone vinculaciones ACP con la conversación actual, OpenClaw devuelve un mensaje claro de no compatibilidad.
• resume y las preguntas de “sesión nueva” son cuestiones de sesión ACP, no del canal. Puedes reutilizar o reemplazar el estado del runtime sin cambiar la superficie de chat actual.

​

Sesiones vinculadas 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/caducidad por inactividad o caducidad por edad máxima elimina la vinculación.

• acp.enabled=true
• acp.dispatch.enabled está activado de forma predeterminada (ponlo en false para pausar el despacho ACP)
• Indicador de creación ACP de hilo del adaptador de canal habilitado (específico del adaptador)
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

​

Canales compatibles con hilos

• Cualquier adaptador de canal que exponga capacidad de vinculación de sesión/hilo.
• Compatibilidad integrada actual:
  • hilos/canales de Discord
  • temas de Telegram (temas de foro en grupos/supergrupos y temas de DM)
• Los canales de plugins pueden añadir compatibilidad mediante la misma interfaz de vinculación.

​

Configuración específica por canal

​

Modelo de vinculación

• bindings[].type="acp" marca una vinculación persistente de conversación ACP.
• 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>"
  • chat DM/de grupo de BlueBubbles: match.channel="bluebubbles" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Prefiere chat_id:* o chat_identifier:* para vinculaciones estables de grupos.
  • chat DM/de grupo de iMessage: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Prefiere chat_id:* para vinculaciones estables de grupos.
• bindings[].agentId es el id del agente propietario de OpenClaw.
• Los overrides ACP opcionales viven en bindings[].acp:
  • mode (persistent o oneshot)
  • label
  • cwd
  • backend

​

Valores predeterminados de runtime por agente

• 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

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

{
  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 } },
        },
      },
    },
  },
}

• 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 mismo lugar.
• Las vinculaciones temporales de runtime (por ejemplo creadas por flujos de enfoque de hilo) siguen aplicándose cuando están presentes.
• Para creaciones ACP entre agentes sin cwd explícito, OpenClaw hereda el espacio de trabajo del agente objetivo desde la configuración del agente.
• Las rutas heredadas del espacio de trabajo que no existen recurren al cwd predeterminado del backend; los fallos reales de acceso se muestran como errores de creación.

​

Iniciar sesiones ACP (interfaces)

​

Desde sessions_spawn

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

• runtime usa subagent de forma predeterminada, 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 persistente vinculada.

• task (obligatorio): prompt inicial enviado a la sesión ACP.
• runtime (obligatorio para ACP): debe ser "acp".
• agentId (opcional): id del harness ACP objetivo. Recurre a acp.defaultAgent si está definido.
• thread (opcional, predeterminado false): solicita un flujo de vinculación con hilo donde se admita.
• mode (opcional): run (puntual) o session (persistente).
  • el valor predeterminado es run
  • si thread: true y se omite mode, OpenClaw puede usar comportamiento persistente por defecto según la ruta de runtime
  • mode: "session" requiere thread: true
• cwd (opcional): directorio de trabajo solicitado para el runtime (validado por la política del backend/runtime). Si se omite, la creación ACP hereda el espacio de trabajo del agente objetivo cuando está configurado; las rutas heredadas que no existen recurren a los valores predeterminados del backend, mientras que los errores reales de acceso se devuelven.
• label (opcional): etiqueta visible para el operador usada en el texto de sesión/banner.
• resumeSessionId (opcional): reanuda una sesión ACP existente en lugar de crear una nueva. El agente vuelve a reproducir su historial de conversación mediante session/load. Requiere runtime: "acp".
• streamTo (opcional): "parent" transmite resúmenes del progreso de la ejecución ACP inicial de vuelta a la sesión solicitante como eventos del sistema.
  • Cuando está disponible, las respuestas aceptadas incluyen streamLogPath que apunta a un registro JSONL con alcance de sesión (<sessionId>.acp-stream.jsonl) que puedes seguir para ver el historial completo del relay.

​

Reanudar una sesión existente

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

• Transferir una sesión de Codex desde tu portátil a tu teléfono: dile a tu agente que retome donde lo dejaste
• Continuar una sesión de programación que empezaste de forma interactiva en la CLI, ahora sin interfaz mediante tu agente
• Retomar trabajo interrumpido por un reinicio del gateway o una caducidad por inactividad

• resumeSessionId requiere runtime: "acp"; devuelve un error si se usa con el runtime de subagente.
• 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" sigue requiriendo thread: true.
• El agente objetivo 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; no hay retorno silencioso a una sesión nueva.

​

Prueba rápida para operadores

1. Verifica la versión/commit del gateway desplegado en el host de destino.
2. Confirma que el código 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 hacia un agente en vivo (por ejemplo razor(main) en jpclawhq).
4. Pide 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 informe:
   • accepted=yes
   • una childSessionKey real
   • sin error de validación
6. Limpia la sesión puente ACPX temporal.

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>.

• Mantén esta prueba rápida en mode: "run" a menos que estés probando intencionalmente sesiones ACP persistentes vinculadas a hilos.
• No exijas streamTo: "parent" para la puerta básica. Esa ruta depende de las capacidades de la sesión/solicitante y es una comprobación de integración aparte.
• Trata las pruebas de mode: "session" vinculadas a hilos como una segunda pasada de integración más rica desde un hilo real de Discord o un tema de Telegram.

​

Compatibilidad con sandbox

• 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 admite 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".

​

Desde el comando /acp

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

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

​

Resolución de objetivos de sesión

1. Argumento de objetivo explícito (o --session para /acp steer)
   • primero intenta con la clave
   • luego con un id de sesión con forma de UUID
   • luego con la etiqueta
2. Vinculación del hilo actual (si esta conversación/hilo está vinculada a una sesión ACP)
3. Respaldo de la sesión solicitante actual

​

Modos de vinculación al crear

• --bind here es la ruta más sencilla para el operador para “hacer que este canal o chat use Codex”.
• --bind here no crea un hilo secundario.
• --bind here solo está disponible en canales que exponen compatibilidad con vinculación de conversación actual.
• --bind y --thread no pueden combinarse en la misma llamada a /acp spawn.

​

Modos de hilo al crear

• En superficies sin vinculación de hilos, el comportamiento predeterminado equivale en la práctica a off.
• La creación vinculada a hilos requiere compatibilidad de política del canal:
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true
• Usa --bind here cuando quieras fijar la conversación actual sin crear un hilo secundario.

​

Controles ACP

• /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

​

Recetario de comandos ACP

​

Mapeo de opciones de runtime

• /acp model <id> se asigna a la clave de configuración de runtime model.
• /acp permissions <profile> se asigna a la clave de configuración de runtime approval_policy.
• /acp timeout <seconds> se asigna a la clave de configuración de runtime timeout.
• /acp cwd <path> actualiza directamente el override de cwd del runtime.
• /acp set <key> <value> es la ruta genérica.
  • Caso especial: key=cwd usa la ruta de override de cwd.
• /acp reset-options borra todos los overrides de runtime para la sesión objetivo.

​

Compatibilidad actual de harnesses acpx

• claude
• codex
• copilot
• cursor (Cursor CLI: cursor-agent acp)
• droid
• gemini
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• pi
• qwen

​

Configuración requerida

{
  acp: {
    enabled: true,
    // Opcional. El valor predeterminado es true; ponlo en false para pausar el despacho ACP y mantener los controles /acp.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "openclaw",
      "opencode",
      "pi",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

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

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

​

Configuración del plugin para backend acpx

/acp doctor

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

openclaw plugins install ./path/to/local/acpx-plugin

/acp doctor

​

Configuración de comando y versión de acpx

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

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

• command acepta una ruta absoluta, ruta relativa o nombre de comando (acpx).
• Las rutas relativas se resuelven desde el directorio del espacio de trabajo de OpenClaw.
• expectedVersion: "any" desactiva la coincidencia estricta de versión.
• Cuando command apunta a un binario/ruta personalizados, la instalación automática local al plugin se desactiva.
• El arranque de OpenClaw sigue siendo no bloqueante mientras se ejecuta la comprobación de estado del backend.

​

Instalación automática de dependencias

​

Puente MCP de herramientas de plugins

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

• Inyecta un servidor MCP integrado llamado openclaw-plugin-tools en el arranque de la sesión ACPX.
• Expone herramientas de plugins ya registradas por plugins instalados y habilitados de OpenClaw.
• Mantiene la función explícita y desactivada por defecto.

• Esto amplía la superficie de herramientas del harness ACP.
• Los agentes ACP obtienen acceso solo a herramientas de plugins ya activas en el gateway.
• Trátalo como el mismo límite de confianza que permitir que esos plugins se ejecuten en OpenClaw.
• Revisa los plugins instalados antes de habilitarlo.

​

Configuración del timeout del runtime

openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

​

Configuración de permisos

​

permissionMode

​

nonInteractivePermissions

​

Configuración

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

Importante: OpenClaw usa actualmente por defecto permissionMode=approve-reads y nonInteractivePermissions=fail. En sesiones ACP no interactivas, cualquier escritura o exec que active un prompt de permisos 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 de forma elegante en lugar de bloquearse.

​

Solución de problemas