Agents ACP

• Si plugins.allow est défini, il constitue un inventaire restrictif de Plugins et doit inclure acpx, faute de quoi le backend ACP installé est intentionnellement bloqué (/acp doctor signale l’entrée manquante dans la liste d’autorisation).
• L’adaptateur Codex ACP est fourni avec le Plugin acpx et se lance localement lorsque cela est possible.
• Codex ACP s’exécute avec un CODEX_HOME isolé. OpenClaw copie depuis la configuration Codex de l’hôte les entrées de confiance des projets approuvés ainsi que la configuration sûre de routage du modèle/fournisseur (model, model_provider, model_reasoning_effort, sandbox_mode et les champs sûrs de model_providers.<name>) ; l’authentification, les notifications et les hooks restent uniquement dans la configuration de l’hôte.
• D’autres adaptateurs d’environnements cibles peuvent être téléchargés à la demande avec npx lors de la première utilisation.
• L’authentification auprès du fournisseur doit déjà exister sur l’hôte pour cet environnement.
• Si l’hôte ne dispose ni de npm ni d’un accès réseau, les téléchargements d’adaptateurs lors de la première exécution échouent jusqu’à ce que les caches soient préchargés ou que l’adaptateur soit installé autrement.

ACP lance un véritable processus d’environnement externe. OpenClaw gère le routage, l’état des tâches en arrière-plan, la livraison, les liaisons et les règles ; l’environnement gère sa connexion au fournisseur, son catalogue de modèles, son comportement vis-à-vis du système de fichiers et ses outils natifs.

Avant de mettre OpenClaw en cause, vérifiez les points suivants :

• /acp doctor signale un backend activé et opérationnel.
• L’identifiant cible est autorisé par acp.allowedAgents lorsque cette liste d’autorisation est définie.
• La commande de l’environnement peut démarrer sur l’hôte du Gateway.
• L’authentification du fournisseur est disponible pour cet environnement (claude, codex, gemini, opencode, droid, etc.).
• Le modèle sélectionné existe pour cet environnement : les identifiants de modèles ne sont pas transférables d’un environnement à l’autre.
• Le cwd demandé existe et est accessible ; sinon, omettez cwd et laissez le backend utiliser sa valeur par défaut.
• Le mode d’autorisation correspond au travail demandé. Les sessions non interactives ne peuvent pas cliquer sur les invites d’autorisation natives ; les exécutions de codage nécessitant beaucoup d’écritures ou de commandes ont donc généralement besoin d’un profil d’autorisation ACPX capable de fonctionner sans interface.

• Le lancement crée ou reprend une session d’exécution ACP, enregistre les métadonnées ACP dans le stockage de sessions OpenClaw et peut créer une tâche en arrière-plan lorsque l’exécution appartient à la tâche parente.
• Les sessions ACP appartenant à une tâche parente sont traitées comme du travail en arrière-plan, même lorsque la session d’exécution est persistante ; l’achèvement et la livraison entre différentes surfaces passent par le mécanisme de notification de la tâche parente plutôt que de se comporter comme une session de discussion normale destinée à l’utilisateur.
• La maintenance des tâches ferme les sessions ACP ponctuelles terminales ou orphelines appartenant à une tâche parente. Les sessions ACP persistantes sont conservées tant qu’une liaison active avec une conversation demeure ; les sessions persistantes obsolètes sans liaison active sont fermées afin qu’elles ne puissent pas être reprises silencieusement une fois la tâche propriétaire terminée ou son enregistrement supprimé.
• Les messages de suivi liés vont directement à la session ACP jusqu’à ce que la liaison soit fermée, désactivée, réinitialisée ou expirée.
• Les commandes du Gateway restent locales. /acp ..., /status et /unfocus ne sont jamais envoyées comme texte d’invite normal à un environnement ACP lié.
• cancel interrompt le tour actif lorsque le backend prend en charge l’annulation ; il ne supprime ni la liaison ni les métadonnées de session.
• close termine la session ACP du point de vue d’OpenClaw et supprime la liaison. Un environnement peut néanmoins conserver son propre historique en amont s’il prend en charge la reprise.
• Le Plugin acpx nettoie les arborescences de processus d’encapsulation et d’adaptation appartenant à OpenClaw après close, et récupère les processus orphelins ACPX appartenant à OpenClaw lors du démarrage du Gateway.
• Les processus d’exécution inactifs peuvent être nettoyés après acp.runtime.ttlMinutes ; les métadonnées de session enregistrées restent disponibles pour /acp sessions.

Déclencheurs en langage naturel qui doivent être acheminés vers le Plugin Codex natif lorsqu’il est activé :

• « Lier ce canal Discord à Codex. »
• « Associer cette discussion au fil Codex <id>. »
• « Afficher les fils Codex, puis lier celui-ci. »

