出力フォーマット:json / text / stream-json

claude -p の --output-format でスクリプトや CI 上の Claude Code 出力を扱う — 構造化 json の解析、リアルタイムな stream-json イベントストリーム、デフォルトのプレーンテキスト、jq とパイプの実例つき

出力フォーマット:json / text / stream-json

スクリプトや CI/CD、自動化パイプラインで必要なのは「人間が読める」回答だけではなく、プログラムが解析できる構造化データです。Claude Code のヘッドレスモード(claude -p)は --output-format で 3 種類の出力フォーマットを提供し、Claude Code を通常の CLI ツールのようにパイプラインへ組み込めます。

これは Claude Code 自身の機能で、アップストリームには依存しません。Claude Code が公式 API を指していても QCode を指していても、--output-format は同じように動きます。本ページは出力フォーマットに焦点を当てます。ヘッドレスの全引数や CI テンプレートは 自動化と CI/CD を参照してください。


一、3 つのフォーマット早見

フォーマット 引数 出力の形 用途
プレーンテキスト --output-format text(デフォルト) 1 つのプレーンテキストの回答 人間が読む、簡単なパイプ
JSON --output-format json 1 つの構造化 JSON オブジェクト スクリプト解析、コスト/使用量/セッション ID の取得
ストリーミング JSON --output-format stream-json 改行区切りの JSON イベントストリーム リアルタイム進捗、逐次消費、長時間タスク
# text がデフォルトなので、次の 2 行は等価
claude -p "冪等性を一文で説明して"
claude -p "冪等性を一文で説明して" --output-format text

二、text:デフォルトのプレーンテキスト

--output-format を付けないと text になり、標準出力はモデルの最終回答そのものです。そのまま読んだり、簡単なパイプに流したりするのに向いています。

# そのまま読む
claude -p "この関数を async 形式に書き換えて"

# 他のツールへパイプ
claude -p "コミットメッセージ候補を 5 つ生成して" | head -5

# ファイルへ書き出す
claude -p "このリポジトリの README 概要を書いて" > intro.txt

制限:text は「回答」しか返さず、コスト・トークン使用量・セッション ID などのメタデータは取れません。多段タスクでも途中経過と最終結果を区別できません。これらが必要なら jsonstream-json に切り替えます。


三、json:1 つの構造化オブジェクト

--output-format json はタスク完了後1 つの JSON オブジェクトを出力し、最終結果と一連のメタデータフィールドを含みます。スクリプトで最もよく使うフォーマットです。

claude -p "src/ 配下の TODO コメント数を数えて" --output-format json

返るオブジェクトの代表的なフィールド(実際のフィールドは利用中のバージョンの出力に従ってください):

フィールド 意味
result 最終回答のテキスト
total_cost_usd この呼び出しのコスト(USD)
usage トークン使用量(入力 / 出力 / キャッシュなど)
session_id セッション ID。--resume で継続に使える

jq で解析する

json フォーマットは jq と相性抜群です:

# 最終回答だけ取り出す
claude -p "今回の変更を一文でまとめて" --output-format json | jq -r '.result'

# この呼び出しのコストを取り出す
claude -p "auth.py をレビューして" --output-format json | jq '.total_cost_usd'

# 複数フィールドをまとめて取得
claude -p "アーキテクチャを分析して" --output-format json \
  | jq '{cost: .total_cost_usd, session: .session_id, tokens: .usage}'

スクリプトで分岐&コスト集計

#!/usr/bin/env bash
set -euo pipefail

out=$(claude -p "UserService の単体テストを書いて" \
        --output-format json --max-turns 8)

result=$(echo "$out" | jq -r '.result')
cost=$(echo "$out"   | jq -r '.total_cost_usd')
sid=$(echo "$out"    | jq -r '.session_id')

echo "結果:$result"
echo "今回のコスト:\$$cost"
echo "セッション ID:$sid(claude --resume $sid で継続)"

ヒントjson はタスク終了後にオブジェクトを一括で吐き出すため、長時間タスクの間は何も出力されません。進捗をリアルタイムで見たい場合は下記の stream-json を使います。


四、stream-json:リアルタイムのイベントストリーム

--output-format stream-json は実行過程を改行区切りの JSON イベント(NDJSON)に分解し、1 行 1 イベントで即座に書き出します。長時間タスクのリアルタイム進捗、ストリーミング UI、出力を生成しながら消費するパイプラインに向いています。

claude -p "utils ディレクトリ全体をリファクタしてテストを追加して" \
  --output-format stream-json --max-turns 20

出力は次のような形です(各行は独立した JSON。フィールドは実際のバージョンに従う):

{"type":"system","subtype":"init","session_id":"..."}
{"type":"assistant","message":{...}}
{"type":"assistant","message":{...}}
{"type":"result","result":"...","total_cost_usd":0.0123,"usage":{...}}

1 行ずつ消費する

各行は正しい JSON なので、ストリームしながら処理できます:

