claude -p で使う非対話モードのオプション（ヘッドレスモード）

claude -p（または --print）は、Claude Code をスクリプトやパイプラインに組み込むためのフラグです。
レスポンスを標準出力に出力して即座に終了します。
対話セッションを開かずシェルから直接使えるため、CI/CD やシェルスクリプトとの相性が良いのが特徴です。

公式ドキュメントではこのモードを「ヘッドレスモード」と呼んでいます。
以前は “headless mode” という名称でしたが、現在は -p フラグの説明として統合されています。

1. 基本的な使い方

claude -p "このコードのバグを教えて"
Code language: JavaScript (javascript)

プロンプトを引数に渡すだけで、回答がそのまま stdout に出力されます。
パイプとの組み合わせも自然に書けます。

cat error.log | claude -p "このエラーの原因と修正方法を教えて"
Code language: JavaScript (javascript)

ファイルにリダイレクトすることで、ドキュメント生成にも使えます。

claude -p "src/ 内のエクスポート関数のドキュメントを生成して" > docs/api-reference.md
Code language: JavaScript (javascript)

1.1. Git コミットメッセージの自動生成

git diff --staged | claude -p "このdiffに対するコミットメッセージを日本語で書いて" \
  | git commit -F -
Code language: JavaScript (javascript)

1.2. PR のセキュリティレビュー

audit_pr() {
  local pr_number="$1"
  gh pr diff "$pr_number" | claude -p \
    --append-system-prompt "セキュリティエンジニアとして、脆弱性・非安全パターン・コンプライアンス上の問題をレビューしてください。" \
    --output-format json \
    --allowedTools "Read,Grep"
}
audit_pr 123 > security-report.json
Code language: JavaScript (javascript)

1.3. エラーログの自動解析

npm test 2>&1 | claude -p "失敗しているテストの原因と修正方法を教えて"
Code language: JavaScript (javascript)

2. システムプロンプトのカスタマイズ

--append-system-prompt でデフォルトの動作を保ちながら指示を追加できます。
--system-prompt を使うと既存のシステムプロンプトをまるごと置き換えます。

# セキュリティレビュー用にロールを追加する
gh pr diff "$PR_NUMBER" | claude -p \
  --append-system-prompt "あなたはセキュリティエンジニアです。脆弱性と非準拠パターンをレビューしてください。" \
  --output-format json
Code language: PHP (php)

2.1. モデルの指定

claude -p "レビューして" --model opus
claude -p "レビューして" --model claude-sonnet-4-6
Code language: JavaScript (javascript)

エイリアス（sonnet、opus）でも、フルモデル名でも指定できます。過負荷時のフォールバック先を設定することもできます。

claude -p "処理して" --model opus --fallback-model sonnet
Code language: JavaScript (javascript)

2.2. セッションの継続と再開（–continue）

非対話モードでも会話の文脈を引き継げます。
セッションIDを使って複数ステップの処理を組むことも可能です。

# 直近のセッションを続ける
claude -p "前の回答をもう少し詳しく" --continue

# セッションIDを指定して再開
claude -p "追加の修正をして" --resume <session-id>
Code language: PHP (php)

セッションIDを変数に保持してマルチターンの自動処理を組む使い方が公式でも紹介されています。

session_id=$(claude -p "レビューを開始して" --output-format json | jq -r '.session_id')
claude -p --resume "$session_id" "ライブラリのアップデート箇所に絞って"
claude -p --resume "$session_id" "問題点のサマリーを生成して"
Code language: JavaScript (javascript)

セッションを保存したくない場合は --no-session-persistence を付けます。
機密データを含む処理や使い捨てのタスクに向いています。

claude -p "この設定ファイルを解析して" --no-session-persistence
Code language: JavaScript (javascript)

3. ツールの制御と権限（`--permission-mode`）

-p モードでもツール（Bash、Edit など）を使わせることができます。
操作の範囲は --permission-mode や --allowedTools で制御します。

# 編集と読み取りだけ許可
claude -p "README を英語に翻訳して上書きして" \
  --permission-mode acceptEdits \
  --allowedTools "Read,Edit"

# 全権限を許可（隔離済み環境専用）
claude -p "テストを修正して通して" \
  --dangerously-skip-permissions
Code language: PHP (php)

--permission-mode の選択肢は以下のとおりです。

モード	動作
`default`	各操作の前に確認を求める
`acceptEdits`	ファイル編集は自動承認、それ以外は確認
`bypassPermissions`	すべて自動承認
`dontAsk`	確認ダイアログを表示せず、デフォルトの動作で進む
`plan`	操作の計画だけを出力し、実行しない

--allowedTools を使うと、許可するツールをさらに絞り込めます。
読み取り専用で動かしたい場合は "Read,Grep,Glob" のように指定すると安全です。

3.1. MCP サーバーとの組み合わせ

--mcp-config で MCP サーバーの設定を読み込むと、外部ツールとの連携もスクリプトから実行できます。

claude -p "Datadog のアラートを診断して対応手順を出して" \
  --append-system-prompt "あなたは SRE の専門家です。影響範囲を評価し、即時対応の手順を示してください。" \
  --output-format json \
  --allowedTools "Bash,Read,mcp__datadog" \
  --mcp-config monitoring-tools.json
