非対話セッションのメリット・デメリット
Claude Code -p / Agent SDK vs OpenAI Codex CLI exec
公式ドキュメント最新版に基づく比較（2026年5月時点）
「非対話セッション」とは
通常の対話型 TUI（ターミナル UI）を立ち上げずに、1 プロンプト＝ 1 実行でエージェントを動かすモード。標準入出力で他のコマンドと連結できるため、シェルスクリプト・CI/CD・cron・Git フック・他プロセスからの呼び出しに組み込める。
Claude Code では claude -p "..."（headless mode / Agent SDK CLI）、OpenAI Codex CLI では codex exec "..." がこれにあたる。
1. ツール別の概要
Claude Code — Headless Mode
コマンド: claude -p "..." / Agent SDK
Agent SDK の CLI フロントエンド。対話型と同じツール・エージェントループ・コンテキスト管理をそのままスクリプトから呼び出せる。--bare を付けるとフック・スキル・MCP・CLAUDE.md などの自動読み込みをスキップして再現性を確保。
claude -p "Find and fix the bug in auth.py" \
--allowedTools "Read,Edit,Bash"
# CI 向けにベアモード＋構造化出力
claude --bare -p "Summarize this file" \
--allowedTools "Read" \
--output-format json
✅ メリット
-
JSON Schema 準拠の構造化出力（
--json-schema） -
ストリーミング（
stream-json）対応 -
--continue/--resumeでセッション復帰 -
total_cost_usdがレスポンスに含まれ呼び出し単位でコスト把握 -
権限モード（
dontAsk/acceptEdits）で CI を安全にロックダウン -
GitHub Actions / GitLab CI の公式統合ドキュメントあり
-
--bareでローカル環境差分の混入を排除
✗ デメリット
-
ユーザー定義スラッシュコマンド（
/commit等の skills）は対話型限定 -
piped stdin は 10MB 上限（v2.1.128 以降）
-
2026年6月15日以降、サブスクリプションでは Agent SDK 用クレジットを別途消費
-
--bare時はANTHROPIC_API_KEY等が必須（OAuth / keychain 不可） -
権限設定をミスると CI で中断する
OpenAI Codex CLI — exec
コマンド: codex exec "..."
TUI を起動せずスクリプトから呼び出すモード。進捗を stderr、最終メッセージを stdout に分離して出力するため、Unix パイプとの相性が良い。デフォルトは読み取り専用サンドボックス。
codex exec "リポジトリ構造を要約し、リスク領域を5つ列挙"
# パイプ + JSONL
npm test 2>&1 | codex exec --json \
"失敗したテストを要約し、最小限の修正を提案"
# 編集を許可するサンドボックス
codex exec --sandbox workspace-write "lint を直して"
✅ メリット
-
stdout/stderr 分離設計で
tee/ リダイレクトしやすい -
--jsonで全イベントを JSONL ストリーム化 -
--output-schemaによる Schema 準拠出力 -
サンドボックス 3 段階（read-only / workspace-write / danger-full-access）
-
codex exec resume --lastで多段階パイプラインを継続 -
--ephemeralでロールアウトファイルを残さない -
公式 GitHub Action あり（API キー露出を最小化）
✗ デメリット
-
デフォルトで Git リポジトリ内必須（
--skip-git-repo-checkで回避） -
full-access サンドボックスはコンテナ隔離前提で危険
-
OPENAI_API_KEYをジョブレベル env に置くと他ステップから参照可能 -
セッション履歴の管理粒度は Claude Code に比べシンプル
-
ChatGPT 認証を CI で使う運用は手間（
auth.jsonの安全配布が必要）
2. 機能対応表
| 項目 | Claude Code claude -p |
Codex CLI codex exec |
|---|---|---|
| 起動コマンド | claude -p "prompt" |
codex exec "prompt" |
| stdin パイプ入力 | ○ （10MB 上限） | ○ （codex exec - で stdin をプロンプト化） |
| 構造化出力 | --output-format json + --json-schema |
--output-schema schema.json |
| イベントストリーミング | --output-format stream-json --include-partial-messages |
--json (JSONL) |
| セッション継続 | --continue / --resume <session_id> |
codex exec resume --last / resume <ID> |
| ツール権限制御 | --allowedTools / --permission-mode |
--sandbox read-only\|workspace-write\|danger-full-access |
| 環境分離 | --bare（フック・MCP 等の自動読込を停止） |
--ignore-user-config / --ignore-rules / --ephemeral |
| コスト計測 | レスポンス内 total_cost_usd ＋モデル別内訳 |
JSONL イベントから集計（標準フィールドは限定的） |
| CI/CD 公式統合 | GitHub Actions / GitLab CI ドキュメントあり | Codex GitHub Action あり |
| 認証 | ANTHROPIC_API_KEY / Bedrock / Vertex / Foundry |
CODEX_API_KEY（OPENAI_API_KEY）/ ChatGPT 認証 |
3. 非対話モード共通のメリット・デメリット
✅ 共通メリット
-
自動化との親和性：cron / GitHub Actions / Makefile / npm scripts に組み込める
-
Unix パイプで連結：既存 CLI（
git,gh,jq,curl,npm test）と素直に繋がる -
再現性が高い：プロンプトと出力を Git で管理でき、レビュー・再実行が容易
-
並列実行：複数 PR を同時にレビュー、複数リポジトリを一括分析できる
-
機械的な後処理：構造化出力で他システムへ橋渡し（チケット起票、Slack 通知、ダッシュボード更新）
-
監査ログを残しやすい：実行コマンド・入出力をそのままアーカイブできる
✗ 共通デメリット
-
途中対話で軌道修正できない：プロンプトを練り込んでおく必要があり、暴走しても止めにくい
-
権限制御の設計負荷：自動承認の範囲を誤るとファイル破壊・git 履歴汚染・無限ループが起きる
-
シークレット漏洩リスク：API キーを CI 環境変数に置くため、他ステップ・ログ流出への注意が必要
-
コスト青天井になりやすい：自動リトライ・長文プロンプト・大量ファイルで意図せず高額化
-
ストリーム UI の利点を失う：途中経過の可視性が低く、デバッグは JSONL ログ解析が中心
-
失敗時の復旧が手作業：対話型のように「Esc で戻る」「直前 turn を編集」ができない
-
ユーザー定義のスラッシュコマンド / skill / hooks の挙動が異なる（特に Claude の
--bare）
4. どう使い分けるか
| シナリオ | 推奨 | 理由 |
|---|---|---|
| 大規模リファクタを CI でドラフト PR 化 | Claude | Agent SDK + Skills / MCP / 権限モードで長尺タスク向き |
| テスト失敗ログを要約してパッチ提案 | どちらも可 | stdin パイプ＋構造化出力で両者とも得意 |
| ログ解析・短い one-shot 処理 | Codex | codex exec は起動が軽く stdout/stderr 分離で扱いやすい |
| 呼び出し単位の正確なコスト集計 | Claude | total_cost_usd がレスポンス標準フィールドにある |
| サンドボックス分離を強く保証したい | Codex | --sandbox 3 段階＋デフォルト read-only が明示的 |
| 多段階パイプラインで履歴を引き継ぐ | どちらも可 | Claude=--continue/--resume、Codex=resume --last |
5. 結論・運用のコツ
-
「小さく・読み取り専用で始める」：両者ともデフォルトは安全側。最初は read-only /
--allowedTools "Read"で観察してから書き込み権限を解放する。 -
CI では再現性を最優先：Claude は
--bare、Codex は--ignore-user-config+--ephemeralでローカル設定の汚染を断つ。 -
構造化出力を必須にする：後工程（Slack 通知・チケット起票・PR コメント）に渡すため、
--json-schema/--output-schemaを活用する。 -
シークレットはステップ単位で注入：ジョブ全体の env に API キーを置かない。Codex は公式 GitHub Action、Claude は Bedrock/Vertex 経由も検討。
-
コスト上限を仕組みで担保：呼び出し時間制限、リトライ上限、トークン上限、コスト集計の自動アラートをセットで用意する。
-
「対話で詰めてから非対話に落とす」：対話モードでプロンプトと権限範囲を固めた後で
-p/exec化するのが事故の少ない流れ。
出典（2026年5月時点・公式ドキュメント）
-
Anthropic — Run Claude Code programmatically (Headless mode)
-
Anthropic — Headless mode（Claude Docs Mintlify）
-
OpenAI — Non-interactive mode – Codex
-
OpenAI — Command line options – Codex CLI
-
OpenAI — codex/docs/exec.md (GitHub)
※ 仕様・料金体系（特に 2026年6月15日以降の Claude Agent SDK クレジット）は変更される場合があります。最新情報は必ず公式を確認してください。
元ファイル: /Users/macdeji/Desktop/ツール開発/99_講義/non-interactive-mode-comparison.html
⠀