tenequm/acpx-faq

acpx FAQ

Treibe Codierungs-Agenten kopflos durch acpx (>= 0.19.3).

Syntax-Autorität

Die Syntax stammt aus der Binärdatei, nicht aus dieser Datei. acpx --skill show acpx ist die Anbieter-Referenz (~43k Zeichen) und der Entscheider bei Befehlsformen – sie NICHT in das Transkript einfügen. Abruf in dieser Reihenfolge:

1. acpx --help / acpx <cmd> --help – die Flags, die du gerade zusammensetzen möchtest.
2. Ein Thema: acpx --skill show acpx | rg -B2 -A12 '<Begriff>', oder ein Abschnitt: acpx --skill show acpx | sed -n '/^## Sessions/,/^## /p'.
3. Etwas Neues authorisieren (ein Ablauf, eine eingebettete Runtime): Einmal in eine temporäre Datei ausgeben und dann diese Datei greppen.

Diese Datei wiederholt nichts, was die Referenz abdeckt. Sie enthält nur das, was der Referenz fehlt: Exit-Codes, Fehlersemantik, Fallstricke und agentenspezifische Rezepte. Wenn eine Syntaxfrage hier nicht beantwortet wird, dann dort – hole sie ab, rate niemals ein Flag. Das docs/-Verzeichnis des Repos (Exit-Codes, Session-Kontrolle, Session-Watch, Berechtigungen, Konfiguration) deckt einiges ab, was die ausgelieferte Referenz auslässt.

Wann dieser Lane

acpx ist der kopflose prozessexterne Ausführungslane: ein anderer Agent, Anbieter oder Account, gesteuert von einem Skript oder einem anderen Agenten, in einem normalen Terminal, SSH oder Cron. Der In-Session-Fan-out bleibt dem Subagenten-Tool des Harness überlassen.

Invarianten

1. Globale Flags stehen vor dem Agenten-Subbefehl (--cwd, --model, --approve-all, --agent, --format, --timeout, --ttl, --mcp-config). Die Prompt-Form akzeptiert nur -s, --no-wait, -f (und exec auch --config-option); andere Subbefehle haben ihre eigenen (sessions watch --cursor, sessions export|import --cwd). Ein globales Flag nach dem Agenten beendet mit 1 mit error: unknown option; ein falsches Flag vor dem Agenten beendet mit 2.

2. -s <name> erzeugt niemals eine Session. Es löst eine auf, indem es von --cwd aufwärts zum nächsten .git sucht – ein Verzeichnis oder eine Datei, sodass jeder Worktree und jedes Submodul seine eigene Grenze hat; außerhalb von Git wird nur das exakte --cwd geprüft. Kein Treffer beendet mit 4. Erstelle zuerst mit sessions ensure --name <n> im selben Verzeichnis.

3. status ist kein Blinklicht. Es überprüft den Queue-Owner-Prozess, niemals den Agenten, und sagt auch nach dem Ende des Zuges noch running. Blockiere niemals eine Automatisierung darauf.

4. Berechtigungs-Flags sind keine Sandbox.

   • claude: Der Adapter startet im permissions.defaultMode aus den Claude-Einstellungen (acceptEdits / auto genehmigt Bearbeitungen automatisch ohne Nachfrage). Nur was dieser Modus eskaliert, erreicht acpx als Berechtigungsanfrage – --deny-all verweigert diese (Exit 5), aber eine automatisch genehmigte Bearbeitung fragt nie nach.
   • codex: Schreibvorgänge innerhalb seiner Workspace-Write-Sandbox (verankert bei --cwd, plus temporären Verzeichnissen) lösen keine Anfrage aus, sodass --deny-all trotzdem schreibt; außerhalb schlägt es fehl mit Operation not permitted – einschließlich des Gitdir eines verlinkten Worktrees, sodass ein eingescannter Lane in einem git worktree nicht commiten kann (index.lock: Operation not permitted). Netzwerk ist aus, es sei denn, config.toml aktiviert network_access. --approve-all ändert den Adaptermodus nicht; INITIAL_AGENT_MODE=read-only|agent|agent-full-access beim Start, oder codex set-mode agent-full-access -s <n> bei einer laufenden Session, tut dies.
   • --allowed-tools / --max-turns erreichen nur Claude (und Qoder); Codex und AGY ignorieren sie. --allowed-tools genehmigt vorab und schränkt niemals ein: "" für "keine Tools" in --help bedeutet keine Genehmigungen, nicht keine Tools.

   Die eigentliche Dateisystemkontrolle ist, welches --cwd du übergibst.

