Routeur ACP Harness

Que fait Routeur ACP Harness ?

Lorsque l'intention de l'utilisateur est "exécute ceci dans Claude Code/Cursor/Copilot/OpenClaw/OpenCode/Gemini/Grok Build/Qwen/Kiro/Kimi/iFlow/Droid/Kilocode (harnais ACP)", n'utilisez pas l'environnement d'exécution du sous-agent ni le scraping PTY. Acheminez via les flux compatibles ACP.

Codex est spécial : la liaison et le contrôle de chat/conversation standard doivent utiliser le plugin natif de l'application serveur Codex (/codex bind, /codex threads, /codex resume) au lieu du chemin ACP par défaut. Utilisez ACP pour Codex uniquement lorsque l'utilisateur nomme explicitement ACP//acp/acpx, ou lors du lancement de sessions enfants en arrière-plan via sessions_spawn lorsqu'un environnement d'exécution Codex natif n'est pas encore disponible.

Détection d'intention

Déclenchez cette compétence lorsque l'utilisateur demande à OpenClaw de :

• exécuter quelque chose dans Claude Code / Cursor / Copilot / OpenClaw / OpenCode / Gemini / Grok Build / Qwen / Kiro / Kimi / iFlow / Droid / Kilocode
• exécuter Codex explicitement via ACP, /acp, ou acpx
• continuer un travail de harnais existant
• relayer des instructions vers un harnais de codage externe
• maintenir une conversation de harnais externe sous forme de conversation en fil

Vérification préalable obligatoire pour les demandes de fil d'agent de codage :

• Avant de créer un fil pour un travail de harnais ACP, lisez d'abord cette compétence dans le même tour.
• Après la lecture, suivez le Chemin d'exécution ACP OpenClaw ci-dessous ; n'utilisez pas message(action="thread-create") pour le lancement de fil de harnais ACP.

Sélection de mode

Choisissez l'un de ces chemins :

1. Chemin d'exécution ACP OpenClaw (par défaut) : utilisez sessions_spawn / outils d'environnement d'exécution ACP.
2. Chemin acpx direct (téléphone arabe) : utilisez la CLI acpx via exec pour piloter la session de harnais directement.

Utilisez le chemin acpx direct lorsque l'une de ces conditions est vraie :

• l'utilisateur demande explicitement un pilotage direct par acpx
• le chemin d'environnement d'exécution/plugin ACP est indisponible ou défaillant
• la tâche consiste simplement à "relayer des invites vers le harnais" et aucune fonctionnalité du cycle de vie ACP d'OpenClaw n'est nécessaire

N'utilisez pas :

• l'environnement d'exécution subagents pour le contrôle du harnais
• la délégation de commande /acp comme une exigence pour l'utilisateur
• le scraping PTY des CLI de harnais ACP prises en charge lorsque acpx est disponible

Correspondance des identifiants d'agent

Utilisez ces valeurs par défaut lorsque l'utilisateur nomme directement un harnais :

• "openclaw" -> agentId: "openclaw"
• "claude" ou "claude code" -> agentId: "claude"
• "codex" -> agentId: "codex" uniquement pour les demandes ACP/acpx explicites ou le lancement d'environnement d'exécution ACP en arrière-plan
• "copilot" ou "github copilot" -> agentId: "copilot"
• "cursor" ou "cursor cli" -> agentId: "cursor"
• "droid" ou "factory droid" -> agentId: "droid"
• "opencode" -> agentId: "opencode"
• "gemini" ou "gemini cli" -> agentId: "gemini"
• "grok build" ou "grok-build" -> agentId: "grok-build"
• "iflow" -> agentId: "iflow"
• "kilocode" -> agentId: "kilocode"
• "kimi" ou "kimi cli" -> agentId: "kimi"
• "kiro" ou "kiro cli" -> agentId: "kiro"
• "qwen" ou "qwen code" -> agentId: "qwen"

Ces valeurs par défaut correspondent aux alias intégrés actuels de acpx.

