Agentes ACP: configuración

Para obtener una visión general, consultar el manual operativo y conocer los conceptos, consulta agentes ACP.

Esta página abarca la configuración del entorno acpx, la configuración de plugins para los puentes MCP y la configuración de permisos.

Usa esta página solo cuando configures la ruta ACP/acpx. Para configurar el entorno de ejecución nativo del servidor de aplicaciones de Codex, usa entorno de Codex. Para configurar claves de la API de OpenAI o el proveedor de modelos de Codex mediante OAuth, usa OpenAI.

Codex tiene dos rutas de OpenClaw:

Prefiere la ruta nativa, salvo que necesites explícitamente el comportamiento de ACP/acpx.

Compatibilidad actual del entorno acpx

Alias integrados del entorno acpx (procedentes de la dependencia fijada acpx):

factory-droid y factorydroid también se resuelven al adaptador integrado droid.

Cuando OpenClaw usa el backend acpx, prefiere estos valores para agentId, salvo que tu configuración de acpx defina alias de agente personalizados. Si tu instalación local de Cursor aún expone ACP como agent acp, sustituye el comando del agente cursor en tu configuración de acpx en lugar de cambiar el valor predeterminado integrado.

El uso directo de la CLI de acpx también puede dirigirse a adaptadores arbitrarios mediante --agent <command>, pero esa vía de escape directa es una función de la CLI de acpx, no la ruta normal de agentId de OpenClaw.

El control del modelo depende de las capacidades del adaptador. OpenClaw normaliza las referencias de modelos de Codex ACP antes del inicio. Los demás entornos necesitan la capacidad ACP models junto con compatibilidad con session/set_model; si un entorno no expone ni esa capacidad ACP ni su propio indicador de modelo durante el inicio, OpenClaw/acpx no puede imponer la selección de un modelo.

Configuración obligatoria

Configuración base de ACP en el núcleo:

