​

Agents ACP

​

Quelle page me faut-il ?

​

Est-ce que cela fonctionne immédiatement ?

• Les nouvelles installations livrent désormais le plugin d’exécution acpx inclus activé par défaut.
• Le plugin acpx inclus privilégie son binaire acpx épinglé local au plugin.
• Au démarrage, OpenClaw sonde ce binaire et le répare automatiquement si nécessaire.
• Commencez par /acp doctor si vous voulez une vérification rapide de l’état de préparation.

• Un adaptateur de harness cible peut être récupéré à la demande avec npx la première fois que vous utilisez ce harness.
• L’authentification du fournisseur doit toujours exister sur l’hôte pour ce harness.
• Si l’hôte n’a pas d’accès npm/réseau, les récupérations initiales d’adaptateur peuvent échouer tant que les caches ne sont pas préchauffés ou que l’adaptateur n’est pas installé autrement.

• /acp spawn codex : OpenClaw doit être prêt à initialiser acpx, mais l’adaptateur ACP Codex peut encore nécessiter une récupération au premier lancement.
• /acp spawn claude : même situation pour l’adaptateur ACP Claude, plus l’authentification côté Claude sur cet hôte.

​

Flux opérateur rapide

1. Créez une session :
   • /acp spawn codex --bind here
   • /acp spawn codex --mode persistent --thread auto
2. Travaillez dans la conversation ou le fil lié (ou ciblez explicitement cette clé de session).
3. Vérifiez l’état d’exécution :
   • /acp status
4. Ajustez les options d’exécution si nécessaire :
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
5. Réorientez une session active sans remplacer le contexte :
   • /acp steer tighten logging and continue
6. Arrêtez le travail :
   • /acp cancel (arrêter le tour en cours), ou
   • /acp close (fermer la session + supprimer les liaisons)

​

Démarrage rapide pour les humains

• « Lie ce canal Discord à Codex. »
• « Démarre une session Codex persistante dans un fil ici et garde-la focalisée. »
• « Exécute ceci comme session ACP Claude Code ponctuelle et résume le résultat. »
• « Lie ce chat iMessage à Codex et garde les suivis dans le même espace de travail. »
• « Utilise Gemini CLI pour cette tâche dans un fil, puis garde les suivis dans ce même fil. »

1. Choisir runtime: "acp".
2. Résoudre la cible de harness demandée (agentId, par exemple codex).
3. Si une liaison à la conversation courante est demandée et que le canal actif la prend en charge, lier la session ACP à cette conversation.
4. Sinon, si une liaison de fil est demandée et que le canal actuel la prend en charge, lier la session ACP au fil.
5. Acheminer les messages de suivi liés vers cette même session ACP jusqu’à défocalisation/fermeture/expiration.

​

ACP versus sous-agents

​

Comment ACP exécute Claude Code

1. Plan de contrôle de session ACP OpenClaw
2. Plugin d’exécution acpx inclus
3. Adaptateur ACP Claude
4. Mécanisme d’exécution/session côté Claude

• ACP Claude est une session de harness avec contrôles ACP, reprise de session, suivi des tâches d’arrière-plan et liaison facultative à une conversation/un fil.
• Les backends CLI sont des exécutions locales de repli texte uniquement distinctes. Consultez Backends CLI.

• vous voulez /acp spawn, des sessions liables, des contrôles d’exécution ou du travail persistant de harness : utilisez ACP
• vous voulez un simple repli texte local via la CLI brute : utilisez les backends CLI

​

Sessions liées

​

Liaisons à la conversation courante

• OpenClaw continue de gérer le transport du canal, l’authentification, la sécurité et la livraison.
• La conversation actuelle est épinglée à la clé de session ACP créée.
• Les messages de suivi dans cette conversation sont acheminés vers la même session ACP.
• /new et /reset réinitialisent sur place cette même session ACP liée.
• /acp close ferme la session et supprime la liaison de la conversation actuelle.

• --bind here conserve la même surface de chat. Sur Discord, le canal actuel reste le canal actuel.
• --bind here peut tout de même créer une nouvelle session ACP si vous lancez un nouveau travail. La liaison attache cette session à la conversation actuelle.
• --bind here ne crée pas à lui seul un fil Discord enfant ni un sujet Telegram.
• L’exécution ACP peut toujours avoir son propre répertoire de travail (cwd) ou un espace de travail géré par le backend sur disque. Cet espace de travail d’exécution est distinct de la surface de chat et n’implique pas un nouveau fil de messagerie.
• Si vous créez une session vers un autre agent ACP et ne passez pas --cwd, OpenClaw hérite par défaut de l’espace de travail de l’agent cible, et non de celui du demandeur.
• Si ce chemin d’espace de travail hérité est manquant (ENOENT/ENOTDIR), OpenClaw revient au cwd par défaut du backend au lieu de réutiliser silencieusement le mauvais arbre.
• Si l’espace de travail hérité existe mais n’est pas accessible (par exemple EACCES), la création renvoie l’erreur réelle d’accès au lieu d’abandonner cwd.

