Codexの設定 - 機能

概要

OpenAI Codex CLIは、OpenAIのモデルを使用したコマンドラインインターフェース (CLI) 開発ツールである。

このページでは、Codex CLIの主要機能を解説する。
サンドボックス、承認モード、セッション管理、インタラクティブUI、パーミッションプロファイル、機能フラグ、Web検索、画像入力、非インタラクティブモード等、CLI機能全般を網羅的に説明する。

Codex CLIの機能は、下表の4層構造でセキュリティを提供する。

セキュリティの4層構造

層	説明
サンドボックス (sandbox)	ファイルシステム・ネットワークアクセスをOSレベルで制限する。
承認モード (approval_policy)	書き込み・実行操作に対してユーザの確認を要求する。
パーミッションプロファイル (permission profile)	ファイルシステム・ネットワークの細粒度な権限をプロファイルとして定義する。
auto-review	リスク評価エージェントが操作を事前審査する。

これらの機能を組み合わせることにより、開発作業の効率性と安全性を高いレベルで両立できる。

インタラクティブターミナルUI

Codex CLIは、フルスクリーンのターミナルユーザインターフェース (TUI) を提供する。

TUIは、リアルタイムのdiff表示、シンタックスハイライト、マルチラインの入力編集等、開発に必要な機能を備えたインタラクティブな操作環境を提供する。

主要キーバインド

下表に、Codex CLIのTUIで使用できる主要なキーバインドを示す。

Codex CLI 主要キーバインド

キーバインド	機能	説明
[Ctrl] + [R]	履歴検索	過去のセッション・コマンド履歴をインクリメンタル検索する。
[Ctrl] + [O]	出力コピー	最後のモデル出力をクリップボードにコピーする。
[Ctrl] + [L]	画面クリア	TUI画面をクリアする。 会話履歴は保持される。
[Ctrl] + [C]	中断	実行中の処理を中断する。
[Ctrl] + [D]	終了	セッションを終了する。
[Shift] + [Tab]	プランモード切り替え	プランモードと通常モードを切り替える。
[Esc]	キャンセル	現在の入力または処理をキャンセルする。
[Tab]	自動補完	コマンドやパスの自動補完を行う。
矢印キー (上 / 下)	履歴移動	入力履歴を遡る・進む。

シンタックスハイライトとdiff表示

TUIは、以下に示す表示機能を標準で提供する。

• シンタックスハイライト

  コードブロックを言語に応じて色付け表示する。

  対応言語: Python, JavaScript, TypeScript, Bash, C/C++, Rust, Go等

  
  

• リアルタイムdiff

  ファイル変更内容を追加 (緑) ・削除 (赤) で視覚的に表示する。

  変更前後の比較をインラインで確認できる。

  
  

• マルチラインエディタ

  複数行にわたるプロンプトを快適に入力・編集できる。

  
  

• ステータスバー

  現在のモデル、サンドボックスモード、承認ポリシー、トークン使用量を常時表示する。

セッション管理

Codex CLIは、会話セッションの永続化と管理機能を提供する。
セッション履歴はローカルに保存され、後から再開・分岐・整理することができる。

セッションの開始と再開

セッションを再開するには、以下の方法がある。

# 前回のセッションに自動復帰
codex resume

# 前回のセッションに復帰 (短縮フラグ)
codex --last

# 特定のセッションIDで復帰
codex resume <セッションID>

セッション内コマンド

セッション中に使用できるスラッシュコマンドを以下に示す。

セッション管理コマンド

コマンド	説明
/fork	現在のセッションを分岐して、新しい並行セッションを作成する。 元のセッションに影響を与えずに別のアプローチを試せる。
/side	サイドスレッドを開始する。 会話を切り替えながら複数の問題を並行処理できる。
/new	新しいセッションを開始する。 現在のセッションは保存される。
/compact	会話履歴を要約・圧縮してコンテキストウィンドウを節約する。 長期セッションで有効である。

会話履歴の永続化

セッションデータは、以下に示すディレクトリにローカル保存される。

• 保存場所

  ~/.codex/sessions/

• 保存形式

  JSON形式でセッション情報を記録する。

