Mode headless

Le mode headless vous permet d’exécuter Qwen Code de manière programmatique depuis des scripts en ligne de commande et des outils d’automatisation, sans aucune interface interactive. Il est idéal pour le scripting, l’automatisation, les pipelines CI/CD et la création d’outils alimentés par l’IA.

Vue d’ensemble

Le mode headless fournit une interface à Qwen Code qui :

• Accepte les prompts via des arguments en ligne de commande ou stdin
• Retourne une sortie structurée (texte ou JSON)
• Prend en charge la redirection de fichiers et les pipes
• Permet les workflows d’automatisation et de scripting
• Fournit des codes de sortie cohérents pour la gestion des erreurs
• Peut reprendre les sessions précédentes limitées au projet actuel pour l’automatisation en plusieurs étapes

Utilisation de base

Prompts directs

Utilisez l’option --prompt (ou -p) pour exécuter en mode headless :

qwen --prompt "What is machine learning?"

Saisie via stdin

Transmettez des données à Qwen Code depuis votre terminal via un pipe :

echo "Explain this code" | qwen

Combinaison avec une saisie par fichier

Lisez des fichiers et traitez-les avec Qwen Code :

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

Reprendre des sessions précédentes (Headless)

Réutilisez le contexte de conversation du projet actuel dans des scripts headless :

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

Personnaliser le prompt principal de la session

Vous pouvez modifier le prompt système principal de la session pour une seule exécution CLI sans modifier les fichiers de mémoire partagée.

Remplacer le prompt système intégré

Utilisez --system-prompt pour remplacer le prompt principal de session intégré à Qwen Code pour l’exécution actuelle :

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

Ajouter des instructions supplémentaires

Utilisez --append-system-prompt pour conserver le prompt intégré et ajouter des instructions supplémentaires pour cette exécution :

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

Vous pouvez combiner les deux options lorsque vous souhaitez un prompt de base personnalisé ainsi qu’une instruction spécifique à l’exécution :

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

Formats de sortie

Qwen Code prend en charge plusieurs formats de sortie pour différents cas d’utilisation :

Sortie texte (par défaut)

Sortie standard lisible par un humain :

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

Format de réponse :

The capital of France is Paris.

Sortie JSON

Retourne des données structurées sous forme de tableau JSON. Tous les messages sont mis en mémoire tampon et affichés ensemble à la fin de la session. Ce format est idéal pour le traitement programmatique et les scripts d’automatisation.

La sortie JSON est un tableau d’objets message. Elle inclut plusieurs types de messages : les messages système (initialisation de la session), les messages assistant (réponses de l’IA) et les messages de résultat (résumé de l’exécution).

Exemple d’utilisation

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

Sortie (à la fin de l’exécution) :

[
  {
    "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": {...}
  }
]

Sortie Stream-JSON

Le format Stream-JSON émet les messages JSON immédiatement au fur et à mesure de leur génération pendant l’exécution, permettant un suivi en temps réel. Ce format utilise du JSON délimité par des lignes, où chaque message est un objet JSON complet sur une seule ligne.

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

Sortie (streaming au fil des événements) :

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

Lorsqu’il est combiné avec --include-partial-messages, des événements de flux supplémentaires sont émis en temps réel (message_start, content_block_delta, etc.) pour les mises à jour d’interface en temps réel.

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

Format d’entrée

Le paramètre --input-format contrôle la manière dont Qwen Code consomme les données depuis l’entrée standard :

• text (par défaut) : Saisie de texte standard depuis stdin ou des arguments en ligne de commande
• stream-json : Protocole de messages JSON via stdin pour une communication bidirectionnelle

Remarque : Le mode d’entrée Stream-json est actuellement en cours de développement et est destiné à l’intégration SDK. Il nécessite que --output-format stream-json soit défini.

Redirection de fichiers

Enregistrez la sortie dans des fichiers ou transmettez-la à d’autres commandes via un pipe :

# 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'

Options de configuration

Principales options en ligne de commande pour l’utilisation en mode headless :

Pour plus de détails sur toutes les options de configuration disponibles, les fichiers de paramètres et les variables d’environnement, consultez le Guide de configuration.

Exemples

Revue de code

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

Générer des messages de commit

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

Documentation d’API

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

Analyse de code par lots

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

Revue de code pour les PR

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

Analyse de logs

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

Génération de notes de version

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

Suivi de l’utilisation des modèles et des outils

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

Mode de retry persistant

Lorsque Qwen Code s’exécute dans des pipelines CI/CD ou en tant que démon en arrière-plan, une brève indisponibilité de l’API (limitation de débit ou surcharge) ne devrait pas interrompre une tâche de plusieurs heures. Le mode de retry persistant permet à Qwen Code de retenter indéfiniment les erreurs API transitoires jusqu’à la récupération du service.

Fonctionnement

• Erreurs transitoires uniquement : Les erreurs HTTP 429 (Rate Limit) et 529 (Overloaded) sont retentées indéfiniment. Les autres erreurs (400, 500, etc.) échouent normalement.
• Backoff exponentiel avec plafond : Les délais de retry augmentent de manière exponentielle mais sont plafonnés à 5 minutes par tentative.
• Keepalive par heartbeat : Pendant les longues attentes, une ligne d’état est affichée sur stderr toutes les 30 secondes pour empêcher les runners CI de tuer le processus en raison d’une inactivité.
• Dégradation gracieuse : Les erreurs non transitoires et le mode interactif restent complètement inchangés.

Activation

Définissez la variable d’environnement QWEN_CODE_UNATTENDED_RETRY sur true ou 1 (correspondance stricte, sensible à la casse) :

export QWEN_CODE_UNATTENDED_RETRY=1

[!important] Le mode de retry persistant nécessite une activation explicite. CI=true seul ne l’active pas — transformer silencieusement un job CI à échec rapide en une attente infinie serait dangereux. Définissez toujours QWEN_CODE_UNATTENDED_RETRY explicitement dans la configuration de votre pipeline.

Exemples

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

Traitement par lots nocturne

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

Démon en arrière-plan

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

Surveillance

Pendant le retry persistant, les messages heartbeat sont affichés sur stderr :

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

Ces messages maintiennent les runners CI actifs et vous permettent de suivre la progression. Ils n’apparaissent pas sur stdout, ce qui garantit que la sortie JSON transmise à d’autres outils reste propre.

Ressources

• Configuration CLI - Guide de configuration complet
• Authentification - Configuration de l’authentification
• Commandes - Référence des commandes interactives
• Tutoriels - Guides d’automatisation étape par étape