5. [done] end_turn und Exit 0 sind keine Erfolgsgarantie. Ein Content-Filter-Kill, ein MCP-Ladefehler, ein API-Fehler (ein 401 während einer Token-Aktualisierung, eine 400 Modell-Ablehnung) oder ein abgebrochener Zug enden alle so. Lies den Stream oder verlange, dass der Agent eine Ergebnisdatei schreibt, die du überprüfen kannst. Vor einem Fan-out fängt ein billiger exec ("Reply OK") pro Agent und Modell Authentifizierungs- und Modellfehler – Codex und AGY lehnen ein nicht angekündigtes --model vor dem Zug ab, Claude warnt und leitet es weiter.

6. Eine persistente Session hält nur dann einen residenten Prozess-Stack, wenn sie beschäftigt oder warm ist. Jeder -s-Prompt wählt einen Queue-Owner, der npm exec -> node <adapter> -> <agent> hält (plus die MCP-Server des Agenten), etwa 550–650 MB vor MCP. Nach dem Leerlauf-TTL (Standard 300s) beendet sich der Owner und die Session bleibt fortsetzbar; der nächste Prompt startet sie neu. sessions close beendet die Aufgabe – verketten Sie es in die Startzeile (siehe Pro Agent), sodass der Abbau nie davon abhängt, dass jemand es vergisst; --ttl 0 entfernt die Selbstbereinigung. Siehe Abbau.

Pro Agent

Einmaliger Dispatch: sessions ensure && prompt && sessions close, ein verketteter Aufruf. Eine benannte Session pro Aufgabe, ein Prompt, geschlossen, wenn die Ergebnisdatei gelesen wird. Die &&-Kette macht den Abbau mechanisch – nichts räumt offene Datensätze auf, und Waisen entstehen durch nicht verkettete Schließungen – während ein Zug, der mit einem Fehler ungleich Null fehlschlägt (Timeout 3, Berechtigung 5), die Schließung selbst überspringt und die Session für die Wiederherstellung offen lässt (siehe Mit einer laufenden Session sprechen). Ein extern abgebrochener Zug beendet trotzdem mit 0, sodass die Ergebnisdatei, nicht der Exit-Code, die Erfolgsprüfung ist (Invariante 5). Parken Sie keine Session für erwartete Folgeschritte: Der Zustand eines Blockers lebt außerhalb des Gesprächs (Credentials sind maschineneben, Teilergebnisse gehören in die Ergebnisdatei) – antworten Sie mit einer neuen Session, die mit der Kurzbeschreibung plus dieser Datei gefüttert wird. Nacharbeiten – eine Korrektur, Überprüfung oder Verfeinerung der Ausgabe einer Session – erhalten ebenfalls eine neue Session: Ein Agent, der seinen eigenen Kontext erneut liest, übersieht, was frische Augen sehen. Verwenden Sie niemals --no-wait in eine Session, deren Startzeile die Schließung enthält: Der Shutdown des Owners verwirft ausstehende Prompts stillschweigend und bricht den aktiven Zug ab (verifiziert 0.19.4); ein blockierender Prompt vor der Schließung ist sicher. Verwenden Sie exec für eine zustandslose Antwort ohne einen aufzubewahrenden Datensatz (ein Preflight "Reply OK"). Sessions sind nach Agentenbefehl + cwd + Name geschlüsselt; geben Sie jedem parallelen Ausführer seinen eigenen Namen und, wenn er Dateien schreibt, sein eigenes Verzeichnis (idealerweise einen Worktree).

