メインコンテンツへスキップ
見出し画像

Claude Codeを自動実行する方法|claude -p(ヘッドレス)の使い方・JSON出力・上限の決め方と、Windowsで毎日動かす手順【実機で確認・2026年10月】

    「毎朝、決まった作業を AI にやらせたい」。「別のスクリプトの中から、Claude に聞きたい」。「寝ている間に、まとめて処理させたい」。Claude Code を使い込むと、こんな要望が出てきます。

    その入口が、claude -p です。画面を開かず、1回だけ動かして、結果を返して終わる実行方法で、「ヘッドレス」「非対話モード」とも呼ばれます。この記事では、基本の使い方から、JSON での出力、権限の決め方、暴走の止め方、Windows で毎日動かす手順までを、実際に動かして確かめた結果とあわせて説明します。

    私は Claude Code と Codex を毎日使って、教材づくり、note・Gumroad への出品、画像づくりを自動化しています。私の作業場では、自分で書いた「依頼ボード」に依頼を入れると、claude -p が裏で起動して作業を進めます(同時に動かす数に上限を設け、同じフォルダでは1つずつ動かしています)。また、決まった時刻に動く処理は、Windows のタスクスケジューラに登録しています。

    この記事の内容は、読み物のために書いたものではなく、実際に動かして確かめたものです。Windows 11 の Claude Code(2.1.296)で、出力の形、会話のつなぎ方、上限、終了コード、PowerShell での呼び方を、順に試しました。全文無料です。

    この記事で分かること

    • claude -p とは何か。画面のある使い方との違い

    • 入力(引数・パイプ)と出力(テキスト・JSON・スキーマ指定)

    • 会話をつなぐ方法

    • 確認の画面が出ない中での、権限の決め方

    • 暴走を止める上限(--max-turns・--max-budget-usd)と、終了コード

    • Windows で毎日動かす手順(PowerShell とタスクスケジューラ)

    • 実機でつまずいた所(標準入力の警告、古い版、ほか)

    先に結論

    • claude -p "依頼" は、画面なしで1回だけ動き、結果を標準出力に出して終わります。成功なら終了コード 0、失敗なら 0 以外です

    • --output-format json を付けると、結果のほかに、会話のID(session_id)、費用(total_cost_usd)、ターン数などが機械で読める形で返ります。--json-schema で、答えの形も指定できます

    • 確認の画面は出ません。だから、権限は前もって決めます。--allowedTools で必要な道具を許可し、--permission-mode dontAsk でそれ以外を自動で断る形が、無人の実行の基本です

    • 暴走防止の上限があります。実機で試して、--max-turns も --max-budget-usd も、終了コード 1 で止まり、止まった理由が JSON に出ました。ただし、費用の上限は、少し超えて止まります

    • Windows では、PowerShell から呼び、タスクスケジューラに登録します。標準入力を空で閉じる($null |)のが、つまずかないコツです

    • 実機でつまずいた所:標準入力の警告(3秒待たされる)、古い版の claude が呼ばれていた、Git Bash が / を書き換える、の3つです

    画像

    claude -p とは

    画面のある Claude Code は、あなたと会話しながら進みます。確認の画面も出ます。claude -p(--print)は、その会話を1回で済ませるものです。

    claude -p "このプロジェクトの認証まわりは、何をしていますか?"

    これだけで、答えが標準出力に出て、終わります。公式のドキュメントでは、スクリプトや CI(自動の検査)から使うための方法として説明されています。

    画面のある使い方との違い

    • 確認の画面が出ない:確認が要る操作は、そのまま止まるか、断られます(権限の節で詳しく)

    • 一部のコマンドは使えない:/login のような、画面前提のコマンドは使えません。/model sonnet のように、値を引数で渡せるコマンドは使えます

    • 自分で作ったスキルやコマンドは使える:プロンプトに /スキル名 と書けば、展開されます

    • フォルダの信頼確認が出ない:プロジェクトの許可ルールの一部が効かない原因になります(あとで書きます)

    入力:引数とパイプ

    引数で渡す

    claude -p "1+1は? 数字だけ答えて"

    パイプで渡す

    標準入力から、データを渡せます。ログやエラーを読ませるときに便利です。

    cat build-error.txt | claude -p "このエラーの原因を1文で。"

    実機で、エラーのログ(ModuleNotFoundError: No module named utils)を渡したところ、「utils というモジュールが見つからないため」という説明が返りました。公式のドキュメントでは、パイプで渡せる量の上限は 10MB です。それより大きいものは、ファイルに書いて、そのパスをプロンプトで指定します。

    出力:3つの形

    --output-format で選びます。

    • text(既定):文章だけ

    • json:結果と、メタ情報(会話のID、費用など)をまとめた JSON

    • stream-json:1行ずつの JSON を、動きに合わせて流す(--verbose も付けます)

    json の中身

    claude -p "1+1は? 数字だけ答えて" --output-format json

    実機で返ってきた JSON の主な項目は、次のとおりです。

    • result:答えの文章(このときは 2)

    • is_error:失敗したか(false)

    • subtype:結果の種類(成功なら success)

    • num_turns:ターン数(1)

    • total_cost_usd:費用の見積もり(0.00025 ドル。軽いモデルでの、ごく短い依頼です)

    • session_id:会話のID(次の節で使います)

    • stop_reason・duration_ms・usage・permission_denials など

    公式のドキュメントによると、費用は「クライアント側の見積もり」で、実際の請求とは違うことがあります。目安として使ってください。jq があれば、| jq -r '.result' のように、必要な項目だけ取り出せます。

    答えの形を決める:--json-schema

    決まった形の答えがほしいときは、JSON Schema を渡します。

    claude -p "エラーの種類と、原因のモジュール名を答えて。" \
      --output-format json \
      --json-schema '{"type":"object","properties":{"kind":{"type":"string"},"module":{"type":"string"}},"required":["kind","module"]}'

    実機では、structured_output という項目に、こう入っていました。

    {"kind": "ModuleNotFoundError", "module": "utils"}

    文章ではなく、そのまま次の処理に渡せる形です。ログの分類や、抽出のように、結果を機械で使う場面で役に立ちます。

    会話をつなぐ

    1回で終わる実行でも、前の続きから頼めます。

    • --continue:直前の会話の続き

    • --resume 会話のID:指定した会話の続き

    会話のIDは、json の出力の session_id で分かります。実機で試しました。

    1. 「合言葉は『青いりんご』です。覚えてください」と頼み、session_id を取り出す

    2. --resume にそのIDを付けて、「さっきの合言葉は何でしたか?」と頼む → 「青いりんごです。」

    3. IDを付けずに、同じ質問をする → 「分かりません。この会話の中に合言葉は出てきておらず…」

    つまり、--resume を付けないと、毎回まっさらな会話です。

    逆に、会話を記録に残したくないときは、--no-session-persistence を付けます。実機で、これを付けて作った会話のIDで --resume すると、「No conversation found with session ID…」と言われ、戻れませんでした。

    権限:確認の画面が出ない中での決め方

    画面なしの実行では、確認する人がいません。だから、確認が要る操作は、そのまま断られます。実機でも、書き換えを頼むと、「書き込みの権限が下りていない」と断られ、ファイルは変わりませんでした。

    権限の仕組みは、私の記事「Claude Codeの権限設定(パーミッション)」で詳しく書いています。ここでは、自動実行の形だけをまとめます。

    • 読むだけの仕事:何もしなくても動く(読み取りは確認なし)

    • 決まったコマンドだけ動かす仕事:--allowedTools "Bash(git log *)" のように、必要な道具だけ許可する

    • ファイルを編集させる仕事:--permission-mode acceptEdits

    • それ以外は断りたい:--permission-mode dontAsk(確認が要る操作を、自動で断る)。公式のドキュメントは、「画面のない CI やスクリプト向け」としています

    • 断られたことを AI に伝えたい:--permission-prompts none(v2.1.259 以降)。確認が要る操作は断られ、AI は「誰も承認できないので、やり直さないで」と伝えられます

    claude -p "最近のコミットを3行で要約して" \
      --permission-mode dontAsk \
      --allowedTools "Bash(git log *)" \
      --output-format json

    実機で、--permission-prompts none を付けて書き込みを頼みました。AI には、「承認できる人がいないので、自動で断った。操作は実行されていない。成功したと言わず、やり直さないこと」という趣旨のメッセージが返り、AI は「ファイルは変わっていません」と報告しました。ファイルも、変わりませんでした。

    つまずき:プロジェクトの allow が効かない

    .claude/settings.json(プロジェクトの設定)に allow を書いても、claude -p では効きません。実機で、Bash(python *) を allow に書いたのに、「このコマンドには承認が必要」と断られました。公式のドキュメントによると、プロジェクトの allow は、フォルダを「信頼する」画面で承認してから効く仕組みで、その画面は claude -p では出ないためです。

    直し方は、.claude/settings.local.json(自分用の設定)に書くか、--allowedTools で渡すか、自分の全体の設定に書くことです。最初の2つは実機で動きました。

    暴走を止める:上限と終了コード

    無人の実行で怖いのは、「終わらない」「費用が膨らむ」ことです。2つの上限があります。

    --max-turns:ターン数の上限

    claude -p "build-error.txt を読んで、1行目を答えて。" --allowedTools Read --max-turns 1 --output-format json

    ファイルを読む必要がある依頼なので、1ターンでは終わりません。実機の結果は、こうでした。

    • 終了コード:1

    • subtype:error_max_turns、is_error:true

    • result:なし(答えは出ない)

    --max-budget-usd:費用の上限

    claude -p "1から20までの数を日本語で書いて" --max-budget-usd 0.0001 --output-format json

    上限を 0.0001 ドルにして試しました。

    • 終了コード:1

    • subtype:error_max_budget_usd、terminal_reason:budget_exhausted

    • 実際の費用は、total_cost_usd が 0.0014 ドル。上限を超えていました

    つまり、費用の上限は、ターンの区切りで確認されるので、1ターンの分は超えうるということです。ぴったり止める保証ではなく、「それ以上は続けない」安全弁として使ってください。

    終了コードで失敗を見分ける

    実機で、いくつかの失敗を起こして確かめました。

    • 上限に達した(ターン数、費用):1

    • 存在しないモデルを指定した:1。「選んだモデルに問題がある」というメッセージ

    • 存在しないオプションを付けた:1。error: unknown option '--no-such-flag'

    • ログインしていない(--bare で API キーなし):1。Not logged in · Please run /login

    • 成功:0

    スクリプトでは、終了コードで分岐し、json の is_error と subtype で理由を読みます。なお、SIGTERM(kill など)で止めると、公式のドキュメントでは、終了コードは 143 です。

    --bare:ふだんの設定を読まずに動かす

    --bare を付けると、フック・スキル・サブエージェント・MCP・CLAUDE.md・自動メモリーを、自動では読み込まずに動きます。どの PC でも同じ結果にしたい CI のような場面向けで、公式のドキュメントは、スクリプトからの呼び出しに推奨し、将来 -p の既定になるとしています。

    ただし、--bare では、サブスクリプションのログインを使えません。API キー(ANTHROPIC_API_KEY)が必要です。実機で、API キーなしで試すと、「Not logged in · Please run /login」と言われ、終了コード 1 でした。サブスクで使っている私は、--bare を使っていません。

    逆に、--bare なしの claude -p は、そのフォルダのフックを実行します。公式のドキュメントにも、「信頼していないフォルダでも、プロジェクトの .claude/settings.json のフックが動き、.mcp.json のサーバーに接続する」とあります。知らないリポジトリで claude -p を動かすのは、避けてください。

    Windows で毎日動かす

    PowerShell から呼ぶ

    実機で、PowerShell(5.1)から呼んでつまずいた所を、先に書きます。

    標準入力の警告です。Bash で claude -p を呼ぶと、標準入力が開いたまま空のとき、こう出ます。

    Warning: no stdin data received in 3s, proceeding without it. If piping from a slow command, redirect stdin explicitly: < /dev/null to skip, or wait longer.

    実機では、3秒待たされてから動きました(< /dev/null を付けると、待たされませんでした)。予約の実行では、待ちが毎回入ってしまいます。

    PowerShell では、< が使えません(実機で試すと、The '<' operator is reserved for future use. と出ました)。かわりに、$null | で、空の入力を渡します。

    $null | claude -p "日本語で「こんにちは」とだけ答えて" --model haiku

    実機では、警告なしで動き、こんにちは と返りました。

    出力を、ファイルに保存するときは、文字コードを明示します。

    $null | claude -p "..." --output-format json | Out-File -Encoding utf8 result.json

    私の環境では、> で書き出しても UTF-8(BOM つき)でしたが、Windows PowerShell 5.1 の標準の挙動は環境で違うことがあるので、-Encoding utf8 を付けておくのが安全です。

    スクリプトにする

    C:\work\daily.ps1 のような、1つのファイルにまとめます。

    Set-Location C:\work\myproject
    $stamp = Get-Date -Format "yyyyMMdd"
    $null | claude -p "昨日の変更を3行で要約して" `
      --model haiku `
      --permission-mode dontAsk `
      --allowedTools "Bash(git log *)" `
      --max-turns 5 `
      --max-budget-usd 0.5 `
      --output-format json | Out-File -Encoding utf8 "C:\work\logs\daily_$stamp.json"

    このスクリプトの形を、PowerShell から実際に動かして、結果の JSON が日付つきのファイルに保存されるのを確かめました(試験では、claude をフルパスで指定しました。理由は、このあと書きます)。

    ポイントは、次のとおりです。

    • 作業フォルダを決める(Set-Location):CLAUDE.md や設定は、そこから読まれます

    • 権限・上限・出力の形を、全部書く:無人の実行では、書いていないものが一番の事故のもとです

    • 結果をログに残す:何が起きたかを、あとで見られるように

    タスクスケジューラに登録する

    schtasks コマンドで、毎日 9 時に動かす予約を登録します。

    schtasks /Create /TN "daily-claude" /SC DAILY /ST 09:00 /TR "powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\work\daily.ps1"

    登録のコマンドは、schtasks /Create /? で、オプション(/TN 名前、/SC 頻度、/ST 時刻、/TR 実行するもの)を確かめた形です。この記事のためには、実際には登録していません。登録したら、まず手で schtasks /Run /TN "daily-claude" を実行して、1回動かしてみてください。

    注意点は、次のとおりです。

    • ログインは、PC のユーザーごとに保存されます。Claude Code にログインしたのと同じユーザーで登録します

    • PC が起動していないと、動きません(スリープも)

    • 試すときは、先に --max-turns と --max-budget-usd を小さくしておきます

    Mac や Linux なら、cron に同じコマンドを書きます。

    実機でつまずいた所:古い版が呼ばれていた

    最後に、私が実機で出会った、地味な落とし穴を書きます。

    この記事の検証で、公式のドキュメントにある --permission-prompts none を、ターミナルで claude と打って試しました。すると、error: unknown option '--permission-prompts' と言われました。

    原因は、claude --version が 2.1.81 だったことです。このオプションは、v2.1.259 以降のものです。私の PC には、VS Code の拡張機能に入っている 2.1.296 と、npm で入れた古い 2.1.81 の、2つの claude があり、ターミナルの claude は古いほうでした。拡張機能の 2.1.296 を指定して実行すると、同じオプションが動きました。

    教訓は、2つです。

    • 公式のドキュメントのオプションが動かないときは、まず claude --version

    • 予約の実行では、どの claude が呼ばれるかを確かめる(where.exe claude で場所が分かります)。フルパスで書いてしまうのも手です

    もう1つ、Git Bash(Windows の Bash)から、claude -p "/greet 太郎" のように、スラッシュコマンドを渡すときは、/ で始まる引数が Windows のパスに書き換えられます(実機で、/shell2 が C:/Program Files/Git/shell2 になりました)。MSYS_NO_PATHCONV=1 を付けるか、PowerShell から実行してください(私の記事「Claude Codeのスラッシュコマンド一覧」に詳しく書きました)。

    安全のために

    • 無人の実行は、最小の権限で:dontAsk + 必要な道具だけの --allowedTools。bypassPermissions は、隔離された環境だけ

    • 上限を必ず付ける:--max-turns と --max-budget-usd

    • 試運転をする:初めて予約に載せる前に、同じコマンドを手で実行し、結果と費用を見る

    • ログを残す:json の出力を、日付つきのファイルに保存する

    • 鍵や個人情報を、プロンプトやログに入れない

    • 知らないフォルダでは動かさない:フックや MCP が、確認なしで動く

    • 利用量の枠に注意:自動実行は、画面で使う分と同じ枠を使います。サブスクで使うなら、/usage で、枠の残りを時々見てください

    よくある疑問

    Q. サブスクリプション(月額)のままで、claude -p は使えますか?

    実機では、サブスクのログインのまま、動きました。ただし、--bare は API キーが要るので、使えません。利用量の枠は、画面で使うときと共有です。

    Q. 同時に何本も動かせますか?

    動かせますが、そのぶん枠を使います。私の作業場では、同時に動かす数と、同じフォルダで同時に動かす数に、上限を設けています。

    Q. サブエージェントを使う依頼は、どうなりますか?

    公式のドキュメントでは、裏で動くサブエージェントがある間、claude -p は、その完了まで終わらずに待ちます。実機の stream-json でも、1回の実行の中で、「起動した」という返事と、「結果が届いた」という返事の、2回が出ました。

    Q. 途中経過を見たいです

    --output-format stream-json --verbose を付けると、1手ずつの動き(使った道具、結果)が1行ずつ流れます。この記事の実験の記録も、これで取りました。

    注意点

    • この記事の内容は、2026年10月15日の公式ドキュメントと、私の Windows 11 の環境(Claude Code 2.1.296)で確かめたものです。オプションは、版が上がると変わることがあります。迷ったら claude --help と、公式のドキュメントを見てください

    • 実機の試験は、小さな試験用フォルダで、軽いモデル(haiku)を使い、1つずつ行いました。費用の数字は、そのときの見積もりです

    • 試していないこと:--bare での成功(API キーがないため)、auto モード、--forward-subagent-text、タスクスケジューラへの実際の登録

    • AI の返事は、毎回同じではありません。自動実行の結果は、ログを時々見て、確かめてください

    まとめ

    • claude -p は、画面なしで1回だけ動く方法。成功なら終了コード 0

    • --output-format json で、結果・会話のID・費用が読める。--json-schema で答えの形も決められる(実機でも structured_output に入った)

    • --resume で会話をつなげる。--no-session-persistence では戻れない

    • 確認の画面は出ない。dontAsk + --allowedTools で、必要な道具だけを許可する

    • 上限は --max-turns と --max-budget-usd。どちらも終了コード 1 で止まるが、費用は少し超える

    • Windows では、$null | claude -p ... で警告を避け、スクリプトにして、schtasks で登録する

    • 動かないときは、まず claude --version。古い版が呼ばれていることがある

    次の一歩は、今日の作業を1つ選んで、claude -p で1回動かし、--output-format json の結果と費用を見ることです。10分で、できます。


    次に読む

    このアカウントをフォローすると、Claude Code や Codex の新しい手順の記事が届きます。ぜひフォローしてください。

    この先で分かること(今後の有料記事)

    • そのままコピーして使える自動実行の実物(毎朝の要約、並列の処理、失敗時の再実行)

    • 依頼ボードから claude -p を自動で起動する、小さな実行係の設計

    • 実際に起きた失敗と、直し方の記録

    まさのAI実務ラボ|Codex・Claude Code では、有料記事が読み放題になります。テンプレートや指示文をまとめて使いたい方はご覧ください。

    あなたへのおすすめ