ヘッドレスモード（Headless Mode / CI・CD自動化）

Claude Code を対話ではなくスクリプトや自動処理で回したい人向け

ヘッドレスモードは、Claude Code を対話画面なしで動かすやり方の総称です。ふだんは claude と打つと会話画面が立ち上がって、人がそこで質問したり「この変更を許可しますか」に答えたりします。それを全部すっ飛ばして、頼みごとを1回渡し、答えだけ受け取って終わるのがヘッドレスです。入口になるのが claude -p "頼みごと" という打ち方になります。

人が画面の前にいなくても回せるので、自動処理の中に Claude Code を組み込めます。料理ブログの記事に画像の説明文を一括で付けたり、毎晩リンク切れを点検させたり。そういう「人が見てない時間に勝手に働いてほしい」仕事と相性がいいです。

そもそもヘッドレスって何のこと？

ヘッドレスは直訳すると「頭がない」。ここでの頭は、人が見て操作する画面のことです。画面という入口を持たずに動くプログラムを、よくヘッドレスと呼びます。

たとえば新しい職場の初日を思い浮かべてください。上司が横についていれば、迷うたびに「これやっていいですか」と聞けます。これが対話モード。一方、上司が外出中で、メモ1枚と「これとこれは勝手にやっていい」というルールだけ渡されて作業するのがヘッドレスです。聞く相手がいないぶん、何を許すかを最初に渡しておく必要があります。

ここが地味に大事。

つまりヘッドレスモードは、Claude Code を「人が承認しなくても動く状態」で起動するやり方そのものを指します。単独の新機能というより、-p を中心にした動かし方の名前だと思ってもらえればいいです。

大事な前提：承認してくれる人がいない状態で動く

対話モードなら、Claude が「このファイルを書き換えていい？」と聞いてきたとき、人が画面で Yes / No を押せます。ヘッドレスではその人がいません。だから何も渡さないと、許可待ちで止まったり、そもそも何も触れずに終わったりします。

ここを分かっていないと「動かしたのに何も起きなかった」になります。最初にやりがちな勘違いです。

解決策は、起動時に「何を勝手にやっていいか」を一緒に渡すこと。公式が用意しているのが --allowedTools という渡し方で、ファイルを読む・書き換える・コマンドを打つといった道具のうち、許すものだけを名前で並べます。

「料理ブログの運用自動化」を例に、実際の手順を見る

cooking-blog という料理ブログのフォルダがあるとします。記事ファイルがたくさんあって、画像に説明文が付いてないものが混ざっている。これを Claude Code に一括で点検・修正させる流れを、頭の中で再現できるように追っていきます。

ステップ1: まず会話なしで1回だけ動かす

いちばん小さい形から。ターミナルで cooking-blog のフォルダに入って、次の1行を打ちます。

$ claude -p "このフォルダの構成を1段落で説明して"

会話画面は出ません。少し待つと、フォルダの説明文だけがそのまま画面に返ってきて、すぐ終了します。これがヘッドレスの基本形です。

ステップ2: 道具を許可して、書き換えまでやらせる

次は読むだけでなく直させます。画像の説明文を付け足す作業には、ファイルを読む・書き換える権限が要ります。許す道具を一緒に渡します。

$ claude -p "各記事の画像に説明文が無ければ付け足して" \
    --allowedTools "Read,Edit"

これで人が横にいなくても、Read（読む）と Edit（書き換える）の範囲に限って勝手に進めてくれます。許してない道具を使おうとした時は、その場で止まる仕組みです。

ステップ3: 結果を機械で扱える形でもらう

答えを文章ではなく、後続の処理が読める形で受け取りたい時があります。--output-format を付けると出力の形を選べます。公式の選択肢は3つ。

• text：ふつうの文章（何も指定しないとこれ）
• json：結果に加えて、やり取りの識別番号やかかった費用などの情報が付いた構造化データ
• stream-json：生成しながら1行ずつ流れてくる形式

$ claude -p "このプロジェクトを要約して" --output-format json

json を選ぶと、答え本体は result という欄に入ります。公式によれば、この json には total_cost_usd（その1回でかかったドル費用）も含まれるので、自動処理ごとにいくら使ったか追えます。

ステップ4: jq で欲しい部分だけ抜く

json をまるごと受け取っても、欲しいのは答えの本文だけ、ということが多いです。jq という定番の道具に流すと、特定の欄だけ取り出せます。

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

縦棒 | は、前のコマンドが出した結果を次のコマンドに横流しする記号です。ここでは Claude の json を jq に渡し、.result の中身だけ抜いています。

ステップ5: 手元のデータを流し込む

