claude -pとは？ヘッドレス実行と定期実行の実録【2026年】

claude -pとは、Claude Codeを対話なしで1回だけ動かし、結果を出して終わる非対話モードです。スクリプトや定期実行に組み込めます。僕の会社では人が開かなくても回る仕事を5本作りましたが、再設計前に定刻どおり完走したのは2本だけでした。公式の仕様と、止まった原因、権限の考え方をまとめます。

claude -pとは？非対話モードの公式仕様

claude -pとは、Claude Codeに指示を1つ渡し、対話画面を開かずに処理させて結果を出力するモードです。「-p」は「--print」の短縮形で、公式ドキュメントではAgent SDKをコマンドラインから使う方法として説明されています。成功すると終了コード0、失敗すると0以外で終わるので、シェルスクリプトやCIの中で結果を見て分岐できます。

ヘッドレス実行とは、人が画面を見て操作しない前提で、プログラムやスケジューラからツールを動かす使い方のことです。Claude Codeでは、claude -pがその入口になります。一番簡単な使い方は次の1行です。

claude -p "このリポジトリのREADMEを3行で要約して"

標準入力も読めるので、ほかのコマンドの出力をパイプで渡せます。公式の例でも、ビルドのエラーログを流し込んで原因を説明させています。パイプで渡せる量は10MBまでで、超えるとエラーで止まります。

cat build-error.txt | claude -p "このビルドエラーの原因を短く説明して" > output.txt

対話モードとの大きな違いは3つです。人が途中で答えられないこと、1回の実行で終わること、出力を機械が読める形にできることです。逆に言えば、対話で普段やっている「途中で確認して、許可を出して、続けて」が一切できません。ここを前提に設計しないと、無人実行はすぐ止まります。

もう1つ知っておきたいのが、claude -pは何を読み込むかです。何も付けなければ、対話モードと同じように作業フォルダや「~/.claude」の設定、CLAUDE.md、フック、スキル、MCPサーバーを読み込みます。「--bare」を付けると、これらの自動読み込みをすべて省いて速く起動します。公式は、スクリプトやSDKから呼ぶなら--bareを推奨し、将来は-pの既定にする予定だと書いています。

claude -pでよく使うオプションは？早見表

よく使うのは、出力形式を決める--output-format、使ってよいツールを決める--allowedTools、権限の基準を決める--permission-mode、暴走を止める--max-turnsと--max-budget-usdの5つです。この5つを決めておけば、たいていの自動化は組めます。

以下は2026年10月時点の公式ドキュメント（CLIリファレンスとヘッドレス実行のページ）で確認した内容です。

JSONで受け取ると、後の処理が楽になります。公式の例にならうと、本文だけを取り出すならjqを使って次のように書きます。

claude -p "このプロジェクトを要約して" --output-format json | jq -r '.result'

JSONには推定費用のtotal_cost_usdも入ります。ただし公式は、これは手元で計算した推定値で、実際の請求とずれることがあると注意しています。費用の管理は推定値を目安にしつつ、正式な数字は使用量の画面で確かめてください。料金と上限の仕組みはClaude Codeの料金と使用量の上限で詳しく書きました。

スキルとの組み合わせもできます。手動で呼ぶスキルは、指示文の中に「/スキル名」と書けば、実行前に展開されます。つまり、普段の対話で育てたスキルを、そのまま無人実行の手順書として使い回せます。スキルの作り方はClaude Skillsとは？作り方と社内の実録にまとめています。

Claude Codeを定期実行するには、どの方法を選ぶべきか？

パソコンが閉じていても動かしたいならクラウドのルーティン、手元のファイルやログイン済みのブラウザを使うならデスクトップアプリの定期タスク、会話中の見張りなら/loopです。claude -pをOSのスケジューラから呼ぶ方法も、手元のマシンが起きている間しか動きません。選ぶ基準は「どこのデータに触るか」と「止まったら誰が気づくか」です。

公式ドキュメントの比較表をもとに、claude -pを使う方法を足して整理します。

デスクトップアプリの定期タスクで特に注意したいのは、取りこぼしの扱いです。公式ドキュメントによると、パソコンが眠っている間に予定時刻を過ぎた分は実行されません。起動や復帰のときに、直近7日で取りこぼした中から最新の1回分だけが追いかけて実行され、それより古い分は捨てられます。朝9時の予定が夜11時に走ることもあるので、指示文の側で「今日の分だけを見る」といった歯止めを書いておくよう、公式も勧めています。

定期タスクとは、決まった時刻に新しいセッションを自動で立ち上げ、あらかじめ書いた指示を実行させる機能のことです。デスクトップアプリでは、1本ごとに「~/.claude/scheduled-tasks/タスク名/SKILL.md」というファイルに指示が保存されます。中身はスキルと同じ形式なので、スキルを書ける人なら定期タスクも書けます。

ウラカタは「人が開かなくても回る仕事」をどう作っているか？