La liaison native des conversations Codex est le mécanisme par défaut de contrôle des conversations. Les outils dynamiques d’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 hooks natifs afin que les hooks des plugins puissent bloquer before_tool_call, observer after_tool_call et acheminer les événements PermissionRequest de Codex via les approbations d’OpenClaw. Les hooks Stop de Codex sont relayés vers before_agent_finalize d’OpenClaw, où les plugins peuvent demander un passage supplémentaire du modèle avant que Codex ne finalise sa réponse. Le relais reste volontairement prudent : il ne modifie pas les arguments des outils natifs de Codex et ne réécrit pas les enregistrements de fils Codex. Utilisez explicitement ACP uniquement lorsque vous souhaitez le modèle d’exécution et de session ACP. Le périmètre de prise en charge de Codex intégré est documenté dans le contrat de prise en charge v1 du harnais Codex.

• anciennes références de modèles Codex - route historique des modèles Codex avec OAuth/abonnement, réparée par doctor.
• openai/* - moteur d’exécution intégré du serveur d’application natif Codex pour les tours d’agent OpenAI.
• /codex ... - contrôle natif des conversations Codex.
• /acp ... ou runtime: "acp" - contrôle explicite ACP/acpx.

Déclencheurs devant acheminer vers le moteur d’exécution ACP :

• « Exécutez ceci sous forme de session ACP Claude Code ponctuelle et résumez le résultat. »
• « Utilisez Gemini CLI pour cette tâche dans un fil, puis conservez 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 l’agentId du harnais, se lie à la conversation ou au fil actuel lorsque cela est pris en charge, puis achemine les suivis vers cette session jusqu’à sa fermeture ou son expiration. Codex ne suit ce chemin que lorsqu’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" n’est proposé que lorsqu’ACP est activé, que le demandeur n’est pas placé dans un bac à sable et qu’un moteur d’exécution ACP est chargé. acp.dispatch.enabled=false suspend l’acheminement 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 transmettez pas un identifiant d’agent de configuration OpenClaw ordinaire provenant de agents_list, sauf si cette entrée est explicitement configurée avec agents.list[].runtime.type="acp" ; sinon, utilisez le moteur d’exécution par défaut des sous-agents. Lorsqu’un agent OpenClaw est configuré avec runtime.type="acp", OpenClaw utilise runtime.acp.agent comme identifiant de harnais sous-jacent.

• --bind here et --thread ... s’excluent mutuellement.
• --bind here fonctionne uniquement sur les canaux qui annoncent la prise en charge de la liaison à la conversation actuelle ; sinon, OpenClaw renvoie un message clair indiquant que cette fonctionnalité n’est pas prise 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, mais pas pour --bind here.
• Si vous lancez une session 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) entraînent un retour au moteur par défaut ; les autres erreurs d’accès (par exemple EACCES) sont signalées comme des erreurs de lancement.
• 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 ordinaire est acheminé vers la session ACP liée ; /status et /unfocus restent également locales chaque fois que le traitement des commandes est activé pour cette surface.

Lorsque les liaisons de fils sont activées pour un adaptateur de canal :

• OpenClaw lie un fil à une session ACP cible.
• Les messages de suivi de ce fil sont acheminés vers la session ACP liée.
• La sortie ACP est renvoyée vers le même fil.
• La désactivation de la focalisation, la fermeture, l’archivage, l’expiration pour inactivité ou l’expiration liée à l’âge maximal supprime la liaison.
• /acp close, /acp cancel, /acp status, /status et /unfocus sont des commandes du Gateway, et non des invites destinées au harnais ACP.

Indicateurs de fonctionnalité requis pour ACP lié à un fil :

• acp.enabled=true
• acp.dispatch.enabled est activé par défaut (définissez-le sur false pour suspendre l’acheminement automatique des fils ACP ; les appels explicites sessions_spawn({ runtime: "acp" }) continuent de fonctionner).
• Lancement de sessions de fil activé pour l’adaptateur de canal (valeur par défaut : true) :
  • Discord : channels.discord.threadBindings.spawnSessions=true
  • Telegram : channels.telegram.threadBindings.spawnSessions=true

La prise en charge de la liaison de fils dépend de l’adaptateur. Si l’adaptateur de canal actif ne prend pas en charge les liaisons de fils, OpenClaw renvoie un message clair indiquant que cette fonctionnalité n’est pas prise en charge ou n’est pas disponible.

• Tout adaptateur de canal exposant une capacité de liaison de session ou de fil.
• Prise en charge intégrée actuelle : fils/canaux Discord, sujets Telegram (sujets de forum dans les groupes/supergroupes et sujets de messages privés).
• Les canaux de plugins peuvent ajouter cette prise en charge via la même interface de liaison.

Les sessions interactives sont conçues pour 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 ou un sujet du canal à la session ACP.
• Les bindings[].type="acp" persistantes configurées acheminent les conversations correspondantes vers la même session ACP.

Les messages suivants dans la conversation liée sont acheminés directement vers la session ACP, et la sortie ACP est renvoyée vers ce même canal, fil ou sujet.

Ce qu’OpenClaw envoie au harnais :

• Les messages de suivi normaux dans une conversation liée sont envoyés sous forme de texte d’invite, avec les pièces jointes uniquement lorsque le harnais ou le backend les prend en charge.
• Les commandes de gestion /acp et les commandes locales du Gateway sont interceptées avant l’envoi à ACP.
• Les événements d’achèvement générés par l’environnement d’exécution sont matérialisés pour chaque cible. Les agents OpenClaw reçoivent l’enveloppe de contexte d’exécution interne d’OpenClaw ; les harnais ACP externes reçoivent une invite en texte brut contenant le résultat de l’enfant et l’instruction. L’enveloppe brute <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> ne doit jamais être envoyée aux harnais externes ni conservée comme texte utilisateur dans la transcription ACP.
• Les entrées de transcription ACP utilisent le texte de déclenchement visible par l’utilisateur ou l’invite d’achèvement en texte brut. Les métadonnées d’événements internes restent structurées dans OpenClaw lorsque cela 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, comme les sous-agents :

• Le parent demande l’exécution d’une tâche 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 dans la même file d’arrière-plan que les lancements de sous-agents natifs ; un harnais ACP lent ne bloque donc pas les tâches sans rapport de la session principale.
• L’achèvement est signalé par le chemin d’annonce de fin de tâche. OpenClaw convertit les métadonnées d’achèvement internes en invite ACP en texte brut avant de les envoyer à un harnais externe ; les harnais ne voient donc pas les marqueurs de contexte d’exécution propres à OpenClaw.
• Le parent reformule le résultat de l’enfant avec la voix normale de l’assistant lorsqu’une réponse destinée à l’utilisateur est utile.

Ne traitez pas ce chemin comme un chat pair à pair entre le parent et l’enfant. L’enfant dispose déjà d’un canal d’achèvement vers le parent.

sessions_send peut cibler une autre session après son lancement. Pour les sessions paires normales, OpenClaw utilise un chemin de suivi agent à agent (A2A) après l’injection du message :

• Attendre la réponse de la session cible.
• Permettre éventuellement au demandeur et à la cible d’échanger un nombre limité 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 une solution de repli 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 une cible ACP et lui envoyer des messages, par exemple avec des paramètres tools.sessions.visibility étendus.

OpenClaw ignore le suivi A2A uniquement lorsque le demandeur est le parent de son propre enfant ACP ponctuel appartenant au parent. Dans ce cas, exécuter A2A en plus de l'achèvement de la tâche peut réveiller le parent avec le résultat de l'enfant, transférer la réponse du parent à l'enfant et créer une boucle d'écho parent/enfant. Le résultat de sessions_send indique delivery.status="skipped" dans ce cas d'enfant possédé, car le chemin d'achèvement est déjà responsable du résultat.

Utilisez resumeSessionId pour poursuivre une session ACP précédente au lieu d'en démarrer une nouvelle. L'agent rejoue l'historique de sa conversation via session/load, ce qui lui permet de reprendre avec tout le contexte précédent.

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

Cas d'utilisation courants :

• Transférez une session Codex de votre ordinateur portable à votre téléphone : demandez à votre agent de reprendre là où vous vous êtes arrêté.
• Poursuivez sans interface, par l'intermédiaire de votre agent, une session de programmation commencée de manière interactive dans la CLI.
• Reprenez un travail interrompu par un redémarrage du Gateway ou un délai d'inactivité.

Remarques :

• resumeSessionId s'applique uniquement lorsque runtime: "acp" ; le runtime de sous-agent par défaut ignore ce champ propre à ACP.
• streamTo s'applique uniquement lorsque runtime: "acp" ; le runtime de sous-agent par défaut ignore ce champ propre à ACP.
• resumeSessionId est un identifiant de reprise ACP/du harnais local à l'hôte, et non une clé de session de canal OpenClaw ; OpenClaw vérifie toujours la politique de lancement ACP et celle de l'agent cible avant l'envoi, tandis que le backend ACP ou le harnais gère l'autorisation de chargement de cet identifiant en amont.
• resumeSessionId restaure l'historique de conversation ACP en amont ; thread et mode continuent de s'appliquer normalement à la nouvelle session OpenClaw que vous créez, donc mode: "session" exige toujours thread: true.
• L'agent cible doit prendre en charge session/load (c'est le cas de Codex et Claude Code).
• Si l'identifiant de session est introuvable, le lancement échoue avec une erreur explicite, sans solution de repli silencieuse vers une nouvelle session.

Après un déploiement du Gateway, effectuez une vérification réelle de bout en bout plutôt que de vous fier 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, la présence d'un véritable childSessionKey et l'absence d'erreur de validation.
5. Nettoyez la session de pont temporaire.

Limitez cette vérification à mode: "run" et omettez streamTo: "parent" : le mode: "session" lié à un fil et les chemins de relais de flux constituent des tests d'intégration distincts et plus complets.