Adapter laufen über npm exec, es sei denn, das Adapter-Binärprogramm (claude-agent-acp, codex-acp) befindet sich im PATH – dann gewinnt diese Kopie gegenüber dem Paket-Fallback, und ein Upgrade von acpx aktualisiert sie nie. Ein frisches HOME pro Job lädt sie neu herunter (jeweils hunderte MB); teilen Sie sich einen npm_config_cache. Unter macOS verbirgt ein frisches HOME auch die Login-Keychain: Der Claude-Adapter schlägt fehl mit RUNTIME: Unable to validate model: Could not resolve authentication method – behalten Sie HOME. Der npx-Cache verwendet auch veraltete Builds wieder – pinnen Sie exakte Adapter-Versionen in ~/.acpx/config.json (agents.<name>.argv). Ein Pin friert ein, welche Modell-IDs funktionieren, und eine Änderung ändert die Session-Schlüssel (siehe Sessions).

Ausführer erben die globalen Anweisungsdateien des Benutzers (Claudes ~/.claude/CLAUDE.md, Codex globales AGENTS.md). Eine Regel wie "vor dem Bearbeiten fragen" beendet einen kopflosen Zug mit einer Frage, ohne dass etwas erledigt wird – beginnen Sie jede Kurzbeschreibung mit "handle jetzt; stoppen Sie nicht, um zu fragen, oder beenden Sie mit einer Frage". Ein Ausführer, der dort liest "verwende einen prozessexternen Ausführer", kann einen verschachtelten acpx-Lane im selben Checkout starten – fügen Sie hinzu "Sie sind der Ausführer; delegieren Sie nicht". Löschen oder benennen Sie die alte Ergebnisdatei vor einem Neustart um (ein Poller liest die veraltete), und geben Sie parallelen Lanes ihre eigenen temporären Pfade und Ports – separate Worktrees isolieren /tmp nicht.

Sie erben auch die Umgebung des Starters, und Codex' zsh liest $ZDOTDIR/.zshenv (Standard ~/.zshenv) für jeden Befehl neu – das Entfernen eines Geheimnisses im Starter hält es nicht fern, und was die Shell ausgibt, landet in den Rollout-Dateien unter ~/.codex/sessions.

AGY / Antigravity

Der integrierte acpx antigravity (0.17.1+) führt agy_acp_server.par vom PATH aus, und die Kopie, die Antigravity unter ~/.local/lib/antigravity-acp/ installiert, ist nicht im PATH – ein bloßes acpx antigravity beendet mit 1 mit Failed to spawn agent command: agy_acp_server.par. Stellen Sie dieses Verzeichnis vor dem PATH ein, setzen Sie agents.antigravity.argv, oder verwenden Sie --agent <path>. Der integrierte gemini-Agent ist die öffentliche Gemini-CLI – ein anderes Produkt. Die .par-Datei stammt aus der Antigravity-Installation oder dem offiziellen ACP-Registry-Archiv; halten Sie sie neben ihrem localharness_external-Helfer aus derselben Version (ein fehlender Helfer protokolliert nur Localharness not found. und macht weiter), oder zeigen Sie mit ANTIGRAVITY_HARNESS_PATH darauf. Weder acpx noch agy update aktualisieren die .par-Datei: Vergleichen Sie ihr --version-Build label: mit dem ACP-Registry und tauschen Sie beide Dateien zusammen aus (der installierte Helfer ist schreibgeschützt – rm -f vor dem Kopieren der neuen).

D=/abs/real/dir                              # muss existieren: Wurzeln werden über realpath aufgelöst
acpx --agent ~/.local/lib/antigravity-acp/agy_acp_server.par \
     --cwd "$D" --model gemini-3.8-flash --approve-all --timeout 1800 \
     exec "Führe $D/brief.md aus. Schreibe deinen Bericht nach $D/report.md."