ヘッドレスは入力も受け取れます。たとえば点検ログを Claude に流し込んで、原因だけ説明させて結果をファイルに書き出す、といった連結ができます。

$ cat link-check.txt | claude -p "リンク切れの原因を簡潔に説明して" > result.txt

左の cat がファイルの中身を吐き出し、それを Claude に横流しし、答えを result.txt に書き出す。ふつうのコマンドと同じ感覚で部品としてつなげます。流し込めるデータの上限は公式で10MBまでと決まっていて、超えるとはっきりエラーで止まります。詳しい連結のしかたは pipe-input のエントリで扱っています。

ステップ6: 毎晩ひとりでに走らせる

ここまでを cron に登録すると、決まった時刻に勝手に走ります。cron はパソコンやサーバーに昔からある「指定時刻にコマンドを実行する仕組み」です。毎晩1時に料理ブログのリンク切れ点検を回す、みたいな使い方ができます。人は朝、結果ファイルを見るだけ。

つまりヘッドレスモードは何をしてくれるのか

• やってくれる：人が画面の前にいなくても、頼みごとを1回渡して答えだけ受け取れる。自動処理やスクリプトの部品として Claude Code を組み込める
• やってくれない：勝手に何でも触ることはしない。許す道具を --allowedTools 等で渡さない限り、書き換え系は止まる
• 意味が薄い場面：1回きりの相談や、人が画面で都度判断したい作業。それなら対話モードのほうが速くて安全

使いどころ3シナリオ（具体題材で再現）

シナリオ1: 料理ブログの画像説明文を一括で埋めたいとき

cooking-blog に記事が80本あって、画像の説明文が抜けているものが半分くらい。1本ずつ画面で確認するのはだるい。claude -p "説明文が無い画像に付け足して" --allowedTools "Read,Edit" を1回叩けば、読む・書き換えの範囲に絞って一気に処理してくれます。終わったら自分で差分を見て確認する。私はこういう「単純だけど数が多い」作業こそヘッドレス向きだと思っています。

シナリオ2: 毎晩リンク切れを点検させたいとき

料理ブログは外部レシピへのリンクが多くて、相手が記事を消すと切れます。点検ログを作るコマンドの結果を claude -p に流し込み、原因を要約させて result.txt に書き出す。これを cron で毎晩1時にセットしておけば、朝チェックするだけで済みます。人が起きてる時間を使わないのが効く。

シナリオ3: 公開前に自動でひと通りチェックさせたいとき

新しい記事を保存する前に、誤字や壊れた書式がないか見てほしい。GitHub という置き場に保存する流れの中に claude -p を挟むと、保存のたびに自動で点検が走らせられます。この GitHub 上での自動実行は github-actions のエントリで専用に扱っているので、組み込み方はそちらを見てください。

初心者が踏みやすい落とし穴

• 道具を許可せずに書き換えを頼む。--allowedTools を渡さないと、ファイルを直す系の頼みごとは許可待ちで止まったり何もせず終わったりします。「動いたのに変化なし」の典型原因です
• 全部許可してしまう。公式には人の確認を全部すっ飛ばす --dangerously-skip-permissions もありますが、名前のとおり危険です。誰も見ていない場で何でも実行できてしまうので、安易に付けないこと
• 対話用のスラッシュ命令を期待する。公式によれば /code-review のような人が画面で打つ命令はヘッドレスでは使えません。やりたいことを文章で頼む形に直します
• 大きすぎるデータを流し込む。流し込めるのは10MBまで。超えるとエラーで止まるので、大きい入力はファイルに書いて、その場所を頼みごとの中で示す形にします
• text のまま機械処理しようとする。後続の処理で結果を扱うなら --output-format json にして、jq で欲しい欄を抜く。文章のまま無理に切り出すと壊れやすいです
• 対話モードのつもりで使う。1回きりの相談や、都度判断したい作業はふつうに claude を起動したほうが速い。ヘッドレスは「同じ作業を無人で繰り返す」ためのものです

書き方

claude -p "頼みごと" --allowedTools "Read,Edit" --output-format json

やってみるとこうなる

入力

cat link-check.txt | claude -p "リンク切れの原因を簡潔に説明して" --output-format json | jq -r '.result'

出力例

json を選ぶと答え本体が result 欄に入り、total_cost_usd（その1回のドル費用）など実行の情報も一緒に返る。jq -r '.result' で答えの文章だけを抜き出せる。

関連項目

• GitHub Actions（ギットハブアクションズ）
• Pipe Input（パイプ・インプット）
• claude -p（クロード・ピー）
• --include-partial-messages（インクルードパーシャルメッセージズ）
• --fallback-model（フォールバックモデル）

公式ドキュメント

https://code.claude.com/docs/en/headless