Claude Codeのヘッドレス実行｜社内チャット返信を止める3段設計

「この返信、下書きだけでも先に作っておいてくれないかな」。社内チャットの未読が積み上がると、そう思う瞬間が来ます。返信そのものは難しくないのに、読んで、書いて、送るまでの往復だけが止まりません。

Claude Codeには、対話画面を開かずに1回分の指示を渡して終了する非対話実行（ヘッドレス実行）があります。これを応答役として組み込めば、下書きまでは機械に任せられます。

ただし、任せた先が送信まで走ってしまっては困ります。この記事は、入力の受け渡し・実行範囲の制限・送信前に人が止める仕組みの3段に分けて、その設計を組み立てます。根拠は公式ドキュメント4件と自社の実測記録です（検証日2026-07-29）。

進行役は、自分の手で動かしたい高梨課長と、体制の側から見る大森部長。答えるのは鈴木さん（本誌監修）です。

01Claude Codeのヘッドレス実行って、AIエージェントに何をさせる仕組みなんですか？

高梨課長

高梨課長の発言

対話画面を開かずに動かせる、とは聞きました。中では何が起きているのでしょう。

鈴木さん

鈴木さんの発言

自動販売機に近いと思っています。硬貨を入れてボタンを押すと、缶が出て終わる。店員とのやり取りは残りません。

非対話実行（ヘッドレス実行）とは、claude -p（--print）にプロンプトを渡すだけで応答を受け取り、対話を残さず終了する実行方式です。

この方式は、Agent SDKのCLI版という位置づけです（出典: Claude Code公式）。Python・TypeScript向けのSDKパッケージも別にありますが、ここで扱うのは-pのCLI実行だけです。

02社内チャットの応答役をAIエージェントに任せる設計は、ヘッドレス実行のどこで区切れるんですか？

社内チャットの応答役に組み込む設計は、3段に分かれます。新着メッセージを渡す段、使える道具と権限を絞る段、そして出力を下書きのまま保留し、人が承認した分だけ送る段です。

最初の2段は、ヘッドレス実行そのものの設定で完結します。3段目だけは違います。呼び出し元のスクリプト側に置く設計判断で、コマンドの引数をいくら並べても生まれません。

左右で違うのは、機能の多さではありません。人が割り込める地点があるかどうかです。対話モードには、確認ダイアログという割り込み口が最初から付いています。ヘッドレス実行にはそれがなく、呼び出し元が結果を受け取ったあとにしか、止める場所を作れません。

ここを混ぜて考えると、道具を減らした時点で「もう止まるはずだ」と思い込んでしまいます。Claude Codeを業務へ広げる話の全体像は、Claude Codeの業務活用｜任せる仕事の地図と判断軸4つにまとめています。

03AIエージェントを社内チャットに置く前に、Claude Codeのヘッドレス実行で何を用意しておくんですか？

検証環境は、claude-opus-5・Claude Code v2.1.x系・macOS 15です（検証日2026-07-29）。以降の設計は、この条件で動かした記録に基づきます。

組み込む前に用意するものは、次の5点です。

• Claude CodeのCLIがインストール済みで、認証が通っていること（サブスクリプションのOAuth、またはANTHROPIC_API_KEY）
• 社内チャット側の送受信を行う既存のAPI・Webhookスクリプト（チャット側の実装そのものは、この記事では扱いません）
• ヘッドレス実行の出力を一時的に置く保留キュー（ディレクトリ1つで足ります）
• 対象ディレクトリで、ワークスペースの信頼（trust）が確立済みであること
• --permission-modeの既定値を決めておくこと

このうち上の3点は、揃っているかどうかが目で見て分かります。残る2点は、揃っていなくても実行が始まってしまう種類の前提です。

04書いた設定がヘッドレス実行で効いていないとき、AIエージェントの画面には何が出るんですか？

高梨課長

高梨課長の発言

準備の抜けは、動かしてみれば分かりますよね。

鈴木さん

鈴木さんの発言

それが分からないんです。抜けていても実行は始まって、結果も返ってきます。違うのは、書いたつもりの制限だけが外れていることです。

見落としやすいのは、ワークスペースの信頼です。非対話モードの-pでは確認ダイアログが出ず、許可ルールも無視されます（出典: Claude Code公式ドキュメント「Configure permissions」）。信頼を立てないまま走らせると、許可の指定だけが宙に浮いて、実行のほうは進んでいきます。