• --approve-all ist zwingend erforderlich. Ohne wird jeder Schreibvorgang verweigert: Exit 5 (oder ein Stillstand zu Exit 3), mit [done] end_turn trotzdem ausgegeben und keinem Bericht.

• Fixed-Choice-Fragen lassen den Prompt mit Exit 5 fehlschlagen, selbst mit --approve-all (letzte Zeile Antigravity requested a user answer...) – auch für --agent-Starts. acpx lässt jede Fixed-Choice-Frage eines Agenten auf diese Weise scheitern (PERMISSION_PROMPT_UNAVAILABLE); AGY ist, wo es zuschlägt. Schreiben Sie Kurzbeschreibungen, die niemals eine Benutzerauswahl benötigen.

• Verwenden Sie nur IDs, die die ACP-Session bewirbt – ein absichtlich schlechtes --model gibt Available models: aus, ohne einen Zug zu starten (Server 1.4.5: gemini-4-argon, gemini-3.8-flash; die aufwandsbasierten IDs gemini-3.7-flash-{low,medium,high} sind verschwunden). agy models ist eine andere Liste. Flash eignet sich für kriteriengesteuerte Massenarbeit und ist viel schneller, übersieht aber echte Ergebnisse bei Überprüfungs-/Fehlersucharbeit; verwenden Sie dort ein stärkeres Modell.

• AGY liest Geschwisterdateien unaufgefordert – Agenten, die ein Verzeichnis gemeinsam nutzen, reproduzieren die Ausgabe des anderen. Ein Verzeichnis pro Agent, und überprüfen Sie jede erneute Ausführung durch Prüfsumme, bevor Sie einer Übereinstimmungszahl glauben.

• Authentifizierung: benötigt auth.type in <GEMINI_HOME>/antigravity-acp/settings.json (einmalig):

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

  Ohne: sofortiges [error] RUNTIME: Authentication required (Exit 1). Damit, aber nie angemeldet: session/new blockiert bei einer Browser-Anmeldung bis zum --timeout (Exit 3) – melden Sie sich einmal interaktiv an. Das Server-Credential ist getrennt von dem der agy-CLI: die macOS-Keychain (Dienst gemini, Account antigravity-acp), oder <GEMINI_HOME>/antigravity-acp/acp_token.json außerhalb von macOS oder mit AGY_ACP_FORCE_FILE_STORAGE=1. GEMINI_HOME allein isoliert das macOS-Credential nicht. Ein Berechtigungsproblem ist serverseitig – "beheben" Sie es nicht, indem Sie zu gemini-api-key oder einem GCP-Projekt wechseln (separate Abrechnung, keine Fehlerbehebungen).

• Übergeben Sie niemals einen Positionsagenten mit --agent – Exit 2.

• Verifizierungsaufforderungen: fordern Sie eine bloße Antwort und lesen Sie das gesamte Log. AGY leitet Antworten in gehirnartige Artefaktdateien um, sodass ein tail nicht zwischen "keine Tools" und "anderswo beantwortet" unterscheiden kann. Fügen Sie "Erstelle keine Dateien" hinzu.

• AGY versteckt MCP-Fehler hinter einem erfolgreich aussehenden Zug – Exit 0, [done] end_turn, und die gesamte Antwort ist Der MCP-Server '<name>' konnte nicht initialisiert werden: .... Grepen Sie nach failed to initialize.

• Bevorzugen Sie exec. Es wurde berichtet, dass ein Server-Absturz während eines Checkpoints ein gespeichertes Gespräch dauerhaft beschädigt (could not find doneCh for checkpoint); die einzige berichtete Wiederherstellung ist das Löschen von ~/.gemini/antigravity-acp/conversations/<id>.db.

Linux / NixOS

