Agents ACP

• 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 manquante dans la liste d’autorisation.
• 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 les entrées de projet fiables ainsi que la configuration sûre de routage modèle/fournisseur depuis la configuration Codex de l’hôte, tandis que l’authentification, les notifications et les hooks restent dans la configuration de l’hôte.
• D’autres adaptateurs de harnais cibles peuvent encore être récupérés à la demande avec npx lors de leur première utilisation.
• L’authentification du fournisseur doit toujours exister sur l’hôte pour ce harnais.
• Si l’hôte n’a pas npm ni accès réseau, les récupérations d’adaptateurs au premier lancement é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 d’incriminer OpenClaw, vérifiez :

• /acp doctor signale un backend activé et sain.
• L’id 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 ids 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 d’autorisation correspond au travail. Les sessions non interactives ne peuvent pas cliquer sur les invites d’autorisation natives, donc les exécutions de codage lourdes en écriture/exécution ont généralement besoin d’un profil d’autorisation ACPX capable de continuer sans interface.

• Le lancement crée ou reprend une session 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 runtime est persistante ; la complétion et la livraison inter-surfaces passent par le notificateur de tâche parent plutôt que d’agir comme une session de chat utilisateur normale.
• La maintenance des tâches ferme les sessions ACP ponctuelles terminales ou orphelines appartenant au parent. Les sessions ACP persistantes sont préservées tant qu’une liaison de conversation active demeure ; les sessions persistantes obsolètes sans liaison active sont fermées afin qu’elles ne puissent pas être reprises silencieusement une fois que la tâche propriétaire est terminée ou que son enregistrement de tâche a disparu.
• Les messages de suivi liés vont directement à la session ACP jusqu’à ce que la liaison soit fermée, désélectionnée, réinitialisée ou expirée.
• Les commandes Gateway restent locales. /acp ..., /status et /unfocus ne sont jamais envoyées comme texte d’invite normal à un harnais ACP lié.
• cancel abandonne le tour actif lorsque le backend prend en charge l’annulation ; il ne supprime pas les métadonnées de liaison ni de session.
• close termine 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 arbres de processus wrapper et adaptateur appartenant à OpenClaw après close, et récupère les orphelins ACPX obsolètes appartenant à OpenClaw au démarrage de Gateway.
• Les workers 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é :

• "Lier ce canal Discord à Codex."
• "Attacher ce chat au fil Codex <id>."
• "Afficher les fils Codex, puis lier celui-ci."

La liaison de conversation Codex native est le chemin de contrôle de chat par défaut. Les outils dynamiques OpenClaw s’exécutent toujours via OpenClaw, tandis que les outils natifs de Codex comme shell/apply-patch s’exécutent dans Codex. Pour les événements d’outils natifs de Codex, OpenClaw injecte un relais de hook natif par tour afin que les hooks de Plugin puissent bloquer before_tool_call, observer after_tool_call et acheminer 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 d’outils natifs de Codex et ne réécrit pas les enregistrements de fil Codex. Utilisez ACP explicite uniquement lorsque vous voulez le modèle de runtime/session ACP. La limite de prise en charge Codex intégrée est documentée dans le contrat de prise en charge du harnais Codex v1.

• refs de modèle Codex héritées - 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 être routés vers le runtime ACP :

• "Exécutez ceci comme une 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 le agentId du harnais, se lie à la conversation ou au fil actuel lorsque c’est pris en charge, et route les suivis vers cette session jusqu’à fermeture/expiration. Codex suit ce chemin uniquement lorsque ACP/acpx est explicite ou que le Plugin Codex natif est indisponible pour l’opération demandée.

Pour sessions_spawn, runtime: "acp" est annoncé uniquement lorsque ACP est activé, que le demandeur n’est pas en bac à sable 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 ids de harnais ACP comme codex, claude, droid, gemini ou opencode. Ne passez pas un id d’agent de configuration OpenClaw normal depuis 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 id de harnais sous-jacent.

• --bind here et --thread ... s’excluent mutuellement.
• --bind here fonctionne uniquement sur les canaux qui annoncent la liaison à la conversation actuelle ; sinon OpenClaw renvoie 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 lancez 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 erreurs de lancement.
• Les commandes de gestion du Gateway restent locales dans les conversations liées - les commandes /acp ... sont gérées par OpenClaw même lorsque le texte de suivi normal est routé vers la session ACP liée ; /status et /unfocus restent également locales 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.
• Unfocus/close/archive/idle-timeout ou une expiration par âge maximal supprime la liaison.
• /acp close, /acp cancel, /acp status, /status et /unfocus sont des commandes Gateway, pas des invites 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 false pour suspendre la distribution automatique des fils ACP ; les appels explicites sessions_spawn({ runtime: "acp" }) fonctionnent toujours).
• Lancements de sessions de fil par adaptateur de canal activés (par défaut : true) :
  • Discord : channels.discord.threadBindings.spawnSessions=true
  • Telegram : channels.telegram.threadBindings.spawnSessions=true

La prise en charge des liaisons 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 la 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.

Les sessions interactives sont destinées à poursuivre l’échange sur une surface de discussion 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ées de façon persistante routent les conversations correspondantes vers la même session ACP.

Les messages de suivi dans la conversation liée sont routés directement vers la session ACP, et la sortie ACP est renvoyée vers 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 les 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 <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> ne doit jamais être envoyée à des harnais externes ni persisté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 discussion rédigé par l’utilisateur.

Les sessions ACP à usage unique créées par une autre exécution d’agent sont des enfants d’arrière-plan, semblables aux sous-agents :

• Le parent demande le 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 les créations de sous-agents natives, de sorte qu’un harnais ACP lent ne bloque pas le travail non lié de la session principale.
• Les rapports d’achèvement reviennent par le chemin d’annonce d’achèvement de tâche. OpenClaw convertit les métadonnées d’achèvement internes en une 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 destinée à l’utilisateur est utile.

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

sessions_send peut cibler une autre session après la création. Pour les sessions de pairs normales, OpenClaw utilise un chemin de suivi agent-à-agent (A2A) après avoir injecté le 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 où l’expéditeur a besoin d’un suivi visible. Il reste activé lorsqu’une session non liée 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 à usage unique possédé par ce parent. Dans ce cas, exécuter A2A par-dessus l’achèvement de la 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 signale delivery.status="skipped" pour ce cas d’enfant possédé, 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, ce qui lui permet de reprendre avec tout le contexte antérieur.

{  "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 vers votre téléphone - dites à votre agent de reprendre là où vous vous étiez arrêté.
• Continuer une session de codage démarrée de manière 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 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/harness local à l’hôte, pas une clé de session de canal OpenClaw ; OpenClaw vérifie toujours la politique de création ACP et la politique de l’agent cible avant l’envoi, tandis que le backend ou le harness ACP possède 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, la création échoue avec une erreur claire - aucun repli silencieux vers une nouvelle session.

Après un déploiement du 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 du gateway déployée et le commit sur l’hôte cible.
2. Ouvrez une session de pont ACPX temporaire vers un agent en direct.
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 le contrôle sur mode: "run" et omettez streamTo: "parent" - les chemins mode: "session" liés aux fils de discussion et les relais de flux sont des passes d’intégration enrichies distinctes.