Headless-Modus

Der Headless-Modus ermöglicht es dir, Qwen Code programmatisch über Befehlszeilen-Skripte und Automatisierungstools ohne jegliche interaktive UI auszuführen. Dies ist ideal für Skripting, Automatisierung, CI/CD-Pipelines und die Entwicklung KI-gestützter Tools.

Übersicht

Der Headless-Modus bietet eine Headless-Schnittstelle zu Qwen Code, die:

• Prompts über Befehlszeilenargumente oder stdin akzeptiert
• Strukturierte Ausgaben (Text oder JSON) zurückgibt
• Dateiumleitung und Piping unterstützt
• Automatisierungs- und Skripting-Workflows ermöglicht
• Konsistente Exit-Codes für die Fehlerbehandlung bereitstellt
• Frühere Sitzungen, die auf das aktuelle Projekt beschränkt sind, für die mehrstufige Automatisierung fortsetzen kann

Grundlegende Verwendung

Direkte Prompts

Verwende das --prompt-Flag (oder -p), um im Headless-Modus zu starten:

qwen --prompt "What is machine learning?"

Stdin-Eingabe

Leite Eingaben von deinem Terminal per Pipe an Qwen Code weiter:

echo "Explain this code" | qwen

Kombination mit Dateieingaben

Lese aus Dateien und verarbeite sie mit Qwen Code:

cat README.md | qwen --prompt "Summarize this documentation"

Frühere Sitzungen fortsetzen (Headless)

Wiederverwenden des Konversationskontextes aus dem aktuellen Projekt in Headless-Skripten:

# Setzt die neueste Sitzung für dieses Projekt fort und führt einen neuen Prompt aus
qwen --continue -p "Run the tests again and summarize failures"
 
# Setzt eine bestimmte Sitzungs-ID direkt fort (keine UI)
qwen --resume 123e4567-e89b-12d3-a456-426614174000 -p "Apply the follow-up refactor"

Ein persistentes Ziel ausführen

Der Headless-Modus akzeptiert /goal als vollständigen Prompt. Der Goal-Zustand wird in der Sitzung gespeichert, verwende also --continue oder --resume <sessionId>, um dasselbe Goal von einem späteren Prozess aus zu inspizieren oder zu steuern. Dies erfordert, dass general.chatRecording aktiviert bleibt (Standard).

# Ein Goal erstellen und seinen Worker starten
qwen -p "/goal Finish the release checklist"
 
# Seinen gespeicherten Zustand in derselben Sitzung inspizieren
qwen --continue -p "/goal"

Verwende das gleiche qwen --continue -p "<control>"-Muster für die anderen Operationen:

Ein Goal ist nur so gut wie seine Abschlussbedingung. Siehe Goals, was der Verifier beurteilen kann und was nicht, und verwende qwen -p "/goal-draft <intent>", um das Ziel formulieren zu lassen, bevor du es setzt.

Laufzeitgeplante Goal-Fortsetzungssegmente zählen nicht gegen --max-session-turns, aber echte Benutzer-Prompts schon. Explizite --max-wall-time- und --max-tool-calls-Budgets gelten weiterhin; das Überschreiten eines davon pausiert aktive Goal-Arbeit, bevor der Lauf mit dem budget-spezifischen Fehler beendet wird.

Mit --output-format stream-json gibt jede Goal-Zustandsänderung ein stream_event aus, dessen event.type goal_state ist. Dieses kanonische Zustands-Event wird auch ohne --include-partial-messages ausgegeben. Wenn Partial Messages aktiviert sind, folgt das ältere active_goal-Event als Kompatibilitätsprojektion; Automatisierungen sollten goal_state als maßgeblich betrachten.

Haupt-Sitzungsprompt anpassen

Du kannst den System-Prompt der Hauptsitzung für einen einzelnen CLI-Lauf ändern, ohne gemeinsam genutzte Speicherdateien zu bearbeiten.

Überschreiben des integrierten System-Prompts

Verwende --system-prompt, um den integrierten Hauptsitzungs-Prompt von Qwen Code für den aktuellen Lauf zu ersetzen:

qwen -p "Review this patch" --system-prompt "You are a terse release reviewer. Report only blocking issues."

Anhängen zusätzlicher Anweisungen

