Agentes ACP — configuración

Para obtener una descripción general, el manual del operador y los conceptos, consulte ACP agents.

Las secciones a continuación cubren la configuración del arnés acpx, la configuración del complemento para los puentes MCP y la configuración de permisos.

Utilice esta página únicamente cuando esté configurando la ruta ACP/acpx. Para la configuración del tiempo de ejecución del servidor de aplicaciones nativo de Codex, utilice Codex harness. Para las claves de API de OpenAI o la configuración del proveedor de modelos OAuth de Codex, utilice OpenAI.

Codex tiene dos rutas de OpenClaw:

Ruta	Configuración/comando	Página de configuración
Servidor de aplicaciones nativo de Codex	/codex ..., openai/gpt-* referencias de agente	Codex harness
Adaptador ACP de Codex explícito	/acp spawn codex, runtime: "acp", agentId: "codex"	Esta página

Prefiera la ruta nativa a menos que necesite explícitamente el comportamiento ACP/acpx.

compatibilidad con el arnés acpx (actual)

Alias de arnés integrados actuales de acpx:

• claude
• codex
• copilot
• cursor (CLI de Cursor: cursor-agent acp)
• droid
• gemini
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• qwen

Cuando OpenClaw usa el backend acpx, prefiera estos valores para agentId a menos que su configuración acpx defina alias de agente personalizados. Si su instalación local de Cursor todavía expone ACP como agent acp, anule el comando de agente cursor en su configuración acpx en lugar de cambiar el valor predeterminado integrado.

El uso directo de la CLI de acpx también puede apuntar a adaptadores arbitrarios a través de --agent <command>, pero esa escapatoria cruda es una característica de la CLI de acpx (no la ruta normal de agentId de OpenClaw).

El control del modelo depende de la capacidad del adaptador. Las referencias del modelo ACP de Codex se normalizan mediante OpenClaw antes del inicio. Otros arneses necesitan soporte de models de ACP más session/set_model; si un arnés no expone esa capacidad de ACP ni su propia marca de modelo de inicio, OpenClaw/acpx no puede forzar una selección de modelo.

Configuración requerida

Línea base básica de ACP:

{
  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", "openclaw", "qwen"],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

La configuración de vinculación de hilos es específica del adaptador del canal. Ejemplo para Discord:

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnSessions: true,
      },
    },
  },
}

Si la generación de ACP vinculada a hilos no funciona, verifique primero la marca de característica del adaptador:

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

Los enlaces de conversación actual no requieren la creación de subprocesos. Requieren un contexto de conversación activo y un adaptador de canal que exponga enlaces de conversación ACP.

Consulte Configuration Reference.

Configuración del complemento para el backend acpx

Las instalaciones empaquetadas utilizan el complemento de tiempo de ejecución @openclaw/acpx oficial para ACP. Instálelo y actívelo antes de usar las sesiones del arnés ACP:

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

Las descargas de código fuente también pueden usar el complemento del espacio de trabajo local después de pnpm install.

Comience con:

/acp doctor

Si deshabilitó acpx, lo denegó mediante plugins.allow / plugins.deny, o desea volver al complemento empaquetado, use la ruta del paquete explícita:

openclaw plugins install @openclaw/acpx
openclaw 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

Luego verifique el estado del backend:

/acp doctor

configuración del comando y la versión de acpx

De forma predeterminada, el complemento acpx registra el backend ACP integrado durante el inicio de Gateway y espera a que finalice la sonda de inicio del entorno de ejecución integrado antes de la señal de inicio de la puerta de enlace ready. Establezca OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 o OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 solo para scripts o entornos que mantengan intencionalmente la sonda de inicio deshabilitada. Ejecute /acp doctor para una sonda explícita bajo demanda.

Sobrescriba el comando o la versión en la configuración del complemento:

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

• command acepta una ruta absoluta, una ruta relativa (resuelta desde el espacio de trabajo de OpenClaw) o un nombre de comando.
• expectedVersion: "any" deshabilita la coincidencia estricta de versiones.
• Las rutas command personalizadas deshabilitan la instalación automática local del complemento.

Sobrescriba un comando de agente ACP individual con argumentos estructurados cuando una ruta o un valor de marca deban permanecer como un token 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 entrecomilla con shell antes de que OpenClaw lo pase a través del registro de cadenas de comandos acpx actual.

Consulte Plugins.

Instalación automática de dependencias

Cuando instala OpenClaw globalmente con npm install -g openclaw, las dependencias de tiempo de ejecución de acpx (binarios específicos de la plataforma) se instalan automáticamente mediante un gancho de postinstalación. Si la instalación automática falla, la puerta de enlace aún se inicia normalmente e informa la dependencia faltante a través de openclaw acp doctor.