{  acp: {    enabled: true,    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.    dispatch: { enabled: true },    backend: "acpx",    defaultAgent: "codex",    allowedAgents: [      "claude",      "codex",      "copilot",      "cursor",      "droid",      "gemini",      "iflow",      "kilocode",      "kimi",      "kiro",      "openclaw",      "opencode",      "qwen",    ],    maxConcurrentSessions: 8,    stream: {      // Defaults are coalesceIdleMs: 350, maxChunkChars: 1800; shown explicitly here.      coalesceIdleMs: 350,      maxChunkChars: 1800,    },    runtime: {      ttlMinutes: 120,    },  },}

La configuración de vinculación a hilos depende del adaptador de canal. Ejemplo para Discord:

{  session: {    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },  },  channels: {    discord: {      threadBindings: {        enabled: true,        // Default is already true; shown explicitly here.        spawnSessions: true,      },    },  },}

Si el inicio de ACP vinculado a un hilo no funciona, comprueba primero el indicador de función del adaptador:

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

Las vinculaciones a la conversación actual no requieren crear un hilo secundario. Requieren un contexto de conversación activo y un adaptador de canal que exponga vinculaciones de conversaciones ACP.

Consulta la referencia de configuración.

Configuración del plugin para el backend acpx

Las instalaciones empaquetadas usan el plugin oficial de entorno de ejecución @openclaw/acpx para ACP. Instálalo y actívalo antes de usar sesiones del entorno ACP:

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

Los repositorios de código fuente también pueden usar el plugin del espacio de trabajo local después de ejecutar pnpm install.

Empieza con:

/acp doctor

Si desactivaste acpx, lo denegaste mediante plugins.allow / plugins.deny o quieres volver al plugin empaquetado, usa la ruta explícita del paquete:

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

Instalación del espacio de trabajo local durante el desarrollo:

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

Después, comprueba el estado del backend:

/acp doctor

Comprobación de inicio del entorno de ejecución acpx

El plugin acpx integra directamente el entorno de ejecución ACP, sin un binario acpx independiente ni una versión que configurar. De forma predeterminada, registra el backend integrado durante el inicio del Gateway y espera a que termine una comprobación de inicio antes de emitir la señal ready del Gateway. Establece OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 o OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 solo para scripts o entornos que mantengan intencionadamente desactivada la comprobación de inicio. Ejecuta /acp doctor para realizar una comprobación explícita bajo demanda.

Sustituye el comando de un agente ACP individual mediante argumentos estructurados cuando una ruta o el valor de un indicador deba permanecer como un único token de argv:

{  "plugins": {    "entries": {      "acpx": {        "enabled": true,        "config": {          "agents": {            "claude": {              "command": "node",              "args": ["/path/to/custom adapter.mjs", "--verbose"]            }          }        }      }    }  }}

• agents.<id>.command es el ejecutable o la cadena de comando existente para ese agente ACP.
• agents.<id>.args es opcional. Cada elemento del arreglo se protege con comillas para el shell antes de que OpenClaw lo pase a través del registro actual de cadenas de comandos de acpx.

Consulta Plugins.

Descarga automática de adaptadores

acpx descarga automáticamente los adaptadores ACP —por ejemplo, los puentes ACP de Claude y Codex— mediante npx la primera vez que se usan. No necesitas instalar manualmente los paquetes de adaptadores y OpenClaw no requiere un paso posterior a la instalación independiente. Si falla la descarga o el inicio de un adaptador, /acp doctor informa del error.

Puente MCP de herramientas de plugins

De forma predeterminada, las sesiones ACPX no exponen al entorno ACP las herramientas registradas por los plugins de OpenClaw.

Si quieres que agentes ACP como Codex o Claude Code puedan invocar herramientas de plugins instalados de OpenClaw, como la recuperación o el almacenamiento de memoria, activa el puente específico:

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

Qué hace:

• Inyecta un servidor MCP integrado llamado openclaw-plugin-tools durante la inicialización de la sesión ACPX.
• Expone las herramientas de plugins ya registradas por los plugins de OpenClaw instalados y activados.
• Mantiene la función explícita y desactivada de forma predeterminada.

Notas de seguridad y confianza:

• Amplía la superficie de herramientas del entorno ACP.
• Los agentes ACP solo obtienen acceso a las herramientas de plugins que ya estén activas en el Gateway.
• Trátalo como el mismo límite de confianza que permitir que esos plugins se ejecuten dentro de OpenClaw.
• Revisa los plugins instalados antes de activarlo.

Los mcpServers personalizados siguen funcionando como antes. El puente integrado de herramientas de plugins es una comodidad opcional adicional, no un sustituto de la configuración genérica de servidores MCP.

Puente MCP de herramientas de OpenClaw

De forma predeterminada, las sesiones ACPX tampoco exponen mediante MCP las herramientas integradas de OpenClaw. Activa el puente independiente de herramientas del núcleo cuando un agente ACP necesite herramientas integradas específicas como cron:

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

Qué hace:

• Inyecta un servidor MCP integrado llamado openclaw-tools durante la inicialización de la sesión ACPX.
• Expone determinadas herramientas integradas de OpenClaw. El servidor inicial expone cron.
• Mantiene la exposición de herramientas del núcleo explícita y desactivada de forma predeterminada.

Configuración del tiempo de espera de las operaciones del entorno de ejecución

De forma predeterminada, el plugin acpx concede 120 segundos al inicio del entorno de ejecución integrado y a las operaciones de control. Esto permite que entornos más lentos, como Gemini CLI, dispongan de tiempo suficiente para completar el inicio y la inicialización de ACP. Sustituye este valor si tu host necesita un límite de operación diferente:

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

Los turnos del entorno de ejecución usan los tiempos de espera de ejecución de agentes de OpenClaw, incluido /acp timeout. sessions_spawn no acepta valores de tiempo de espera específicos por llamada; la ruta del operador es agents.defaults.subagents.runTimeoutSeconds. Reinicia el Gateway después de cambiar timeoutSeconds.

Configuración del agente para comprobaciones de estado

Cuando /acp doctor o la comprobación de inicio verifica el backend, el plugin acpx incluido comprueba un agente del entorno. Si se establece acp.allowedAgents, usa de forma predeterminada el primer agente permitido; de lo contrario, usa codex. Si tu implementación necesita un agente ACP diferente para las comprobaciones de estado, establece explícitamente el agente de comprobación:

openclaw config set plugins.entries.acpx.config.probeAgent claude

Reinicia el Gateway después de cambiar este valor.

Configuración de permisos

Las sesiones ACP se ejecutan de forma no interactiva: no hay una TTY para aprobar o denegar solicitudes de permisos de escritura de archivos y ejecución de comandos del shell. El plugin acpx proporciona dos claves de configuración que controlan cómo se gestionan los permisos:

Estos permisos del entorno ACPX son independientes de las aprobaciones de ejecución de OpenClaw y de los indicadores de omisión del proveedor del backend de la CLI, como --permission-mode bypassPermissions de Claude CLI. approve-all de ACPX es el interruptor de emergencia del entorno para las sesiones ACP.

Para consultar una comparación más amplia entre tools.exec.mode de OpenClaw, las aprobaciones de Codex Guardian y los permisos del entorno ACPX, consulta modos de permisos.

permissionMode

Controla qué operaciones puede realizar el agente del entorno sin solicitar confirmación.

nonInteractivePermissions

Controla qué sucede cuando se debería mostrar una solicitud de permiso, pero no hay ninguna TTY interactiva disponible (lo que siempre ocurre en las sesiones ACP).

Configuración

Establézcalo mediante la configuración del Plugin:

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

Reinicie el Gateway después de cambiar estos valores.

Temas relacionados

• Agentes ACP — descripción general, manual operativo y conceptos
• Subagentes
• Enrutamiento multiagente