• surface de chat : là où les personnes continuent à parler (canal Discord, sujet Telegram, chat iMessage)
• session ACP : l’état d’exécution durable Codex/Claude/Gemini vers lequel OpenClaw achemine
• fil/sujet enfant : surface de messagerie supplémentaire facultative créée uniquement par --thread ...
• espace de travail d’exécution : l’emplacement du système de fichiers où le harness s’exécute (cwd, checkout du dépôt, espace de travail du backend)

• /acp spawn codex --bind here : garder ce chat, créer ou rattacher une session ACP Codex, et y acheminer les futurs messages
• /acp spawn codex --thread auto : OpenClaw peut créer un fil/sujet enfant et y lier la session ACP
• /acp spawn codex --bind here --cwd /workspace/repo : même liaison de chat que ci-dessus, mais Codex s’exécute dans /workspace/repo

• Les canaux de chat/message qui annoncent la prise en charge de la liaison à la conversation courante peuvent utiliser --bind here via le chemin partagé de liaison de conversation.
• Les canaux avec une sémantique personnalisée de fil/sujet peuvent toujours fournir une canonicalisation spécifique au canal derrière la même interface partagée.
• --bind here signifie toujours « lier la conversation courante sur place ».
• Les liaisons génériques à la conversation courante utilisent le stockage partagé de liaison OpenClaw et survivent aux redémarrages normaux de la passerelle.

• --bind here et --thread ... s’excluent mutuellement dans /acp spawn.
• Sur Discord, --bind here lie sur place le canal ou fil actuel. spawnAcpSessions n’est requis que lorsque OpenClaw doit créer un fil enfant pour --thread auto|here.
• Si le canal actif n’expose pas les liaisons ACP à la conversation courante, OpenClaw renvoie un message clair indiquant que ce n’est pas pris en charge.
• resume et les questions de « nouvelle session » sont des questions de session ACP, pas des questions de canal. Vous pouvez réutiliser ou remplacer l’état d’exécution sans changer la surface de chat actuelle.

​

Sessions liées à un fil

• OpenClaw lie un fil à une session ACP cible.
• Les messages de suivi dans ce fil sont acheminés vers la session ACP liée.
• La sortie ACP est renvoyée dans le même fil.
• La défocalisation/fermeture/archivage/expiration par inactivité ou par âge maximal supprime la liaison.

• acp.enabled=true
• acp.dispatch.enabled est activé par défaut (définissez false pour suspendre la distribution ACP)
• drapeau d’adaptateur de canal pour création de fil ACP activé (spécifique à l’adaptateur)
  • Discord : channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram : channels.telegram.threadBindings.spawnAcpSessions=true

​

Canaux prenant en charge les fils

• Tout adaptateur de canal exposant 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 de plugin peuvent ajouter la prise en charge via la même interface de liaison.

​

Paramètres spécifiques au canal

​

Modèle de liaison

• bindings[].type="acp" marque une liaison persistante de conversation ACP.
• bindings[].match identifie la conversation cible :
  • canal ou fil Discord : match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • sujet de forum Telegram : match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • chat de groupe/MP BlueBubbles : match.channel="bluebubbles" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Préférez chat_id:* ou chat_identifier:* pour des liaisons de groupe stables.
  • chat de groupe/MP iMessage : match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Préférez chat_id:* pour des liaisons de groupe stables.
• bindings[].agentId est l’ID de l’agent OpenClaw propriétaire.
• Les remplacements ACP facultatifs se trouvent sous bindings[].acp :
  • mode (persistent ou oneshot)
  • label
  • cwd
  • backend

​

Valeurs par défaut d’exécution par agent

• agents.list[].runtime.type="acp"
• agents.list[].runtime.acp.agent (ID de harness, par exemple codex ou claude)
• agents.list[].runtime.acp.backend
• agents.list[].runtime.acp.mode
• agents.list[].runtime.acp.cwd

1. bindings[].acp.*
2. agents.list[].runtime.acp.*
3. valeurs par défaut ACP globales (par exemple acp.backend)

{
  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 } },
        },
      },
    },
  },
}

• OpenClaw s’assure que la session ACP configurée existe avant utilisation.
• Les messages dans ce canal ou sujet sont acheminés vers la session ACP configurée.
• Dans les conversations liées, /new et /reset réinitialisent sur place cette même clé de session ACP.
• Les liaisons d’exécution temporaires (par exemple créées par des flux de focalisation de fil) continuent de s’appliquer lorsqu’elles sont présentes.
• Pour les créations 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 reviennent au cwd par défaut du backend ; les véritables échecs d’accès sont remontés comme erreurs de création.