• 保存内容

  会話履歴、ファイル変更履歴、コンテキスト情報、セッション設定

承認決定のキャッシュ

1度ユーザが承認した操作パターンは、セッション内でキャッシュされる。
同じ種類の操作に対して繰り返し承認を求めることなく、スムーズに作業を進めることができる。

キャッシュの動作モード

動作	説明
セッション内でのキャッシュ	同一セッション中は承認済みの操作をキャッシュする。
セッションをまたいだキャッシュ	プロファイルに always_allow ルールを設定することで永続化できる。

セッションIDによる管理

各セッションには一意のセッションIDが割り当てられる。

# セッション一覧を表示
codex sessions list

# 特定のセッションIDで再開
codex resume abc123def456

# セッションを削除
codex sessions delete abc123def456

サンドボックスモード

Codex CLIのサンドボックスは、AIによる操作をOSレベルで制限するセキュリティ機構である。

実行環境に応じた適切なサンドボックスモードを選択することが重要である。

read-only

全ての変更操作とコマンド実行に対してユーザの承認が必要なモードである。

• 特徴

  ファイルの読み取りのみ自動許可される。

  全ての書き込み・実行に承認ダイアログが表示される。

  最も安全なモードである。

• 用途

  コードレビュー、調査作業、安全性最優先の作業環境

codex --sandbox read-only

workspace-write (推奨)

作業ディレクトリ内のファイル操作を自動許可し、ネットワークアクセスを遮断するモードである。

• 特徴

  ワーキングディレクトリ以下の書き込みを自動許可する。

  ネットワークアクセスはデフォルトで無効である。

  作業効率と安全性のバランスが取れた推奨モードである。

• 用途

  通常の開発作業、コード生成・修正。

codex --sandbox workspace-write

danger-full-access

サンドボックスを無効にして全ての操作を承認なしで実行するモードである。

• 特徴

  ファイルシステム・ネットワークの制限がない。

  承認プロンプトが表示されない。

  隔離されたCI/CD環境やコンテナ内での使用のみ推奨される。

• 用途

  完全に隔離されたビルド環境、自動化パイプライン

codex --sandbox danger-full-access

OS別実装

サンドボックスの実装はOSによって異なる。

• Linux

  bwrap (bubblewrap) と seccomp を組み合わせて、名前空間の分離とシステムコールのフィルタリングを行う。

• Windows

  WSL2上での使用を推奨する。WSL1は v0.115 以降でサポート対象外となった。

• MacOS

  Seatbelt (Apple Sandbox) と sandbox-exec を使用して、プロセスレベルでの制限を実現する。

保護されたパス

workspace-write モードであっても、以下のパスは常に読み取り専用で保護される。

• .git/

  Gitのバージョン管理データを保護する。

• .codex/

  Codex CLIの設定、セッションデータを保護する。

• .agents/

  エージェント定義ファイルを保護する。

--add-dirでのディレクトリ拡張

workspace-write モードで書き込み許可を追加するディレクトリを指定できる。

# /tmp/build を書き込み許可ディレクトリとして追加
codex --sandbox workspace-write --add-dir /tmp/build

# 複数のディレクトリを追加
codex --sandbox workspace-write --add-dir /tmp/build --add-dir /var/output

サンドボックスモード比較

サンドボックスモード比較

モード	ファイル書き込み	ネットワーク	承認要求	推奨用途
read-only	全て要承認	全て要承認	常に表示	コードレビュー、調査
workspace-write	ワーキングディレクトリは自動許可	無効	範囲外のみ	通常の開発作業
danger-full-access	制限なし	制限なし	なし	隔離コンテナ、CI/CD

承認モード (approval_policy)

承認モードは、Codex CLIがファイル操作やコマンド実行を行う時に、ユーザへの確認を求める動作を制御する設定である。

on-request (デフォルト)

安全と判断される読み取り操作は自動実行し、書き込み・実行操作はユーザに承認を求めるモードである。

• 動作

  ファイルの読み取り、ディレクトリの参照は自動実行される。

  ファイルの書き込み、コマンド実行は承認ダイアログを表示する。