grok-build est une cible d'agent ACPX, pas l'identifiant de modèle xAI xai/grok-build-0.1. Acheminez grok-build via agentId ; utilisez la référence xAI complète uniquement dans un champ model d'OpenClaw.

Si la politique rejette l'identifiant choisi, signalez clairement l'erreur de politique et demandez l'identifiant d'agent ACP autorisé.

Chemin d'exécution ACP OpenClaw

Comportement requis :

1. Pour les demandes de lancement de fil de harnais ACP, lisez d'abord cette compétence dans le même tour avant d'appeler des outils.
2. Utilisez sessions_spawn avec :
   • runtime: "acp"
   • thread: true
   • mode: "session" (sauf si l'utilisateur souhaite explicitement un mode unique)
3. Pour la création de fil de harnais ACP, n'utilisez pas message avec action=thread-create ; sessions_spawn est le seul chemin de création de fil.
4. Placez le travail demandé dans task pour que la session ACP le reçoive immédiatement.
5. Définissez agentId explicitement sauf si l'agent ACP par défaut est connu.
6. Ne demandez pas à l'utilisateur d'exécuter des commandes slash ou des CLI lorsque ce chemin fonctionne directement.

Exemple :

Utilisateur : "lance une session ACP codex de test dans un fil et dis-lui de dire bonjour"

Appel :

{
  "task": "Dis bonjour.",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

Politique de récupération de lancement de fil

Lorsque l'utilisateur demande de démarrer un harnais de codage dans un fil, traitez cela comme une demande d'environnement d'exécution ACP et essayez de la satisfaire de bout en bout.

Comportement requis lorsque le backend ACP est indisponible :

1. Ne demandez pas immédiatement à l'utilisateur de choisir un chemin alternatif.
2. Tentez d'abord une réparation locale automatique :
   • vérifiez que acpx épinglé localement dans le plugin est installé dans le paquet de plugin ACPX
   • vérifiez ${ACPX_CMD} --version
3. Après la réinstallation/réparation, redémarrez la passerelle et proposez explicitement d'exécuter ce redémarrage pour l'utilisateur.
4. Réessayez le lancement de fil ACP une fois après la réparation.
5. Ce n'est qu'en cas d'échec de la réparation+nouvelle tentative que vous signalez l'erreur concrète et proposez ensuite des options de repli.

Lorsque vous proposez un repli, gardez ACP en premier :

• Option 1 : réessayer le lancement ACP après avoir montré l'étape exacte qui a échoué
• Option 2 : flux direct acpx (téléphone arabe)

Ne revenez pas par défaut à l'environnement d'exécution du sous-agent pour ces demandes.

Politique d'installation et de version d'ACPX (chemin acpx direct)

Pour ce dépôt, les appels acpx directs doivent suivre la même politique d'épinglage que le paquet d'extension @openclaw/acpx.

1. Préférez le binaire local au plugin, pas le PATH global :
   • ${ACPX_PLUGIN_ROOT}/node_modules/.bin/acpx
2. Résolvez la version épinglée depuis la dépendance d'extension :
   • node -e "console.log(require(process.env.ACPX_PLUGIN_ROOT + '/package.json').dependencies.acpx)"
3. Si le binaire est manquant ou la version ne correspond pas, installez la version épinglée localement au plugin :
   • cd "$ACPX_PLUGIN_ROOT" && npm install --omit=dev --no-save acpx@<versionEpinglee>
4. Vérifiez avant utilisation :
   • ${ACPX_PLUGIN_ROOT}/node_modules/.bin/acpx --version
5. Si l'installation/la réparation a modifié les artefacts ACPX, redémarrez la passerelle et proposez d'exécuter le redémarrage.
6. N'exécutez pas npm install -g acpx sauf si l'utilisateur demande explicitement une installation globale.

Définissez et réutilisez :

ACPX_PLUGIN_ROOT="<racine-du-plugin-acpx-embarque>"
ACPX_CMD="$ACPX_PLUGIN_ROOT/node_modules/.bin/acpx"

Chemin acpx direct ("téléphone arabe")

Utilisez ce chemin pour piloter des sessions de harnais sans /acp ni environnement d'exécution de sous-agent.

Règles

1. Utilisez des commandes exec qui appellent ${ACPX_CMD}.
2. Réutilisez un nom de session stable par conversation afin que les invites de suivi restent dans le même contexte de harnais.
3. Préférez --format quiet pour un texte d'assistant propre à relayer à l'utilisateur.
4. Utilisez exec (unique) uniquement lorsque l'utilisateur souhaite un comportement unique.
5. Rendez le répertoire de travail explicite (--cwd) lorsque la portée de la tâche dépend du contexte du dépôt.

Nommage des sessions

Utilisez un nom stable, par exemple :

• oc-<harnais>-<idConversation>

Où idConversation est l'identifiant du fil lorsqu'il est disponible, sinon l'identifiant du canal/de la conversation.

Modèles de commandes

Session persistante (créer si manquante, puis invite) :

${ACPX_CMD} codex sessions show oc-codex-<idConversation> \
  || ${ACPX_CMD} codex sessions new --name oc-codex-<idConversation>

${ACPX_CMD} codex -s oc-codex-<idConversation> --cwd <cheminEspaceTravail> --format quiet "<invite>"

Unique :

${ACPX_CMD} codex exec --cwd <cheminEspaceTravail> --format quiet "<invite>"

Annuler un tour en cours :

${ACPX_CMD} codex cancel -s oc-codex-<idConversation>

Fermer la session :

${ACPX_CMD} codex sessions close oc-codex-<idConversation>

Alias de harnais dans acpx

• claude
• codex
• copilot
• cursor
• droid
• gemini
• grok-build
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• qwen

Commandes d'adaptateur intégrées dans acpx

Les valeurs par défaut sont :

• openclaw -> openclaw acp
• claude -> bundled @agentclientprotocol/[email protected]
• codex -> bundled @agentclientprotocol/[email protected] through OpenClaw's isolated CODEX_HOME wrapper
• copilot -> copilot --acp --stdio
• cursor -> cursor-agent acp
• droid -> droid exec --output-format acp
• gemini -> gemini --acp
• grok-build -> grok agent stdio
• iflow -> iflow --experimental-acp
• kilocode -> npx -y @kilocode/cli acp
• kimi -> kimi acp
• kiro -> kiro-cli acp
• opencode -> npx -y opencode-ai acp
• qwen -> qwen --acp

Si ~/.acpx/config.json remplace agents, ces remplacements remplacent les valeurs par défaut. Si votre installation locale de Cursor expose encore ACP sous la forme agent acp, définissez cela comme remplacement explicite de l'agent cursor.

Gestion des échecs

• acpx: command not found :
  • pour les demandes ACP de lancement de fil, installez immédiatement acpx épinglé localement dans le paquet de plugin ACPX
  • redémarrez la passerelle après l'installation et proposez d'exécuter le redémarrage automatiquement
  • puis réessayez une fois
  • ne demandez pas d'abord la permission d'installation, sauf si la politique l'exige explicitement
  • n'installez pas acpx globalement sauf demande explicite
• commande d'adaptateur manquante (par exemple claude-agent-acp introuvable) :
  • pour les demandes ACP de lancement de fil, restaurez d'abord les valeurs par défaut intégrées en supprimant les remplacements d'agent défectueux dans ~/.acpx/config.json
  • puis réessayez une fois avant de proposer un repli
  • si l'utilisateur souhaite des remplacements basés sur des binaires, installez exactement le binaire d'adaptateur configuré
• NO_SESSION : exécutez ${ACPX_CMD} <agent> sessions new --name <nomSession> puis réessayez l'invite.
• file d'attente occupée : attendez la fin (par défaut) ou utilisez --no-wait lorsque le comportement asynchrone est explicitement souhaité.

Relais de sortie

Lors du relais à l'utilisateur, renvoyez le texte de sortie final de l'assistant issu du résultat de la commande acpx. Évitez de relayer le bruit brut des outils locaux, sauf si l'utilisateur a demandé des journaux détaillés.