Agents ACP — configuration

Pour la présentation, le guide opérationnel et les concepts, consultez Agents ACP.

Cette page couvre la configuration du banc d’exécution acpx, la configuration du Plugin pour les passerelles MCP et la configuration des autorisations.

Utilisez cette page uniquement lorsque vous configurez la voie ACP/acpx. Pour la configuration d’exécution native du serveur d’application Codex, utilisez le banc d’exécution Codex. Pour les clés d’API OpenAI ou la configuration du fournisseur de modèles avec OAuth Codex, utilisez OpenAI.

Codex dispose de deux voies OpenClaw :

Privilégiez la voie native, sauf si vous avez explicitement besoin du comportement ACP/acpx.

Prise en charge du banc d’exécution acpx (actuelle)

Alias de banc d’exécution acpx intégrés (issus de la dépendance acpx épinglée) :

factory-droid et factorydroid sont également résolus vers l’adaptateur droid intégré.

Lorsque OpenClaw utilise le backend acpx, privilégiez ces valeurs pour agentId, sauf si votre configuration acpx définit des alias d’agent personnalisés. Si votre installation locale de Cursor expose encore ACP sous la forme agent acp, remplacez la commande de l’agent cursor dans votre configuration acpx au lieu de modifier la valeur intégrée par défaut.

L’utilisation directe de la CLI acpx peut également cibler des adaptateurs arbitraires via --agent <command>, mais cette échappatoire brute est une fonctionnalité de la CLI acpx, et non la voie agentId normale d’OpenClaw.

Le contrôle du modèle dépend des capacités de l’adaptateur. Les références de modèles ACP Codex sont normalisées par OpenClaw avant le démarrage. Les autres bancs d’exécution nécessitent la capacité ACP models ainsi que la prise en charge de session/set_model ; si un banc d’exécution n’expose ni cette capacité ACP ni son propre indicateur de modèle au démarrage, OpenClaw/acpx ne peut pas imposer la sélection d’un modèle.

Configuration requise

Configuration ACP de base :

