Diese Seite ist eine Übersetzung der englischen Dokumentation. Befehle, Bezeichner und Beispiele bleiben unverändert. Runtime 7.24.4 · SDK 2.6.7. Englische Fassung

Headless-CLI (ax-code run) ohne Oberfläche

Status: Aktiv Umfang: aktueller Stand Zuletzt geprüft: 2026-09-22 Verantwortlich: Betreuer der AX Code-Laufzeit

ax-code run ist der einmalige, nicht interaktive Einstiegspunkt für KI-Coding-Agenten und Skripte. Er übermittelt einen einzelnen Prompt, gibt die endgültige Antwort des Assistenten aus und beendet sich — ohne Terminaloberfläche und ohne interaktive Nachfragen. Dieser Leitfaden behandelt die Optionsoberfläche, den Ausgabevertrag, Exitcodes und kopierbare Rezepte für Skripte und CI.

Einen Lauf aufrufen

Es gibt vier Wege, den Prompt zu liefern. sie werden in dieser Reihenfolge zusammengesetzt: --prompt-file, dann -p/--prompt, dann die Positionsnachricht, dann über stdin geleitete Eingabe.

# Positional after -- (safest; flags after -- are never consumed as options)
ax-code run --model qwen -- "Review this change"

# Explicit prompt flag
ax-code run --model qwen --prompt "Review this change"
ax-code run --model qwen -p "Review this change"

# Prompt read from a file (not an attachment)
ax-code run --model qwen --prompt-file ./prompt.txt

# Piped stdin (used as the prompt when no positional/--prompt is given)
printf 'Review this change' | ax-code run --model qwen

Wenn stdin kein TTY ist, wird sein Inhalt an den zusammengesetzten Prompt angehängt, sodass er der ganze Prompt ist, wenn nichts anderes geliefert wird. Der stdin-Leser wartet auf ein ruhiges Fenster von 300 ms, bevor er eine offene Pipe aufgibt. Schreiben Sie den Prompt daher zügig und schließen Sie stdin — oder verwenden Sie --prompt-file für große oder langsam erzeugte Prompts. --prompt-file - liest den Prompt ausdrücklich aus stdin (Verwendungsfehler, wenn stdin ein TTY ist). Das implizite Anhängen von geleitetem stdin läuft für diesen Aufruf nie ein zweites Mal.

-f/--file hängt Dateien an die Nachricht an und ersetzt den Prompt nie. Es ist wiederholbar:

ax-code run --model qwen --file README.md --file src/main.ts -- "Summarize these"

Ein Anhang muss im Projektverzeichnis liegen: Der Server lehnt Anhänge außerhalb davon unabhängig von Berechtigungsregeln ab, daher weist die CLI sie vorab mit einem Verwendungsfehler zurück. Kopieren Sie die Datei ins Projekt oder übergeben Sie ihren Inhalt mit --prompt-file. --add-dir gewährt Tools Zugriff auf zusätzliche Verzeichnisse, ändert diese Regel aber nicht.

