​

Agentes ACP

​

¿Qué página necesito?

​

¿Esto funciona listo para usar?

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

• Un adaptador de harness de destino puede descargarse bajo demanda con npx la primera vez que uses ese harness.
• La autenticación del proveedor aún debe 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 la caché se precaliente o el adaptador se instale de otra manera.

• /acp spawn codex: OpenClaw debería estar listo para inicializar acpx, pero el adaptador ACP de Codex aún podría necesitar una descarga en el primer uso.
• /acp spawn claude: la misma situación para 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. Redirige 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)

​

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 de Claude Code de una sola vez 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 objetivo del harness solicitado (agentId, por ejemplo codex).
3. Si se solicita una vinculación a 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 una vinculación a un 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, se cierre o expire.

​

ACP frente a subagentes

​

Cómo ACP ejecuta Claude Code

1. Plano de control de sesiones ACP de OpenClaw
2. plugin de runtime acpx integrado
3. Adaptador ACP de Claude
4. Maquinaria de runtime/sesión del lado de Claude

• Claude sobre ACP no es lo mismo que el runtime de respaldo directo claude-cli/....
• Claude sobre 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.
• claude-cli/... es un backend CLI local solo de texto. Consulta Backends de CLI.

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

​

Sesiones vinculadas

​

Vinculaciones a la conversación actual

• OpenClaw sigue siendo responsable del transporte del canal, autenticación, seguridad y entrega.
• La conversación actual se fija 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 restablecen la misma sesión ACP vinculada en su 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 canal actual.
• --bind here aún puede crear una nueva sesión ACP si estás iniciando trabajo nuevo. La vinculación adjunta esa sesión a la conversación actual.
• --bind here no crea por sí solo un hilo secundario de Discord ni un tema de Telegram.
• El runtime ACP aún puede tener su propio directorio de trabajo (cwd) o espacio de trabajo administrado por el backend en disco. Ese espacio de trabajo del runtime es independiente de la superficie de chat y no implica un nuevo hilo de mensajería.
• Si creas una sesión para otro agente ACP y no pasas --cwd, OpenClaw hereda de forma predeterminada el espacio de trabajo del agente de destino, no del solicitante.
• Si falta esa ruta de espacio de trabajo heredada (ENOENT/ENOTDIR), OpenClaw recurre al cwd predeterminado del backend en lugar de reutilizar silenciosamente el árbol incorrecto.
• 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 las personas siguen 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 al chat que arriba, pero Codex se ejecuta en /workspace/repo

• Los canales de chat/mensajes que anuncian compatibilidad con vinculación a la conversación actual pueden usar --bind here mediante la ruta compartida de vinculación de conversaciones.
• Los canales con semántica personalizada de hilos/temas aún pueden proporcionar 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 a la conversación actual usan el almacén compartido de vinculaciones de OpenClaw y sobreviven a 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 necesita crear un hilo secundario para --thread auto|here.
• Si el canal activo no expone vinculaciones ACP a la conversación actual, OpenClaw devuelve un mensaje claro de no compatible.
• resume y las preguntas de “sesión nueva” son preguntas sobre la sesión ACP, no sobre el 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 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.
• Desenfocar/cerrar/archivar/expiración por tiempo de inactividad o por antigüedad máxima elimina la vinculación.

• acp.enabled=true
• acp.dispatch.enabled está activado de forma predeterminada (configúralo en 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 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 plugin pueden añadir compatibilidad mediante la misma interfaz de vinculación.

​

Ajustes específicos de canal

​

Modelo de vinculación

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

​

Valores predeterminados del 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 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 restablecen en su lugar la misma clave de sesión ACP.
• Las vinculaciones temporales del runtime (por ejemplo las creadas 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 heredadas de espacio de trabajo que faltan recurren al cwd predeterminado del backend; los fallos reales de acceso en rutas existentes 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 por defecto subagent, así que configura explícitamente runtime: "acp" 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.

• task (obligatorio): prompt inicial enviado a la sesión ACP.
• runtime (obligatorio para ACP): debe ser "acp".
• agentId (opcional): id del harness ACP de destino. Usa acp.defaultAgent como respaldo si está configurado.
• thread (opcional, predeterminado false): solicita flujo de vinculación a hilo donde sea compatible.
• mode (opcional): run (una sola vez) o session (persistente).
  • el valor predeterminado es run
  • si thread: true y se omite el modo, OpenClaw puede usar un comportamiento persistente predeterminado según la ruta del 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 de destino cuando esté configurado; las rutas heredadas ausentes recurren a los valores predeterminados del backend, mientras que los errores reales de acceso se devuelven.
• label (opcional): etiqueta orientada al 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 reproduce 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 de tu portátil a tu teléfono: indica a tu agente que retome donde lo dejaste
• Continuar una sesión de programación que comenzaste de forma interactiva en la CLI, ahora de forma headless mediante tu agente
• Retomar trabajo que fue interrumpido por un reinicio del gateway o por expiración 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 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 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; no hay respaldo silencioso a una sesión nueva.

​

Prueba de humo para operadores

1. Verifica la versión/commit del gateway desplegado en el host de destino.
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 temporal de puente ACPX 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"
   • tarea: Reply with exactly LIVE-ACP-SPAWN-OK
5. Verifica que el agente informe:
   • accepted=yes
   • una childSessionKey real
   • ningún error de validador
6. Limpia la sesión temporal de puente ACPX.

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 de humo 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 del solicitante/la sesión y es una comprobación de integración aparte.
• Trata las pruebas vinculadas a hilos con mode: "session" como una segunda pasada de integración más completa 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 destino de sesión

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

​

Modos de vinculación al crear

• --bind here es la ruta más simple para operadores 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 a la 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 a hilos, el comportamiento predeterminado es efectivamente off.
• La creación vinculada a hilos requiere compatibilidad de la 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 reemplazo de cwd del runtime.
• /acp set <key> <value> es la ruta genérica.
  • Caso especial: key=cwd usa la ruta de reemplazo de cwd.
• /acp reset-options borra todos los reemplazos de runtime para la sesión de destino.

​

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 obligatoria

{
  acp: {
    enabled: true,
    // Opcional. El valor predeterminado es true; configúralo en false para pausar el despacho ACP manteniendo 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 el 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 node_modules/.bin/acpx local del 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 listo.
4. Un trabajo de ensure en segundo plano verifica 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.

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

• command acepta una ruta absoluta, una ruta relativa o un nombre de comando (acpx).
• Las rutas relativas se resuelven desde el directorio del espacio de trabajo de OpenClaw.
• expectedVersion: "any" desactiva la comprobación estricta de versión.
• Cuando command apunta a un binario/ruta personalizado, se desactiva la instalación automática local del plugin.
• El inicio de OpenClaw sigue sin bloquear 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 bootstrap de la sesión ACPX.
• Expone herramientas de plugins ya registradas por plugins de OpenClaw instalados y habilitados.
• Mantiene la función explícita y desactivada de forma predeterminada.

• Esto amplía la superficie de herramientas del harness ACP.
• Los agentes ACP obtienen acceso solo a las 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 el propio OpenClaw.
• Revisa los plugins instalados antes de habilitarlo.

​

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: Actualmente, OpenClaw usa por defecto permissionMode=approve-reads y nonInteractivePermissions=fail. En sesiones ACP no interactivas, cualquier escritura o ejecución que active una solicitud de permisos puede fallar con AcpRuntimeError: Permission prompt unavailable in non-interactive mode. Si necesitas restringir permisos, configura nonInteractivePermissions en deny para que las sesiones se degraden de forma controlada en lugar de fallar.

​

Solución de problemas