--- read_when: - Exécuter des harnais de codage via ACP - Configuration de sessions ACP liées à une conversation sur les canaux de messagerie - Liaison d’une conversation de canal de messagerie à une session ACP persistante - Dépannage du backend ACP, du câblage des Plugin ou de la livraison des complétions - Utiliser les commandes /acp depuis le chat sidebarTitle: ACP agents summary: Exécuter des harnais de codage externes (Claude Code, Cursor, Gemini CLI, Codex ACP explicite, OpenClaw ACP, OpenCode) via le backend ACP title: Agents ACP x-i18n: generated_at: "2026-05-11T20:57:19Z" model: gpt-5.5 provider: openai source_hash: f6f4beb509c00c965bc2b202648f1b6567d1f3a633f2f9926882adafc5144e06 source_path: tools/acp-agents.md workflow: 16 --- Les sessions [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) permettent à OpenClaw d’exécuter des harnais de codage externes (par exemple Pi, Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI et d’autres harnais ACPX pris en charge) via un plugin de backend ACP. Chaque lancement de session ACP est suivi comme une [tâche en arrière-plan](/fr/automation/tasks). **ACP est le chemin des harnais externes, pas le chemin Codex par défaut.** Le plugin natif de serveur d’application Codex possède les contrôles `/codex ...` et le runtime intégré `openai/gpt-*` par défaut pour les tours d’agent ; ACP possède les contrôles `/acp ...` et les sessions `sessions_spawn({ runtime: "acp" })`. Si vous voulez que Codex ou Claude Code se connecte comme client MCP externe directement aux conversations de canal OpenClaw existantes, utilisez [`openclaw mcp serve`](/fr/cli/mcp) au lieu d’ACP. ## Quelle page me faut-il ? | Vous voulez… | Utilisez ceci | Remarques | | ----------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Lier ou contrôler Codex dans la conversation actuelle | `/codex bind`, `/codex threads` | Chemin natif du serveur d’application Codex lorsque le plugin `codex` est activé ; inclut les réponses de chat liées, le transfert d’images, modèle/rapide/permissions, arrêt et contrôles de pilotage. ACP est une solution de repli explicite | | Exécuter Claude Code, Gemini CLI, Codex ACP explicite ou un autre harnais externe _via_ OpenClaw | Cette page | Sessions liées au chat, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, tâches en arrière-plan, contrôles de runtime | | Exposer une session Gateway OpenClaw _comme_ serveur ACP pour un éditeur ou un client | [`openclaw acp`](/fr/cli/acp) | Mode pont. L’IDE/client parle ACP à OpenClaw via stdio/WebSocket | | Réutiliser une CLI IA locale comme modèle de repli en texte seul | [Backends CLI](/fr/gateway/cli-backends) | Pas ACP. Aucun outil OpenClaw, aucun contrôle ACP, aucun runtime de harnais | ## Est-ce que cela fonctionne immédiatement ? Oui, après l’installation du plugin de runtime ACP officiel : ```bash openclaw plugins install @openclaw/acpx openclaw config set plugins.entries.acpx.enabled true ``` Les extractions de source peuvent utiliser le plugin d’espace de travail local `extensions/acpx` après `pnpm install`. Exécutez `/acp doctor` pour vérifier l’état de préparation. OpenClaw n’informe les agents du lancement ACP que lorsqu’ACP est **réellement utilisable** : ACP doit être activé, la distribution ne doit pas être désactivée, la session actuelle ne doit pas être bloquée par le sandbox, et un backend de runtime doit être chargé. Si ces conditions ne sont pas remplies, les Skills du plugin ACP et les instructions ACP `sessions_spawn` restent masquées afin que l’agent ne suggère pas un backend indisponible. - Si `plugins.allow` est défini, il s’agit d’un inventaire de plugins restrictif et il **doit** inclure `acpx` ; sinon le backend ACP installé est intentionnellement bloqué et `/acp doctor` signale l’entrée de liste d’autorisation manquante. - L’adaptateur Codex ACP est préparé avec le plugin `acpx` et lancé localement lorsque c’est possible. - Codex ACP s’exécute avec un `CODEX_HOME` isolé ; OpenClaw copie uniquement les entrées de projet de confiance depuis la configuration Codex de l’hôte et fait confiance à l’espace de travail actif, en laissant l’authentification, les notifications et les hooks dans la configuration de l’hôte. - D’autres adaptateurs de harnais cibles peuvent encore être récupérés à la demande avec `npx` la première fois que vous les utilisez. - L’authentification fournisseur doit toujours exister sur l’hôte pour ce harnais. - Si l’hôte n’a pas npm ou d’accès réseau, les récupérations d’adaptateur de première exécution échouent jusqu’à ce que les caches soient préchauffés ou que l’adaptateur soit installé autrement. ACP lance un véritable processus de harnais externe. OpenClaw possède le routage, l’état des tâches en arrière-plan, la livraison, les liaisons et la politique ; le harnais possède sa connexion fournisseur, son catalogue de modèles, son comportement de système de fichiers et ses outils natifs. Avant de mettre OpenClaw en cause, vérifiez que : - `/acp doctor` signale un backend activé et sain. - L’identifiant cible est autorisé par `acp.allowedAgents` lorsque cette liste d’autorisation est définie. - La commande du harnais peut démarrer sur l’hôte Gateway. - L’authentification fournisseur est présente pour ce harnais (`claude`, `codex`, `gemini`, `opencode`, `droid`, etc.). - Le modèle sélectionné existe pour ce harnais - les identifiants de modèle ne sont pas portables entre harnais. - Le `cwd` demandé existe et est accessible, ou omettez `cwd` et laissez le backend utiliser sa valeur par défaut. - Le mode de permissions correspond au travail. Les sessions non interactives ne peuvent pas cliquer sur les invites de permission natives, donc les exécutions de codage intensives en écriture/exécution nécessitent généralement un profil de permissions ACPX capable d’avancer sans interface. Les outils de plugin OpenClaw et les outils OpenClaw intégrés ne sont **pas** exposés aux harnais ACP par défaut. Activez les ponts MCP explicites dans [Agents ACP - configuration](/fr/tools/acp-agents-setup) uniquement lorsque le harnais doit appeler ces outils directement. ## Cibles de harnais prises en charge Avec le backend `acpx`, utilisez ces identifiants de harnais comme cibles `/acp spawn ` ou `sessions_spawn({ runtime: "acp", agentId: "" })` : | Identifiant de harnais | Backend typique | Remarques | | ---------- | ---------------------------------------------- | ----------------------------------------------------------------------------------- | | `claude` | Adaptateur Claude Code ACP | Nécessite l’authentification Claude Code sur l’hôte. | | `codex` | Adaptateur Codex ACP | Repli ACP explicite uniquement lorsque `/codex` natif est indisponible ou qu’ACP est demandé. | | `copilot` | Adaptateur GitHub Copilot ACP | Nécessite l’authentification CLI/runtime Copilot. | | `cursor` | Cursor CLI ACP (`cursor-agent acp`) | Remplacez la commande acpx si une installation locale expose un point d’entrée ACP différent. | | `droid` | Factory Droid CLI | Nécessite l’authentification Factory/Droid ou `FACTORY_API_KEY` dans l’environnement du harnais. | | `gemini` | Adaptateur Gemini CLI ACP | Nécessite l’authentification Gemini CLI ou la configuration d’une clé API. | | `iflow` | iFlow CLI | La disponibilité de l’adaptateur et le contrôle du modèle dépendent de la CLI installée. | | `kilocode` | Kilo Code CLI | La disponibilité de l’adaptateur et le contrôle du modèle dépendent de la CLI installée. | | `kimi` | Kimi/Moonshot CLI | Nécessite l’authentification Kimi/Moonshot sur l’hôte. | | `kiro` | Kiro CLI | La disponibilité de l’adaptateur et le contrôle du modèle dépendent de la CLI installée. | | `opencode` | Adaptateur OpenCode ACP | Nécessite l’authentification CLI/fournisseur OpenCode. | | `openclaw` | Pont Gateway OpenClaw via `openclaw acp` | Permet à un harnais compatible ACP de reparler à une session Gateway OpenClaw. | | `pi` | Runtime Pi/OpenClaw intégré | Utilisé pour les expérimentations de harnais natifs OpenClaw. | | `qwen` | Qwen Code / Qwen CLI | Nécessite une authentification compatible Qwen sur l’hôte. | Les alias d’agent acpx personnalisés peuvent être configurés dans acpx lui-même, mais la politique OpenClaw vérifie toujours `acp.allowedAgents` et tout mappage `agents.list[].runtime.acp.agent` avant la distribution. ## Runbook opérateur Flux `/acp` rapide depuis le chat : `/acp spawn claude --bind here`, `/acp spawn gemini --mode persistent --thread auto`, ou `/acp spawn codex --bind here` explicite. Continuez dans la conversation ou le fil lié (ou ciblez explicitement la clé de session). `/acp status` `/acp model `, `/acp permissions `, `/acp timeout `. Sans remplacer le contexte : `/acp steer tighten logging and continue`. `/acp cancel` (tour actuel) ou `/acp close` (session + liaisons). - Le lancement crée ou reprend une session de runtime ACP, enregistre les métadonnées ACP dans le magasin de sessions OpenClaw et peut créer une tâche en arrière-plan lorsque l’exécution appartient au parent. - Les sessions ACP appartenant au parent sont traitées comme du travail en arrière-plan même lorsque la session de runtime est persistante ; l’achèvement et la livraison inter-surfaces passent par le notificateur de tâche parent plutôt que de se comporter comme une session de chat normale destinée à l’utilisateur. - La maintenance des tâches ferme les sessions ACP ponctuelles appartenant au parent qui sont terminales ou orphelines. Les sessions ACP persistantes sont conservées tant qu’une liaison de conversation active reste en place ; les sessions persistantes obsolètes sans liaison active sont fermées afin qu’elles ne puissent pas être reprises silencieusement après la fin de la tâche propriétaire ou la disparition de son enregistrement de tâche. - Les messages de suivi liés vont directement à la session ACP jusqu’à ce que la liaison soit fermée, retirée du focus, réinitialisée ou expirée. - Les commandes Gateway restent locales. `/acp ...`, `/status` et `/unfocus` ne sont jamais envoyés comme texte d’invite normal à un harnais ACP lié. - `cancel` interrompt le tour actif lorsque le backend prend en charge l’annulation ; cela ne supprime ni la liaison ni les métadonnées de session. - `close` met fin à la session ACP du point de vue d’OpenClaw et supprime la liaison. Un harnais peut encore conserver son propre historique amont s’il prend en charge la reprise. - Le plugin acpx nettoie les arborescences de processus wrapper et adaptateur détenues par OpenClaw après `close`, et récupère les orphelins ACPX obsolètes détenus par OpenClaw au démarrage de Gateway. - Les workers de runtime inactifs peuvent être nettoyés après `acp.runtime.ttlMinutes` ; les métadonnées de session stockées restent disponibles pour `/acp sessions`. Déclencheurs en langage naturel qui doivent être routés vers le **plugin Codex natif** lorsqu’il est activé : - « Liez ce canal Discord à Codex. » - « Attachez ce chat au fil Codex ``. » - « Affichez les fils Codex, puis liez celui-ci. » La liaison de conversation Codex native est le chemin de contrôle de chat par défaut. Les outils dynamiques OpenClaw continuent de s’exécuter via OpenClaw, tandis que les outils natifs de Codex tels que shell/apply-patch s’exécutent dans Codex. Pour les événements d’outils natifs de Codex, OpenClaw injecte à chaque tour un relais de hook natif afin que les hooks de Plugin puissent bloquer `before_tool_call`, observer `after_tool_call`, et router les événements Codex `PermissionRequest` via les approbations OpenClaw. Les hooks Codex `Stop` sont relayés vers OpenClaw `before_agent_finalize`, où les plugins peuvent demander un passage de modèle supplémentaire avant que Codex finalise sa réponse. Le relais reste volontairement conservateur : il ne modifie pas les arguments des outils natifs de Codex et ne réécrit pas les enregistrements de fil Codex. Utilisez ACP explicite uniquement lorsque vous souhaitez le modèle runtime/session ACP. La frontière de prise en charge intégrée de Codex est documentée dans le [contrat de prise en charge du harnais Codex v1](/fr/plugins/codex-harness-runtime#v1-support-contract). - `openai-codex/*` - route de modèle OAuth/abonnement Codex héritée réparée par doctor. - `openai/*` - runtime intégré de serveur d’application Codex natif pour les tours d’agent OpenAI. - `/codex ...` - contrôle de conversation Codex natif. - `/acp ...` ou `runtime: "acp"` - contrôle ACP/acpx explicite. Déclencheurs qui doivent router vers le runtime ACP : - "Exécutez ceci comme une session Claude Code ACP ponctuelle et résumez le résultat." - "Utilisez Gemini CLI pour cette tâche dans un fil, puis gardez les suivis dans ce même fil." - "Exécutez Codex via ACP dans un fil en arrière-plan." OpenClaw choisit `runtime: "acp"`, résout le `agentId` du harnais, se lie à la conversation ou au fil actuel quand c’est pris en charge, et route les suivis vers cette session jusqu’à la fermeture/expiration. Codex ne suit ce chemin que lorsque ACP/acpx est explicite ou que le Plugin Codex natif n’est pas disponible pour l’opération demandée. Pour `sessions_spawn`, `runtime: "acp"` est annoncé uniquement quand ACP est activé, que le demandeur n’est pas en sandbox, et qu’un backend de runtime ACP est chargé. `acp.dispatch.enabled=false` suspend la distribution automatique des fils ACP, mais ne masque ni ne bloque les appels explicites `sessions_spawn({ runtime: "acp" })`. Il cible des identifiants de harnais ACP tels que `codex`, `claude`, `droid`, `gemini` ou `opencode`. Ne passez pas un identifiant d’agent de configuration OpenClaw normal provenant de `agents_list`, sauf si cette entrée est explicitement configurée avec `agents.list[].runtime.type="acp"` ; sinon, utilisez le runtime de sous-agent par défaut. Lorsqu’un agent OpenClaw est configuré avec `runtime.type="acp"`, OpenClaw utilise `runtime.acp.agent` comme identifiant de harnais sous-jacent. ## ACP contre sous-agents Utilisez ACP lorsque vous souhaitez un runtime de harnais externe. Utilisez le **serveur d’application Codex natif** pour la liaison/le contrôle de conversation Codex lorsque le Plugin `codex` est activé. Utilisez les **sous-agents** lorsque vous voulez des exécutions déléguées natives OpenClaw. | Domaine | Session ACP | Exécution de sous-agent | | ------------- | ------------------------------------- | ----------------------------------- | | Runtime | Plugin backend ACP (par exemple acpx) | Runtime de sous-agent natif OpenClaw | | Clé de session | `agent::acp:` | `agent::subagent:` | | Commandes principales | `/acp ...` | `/subagents ...` | | Outil de création | `sessions_spawn` avec `runtime:"acp"` | `sessions_spawn` (runtime par défaut) | Voir aussi [Sous-agents](/fr/tools/subagents). ## Comment ACP exécute Claude Code Pour Claude Code via ACP, la pile est : 1. Plan de contrôle de session ACP OpenClaw. 2. Plugin runtime officiel `@openclaw/acpx`. 3. Adaptateur ACP Claude. 4. Mécanisme runtime/session côté Claude. ACP Claude est une **session de harnais** avec contrôles ACP, reprise de session, suivi des tâches en arrière-plan, et liaison facultative de conversation/fil. Les backends CLI sont des runtimes de secours locaux séparés, en texte uniquement - voir [Backends CLI](/fr/gateway/cli-backends). Pour les opérateurs, la règle pratique est : - **Vous voulez `/acp spawn`, des sessions pouvant être liées, des contrôles de runtime ou un travail de harnais persistant ?** Utilisez ACP. - **Vous voulez un simple secours texte local via la CLI brute ?** Utilisez les backends CLI. ## Sessions liées ### Modèle mental - **Surface de chat** - l’endroit où les personnes continuent de parler (canal Discord, sujet Telegram, chat iMessage). - **Session ACP** - l’état durable du runtime Codex/Claude/Gemini vers lequel OpenClaw route. - **Fil/sujet enfant** - une surface de messagerie supplémentaire facultative créée uniquement par `--thread ...`. - **Espace de travail runtime** - l’emplacement du système de fichiers (`cwd`, checkout du dépôt, espace de travail backend) où le harnais s’exécute. Indépendant de la surface de chat. ### Liaisons de conversation actuelle `/acp spawn --bind here` épingle la conversation actuelle à la session ACP créée - pas de fil enfant, même surface de chat. OpenClaw continue de posséder le transport, l’authentification, la sécurité et la livraison. Les messages de suivi dans cette conversation sont routés vers la même session ; `/new` et `/reset` réinitialisent la session sur place ; `/acp close` supprime la liaison. Exemples : ```text /codex bind # liaison Codex native, route les futurs messages ici /codex model gpt-5.4 # ajuste le fil Codex natif lié /codex stop # contrôle le tour Codex natif actif /acp spawn codex --bind here # secours ACP explicite pour Codex /acp spawn codex --thread auto # peut créer un fil/sujet enfant et s’y lier /acp spawn codex --bind here --cwd /workspace/repo # même liaison de chat, Codex s’exécute dans /workspace/repo ``` - `--bind here` et `--thread ...` sont mutuellement exclusifs. - `--bind here` ne fonctionne que sur les canaux qui annoncent la liaison à la conversation actuelle ; OpenClaw renvoie sinon un message clair indiquant que ce n’est pas pris en charge. Les liaisons persistent après les redémarrages du Gateway. - Sur Discord, `spawnSessions` contrôle la création de fils enfants pour `--thread auto|here` - pas `--bind here`. - Si vous créez vers un autre agent ACP sans `--cwd`, OpenClaw hérite par défaut de l’espace de travail de **l’agent cible**. Les chemins hérités manquants (`ENOENT`/`ENOTDIR`) reviennent au défaut du backend ; les autres erreurs d’accès (par exemple `EACCES`) apparaissent comme des erreurs de création. - Les commandes de gestion du Gateway restent locales dans les conversations liées - les commandes `/acp ...` sont traitées par OpenClaw même lorsque le texte de suivi normal est routé vers la session ACP liée ; `/status` et `/unfocus` restent également locaux chaque fois que la gestion des commandes est activée pour cette surface. Lorsque les liaisons de fil sont activées pour un adaptateur de canal : - OpenClaw lie un fil à une session ACP cible. - Les messages de suivi dans ce fil sont routés vers la session ACP liée. - La sortie ACP est renvoyée dans le même fil. - Un retrait de focus/une fermeture/un archivage/un délai d’inactivité ou une expiration d’âge maximal supprime la liaison. - `/acp close`, `/acp cancel`, `/acp status`, `/status` et `/unfocus` sont des commandes Gateway, pas des prompts destinés au harnais ACP. Feature flags requis pour ACP lié à un fil : - `acp.enabled=true` - `acp.dispatch.enabled` est activé par défaut (définissez `false` pour suspendre la distribution automatique des fils ACP ; les appels explicites `sessions_spawn({ runtime: "acp" })` fonctionnent toujours). - Créations de sessions de fil d’adaptateur de canal activées (par défaut : `true`) : - Discord : `channels.discord.threadBindings.spawnSessions=true` - Telegram : `channels.telegram.threadBindings.spawnSessions=true` La prise en charge de la liaison de fil dépend de l’adaptateur. Si l’adaptateur de canal actif ne prend pas en charge les liaisons de fil, OpenClaw renvoie un message clair indiquant que ce n’est pas pris en charge ou pas disponible. - Tout adaptateur de canal qui expose une capacité de liaison de session/fil. - Prise en charge intégrée actuelle : fils/canaux **Discord**, sujets **Telegram** (sujets de forum dans les groupes/supergroupes et sujets de DM). - Les canaux de Plugin peuvent ajouter la prise en charge via la même interface de liaison. ## Liaisons de canal persistantes Pour les workflows non éphémères, configurez les liaisons ACP persistantes dans les entrées `bindings[]` de niveau supérieur. ### Modèle de liaison Marque une liaison de conversation ACP persistante. Identifie la conversation cible. Formes par canal : - **Canal/fil Discord :** `match.channel="discord"` + `match.peer.id=""` - **Canal/DM Slack :** `match.channel="slack"` + `match.peer.id="|#|userId|user:|slack:|<@userId>>"`. Préférez les ids Slack stables ; les liaisons de canal correspondent aussi aux réponses dans les fils de ce canal. - **Sujet de forum Telegram :** `match.channel="telegram"` + `match.peer.id=":topic:"` - **DM/groupe iMessage :** `match.channel="imessage"` + `match.peer.id=""`. Préférez `chat_id:*` pour les liaisons de groupe stables. L’identifiant de l’agent OpenClaw propriétaire. Remplacement ACP facultatif. Libellé facultatif destiné à l’opérateur. Répertoire de travail runtime facultatif. Remplacement de backend facultatif. ### Valeurs par défaut du runtime par agent Utilisez `agents.list[].runtime` pour définir les valeurs par défaut ACP une fois par agent : - `agents.list[].runtime.type="acp"` - `agents.list[].runtime.acp.agent` (identifiant de harnais, par exemple `codex` ou `claude`) - `agents.list[].runtime.acp.backend` - `agents.list[].runtime.acp.mode` - `agents.list[].runtime.acp.cwd` **Priorité des remplacements pour les sessions liées ACP :** 1. `bindings[].acp.*` 2. `agents.list[].runtime.acp.*` 3. Valeurs par défaut ACP globales (par exemple `acp.backend`) ### Exemple ```json5 { agents: { list: [ { id: "codex", runtime: { type: "acp", acp: { agent: "codex", backend: "acpx", mode: "persistent", cwd: "/workspace/openclaw", }, }, }, { id: "claude", runtime: { type: "acp", acp: { agent: "claude", backend: "acpx", mode: "persistent" }, }, }, ], }, bindings: [ { type: "acp", agentId: "codex", match: { channel: "discord", accountId: "default", peer: { kind: "channel", id: "222222222222222222" }, }, acp: { label: "codex-main" }, }, { type: "acp", agentId: "claude", match: { channel: "telegram", accountId: "default", peer: { kind: "group", id: "-1001234567890:topic:42" }, }, acp: { cwd: "/workspace/repo-b" }, }, { type: "route", agentId: "main", match: { channel: "discord", accountId: "default" }, }, { type: "route", agentId: "main", match: { channel: "telegram", accountId: "default" }, }, ], channels: { discord: { guilds: { "111111111111111111": { channels: { "222222222222222222": { requireMention: false }, }, }, }, }, telegram: { groups: { "-1001234567890": { topics: { "42": { requireMention: false } }, }, }, }, }, } ``` ### Comportement - OpenClaw s’assure que la session ACP configurée existe avant son utilisation. - Les messages dans ce canal ou ce sujet sont acheminés vers la session ACP configurée. - Dans les conversations liées, `/new` et `/reset` réinitialisent sur place la même clé de session ACP. - Les liaisons d’exécution temporaires (par exemple celles créées par les flux de focalisation sur un fil) s’appliquent toujours lorsqu’elles sont présentes. - Pour les lancements ACP inter-agents sans `cwd` explicite, OpenClaw hérite de l’espace de travail de l’agent cible depuis la configuration de l’agent. - Les chemins d’espace de travail hérités manquants se rabattent sur le cwd par défaut du backend ; les échecs d’accès non manquants remontent comme erreurs de lancement. ## Démarrer des sessions ACP Deux façons de démarrer une session ACP : Utilisez `runtime: "acp"` pour démarrer une session ACP depuis un tour d’agent ou un appel d’outil. ```json { "task": "Open the repo and summarize failing tests", "runtime": "acp", "agentId": "codex", "thread": true, "mode": "session" } ``` `runtime` vaut par défaut `subagent`, définissez donc explicitement `runtime: "acp"` pour les sessions ACP. Si `agentId` est omis, OpenClaw utilise `acp.defaultAgent` lorsqu’il est configuré. `mode: "session"` nécessite `thread: true` pour conserver une conversation liée persistante. Utilisez `/acp spawn` pour un contrôle explicite par l’opérateur depuis le chat. ```text /acp spawn codex --mode persistent --thread auto /acp spawn codex --mode oneshot --thread off /acp spawn codex --bind here /acp spawn codex --thread here ``` Indicateurs clés : - `--mode persistent|oneshot` - `--bind here|off` - `--thread auto|here|off` - `--cwd ` - `--label ` Consultez [Commandes slash](/fr/tools/slash-commands). ### Paramètres de `sessions_spawn` Invite initiale envoyée à la session ACP. Doit être `"acp"` pour les sessions ACP. Identifiant du harnais ACP cible. Se rabat sur `acp.defaultAgent` s’il est défini. Demande le flux de liaison de fil lorsqu’il est pris en charge. `"run"` est ponctuel ; `"session"` est persistant. Si `thread: true` et que `mode` est omis, OpenClaw peut utiliser par défaut un comportement persistant selon le chemin d’exécution. `mode: "session"` nécessite `thread: true`. Répertoire de travail d’exécution demandé (validé par la politique du backend/de l’exécution). S’il est omis, le lancement ACP hérite de l’espace de travail de l’agent cible lorsqu’il est configuré ; les chemins hérités manquants se rabattent sur les valeurs par défaut du backend, tandis que les véritables erreurs d’accès sont renvoyées. Libellé visible par l’opérateur utilisé dans le texte de session/bannière. Reprendre une session ACP existante au lieu d’en créer une nouvelle. L’agent rejoue son historique de conversation via `session/load`. Nécessite `runtime: "acp"`. `"parent"` diffuse les résumés de progression de l’exécution ACP initiale vers la session demandeuse sous forme d’événements système. Les réponses acceptées incluent `streamLogPath`, qui pointe vers un journal JSONL limité à la session (`.acp-stream.jsonl`) que vous pouvez suivre pour l’historique complet du relais. Interrompt le tour enfant ACP après N secondes. `0` conserve le tour sur le chemin sans délai d’expiration du Gateway. La même valeur est appliquée à l’exécution Gateway et à l’exécution ACP, afin que les harnais bloqués ou à quota épuisé n’occupent pas indéfiniment la voie de l’agent parent. Remplacement explicite du modèle pour la session enfant ACP. Les lancements ACP Codex normalisent les références OpenClaw Codex telles que `openai-codex/gpt-5.4` en configuration de démarrage ACP Codex avant `session/new` ; les formes slash telles que `openai-codex/gpt-5.4/high` définissent aussi l’effort de raisonnement ACP Codex. Les autres harnais doivent annoncer les `models` ACP et prendre en charge `session/set_model` ; sinon OpenClaw/acpx échoue clairement au lieu de se rabattre silencieusement sur la valeur par défaut de l’agent cible. Effort de réflexion/raisonnement explicite. Pour Codex ACP, `minimal` correspond à un effort faible, `low`/`medium`/`high`/`xhigh` correspondent directement, et `off` omet le remplacement de démarrage de l’effort de raisonnement. ## Modes de liaison et de fil de lancement | Mode | Comportement | | ------ | ------------------------------------------------------------------------------- | | `here` | Lie sur place la conversation active actuelle ; échoue si aucune n’est active. | | `off` | Ne crée pas de liaison avec la conversation actuelle. | Notes : - `--bind here` est le chemin opérateur le plus simple pour « adosser ce canal ou chat à Codex ». - `--bind here` ne crée pas de fil enfant. - `--bind here` est uniquement disponible sur les canaux qui exposent la prise en charge de la liaison avec la conversation actuelle. - `--bind` et `--thread` ne peuvent pas être combinés dans le même appel `/acp spawn`. | Mode | Comportement | | ------ | --------------------------------------------------------------------------------------------------------- | | `auto` | Dans un fil actif : lie ce fil. Hors d’un fil : crée/lie un fil enfant lorsque cela est pris en charge. | | `here` | Exige le fil actif actuel ; échoue si vous n’êtes pas dans un fil. | | `off` | Aucune liaison. La session démarre sans liaison. | Notes : - Sur les surfaces de liaison sans fil, le comportement par défaut est effectivement `off`. - Le lancement lié à un fil nécessite la prise en charge par la politique de canal : - Discord : `channels.discord.threadBindings.spawnSessions=true` - Telegram : `channels.telegram.threadBindings.spawnSessions=true` - Utilisez `--bind here` lorsque vous voulez épingler la conversation actuelle sans créer de fil enfant. ## Modèle de livraison Les sessions ACP peuvent être soit des espaces de travail interactifs, soit du travail en arrière-plan détenu par le parent. Le chemin de livraison dépend de cette forme. Les sessions interactives sont destinées à poursuivre la conversation sur une surface de chat visible : - `/acp spawn ... --bind here` lie la conversation actuelle à la session ACP. - `/acp spawn ... --thread ...` lie un fil/sujet de canal à la session ACP. - Les `bindings[].type="acp"` configurés de façon persistante acheminent les conversations correspondantes vers la même session ACP. Les messages de suivi dans la conversation liée sont acheminés directement vers la session ACP, et la sortie ACP est renvoyée à ce même canal/fil/sujet. Ce qu’OpenClaw envoie au harnais : - Les suivis liés normaux sont envoyés comme texte d’invite, avec des pièces jointes uniquement lorsque le harnais/backend les prend en charge. - Les commandes de gestion `/acp` et les commandes locales Gateway sont interceptées avant l’envoi ACP. - Les événements d’achèvement générés par l’exécution sont matérialisés par cible. Les agents OpenClaw reçoivent l’enveloppe de contexte d’exécution interne d’OpenClaw ; les harnais ACP externes reçoivent une invite simple avec le résultat enfant et l’instruction. L’enveloppe brute `<<>>` ne doit jamais être envoyée à des harnais externes ni conservée comme texte de transcription utilisateur ACP. - Les entrées de transcription ACP utilisent le texte déclencheur visible par l’utilisateur ou l’invite d’achèvement simple. Les métadonnées d’événement internes restent structurées dans OpenClaw lorsque c’est possible et ne sont pas traitées comme du contenu de chat rédigé par l’utilisateur. Les sessions ACP ponctuelles lancées par l’exécution d’un autre agent sont des enfants en arrière-plan, similaires aux sous-agents : - Le parent demande du travail avec `sessions_spawn({ runtime: "acp", mode: "run" })`. - L’enfant s’exécute dans sa propre session de harnais ACP. - Les tours enfants s’exécutent sur la même voie d’arrière-plan que celle utilisée par les lancements de sous-agents natifs, de sorte qu’un harnais ACP lent ne bloque pas le travail sans rapport de la session principale. - L’achèvement est rapporté via le chemin d’annonce d’achèvement de tâche. OpenClaw convertit les métadonnées d’achèvement internes en invite ACP simple avant de les envoyer à un harnais externe, de sorte que les harnais ne voient pas les marqueurs de contexte d’exécution propres à OpenClaw. - Le parent reformule le résultat enfant avec une voix d’assistant normale lorsqu’une réponse visible par l’utilisateur est utile. Ne traitez **pas** ce chemin comme un chat pair-à-pair entre parent et enfant. L’enfant dispose déjà d’un canal d’achèvement vers le parent. `sessions_send` peut cibler une autre session après le lancement. Pour les sessions paires normales, OpenClaw utilise un chemin de suivi agent-à-agent (A2A) après avoir injecté le message : - Attendre la réponse de la session cible. - Laisser éventuellement le demandeur et la cible échanger un nombre borné de tours de suivi. - Demander à la cible de produire un message d’annonce. - Livrer cette annonce au canal ou au fil visible. Ce chemin A2A est un recours pour les envois entre pairs lorsque l’expéditeur a besoin d’un suivi visible. Il reste activé lorsqu’une session sans rapport peut voir et envoyer un message à une cible ACP, par exemple avec des paramètres `tools.sessions.visibility` larges. OpenClaw ignore le suivi A2A uniquement lorsque le demandeur est le parent de son propre enfant ACP ponctuel détenu par le parent. Dans ce cas, exécuter A2A par-dessus l’achèvement de tâche peut réveiller le parent avec le résultat de l’enfant, renvoyer la réponse du parent dans l’enfant et créer une boucle d’écho parent/enfant. Le résultat `sessions_send` indique `delivery.status="skipped"` pour ce cas d’enfant détenu, car le chemin d’achèvement est déjà responsable du résultat. Utilisez `resumeSessionId` pour continuer une session ACP précédente au lieu de repartir de zéro. L’agent rejoue son historique de conversation via `session/load`, il reprend donc avec le contexte complet de ce qui précède. ```json { "task": "Continue where we left off - fix the remaining test failures", "runtime": "acp", "agentId": "codex", "resumeSessionId": "" } ``` Cas d’utilisation courants : - Transférer une session Codex de votre ordinateur portable à votre téléphone - demandez à votre agent de reprendre là où vous vous étiez arrêté. - Continuer une session de codage que vous aviez démarrée de façon interactive dans la CLI, désormais sans interface via votre agent. - Reprendre un travail interrompu par un redémarrage du gateway ou un délai d’inactivité. Notes : - `resumeSessionId` ne s’applique que lorsque `runtime: "acp"` ; l’exécution de sous-agent par défaut ignore ce champ propre à ACP. - `streamTo` ne s’applique que lorsque `runtime: "acp"` ; l’exécution de sous-agent par défaut ignore ce champ propre à ACP. - `resumeSessionId` est un identifiant de reprise ACP/harnais local à l’hôte, pas une clé de session de canal OpenClaw ; OpenClaw vérifie toujours la politique de lancement ACP et la politique de l’agent cible avant l’envoi, tandis que le backend ou le harnais ACP détient l’autorisation de charger cet identifiant amont. - `resumeSessionId` restaure l’historique de conversation ACP amont ; `thread` et `mode` s’appliquent toujours normalement à la nouvelle session OpenClaw que vous créez, donc `mode: "session"` nécessite toujours `thread: true`. - L’agent cible doit prendre en charge `session/load` (Codex et Claude Code le font). - Si l’identifiant de session est introuvable, le lancement échoue avec une erreur claire - pas de repli silencieux vers une nouvelle session. Après un déploiement de gateway, exécutez une vérification de bout en bout en direct plutôt que de faire confiance aux tests unitaires : 1. Vérifiez la version et le commit du Gateway déployé sur l'hôte cible. 2. Ouvrez une session de pont ACPX temporaire vers un agent actif. 3. Demandez à cet agent d'appeler `sessions_spawn` avec `runtime: "acp"`, `agentId: "codex"`, `mode: "run"` et la tâche `Reply with exactly LIVE-ACP-SPAWN-OK`. 4. Vérifiez `accepted=yes`, un vrai `childSessionKey` et l'absence d'erreur de validateur. 5. Nettoyez la session de pont temporaire. Gardez la barrière sur `mode: "run"` et ignorez `streamTo: "parent"` - les chemins `mode: "session"` liés au thread et de relais de flux sont des passes d'intégration distinctes et plus riches. ## Compatibilité du bac à sable Les sessions ACP s'exécutent actuellement sur le runtime de l'hôte, **pas** dans le bac à sable OpenClaw. **Limite de sécurité :** - Le harnais externe peut lire/écrire selon ses propres autorisations CLI et le `cwd` sélectionné. - La politique de bac à sable d'OpenClaw **n'encapsule pas** l'exécution du harnais ACP. - OpenClaw applique toujours les garde-fous de fonctionnalités ACP, les agents autorisés, la propriété des sessions, les liaisons de canaux et la politique de livraison du Gateway. - Utilisez `runtime: "subagent"` pour le travail natif OpenClaw appliqué par le bac à sable. Limitations actuelles : - Si la session demandeuse est en bac à sable, les lancements ACP sont bloqués pour `sessions_spawn({ runtime: "acp" })` comme pour `/acp spawn`. - `sessions_spawn` avec `runtime: "acp"` ne prend pas en charge `sandbox: "require"`. ## Résolution de la cible de session La plupart des actions `/acp` acceptent une cible de session facultative (`session-key`, `session-id` ou `session-label`). **Ordre de résolution :** 1. Argument de cible explicite (ou `--session` pour `/acp steer`) - essaie la clé - puis l'id de session au format UUID - puis le libellé 2. Liaison du thread actuel (si cette conversation/ce thread est lié à une session ACP). 3. Repli sur la session demandeuse actuelle. Les liaisons de conversation actuelle et les liaisons de thread participent toutes deux à l'étape 2. Si aucune cible n'est résolue, OpenClaw renvoie une erreur claire (`Unable to resolve session target: ...`). ## Contrôles ACP | Commande | Ce qu'elle fait | Exemple | | -------------------- | ------------------------------------------------------- | ------------------------------------------------------------- | | `/acp spawn` | Créer une session ACP ; liaison actuelle ou liaison de thread facultative. | `/acp spawn codex --bind here --cwd /repo` | | `/acp cancel` | Annuler le tour en cours pour la session cible. | `/acp cancel agent:codex:acp:` | | `/acp steer` | Envoyer une instruction de pilotage à la session en cours d'exécution. | `/acp steer --session support inbox prioritize failing tests` | | `/acp close` | Fermer la session et délier les cibles de thread. | `/acp close` | | `/acp status` | Afficher le backend, le mode, l'état, les options de runtime et les capacités. | `/acp status` | | `/acp set-mode` | Définir le mode de runtime pour la session cible. | `/acp set-mode plan` | | `/acp set` | Écrire une option de configuration de runtime générique. | `/acp set model openai/gpt-5.4` | | `/acp cwd` | Définir la substitution du répertoire de travail du runtime. | `/acp cwd /Users/user/Projects/repo` | | `/acp permissions` | Définir le profil de politique d'approbation. | `/acp permissions strict` | | `/acp timeout` | Définir le délai d'expiration du runtime (secondes). | `/acp timeout 120` | | `/acp model` | Définir la substitution du modèle de runtime. | `/acp model anthropic/claude-opus-4-6` | | `/acp reset-options` | Supprimer les substitutions d'options de runtime de la session. | `/acp reset-options` | | `/acp sessions` | Lister les sessions ACP récentes depuis le stockage. | `/acp sessions` | | `/acp doctor` | Santé du backend, capacités, corrections actionnables. | `/acp doctor` | | `/acp install` | Afficher des étapes déterministes d'installation et d'activation. | `/acp install` | `/acp status` affiche les options de runtime effectives ainsi que les identifiants de session au niveau du runtime et du backend. Les erreurs de contrôle non pris en charge apparaissent clairement lorsqu'un backend ne dispose pas d'une capacité. `/acp sessions` lit le stockage pour la session actuellement liée ou demandeuse ; les jetons de cible (`session-key`, `session-id` ou `session-label`) sont résolus via la découverte de sessions du Gateway, y compris les racines `session.store` personnalisées par agent. ### Mappage des options de runtime `/acp` dispose de commandes pratiques et d'un setter générique. Opérations équivalentes : | Commande | Correspond à | Notes | | ---------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/acp model ` | clé de configuration de runtime `model` | Pour Codex ACP, OpenClaw normalise `openai-codex/` vers l'id de modèle de l'adaptateur et mappe les suffixes de raisonnement avec barre oblique, comme `openai-codex/gpt-5.4/high`, vers `reasoning_effort`. | | `/acp set thinking ` | option canonique `thinking` | OpenClaw envoie l'équivalent annoncé par le backend lorsqu'il est présent, en préférant `thinking`, puis `effort`, `reasoning_effort` ou `thought_level`. Pour Codex ACP, l'adaptateur mappe les valeurs vers `reasoning_effort`. | | `/acp permissions ` | option canonique `permissionProfile` | OpenClaw envoie l'équivalent annoncé par le backend lorsqu'il est présent, comme `approval_policy`, `permission_profile`, `permissions` ou `permission_mode`. | | `/acp timeout ` | option canonique `timeoutSeconds` | OpenClaw envoie l'équivalent annoncé par le backend lorsqu'il est présent, comme `timeout` ou `timeout_seconds`. | | `/acp cwd ` | substitution du cwd du runtime | Mise à jour directe. | | `/acp set ` | générique | `key=cwd` utilise le chemin de substitution du cwd. | | `/acp reset-options` | efface toutes les substitutions de runtime | - | ## Harnais acpx, configuration de Plugin et autorisations Pour la configuration du harnais acpx (alias Claude Code / Codex / Gemini CLI), les ponts MCP plugin-tools et OpenClaw-tools, ainsi que les modes d'autorisation ACP, consultez [Agents ACP - configuration](/fr/tools/acp-agents-setup). ## Dépannage | Symptôme | Cause probable | Correction | | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ACP runtime backend is not configured` | Plugin backend manquant, désactivé ou bloqué par `plugins.allow`. | Installez et activez le Plugin backend, incluez `acpx` dans `plugins.allow` lorsque cette liste d’autorisation est définie, puis exécutez `/acp doctor`. | | `ACP is disabled by policy (acp.enabled=false)` | ACP désactivé globalement. | Définissez `acp.enabled=true`. | | `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Répartition automatique depuis les messages de fil normaux désactivée. | Définissez `acp.dispatch.enabled=true` pour reprendre le routage automatique des fils ; les appels explicites `sessions_spawn({ runtime: "acp" })` fonctionnent toujours. | | `ACP agent "" is not allowed by policy` | Agent absent de la liste d’autorisation. | Utilisez un `agentId` autorisé ou mettez à jour `acp.allowedAgents`. | | `/acp doctor` reports backend not ready right after startup | Plugin backend manquant, désactivé, bloqué par une politique d’autorisation/refus, ou son exécutable configuré est indisponible. | Installez/activez le Plugin backend, relancez `/acp doctor` et inspectez l’installation du backend ou l’erreur de politique s’il reste défaillant. | | Harness command not found | La CLI de l’adaptateur n’est pas installée, le Plugin externe est manquant, ou la récupération initiale `npx` a échoué pour un adaptateur non Codex. | Exécutez `/acp doctor`, installez/préchargez l’adaptateur sur l’hôte Gateway, ou configurez explicitement la commande de l’agent acpx. | | Model-not-found from the harness | L’id de modèle est valide pour un autre fournisseur/harnais mais pas pour cette cible ACP. | Utilisez un modèle répertorié par ce harnais, configurez le modèle dans le harnais, ou omettez la surcharge. | | Vendor auth error from the harness | OpenClaw est sain, mais la CLI/le fournisseur cible n’est pas connecté. | Connectez-vous ou fournissez la clé fournisseur requise dans l’environnement de l’hôte Gateway. | | `Unable to resolve session target: ...` | Jeton de clé/id/libellé incorrect. | Exécutez `/acp sessions`, copiez la clé/le libellé exact, puis réessayez. | | `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` utilisé sans conversation active pouvant être liée. | Accédez au chat/canal cible et réessayez, ou utilisez un lancement non lié. | | `Conversation bindings are unavailable for .` | L’adaptateur ne dispose pas de la capacité de liaison ACP à la conversation courante. | Utilisez `/acp spawn ... --thread ...` lorsque c’est pris en charge, configurez `bindings[]` au niveau supérieur, ou accédez à un canal pris en charge. | | `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` utilisé hors d’un contexte de fil. | Accédez au fil cible ou utilisez `--thread auto`/`off`. | | `Only can rebind this channel/conversation/thread.` | Un autre utilisateur possède la cible de liaison active. | Reliez en tant que propriétaire ou utilisez une autre conversation ou un autre fil. | | `Thread bindings are unavailable for .` | L’adaptateur ne dispose pas de la capacité de liaison aux fils. | Utilisez `--thread off` ou accédez à un adaptateur/canal pris en charge. | | `Sandboxed sessions cannot spawn ACP sessions ...` | Le runtime ACP est côté hôte ; la session demandeuse est en bac à sable. | Utilisez `runtime="subagent"` depuis les sessions en bac à sable, ou lancez ACP depuis une session non mise en bac à sable. | | `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | `sandbox="require"` demandé pour le runtime ACP. | Utilisez `runtime="subagent"` pour une mise en bac à sable requise, ou utilisez ACP avec `sandbox="inherit"` depuis une session non mise en bac à sable. | | `Cannot apply --model ... did not advertise model support` | Le harnais cible n’expose pas le changement de modèle ACP générique. | Utilisez un harnais qui annonce ACP `models`/`session/set_model`, utilisez les références de modèle Codex ACP, ou configurez le modèle directement dans le harnais s’il dispose de son propre indicateur de démarrage. | | Missing ACP metadata for bound session | Métadonnées de session ACP obsolètes/supprimées. | Recréez avec `/acp spawn`, puis reliez à nouveau/concentrez le fil. | | `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` bloque les écritures/l’exécution dans la session ACP non interactive. | Définissez `plugins.entries.acpx.config.permissionMode` sur `approve-all` et redémarrez le Gateway. Consultez [Configuration des autorisations](/fr/tools/acp-agents-setup#permission-configuration). | | ACP session fails early with little output | Les invites d’autorisation sont bloquées par `permissionMode`/`nonInteractivePermissions`. | Vérifiez les journaux du Gateway pour `AcpRuntimeError`. Pour les autorisations complètes, définissez `permissionMode=approve-all` ; pour une dégradation progressive, définissez `nonInteractivePermissions=deny`. | | ACP session stalls indefinitely after completing work | Le processus du harnais s’est terminé, mais la session ACP n’a pas signalé l’achèvement. | Mettez OpenClaw à jour ; le nettoyage acpx actuel récolte les processus wrapper et adaptateur obsolètes appartenant à OpenClaw à la fermeture et au démarrage du Gateway. | | Harness sees `<<>>` | L’enveloppe d’événement interne a fui au-delà de la frontière ACP. | Mettez OpenClaw à jour et relancez le flux de finalisation ; les harnais externes ne doivent recevoir que des invites de finalisation simples. | ## Connexe - [Agents ACP - configuration](/fr/tools/acp-agents-setup) - [Envoi à l’agent](/fr/tools/agent-send) - [Backends CLI](/fr/gateway/cli-backends) - [Harnais Codex](/fr/plugins/codex-harness) - [Runtime du harnais Codex](/fr/plugins/codex-harness-runtime) - [Outils de bac à sable multi-agent](/fr/tools/multi-agent-sandbox-tools) - [`openclaw acp` (mode pont)](/fr/cli/acp) - [Sous-agents](/fr/tools/subagents)