acp

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

Este comando habla ACP sobre stdio para IDEs y reenvía los prompts al Gateway por WebSocket. Mantiene las sesiones ACP mapeadas a claves de sesión del Gateway.

openclaw acp es un puente ACP respaldado por el Gateway, no un runtime nativo de ACP completo. Se enfoca en el enrutamiento de sesiones, la entrega de prompts y las actualizaciones básicas de streaming.

Matriz de compatibilidad

Limitaciones conocidas

• loadSession reproduce el historial almacenado de texto de usuario y asistente, pero no reconstruye llamadas a herramientas históricas, avisos del sistema, ni tipos de eventos nativos de ACP más ricos.
• Si múltiples clientes ACP comparten la misma clave de sesión del Gateway, el enrutamiento de eventos y cancelación es de mejor esfuerzo en lugar de estar estrictamente aislado por cliente. Prefiere las sesiones aisladas por defecto acp:<uuid> cuando necesites turnos limpios locales del editor.
• Los estados de parada del Gateway se traducen a razones de parada ACP, pero ese mapeo es menos expresivo que un runtime completamente nativo de ACP.
• Los controles iniciales de sesión actualmente exponen un subconjunto enfocado de opciones 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 ACP.
• session_info_update y usage_update se derivan de snapshots de sesión del Gateway, no de contabilidad nativa del runtime ACP. El uso es aproximado, no incluye datos de costo, y solo se emite cuando el Gateway marca los datos totales de tokens como actualizados.
• Los datos de seguimiento de herramientas son de mejor esfuerzo. El puente puede mostrar rutas de archivos que aparecen en args/resultados conocidos de herramientas, pero aún no emite terminales ACP ni diffs estructurados de archivos.

Uso

openclaw acp

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

# Gateway remoto (token desde archivo)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Conectar a una clave de sesión existente
openclaw acp --session agent:main:main

# Conectar por etiqueta (debe existir previamente)
openclaw acp --session-label "support inbox"

# Reiniciar la clave de sesión antes del primer prompt
openclaw acp --session agent:main:main --reset-session

Cliente ACP (depuración)

Usa el cliente ACP integrado para verificar el puente sin un IDE. Inicia el puente ACP y te permite escribir prompts interactivamente.

openclaw acp client

# Apuntar el puente iniciado a un Gateway remoto
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Sobrescribir el comando del servidor (por defecto: 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 auto-aprobación se basa en una lista blanca y solo aplica a IDs de herramientas principales de confianza.
• La auto-aprobación de read está limitada al directorio de trabajo actual (--cwd cuando se establece).
• Los nombres de herramientas desconocidos/no principales, las lecturas fuera de alcance y las herramientas peligrosas siempre requieren aprobación explícita por prompt.
• El toolCall.kind proporcionado por el servidor se trata como metadatos no confiables (no es una fuente de autorización).

Cómo usar esto

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

1. Asegúrate de que el Gateway esté corriendo (local o remoto).
2. Configura el destino del Gateway (configuración o flags).
3. Apunta tu IDE para que ejecute openclaw acp sobre 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 escritura de configuración):

openclaw acp --url wss://gateway-host:18789 --token <token>
# preferido para seguridad de procesos locales
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

Seleccionar agentes

ACP no selecciona agentes directamente. Enruta por la clave de sesión del Gateway.

Usa claves de sesión con alcance de agente para apuntar 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 ACP se mapea a una única clave de sesión del Gateway. Un agente puede tener muchas sesiones; ACP usa por defecto una sesión aislada acp:<uuid> a menos que sobrescribas la clave o etiqueta.

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

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

Si quieres que un agente de programación como Codex o Claude Code hable con tu bot de OpenClaw a través de ACP, usa acpx con su objetivo openclaw integrado.

Flujo típico:

1. Ejecuta el Gateway y asegúrate de que el puente ACP pueda alcanzarlo.
2. Apunta acpx openclaw a openclaw acp.
3. Apunta a la clave de sesión de OpenClaw que quieres que use el agente de programación.

Ejemplos:

# Solicitud de un solo uso en tu sesión ACP por defecto de OpenClaw
acpx openclaw exec "Summarize the active OpenClaw session state."

# Sesión con nombre persistente para turnos de seguimiento
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 clave de sesión específicos en cada ejecución, 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 el repositorio, usa el punto de entrada directo del CLI en lugar del ejecutor de desarrollo para que el stream 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 fácil de permitir que Codex, Claude Code u otro cliente compatible con ACP obtenga información contextual de un agente de OpenClaw sin hacer scraping de una terminal.

Configuración del editor Zed

Agrega 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 Agente y selecciona “OpenClaw ACP” para iniciar un hilo.

Mapeo de sesiones

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

• --session <key>: usa una clave de sesión específica del Gateway.
• --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 ACP soporta metadatos, puedes sobrescribir por sesión:

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

Más información sobre claves de sesión en /concepts/session.

Opciones

• --url <url>: URL WebSocket del Gateway (usa gateway.remote.url cuando está configurado por defecto).
• --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/etiqueta de sesión no existe.
• --reset-session: reinicia la clave de sesión antes del primer uso.
• --no-prefix-cwd: no prefijar los prompts con el directorio de trabajo.
• --verbose, -v: registro detallado a stderr.

Nota de seguridad:

• --token y --password pueden ser visibles en listados de procesos locales en algunos sistemas.
• Prefiere --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 usado por otros clientes del 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 de forma cerrada)
  • modo remoto: gateway.remote.* con fallback de env/config según 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 ACP reciben OPENCLAW_SHELL=acp, que puede usarse para reglas de shell/perfil específicas del contexto.
• openclaw acp client establece OPENCLAW_SHELL=acp-client en el proceso del puente iniciado.

Opciones de acp client

• --cwd <dir>: directorio de trabajo para la sesión ACP.
• --server <command>: comando del servidor ACP (por defecto: openclaw).
• --server-args <args...>: argumentos adicionales pasados al servidor ACP.
• --server-verbose: habilitar registro detallado en el servidor ACP.
• --verbose, -v: registro detallado del cliente.