• 用途

  対話的な開発作業のデフォルト設定として適している。

codex --ask-for-approval on-request

never

承認プロンプトを無効化して全操作を自動実行するモードである。

• 動作

  全ての操作が承認なしで実行される。

  サンドボックスによる制限は引き続き有効である。

• 用途

  CI/CDパイプライン、自動化スクリプト、バッチ処理

codex --ask-for-approval never

auto-review

リスク評価エージェントが操作を事前審査するモードである。

• 動作

  AIが操作のリスクを評価して、低リスクは自動実行・高リスクは承認要求を判断する。

  データ流出の可能性がある操作 (ネットワーク送信、機密ファイルへのアクセス等) を検出して警告する。

• 用途

  安全性を維持しながら承認負担を軽減したい場合。

codex --ask-for-approval auto-review

/permissions コマンド

セッション中に承認モードを動的に切り替えることができる。

# セッション中に承認モードを確認
/permissions

# セッション中に承認モードを変更
/permissions never
/permissions on-request
/permissions auto-review

--yolo / --dangerously-bypass-approvals-and-sandbox

サンドボックスと承認を一括バイパスするフラグである。

サンドボックスと承認ポリシーを両方無効化するため、信頼できる隔離環境以外では使用しないことを強く推奨する。

# 短縮形
codex --yolo

# フル形式
codex --dangerously-bypass-approvals-and-sandbox

承認ポリシー比較

承認ポリシー比較

ポリシー	読み取り	書き込み・実行	AIによる審査	用途
on-request	自動	要承認	なし	通常の開発
never	自動	自動	なし	CI/CD
auto-review	自動	リスク評価後に自動または承認	あり	バランス重視

パーミッションプロファイル

パーミッションプロファイルは、ファイルシステムとネットワークアクセスの権限を細かく定義する設定である。

サンドボックスモードと組み合わせることにより、より精密なアクセス制御を実現できる。

ビルトインプロファイル

Codex CLIは、以下に示すビルトインプロファイルを提供する。

• :read-only

  全てのファイル・ネットワークアクセスを読み取り専用に制限する。

  
  

• :workspace

  ワーキングディレクトリへの書き込みを許可する。

  ネットワークは無効

  
  

• :danger-no-sandbox

  サンドボックスを無効化する。

  隔離環境での使用のみ推奨

codex --profile :read-only
codex --profile :workspace
codex --profile :danger-no-sandbox

カスタムプロファイル

~/.codex/config.toml または .codex/config.toml にカスタムプロファイルを定義できる。

 [permissions.my-profile]
 description = "カスタム開発プロファイル"
 
 [permissions.my-profile.filesystem]
 # read, write, none のいずれかを指定
 "/home/user/projects" = "write"
 "/etc" = "read"
 "/tmp" = "write"
 
 [permissions.my-profile.network]
 # read, write, none のいずれかを指定
 "api.example.com" = "write"
 "*.internal.example.com" = "write"

権限の種類

権限	説明
none	アクセスを禁止する。
read	読み取りのみ許可する。
write	読み書きを許可する。

default_permissions設定

デフォルトで適用するプロファイルをグローバル設定ファイルで指定できる。

 # ~/.codex/config.toml
 
 default_permissions = "my-profile"

実装例

以下に、一般的な用途向けのカスタムプロファイル設定例を示す。

マルチテナント環境

複数のプロジェクトを分離して管理するためのプロファイル設定例を以下に示す。

 [permissions.tenant-isolated]
 description = "マルチテナント隔離プロファイル"
 
 [permissions.tenant-isolated.filesystem]
 "/home/user/tenant-a" = "write"
 "/home/user/shared-libs" = "read"
 "/tmp/tenant-a" = "write"
 
 [permissions.tenant-isolated.network]
 "tenant-a.api.example.com" = "write"

secrets除外設定

機密ファイルへのアクセスを明示的に禁止する設定例を以下に示す。

 [permissions.no-secrets]
 description = "機密ファイル除外プロファイル"
 
 [permissions.no-secrets.filesystem]
 "/home/user/project" = "write"
 "/home/user/project/.env" = "none"
 "/home/user/project/secrets" = "none"
 "/home/user/.ssh" = "none"
 "/home/user/.aws" = "none"