Code language: JavaScript (javascript)

API コストの上限をドル単位で指定できます。
CI での意図しない高額課金を防ぐのに使えます。

4. 出力フォーマットの制御

--output-format で出力形式を切り替えられます。

# デフォルト（プレーンテキスト）
claude -p "要約して" --output-format text

# JSON（メタデータ付きの単一オブジェクト）
claude -p "要約して" --output-format json

# ストリーミングJSON（生成されるたびにチャンクが流れる）
claude -p "要約して" --output-format stream-json
Code language: PHP (php)

JSON フォーマットを選択すると、コスト・所要時間・セッションIDを含む構造化データが返ってきます。

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "duration_ms": 1234,
  "num_turns": 6,
  "result": "レスポンス本文...",
  "session_id": "abc123"
}
Code language: JSON / JSON with Comments (json)

stream-json は jq と組み合わせて特定フィールドだけ取り出す場合に便利です。

result=$(claude -p "コードを生成して" --output-format json)
code=$(echo "$result" | jq -r '.result')
cost=$(echo "$result" | jq -r '.total_cost_usd')
Code language: JavaScript (javascript)

4.1. 構造化出力

--json-schema でレスポンスの形式を JSON スキーマで指定できます。スクリプトで確実にパースしたいときに使います。

claude -p "依存パッケージを列挙して" \
  --json-schema '{"type":"object","properties":{"packages":{"type":"array","items":{"type":"string"}}},"required":["packages"]}'
Code language: JavaScript (javascript)

5. エラー処理とタイムアウト

スクリプトに組み込む場合は終了コードの確認とタイムアウト設定を入れておくと安全です。

if ! claude -p "$prompt" 2>error.log; then
    echo "エラーが発生しました:" >&2
    cat error.log >&2
    exit 1
fi

# 5分でタイムアウト
timeout 300 claude -p "$complex_prompt" || echo "タイムアウトしました"
Code language: PHP (php)

5.1. エージェントのターン数制限

--max-turns でエージェントが実行できる反復回数を制限できます。
デフォルトではヘッドレスモードで最大10ターンです。
CI環境でリソースを管理したいときや、無限ループを防ぎたい場合に設定します。

# 軽いタスクは3ターンで打ち切る
claude -p "コードをレビューして" --max-turns 3

# 複雑なリファクタリングは10ターン許可
claude -p "auth モジュールをリファクタリングして" \
  --max-turns 10 \
  --dangerously-skip-permissions
Code language: PHP (php)

5.2. コスト上限の設定

claude -p "リファクタリングして" --max-budget-usd 0.50
Code language: JavaScript (javascript)

6. codex exec との違い

claude -p と codex exec はどちらも非対話モードですが、設計の目的が異なります。

claude -p は Claude Code のインタラクティブ CLI に -p フラグを付けたものです。
対話セッションと同じ機能をそのままスクリプトから使える、という位置づけです。
codex exec はスクリプトや CI 専用に設計された独立したサブコマンドです。
自動化パイプラインでの使用を前提に、オプション体系が整理されています。

6.1. 使い分けの目安

ケース	向いているツール
ワンライナーやパイプで使いたい	`claude -p`
CI パイプラインに組み込む	どちらも可
セッションを跨いで文脈を引き継ぎたい	`claude -p --resume`
サンドボックスポリシーを細かく制御したい	`codex exec -s`
画像を添付してコード生成したい	`codex exec -i`
MCP サーバーと連携したい	`claude -p --mcp-config`
コスト上限を設定したい	`claude -p --max-budget-usd`

6.2. 権限とサンドボックスの扱い

claude -p は --permission-mode でモードを選び、--dangerously-skip-permissions で全確認をスキップします。
サンドボックスの概念は持っていません。

codex exec は -s / --sandbox でサンドボックスポリシーを細かく制御できます。
read-only、workspace-write、danger-full-access から選択でき、--full-auto が「確認スキップ＋workspace書き込み許可」をまとめて有効にする便利エイリアスになっています。

# claude -p の場合
claude -p "テストを修正して" --permission-mode bypassPermissions

# codex exec の場合（同等）
codex exec --full-auto "テストを修正して"
Code language: PHP (php)

6.3. 出力制御

claude -p は --output-format（text / json / stream-json）と --json-schema で出力を制御します。JSON フォーマットではコストや所要時間のメタデータも含まれます。

codex exec は -o でファイルへの書き出し、--json で JSONL ストリーム出力、--output-schema でスキーマ指定と、それぞれが独立したオプションになっています。

6.4. セッション管理

claude -p は --continue や --resume で既存セッションを引き継ぎ、--no-session-persistence で保存を無効化します。

codex exec は --ephemeral で保存しない使い捨てモード、codex exec resume で再開という構造です。サブコマンドとして分離しているため、スクリプトで resume の前後を明示的に制御しやすい設計になっています。

すでに Claude Code を使っているなら claude -p で十分なケースがほとんどです。CI 環境でサンドボックスを明示的に設定したい場合や、codex のエコシステムに乗りたい場合に codex exec を選ぶのが自然な判断基準です。