Verwende --append-system-prompt, um den integrierten Prompt beizubehalten und zusätzliche Anweisungen für diesen Lauf hinzuzufügen:

qwen -p "Review this patch" --append-system-prompt "Be terse and focus on concrete findings."

Du kannst beide Flags kombinieren, wenn du einen benutzerdefinierten Basis-Prompt zusammen mit einer zusätzlichen laufspezifischen Anweisung verwenden möchtest:

qwen -p "Summarize this repository" \
  --system-prompt "You are a migration planner." \
  --append-system-prompt "Return exactly three bullets."

Wähle einen Ausgabestil

Verwende --output-style, um einen Ausgabestil — integriert oder benutzerdefiniert — für diesen Lauf auszuwählen. Ein Stil ist ein benannter Anweisungsblock, der auf den integrierten Prompt geschichtet wird und verändert, wie die Antwort geschrieben wird — Concise beginnt mit dem Ergebnis und lässt Einleitung und Erzählung weg, Proactive beginnt direkt mit der Arbeit statt Vorschläge zu machen, Explanatory fügt unterwegs kurze Anmerkungen zur Codebasis hinzu. Er überschreibt die Einstellung general.outputStyle; default wählt keinen Stil.

qwen -p "Why does the build fail on Windows?" --output-style Concise

Ausgabeformate

Qwen Code unterstützt mehrere Ausgabeformate für verschiedene Anwendungsfälle:

Textausgabe (Standard)

Standardmäßige, für Menschen lesbare Ausgabe:

qwen -p "What is the capital of France?"

Antwortformat:

The capital of France is Paris.

JSON-Ausgabe

Gibt strukturierte Daten als JSON-Array zurück. Alle Nachrichten werden gepuffert und gemeinsam ausgegeben, wenn die Sitzung abgeschlossen ist. Dieses Format ist ideal für die programmatische Verarbeitung und Automatisierungsskripte.

Die JSON-Ausgabe ist ein Array von Nachrichtenobjekten. Die Ausgabe umfasst mehrere Nachrichtentypen: Systemnachrichten (Sitzungsinitialisierung), Assistant-Nachrichten (KI-Antworten) und Ergebnisnachrichten (Ausführungszusammenfassung).

Beispielverwendung

qwen -p "What is the capital of France?" --output-format json

Ausgabe (am Ende der Ausführung):

[
  {
    "type": "system",
    "subtype": "session_start",
    "uuid": "...",
    "session_id": "...",
    "model": "qwen3-coder-plus",
    ...
  },
  {
    "type": "assistant",
    "uuid": "...",
    "session_id": "...",
    "message": {
      "id": "...",
      "type": "message",
      "role": "assistant",
      "model": "qwen3-coder-plus",
      "content": [
        {
          "type": "text",
          "text": "The capital of France is Paris."
        }
      ],
      "usage": {...}
    },
    "parent_tool_use_id": null
  },
  {
    "type": "result",
    "subtype": "success",
    "uuid": "...",
    "session_id": "...",
    "is_error": false,
    "duration_ms": 1234,
    "result": "The capital of France is Paris.",
    "usage": {...}
  }
]

Stream-JSON-Ausgabe

Das Stream-JSON-Format gibt JSON-Nachrichten sofort aus, wenn sie während der Ausführung auftreten, und ermöglicht so ein Echtzeit-Monitoring. Dieses Format verwendet zeilenbegrenztes JSON, wobei jede Nachricht ein vollständiges JSON-Objekt in einer einzigen Zeile ist.

qwen -p "Explain TypeScript" --output-format stream-json

Ausgabe (Streaming beim Auftreten von Events):

{"type":"system","subtype":"session_start","uuid":"...","session_id":"..."}
{"type":"assistant","uuid":"...","session_id":"...","message":{...}}
{"type":"result","subtype":"success","uuid":"...","session_id":"..."}

In Kombination mit --include-partial-messages werden zusätzliche Stream-Events in Echtzeit (message_start, content_block_delta, etc.) für Echtzeit-UI-Updates ausgegeben.

