Skip to Content
BenutzerhandbuchFunktionenHeadless-Modus

Headless-Modus

Der Headless-Modus ermöglicht es dir, Qwen Code programmatisch über Befehlszeilenskripte und Automatisierungstools ohne interaktive Benutzeroberfläche 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
  • Datei-Umleitung und Piping unterstützt
  • Automatisierungs- und Skripting-Workflows ermöglicht
  • Konsistente Exit-Codes für die Fehlerbehandlung bereitstellt
  • Vorherige Sitzungen im Kontext des aktuellen Projekts für mehrstufige Automatisierung fortsetzen kann

Grundlegende Verwendung

Direkte Prompts

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

qwen --prompt "What is machine learning?"

Stdin-Eingabe

Leite Eingaben von deinem Terminal an Qwen Code weiter:

echo "Explain this code" | qwen

Kombination mit Dateieingabe

Lese aus Dateien und verarbeite sie mit Qwen Code:

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

Vorherige Sitzungen fortsetzen (Headless)

Verwende den Konversationskontext des aktuellen Projekts in Headless-Skripten wieder:

# Continue the most recent session for this project and run a new prompt
qwen --continue -p "Run the tests again and summarize failures"
 
# Resume a specific session ID directly (no UI)
qwen --resume 123e4567-e89b-12d3-a456-426614174000 -p "Apply the follow-up refactor"
Note
  • Sitzungsdaten werden als projektbezogene JSONL-Dateien unter ~/.qwen/projects/<sanitized-cwd>/chats gespeichert.
  • Stellt den Konversationsverlauf, Tool-Ausgaben und Chat-Komprimierungs-Checkpoints wieder her, bevor der neue Prompt gesendet wird.

Haupt-Sitzungsprompt anpassen

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

Integrierten Systemprompt überschreiben

Verwende --system-prompt, um den integrierten Hauptsitzungsprompt 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."

Zusätzliche Anweisungen anhängen

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 plus eine laufspezifische Zusatzanweisung benötigst:

qwen -p "Summarize this repository" \
  --system-prompt "You are a migration planner." \
  --append-system-prompt "Return exactly three bullets."
Note
  • --system-prompt gilt nur für die Hauptsitzung des aktuellen Laufs.
  • Geladene Speicher- und Kontextdateien wie QWEN.md werden weiterhin nach --system-prompt angehängt.
  • --append-system-prompt wird nach dem integrierten Prompt und dem geladenen Speicher angewendet und kann zusammen mit --system-prompt verwendet werden.

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 aus 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, sobald sie während der Ausführung auftreten, und ermöglicht so Echtzeit-Monitoring. Dieses Format verwendet zeilengetrenntes JSON, bei dem jede Nachricht ein vollständiges JSON-Objekt in einer einzigen Zeile ist.

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

Ausgabe (Streaming bei Ereigniseintritt):

{"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-Ereignisse in Echtzeit ausgegeben (message_start, content_block_delta usw.), um Echtzeit-UI-Updates zu ermöglichen.

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 verarbeitet:

  • text (Standard): Standard-Texteingabe über stdin oder Befehlszeilenargumente
  • 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 die Einstellung von --output-format stream-json.

Datei-Umleitung

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

# Save to file
qwen -p "Explain Docker" > docker-explanation.txt
qwen -p "Explain Docker" --output-format json > docker-explanation.json
 
# Append to file
qwen -p "Add more details" >> docker-explanation.txt
 
# Pipe to other tools
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 output for real-time processing
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:

OptionBeschreibungBeispiel
--prompt, -pStartet im Headless-Modusqwen -p "query"
--output-format, -oGibt das Ausgabeformat an (text, json, stream-json)qwen -p "query" --output-format json
--input-formatGibt das Eingabeformat an (text, stream-json)qwen --input-format text --output-format stream-json
--include-partial-messagesBindet teilweise Nachrichten in die stream-json-Ausgabe einqwen -p "query" --output-format stream-json --include-partial-messages
--system-promptÜberschreibt den Systemprompt der Hauptsitzung für diesen Laufqwen -p "query" --system-prompt "You are a terse reviewer."
--append-system-promptHängt zusätzliche Anweisungen an den Systemprompt der Hauptsitzung für diesen Lauf anqwen -p "query" --append-system-prompt "Focus on concrete findings."
--debug, -dAktiviert den Debug-Modusqwen -p "query" --debug
--all-files, -aBindet alle Dateien in den Kontext einqwen -p "query" --all-files
--include-directoriesBindet zusätzliche Verzeichnisse einqwen -p "query" --include-directories src,docs
--yolo, -yBestätigt alle Aktionen automatischqwen -p "query" --yolo
--approval-modeLegt den Bestätigungsmodus festqwen -p "query" --approval-mode auto_edit
--continueSetzt die zuletzt genutzte Sitzung für dieses Projekt fortqwen --continue -p "Pick up where we left off"
--resume [sessionId]Setzt eine bestimmte Sitzung fort (oder wählt interaktiv aus)qwen --resume 123e... -p "Finish the refactor"

Vollständige Details zu allen verfügbaren Konfigurationsoptionen, Einstellungsdateien und Umgebungsvariablen findest du im Konfigurationshandbuch.

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 von 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

Ressourcen

Last updated on
FähigkeitenGenehmigungsmodus