僕の会社は今、デスクトップアプリの定期タスクを本線にしています。経理のチェック、経費の領収書の整理、自社サイトのお知らせのネタ出し、経営ダッシュボードの月次更新、そしてこのAIメディアの毎朝の記事更新の5本が動いていて、週次の広告レポートは止めて登録も外しています。claude -pは、まだ定期実行に使っていません。社内の資料とログイン済みのサービスを毎回使うので、手元の定期タスクの方が合っていました。

2026年10月1日時点の構成を表にします。時刻は設定値で、実際には公式の仕様どおり数分ずつずらして起動します。

共通しているのは、お金と対外の操作をさせないことです。会計ソフトへの書き込み、振込などの銀行操作、広告の設定変更、クライアントへの送付は、定期タスクの中では一切させません。書き込みを許しているのは自社サイトの中だけで、ダッシュボードの反映と記事の公開がそれに当たります。記事の公開も、書いたエージェントとは別のエージェントが検品して合格を出したものに限り、2回落ちたら公開せずに保留として通知させます。経費の判定も、迷うものは勝手に「経費」や「個人」に振り分けず、質問リストに載せて人の答えを待ちます。無人で動く仕事ほど、止まる場所を先に決めておく方が安心して任せられます。

全タスクには、2026年9月7日に決めた共通ルール5条を入れています。

1. 毎回ログを1本残す：異常がゼロでも「異常なし」と書いて保存する。ログが増えていなければ、動いていないと一目で分かるようにするため
2. 報告は異常がある時だけ詳しく：正常なら1〜2行で終える
3. 最後に必ず通知を1回送る：会話を開かなくても、終わったことが分かるようにする
4. 認証切れで固まらない：ログインが切れていたら、取れた範囲だけログに書いて終える
5. 途中で失敗しても、どこまで進んだかを書いてから終わる

定期タスクとは別に、フックも使っています。フックとは、セッションの開始、ツールの実行前後、応答の終了などの決まったタイミングで、自動的にスクリプトを走らせるClaude Codeの仕組みです。設定は「~/.claude/settings.json」に書きます。僕の会社で主に使っているのは次の4つです。

2つ目のフックは、「実行したかどうか」ではなく「成果物があるかどうか」で判定しています。後で書く通り、定期タスクの「実行済み」の記録は、成果物が無くても付くことがあったからです。4つ目は、応答の終了時に動くフックが、条件を満たすと一度だけ終了を止めて、引き継ぎメモを書かせる作りです。公式のフックの仕様では、応答終了時のフックが「block」を返すと、Claudeは止まらずに作業を続けます。

定期タスクが動かなかった原因は何だったのか？（実録）

一番多かった原因は、権限の確認待ちで止まることでした。普段の対話では確認が出ないように設定していたので気づかず、無人のセッションで初めて確認画面が出て、誰も答えないまま13時間止まっていました。ほかに、実行済みの記録だけが付いて中身が無い空振りと、登録そのものが消える現象もありました。どれも「動いているように見える」のが厄介な点です。対話中の画面で止まったときの見分け方は、Claude Codeが途中で止まる時の切り分け方にまとめました。

経緯を順に書きます。2026年8月から9月初めまで、定期タスクを5本登録していました。ところが9月7日に振り返ると、定刻どおり最後まで完走したのは8月24日の2本だけで、それ以降の2週間はゼロでした。症状ごとに切り分けると、原因は3つでした。

確認待ちの根本原因は、ユーザー設定の許可リストがほぼ空だったことです。普段の対話セッションは確認を飛ばすモードで動かしていたので、困りませんでした。ところが定期タスクは、タスクごとの権限モードと、ユーザー設定の許可ルールで動きます。公式ドキュメントにも、手動確認のモードで許可のないツールを使おうとすると、承認されるまで実行が止まると書かれています。

対策として、9月7日に既定の権限モードをファイル編集の自動承認（acceptEdits）にし、読み取り系のツールと定番のコマンドを許可リストに足しました。2026年10月1日時点で許可ルールは48件です。広告の設定を書き換える系統のツールは、意図的に許可リストから外しています。公式は、タスクを作った直後に「今すぐ実行」を押し、出てきた確認に「常に許可」で答えておく方法も案内しています。

一方で、広告レポートは止めました。データの棚卸し、数字の集計、レポートの作成を1本でやる大きなタスクで、一度も最後まで走りきらなかったからです。再開するときは、軽くて必ず終わる「棚卸し」と、重い「レポート作成」の2本に分けます。無人実行は、1本の仕事を小さくするほど完走しやすくなります。

再設計の後も、すべてが直ったわけではありません。9月7日の夜は、経理チェックが「パソコンのスリープ中に接続が切れた」というエラーで失敗しました。さらに2026年10月1日に実行履歴を確認すると、9月21日と28日の月曜の3本は、どれも管理画面上は「成功」なのに、セッションが4〜16秒で終わっていました。経理チェックは2回とも、手順の途中でツールを5回ほど呼んだところで終わり、ログのファイルは作られていません。同じ日に一覧を開くと、稼働中だった4本の登録がすべて消えていて、指示ファイルだけが残っていました。同じ指示文で再登録しましたが、再登録すると過去の実行履歴は見えなくなります。実行履歴の「成功」だけを見ていたら、気づけなかった失敗です。いまは成果物の有無に加えて、登録が一覧に残っているかも確かめるようにしています。