厄介なのは、画面に何も出ないことです。動いていないのではありません。動いてはいるけれど、書いたつもりの制限だけが外れています。

書いたことと効いていることを分けて数える習慣は、常駐で動かす仕組みの入口でも同じです。運営元のWEBMARKSは、そこを毎回測っています。launchdジョブは8本のplistを定義していますが、launchctlでの実測ではロード済みは1本だけでした（2026-07-28実測・自社実測台帳より）。

差そのものより、この差は数えるまで見えないことのほうが重要です。定義したファイルは手元に残るので、書いた側の数はいつでも確認できます。読み込まれた側は、別のコマンドで数えないと表に出てきません。

以降で示すのは「どう組むか」という設計です。「常時稼働している」という主張ではありません。

05社内チャットの本文は、ヘッドレス実行のどの経路でAIエージェントに渡すんですか？

渡し方は3通りあります。選ぶときに見るのは、本文の長さと、記号がそのまま通るかどうかの2点です。

（出典: Claude Code公式）

標準入力なら、本文に"や` ``が混ざっていても、そのままの形で運べます。社内チャットの本文は、こちらが書式を決められません。コードの断片も、引用符も、そのまま飛んできます。既定を標準入力にしておくと、あとから例外に振り回されずに済みます。

06ヘッドレス実行で2通目の返信を送るとき、AIエージェントは前のやり取りをどこから引き継ぐんですか？

文脈を保つには、--session-id（UUID形式）でスレッドIDを割り当てます（出典: Claude Code公式ドキュメント「CLI reference」）。2通目以降は、同じIDを--resumeに渡して継続します。

# 1通目：新しいスレッドとして開始し、セッションIDを固定する
cat message_001.txt | claude --bare \
  --session-id "550e8400-e29b-41d4-a716-446655440000" \
  --output-format json \
  -p "この社内チャットのメッセージに、返信の下書きを作成してください"

# 2通目以降：同じスレッドの続きとして渡す
cat message_002.txt | claude --bare \
  --resume "550e8400-e29b-41d4-a716-446655440000" \
  --output-format json \
  -p "続けて返信の下書きを作成してください"

図の下に添えた一言が、この章のつまずきどころです。セッションIDの検索は、起動ディレクトリとそのgit worktreeに限定されます。起動元スクリプトは、毎回同じディレクトリから実行してください。

同じ制約はClaude Codeのセッション復元｜入口3つと戻らない設定の見分け方でも扱っています。

07AI社員に渡す道具は、ヘッドレス実行のどの指定で絞るんですか？

--permission-modeは、ヘッドレス実行がツール呼び出しをどう扱うかの既定値です。公式ドキュメントが挙げるモードは6種類です（出典: 同「Configure permissions」）。

チャットの応答役にはdontAskが向きます。たずねる相手がいないという前提と、許していないものは断るという振る舞いが、そのまま噛み合うからです。bypassPermissionsは公式ドキュメントが「隔離環境限定」と明記しており、日常運用には向きません（出典: 同ドキュメント）。

2軸に置き直すと、表では見えないものが見えます。答える人がいない場所では、「確認する」は「止まる」と同じ意味になるということです。default（manual）は対話モードでは丁寧な既定値ですが、ヘッドレス実行では、ただ進まない設定に変わります。

モードを選ぶ作業は、危険度の順に並べる作業ではありません。誰が返事をする前提の設定かを見分ける作業です。

08チーム全員に同じ制限を効かせるには、ヘッドレス実行でAIエージェントの設定をどこに書くんですか？

--allowedTools・--disallowedToolsは、モードの上からさらに絞り込みます。--disallowedToolsに渡したツールはClaudeの認識から消え、存在しないものとして扱われます（出典: 同ドキュメント）。

claude --bare \
  --permission-mode dontAsk \
  --allowedTools "Read(./knowledge/**)" \
  --disallowedTools "Bash" "WebFetch" "mcp__*" \
  --max-turns 6 \
  --max-budget-usd 0.50 \
  --output-format json \
  --json-schema '{"type":"object","properties":{"reply_draft":{"type":"string"},"needs_human_review":{"type":"boolean"}},"required":["reply_draft","needs_human_review"]}' \
  -p "このメッセージへの返信案を作成してください" < message.txt