Der integrierte Agent fügt das erforderliche --uid= selbst hinzu. NixOS benötigt zusätzlich ein CA-Bundle, also zeigen Sie mit --agent (oder agents.antigravity.argv) auf einen 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= "$@"

Ohne SSL_CERT_FILE hat das eingebettete OpenSSL der .par-Datei keine gültigen CA-Pfade; sein lokaler Proxy meldet 502 Bad Gateway: Failed to connect to backend API und der Zug endet trotzdem mit [done] end_turn und Exit 0 (Invariante 5). Das echte CERTIFICATE_VERIFY_FAILED erscheint nur unter --alsologtostderr.

Codex

D=/abs/dir
acpx --cwd "$D" codex sessions ensure --name work            # idempotent; -s kann nicht erstellen
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 'Führe ./brief.md aus. Schreibe deinen Bericht nach ./report.md.' && \
  acpx --cwd "$D" codex sessions close work; } > run.log 2>&1 &
# Ein fehlgeschlagener Zug überspringt die Schließung – erneutes Prompten mit -s work zur Wiederherstellung, dann selbst schließen

Einmaliger Dispatch: --model <id> exec --config-option reasoning_effort=low setzt Modell und Aufwand inline.

• Der Codex-Adapter (@agentclientprotocol/codex-acp) schwebt auf ^1.1.5 – das Verhalten kann sich ohne ein acpx-Upgrade ändern, aber das brechende 2.x ist außer Reichweite. Ein veralteter Adapter lehnt neuere Modell-IDs ab: [error] RUNTIME: Invalid params bei session/set_config_option (Exit 1), oder ein 400 model is not supported, das trotzdem [done] end_turn, Exit 0, endet. Pinnen Sie eine aktuelle: {"agents":{"codex":{"argv":["npx","-y","@agentclientprotocol/[email protected]"]}}}. Ein exakter Pin lässt immer noch das Codex-Binärprogramm darin schweben (2.5.0 hängt von @openai/codex ^0.165.0 ab). Die gleichen Symptome treten bei einem aktuellen Adapter auf, wenn dem Konto das Modell fehlt: Die beworbene Liste variiert pro Konto – Preflight unter dem eigenen Login des Lanes.
• Der Inhaltsfilter von OpenAI tötet harmlose Züge, die sauber enden ([done] end_turn, Exit 0). Vokabular wie Rennen / Sweep / Exploit / Angriff in einem Dateinamen, Kommentar oder Prompt löst es aus. Lesen Sie das Ende des Transkripts, bevor Sie den Abschluss glauben; stellen Sie wieder her, indem Sie denselben -s <name> erneut auffordern (der Kontext überlebt, es sei denn, die Verbindung wird unterbrochen – acpx fällt dann stillschweigend auf session/new zurück) mit der Aufforderung, den fehlgeschlagenen Schritt zu wiederholen. Der Standardbrief bei Nichtübereinstimmung kann den Filter ebenfalls auslösen – erwägen Sie, ~/.codex/AGENTS.md während der Ausführung zu verschieben.
• --suppress-reads muss gesetzt werden, um Codex-Lesevorgänge als Lesevorgänge an acpx zu senden (andernfalls sendet der Standard-Read-Handler read, der einen Berechtigungsdialog auslöst). Brechende Stille: Ohne das Flag wird jeder Dateilesebefehl zur Genehmigung angehalten – der Zug stoppt mit Exit 5 (oder Timeout Exit 3). Verwenden Sie es zusammen mit --approve-all (nicht stattdessen): Die Genehmigung wird auf Kosten von Zeit durchgesetzt – etwa 2s pro Lesebefehl bei --approve-all, die ohne das Lesen bei einem anderen Prompt hätte vermieden werden können, der die Datei zuerst liest.
• Jeder erfolgreiche Datensatz, der nicht geschlossen wird, steht auf der Karte und verliert seine Verbindung zu Ihrer Überprüfung. Andersherum: Wenn Sie eine laufende Hintergrund-Session mit -s <name> beobachten, steckt Ihr Beobachter den Queue-Owner (das Arbeitsverzeichnis) fest, und sessions close von innerhalb der Subshell schließt die Session, wenn der Zug endet – die Ausgabe von stdout/stderr wird zusammengeführt, und wait fängt den Exit-Code auf.
• Ergebnisdateien, die vor dem Schließen gelesen werden, können unvollständig sein. Codex schreibt, wann immer es kann, aber sein MCP-Ausgangspuffer kann zurückbleiben. Erwägen Sie einen abschließenden Lesebefehl mit der Aufforderung, die Datei zu lesen und, wenn vollständig, explizit zu signalisieren ("Antworte READY"), sodass die Ausgabe von Codex dem Lesen des Dateisystems vorausgeht.

