Non-interactive mode

概要

対話 TUI を開かずにスクリプト（CI ジョブなど）から Codex を動かすモード。codex exec で起動する。

仕様

基本

タスクのプロンプトを 1 引数として渡す
実行中、進捗は stderr にストリームされ、stdout には最終のエージェントメッセージだけが出る
--ephemeral でセッションの rollout ファイルをディスクに残さない
stdin がパイプされていて、かつプロンプト引数もある場合、プロンプトを指示、パイプされた内容を追加コンテキストとして扱う

権限と安全性

既定では codex exec は read-only sandbox で動く
編集を許すには --sandbox workspace-write、より広くは --sandbox danger-full-access
danger-full-access は隔離された CI runner やコンテナなど管理された環境でのみ使う
codex exec --full-auto は deprecated な互換フラグで、警告を表示する。新しいスクリプトでは明示的に --sandbox workspace-write を使う
--ignore-user-config で $CODEX_HOME/config.toml を読み込まない実行にする
--ignore-rules で user と project の execpolicy .rules を飛ばす
required = true の有効な MCP サーバーが初期化に失敗すると、そのサーバー無しで続行せずエラー終了する

機械可読な出力

--json で stdout が JSON Lines ストリームになり、実行中に出る全イベントを取得できる
イベント種別: thread.started、turn.started、turn.completed、turn.failed、item.*、error
item 種別: agent メッセージ、reasoning、コマンド実行、ファイル変更、MCP ツール呼び出し、web 検索、plan 更新
最終メッセージだけが必要なら -o <path> / --output-last-message <path>。ファイルに書いたうえで stdout にも出力する

構造化出力

--output-schema で JSON Schema に適合する最終応答を要求できる
ジョブサマリ、リスクレポート、リリースメタデータなど、安定したフィールドが要る自動ワークフロー向け

自動化での認証

codex exec は既定で保存済みの CLI 認証を再利用する
GitHub Actions では CLI を自前でインストール・認証するのではなく Codex GitHub Action を使う。Codex のインストール、Responses API プロキシの起動、設定可能な安全戦略での実行を行い、API キーの露出を減らす設計
Codex GitHub Action の識別子は openai/codex-action（出典のワークフロー例では uses: openai/codex-action@v1）。ソースは https://github.com/openai/codex-action で公開されている
Codex GitHub Action の前提: OpenAI キーを GitHub secret に置く、Linux または macOS の runner で動かす（Windows では safety-strategy: unsafe を指定する）、action を呼ぶ前にコードを checkout する、プロンプトは prompt（インライン）か prompt-file（リポジトリ内のファイル）で渡す
リポジトリで管理されたコードを checkout / 実行するワークフローで、OPENAI_API_KEY や CODEX_API_KEY をジョブレベルの環境変数に設定しない。 同じジョブ内のビルドスクリプト、テスト、依存関係のライフサイクル hook、侵害された action がそれらを読めてしまう
他の自動化環境では、CODEX_API_KEY をその 1 回の codex exec 呼び出しにだけ設定し、同じプロセス環境で untrusted なコードが走らないようにする
CODEX_API_KEY は codex exec でのみサポートされる
API キーではなく Codex ユーザーアカウントで CI/CD を動かす経路について
- 自動化の既定としては API キーが適切（発行とローテーションが簡単なため）。アカウントとして動かす必要がある場合にのみこの経路を使う
- ~/.codex/auth.json はアクセストークンを含む。パスワードと同様に扱い、コミット・貼り付け・共有をしない
- 公開・オープンソースのリポジトリではこのワークフローを使わない
- runner で codex login が使えない場合は、安全なストレージ経由で auth.json を配置し、runner 上で Codex を動かして更新させ、実行間で更新後のファイルを永続化する

非対話セッションの resume

codex exec resume --last "<prompt>" で直前の実行を継続する
codex exec resume <SESSION_ID> で特定のセッションを指定する

Git リポジトリの要求

破壊的な変更を防ぐため、コマンドは Git リポジトリ内で実行する必要がある
環境が安全だと分かっている場合は codex exec --skip-git-repo-check で回避する

stdin のパターン

パターン	使いどころ
prompt + stdin	指示は自分で書き、別コマンドの出力をコンテキストとして渡す
`codex exec -`	stdin をプロンプト全体にする。プロンプトをファイルに置く、シェルスクリプトで組み立てる、コマンド出力と指示を合成する場合に向く

プロンプト引数を省略すると Codex は stdin からプロンプトを読む。- はその挙動を明示的に強制する sentinel

設定

codex exec "summarize the repository structure and list the top 5 risky areas"
codex exec "generate release notes for the last 10 commits" | tee release-notes.md
codex exec --ephemeral "triage this repository and suggest next steps"
codex exec --sandbox workspace-write "<task>"
codex exec --json "summarize the repo structure" | jq

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"

codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"

npm test 2>&1 \
  | codex exec "summarize the failing tests and propose the smallest likely fix" \
  | tee test-summary.md

cat prompt.txt | codex exec -
generate_prompt.sh | codex exec - --json > result.jsonl