ここで残しているのは社内ナレッジを読む操作だけで、Bash・外部通信・MCPツールは束ごと外しています。--max-turnsはやり取り回数、--max-budget-usdは金額に上限を置く数値です（出典: 同「CLI reference」）。

ただし、この指定はそのセッション限りです。同じルールは、チームで共有する設定ファイル側にも重ねます。拒否の一覧をそこへ書けば、コマンドの書き方を各自が覚えていなくても効きます。

{
  "permissions": {
    "deny": ["Bash", "WebFetch", "mcp__*"],
    "allow": ["Read(./knowledge/**)"]
  }
}

積み上げてみると、並列に見えた指定に上下が付きます。下の層ほど長く効き、上の層ほどその場限りで強いという関係です。どちらか一方に寄せると、共有できないか、その場で変えられないかのどちらかが残ります。

配分の考え方はClaude Codeの権限設定｜AIエージェントに任せる範囲と3列の配分が扱っています。

そして許可の側には、用意の章で触れた落とし穴がそのまま残ります。Read(./knowledge/**)も、対象ディレクトリのワークスペース信頼が未確立だと-p実行では適用されません。拒否だけが効いて許可が効かない状態にならないよう、自動化に組み込む前に一度対話モードで対象ディレクトリを開き、信頼を確立してください。

09送信の手前でAIエージェントを止めるには、ヘッドレス実行に何を持たせないんですか？

大森部長

大森部長の発言

権限を絞れば、誤送信は起きないと考えてよいですか。

鈴木さん

鈴木さんの発言

半分だけです。絞るのは「できることを減らす」話で、「止まる場所を作る」話とは別なんです。送信の手段そのものを渡さない、というのが先にきます。

大森部長

大森部長の発言

それでも送ろうとしたら、どうなりますか。

鈴木さん

鈴木さんの発言

道具の一覧に無いので、試みること自体が起きません。そのうえで、念のための2枚目を置きます。

人が最後に止める設計の一般原則は、AIエージェントの承認ゲート｜止める操作4種と3層の選び方が扱っています。ここでは、その原則をヘッドレス実行の出口へどう当てはめるかに絞ります。

いちばん堅いのは、非対話実行の側に送信の手段をそもそも置かない形です。投稿用ツールを--disallowedToolsで除外すれば、Claudeの認識にも上らず、送信を試みる余地自体がありません（出典: 同「CLI reference」）。

10それでも送信の道具を渡すなら、ヘッドレス実行のAIエージェントはどこで止まるんですか？

送信するツールを持たせる場合は、PreToolUseフックが二重の防御になります。ツール実行の直前に発火し、判定結果をallow・deny・ask・deferで返します（出典: Claude Code公式ドキュメント「Hooks」）。送信用のツールにはいつでもdenyを返す、という処理を1本置いておけば、そこが最後の壁になります。実コードはClaude CodeのPreToolUseで危険コマンドを遮断する4つの判定が扱っています。

11ヘッドレス実行の出力は、AIエージェントとスクリプトのどちらが運ぶんですか？

出口の側では、Claudeに送らせず、呼び出した側のスクリプトが受け取ります。--output-format jsonで返ってきたstructured_outputを、保留キューへ置くところで手を止めます。社内では、この設計を人間ゲートと呼んでいます。

#!/usr/bin/env bash
# headless-reply.sh — ヘッドレス実行の出力を、送信せず保留キューへ置く
set -euo pipefail

RESULT=$(cat "$1" | claude --bare --permission-mode dontAsk \
  --allowedTools "Read(./knowledge/**)" \
  --disallowedTools "Bash" "WebFetch" "mcp__*" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"reply_draft":{"type":"string"},"needs_human_review":{"type":"boolean"}},"required":["reply_draft","needs_human_review"]}' \
  -p "返信案を作成してください")

echo "$RESULT" | python3 -c '
import json, sys, pathlib, uuid
data = json.load(sys.stdin)
draft = data.get("structured_output", {})
pending = pathlib.Path("./pending") / f"{uuid.uuid4()}.json"
pending.write_text(json.dumps(draft, ensure_ascii=False, indent=2))
print(f"保留キューへ書き出し: {pending}")
'
# ここでチャットAPIへは一切アクセスしない。送信は人が承認した後の別プロセスが行う。

この設計の要点は3つです。

• Claudeのツール一覧に、チャットへ送信する手段が最初から存在しない
• structured_outputの書き出し先は、送信APIではなく保留キューのファイルである
• 承認と送信は、この非対話実行とは別のプロセス・別の権限で行う

--output-format jsonはresult・session_id・total_cost_usdを返します（出典: Claude Code公式）。--json-schemaを指定すると、ここにstructured_outputが加わります。needs_human_reviewは公式仕様ではなく、スキーマで自分が定義した項目で、レビューの優先度分けに使えます。

12Claude Codeのヘッドレス実行でAI社員がつまずくのは、どの3箇所ですか？

落とし穴1｜チャット履歴を丸ごと標準入力へ渡して失敗する

標準入力には10MBの上限があり（v2.1.128以降）、超えるとClaude Codeは明確なエラーで終了します（出典: Claude Code公式）。画像添付やログ引用の多いスレッドは想定より早く到達するため、履歴はファイルへ書き出し、Claude自身にReadさせます。

落とし穴2｜許可ルールを書いたのに、ヘッドレス実行では効いていない

ワークスペースの信頼が未確立だと、非対話実行では確認ダイアログの代わりに、ルールが無視されたまま進みます（出典: 同）。画面を開いていれば初回のダイアログで分かりますが、開かない実行には、それを知らせる相手がいません。自動化へ載せる前に、対象ディレクトリを一度だけ画面から開いて、信頼を立てておいてください。

落とし穴3｜--bareを付け忘れ、想定外のフックやMCPが動く

--bareを付けないと、対話モードと同じhooks・skills・plugins・MCP・CLAUDE.mdが読み込まれます（出典: Claude Code公式）。誰かが個人用のフックを足すと、応答役だけが理由もなく挙動を変えます。--bareがあれば、効くのは渡した設定だけになります。同じ入力から同じ結果が出やすくなります。

3つを並べると、性質が分かれます。1つ目はエラーで止まる失敗です。気づけます。残る2つは黙って進む失敗で、画面上は成功したときと区別が付きません。整備の順番を決めるなら、気づけないほうから手を付けてください。

13ヘッドレス実行が止まるべき所で止まったと、AIエージェントの何で判定するんですか？

見るのは、出来上がった文章だけではありません。止まってほしかった場所で、実際に止まったかどうかを見ます。判定基準は次の4点です。

4点のうち1つでも欠けると、その設計は未完成です。

見る順番にも意味があります。「送信の分離」は、権限を絞ったコマンドから--max-turnsをさらに小さくしたテスト実行で、先に確かめます。壊れて困る順ではなく、壊れたときに取り返しがつかない順に見てください。

14ヘッドレス実行の保留キューに置いた下書きは、AI導入の運用として誰がどう捌くんですか？

大森部長

大森部長の発言

下書きが溜まる場所を作るなら、そこを見る人も要りますね。

鈴木さん

鈴木さんの発言

そうです。だから、承認する側の権限は分けています。読んで送る作業と、書く作業を、同じ鍵で回さないという考え方です。

保留キューは、ディレクトリ1つで足ります。凝った仕組みは要りません。大事なのは置き場所の形ではなく、そこから先が別のプロセス・別の権限になっていることです。

書く側は、社内ナレッジを読む権限しか持ちません。送る側は、チャットへ投稿する権限を持ちますが、下書きを書き換える必要はありません。分けておくと、片方が壊れても、もう片方までは届きません。

needs_human_reviewのようなフラグは、この捌き方を助けます。ただし、これは公式仕様ではなく、こちらがスキーマで定義した項目です。値を決めているのはClaude自身なので、優先度の目安にはなっても、確認を省いてよい根拠にはなりません。

事実関係が絡む返信ほど、人が中身を読む前提を崩さないでください。読む相手がいる文章は、送った時点で戻せません。

15よくある質問

16まとめ｜今日やる3つのこと

設計は3段でした。入力を渡し、実行範囲を絞り、送信の手前で止める。最初の2段はコマンドの中で閉じ、3段目だけが呼び出し元の仕事でした。そして、書いた設定と効いている設定は、別々に数えます。