Agents ACP

Les sessions Agent Client Protocol (ACP) 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.

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 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`	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	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 :

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.

Pièges de la première exécution

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.

Prérequis de runtime

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 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 <id> ou sessions_spawn({ runtime: "acp", agentId: "<id>" }) :

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 :

Lancer

/acp spawn claude --bind here, /acp spawn gemini --mode persistent --thread auto, ou /acp spawn codex --bind here explicite.

Travailler

Continuez dans la conversation ou le fil lié (ou ciblez explicitement la clé de session).

Vérifier l’état

/acp status

Ajuster

/acp model <provider/model>, /acp permissions <profile>, /acp timeout <seconds>.

Piloter

Sans remplacer le contexte : /acp steer tighten logging and continue.

Arrêter

/acp cancel (tour actuel) ou /acp close (session + liaisons).

Détails du cycle de vie

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.

Règles de routage Codex natif

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 <id>. »
« 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.

Aide-mémoire de sélection de modèle / fournisseur / runtime

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 en langage naturel pour le routage ACP

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:<agentId>:acp:<uuid>`	`agent:<agentId>:subagent:<uuid>`
Commandes principales	`/acp ...`	`/subagents ...`
Outil de création	`sessions_spawn` avec `runtime:"acp"`	`sessions_spawn` (runtime par défaut)

Voir aussi Sous-agents.

Comment ACP exécute Claude Code

Pour Claude Code via ACP, la pile est :

Plan de contrôle de session ACP OpenClaw.
Plugin runtime officiel @openclaw/acpx.
Adaptateur ACP Claude.
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. 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 <harness> --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 :

/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

Règles de liaison et exclusivité

--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.

Sessions liées à un fil

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.

Canaux prenant en charge les fils

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

bindings[].type

"acp"

Marque une liaison de conversation ACP persistante.

bindings[].match

object

Identifie la conversation cible. Formes par canal :

Canal/fil Discord : match.channel="discord" + match.peer.id="<channelOrThreadId>"
Canal/DM Slack : match.channel="slack" + match.peer.id="<channelId|channel:<channelId>|#<channelId>|userId|user:<userId>|slack:<userId>|<@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="<chatId>:topic:<topicId>"
DM/groupe iMessage : match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>". Préférez chat_id:* pour les liaisons de groupe stables.

bindings[].agentId

string

L’identifiant de l’agent OpenClaw propriétaire.

bindings[].acp.mode

"persistent" | "oneshot"

Remplacement ACP facultatif.

bindings[].acp.label

string

Libellé facultatif destiné à l’opérateur.

bindings[].acp.cwd

string

Répertoire de travail runtime facultatif.

bindings[].acp.backend

string

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 :

bindings[].acp.*
agents.list[].runtime.acp.*
Valeurs par défaut ACP globales (par exemple acp.backend)

Exemple

{
  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 :

Depuis sessions_spawn
Depuis la commande /acp

Utilisez runtime: "acp" pour démarrer une session ACP depuis un tour d’agent ou un appel d’outil.

{
  "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.

/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 <absolute-path>
--label <name>

Consultez Commandes slash.

Paramètres de `sessions_spawn`

task

string

requis

Invite initiale envoyée à la session ACP.

runtime

"acp"

requis

Doit être "acp" pour les sessions ACP.

agentId

string

Identifiant du harnais ACP cible. Se rabat sur acp.defaultAgent s’il est défini.

thread

boolean

défaut:"false"

Demande le flux de liaison de fil lorsqu’il est pris en charge.

mode

"run" | "session"

défaut:"run"

"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.

cwd

string

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.

label

string

Libellé visible par l’opérateur utilisé dans le texte de session/bannière.

resumeSessionId

string

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".

streamTo

"parent"

"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 (<sessionId>.acp-stream.jsonl) que vous pouvez suivre pour l’historique complet du relais.

runTimeoutSeconds

number

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.

model

string

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.

thinking

string

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

--bind here|off
--thread auto|here|off

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.

Sessions ACP interactives

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 <<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>> 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.

Sessions ACP ponctuelles détenues par le parent

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 et livraison A2A

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.

Reprendre une session existante

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.

{
  "task": "Continue where we left off - fix the remaining test failures",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

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.

Test smoke post-déploiement

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 :

Vérifiez la version et le commit du Gateway déployé sur l’hôte cible.
Ouvrez une session de pont ACPX temporaire vers un agent actif.
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.
Vérifiez accepted=yes, un vrai childSessionKey et l’absence d’erreur de validateur.
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 :

Argument de cible explicite (ou --session pour /acp steer)
- essaie la clé
- puis l’id de session au format UUID
- puis le libellé
Liaison du thread actuel (si cette conversation/ce thread est lié à une session ACP).
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:<uuid>`
`/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 <id>`	clé de configuration de runtime `model`	Pour Codex ACP, OpenClaw normalise `openai-codex/<model>` 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 <level>`	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 <profile>`	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 <seconds>`	option canonique `timeoutSeconds`	OpenClaw envoie l’équivalent annoncé par le backend lorsqu’il est présent, comme `timeout` ou `timeout_seconds`.
`/acp cwd <path>`	substitution du cwd du runtime	Mise à jour directe.
`/acp set <key> <value>`	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.

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 "<id>" 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 <channel>.`	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 <user-id> 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 <channel>.`	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.
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 `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>`	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.

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Quelle page me faut-il ?

Est-ce que cela fonctionne immédiatement ?

Cibles de harnais prises en charge

Runbook opérateur

ACP contre sous-agents

Comment ACP exécute Claude Code

Sessions liées

Modèle mental

Liaisons de conversation actuelle

Liaisons de canal persistantes

Modèle de liaison

Valeurs par défaut du runtime par agent

Exemple

Comportement

Démarrer des sessions ACP

Paramètres de `sessions_spawn`

Modes de liaison et de fil de lancement

Modèle de livraison

Compatibilité du bac à sable

Résolution de la cible de session

Contrôles ACP

Mappage des options de runtime

Harnais acpx, configuration de Plugin et autorisations

Dépannage

Connexe

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Documentation Index

​Quelle page me faut-il ?

​Est-ce que cela fonctionne immédiatement ?

​Cibles de harnais prises en charge

​Runbook opérateur

​ACP contre sous-agents

​Comment ACP exécute Claude Code

​Sessions liées

​Modèle mental

​Liaisons de conversation actuelle

​Liaisons de canal persistantes

​Modèle de liaison

​Valeurs par défaut du runtime par agent

​Exemple

​Comportement

​Démarrer des sessions ACP

​Paramètres de sessions_spawn

​Modes de liaison et de fil de lancement

​Modèle de livraison

​Compatibilité du bac à sable

​Résolution de la cible de session

​Contrôles ACP

​Mappage des options de runtime

​Harnais acpx, configuration de Plugin et autorisations

​Dépannage

​Connexe

Quelle page me faut-il ?

Est-ce que cela fonctionne immédiatement ?

Cibles de harnais prises en charge

Runbook opérateur

ACP contre sous-agents

Comment ACP exécute Claude Code

Sessions liées

Modèle mental

Liaisons de conversation actuelle

Liaisons de canal persistantes

Modèle de liaison

Valeurs par défaut du runtime par agent

Exemple

Comportement

Démarrer des sessions ACP

Paramètres de `sessions_spawn`

Modes de liaison et de fil de lancement

Modèle de livraison

Compatibilité du bac à sable

Résolution de la cible de session

Contrôles ACP

Mappage des options de runtime

Harnais acpx, configuration de Plugin et autorisations

Dépannage

Connexe