MIME-Typen von Anhängen werden aus der Erweiterung abgeleitet: png, jpg, jpeg, gif und webp werden ihrem Typ image/* zugeordnet und pdf dem Typ application/pdf, sodass binäre Anhänge den Server mit ihrem echten Typ erreichen statt als text/plain. Alles andere — einschließlich einer Datei ohne erkannte Erweiterung — wird als text/plain gesendet, und ein Verzeichnisanhang wird als application/x-directory eingeordnet.

Den Lauf steuern

Drei Flags steuern einen Lauf, ohne den Prompttext zu ändern. Alle sind nur in Langform und in Kebab-Schreibweise.

--append-system-prompt TEXT / --append-system-prompt-file PATH

Hängt zusätzlichen Text nach den Systemprompts von Agent und Umgebung an den Systemprompt an — er hängt an und ersetzt den eingebauten Systemprompt nie. Die beiden Formen schließen sich gegenseitig aus. Eine Dateivariante eignet sich für längere Anweisungen. Genau ein abschließender Zeilenumbruch wird entfernt, und ein leerer Text (oder eine unlesbare Datei) ist ein Verwendungsfehler, bevor etwas übermittelt wird.

ax-code run --model qwen --append-system-prompt "Answer in English only" -- "Review this change"

--disallowed-tools a,b

Deaktiviert Tools nach ID für den Lauf (kommagetrennt, wiederholbar). Es wird über beide Servermechanismen angewendet: Ablehnungsregeln der erzeugten Sitzung decken neue Läufe ab, und eine Tools-Zuordnung je Anfrage deckt auch fortgesetzte Läufe --session/--continue ab. Das Ablehnen von bash lehnt auch den Befehl des Tools monitor ab, der über denselben Shell-Starter läuft. Ein Aufruf, der eine Ablehnungsregel trifft, schlägt als Toolfehler fehl und zählt als Ablehnung für den Status eines blockierten Laufs. Unbekannte IDs sind kein Fehler — MCP-Tool-IDs sind dynamisch —, aber im Standardformat gibt jede ID außerhalb des eingebauten Tool-Satzes eine Warnung auf stderr aus (unterdrückt durch --quiet).

ax-code run --model qwen --disallowed-tools bash,write -- "Audit this module without mutating anything"

--add-dir PATH

Gewährt dem Agenten Zugriff auf ein zusätzliches Verzeichnis (wiederholbar): Eine Zulassungsregel external_directory für <resolved-path>/* wird den Berechtigungsregeln der neuen Sitzung hinzugefügt und deckt das Verzeichnis sowie alles darunter ab. Jeder Pfad muss existieren und ein Verzeichnis sein (aufgelöst gegen das cwd des Aufrufers wie --file). Die Regel wird angewendet, wenn die Sitzung erzeugt wird, daher kann sie unter --session/--continue nicht wirken — die CLI gibt --add-dir applies only to new sessions auf stderr aus und fährt fort. sie ändert die Eingrenzung von --file nicht: Anhänge müssen weiterhin im Projektverzeichnis liegen. sie deckt die Datei-Tools ab (read, glob, grep, list, edit, write). Ein Shell-Befehl, der über einen dynamischen Pfad in das Verzeichnis gelangt, löst weiterhin die nur interaktive Nachfrage zum Pfadzugriff aus, die ein Headless-Lauf automatisch ablehnt. Bevorzugen Sie daher die Datei-Tools oder übergeben Sie den Dateiinhalt ausdrücklich.

ax-code run --model qwen --add-dir ../design-docs -- "Read ../design-docs/spec.md and summarize it"

Ein Modell wählen

Listen Sie nutzbare IDs mit ax-code models auf. Übergeben Sie den resultierenden Wert provider/model an --model (-m):

ax-code models            # one "provider/model" ID per line
ax-code models --json     # one JSON document

ax-code models --json gibt ein einzelnes Dokument der Form {"models":[{"id":"provider/model","provider":"...","model":"...","connected":true}]} aus.

Die Familiennamen deepseek, glm und qwen lösen sich auf ihre Flash-Standards auf, daher funktioniert ax-code run --model qwen -- "...", ohne eine volle ID provider/model auszuschreiben. Das Weglassen von --model verwendet den konfigurierten Standard. Der wirksame Agent und das Modell werden auf stderr als > Agent · model ausgegeben.

Ausgabeformate

--format akzeptiert default (der Standard), json, jsonl oder ndjson (jsonl und ndjson sind Aliase für json).

Standard (Text)

Das Standardformat gibt nur den endgültigen Assistententext auf stdout aus. Fortschritt, Toolaktivität und Diagnosen gehen nach stderr, beginnend mit einem Kopf > Agent · model · ses_..., der die Sitzungs-ID enthält, sodass ein Aufrufer mit mehreren Runden mit --session fortsetzen kann, ohne auf --format json zu wechseln (--quiet unterdrückt den Kopf). ANSI-Farben sind deaktiviert, wenn stderr kein TTY ist oder wenn NO_COLOR gesetzt ist (beliebiger Wert), sodass ein geleiteter Lauf nie Escape-Codes ausgibt.

JSON-Strom (--format json)

--format json gibt einen zeilengetrennten JSON-Ereignisstrom (NDJSON) aus — ein JSON-Objekt je Zeile, kein einzelnes JSON-Dokument. Ereignisse umfassen step_start, text, tool_use, reasoning (nur mit --thinking), permission_denied, error und step_finish. Der Strom endet immer mit genau einer Zeile result:

{
  "type": "result",
  "timestamp": 1727000000000,
  "sessionID": "ses_...",
  "status": "completed",
  "text": "...",
  "permissionDenials": 0,
  "usage": { "input": 1200, "output": 80, "reasoning": 0, "cacheRead": 0, "cacheWrite": 0 }
}

status ist completed, blocked oder error. usage trägt nur Tokenzahlen — input, output, reasoning, cacheRead, cacheWrite — und wird ganz weggelassen, wenn die Zahlen unbekannt sind. Es gibt kein Kostenfeld. Wenn ein Lauf vor der Übermittlung fehlschlägt (schlechtes Flag, unbekanntes Modell und Ähnliches), gibt das Stromformat vor dem Beenden eine Zeile aus:

{ "type": "error", "error": { "code": "usage", "message": "..." } }

Das error.code ist eines von:

Exitcodes

Sandbox

--sandbox read-only|workspace-write|full-access wählt den Isolationsmodus (Standard full-access). In Headless-Läufen werden Berechtigungsfragen automatisch abgelehnt und als Ereignisse permission_denied gemeldet, sodass ein Lauf, der eine ihm nicht erlaubte Schreiboperation braucht, blocked meldet und mit 3 endet. Das gilt auch für Subagenten: Fragen in Kindersitzungen, die das Tool task erzeugt, werden ebenso abgelehnt, und ihre Ereignisse permission_denied tragen das Kinder-sessionID. Toolaufrufe, die eine Berechtigungsablehnung (zum Beispiel aus --disallowed-tools) oder die Nur-Lese-Sandbox zurückweist, zählen ebenfalls als Ablehnungen. Die interaktiven Tools question und plan_exit sind in einem Headless-Lauf immer deaktiviert, auch in fortgesetzten Sitzungen. Verwenden Sie read-only nur, wenn keine Mutation erwartet wird. workspace-write hält Schreibvorgänge im Projekt.

Unter --attach wird das Flag außerdem als Isolationsrichtlinie je Anfrage in jedem Promptkörper gesendet. Der Server wendet das Strengere aus eigenem Modus und angeforderter Richtlinie an und kann daher nur verschärfen. Dieselbe Richtlinie je Anfrage wird für lokal betriebene Server gesendet, damit das Verhalten einheitlich bleibt.

Strukturierte Ausgabe

-o/--output-file <path> schreibt den endgültigen Assistententext in eine Datei. --output-schema <file> validiert den endgültigen Text als JSON gegen eine JSON-Schema-Datei. Eine Abweichung wird als Ereignis error mit result.status error gemeldet, und der Prozess endet mit

1. Die Schemadatei wird vor dem Modelllauf vorgeprüft — ein unlesbares, nicht parsebares oder kein Objekt bildendes Schema ist ein Verwendungsfehler, bevor etwas übermittelt wird. Bei Erfolg wird das geparste Schema außerdem als Ausgabeformat json_schema des Laufs an das Modell gesendet, und der Server versucht eine ungültige Antwort bis zu zweimal erneut, bevor die eigene Endvalidierung der CLI als Rückhalt läuft. Die endgültige Ausgabe ist das serialisierte strukturierte Objekt (eine Zeile JSON): das ist es, was stdout, --output-file und result.text tragen:

ax-code run --model qwen --output-schema ./answer.schema.json -- "Return a JSON object with a summary field"

Sitzungen und Fortsetzen

• -c/--continue — die jüngste Sitzung fortsetzen.
• -s/--session <id> — eine bestimmte Sitzung nach ID fortsetzen.
• --fork — die Sitzung vor dem Fortsetzen forken (verlangt --continue oder --session).
• --show-history — die sichtbare Sitzungshistorie beim Fortsetzen ausgeben (verlangt --continue oder --session).
• --attach <url> — an einen bereits laufenden Server anbinden, statt einen zu starten; kombinieren Sie das mit --dir, um ein Projektverzeichnis auf diesem Server zu wählen. Ein mit AX_CODE_SERVER_PASSWORD geschützter Server nimmt --password entgegen (oder dieselbe Variable auf der Aufruferseite). Eine verwaltete Laufzeit nimmt ihr Token aus AX_CODE_RUNTIME_TOKEN.
• --runtime — an die verwaltete Laufzeit des Projektverzeichnisses anbinden (--dir oder das cwd des Aufrufers), die mit ax-code runtime start gestartet wurde, und URL sowie Token aus dem privaten Laufzeitdatensatz auflösen. Ohne laufende Laufzeit schlägt der Lauf vor jeder Anfrage mit dem Fehlercode attach und einer Meldung fehl, die den Startbefehl nennt. --runtime und --attach schließen sich gegenseitig aus.

Rezepte

Einmalig

ax-code run --model qwen -- "Fix the failing test in src/parser.ts"

Einen Lauf mit einer Zeitgrenze begrenzen

ax-code run --timeout 120 --model qwen -- "Fix the failing test in src/parser.ts"

--timeout <seconds> bricht den Lauf auf dem Server ab und endet mit 124 (result.status ist timeout), wenn der Lauf die Grenze überdauert, sodass ein hängender Agent einen CI-Job nicht unbegrenzt offen halten kann. Die Grenze deckt den gesamten Aufruf ab — sie wird vor dem ersten Serveraufruf scharfgeschaltet, sodass selbst ein unerreichbarer Host --attach oder ein hängender Start rechtzeitig endet (in diesem frühen Fall trägt die Ergebniszeile ein leeres sessionID).

Auf Hintergrund-Subagenten warten

ax-code run --await-background 300 --timeout 360 --model qwen -- \
  "Delegate the independent checks, then integrate their results"

--await-background <seconds> hält diesen Aufruf für Hintergrundkinder task offen, die seine Sitzung erzeugt, sowie für die Folgerunden des Elternteils, die deren Ergebnisse auslösen. Es ist optional und auf 3600 Sekunden begrenzt. Die endgültige Antwort und das JSON-result.text stammen aus der zuletzt abgeschlossenen Elternrunde. Wenn die Kinder oder ihre Folge nicht innerhalb der Wartegrenze zur Ruhe kommen, meldet der Lauf einen Fehler und endet mit 1. --timeout bleibt die Gesamtgrenze. Geplante Projektaufgaben laufen in getrennten Sitzungen und gehören nicht zu dieser Wartezeit. Dieser einmalige Befehl beansprucht keine fälligen Projektpläne. Ein dauerhaftes Backend besitzt deren Versand.

Den JSON-Strom auswerten

result=$(ax-code run --format json --model qwen -- "..." | tail -n 1)
echo "$result" | jq -r '.status'
echo "$result" | jq -r '.text'

Die Zeile result ist immer die letzte Zeile, daher isoliert tail -n 1 sie auch dann, wenn der Strom früh endet.

Nur-Lese-Prüfung

ax-code run --sandbox read-only --model qwen -- "Review this diff for bugs"

Strukturierte JSON-Ausgabe mit einem Schema

cat > answer.schema.json <<'JSON'
{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}
JSON
ax-code run --model qwen --output-schema answer.schema.json --output-file answer.json \
  -- "Return JSON with a one-sentence summary"

Eine Sitzung fortsetzen

# Start a session and note the sessionID from the result line
ax-code run --format json --model qwen -- "Draft the outline" | tail -n 1

# Continue it
ax-code run --model qwen --session ses_... -- "Now write section 2"

Eine Datei anhängen

ax-code run --model qwen --file docs/spec.md -- "Summarize the attached spec"

Maschinenlesbare Befehle

ax-code run --format json gibt einen zeilengetrennten Ereignisstrom aus (siehe JSON-Strom). Es ist die einzige Oberfläche von --json, die streamt. Jeder andere Nur-Lese-Befehl, der ein Flag --json trägt, folgt einem strengeren Vertrag: Bei Erfolg schreibt er genau ein JSON-Dokument nach stdout, und bei einem Fehler bleibt stdout leer, während ein einzelnes Dokument {"error":{"code","message"}} nach stderr geht und der Exitcode 1 ist.

Befehle mit --json:

• ax-code session list --json
• ax-code models --json
• ax-code providers list --json
• ax-code agent list --json
• ax-code mcp list --json
• ax-code mcp auth list --json
• ax-code stats --json
• ax-code context --json
• ax-code memory status --json
• ax-code memory list --json
• ax-code task list --json / ax-code task show <taskID> --json
• ax-code schedule list --json / ax-code schedule show <taskID> --json
• ax-code runtime list --json / ax-code runtime status --json
• ax-code doctor --json
• ax-code risk <sessionID> --json
• ax-code wiki status --json
• ax-code workflow list --json / ax-code workflow status <runID> --json

ax-code runtime status gibt sein JSON-Dokument bedingungslos aus — das Flag --json wird der Einheitlichkeit halber akzeptiert, die Statusaktion gibt aber immer JSON auf stdout aus.

ax-code aus einem anderen Agenten aufrufen

Wenn Sie ax-code run aus einem Skript, einem CI-Schritt oder einem anderen Agenten einhüllen:

• Verwenden Sie --format json und lesen Sie die letzte Zeile — der Datensatz result ist immer die letzte Zeile, auch wenn der Strom früh endet.
• Entnehmen Sie sessionID aus dieser Ergebniszeile für jede Folgerunde und geben Sie es mit --session zurück.
• Verwenden Sie --continue nie von gleichzeitigen Aufrufern — es setzt die jüngste Sitzung fort, was kollidiert, wenn mehrere Aufrufer aktiv sind. Übergeben Sie stattdessen eine ausdrückliche ID --session.
• Übergeben Sie ein ausdrückliches --model, damit der Lauf nicht von einem veränderlichen konfigurierten Standard abhängt.
• Übergeben Sie immer --timeout, damit ein hängender Agent den Aufrufer nicht offen halten kann.
• Schließen Sie stdin oder verwenden Sie --prompt-file / --prompt-file -: Der implizite Pipe-Leser gibt nach einem ruhigen Fenster von 300 ms auf und schneidet eine langsame Pipe stillschweigend ab.
• Setzen Sie NO_COLOR=1 oder verlassen Sie sich auf die Erkennung eines Nicht-TTY, damit ein geleiteter Lauf nie ANSI-Escape-Codes ausgibt.
• Führen Sie den Befehl aus dem Projektverzeichnis aus: Ein Home-Verzeichnis oder ein Elternverzeichnis mehrerer Repositories wird im nicht interaktiven Modus abgelehnt. Setzen Sie AX_CODE_ALLOW_BROAD_DIR=1, um diese Sperre zu überschreiben.
• Verwendungsfehler geben auf stdout nichts aus (Hilfe und der einzeilige Fehler gehen nach stderr), sodass ein falsch geschriebener Befehl stdout leer lässt und mit Exitcode 1 endet. Unter --format json wird der Verwendungsfehler außerdem als eine Zeile error auf stdout geschrieben.
• Ein Signal, das eintrifft, während der Prozess noch lädt und bevor der Befehl run aktiv ist, beendet den Prozess mit Exitcode 130 und ohne Ausgabe. Sobald der Befehl aktiv ist, erzeugen SIGINT und SIGTERM immer die einzelne abschließende Zeile result mit dem Status cancelled.