Claude Codeのheadless（非対話）実行は、claude -pで依頼を渡し、対話画面を開かずに結果を受け取る使い方です。ログの説明や資料の要約を、シェルスクリプトや既存の処理へ組み込めます。自動処理へ接続する際は、実行できたこと、JSONを受け取れたこと、求めた仕事が完成したことを分けて確認します。
この記事は2026年10月28日に確認した公式資料をもとに、編集部が実装の考え方と説明用コードをまとめたものです。掲載例は説明用で、Claude Codeを実際に動かした実測結果ではありません。認証・利用条件・利用中の版は、自分の環境で確認してください。
Claude Codeのheadlessとは
-pは--printと同じく、依頼を非対話で実行するための指定です。人がターミナルで毎回回答を読む使い方から、入力を渡して出力を次の処理へ送る使い方へ広げられます。公式ではCLIに加え、Python・TypeScriptのAgent SDKも案内されています。本記事はCLIのclaude -pを対象にします。
向いている最初の仕事は、正解や合格条件を人が確認できる、小さな読み取り処理です。たとえば公開してよいエラーログを説明させる、短い文書から見出しを抜き出す、といった作業なら、入力と出力を照合できます。原稿を書いてすぐ公開する、外部へ自動送信する、といった連続処理は、受け取った結果の検証を設けてから組み立てます。
利用方法の原典はClaude Codeの非対話実行、各フラグの定義はCLIリファレンスです。インストール済みでも認証が別途必要なため、認証の公式資料も確認してください。
headless実行を小さな入力で始める
最小の形は、依頼を文字列として渡す方法です。以下は、組み込みツールを使わずに短い文章の説明を返すための例です。外部連携を含まない、信頼できる練習フォルダーで試す想定です。
claude -p '「確認済み」と「未確認」の違いを1文で説明してください。' --tools ""--tools ""は組み込みツールを無効にする指定です。ただし、これだけでMCPの道具や起動時に読み込む設定まで全部消えるわけではありません。自分の環境で何が読み込まれるかを、先に確認してください。既存の業務フォルダーで初めて試すより、設定の少ない練習場所から始める方が、結果の原因を追いやすくなります。
ファイルの内容を標準入力から渡すこともできます。次の例は、あらかじめ用意した公開可能な練習ログを読み、説明を別ファイルへ保存する形です。出力先に同名ファイルがあると上書きされるため、実際には毎回の処理IDなどで名前を分けます。
claude -p 'この練習ログから、確認すべき点を3つ挙げてください。' --tools "" < sample-log.txt > explanation-new.txt標準入力の上限は、確認時点の公式資料では10MBです。大きなデータを無理に流すのではなく、必要な範囲を切り出すか、ファイルを読む方式へ切り替えます。また「入力のファイルを送ること」と「端末上のツールを使わせること」は別なので、秘密情報や顧客情報を入力へ混ぜない確認は必要です。
headlessのJSON出力を受け取る
人が読むだけなら既定のtextで十分ですが、プログラムへ渡すなら--output-format jsonを使うと、結果だけでなくセッションIDなどの情報も受け取れます。通常の文章はresultへ、--json-schemaで形式を指定した結果はstructured_outputへ入る点を区別します。
claude -p '入力文を見出し1つと要点の配列にしてください。' --tools "" --output-format json --json-schema '{"type":"object","properties":{"heading":{"type":"string"},"points":{"type":"array","items":{"type":"string"}}},"required":["heading","points"]}' < sample-note.txt > result-new.jsonこの例が定めるのは、headingという文字列とpointsという配列を持つ形です。JSONの形が正しくても、入力にない事実を加えていないか、要点が不足していないかは別に検証します。日付やメールアドレスのような値も、形式名を指定するだけで業務上の正しさまで保証されるわけではありません。
また、正常な構造化結果が出ない場合、structured_output自体がないことがあります。たとえばPythonで受け取る側では、まず終了状態を確認し、JSONとして読めること、必要な項目があること、項目の型と内容が合うことの順に点検します。data["structured_output"]をいきなり読む設計だと、失敗時の原因を見失いやすくなります。
| 出力形式 | 使う場面 | 受け取り側が見るもの |
|---|---|---|
| text | 人が文章を読む | 回答と終了状態 |
| json | 完了後にまとめて処理する | 結果・セッションID・必要な項目 |
| stream-json | 途中経過を表示する | 1行ごとのイベントと最後の結果 |
途中経過が不要なら、最初からstream-jsonのイベント処理を作る必要はありません。必要になったら--verboseなど公式の組み合わせを確認し、最後のresultイベントを受け取ったかまで管理します。途中の文章が一つ届いたことを、仕事の完了として扱わないことが大切です。
headlessのツール許可を必要な範囲へ絞る
--allowedToolsは、指定したツールを手動確認なしで使えるようにする設定です。利用可能な組み込みツールの種類を絞る--toolsとは役割が違います。読み取りだけの仕事なのにBashとEditをまとめて許可すると、仕事に必要な範囲より広くなります。
たとえば、READMEだけの要約を依頼するなら、利用する組み込みツールをReadへ絞り、その利用を許可する設計から検討できます。ただしReadを許可することは特定の一ファイルだけのアクセス制御と同じではなく、設定や作業ディレクトリの範囲も関係します。細かなパス制限は公式の権限設定で確認します。
人が応答しない処理では、承認が必要な操作に出会ったときの扱いも決めます。--permission-prompts noneは、承認が必要になっても人の回答を待たず、その場で許可が得られない操作を拒否するための指定です。何でも許可する指定ではありません。既存のルールやモードなどが先に評価される点も含め、拒否が出たら必要な処理が欠けていないかを結果側で確認してください。
確認時点の公式資料では、v2.1.302以降は、ほかにモード指定がない-p実行はManualで始まるとされています。古い例と動きが違う場合は、利用している版と起動オプションを記録して比べます。確認を省くために権限チェックをすべて無効にする前に、必要なツールを一つずつ確認すると、後から設定を見直しやすくなります。
headlessで--bareを使う前に確認すること
通常の-p実行は、プロジェクトやホームの設定にあるhooks・スキル・プラグイン・MCPなどを読み込む場合があります。対話画面の信頼確認が出ないことは、未知のフォルダー内での実行が安全であることを意味しません。自動処理の再現性を重視する場合、公式は--bareを案内しています。
bareは、こうした自動検出の多くを省き、必要な設定を明示して起動する方法です。ただし「軽い起動オプション」だけとして付け足すと、いつも使うCLAUDE.mdやスキルが読まれないことで、結果の条件が変わります。先に、必要な業務ルール・追加設定・MCPを一覧にし、何をどこから渡すかを決めてください。
認証も重要です。公式資料では、bareはOAuthの資格情報やシステムのキーチェーンを読まず、Anthropic APIの利用にはAPIキー等の対応する認証を用意する必要があると説明されています。普段のサブスクリプションログインを、そのまま使えると想定して無人処理へ追加しないでください。API利用と契約の条件を確認した上で選びます。
最初の実装で確認するのは、「いつもの手元環境を使う処理」なのか「明示した設定だけで再現する処理」なのかです。どちらを選んでも、実行場所と設定を記録し、別の端末で同じ結果になると無条件に決めつけないようにします。
headlessの失敗を次の処理へ流さない
受け取り側では、次の4段階を分けて判定します。これは製品の仕様ではなく、編集部が業務へ組み込む際の確認順として整理したものです。
- プロセスの終了。終了コードを保存し、失敗なら次の処理を止めます。標準エラーだけでなく標準出力にも失敗理由が出る場合があります。
- 結果の構造。JSONとして読めるか、structured_outputなど必要な項目があるかを確認します。
- 内容の合格。入力の件数、必須の項目、引用や計算など、仕事ごとの条件と照合します。
- 外部の結果。公開や登録を別工程で行った場合、実際の保存先で反映を確認します。
利用量や実行の長さを制御するには、--max-turnsや--max-budget-usdも使えます。ただし後者はクライアント側の費用見積もりを基準とするため、厳密な請求上限の保証ではありません。前者も処理が完了したことを保証する指定ではなく、上限到達なら未完了として扱います。
処理を途中で止めた場合や、結果を受け取る接続が切れた場合も注意が必要です。もう一度同じ依頼を送る前に、生成ファイルや外部への反映が済んでいないか確認します。すでに作成された成果物を二重に作ったり、同じ送信を二度行ったりしないよう、処理ごとのIDと結果の保存先を持たせます。
複数のジョブを並行するなら、単に--continueで直前の会話へ戻す方法より、結果から得たセッションIDと仕事のIDを対応させ、--resumeで対象を明示する設計を検討します。再開前には、前のプロセスが本当に終わったかも確認します。
headlessは、入力と合格条件が明確な仕事から始める
まず-pで小さな入力を処理し、必要ならJSONへ進みます。その後、ツールの範囲、認証と設定、失敗の受け取り方をそろえて既存の処理へ接続します。数を増やす前に、正常終了だけでは分からない品質を、入力と成果物で確かめられる状態にしてください。
社内の定型業務へ組み込む場合は、読み取り・下書き・確認・公開のどこを自動化するかを分けると設計しやすくなります。業務に合わせた実行と検収の仕組みは、PLaiのAI社員導入支援でも相談できます。