{  acp: {    enabled: true,    // Facultatif. La valeur par défaut est true ; définissez false pour suspendre l’envoi ACP tout en conservant les commandes /acp.    dispatch: { enabled: true },    backend: "acpx",    defaultAgent: "codex",    allowedAgents: [      "claude",      "codex",      "copilot",      "cursor",      "droid",      "gemini",      "iflow",      "kilocode",      "kimi",      "kiro",      "openclaw",      "opencode",      "qwen",    ],    maxConcurrentSessions: 8,    stream: {      // Les valeurs par défaut sont coalesceIdleMs: 350 et maxChunkChars: 1800 ; elles sont indiquées explicitement ici.      coalesceIdleMs: 350,      maxChunkChars: 1800,    },    runtime: {      ttlMinutes: 120,    },  },}

La configuration de liaison aux fils de discussion dépend de l’adaptateur de canal. Exemple pour Discord :

{  session: {    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },  },  channels: {    discord: {      threadBindings: {        enabled: true,        // La valeur par défaut est déjà true ; elle est indiquée explicitement ici.        spawnSessions: true,      },    },  },}

Si le lancement ACP lié à un fil de discussion ne fonctionne pas, vérifiez d’abord l’indicateur de fonctionnalité de l’adaptateur :

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

Les liaisons à la conversation actuelle ne nécessitent pas la création d’un fil enfant. Elles requièrent un contexte de conversation actif et un adaptateur de canal qui expose les liaisons de conversation ACP.

Consultez la référence de configuration.

Configuration du Plugin pour le backend acpx

Les installations empaquetées utilisent le Plugin d’exécution officiel @openclaw/acpx pour ACP. Installez-le et activez-le avant d’utiliser des sessions de banc d’exécution ACP :

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

Les extractions du code source peuvent également utiliser le Plugin de l’espace de travail local après pnpm install.

Commencez par :

/acp doctor

Si vous avez désactivé acpx, l’avez interdit via plugins.allow / plugins.deny, ou souhaitez revenir au Plugin empaqueté, utilisez le chemin de paquet explicite :

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

Installation de l’espace de travail local pendant le développement :

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

Vérifiez ensuite l’état du backend :

/acp doctor

Sonde de démarrage de l’exécution acpx

Le Plugin acpx intègre directement l’exécution ACP, sans binaire acpx distinct ni version à configurer. Par défaut, il enregistre le backend intégré au démarrage du Gateway et attend l’achèvement d’une sonde de démarrage avant le signal ready du Gateway. Définissez OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 ou OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 uniquement pour les scripts ou environnements qui maintiennent intentionnellement la sonde de démarrage désactivée. Exécutez /acp doctor pour lancer explicitement une sonde à la demande.

Remplacez la commande d’un agent ACP individuel par des arguments structurés lorsqu’un chemin ou une valeur d’indicateur doit rester un seul jeton argv :

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

• agents.<id>.command est l’exécutable ou la chaîne de commande existante de cet agent ACP.
• agents.<id>.args est facultatif. Chaque élément du tableau est protégé pour l’interpréteur de commandes avant qu’OpenClaw ne le transmette au registre actuel des chaînes de commande acpx.

Consultez Plugins.

Téléchargement automatique des adaptateurs

acpx télécharge automatiquement les adaptateurs ACP, par exemple les passerelles ACP Claude et Codex, via npx lors de la première utilisation. Vous n’avez pas besoin d’installer manuellement les paquets d’adaptateurs et OpenClaw lui-même ne comporte aucune étape post-installation distincte. Si le téléchargement ou le lancement d’un adaptateur échoue, /acp doctor signale l’échec.

Passerelle MCP des outils de Plugin

Par défaut, les sessions ACPX n’exposent pas au banc d’exécution ACP les outils enregistrés par les Plugins OpenClaw.

Si vous souhaitez que des agents ACP tels que Codex ou Claude Code appellent des outils de Plugins OpenClaw installés, comme le rappel ou le stockage en mémoire, activez la passerelle dédiée :

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

Effets de cette option :

• Injecte un serveur MCP intégré nommé openclaw-plugin-tools dans l’amorçage de la session ACPX.
• Expose les outils de Plugins déjà enregistrés par les Plugins OpenClaw installés et activés.
• Conserve une activation explicite de cette fonctionnalité, désactivée par défaut.

Remarques sur la sécurité et la confiance :

• Cela étend la surface d’outils du banc d’exécution ACP.
• Les agents ACP accèdent uniquement aux outils de Plugins déjà actifs dans le Gateway.
• Considérez cette option comme relevant de la même frontière de confiance que l’autorisation donnée à ces Plugins de s’exécuter dans OpenClaw lui-même.
• Vérifiez les Plugins installés avant de l’activer.

Les mcpServers personnalisés continuent de fonctionner comme auparavant. La passerelle intégrée des outils de Plugins est une commodité facultative supplémentaire, et non un remplacement de la configuration générique des serveurs MCP.

Passerelle MCP des outils OpenClaw

Par défaut, les sessions ACPX n’exposent pas non plus les outils OpenClaw intégrés via MCP. Activez la passerelle distincte des outils du cœur lorsqu’un agent ACP a besoin d’outils intégrés sélectionnés, tels que cron :

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

Effets de cette option :

• Injecte un serveur MCP intégré nommé openclaw-tools dans l’amorçage de la session ACPX.
• Expose certains outils OpenClaw intégrés. Le serveur initial expose cron.
• Conserve une exposition explicite des outils du cœur, désactivée par défaut.

Configuration du délai d’expiration des opérations d’exécution

Le Plugin acpx accorde par défaut 120 secondes au démarrage de l’exécution intégrée et aux opérations de contrôle. Cela laisse aux bancs d’exécution plus lents, tels que la CLI Gemini, suffisamment de temps pour terminer le démarrage et l’initialisation ACP. Modifiez cette valeur si votre hôte nécessite une autre limite d’opération :

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

Les tours d’exécution utilisent les délais d’expiration des agents/exécutions OpenClaw, y compris /acp timeout. sessions_spawn n’accepte pas de remplacement du délai d’expiration par appel ; la voie opérateur est agents.defaults.subagents.runTimeoutSeconds. Redémarrez le Gateway après avoir modifié timeoutSeconds.

Configuration de l’agent de sonde d’intégrité

Lorsque /acp doctor ou la sonde de démarrage vérifie le backend, le Plugin acpx fourni sonde un agent de banc d’exécution. Si acp.allowedAgents est défini, le premier agent autorisé est utilisé par défaut ; sinon, la valeur par défaut est codex. Si votre déploiement nécessite un autre agent ACP pour les contrôles d’intégrité, définissez explicitement l’agent de sonde :

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

Redémarrez le Gateway après avoir modifié cette valeur.

Configuration des autorisations

Les sessions ACP s’exécutent de manière non interactive : aucune TUI ne permet d’approuver ou de refuser les demandes d’autorisation d’écriture de fichiers et d’exécution de commandes shell. Le Plugin acpx fournit deux clés de configuration qui contrôlent la gestion des autorisations :

Ces autorisations du banc d’exécution ACPX sont distinctes des approbations d’exécution OpenClaw et des indicateurs de contournement propres aux fournisseurs du backend CLI, tels que --permission-mode bypassPermissions de la CLI Claude. approve-all d’ACPX est le mécanisme de dernier recours au niveau du banc d’exécution pour les sessions ACP.

Pour une comparaison plus générale entre tools.exec.mode d’OpenClaw, les approbations Codex Guardian et les autorisations du banc d’exécution ACPX, consultez Modes d’autorisation.

permissionMode

Contrôle les opérations que l’agent du banc d’exécution peut effectuer sans demander de confirmation.

nonInteractivePermissions

Détermine ce qui se passe lorsqu’une demande d’autorisation devrait être affichée, mais qu’aucun TTY interactif n’est disponible (ce qui est toujours le cas pour les sessions ACP).

Configuration

Définissez ces valeurs via la configuration du Plugin :

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

Redémarrez le Gateway après avoir modifié ces valeurs.

Voir aussi

• Agents ACP — vue d’ensemble, guide d’exploitation, concepts
• Sous-agents
• Routage multi-agent