Conecta OpenClaw con ACP: Puente de Gateway para IDEs

Ejecuta el bridge del Agent Client Protocol (ACP) que se comunica con un OpenClaw Gateway.

Este comando habla ACP a través de stdio para IDEs y reenvía los prompts al Gateway mediante WebSocket. Mantiene las sesiones de ACP vinculadas a las claves de sesión del Gateway.

openclaw acp es un bridge de ACP respaldado por el Gateway, no un runtime de editor nativo de ACP completo. Se centra en el enrutamiento de sesiones y la entrega de prompts, junto con actualizaciones básicas de streaming.

Si quieres que un cliente MCP externo hable directamente con las conversaciones de los canales de OpenClaw en lugar de alojar una sesión de ACP, usa openclaw mcp serve en su lugar.

Matriz de compatibilidad

Área ACP	Estado	Notas
initialize, newSession, prompt, cancel	Implementado	Flujo principal del bridge sobre stdio hacia el chat/envío del Gateway y la acción de abortar.
listSessions, slash commands	Implementado	La lista de sesiones funciona contra el estado de sesión del Gateway; los comandos se anuncian mediante available_commands_update.
loadSession	Parcial	Vuelve a vincular la sesión ACP a una clave de sesión del Gateway y reproduce el historial de texto almacenado del usuario y del asistente. El historial de herramientas o del sistema aún no se reconstruye.
Contenido del prompt (text, resource integrado, imágenes)	Parcial	El texto y los recursos se aplanan en la entrada del chat; las imágenes se convierten en adjuntos del Gateway.
Modos de sesión	Parcial	Se soporta session/set_mode y el bridge expone controles iniciales de sesión respaldados por el Gateway para nivel de pensamiento, verbosidad de herramientas, razonamiento, detalle de uso y acciones elevadas. Superficies de configuración o modo nativas de ACP más amplias siguen fuera del alcance.
Actualizaciones de uso e información de sesión	Parcial	El bridge emite notificaciones de session_info_update y usage_update (mejor esfuerzo) desde capturas de sesión del Gateway en caché. El uso es aproximado y solo se envía cuando los totales de tokens del Gateway se marcan como actualizados.
Streaming de herramientas	Parcial	Los eventos tool_call / tool_call_update incluyen I/O sin procesar y contenido de texto, además de ubicaciones de archivos (mejor esfuerzo) cuando los argumentos o resultados de las herramientas del Gateway los exponen. Terminales integradas y salidas nativas de diff más ricas aún no se exponen.
Servidores MCP por sesión (mcpServers)	No soportado	El modo bridge rechaza solicitudes de servidores MCP por sesión. Configura MCP en el Gateway o agente de OpenClaw en su lugar.
Métodos de sistema de archivos del cliente (fs/read_text_file, fs/write_text_file)	No soportado	El bridge no llama a los métodos del sistema de archivos del cliente ACP.
Métodos de terminal del cliente (terminal/*)	No soportado	El bridge no crea terminales de cliente ACP ni transmite IDs de terminal a través de llamadas a herramientas.
Planes de sesión / streaming de pensamiento	No soportado	El bridge actualmente emite texto de salida y estado de herramientas, no actualizaciones de planes o pensamientos de ACP.

Limitaciones conocidas

• loadSession reproduce el historial de texto almacenado del usuario y del asistente, pero no reconstruye las llamadas a herramientas históricas ni los avisos del sistema. Tampoco recupera tipos de eventos nativos de ACP más complejos.
• Si varios clientes ACP comparten la misma clave de sesión del Gateway, el enrutamiento de eventos y cancelaciones se realiza por mejor esfuerzo en lugar de estar estrictamente aislado por cliente. Es mejor que uses las sesiones aisladas acp:<uuid> por defecto cuando necesites turnos limpios y locales en el editor.
• Los estados de parada del Gateway se traducen en motivos de parada de ACP, aunque ese mapeo es menos expresivo que un runtime totalmente nativo de ACP.
• Los controles de sesión iniciales muestran actualmente un subconjunto específico de ajustes del Gateway: nivel de pensamiento, verbosidad de herramientas, razonamiento, detalle de uso y acciones elevadas. La selección de modelo y los controles de exec-host aún no se exponen como opciones de configuración de ACP.
• session_info_update y usage_update se derivan de capturas de sesión del Gateway, no de una contabilidad en vivo del runtime nativo de ACP. El uso es aproximado y no incluye datos de costo; solo se emite cuando el Gateway marca los datos totales de tokens como actualizados.
• Los datos de seguimiento de herramientas funcionan por mejor esfuerzo. El bridge puede mostrar rutas de archivos que aparecen en argumentos o resultados de herramientas conocidos, pero aún no emite terminales ACP ni diffs de archivos estructurados.

Pasos siguientes

• openclaw mcp serve

AI Setup Assistant

Uso

Para empezar a trabajar, puedes ejecutar el comando base directamente. Si necesitas conectarte a un Gateway remoto, pasa la URL y el token como parámetros, o utiliza un archivo de tokens para que sea más seguro.

openclaw acp

# Remote Gateway
openclaw acp --url wss://gateway-host:18789 --token <token>

# Remote Gateway (token from file)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Attach to an existing session key
openclaw acp --session agent:main:main

# Attach by label (must already exist)
openclaw acp --session-label "support inbox"

# Reset the session key before the first prompt
openclaw acp --session agent:main:main --reset-session

Cliente ACP (depuración)

Te recomiendo usar el cliente ACP integrado para comprobar que el bridge funciona bien sin tener que configurar un IDE. Este cliente lanza el bridge de ACP y te permite escribir prompts de forma interactiva para probar el sistema.

openclaw acp client

# Point the spawned bridge at a remote Gateway
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Override the server command (default: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

Modelo de permisos (modo de depuración del cliente):

• La aprobación automática se basa en una allowlist y solo se aplica a IDs de herramientas core que son de confianza.
• La aprobación automática de tipo read está limitada al directorio de trabajo actual (el valor de --cwd cuando se define).
• ACP solo aprueba automáticamente categorías de solo lectura muy restringidas: llamadas read dentro del cwd activo y herramientas de búsqueda de solo lectura (search, web_search, memory_search). Las herramientas desconocidas o que no pertenecen al core, las lecturas fuera de scope, las herramientas con capacidad de ejecución (exec), las de plano de control, las herramientas que modifican datos y los flujos interactivos requieren siempre tu aprobación explícita.
• El valor toolCall.kind proporcionado por el servidor se trata como metadatos no confiables, por lo que no se utiliza como fuente de autorización.
• Esta política del bridge de ACP es independiente de los permisos del harness ACPX. Si decides ejecutar OpenClaw mediante el backend acpx, la opción plugins.entries.acpx.config.permissionMode=approve-all es el interruptor de emergencia para esa sesión del harness.

Cómo usar esto

Usa ACP cuando un IDE (u otro cliente) hable Agent Client Protocol y quieras que controle una sesión de OpenClaw Gateway.

1. Asegúrate de que el Gateway esté funcionando (local o remoto).
2. Configura el destino del Gateway (mediante config o flags).
3. Configura tu IDE para ejecutar openclaw acp a través de stdio.

Ejemplo de configuración (persistida):

openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>

Ejemplo de ejecución directa (sin escribir en la configuración):

openclaw acp --url wss://gateway-host:18789 --token <token>
# preferred for local process safety
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

Selección de agentes

ACP no elige agentes directamente. Realiza el enrutamiento mediante la session key del Gateway.

Usa session keys con alcance de agente para dirigirte a un agente específico:

openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123

Cada sesión de ACP se mapea a una única session key del Gateway. Un agente puede tener muchas sesiones; ACP usa por defecto una sesión aislada acp:<uuid> a menos que sobrescribas la key o la etiqueta.

Los mcpServers por sesión no están soportados en modo bridge. Si un cliente ACP los envía durante newSession o loadSession, el bridge devuelve un error claro en lugar de ignorarlos en silencio.

Si quieres que las sesiones basadas en ACPX vean las herramientas de los plugins de OpenClaw, activa el bridge del plugin ACPX en el lado del gateway en lugar de intentar pasar mcpServers por sesión. Consulta ACP Agents.

Uso desde acpx (Codex, Claude, Copilot y otros clientes ACP)

Si quieres que un agente de código como Codex o Claude Code se comunique con tu bot de OpenClaw mediante ACP, usa acpx con su objetivo openclaw integrado.

Flujo típico:

1. Ejecuta el Gateway en tu entorno.
2. Asegúrate de que el bridge ACP tenga acceso a él.
3. Apunta acpx openclaw hacia openclaw acp.
4. Selecciona la clave de sesión de OpenClaw que debe usar el agente.

Ejemplos:

# One-shot request into your default OpenClaw ACP session
acpx openclaw exec "Summarize the active OpenClaw session state."

# Persistent named session for follow-up turns
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
  "Ask my OpenClaw work agent for recent context relevant to this repo."

Si quieres que acpx openclaw apunte a un Gateway y una clave de sesión específicos siempre, sobrescribe el comando del agente openclaw en ~/.acpx/config.json:

{
  "agents": {
    "openclaw": {
      "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"
    }
  }
}

Para un checkout local de OpenClaw en un repo, usa el punto de entrada directo de la CLI en lugar del dev runner para que el stream de ACP se mantenga limpio. Por ejemplo:

env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...

Esta es la forma más sencilla de permitir que Codex o Claude Code extraigan información contextual de un agente de OpenClaw sin tener que leer la terminal.

Configuración en el editor Zed

Añade un agente ACP personalizado en ~/.config/zed/settings.json o usa la interfaz de configuración de Zed:

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": ["acp"],
      "env": {}
    }
  }
}

Para apuntar a un Gateway o agente específico:

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": [
        "acp",
        "--url",
        "wss://gateway-host:18789",
        "--token",
        "<token>",
        "--session",
        "agent:design:main"
      ],
      "env": {}
    }
  }
}

En Zed, abre el panel de Agent y selecciona “OpenClaw ACP” para iniciar un hilo.

Mapeo de sesiones

Por defecto, las sesiones de ACP obtienen una clave de sesión de Gateway aislada con el prefijo acp:. Si quieres reutilizar una sesión conocida, pasa una clave o etiqueta de sesión:

• --session <key>: usa una clave de sesión de Gateway específica.
• --session-label <label>: resuelve una sesión existente por etiqueta.
• --reset-session: genera un nuevo ID de sesión para esa clave (misma clave, nueva transcripción).

Si tu cliente de ACP admite metadatos, puedes sobrescribirlos por sesión:

{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  }
}

Aprende más sobre las claves de sesión en /concepts/session.

Opciones

• --url <url>: URL de WebSocket del Gateway (por defecto es gateway.remote.url cuando está configurado).
• --token <token>: Token de autenticación del Gateway.
• --token-file <path>: lee el token de autenticación del Gateway desde un archivo.
• --password <password>: Contraseña de autenticación del Gateway.
• --password-file <path>: lee la contraseña de autenticación del Gateway desde un archivo.
• --session <key>: clave de sesión por defecto.
• --session-label <label>: etiqueta de sesión por defecto a resolver.
• --require-existing: falla si la clave o etiqueta de sesión no existe.
• --reset-session: reinicia la clave de sesión antes del primer uso.
• --no-prefix-cwd: no añade el directorio de trabajo como prefijo a los prompts.
• --verbose, -v: registro detallado (verbose) en stderr.

Nota de seguridad:

• --token y --password pueden ser visibles en las listas de procesos locales en algunos sistemas.
• Es mejor usar --token-file/--password-file o variables de entorno (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD).
• La resolución de autenticación del Gateway sigue el contrato compartido que usan otros clientes de Gateway:
  • modo local: env (OPENCLAW_GATEWAY_*) -> gateway.auth.* -> fallback a gateway.remote.* solo cuando gateway.auth.* no está configurado (los SecretRefs locales configurados pero no resueltos fallan por seguridad).
  • modo remoto: gateway.remote.* con fallback de env/config según las reglas de precedencia remota.
  • --url es seguro para sobrescribir y no reutiliza credenciales implícitas de config/env; pasa --token/--password explícitos (o variantes de archivo).
• Los procesos hijos del backend del runtime de ACP reciben OPENCLAW_SHELL=acp, que puedes usar