Puente MCP de herramientas de complementos

De manera predeterminada, las sesiones de ACPX no exponen las herramientas registradas por complementos de OpenClaw al arnés de ACP.

Si desea que los agentes de ACP, como Codex o Claude Code, llamen a herramientas de complementos de OpenClaw instaladas, como la recuperación/almacenamiento de memoria, habilite el puente dedicado:

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

Lo que esto hace:

• Inyecta un servidor MCP integrado llamado openclaw-plugin-tools en el arranque de la sesión ACPX.
• Expone las herramientas de los plugins ya registrados por los plugins de OpenClaw instalados y habilitados.
• Mantiene la función explícita y desactivada por defecto.

Notas de seguridad y confianza:

• Esto amplía la superficie de herramientas del arnés ACP.
• Los agentes ACP solo obtienen acceso a las herramientas de los plugins ya activos en la puerta de enlace.
• Trate esto con el mismo límite de confianza que permitir que esos complementos se ejecuten en el propio OpenClaw.
• Revise los complementos instalados antes de habilitarlo.

Las mcpServers personalizadas siguen funcionando como antes. El puente plugin-tools integrado es una comodidad opcional adicional, no un reemplazo para la configuración genérica del servidor MCP.

Puente MCP de herramientas de OpenClaw

De forma predeterminada, las sesiones de ACPX también no exponen las herramientas integradas de OpenClaw a través de MCP. Habilite el puente core-tools separado cuando un agente ACP necesite herramientas integradas seleccionadas, como cron:

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

Lo que hace esto:

• Inyecta un servidor MCP integrado llamado openclaw-tools en el arranque de la sesión ACPX.
• Expone herramientas integradas seleccionadas de OpenClaw. El servidor inicial expone cron.
• Mantiene la exposición de herramientas básicas explícita y desactivada por defecto.

Configuración del tiempo de espera de la operación de tiempo de ejecución

El complemento acpx otorga a las operaciones de inicio y control del tiempo de ejecución integrado 120 segundos de forma predeterminada. Esto da tiempo suficiente a arneses más lentos, como Gemini CLI, para completar el inicio y la inicialización de ACP. Anúlelo si su host necesita un límite de operación diferente:

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

Los turnos de tiempo de ejecución utilizan tiempos de espera de agente/ejecución de OpenClaw, incluyendo /acp timeout. sessions_spawn no acepta anulaciones de tiempo de espera por llamada. Reinicie el gateway después de cambiar este valor.

Configuración del agente de sonda de estado

Cuando /acp doctor o la sonda de inicio verifica el backend, el complemento acpx incluido sondea un agente del arnés. Si se establece acp.allowedAgents, el valor predeterminado es el primer agente permitido; de lo contrario, el valor predeterminado es codex. Si su implementación necesita un agente ACP diferente para las comprobaciones de estado, establezca el agente de sonda explícitamente:

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

Reinicie la puerta de enlace después de cambiar este valor.

Configuración de permisos

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

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

Para la comparación más amplia entre OpenClaw tools.exec.mode, las aprobaciones de Codex Guardian y los permisos del arnés ACPX, consulte Permission modes.

permissionMode

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

Valor	Comportamiento
approve-all	Aprobar automáticamente todas las escrituras de archivos y comandos de shell.
approve-reads	Aprobar automáticamente solo las lecturas; las escrituras y ejecuciones requieren solicitudes.
deny-all	Denegar todas las solicitudes de permiso.

nonInteractivePermissions

Controla qué sucede cuando se mostraría una solicitud de permiso pero no hay un TTY interactivo disponible (lo cual siempre es el caso para las sesiones ACP).

Valor	Comportamiento
fail	Abortar la sesión con AcpRuntimeError. (predeterminado)
deny	Denegar silenciosamente el permiso y continuar (degradación elegante).

Configuración

Establecer a través de la configuración del complemento:

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

Reinicie el gateway después de cambiar estos valores.

Warning

OpenClaw por defecto utiliza permissionMode=approve-reads y nonInteractivePermissions=fail. En sesiones ACP no interactivas, cualquier escritura o ejecución que active una solicitud de permiso puede fallar con AcpRuntimeError: Permission prompt unavailable in non-interactive mode.

Si necesita restringir permisos, establezca nonInteractivePermissions en deny para que las sesiones se degraden elegantemente en lugar de bloquearse.

Relacionado

• ACP agents — descripción general, manual del operador, conceptos
• Sub-agentes
• Enrutamiento multiagente