Agent coordination

Agentes ACP — configuración

Para la descripción general, la guía operativa y los conceptos, consulta agentes ACP.

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

Usa esta página solo cuando estés configurando la ruta ACP/acpx. Para la configuración del runtime app-server nativo de Codex, usa arnés de Codex. Para claves de API de OpenAI o configuración del proveedor de modelos OAuth de Codex, usa OpenAI.

Codex tiene dos rutas de OpenClaw:

Ruta	Configuración/comando	Página de configuración
app-server nativo de Codex	`/codex ...`, `agentRuntime.id: "codex"`	arnés de Codex
Adaptador ACP explícito de Codex	`/acp spawn codex`, `runtime: "acp", agentId: "codex"`	Esta página

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

Compatibilidad con el arnés acpx (actual)

Alias actuales de arnés integrados en acpx:

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

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 todavía expone ACP como agent acp, sobrescribe 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 sin procesar es una función de la CLI de acpx (no la ruta normal de agentId de OpenClaw).

El control de modelos depende de las capacidades del adaptador. Las referencias de modelo ACP de Codex son normalizadas por OpenClaw antes del inicio. Otros arneses necesitan models de ACP más compatibilidad con session/set_model; si un arnés no expone ni 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

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

La configuración de vinculación de hilos es específica de cada adaptador de 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, verifica primero la marca de función del adaptador:

Discord: channels.discord.threadBindings.spawnSessions=true

Las vinculaciones de la conversación actual no requieren creación de hilos secundarios. Requieren un contexto de conversación activo y un adaptador de canal que exponga vinculaciones de conversación ACP.

Consulta Referencia de configuración.

Configuración del Plugin para el backend acpx

Las instalaciones empaquetadas usan el Plugin de runtime oficial @openclaw/acpx para ACP. Instálalo y actívalo antes de usar sesiones de arnés ACP:

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

Los checkouts de código fuente también pueden usar el Plugin del workspace local después de 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 de paquete explícita:

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

Instalación de workspace local durante el desarrollo:

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

Luego verifica el estado del backend:

/acp doctor

Configuración de comando y versión de acpx

De forma predeterminada, el Plugin acpx registra el backend ACP integrado sin generar un agente ACP durante el inicio del Gateway. Ejecuta /acp doctor para una prueba en vivo explícita. Configura OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=1 solo cuando necesites que el Gateway pruebe el agente configurado al inicio.

Sobrescribe el comando o la versión en la configuración del Plugin:

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

command acepta una ruta absoluta, una ruta relativa (resuelta desde el workspace de OpenClaw) o un nombre de comando.
expectedVersion: "any" desactiva la coincidencia estricta de versión.
Las rutas command personalizadas desactivan la instalación automática local del Plugin.

Consulta Plugins.

Instalación automática de dependencias

Cuando instalas OpenClaw globalmente con npm install -g openclaw, las dependencias de runtime de acpx (binarios específicos de la plataforma) se instalan automáticamente mediante un hook de postinstalación. Si la instalación automática falla, el gateway sigue iniciándose con normalidad e informa la dependencia faltante mediante openclaw acp doctor.

Puente MCP de herramientas de Plugin

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

Si quieres que agentes ACP como Codex o Claude Code llamen a herramientas de Plugins de OpenClaw instaladas, como recuperar/almacenar memoria, activa el puente dedicado:

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

Qué hace esto:

Inyecta un servidor MCP integrado llamado openclaw-plugin-tools en el arranque de sesión ACPX.
Expone herramientas de Plugins ya registradas por Plugins de OpenClaw instalados y activados.
Mantiene la función explícita y desactivada de forma predeterminada.

Notas de seguridad y confianza:

Esto amplía la superficie de herramientas del arnés ACP.
Los agentes ACP obtienen acceso solo a herramientas de Plugins ya activas en el gateway.
Trata esto como el mismo límite de confianza que permitir que esos Plugins se ejecuten en 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 adicional opcional, no un reemplazo de la configuración genérica de servidores MCP.

Puente MCP de herramientas de OpenClaw

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

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

Qué hace esto:

Inyecta un servidor MCP integrado llamado openclaw-tools en el arranque de sesión ACPX.
Expone herramientas integradas seleccionadas 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 de tiempo de espera de runtime

El Plugin acpx establece de forma predeterminada un tiempo de espera de 120 segundos para los turnos de runtime integrados. Esto da a arneses más lentos, como Gemini CLI, tiempo suficiente para completar el inicio y la inicialización de ACP. Sobrescríbelo si tu host necesita un límite de runtime diferente:

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

Reinicia el gateway después de cambiar este valor.

Configuración del agente de prueba de estado

Cuando /acp doctor o la prueba de inicio opcional comprueba el backend, el Plugin acpx incluido prueba un agente de arnés. Si acp.allowedAgents está configurado, el valor predeterminado es el primer agente permitido; de lo contrario, el valor predeterminado es codex. Si tu despliegue necesita un agente ACP diferente para comprobaciones de estado, configura el agente de prueba explícitamente:

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 TTY para aprobar o denegar solicitudes de permiso de escritura de archivos y ejecución de shell. El Plugin acpx proporciona dos claves de configuración que controlan cómo se gestionan los permisos:

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

`permissionMode`

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

Valor	Comportamiento
`approve-all`	Aprueba automáticamente todas las escrituras de archivos y comandos de shell.
`approve-reads`	Aprueba automáticamente solo las lecturas; las escrituras y la ejecución requieren solicitudes.
`deny-all`	Deniega todas las solicitudes de permiso.

`nonInteractivePermissions`

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

Valor	Comportamiento
`fail`	Aborta la sesión con `AcpRuntimeError`. (predeterminado)
`deny`	Deniega silenciosamente el permiso y continúa (degradación gradual).

Configuración

Configura mediante la configuración del Plugin:

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

Reinicia el gateway después de cambiar estos valores.

Relacionado

agentes ACP — descripción general, guía operativa, conceptos
Subagentes
Enrutamiento multiagente

# Compatibilidad con el arnés acpx (actual)

# Configuración requerida

# Configuración del Plugin para el backend acpx

# Configuración de comando y versión de acpx

# Instalación automática de dependencias

# Puente MCP de herramientas de Plugin

# Puente MCP de herramientas de OpenClaw

# Configuración de tiempo de espera de runtime

# Configuración del agente de prueba de estado

# Configuración de permisos

# permissionMode

# nonInteractivePermissions

# Configuración

# Relacionado