​

Démarrer des sessions ACP (interfaces)

​

Depuis sessions_spawn

{
  "task": "Ouvre le dépôt et résume les tests en échec",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

• runtime vaut par défaut subagent, donc définissez explicitement runtime: "acp" pour les sessions ACP.
• Si agentId est omis, OpenClaw utilise acp.defaultAgent lorsqu’il est configuré.
• mode: "session" requiert thread: true pour conserver une conversation liée persistante.

• task (obligatoire) : prompt initial envoyé à la session ACP.
• runtime (obligatoire pour ACP) : doit être "acp".
• agentId (facultatif) : ID de harness ACP cible. Se rabat sur acp.defaultAgent s’il est défini.
• thread (facultatif, par défaut false) : demande un flux de liaison de fil lorsque pris en charge.
• mode (facultatif) : run (ponctuel) ou session (persistant).
  • la valeur par défaut est run
  • si thread: true et que le mode est omis, OpenClaw peut par défaut adopter un comportement persistant selon le chemin d’exécution
  • mode: "session" requiert thread: true
• cwd (facultatif) : répertoire de travail demandé pour l’exécution (validé par la politique backend/exécution). S’il est omis, la création ACP hérite de l’espace de travail de l’agent cible lorsqu’il est configuré ; les chemins hérités manquants reviennent aux valeurs par défaut du backend, tandis que les véritables erreurs d’accès sont renvoyées.
• label (facultatif) : libellé orienté opérateur utilisé dans le texte de session/bannière.
• resumeSessionId (facultatif) : reprendre une session ACP existante au lieu d’en créer une nouvelle. L’agent rejoue son historique de conversation via session/load. Requiert runtime: "acp".
• streamTo (facultatif) : "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.
  • Lorsque disponible, les réponses acceptées incluent streamLogPath pointant vers un journal JSONL limité à la session (<sessionId>.acp-stream.jsonl) que vous pouvez suivre pour obtenir l’historique complet du relais.

​

Reprendre une session existante

{
  "task": "Continue là où nous nous étions arrêtés — corrige les échecs de test restants",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

• Transférer une session Codex de votre ordinateur portable à votre téléphone — demandez à votre agent de reprendre là où vous vous êtes arrêté
• Continuer une session de code commencée de façon interactive dans la CLI, maintenant de façon headless via votre agent
• Reprendre un travail interrompu par un redémarrage de passerelle ou un délai d’inactivité

• resumeSessionId requiert runtime: "acp" — renvoie une erreur s’il est utilisé avec l’exécution de sous-agent.
• 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" requiert 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, la création échoue avec une erreur claire — aucun repli silencieux vers une nouvelle session.

​

Test de fumée opérateur

1. Vérifiez la version/le commit de la passerelle déployée sur l’hôte cible.
2. Confirmez que la source déployée inclut l’acceptation de lignée ACP dans src/gateway/sessions-patch.ts (subagent:* or acp:* sessions).
3. Ouvrez une session pont ACPX temporaire vers un agent actif (par exemple razor(main) sur jpclawhq).
4. Demandez à cet agent d’appeler sessions_spawn avec :
   • runtime: "acp"
   • agentId: "codex"
   • mode: "run"
   • tâche : Reply with exactly LIVE-ACP-SPAWN-OK
5. Vérifiez que l’agent signale :
   • accepted=yes
   • une vraie childSessionKey
   • aucune erreur de validateur
6. Nettoyez la session pont ACPX temporaire.

Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
Set the task to: "Reply with exactly LIVE-ACP-SPAWN-OK".
Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exact text or none>.

• Gardez ce test de fumée sur mode: "run" sauf si vous testez intentionnellement des sessions ACP persistantes liées à un fil.
• N’exigez pas streamTo: "parent" pour la validation de base. Ce chemin dépend des capacités du demandeur/de la session et constitue une vérification d’intégration distincte.
• Considérez les tests mode: "session" liés à un fil comme un second passage d’intégration plus riche depuis un vrai fil Discord ou sujet Telegram.

​

Compatibilité sandbox

• Si la session demandeuse est sandboxée, les créations ACP sont bloquées à la fois pour sessions_spawn({ runtime: "acp" }) et /acp spawn.
  • Erreur : Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.
• sessions_spawn avec runtime: "acp" ne prend pas en charge sandbox: "require".
  • Erreur : sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".

​

Depuis la commande /acp

/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --bind here
/acp spawn codex --thread here

• --mode persistent|oneshot
• --bind here|off
• --thread auto|here|off
• --cwd <absolute-path>
• --label <name>

​

Résolution de cible de session

1. Argument de cible explicite (ou --session pour /acp steer)
   • essaie d’abord la clé
   • puis l’ID de session de forme UUID
   • puis le libellé
2. Liaison du fil courant (si cette conversation/ce fil est lié à une session ACP)
3. Repli sur la session demandeuse actuelle

​

Modes de liaison lors de la création

• --bind here est le chemin opérateur le plus simple pour « faire de ce canal ou chat un espace propulsé par Codex ».
• --bind here ne crée pas de fil enfant.
• --bind here n’est disponible que sur les canaux exposant la prise en charge de la liaison à la conversation courante.
• --bind et --thread ne peuvent pas être combinés dans le même appel /acp spawn.

​

Modes de fil lors de la création

• Sur les surfaces sans liaison de fil, le comportement par défaut est en pratique off.
• La création liée à un fil nécessite la prise en charge par la politique du canal :
  • Discord : channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram : channels.telegram.threadBindings.spawnAcpSessions=true
• Utilisez --bind here lorsque vous voulez épingler la conversation actuelle sans créer de fil enfant.

​

Contrôles ACP

• /acp spawn
• /acp cancel
• /acp steer
• /acp close
• /acp status
• /acp set-mode
• /acp set
• /acp cwd
• /acp permissions
• /acp timeout
• /acp model
• /acp reset-options
• /acp sessions
• /acp doctor
• /acp install

​

Guide pratique des commandes ACP

​

Correspondance des options d’exécution

• /acp model <id> correspond à la clé de configuration d’exécution model.
• /acp permissions <profile> correspond à la clé de configuration d’exécution approval_policy.
• /acp timeout <seconds> correspond à la clé de configuration d’exécution timeout.
• /acp cwd <path> met directement à jour le remplacement cwd d’exécution.
• /acp set <key> <value> est le chemin générique.
  • Cas particulier : key=cwd utilise le chemin de remplacement cwd.
• /acp reset-options efface tous les remplacements d’exécution pour la session cible.

​

Prise en charge des harnesses acpx (actuelle)

• claude
• codex
• copilot
• cursor (Cursor CLI : cursor-agent acp)
• droid
• gemini
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• pi
• qwen

​

Configuration requise

{
  acp: {
    enabled: true,
    // Facultatif. La valeur par défaut est true ; définissez false pour suspendre la distribution ACP tout en conservant les contrôles /acp.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "openclaw",
      "opencode",
      "pi",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}

• Discord : channels.discord.threadBindings.spawnAcpSessions=true

​

Configuration du plugin pour le backend acpx

/acp doctor

openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true

openclaw plugins install ./path/to/local/acpx-plugin

/acp doctor

​

Configuration de la commande et de la version d’acpx

1. La commande pointe par défaut vers node_modules/.bin/acpx local au plugin à l’intérieur du paquet du plugin ACPX.
2. La version attendue correspond par défaut à l’épinglage de l’extension.
3. Au démarrage, le backend ACP est immédiatement enregistré comme non prêt.
4. Une tâche d’assurance en arrière-plan vérifie acpx --version.
5. Si le binaire local au plugin est manquant ou ne correspond pas, il exécute : npm install --omit=dev --no-save acpx@<pinned> puis revérifie.

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}

• command accepte un chemin absolu, un chemin relatif ou un nom de commande (acpx).
• Les chemins relatifs sont résolus à partir du répertoire de travail OpenClaw.
• expectedVersion: "any" désactive la vérification stricte de version.
• Lorsque command pointe vers un binaire/chemin personnalisé, l’auto-installation locale au plugin est désactivée.
• Le démarrage d’OpenClaw reste non bloquant pendant l’exécution de la vérification de santé du backend.

​

Installation automatique des dépendances

​

Pont MCP des outils de plugin

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

• Injecte un serveur MCP intégré nommé openclaw-plugin-tools dans le bootstrap de session ACPX.
• Expose les outils de plugin déjà enregistrés par les plugins OpenClaw installés et activés.
• Garde la fonctionnalité explicite et désactivée par défaut.

• Cela élargit la surface d’outils du harness ACP.
• Les agents ACP n’obtiennent l’accès qu’aux outils de plugin déjà actifs dans la passerelle.
• Considérez cela comme la même frontière de confiance que celle consistant à laisser ces plugins s’exécuter dans OpenClaw lui-même.
• Examinez les plugins installés avant de l’activer.

​

Configuration du délai d’exécution

openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

​

Configuration des permissions

​

permissionMode

​

nonInteractivePermissions

​

Configuration

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

Important : OpenClaw utilise actuellement par défaut permissionMode=approve-reads et nonInteractivePermissions=fail. Dans les sessions ACP non interactives, toute écriture ou exécution qui déclenche une invite de permission peut échouer avec AcpRuntimeError: Permission prompt unavailable in non-interactive mode. Si vous devez restreindre les permissions, définissez nonInteractivePermissions sur deny afin que les sessions se dégradent proprement au lieu de planter.

​

Dépannage