機能フラグ (Feature Flags)

機能フラグは、Codex CLIの実験的機能や特定の動作を有効 / 無効にする仕組みである。

機能フラグの管理コマンド

# 利用可能な機能フラグの一覧を表示
codex features list

# 機能フラグを有効化
codex features enable shell_snapshot

# 機能フラグを無効化
codex features disable shell_snapshot

プロファイル使用時の保存先

--profile フラグを使用している場合、機能フラグの設定は対象プロファイルに保存される。

# 特定のプロファイルで機能フラグを有効化
codex --profile my-profile features enable codex_hooks

主要な機能フラグ

主要な機能フラグ一覧

フラグ名	説明	デフォルト
shell_snapshot	シェルの状態スナップショット機能を有効化する。 セッション復元時にシェル環境を再現する。	無効
codex_hooks	Codex CLIのフックシステムを有効化する。 ファイル操作・コマンド実行前後に処理を挿入できる。	無効
streaming_diff	コード生成中のリアルタイムdiff表示を有効化する。	有効
multi_agent	マルチエージェントオーケストレーション機能を有効化する。	無効

設定ファイルによる機能フラグの管理

~/.codex/config.toml で機能フラグを永続的に設定できる。

 [features]
 shell_snapshot = true
 codex_hooks = true
 streaming_diff = true
 multi_agent = false

Web検索統合

Codex CLIは、モデルがWeb検索を利用して最新情報にアクセスする機能を提供する。

検索モードの設定

# キャッシュされた結果を使用 (デフォルト)
codex --search cached

# ライブ検索を使用
codex --search live

# Web検索を無効化
codex --search disabled

各検索モードの説明

• cached (デフォルト)

  事前に取得・キャッシュされた検索結果を使用する。

  ネットワークへのリアルタイムアクセスが発生しないためセキュリティが向上する。

  workspace-write サンドボックスとの組み合わせに適している。

  
  

• live

  リアルタイムでWeb検索を実行する。

  最新情報へのアクセスが可能である。

  danger-full-access モードではデフォルトで live が適用される。

  
  

• disabled

  Web検索機能を完全に無効化する。

  ネットワーク遮断環境やオフライン環境での使用に適している。

画像入力

Codex CLIは、画像をプロンプトの入力として使用する機能を提供する。

コマンドラインからの画像入力

# 単一画像の入力
codex -i screenshot.png "この画面のバグを修正してください"

# 長形式フラグ
codex --image design.png "このデザインをReactコンポーネントとして実装してください"

# 複数画像の入力
codex -i before.png -i after.png "変更点を説明してください"

TUI内での画像ペースト

TUIセッション中に画像をクリップボードから直接ペーストして入力することができる。

• ペースト方法

  [Ctrl] + [V] または OS標準のペースト操作で画像を入力欄に貼り付ける。

  ペースト後、画像のプレビューが表示される。

対応形式

• PNG

  スクリーンショット、UIデザイン画像

• JPG / JPEG

  写真、ドキュメントスキャン

• WebP

  Web最適化された画像

主な用途

• スクリーンショットを用いたバグ報告

  UIの不具合箇所のスクリーンショットを入力して修正を依頼する。

  
  

• Figmaエクスポートからのコード生成

  デザインファイルのエクスポート画像をもとにコンポーネントを生成する。

  
  

• 設計図・アーキテクチャ図の解析

  システム設計図を入力して実装の相談を行う。

  
  

• エラーメッセージ画像の解析

  ターミナルやGUIアプリのエラー画面を入力して原因を調査する。

非インタラクティブモード

Codex CLIは、スクリプトや自動化パイプラインで使用するための非インタラクティブモードを提供する。

codex execコマンド

# 単一のタスクを非インタラクティブに実行
codex exec "テストファイルを実行してエラーを修正してください"

# JSON形式で出力
codex exec --output json "コードのドキュメントを生成してください"

# セッション再開対応
codex exec --resume <セッションID> "前回のタスクを続けてください"

JSON出力

