tenequm/acpx-faq

FAQ acpx

Pilotez des agents de codage en mode headless via acpx (>= 0.19.3).

Autorité syntaxique

La syntaxe provient du binaire, pas de ce fichier. acpx --skill show acpx est la référence du fournisseur (~43 000 caractères) et l'arbitre final sur la forme des commandes - ne la DUMPEZ PAS dans la transcription. Récupérez-la dans cet ordre :

1. acpx --help / acpx <commande> --help - les drapeaux que vous êtes sur le point de composer.
2. Un sujet : acpx --skill show acpx | rg -B2 -A12 '<terme>', ou une section : acpx --skill show acpx | sed -n '/^## Sessions/,/^## /p'.
3. Pour écrire quelque chose de nouveau (un flux, un runtime intégré) : dump UNE FOIS dans un fichier temporaire et grep ce fichier.

Ce fichier ne répète rien de ce que couvre la référence. Il ne contient que ce que la référence omet : codes de sortie, sémantique des échecs, pièges et recettes par agent. Si une question de syntaxe n'est pas résolue ici, elle l'est là-bas - allez la chercher, ne devinez jamais un drapeau. Le dossier docs/ du dépôt (codes-de-sortie, contrôle-de-session, surveillance-de-session, permissions, configuration) couvre une partie de ce que la référence livrée omet.

Quand utiliser cette voie

acpx est la voie d'exécution headless hors processus : un autre agent, fournisseur ou compte, piloté depuis un script ou depuis un autre agent, dans un terminal simple, ssh ou cron. Le fan-out intra-session reste sur l'outil de sous-agent du harnais.

Invariants

1. Les drapeaux globaux précèdent la sous-commande de l'agent (--cwd, --model, --approve-all, --agent, --format, --timeout, --ttl, --mcp-config). Le formulaire d'invite n'accepte que -s, --no-wait, -f (et exec aussi --config-option) ; les autres sous-commandes portent les leurs (sessions watch --cursor, sessions export|import --cwd). Un drapeau global après l'agent se termine 1 avec error: unknown option ; un mauvais drapeau avant l'agent se termine 2.

2. -s <nom> ne crée jamais de session. Elle en résout une, en remontant de --cwd jusqu'au .git le plus proche - un répertoire ou fichier, donc chaque worktree et sous-module a sa propre frontière ; en dehors de git, seul le --cwd exact est vérifié. Aucune correspondance ne se termine 4. Créez d'abord avec sessions ensure --name <n> dans le même répertoire.

3. status n'est pas un signal de fin de tour. Elle sonde le processus propriétaire de la file d'attente, jamais l'agent, et continue d'indiquer running après la fin du tour. Ne l'utilisez jamais pour déclencher une automatisation.

4. Les drapeaux de permission ne sont pas un bac à sable.

   • claude : l'adaptateur démarre dans permissions.defaultMode depuis les paramètres Claude (acceptEdits / auto approuve les modifications sans demander). Seulement ce que ce mode escalade atteint acpx comme demande de permission - --deny-all les refuse (exit 5), mais une modification auto-approuvée ne demande jamais.
   • codex : les écritures dans son bac à sable d'écriture de workspace (raciné à --cwd, plus les répertoires temporaires) ne soulèvent aucune demande, donc --deny-all écrit toujours ; en dehors, échoue avec Operation not permitted - y compris le gitdir d'un worktree lié, donc une voie en bac à sable dans un git worktree ne peut pas committer (index.lock: Operation not permitted). Le réseau est désactivé à moins que config.toml n'active network_access. --approve-all ne change pas le mode de l'adaptateur ; INITIAL_AGENT_MODE=read-only|agent|agent-full-access au lancement, ou codex set-mode agent-full-access -s <n> sur une session active, le fait.
   • --allowed-tools / --max-turns n'atteignent que claude (et qoder) ; codex et agy les ignorent. --allowed-tools pré-approuve et ne restreint jamais : "" pour aucun outil dans --help signifie aucune approbation, pas aucun outil.

   Le véritable contrôle du système de fichiers est le --cwd que vous lui donnez.