Für JSON- und Stream-JSON-Ausgabe sind textuelle tool_result.content-Werte nach der JSON-String-Serialisierung auf 65.536 UTF-8 Bytes begrenzt. Übergroße Werte werden als deterministische Kopf-/Ende-Vorschauen ausgegeben. Dieselbe Grenze gilt für persistente Stream-JSON-Sessions, SDK-Transports, Subagent-Tool-Ergebnisse und Dual Output. Der Textmodus gibt weiterhin nur die finale Antwort aus, behält aber intern nur die begrenzte Vorschau. Dieses Limit begrenzt nicht eine gesamte JSON-Session, ein JSONL-Event, eine Tool-Eingabe oder eine Partial-Message.

qwen -p "Write a Python script" --output-format stream-json --include-partial-messages

Eingabeformat

Der Parameter --input-format steuert, wie Qwen Code Eingaben von der Standardeingabe konsumiert:

• text (Standard): Standard-Texteingabe von stdin oder Befehlszeilenargumenten
• stream-json: JSON-Nachrichtenprotokoll über stdin für bidirektionale Kommunikation

Hinweis: Der Stream-JSON-Eingabemodus befindet sich derzeit in der Entwicklung und ist für die SDK-Integration vorgesehen. Er erfordert, dass --output-format stream-json gesetzt ist.

Dateiumleitung

Speichere Ausgaben in Dateien oder leite sie an andere Befehle weiter:

# In Datei speichern
qwen -p "Explain Docker" > docker-explanation.txt
qwen -p "Explain Docker" --output-format json > docker-explanation.json
 
# An Datei anhängen
qwen -p "Add more details" >> docker-explanation.txt
 
# An andere Tools weiterleiten
qwen -p "What is Kubernetes?" --output-format json | jq -r '.[-1].result'
qwen -p "Explain microservices" | wc -w
qwen -p "List programming languages" | grep -i "python"
 
# Stream-JSON-Ausgabe für die Echtzeitverarbeitung
qwen -p "Explain Docker" --output-format stream-json | jq '.type'
qwen -p "Write code" --output-format stream-json --include-partial-messages | jq '.event.type'

Konfigurationsoptionen

Wichtige Befehlszeilenoptionen für die Headless-Nutzung:

Sicherheit bei unbeaufsichtigten Ausführungen

Headless-/CI-Ausführungen in Kombination mit --yolo (oder --approval-mode=yolo) genehmigen jeden Tool-Aufruf automatisch, einschließlich shell, write und edit. --yolo aktiviert keine Sandbox – diese Tools laufen mit den Berechtigungen des Host-Prozesses. Wenn Qwen Code diese Kombination ohne konfigurierte Sandbox erkennt, gibt es beim Start eine einzeilige Warnung auf stderr aus. Unterdrücke die Warnung mit QWEN_CODE_SUPPRESS_YOLO_WARNING=1, sobald du die Kompromisse abgewogen hast.

Budgets auf Ausführungsebene

Qwen Code kann eine unbeaufsichtigte Ausführung abbrechen, wenn einer der folgenden Schwellenwerte überschritten wird. Jeder ist standardmäßig auf -1 (unbegrenzt) gesetzt; das Setzen eines einzigen Wertes reicht aus, um durchgehendes Verhalten zu begrenzen. Sie werden kooperativ gegen denselben AbortController durchgesetzt, der bereits SIGINT trägt, sodass ein Budget-Abbruch einen strukturierten FatalBudgetExceededError (Exit-Code 55) ausgibt – unterscheidbar vom Turn-Cap-Exit-Code 53 und dem SIGINT-Code 130, damit CI-Skripte basierend auf dem Grund verzweigen können.

Geltungsbereich