--output json フラグを指定することで、構造化されたJSON形式で出力を取得できる。
CI/CDパイプラインやスクリプトから結果を解析する場合に有用である。

codex exec --output json "このPythonファイルのバグを特定してください" | jq '.result'

リモートTUI接続

Codex CLIは、アプリケーションサーバをリモートで動作させ、TUIをローカルで操作するアーキテクチャをサポートする。

基本的な仕組み

• アプリサーバ (リモート)

  Codex CLIのバックエンド処理をリモートサーバで実行する。

  AIモデルへのAPI呼び出し、ファイル操作、コマンド実行をリモートで処理する。

• TUIクライアント (ローカル)

  ローカルのターミナルからリモートのアプリサーバに接続する。

  ローカルマシンのリソースを消費せずにリモート作業を行える。

認証方式

リモートTUI接続には、以下の認証方式がサポートされている。

• localhost-only

  ローカルホストからの接続のみ許可する。

  SSHトンネリングと組み合わせて使用する。

  
  

• capability token

  ケーパビリティトークンによる認証

  共有リンクでのアクセス制御に使用する。

  
  

• signed bearer token

  署名付きBearerトークンによる認証

  エンタープライズ環境での安全な認証に適している。

シェル補完

Codex CLIは、主要なシェルに対してコマンド補完機能を提供する。

 # Bash向けの補完スクリプトを生成
 codex completion bash >> ~/.bashrc
 source ~/.bashrc
 
 # Zsh向けの補完スクリプトを生成
 codex completion zsh >> ~/.zshrc
 source ~/.zshrc
 
 # Fish向けの補完スクリプトを生成
 codex completion fish > ~/.config/fish/completions/codex.fish

補完機能では、以下のものが補完対象となる。

• codex のサブコマンド
• --profile に設定済みのプロファイル名
• --sandbox のモード名
• --model に利用可能なモデル名
• --search のオプション値

Code Reviewワークフロー

Codex CLIは、別エージェントによるコードレビューと承認を行う専用ワークフローをサポートする。

auto-reviewエージェントの動作

approvals_reviewer = "auto_review" を設定することにより、専用のレビューエージェントが以下の審査を行う。

• コードの変更内容を静的解析する。
• セキュリティ上のリスクを評価する。
• データ流出の可能性がある操作を検出する。
• 審査結果に基づいて自動承認または承認要求を判断する。

設定例

 # ~/.codex/config.toml
 approvals_reviewer = "auto_review"
 
 [auto_review]
 # リスクスコアの閾値 (0.0 - 1.0)
 # この値を超えると人間の承認を要求する
 approval_threshold = 0.7
 
 # データ流出チェックを有効化
 check_data_exfiltration = true
 
 # 外部ネットワーク送信の監視
 monitor_network_egress = true

その他のCLIサブコマンド

Codex CLIは、開発・運用に関わる多様なサブコマンドを提供する。

codex app

デスクトップGUIアプリケーションを起動するサブコマンドである。

# Windows / MacOSでデスクトップアプリを起動
codex app

• 対応OS

  Windows / MacOS

  LinuxではTUIが標準インターフェースとなる。

codex cloud

クラウド環境でタスクを実行するサブコマンドである。

# クラウドタスクを実行
codex cloud run "テストスイートを全て実行してレポートを生成してください"

• 特徴

  ローカルマシンのリソースを使用せずにタスクを実行できる。

  長時間実行タスクのバックグラウンド処理に適している。

codex mcp serve

Codex CLI自身をMCP (Model Context Protocol) サーバとして起動するサブコマンドである。

# Codex CLIをMCPサーバとして起動
codex mcp serve

# ポートを指定して起動
codex mcp serve --port 3000

• 用途

  他のMCPクライアント (Claude Code、OpenCode等) からCodexの機能を呼び出す。

  複数のAIツールを統合したワークフローを構築する。

requirements.toml (組織管理)

組織の管理者は requirements.toml を使用して、組織内のCodex CLI使用ポリシーを強制できる。