# 各イベントのタイプをリアルタイムで表示
claude -p "新しい API へ移行して" --output-format stream-json \
  | jq -r '.type'

# 最終イベントが出たときだけ結果とコストを取り出す
claude -p "新しい API へ移行して" --output-format stream-json \
  | jq -r 'select(.type == "result") | "\(.result)\nコスト $\(.total_cost_usd)"'
# while ループで 1 行ずつ処理し、進捗をリアルタイムで返す
claude -p "リポジトリ全体のコードレビュー" --output-format stream-json | \
while IFS= read -r line; do
  type=$(echo "$line" | jq -r '.type')
  case "$type" in
    system) echo "▶ 開始…" ;;
    assistant) echo "… 思考中" ;;
    result) echo "✓ 完了:$(echo "$line" | jq -r '.result')" ;;
  esac
done

json vs stream-jsonjson はタスク終了を待って1 つの完全なオブジェクトを返すため解析が簡単。stream-json は全体を通して複数のイベントをストリームし、リアルタイムなフィードバックができる反面、1 行ずつの解析が必要です。CI では最終結果に json、進捗ログに stream-json を使います。


五、CI / パイプライン実例

GitHub Actions で結果を取得してコメント投稿

- name: Claude レビュー
  env:
    ANTHROPIC_BASE_URL: https://api.qcode.cc/api
    ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
  run: |
    out=$(claude -p "この PR の diff をレビューして問題点を挙げて" \
            --output-format json --max-turns 6 --allowedTools Read,Glob,Grep)
    echo "$out" | jq -r '.result' > review.md
    echo "今回のレビューのコスト \$$(echo "$out" | jq -r '.total_cost_usd')"

コストゲートを設ける(予算超過なら失敗)

out=$(claude -p "リリースノートを生成して" --output-format json)
cost=$(echo "$out" | jq -r '.total_cost_usd')
# awk で浮動小数点比較:0.5 ドルを超えたら CI を失敗させる
awk -v c="$cost" 'BEGIN{ exit (c > 0.5) ? 1 : 0 }' \
  || { echo "コスト \$$cost は予算超過"; exit 1; }
echo "$out" | jq -r '.result'

複数回の呼び出しのコストを合算

total=0
for f in src/*.py; do
  out=$(claude -p "$f に docstring を書いて" --output-format json)
  c=$(echo "$out" | jq -r '.total_cost_usd')
  total=$(awk -v t="$total" -v c="$c" 'BEGIN{ printf "%.4f", t + c }')
done
echo "全ファイルの合計コスト \$$total"

QCode を指す:上記コマンドは公式 API でも QCode でも完全に同じです。ANTHROPIC_BASE_URLhttps://api.qcode.cc/api末尾にスラッシュなしに注意)に、ANTHROPIC_AUTH_TOKEN にあなたの cr_ キーを設定するだけ。CN ユーザーは asia.qcode.cc を使えます。詳しくは 接続先と API フォーマット を参照。


六、よくある落とし穴

  • json は長時間タスク中は無音:終了時に 1 回だけ出力するので、進捗が見えないのは正常。進捗が欲しければ stream-json を。
  • stream-json を一括 jq できない:NDJSON なので、複数オブジェクトは単一の JSON ドキュメントになりません。行ごとの jqjq -c--stream を使い、ストリーム全体に jq '.' を流さないこと。
  • --max-turns を忘れない:自動化ではターン数を制限し、タスクの暴走と課金の暴発を防ぐ。
  • BASE_URL の末尾にスラッシュを付けないhttps://api.qcode.cc/api が正しく、余分な / は誤ったパスを作ります。
  • メタデータフィールドはバージョンで変わる:自分のマシンの claude -p ... --output-format json の実出力を信頼し、まず jq 'keys' で何があるか確認を。

次のステップ

Claude Code をパイプラインに組み込めば、コストは出力にそのまま表示されます —— QCode のプランと料金を見る で、あなたの自動化ボリュームに合うプランを選びましょう。

関連ドキュメント

9router で QCode を使う
ローカルのマルチプロバイダールーター 9router に QCode.cc をカスタムプロバイダーとして追加し、プロバイダー横断のフォールバックと一元管理を実現する
gpt-image-2 画像生成と編集
OpenAI 互換の gpt-image-2 画像生成 + 編集 API:base_url の差し替えだけで利用可能、マルチリージョン、QCode キーで統一請求
画像入力(ビジョン)
Claude Code に画像を渡す:貼り付け・ドラッグ&ドロップ・ファイルパス参照で、スクリーンショット・デザインカンプ・アーキテクチャ図・チャートをモデルに読ませる。QCode.cc のビジョンモデル対応、1 つの API Key が全エンドポイントで使えます。
🚀
QCode を始めよう — Claude Code & Codex
1つのプランで Claude Code と Codex の両方を加速、アジア太平洋低遅延
料金プランを見る → アカウント登録
3人以上のチーム?
企業版:専用ドメイン + サブKey管理 + 封禁保護、¥250/人/月〜
企業版を見る →