• --max-tool-calls zählt nur Top-Level-Dispatches. Wenn das Modell das agent-Tool aufruft, zählt der Dispatch als 1; innere Tool-Aufrufe, die vom gestarteten Subagenten ausgeführt werden, werden nicht gezählt. Ein Modell, das Arbeit durch Subagenten leitet, kann unbegrenzte innere Arbeit unter einem kleinen Top-Level-Budget verrichten. Kombiniere es mit --exclude-tools agent, wenn du eine strengere Obergrenze benötigst.
• structured_output ist von --max-tool-calls ausgenommen. Unter --json-schema ist der terminale structured_output-Aufruf des Modells der “Ich bin fertig”-Vertrag, keine echte Arbeit – er wird nicht auf --max-tool-calls angerechnet, sodass eine Fertigstellung am Budget-Rand nicht als False Positive abgebrochen wird. Die Ausnahme ist bedingungslos (einschließlich fehlgeschlagener Ajv-Validierungen), sodass ein Modell, das in einer Retry-Schleife für fehlerhafte Ausgaben feststeckt, nicht durch --max-tool-calls begrenzt wird; kombiniere es mit --max-session-turns oder --max-wall-time, um Retries zu begrenzen.
• structured_output ist nicht von --max-session-turns ausgenommen. Dieser Zähler ist bereits vorhanden und erhöht sich bei jedem Turn, einschließlich des terminalen Vertrags. Setze --max-session-turns auf N+1, wenn du N echte Arbeits-Turns unter --json-schema erlauben möchtest.
• Single-shot vs. --input-format stream-json: Im stream-json-Eingabemodus setzt der Daemon die Budget-Zähler zu Beginn jeder User-Nachricht zurück; das Budget gilt pro Nachricht, nicht pro Prozess.
• qwen serve / ACP-Sessions: Der Daemon-ACP-Session-Pfad berücksichtigt derzeit nicht --max-wall-time / --max-tool-calls aus der settings.json. Diese Budgets gelten nur für Single-Shot-qwen -p-Ausführungen und --input-format stream-json-Sessions. (qwen serve gibt beim Booten die YOLO-no-sandbox-Warnung aus, wenn tools.approvalMode: 'yolo' in den Einstellungen gesetzt ist.)

Empfohlene Kombinationen

• Vertrauenswürdige, isolierte Umgebung (ephemeraler CI-Runner, Container): qwen -p "..." --yolo --max-session-turns N --max-wall-time 10m --output-format json. Lege ein Turn-Budget und ein Echtzeit-Budget fest, damit ein steckengebliebener Agent nicht deine CI-Minuten verbrennt, und erfasse --output-format json für die Nutzung nach dem Lauf / Tool-Call-Auditing.
• Lokaler Rechner oder gemeinsame Infrastruktur: übergib zusätzlich --sandbox (oder setze QWEN_SANDBOX=1), damit shell-/write-/edit-Tools innerhalb des Sandbox-Images laufen.
• Langlaufende CI mit Retry-on-Rate-Limit: kombiniere QWEN_CODE_UNATTENDED_RETRY=1 mit --max-wall-time. Die Retry-Umgebungsvariable hält die Ausführung über vorübergehende 429-/529-Antworten hinweg am Leben; das Echtzeit-Budget stellt sicher, dass ein dauerhaft fehlschlagender Provider den Job nicht unbegrenzt verlängern kann.
• Begrenztes Auditing / Exploration: für reine Leseaufgaben begrenzt --max-tool-calls 25, wie aggressiv das Modell grep / read nutzen kann. Kombiniere es mit --exclude-tools shell,write,edit, um die Begrenzung wirksam zu machen.

Beispiele

Code-Review

cat src/auth.py | qwen -p "Review this authentication code for security issues" > security-review.txt

Commit-Nachrichten generieren

result=$(git diff --cached | qwen -p "Write a concise commit message for these changes" --output-format json)
echo "$result" | jq -r '.[-1].result'

API-Dokumentation

result=$(cat api/routes.js | qwen -p "Generate OpenAPI spec for these routes" --output-format json)
echo "$result" | jq -r '.[-1].result' > openapi.json

Batch-Codeanalyse