Claude

D=/abs/dir
acpx --cwd "$D" claude sessions ensure --name work
acpx --cwd "$D" --model claude-sonnet-5-20250505 --approve-all --timeout 600 --suppress-reads \
     claude -s work 'Führe ./brief.md aus. Schreibe deinen Bericht nach ./report.md.' && \
  acpx --cwd "$D" claude sessions close work

• --model wird standardmäßig ignoriert, es sei denn, es ist erlaubt. Der integrierte --help sagt, dass --model global ist, aber der claude-adapter antwortet mit "flag provided but not defined: --model" (Exit 2), wenn der Anbieter --model nicht annonciert hat. Der Task---help zeigt acpx exec --model <id> an; dieser akzeptiert nur IDs, die der Anbieter annonciert. Wenn acpx exec --model das Flag akzeptiert, ist es erlaubt. Wenn nicht, setzen Sie das Modell im Prompt: "Verwende Claude Sonnet 5 für jeden Schritt" (Claude gehorcht normalerweise). Eine andere Möglichkeit ist, Modellhints in der Kurzbeschreibung zu platzieren (wie oben).
• Der Claude-Adapter unterstützt kein INITIAL_AGENT_MODE – verwenden Sie stattdessen ~/.claude/CLAUDE.md oder die Projekteinstellungen.
• Keine automatische Wiederherstellung nach einem Inhaltssicherheits-Kill – er endet wie ein Content-Filter-Kill: der Zug endet sauber mit [done] end_turn, Exit 0, und die Antwort ist I apologize, but I cannot... (oder etwas Ähnliches). Verwenden Sie einen bestimmten Prompt, um dies zu erkennen, z. B. Durchsuchen Sie das letzte [text]-Ereignis im Log auf apologize.
• Die max_tokens-Begrenzung von Claude scheint nicht mehr über das Flag --ollama-context-length zugänglich zu sein – zumindest nicht beim claude-adapter. Standardmäßig wird ein kleiner Kontext verwendet; erwägen Sie, die Kurzbeschreibung nach der Ausgabe in eine Datei aufzuteilen, um das Problem zu umgehen.

Agy / Antigravity zusammenführen

Manchmal möchten Sie die Ergebnisse einer agy-Analyse in eine bestehende ACP-Konversation integrieren, z. B. wenn ein codex-Agent eine agy-Ausgabe als Kontext benötigt. Verwenden Sie den acpx, um eine agy-Sitzung auszuführen, und lesen Sie die Ausgabe aus der Datei. Dann übergeben Sie diese Ausgabe an den codex-Agenten als Teil des Prompts.

Fehlerbehandlung

Exit-Codes