ポリシー設定例

 # /etc/codex/requirements.toml (システム全体への適用)
 # または ~/.codex/requirements.toml (ユーザレベルへの適用)
 
 [policy]
 # neverポリシーを禁止 (承認なし実行の禁止)
 deny_approval_policy = ["never"]
 
 # danger-full-accessサンドボックスを禁止
 deny_sandbox = ["danger-full-access"]
 
 # --yoloフラグの使用を禁止
 deny_flags = ["--yolo", "--dangerously-bypass-approvals-and-sandbox"]
 
 # 必須のサンドボックスモードを指定
 require_sandbox = "workspace-write"
 
 # 組織のポリシーメッセージ
 policy_message = "セキュリティポリシーにより、danger-full-access モードは使用できません。"

ポリシーの適用範囲

• システムレベル

  /etc/codex/requirements.toml に配置することにより、全ユーザに強制適用される。

• ユーザレベル

  ~/.codex/requirements.toml に配置することにより、特定ユーザに適用される。

• プロジェクトレベル

  .codex/requirements.toml に配置することにより、特定プロジェクトに適用される。

CLIフラグ一覧

下表に、Codex CLIを起動する際に使用できる主要なCLIフラグを示す。

Codex CLI 主要フラグ一覧

フラグ	短縮形	説明	例
--model	なし	使用するモデルを指定する。	codex --model o4-mini
--profile	なし	使用するパーミッションプロファイルを指定する。	codex --profile :workspace
--config	-c	設定値をインラインで上書きする。	codex -c mcp_servers.context7.enabled=false
--sandbox	なし	サンドボックスモードを指定する。	codex --sandbox workspace-write
--ask-for-approval	なし	承認ポリシーを指定する。	codex --ask-for-approval never
--add-dir	なし	書き込み許可ディレクトリを追加する。	codex --add-dir /tmp/build
--image	-i	入力画像ファイルを指定する。	codex -i screenshot.png
--search	なし	Web検索モードを指定する。	codex --search cached
--yolo	なし	サンドボックスと承認を一括バイパスする。	codex --yolo
--last	なし	前回のセッションに復帰する。	codex --last
--output	なし	出力形式を指定する (json, text)。	codex exec --output json

-cフラグによるインライン設定上書き

-c フラグを使用して、設定ファイルの値を起動時にインラインで上書きできる。

# MCPサーバを無効化してCodexを起動
codex -c mcp_servers.context7.enabled=false

# モデルを上書きして起動
codex -c model=gpt-4o

# 複数の設定を上書き
codex -c model=o4-mini -c sandbox=workspace-write

推奨構成例

用途別の推奨構成を以下に示す。

ローカル開発

 # ~/.codex/config.toml
 model = "o4-mini"
 default_permissions = ":workspace"
 
 [sandbox]
 mode = "workspace-write"
 
 [approval]
 policy = "on-request"
 
 [features]
 streaming_diff = true
 codex_hooks = true

# 起動コマンド例
codex --sandbox workspace-write --ask-for-approval on-request

CI/CDパイプライン

 # .codex/config.toml (プロジェクト固有)
 model = "o4-mini"
 default_permissions = ":workspace"
 
 [sandbox]
 mode = "workspace-write"
 
 [approval]
 policy = "never"

# CI/CDでの実行例
codex exec \
     --sandbox workspace-write \
     --ask-for-approval never \
     --output json \
     "テストを実行してカバレッジレポートを生成してください"

マルチテナント環境

 # ~/.codex/config.toml
 model = "gpt-4o"
 approvals_reviewer = "auto_review"
 
 [permissions.tenant-safe]
 description = "マルチテナント安全プロファイル"
 
 [permissions.tenant-safe.filesystem]
 "/workspace" = "write"
 "/workspace/.env" = "none"
 "/workspace/secrets" = "none"
 
 [permissions.tenant-safe.network]
 "*.internal.example.com" = "write"
 
 [auto_review]
 approval_threshold = 0.6
 check_data_exfiltration = true
 monitor_network_egress = true

# マルチテナント環境での起動例
codex --profile tenant-safe --ask-for-approval auto-review

関連ページ

• Codexの設定 - 環境変数
• Codexの設定 - プロファイル
• Codexの設定 - プランモード
• Codexの設定 - コマンド
• Codexの設定 - MCPサーバ