ACP

​

Qué no es

• el editor/cliente desea comunicarse mediante ACP con OpenClaw: utilice openclaw acp
• OpenClaw debe iniciar Codex/Claude/Gemini como entorno ACP: utilice /acp spawn y Agentes ACP

​

Matriz de compatibilidad

​

Limitaciones conocidas

• loadSession reproduce el historial completo del registro de eventos ACP solo para las sesiones creadas por el puente. Las sesiones antiguas o sin registro utilizan el respaldo de la transcripción y no reconstruyen llamadas históricas a herramientas ni avisos del sistema.
• Si varios clientes ACP comparten la misma clave de sesión del Gateway, el enrutamiento de eventos y cancelaciones es de mejor esfuerzo, en lugar de estar estrictamente aislado por cliente. Se recomienda usar las sesiones acp-bridge:<uuid> aisladas predeterminadas cuando se necesiten turnos locales del editor claramente separados.
• Los estados de detención del Gateway se traducen en motivos de detención de ACP, pero esa correspondencia es menos expresiva que la de un entorno de ejecución completamente nativo de ACP.
• Los controles de sesión exponen un subconjunto específico de opciones del Gateway: nivel de pensamiento, verbosidad de las herramientas, razonamiento, detalle de uso y acciones con privilegios elevados. La selección de modelos y los controles del host de ejecución no se exponen como opciones de configuración de ACP.
• session_info_update y usage_update se derivan de instantáneas de sesiones del Gateway, no de la contabilidad en tiempo real de un entorno de ejecución nativo de ACP. El uso es aproximado, no incluye datos de costes y solo se emite cuando el Gateway marca como recientes los datos del total de tokens.
• Los datos de seguimiento de las herramientas son de mejor esfuerzo: el puente muestra las rutas de archivos que aparecen en argumentos o resultados conocidos de herramientas, pero no emite terminales ACP ni diferencias estructuradas de archivos.
• La retransmisión de aprobaciones de ejecución se limita al turno activo de la solicitud ACP; se ignoran las aprobaciones de otras sesiones del Gateway.

​

Uso

openclaw acp

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

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

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

# Conectarse mediante una etiqueta (debe existir previamente)
openclaw acp --session-label "support inbox"

# Restablecer la clave de sesión antes de la primera solicitud
openclaw acp --session agent:main:main --reset-session

​

Cliente ACP (depuración)

openclaw acp client

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

# Reemplazar el comando del servidor (valor predeterminado: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

• La aprobación automática se basa en una lista de permitidos y solo se aplica a identificadores de herramientas principales de confianza.
• La aprobación automática de read se limita al directorio de trabajo actual (--cwd cuando está configurado).
• ACP solo aprueba automáticamente categorías restringidas de solo lectura: llamadas read limitadas al directorio de trabajo activo, además de herramientas de búsqueda de solo lectura (search, web_search, memory_search). Las herramientas desconocidas o no principales, las lecturas fuera del ámbito, las herramientas con capacidad de ejecución, las herramientas del plano de control, las herramientas que realizan modificaciones y los flujos interactivos siempre requieren la aprobación explícita de la solicitud.
• El valor toolCall.kind proporcionado por el servidor se trata como metadatos no fiables, no como fuente de autorización.
• Esta política del puente ACP es independiente de los permisos del entorno ACPX. Si se ejecuta OpenClaw mediante el backend acpx, plugins.entries.acpx.config.permissionMode=approve-all es el interruptor de emergencia «yolo» para esa sesión del entorno.

​

Pruebas rápidas del protocolo

{
  "initialize": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionCapabilities": {
        "list": {},
        "resume": {},
        "close": {}
      }
    }
  },
  "listSessions": {
    "sessions": [
      {
        "sessionId": "agent:main:acp-smoke",
        "cwd": "/path/to/workspace",
        "_meta": {
          "sessionKey": "agent:main:acp-smoke",
          "kind": "direct"
        }
      }
    ],
    "nextCursor": null
  },
  "notifications": ["session_info_update", "available_commands_update", "usage_update"],
  "gatewayLogTail": ["[gateway] ready", "[ws] ⇄ res ✓ sessions.list 305ms"]
}

​

Cómo utilizarlo

1. Asegúrese de que el Gateway esté en ejecución (local o remoto).
2. Configure el destino del Gateway (mediante la configuración o indicadores).
3. Configure el IDE para que ejecute openclaw acp mediante stdio.

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

openclaw acp --url wss://gateway-host:18789 --token <token>
# preferible para la seguridad del proceso local
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

​

Selección de agentes

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

​

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

1. Ejecute el Gateway y asegúrese de que el puente ACP pueda acceder a él.
2. Dirija acpx openclaw a openclaw acp.
3. Indique la clave de sesión de OpenClaw que debe usar el agente de programación.

# Solicitud única a la sesión ACP predeterminada de OpenClaw
acpx openclaw exec "Resume el estado de la sesión activa de OpenClaw."

# Sesión persistente con nombre para turnos posteriores
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
  "Pide a mi agente de trabajo de OpenClaw contexto reciente relevante para este repositorio."

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

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

​

Configuración del editor Zed

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

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

​

Asignación de sesiones

• --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 identificador de sesión para esa clave (misma clave, nueva transcripción).

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

​

Opciones

• --url <url>: URL WebSocket del Gateway (el valor predeterminado 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 predeterminada.
• --session-label <label>: etiqueta de sesión predeterminada que se resolverá.
• --require-existing: genera un error si la clave o etiqueta de sesión no existe.
• --reset-session: restablece la clave de sesión antes del primer uso.
• --no-prefix-cwd: no antepone el directorio de trabajo a los prompts.
• --provenance <off|meta|meta+receipt>: incluye metadatos de procedencia o recibos de ACP.
• --verbose, -v: registro detallado en stderr.

• --token y --password pueden ser visibles en las listas de procesos locales de algunos sistemas. Es preferible 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 utilizan otros clientes del Gateway:
  • modo local: entorno (OPENCLAW_GATEWAY_*) y después gateway.auth.*; recurre a gateway.remote.* solo cuando gateway.auth.* no está definido (un SecretRef local configurado pero no resuelto produce un error seguro en lugar de recurrir silenciosamente a otra opción)
  • modo remoto: gateway.remote.* con alternativa de entorno/configuración según las reglas de precedencia remota
  • --url permite sobrescrituras de forma segura y no reutiliza credenciales implícitas de configuración o entorno; pase --token/--password explícitos (o sus variantes de archivo)

​

Opciones de acp client

• --cwd <dir>: directorio de trabajo de la sesión ACP.
• --server <command>: comando del servidor ACP (valor predeterminado: openclaw).
• --server-args <args...>: argumentos adicionales que se pasan al servidor ACP.
• --server-verbose: habilita el registro detallado en el servidor ACP.
• --verbose, -v: registro detallado del cliente.
• openclaw acp client establece OPENCLAW_SHELL=acp-client en el proceso de puente iniciado, que puede utilizarse para reglas de shell/perfil específicas del contexto.

​

Contenido relacionado

• Referencia de la CLI
• Agentes ACP