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 de liste d’autorisation manquante.
• L’adaptateur Codex ACP est préparé avec le Plugin acpx et lancé localement lorsque c’est possible.
• 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 du fournisseur doit toujours exister sur l’hôte pour ce harnais.
• Si l’hôte n’a pas d’accès npm ou 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é d’une autre manière.

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 les règles ; le harnais possède sa connexion au 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 de 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 du Gateway.
• L'authentification du 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 d'un harnais à l'autre.
• 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 ; les exécutions de codage intensives en écriture/exécution nécessitent donc généralement un profil d'autorisation ACPX capable de fonctionner sans interface.

• Le lancement crée ou reprend une session de runtime 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 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 ; la finalisation et la livraison entre surfaces passent par le notificateur de tâche parent au lieu 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 demeure ; 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ées 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 tout de même conserver son propre historique amont s'il prend en charge la reprise.
• 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é :

• "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 Codex comme shell/apply-patch s'exécutent dans Codex. Pour les événements d'outils natifs 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 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 délibérément conservateur : il ne modifie pas les arguments d'outils natifs Codex et ne réécrit pas les enregistrements de fil Codex. Utilisez ACP explicitement uniquement lorsque vous voulez le modèle de runtime/session ACP. La frontière de prise en charge Codex intégrée est documentée dans le contrat de prise en charge du harnais Codex v1.

• openai-codex/* - route OAuth/abonnement PI Codex.
• openai/* plus agentRuntime.id: "codex" - runtime intégré natif du serveur d’application Codex.
• /codex ... - contrôle natif de conversation Codex.
• /acp ... ou runtime: "acp" - contrôle ACP/acpx explicite.

Déclencheurs qui doivent être routés vers le runtime ACP :

• "Exécute ceci comme une session ACP Claude Code ponctuelle et résume le résultat."
• "Utilise Gemini CLI pour cette tâche dans un fil, puis conserve les suivis dans ce même fil."
• "Exécute Codex via ACP dans un fil en arrière-plan."

OpenClaw choisit runtime: "acp", résout le harnais agentId, 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 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 sandboxé et qu’un backend de runtime ACP est chargé. acp.dispatch.enabled=false suspend l’envoi automatique des fils ACP, mais ne masque ni ne bloque les appels explicites sessions_spawn({ runtime: "acp" }). Il cible les 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.

• --bind here et --thread ... sont mutuellement exclusifs.
• --bind here fonctionne uniquement 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 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) retombent sur la valeur par défaut du backend ; les autres erreurs d’accès (par exemple EACCES) apparaissent 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 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 fils 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 au même fil.
• Le désengagement/la fermeture/l’archivage/le délai d’inactivité ou l’expiration par âge maximal supprime la liaison.
• /acp close, /acp cancel, /acp status, /status et /unfocus sont des commandes Gateway, pas des prompts envoyés 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 l’envoi 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 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 c’est non pris en charge/indisponible.

• 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 MP).
• Les canaux 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 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" persistantes configurées 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 au même canal/fil/sujet.

Ce qu’OpenClaw envoie au harnais :

• Les suivis liés normaux sont envoyés sous forme de 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 Gateway locales sont interceptées avant l’envoi ACP.
• Les événements d’achèvement générés par le runtime 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 chat rédigé par l’utilisateur.

Les sessions ACP ponctuelles lancées par une autre exécution d’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 les lancements de sous-agents natifs, afin 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, afin 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 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 le 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.
• Autoriser éventuellement le demandeur et la cible à é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 un repli pour les envois entre pairs lorsque 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 larges de tools.sessions.visibility.

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 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 de sessions_send indique 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, de sorte qu’il reprend avec tout le contexte 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 : dites à votre agent de reprendre là où vous vous étiez arrêté.
• Continuer une session de codage que vous avez 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 ne s’applique que lorsque runtime: "acp" ; le runtime de sous-agent par défaut ignore ce champ propre à ACP.
• streamTo ne s’applique que lorsque runtime: "acp" ; le runtime de sous-agent par défaut ignore ce champ propre à ACP.
• resumeSessionId est un ID 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 ACP ou le harnais possède l’autorisation de chargement de cet ID 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’ID de session est introuvable, le lancement échoue avec une erreur claire, sans repli silencieux vers une nouvelle session.

Après un déploiement du Gateway, exécutez une vérification de bout en bout en direct au lieu 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 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 la barrière sur mode: "run" et ignorez streamTo: "parent" : les chemins mode: "session" liés à un fil et de relais de flux sont des passes d’intégration enrichies distinctes.