ヘッドレスモード

ヘッドレスモードを使用すると、対話的なUIなしにコマンドラインスクリプトや自動化ツールからQwen Codeをプログラム的に実行できます。これはスクリプティング、自動化、CI/CDパイプライン、およびAI駆動のツール構築に最適です。

概要

ヘッドレスモードは、Qwen Codeに対するヘッドレスインターフェースを提供し、以下のような機能を備えています：

コマンドライン引数または標準入力経由でプロンプトを受け入れる
構造化された出力（テキストまたはJSON）を返す
ファイルリダイレクトとパイピングをサポートする
自動化およびスクリプティングワークフローを有効にする
エラーハンドリング用に一貫した終了コードを提供する
複数ステップの自動化のために現在のプロジェクトにスコープされた以前のセッションを再開できる

基本的な使用方法

直接プロンプト

--prompt（または-p）フラグを使用してヘッドレスモードで実行します：


qwen --prompt "機械学習とは何ですか？"

標準入力からの入力

ターミナルからQwen Codeへ入力をパイプします：


echo "このコードを説明してください" | qwen

ファイル入力との組み合わせ

ファイルから読み込んで Qwen Code で処理する:


cat README.md | qwen --prompt "このドキュメントを要約してください"

前回のセッションを再開（ヘッドレス）

現在のプロジェクトから会話コンテキストを再利用してヘッドレススクリプトを実行:


 
# このプロジェクトの最も最近のセッションを継続して、新しいプロンプトを実行
qwen --continue -p "テストを再度実行し、失敗を要約してください"
 
# 特定のセッションIDを直接再開（UIなし）
qwen --resume 123e4567-e89b-12d3-a456-426614174000 -p "後続のリファクタリングを適用してください"

Note

セッションデータは ~/.qwen/projects/<sanitized-cwd>/chats 配下のプロジェクトスコープなJSONL形式で保存されます。
新しいプロンプトを送信する前に、会話履歴、ツール出力、チャット圧縮チェックポイントを復元します。

出力フォーマット

Qwen Code は異なるユースケースに対応する複数の出力フォーマットをサポートしています:

テキスト出力（デフォルト）

標準の人が読める形式での出力:


qwen -p "フランスの首都はどこですか？"

レスポンス形式:


フランスの首都はパリです。

JSON 出力

構造化されたデータを JSON 配列として返します。すべてのメッセージはバッファリングされ、セッションが完了した時点でまとめて出力されます。この形式は、プログラムによる処理や自動化スクリプトに最適です。

JSON 出力はメッセージオブジェクトの配列です。出力には複数のメッセージタイプが含まれます: システムメッセージ（セッション初期化）、アシスタントメッセージ（AI の応答）、および結果メッセージ（実行サマリ）。

使用例


qwen -p "フランスの首都はどこですか？" --output-format json

出力（実行終了時）:


[
  {
    "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": "フランスの首都はパリです。"
        }
      ],
      "usage": {...}
    },
    "parent_tool_use_id": null
  },
  {
    "type": "result",
    "subtype": "success",
    "uuid": "...",
    "session_id": "...",
    "is_error": false,
    "duration_ms": 1234,
    "result": "フランスの首都はパリです。",
    "usage": {...}
  }
]

Stream-JSON 出力

Stream-JSON 形式は、実行中に発生するイベントごとに即座に JSON メッセージを出力し、リアルタイム監視を可能にします。この形式では、各行が完全な JSON オブジェクトであるラインデリミットされた JSON を使用します。


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

出力（イベント発生時にストリーミング）:


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

--include-partial-messages と組み合わせると、リアルタイムの UI 更新のために追加のストリームイベント（message_start、content_block_delta など）がリアルタイムに出力されます。


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

入力形式

--input-format パラメータは、Qwen Code が標準入力からどのように入力を取得するかを制御します。

text (デフォルト): 標準入力またはコマンドライン引数からのテキスト入力
stream-json: 双方向通信のための標準入力を介した JSON メッセージプロトコル

注: Stream-json 入力モードは現在開発中であり、SDK 統合を想定しています。これには --output-format stream-json の設定が必要です。

ファイルリダイレクト

