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"

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."

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.

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 '.response'
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 '.response'

API-Dokumentation

result=$(cat api/routes.js | qwen -p "Generate OpenAPI spec for these routes" --output-format json)
echo "$result" | jq -r '.response' > 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 '.response' > "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 '.response' > 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 '.response')
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 '.stats.models // {} | to_entries | map(.value.tokens.total) | add // 0')
models_used=$(echo "$result" | jq -r '.stats.models // {} | keys | join(", ") | if . == "" then "none" else . end')
tool_calls=$(echo "$result" | jq -r '.stats.tools.totalCalls // 0')
tools_used=$(echo "$result" | jq -r '.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 '.response' > 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