• 0: Erfolg (sauberer Zug, oder Zug wurde abgebrochen, aber die API antwortet trotzdem mit Erfolg). Überprüfen Sie das Log, um zwischen Erfolg und Abbruch zu unterscheiden.
• 1: Fehler beim Starten des Agenten, Fehler beim Lesen der Konfiguration, Syntaxfehler (unbekanntes Flag).
• 2: Syntaxfehler (bekanntes Flag falsch platziert, fehlender erforderlicher Parameter).
• 3: Zeitüberschreitung (der Zug wurde nicht innerhalb von --timeout Sekunden beendet).
• 4: Session nicht gefunden (-s-Name existiert nicht).
• 5: Berechtigung verweigert (der Agent hat eine Berechtigungsanfrage gestellt, und --deny-all oder der Modus hat sie abgelehnt).
• 6: Interner Fehler (unbekannt).

Wiederherstellung nach einem Fehler

Wenn ein Zug mit einem Fehler beendet wird (Exit != 0 oder Exit 0, aber der Log zeigt einen Abbruch an):

1. Überprüfen Sie den Exit-Code und das Log, um die Fehlerursache zu ermitteln.
2. Wenn die Session noch offen ist (Exit 3 oder 5), starten Sie sie erneut mit demselben -s <name> – der Kontext bleibt erhalten.
3. Wenn die Session geschlossen ist (Exit 1, 2, 4, 6), erstellen Sie eine neue Session mit demselben Namen und geben Sie den gleichen Prompt.
4. Wenn der Fehler durch einen Inhaltsfilter verursacht wurde, überarbeiten Sie den Prompt oder die Eingabedateien, um die auslösenden Begriffe zu vermeiden.
5. Wenn der Fehler durch ein Modellproblem verursacht wurde (z. B. nicht unterstütztes Modell), wechseln Sie zu einem anderen Modell.

Ablaufsteuerung

Zeitüberschreitung (--timeout)

Setzen Sie --timeout auf einen Wert, der für Ihre Aufgabe angemessen ist (z. B. 600s für eine einfache Frage, 3600s für eine komplexe Analyse). Wenn der Zug die Zeitüberschreitung erreicht, wird er mit Exit 3 beendet. Sie können dann die Session erneut starten.

Leerlauf-TTL (--ttl)

Der Standard-TTL beträgt 300s (5 Minuten). Wenn Sie eine Session länger warm halten möchten, setzen Sie --ttl auf einen höheren Wert (z. B. --ttl 3600 für eine Stunde). Wenn Sie die Selbstbereinigung deaktivieren möchten, setzen Sie --ttl 0. Seien Sie vorsichtig: Eine Session ohne TTL bleibt für immer geöffnet, bis Sie sie explizit schließen.

Session beobachten

Verwenden Sie sessions watch --cursor, um die Ausgabe einer laufenden Session live zu verfolgen. Dies ist nützlich für Debugging oder um den Fortschritt zu überwachen.

Session schließen

Verwenden Sie sessions close <name>, um eine Session zu schließen. Wenn Sie die Session nicht schließen, bleibt sie auf der Karte, bis sie den TTL erreicht oder Sie acpx beenden. Verketten Sie sessions close immer in die Startzeile (siehe oben), um Waisen zu vermeiden.

Tipps

• Ergebnisdatei lesen: Verwenden Sie eine einfache Prüfung wie grep -q "Aufgabe abgeschlossen" report.md, um zu überprüfen, ob die Aufgabe erfolgreich war.
• Parallele Ausführung: Geben Sie jedem parallelen Ausführer einen anderen Session-Namen und ein anderes Arbeitsverzeichnis. Verwenden Sie separate Worktrees, wenn Dateien erstellt werden.
• Fehlerbehandlung: Überprüfen Sie immer das Log auf Fehler, auch wenn der Exit-Code 0 ist. Verwenden Sie Jumpboxen, um die Logs nach wichtigen Fehlern zu durchsuchen.
• Konfiguration: Speichern Sie die Konfiguration in ~/.acpx/config.json, um häufig verwendete Einstellungen (wie Modell, Timeout, Agent-Pfade) zu definieren. Dies reduziert die Befehlszeilenlänge.

Siehe auch

• acpx GitHub-Repository
• ACP-Spezifikation
• Claude-Code-Dokumentation
• Codex-Dokumentation