出力をファイルに保存したり、他のコマンドにパイプしたりできます。


 
# ファイルに保存
qwen -p "Docker を説明してください" > docker-explanation.txt
qwen -p "Docker を説明してください" --output-format json > docker-explanation.json
 
# ファイルに追記
qwen -p "さらに詳細を追加" >> docker-explanation.txt
 
# 他のツールにパイプ
qwen -p "Kubernetes とは？" --output-format json | jq '.response'
qwen -p "マイクロサービスを説明してください" | wc -w
qwen -p "プログラミング言語を一覧表示" | grep -i "python"

実時間処理のためのストリームJSON出力

qwen -p “Dockerを説明してください” —output-format stream-json | jq ‘.type’ qwen -p “コードを書いてください” —output-format stream-json —include-partial-messages | jq ‘.event.type’

設定オプション

ヘッドレス使用のための主要コマンドラインオプション：

オプション	説明	例
`--prompt`, `-p`	ヘッドレスモードで実行	`qwen -p "query"`
`--output-format`, `-o`	出力形式を指定 (text, json, stream-json)	`qwen -p "query" --output-format json`
`--input-format`	入力形式を指定 (text, stream-json)	`qwen --input-format text --output-format stream-json`
`--include-partial-messages`	stream-json 出力に部分的なメッセージを含める	`qwen -p "query" --output-format stream-json --include-partial-messages`
`--debug`, `-d`	デバッグモードを有効化	`qwen -p "query" --debug`
`--all-files`, `-a`	コンテキストにすべてのファイルを含める	`qwen -p "query" --all-files`
`--include-directories`	追加ディレクトリを含める	`qwen -p "query" --include-directories src,docs`
`--yolo`, `-y`	すべてのアクションを自動承認	`qwen -p "query" --yolo`
`--approval-mode`	承認モードを設定	`qwen -p "query" --approval-mode auto_edit`
`--continue`	このプロジェクトの最新セッションを再開	`qwen --continue -p "Pick up where we left off"`
`--resume [sessionId]`	特定のセッションを再開 (または対話的に選択)	`qwen --resume 123e... -p "Finish the refactor"`

利用可能なすべての設定オプション、設定ファイル、環境変数の詳細については、設定ガイドを参照してください。

例

コードレビュー


cat src/auth.py | qwen -p "この認証コードのセキュリティ問題をレビューしてください" > security-review.txt

コミットメッセージの生成


result=$(git diff --cached | qwen -p "これらの変更に対する簡潔なコミットメッセージを作成してください" --output-format json)
echo "$result" | jq -r '.response'

APIドキュメント


result=$(cat api/routes.js | qwen -p "これらのルート用にOpenAPI仕様を生成してください" --output-format json)
echo "$result" | jq -r '.response' > openapi.json

バッチコード解析


for file in src/*.py; do
    echo "Analyzing $file..."
    result=$(cat "$file" | qwen -p "潜在的なバグを見つけて改善提案をしてください" --output-format json)
    echo "$result" | jq -r '.response' > "reports/$(basename "$file").analysis"
    echo "$(basename "$file") の解析が完了しました" >> reports/progress.log
done

PR コードレビュー


result=$(git diff origin/main...HEAD | qwen -p "これらの変更に含まれるバグ、セキュリティ問題、およびコード品質をレビューしてください" --output-format json)
echo "$result" | jq -r '.response' > pr-review.json

ログ分析


grep "ERROR" /var/log/app.log | tail -20 | qwen -p "これらのエラーを分析し、根本原因と修正方法を提案してください" > error-analysis.txt

リリースノート生成


result=$(git log --oneline v1.0.0..HEAD | qwen -p "これらのコミットからリリースノートを生成してください" --output-format json)
response=$(echo "$result" | jq -r '.response')
echo "$response"
echo "$response" >> CHANGELOG.md

モデルおよびツールの使用状況追跡


result=$(qwen -p "このデータベーススキーマを説明してください" --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 トークン, $tool_calls 回のツール呼び出し ($tools_used) を以下のモデルで使用: $models_used" >> usage.log
echo "$result" | jq -r '.response' > schema-docs.md
echo "最近の使用傾向:"
tail -5 usage.log

リソース

CLI 設定 - 完全な設定ガイド
認証 - 認証のセットアップ
コマンド - 対話型コマンドリファレンス
チュートリアル - ステップバイステップの自動化ガイド