ここから分かるのは、無人実行は「成功」の表示を信じず、ログや出力ファイルが増えているかどうかで成果物を確かめるしかないということです。原因を1つに絞るより先に、そう決めました。共通ルールの1条目でログを必ず残させているのも、セッション開始時のフックで成果物の有無を見ているのも、そのためです。止まった仕事に人が気づける仕組みまで作って、初めて「人が開かなくても回る」と言えます。失敗を仕組みに変える考え方は、AI導入の失敗事例7つでも書きました。

無人実行の権限はどう考えるべきか？

基本は「読むのは広く、書くのは狭く、外に出すのは人が押す」です。無人実行では途中で誰も止められないので、取り返しのつかない操作は最初から許可しないのが一番確実です。claude -pなら--allowedToolsで使えるツールを列挙し、--permission-prompts noneで確認が必要な操作を拒否させます。定期タスクでも考え方は同じです。定期タスクが確認待ちで止まった実例と、cdや&&つきのコマンドが別扱いになる点はClaude Codeで毎回許可を聞かれる原因と設定に書きました。

権限モードとは、Claudeがツールを使うときに、どこまで確認なしで進めてよいかを決める基準のことです。公式ドキュメントでは、-pでよく使うものとして次の3つが挙げられています。

僕の会社の社内ルールでは、ファイル編集、ブラウザ操作、Web検索、メールの下書き作成までは確認なしで進めます。メールの送信、ファイルの削除や共有、プルリクエストのマージは確認が出る設定です。さらに、広告の公開、支払い、SNSへの投稿のような対外的な操作は、ツールの許可が通っていても、押す直前にチャットで承認を取ります。ツールの許可と、仕事としての承認を分けて考えるのがポイントです。

claude -pならではの注意点もあります。公式ドキュメントによると、--bareを付けないclaude -pは、信頼の確認をしていないフォルダでも、そのプロジェクトのフックやMCPサーバーを確認なしで動かします。他人から受け取ったリポジトリでclaude -pを走らせるときは、--bareを付けるか、中身を確かめてからにしてください。

もう1つは、失敗の見分け方です。この記事を書くにあたって、手元のMacでclaude -pを試しました。ターミナル版のClaude Code（v2.1.237）で小さな集計を頼んだところ、ターミナル側のログインが期限切れになっていて、401の認証エラーで約6秒で終わりました。デスクトップアプリは毎日使っていても、ターミナルのclaudeは別にログインし直す必要があったわけです。

このときのJSONは、resultにエラーの文面が入り、is_errorはtrue、終了コードは1でした。ただし、結果の種類を表すsubtypeという欄は「success」のままでした。スクリプトで成否を判定するなら、subtypeではなく、終了コードとis_errorを見るのが安全です。

out=$(claude -p "logs/ の最新ファイルを読み、異常があれば1行で報告して" \
  --allowedTools "Read" --max-turns 5 --output-format json)
status=$?
if [ $status -ne 0 ] || [ "$(echo "$out" | jq -r '.is_error')" = "true" ]; then
  echo "失敗: $(echo "$out" | jq -r '.result')"
fi

ついでに分かったのが、バージョンの差です。手元のターミナル版はv2.1.237で、無人実行向けの--permission-prompts（v2.1.259以降）にはまだ対応していませんでした。デスクトップアプリとターミナルで中身のバージョンが違うことがあるので、claude -pを組む前に「claude --version」で確かめておくと、オプションが通らずに悩む時間を省けます。

最後に、使用量の見張りも公式の経路に寄せました。以前は使用量を常時表示する仕組みを自作していましたが、非公式な取り方だったので、2026年9月30日に止めています。今はセッションの中で公式の使用量を測らせ、先ほどのフックで95%を超えたら引き継ぎメモを書かせる形です。AIエージェント全般の組み方はAIエージェントの作り方で、自社の業務への落とし込みはウラカタのサービス一覧で紹介しています。

まとめ

• claude -pとは、Claude Codeを対話なしで1回動かして終わる非対話モード。成功なら終了コード0で、スクリプトやCIに組み込める
• 押さえるオプションは--output-format、--allowedTools、--permission-mode、--max-turns、--max-budget-usd。CIでは--bareで読み込みを止める
• 定期実行は、パソコンが閉じていても動かすならクラウド、手元の資料やログインを使うならデスクトップの定期タスク。どちらも成功の表示ではなく成果物で確かめる
• 僕の会社では5本中、定刻に完走したのが2本だけだった時期がある。最大の原因は権限の確認待ちで、許可リストの整備と、仕事を小さく分けることで減らした
• 無人実行の権限は「読むのは広く、書くのは狭く、外に出すのは人が押す」。成否はsubtypeではなく、終了コードとis_errorで判定する