for file in src/*.py; do
    echo "Analyzing $file..."
    result=$(cat "$file" | qwen -p "Find potential bugs and suggest improvements" --output-format json)
    echo "$result" | jq -r '.[-1].result' > "reports/$(basename "$file").analysis"
    echo "Completed analysis for $(basename "$file")" >> reports/progress.log
done

PR-Code-Review

result=$(git diff origin/main...HEAD | qwen -p "Review these changes for bugs, security issues, and code quality" --output-format json)
echo "$result" | jq -r '.[-1].result' > pr-review.json

Log-Analyse

grep "ERROR" /var/log/app.log | tail -20 | qwen -p "Analyze these errors and suggest root cause and fixes" > error-analysis.txt

Generierung von Release Notes

result=$(git log --oneline v1.0.0..HEAD | qwen -p "Generate release notes from these commits" --output-format json)
response=$(echo "$result" | jq -r '.[-1].result')
echo "$response"
echo "$response" >> CHANGELOG.md

Tracking der Modell- und Tool-Nutzung

result=$(qwen -p "Explain this database schema" --include-directories db --output-format json)
total_tokens=$(echo "$result" | jq -r '.[-1].stats.models // {} | to_entries | map(.value.tokens.total) | add // 0')
models_used=$(echo "$result" | jq -r '.[-1].stats.models // {} | keys | join(", ") | if . == "" then "none" else . end')
tool_calls=$(echo "$result" | jq -r '.[-1].stats.tools.totalCalls // 0')
tools_used=$(echo "$result" | jq -r '.[-1].stats.tools.byName // {} | keys | join(", ") | if . == "" then "none" else . end')
echo "$(date): $total_tokens tokens, $tool_calls tool calls ($tools_used) used with models: $models_used" >> usage.log
echo "$result" | jq -r '.[-1].result' > schema-docs.md
echo "Recent usage trends:"
tail -5 usage.log

Persistenter Retry-Modus

Wenn Qwen Code in CI/CD-Pipelines oder als Hintergrund-Daemon läuft, sollte ein kurzer API-Ausfall (Rate Limiting oder Überlastung) keine mehrstündige Aufgabe abbrechen. Der persistente Retry-Modus lässt Qwen Code vorübergehende API-Fehler unbegrenzt wiederholen, bis der Dienst sich erholt.

Funktionsweise

• Nur vorübergehende Fehler: HTTP 429 (Rate Limit) und 529 (Overloaded) werden unbegrenzt wiederholt. Andere Fehler (400, 500 usw.) schlagen weiterhin normal fehl.
• Exponentielles Backoff mit Obergrenze: Retry-Verzögerungen wachsen exponentiell, sind aber auf 5 Minuten pro Retry begrenzt.
• Heartbeat-Keepalive: Während langer Wartezeiten wird alle 30 Sekunden eine Statuszeile auf stderr ausgegeben, um zu verhindern, dass CI-Runner den Prozess wegen Inaktivität beenden.
• Graceful Degradation: Nicht-vorübergehende Fehler und der interaktive Modus sind davon völlig unbetroffen.

Aktivierung

Setze die Umgebungsvariable QWEN_CODE_UNATTENDED_RETRY auf true oder 1 (strikte Übereinstimmung, case-sensitive):

export QWEN_CODE_UNATTENDED_RETRY=1

[!important] Der persistente Retry-Modus erfordert ein explizites Opt-in. CI=true allein aktiviert ihn nicht – einen schnell fehlschlagenden CI-Job stillschweigend in einen unendlich wartenden Job zu verwandeln, wäre gefährlich. Setze QWEN_CODE_UNATTENDED_RETRY in deiner Pipeline-Konfiguration immer explizit.

Beispiele

GitHub Actions

- name: Automated code review
  env:
    QWEN_CODE_UNATTENDED_RETRY: '1'
  run: |
    qwen -p "Review all files in src/ for security issues" \
      --output-format json \
      --yolo > review.json

Nächtliche Batch-Verarbeitung

export QWEN_CODE_UNATTENDED_RETRY=1
qwen -p "Migrate all callback-style functions to async/await in src/" --yolo

Hintergrund-Daemon

QWEN_CODE_UNATTENDED_RETRY=1 nohup qwen -p "Audit all dependencies for known CVEs" \
  --output-format json > audit.json 2> audit.log &

Monitoring

Während des persistenten Retrys werden Heartbeat-Nachrichten auf stderr ausgegeben:

[qwen-code] Waiting for API capacity... attempt 3, retry in 45s
[qwen-code] Waiting for API capacity... attempt 3, retry in 15s

Diese Nachrichten halten CI-Runner am Leben und ermöglichen dir die Überwachung des Fortschritts. Sie erscheinen nicht in stdout, sodass an andere Tools weitergeleitete JSON-Ausgaben sauber bleiben.

Ressourcen

• CLI-Konfiguration - Vollständiger Konfigurationsleitfaden
• Authentifizierung - Authentifizierung einrichten
• Befehle - Referenz für interaktive Befehle
• Tutorials - Schritt-für-Schritt-Automatisierungsleitfäden