5. [done] end_turn et exit 0 ne sont pas une preuve de succès. Une suppression par le filtre de contenu, un échec de chargement MCP, une erreur API (une 401 lors d'un rafraîchissement de jeton, un rejet de modèle 400) ou un tour tronqué se terminent tous ainsi. Lisez le flux, ou exigez que l'agent écrive un fichier de résultat que vous pouvez vérifier. Avant un fan-out, un exec bon marché ("Reply OK") par agent et modèle détecte les erreurs d'authentification et de modèle - codex et agy rejettent un --model non annoncé avant le tour, claude avertit et le transmet.

6. Une session persistante maintient une pile de processus résidents uniquement lorsqu'elle est occupée ou chaude. Chaque invite -s élit un propriétaire de file d'attente contenant npm exec -> node <adaptateur> -> <agent> (plus les serveurs MCP de l'agent), environ 550-650 Mo avant MCP. Après le TTL d'inactivité (300s par défaut), le propriétaire se termine et la session reste reprenable ; l'invite suivante la relance. sessions close termine la tâche - enchaînez-la dans la ligne de lancement (voir Par agent) pour que le démontage ne dépende jamais de la mémoire de quelqu'un ; --ttl 0 supprime l'auto-récolte. Voir Démontage.

Par agent

Lancement unique : sessions ensure && prompt && sessions close, un seul appel enchaîné. Une session nommée par tâche, une invite, fermée lorsque le fichier de résultat est lu. La chaîne && rend le démontage mécanique - rien ne nettoie les enregistrements ouverts, et les orphelins proviennent de fermetures non enchaînées - tandis qu'un tour qui échoue avec un code non nul (timeout 3, permission 5) saute la fermeture tout seul, laissant la session ouverte pour la récupération (voir Parler à une session active). Un tour annulé de l'extérieur se termine toujours par 0, donc le fichier de résultat, et non le code de sortie, est la vérification de succès (invariant 5). Ne gardez pas une session pour des suivis attendus : l'état d'un blocage vit en dehors de la conversation (les identifiants sont au niveau de la machine, les parties appartiennent au fichier de résultat) - répondez-y avec une nouvelle session alimentée par le brief plus ce fichier. La reprise - une correction, une révision ou un polissage du résultat d'une session - obtient également une nouvelle session : un agent qui relit son propre contexte manque ce que des yeux neufs repèrent. N'utilisez jamais --no-wait dans une session dont la ligne de lancement porte la fermeture : l'arrêt du propriétaire supprime silencieusement les invites en attente et annule le tour actif (vérifié 0.19.4) ; une invite bloquante avant la fermeture est sécurisée. Utilisez exec pour une réponse sans état sans enregistrement à conserver (un pré-vol "Reply OK"). Les sessions sont indexées par commande de l'agent + cwd + nom ; donnez à chaque exécuteur parallèle son propre nom et, lorsqu'il écrit des fichiers, son propre répertoire (idéalement un worktree).

Les adaptateurs s'exécutent via npm exec à moins que le binaire de l'adaptateur (claude-agent-acp, codex-acp) ne soit sur PATH - cette copie l'emporte sur le fallback du package, et la mise à niveau d'acpx ne le met jamais à jour. Un HOME frais par travail les retélécharge (des centaines de Mo chacun) ; partagez un seul npm_config_cache. Sous macOS, un HOME frais cache également le Trousseau de connexion : l'adaptateur claude échoue avec RUNTIME: Unable to validate model: Could not resolve authentication method - gardez HOME. Le cache npx réutilise également les builds périmées - épinglez les versions exactes des adaptateurs dans ~/.acpx/config.json (agents.<nom>.argv). Une épingle fige les identifiants de modèle qui fonctionnent, et la changer re-indexe les sessions (voir Sessions).

Les exécuteurs héritent des fichiers d'instructions globales de l'utilisateur (le ~/.claude/CLAUDE.md de claude, le AGENTS.md global de codex). Une règle comme "demander avant de modifier" termine un tour headless sur une question sans travail effectué - ouvrez chaque brief par "agissez maintenant ; ne vous arrêtez pas pour demander ou ne terminez pas sur une question". Un exécuteur qui y lit "utiliser un exécuteur hors processus" peut lancer une voie acpx imbriquée dans le même répertoire de travail - ajoutez "vous êtes l'exécuteur ; ne déléguez pas". Supprimez ou renommez l'ancien fichier de résultat avant un relancement (un sondeur lit le fichier périmé), et donnez aux voies parallèles leurs propres chemins temporaires et ports - des worktrees séparés n'isolent pas /tmp.

Ils héritent également de l'environnement du lanceur, et le zsh de codex relit $ZDOTDIR/.zshenv (par défaut ~/.zshenv) pour chaque commande - désactiver un secret dans le lanceur ne l'empêche pas d'entrer, et tout ce que le shell imprime se retrouve dans les fichiers de déploiement sous ~/.codex/sessions.

agy / Antigravity

L'acpx antigravity intégré (0.17.1+) exécute agy_acp_server.par depuis PATH, et la copie qu'Antigravity installe sous ~/.local/lib/antigravity-acp/ n'est pas sur PATH - un acpx antigravity nu se termine 1 avec Failed to spawn agent command: agy_acp_server.par. Ajoutez ce répertoire à PATH, définissez agents.antigravity.argv, ou utilisez --agent <chemin>. L'agent gemini intégré est le CLI Gemini public - un produit différent. Le .par provient de l'installation d'Antigravity ou de l'archive officielle du registre ACP ; gardez-le à côté de son helper localharness_external de la même version (un helper manquant ne fait que logger Localharness not found. et continue), ou pointez ANTIGRAVITY_HARNESS_PATH vers lui. Ni acpx ni agy update ne rafraîchissent le .par : comparez son --version Build label: avec le registre ACP et remplacez les deux fichiers ensemble (le helper installé est en lecture seule - rm -f avant de copier le nouveau).

D=/abs/real/dir                              # doit exister : les racines se résolvent via realpath
acpx --agent ~/.local/lib/antigravity-acp/agy_acp_server.par \
     --cwd "$D" --model gemini-3.8-flash --approve-all --timeout 1800 \
     exec "Exécutez $D/brief.md. Écrivez votre rapport dans $D/report.md."

• --approve-all est obligatoire. Sans cela, chaque écriture est refusée : exit 5 (ou un blocage vers exit 3), avec [done] end_turn toujours imprimé et aucun rapport.

• Les questions à choix fixe font échouer l'invite avec exit 5 même sous --approve-all (dernière ligne Antigravity requested a user answer...) - également pour les lancements --agent. acpx échoue toute question à choix fixe d'un agent de cette façon (PERMISSION_PROMPT_UNAVAILABLE) ; c'est avec agy que ça mord. Rédigez des briefs qui n'ont jamais besoin d'un choix utilisateur.

• Utilisez uniquement les identifiants que la session ACP annonce - un --model délibérément mauvais affiche Available models: sans démarrer un tour (serveur 1.4.5 : gemini-4-argon, gemini-3.8-flash ; les identifiants avec effort gemini-3.7-flash-{low,medium,high} sont partis). agy models est une liste différente. Flash convient au travail en masse basé sur des rubriques et est beaucoup plus rapide, mais manque de vraies découvertes dans le travail de révision / chasse aux bugs ; utilisez un modèle plus fort là.

• agy lit les fichiers frères sans y être invité - les agents partageant un répertoire reproduisent la sortie les uns des autres. Un répertoire par agent, et checksummez toute ré-exécution avant de croire un numéro d'accord.

• Authentification : besoin de auth.type dans <GEMINI_HOME>/antigravity-acp/settings.json (une fois) :

  mkdir -p ~/.gemini/antigravity-acp
  echo '{"auth":{"type":"oauth-personal"}}' > ~/.gemini/antigravity-acp/settings.json
  

  Sans cela : [error] RUNTIME: Authentication required immédiat (exit 1). Avec cela mais jamais connecté : session/new bloque sur une connexion navigateur jusqu'à --timeout (exit 3) - connectez-vous une fois de manière interactive. Le jeton du serveur est séparé de celui du CLI agy : le Trousseau macOS (service gemini, compte antigravity-acp), ou <GEMINI_HOME>/antigravity-acp/acp_token.json hors macOS ou avec AGY_ACP_FORCE_FILE_STORAGE=1. GEMINI_HOME seul n'isole pas le jeton macOS. Un problème d'autorisation est côté serveur - ne le "réparez" pas en passant à gemini-api-key ou un projet GCP (facturation séparée, pas des correctifs).

• Ne passez jamais un agent positionnel avec --agent - exit 2.

• Invites de vérification : exigez une réponse simple et lisez tout le journal. agy achemine les réponses dans des fichiers artefact du cerveau, donc un tail ne peut pas distinguer "aucun outil" de "répondu ailleurs". Ajoutez "Ne créez aucun fichier".

• agy cache les échecs MCP dans un tour qui semble réussi - exit 0, [done] end_turn, et toute la réponse est Le serveur MCP '<nom>' a échoué à s'initialiser : .... Grep pour failed to initialize.

• Préférez exec. Une mort de serveur en milieu de point de contrôle a été signalée pour casser une conversation enregistrée définitivement (could not find doneCh for checkpoint) ; la seule récupération signalée est la suppression de ~/.gemini/antigravity-acp/conversations/<id>.db.

Linux / NixOS

L'agent intégré ajoute le --uid= requis lui-même. NixOS a en plus besoin d'un bundle CA, donc pointez --agent (ou agents.antigravity.argv) vers un wrapper (~/.local/bin/agy-acp-server) :

#!/usr/bin/env bash
export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
exec ~/.local/lib/antigravity-acp/agy_acp_server.par --uid= "$@"

Sans SSL_CERT_FILE, l'OpenSSL intégré du .par n'a pas de chemins CA valides ; son proxy local rapporte 502 Bad Gateway: Failed to connect to backend API et le tour se termine toujours [done] end_turn avec exit 0 (invariant 5). Le vrai CERTIFICATE_VERIFY_FAILED n'apparaît que sous --alsologtostderr.

codex

D=/abs/dir
acpx --cwd "$D" codex sessions ensure --name work            # idempotent ; -s ne peut pas créer
acpx --cwd "$D" codex set model gpt-6-astra -s work
acpx --cwd "$D" codex set reasoning_effort high -s work
{ acpx --cwd "$D" --approve-all --timeout 5400 --suppress-reads \
     codex -s work 'Exécutez ./brief.md. Écrivez votre rapport dans ./report.md.' && \
  acpx --cwd "$D" codex sessions close work; } > run.log 2>&1 &
# un tour échoué saute la fermeture - ré-invitez -s work pour récupérer, puis fermez vous-même

Lancement unique : --model <id> exec --config-option reasoning_effort=low définit le modèle et l'effort en ligne.

• L'adaptateur codex (@agentclientprotocol/codex-acp) flotte sur ^1.1.5 - le comportement peut changer sans mise à niveau d'acpx, mais le 2.x cassant est hors de portée. Un adaptateur périmé rejette les identifiants de modèle plus récents : [error] RUNTIME: Invalid params à session/set_config_option (exit 1), ou une 400 model is not supported qui se termine toujours par [done] end_turn, exit 0. Épinglez-en un à jour : {"agents":{"codex":{"argv":["npx","-y","@agentclientprotocol/[email protected]"]}}}. Une épingle exacte fait toujours flotter le binaire codex à l'intérieur (2.5.0 dépend de @openai/codex ^0.165.0). Les mêmes symptômes touchent un adaptateur à jour lorsque le compte ne dispose pas du modèle : la liste annoncée diffère selon le compte - pré-vol sous le propre login de la voie.
• Le filtre de contenu d'OpenAI supprime les tours inoffensifs qui se terminent proprement ([done] end_turn, exit 0). Du vocabulaire comme race / sweep / exploit / attack dans un nom de fichier, un commentaire ou une invite le déclenche. Lisez la fin de la transcription avant de croire à l'achèvement ; récupérez en ré-invitant la même -s <nom> (le contexte survit à moins que la reconnexion n'échoue - acpx retombe alors silencieusement sur session/new) avec l'argument supplémentaire pour éviter ce vocabulaire. Pour les cascades de nombreux fichiers de brief, vérifiez le transcript avant de fermer avec un somme scripté : trap 'close sano' EXIT dans le processus de fond ne ferme que si la sous-commande se termine normalement. ...

[Le contenu original a été tronqué pour la traduction ; le fichier complet traite d'autres agents comme claude et qoder.]