Codex CLI：決定版テクニカルリファレンス

TL;DR: Codexはマルチサーフェスのコーディングエージェントであり、コードベースを読み取り、OSレベルのサンドボックス内でコマンドを実行し、ファイルにパッチを適用し、タスクをクラウドに委任します。5つの中核システム（config.toml、sandbox/approvalモデル、AGENTS.md、MCP、skills）を使いこなせば、Codexは戦力増強装置となります。コンテキスト切り替えにはprofiles、コンテキスト予算の管理には/compact、永続化された作業ゴールには/goal、Codex・Cursor・Ampなどで動作するクロスツールのプロジェクト指示にはAGENTS.mdを活用してください。GPT-5.5（2026年4月23日リリース）がCodexの推奨デフォルトです — Codexでは400Kコンテキストウィンドウ（APIでは1M）、$5/$30 per MTok、Terminal-Bench 2.0で82.7%のSOTAを達成しています。⁸³ CLI v0.130.0（2026年5月8日）時点で、Codexはヘッドレスapp-server制御のためのトップレベルcodex remote-controlコマンド、マルチ環境でのview_image解決、AWS aws loginコンソールログイン認証情報によるBedrock認証、app-serverスレッドのページネーション、共有リンクメタデータと検出可能性制御を備えたバンドルhooksのplugin詳細表示、実行中スレッドでのlive config更新、構成可能なOpenTelemetryトレースメタデータ、LinuxおよびWindowsでのサンドボックス強化を継続的に提供しています。v0.129.0（2026年5月7日）では、モーダルVim編集（/vim）、再設計されたworkflow picker、TUI内蔵の/hooksブラウザ、テーマ対応のステータスライン、マーケットプレイス操作を伴うpluginワークスペース共有、/goalライフサイクルの変更が追加されました。明示的なsandbox/approvalフラグやpermission profilesを、レガシーな--full-autoより優先して使い続けてください。js_replは引き続き削除されています。^86878991

Codexはマルチサーフェスのコーディングエージェントとして動作します。コードを書くチャットボットではありません。CLIはコードベースを読み、サンドボックス内でコマンドを実行し、ファイルにパッチを適用し、MCPを介して外部サービスに接続し、長時間実行されるタスクをクラウドに委任します。ローカルで動きながらもグローバルに思考するのです。同じインテリジェンスが、作業スタイルに応じた5つの異なるサーフェスを支えており、これにはブラウザを乗っ取ることなくCodexを動作させる新しいChrome拡張機能も含まれています。⁹⁰

Codexの利用がカジュアルなものか効果的なものかを分けるのは、5つの中核システムに集約されます。 これらをマスターすれば、Codexは戦力増強装置となります。

1. Configurationシステム: config.tomlを介して動作を制御
2. Sandbox & approvalモデル: Codexが実行できる内容をゲート制御
3. AGENTS.md: プロジェクトレベルの運用契約を定義
4. MCPプロトコル: 外部サービスへの機能拡張
5. Skillsシステム: 再利用可能なドメイン専門知識をパッケージ化

私は数か月にわたり、本番コードベース、CI/CDパイプライン、チームワークフローを横断してClaude Codeと並走させながらCodexを運用してきました。本ガイドはその経験を凝縮し、私が始めた当初に存在してほしかった完全なリファレンスとしてまとめたものです。すべての機能について、実際の構文、リアルな構成例、経験豊富なユーザーでもつまずくエッジケースを掲載しています。

安定性に関する注記: [EXPERIMENTAL]またはunder developmentとマークされた機能は、リリース間で変更される可能性があります。v0.130.0（2026年5月8日）時点で、Codex Cloudとcode modeは引き続き実験的または開発中である一方、コアのCLI、サンドボックス、AGENTS.md、config.toml、Skills、hooks、マルチエージェントツール、pluginsは安定したサーフェスとなっています。v0.130.0では、codex remote-controlトップレベルコマンド（ヘッドレスかつリモート制御可能なapp-serverへのよりシンプルなエントリーポイント）、マルチ環境でのview_image解決、AWS aws loginコンソールログイン認証情報によるBedrock認証、unloaded / summary / fullターンビューを備えたapp-serverスレッドのページネーション、共有リンクメタデータと検出可能性制御を備えたバンドルhooksのplugin詳細表示、live app-server config更新（実行中スレッドが再起動なしにconfigの変更を取り込みます）、codex exec起動バナーから「research preview」表記を削除、構成可能なOpenTelemetryトレースメタデータ、Linuxサンドボックスの起動時強化、デスクトップランタイムバイナリキャッシュへのWindowsサンドボックス権限付与が追加されました。⁹¹ v0.129.0（2026年5月7日）では、composerでのモーダルVim編集（/vim + 構成可能なデフォルトモード）、再設計されたTUI workflow picker（resume/forkがしやすく、生のスクロールバックも閲覧可能）、/hooksブラウザ、オプションでPR + branchサマリーを表示するテーマ対応ステータスライン、pluginワークスペース共有 + マーケットプレイス操作 + 共有アクセス制御 + ソースフィルタリング、/goalライフサイクルの変更（実験的ゴールはオプトインし直さない限りresume後も一時停止状態のまま）、Linuxサンドボックスの起動時強化、Windowsサンドボックスの信頼性改善、上流のセキュリティパッチを取り込んだBubblewrap 0.11.2へのバンプが追加されました。⁸⁹ v0.128.0（2026年4月30日）では、永続化された/goalワークフロー、codex update、構成可能なTUIキーマップ、拡張されたpermission profilesが導入されました。レガシーな--full-autoは引き続き非推奨で、js_replは引き続き削除されています。⁸⁶⁸⁷

主なポイント

• 5つのサーフェス、1つの頭脳: CLI、デスクトップアプリ、IDE拡張機能、クラウドタスク、そして新しいChrome拡張機能のすべてが、同じGPT-5.x-Codexの知能を共有しています。ワークフローに合ったサーフェスを選びましょう。⁹⁰
• OSレベルのサンドボックス: Codexはコンテナ内ではなく、カーネルレベルでファイルシステムとネットワークの制限を強制します（macOSではSeatbelt、LinuxではLandlock + seccomp）。
• AGENTS.mdはツール横断: プロジェクトの指示は、Codex、Cursor、Copilot、Amp、Jules、Gemini CLI、Windsurf、Cline、Aider、Zed、そして60,000以上のオープンソースプロジェクトで機能します。一度書けば、どこでも使えます。
• プロファイルでコンテキスト切り替えのオーバーヘッドを削減: 名前付きの設定プリセット（fast、careful、auto）を定義し、--profileで切り替えられます。
• コンテキスト管理が重要: GPT-5.4は1Mのコンテキストを提供し、GPT-5.4 miniはサブエージェント作業向けに400Kを、GPT-5.3-Codexは272Kの入力を提供します。/compact、的を絞ったプロンプト、@file参照を活用して、トークン予算を積極的に管理しましょう。

本ガイドの使い方

これは2,500行を超えるリファレンスです。ご自身の経験レベルに合った場所から始めてください。

末尾のクイックリファレンスカードでは、すべての主要コマンドを一覧で確認できます。

Codexの仕組み: メンタルモデル

機能の詳細に入る前に、Codexのアーキテクチャがあなたの作業全般にどう影響するかを理解しておきましょう。システムは、共有された知能レイヤーに支えられた4つのサーフェス上で動作します。

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                        │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │ │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│  │   MCP   │  │ Skills  │  │  Apps   │  │  Search │   │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘   │
│  External tools, reusable expertise, ChatGPT            │
│  connectors, web search (cached + live)                  │
├─────────────────────────────────────────────────────────┤
│  SECURITY LAYER                                          │
│  ┌─────────────────────────────────────────────────┐    │
│  │    Sandbox (Seatbelt / Landlock / seccomp)      │    │
│  │    + Approval Policy (untrusted → never)        │    │
│  └─────────────────────────────────────────────────┘    │
│  OS-level filesystem + network restrictions              │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         GPT-5.x-Codex Intelligence              │    │
│  │   Tools: Shell, Patch, Read, Web Search         │    │
│  │   (legacy artifact, read_file, grep_files       │    │
│  │    removed in v0.117.0)                          │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens          │
└─────────────────────────────────────────────────────────┘

コアレイヤー: GPT-5.xモデルファミリーがすべてを支えています。2026年4月23日時点で、利用可能な場合はgpt-5.5が推奨モデルです。Codexでは400Kコンテキスト（APIでは1M）、Terminal-Bench 2.0で82.7%のSOTAを達成しています。ロールアウト中はgpt-5.4がフォールバックのデフォルトとして残ります（1Mコンテキスト、ネイティブのコンピューター使用）。⁸³⁶⁴ ファイルを読み、パッチを書き、シェルコマンドを実行し、コードベースについて推論します。コンテキストが満杯になると、Codexは会話をコンパクトにして領域を解放します。このレイヤーはトークンを消費します。

セキュリティレイヤー: Codexが実行するすべてのコマンドは、OSレベルのサンドボックスを通過します。macOSではAppleのSeatbeltフレームワークがカーネルレベルの制限を強制します。LinuxではLandlock + seccompがファイルシステムとシステムコールへのアクセスをフィルタリングします。サンドボックスはコンテナ内ではなく、カーネルレベルで動作します。続いて承認ポリシーが、人間の確認をいつ求めるかを決定します。

拡張レイヤー: MCPは外部サービス（GitHub、Figma、Sentry）と接続します。Skillsは再利用可能なワークフローをパッケージ化し、Codexがオンデマンドで読み込みます。AppsはChatGPT connectorsに接続します。Web searchはインターネットからリアルタイムのコンテキストを追加します。

サーフェスレイヤー: CLIはターミナルのパワーユーザーと自動化向け。デスクトップアプリはマルチスレッドのプロジェクト管理向け。IDE拡張機能は編集・コンパイル・テストのループ向け。クラウドは独立して実行される非同期タスク向けです。

重要な洞察: ほとんどのユーザーは1つのサーフェスしか使いません。パワーユーザーは4つすべてを使います。長時間実行タスクにはクラウド、決定論的なリポジトリ操作にはCLI、緊密なコーディングループにはIDE拡張機能、プランニングと調整にはデスクトップアプリといった使い分けです。

目次

1. Codexのインストール方法
2. クイックスタート: 初めてのセッション
3. コアインタラクションサーフェス
4. 設定システムの詳細
5. どのモデルを選ぶべきか？
6. Codexのコストは？
7. 意思決定フレームワーク
8. サンドボックスと承認システムの仕組みは？
9. AGENTS.mdの仕組みは？
10. Hooks
11. MCP（Model Context Protocol）とは？
12. Code Mode
13. JavaScript REPLランタイム
14. Skillsとは？
15. Plugins
16. Plan Modeとコラボレーション
17. メモリシステム
18. セッション管理
19. 非対話モード（codex exec）
20. Codex Cloudとバックグラウンドタスク
21. Codex Desktop App
22. GitHub ActionとCI/CD
23. Codex SDK
24. パフォーマンス最適化
25. 問題のデバッグ方法は？
26. エンタープライズ展開
27. ベストプラクティスとアンチパターン
28. ワークフローレシピ
29. 移行ガイド
30. クイックリファレンスカード
31. 変更履歴
32. 参考文献

Codexをインストールするには？

パッケージマネージャー

# npm (recommended)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.Codex

# Upgrade to latest
npm install -g @openai/codex@latest

直接インストールスクリプト（v0.106.0+）

macOSとLinuxでは、1行で実行できるインストールスクリプトがGitHubのリリースアセットとして提供されています:⁶⁰

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | sh

このスクリプトはプラットフォームとアーキテクチャを自動検出し、適切なバイナリをダウンロードしてPATH上に配置します。

バイナリダウンロード

npmやHomebrewがない環境では、GitHub Releasesからプラットフォーム別のバイナリをダウンロードできます¹:

システム要件

• macOS: Apple SiliconまたはIntel（Seatbeltによる完全なsandboxサポート）
• Linux: x86_64またはarm64（Landlock + seccompによるsandbox）
• Windows: 制限付きトークンによるネイティブsandbox（v0.100.0でexperimentalから昇格）。WSLもサポートされています²

認証

codex login                  # Interactive OAuth (recommended)
codex login --device-auth    # OAuth device code flow (headless)
codex login --with-api-key   # API key from stdin
codex login status           # Check auth state (exit 0 = logged in)
codex logout                 # Clear stored credentials

認証方法は2つあります。

1. ChatGPT Account（推奨）: 既存のPlus、Pro、Team、Business、Edu、Enterpriseサブスクリプションでサインインします。cloud tasksを含むすべての機能にアクセスできます。
2. API Key: CODEX_API_KEY環境変数、またはcodex login --with-api-keyで設定します。一部の機能（cloud threads）は利用できない場合があります。

Expert tip: 認証情報の保存先は、config.tomlのcli_auth_credentials_storeで設定できます。選択肢はfile（デフォルト）、keyring（OS keychain）、auto（利用可能ならkeyring、なければfileにフォールバック）です。

シェル補完

# Generate completions for your shell
codex completion bash > /etc/bash_completion.d/codex
codex completion zsh > ~/.zsh/completions/_codex
codex completion fish > ~/.config/fish/completions/codex.fish

インストールを確認する

codex --version
# codex-cli 0.130.0

クイックスタート：最初のセッション

5分で、何もない状態から作業を始められるところまで進めます。

1. インストールして認証する:

npm i -g @openai/codex          # Install
codex login                      # Log in with your OpenAI account

2. プロジェクトに移動する:

cd ~/my-project                  # Any git repo works

3. Codexを起動する:

codex

インタラクティブなTUIが表示されます。Codexはプロジェクト構成を自動的に読み取ります。

4. 質問する:

> What does this project do? Summarize the architecture.

Codexが主要なファイルを読み取り、コードベースを説明します。デフォルトのsuggestモードでは変更は行われません。

5. 変更を加える:

> Add input validation to the login endpoint

Codexは編集内容をdiffとして提案します。確認してyで承認するか、nで却下します。

6. slash commandを使う:

> /plan Refactor the database layer to use connection pooling

Codexは実行せずにplanを作成します。planを確認し、承認すると実行が始まります。

7. 作業内容を確認する:

> /diff

現在のセッションでCodexが行ったすべての変更を確認できます。

次に行うこと: - プロジェクト指示としてAGENTS.mdを設定する（AGENTS.mdはどのように機能しますか？を参照） - ワークフローに合わせてprofileを設定する（Profilesを参照） - 非インタラクティブな自動化にはcodex execを試す（Non-Interactive Modeを参照）

コアインタラクションサーフェス

Codexは、同じインテリジェンスを基盤とする4つの異なるインターフェースを提供します。各サーフェスは、異なるワークフローパターンに最適化されています。

1. インタラクティブ CLI（Terminal UI）

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-5.5            # Specify model
codex --sandbox workspace-write --ask-for-approval on-request

ターミナルUIは、以下を備えたフルスクリーンアプリケーションです。

• コンポーザー: プロンプトを入力し、@でファイルを添付、!プレフィックスでシェルコマンドを実行
• 出力ペイン: ストリーミングされるモデルの応答、ツール呼び出し、コマンド出力
• ステータスバー: モデル、トークン使用量、gitブランチ、サンドボックスモード

主要なTUIショートカット:

ステータスラインの変更（v0.121.0）: ステータスラインの旧コンテキストウィンドウメーターは、コンテキストウィンドウの使用率を示すコンテキスト割合インジケーターに置き換えられました。ステータスラインを解析するスクリプトやhookがある場合は、このフォーマット変更を確認してください。⁸² また、新しいバージョンが利用可能になると、Codexは CLI のアップデート通知を表示します。

TUIで利用可能なスラッシュコマンド:

ワークフローピッカーの再設計（v0.129.0）: 再設計されたピッカーから、resumeとforkにより簡単にアクセスできるようになりました。さらに、新しいraw scrollbackモードにより、コマンドやモデル出力をそのままコピーする必要がある場面で、レンダリング前のトランスクリプトをスクロールできます。長いデバッグセッションのトリアージ時や、出力を別のツールにパイプする際に便利です。⁸⁹

2. Codex Desktop App（macOS + Windows）

codex app                    # Launch desktop app (auto-installs if missing)

デスクトップアプリでは、 CLI にはない機能が追加されます。

• マルチタスク: 複数のプロジェクトをまたいで、複数の並列エージェントを同時に実行
• Git worktreeによる分離: 各スレッドがリポジトリの分離されたコピー上で作業
• インライン差分レビュー: アプリを離れずに変更をステージング、リバート、コミット
• 統合ターミナル: スレッドごとのターミナルでコマンド実行
• 会話のフォーク: 会話を分岐させて代替案を探索
• フローティングポップアウトウィンドウ: 会話を切り離してポータブルウィンドウ化
• オートメーション: 定期タスクのスケジュール設定（issueトリアージ、CI監視、アラート対応）

アプリと CLI の使い分け: 複数のワークストリームを調整する場合や、視覚的な差分レビューが必要な場合はデスクトップアプリを使用してください。ターミナルでの組み合わせ可能性、スクリプティング、CI/CD統合を求める場合は CLI を使用してください。

3. IDE拡張機能（VS Code、Cursor、Windsurf）

Codex IDE拡張機能は、エディタに直接統合されます。

• デフォルトでエージェントモード: ファイルの読み取り、編集、コマンド実行を実施
• インライン編集: アクティブなファイルでコンテキスト対応の提案
• 共有セッション: CLI とIDE拡張機能間でセッションを同期
• 同一の認証: ChatGPTアカウントまたは API キーでサインイン

VS CodeマーケットプレイスまたはCursor/Windsurf拡張機能ストアからインストールしてください。³

4. Codex Cloud [EXPERIMENTAL]

クラウドタスクは、OpenAI管理の環境で非同期に実行されます。

• Fire and forget: ローカルマシンと独立して実行されるタスクをキューに登録
• 並列実行: 複数のクラウドタスクを同時実行
• PR作成: Codexが完了した作業からプルリクエストを作成
• ローカルへの適用: codex apply <TASK_ID>でクラウドの結果をローカルリポジトリに取り込み

codex cloud list             # List recent cloud tasks
codex apply <TASK_ID>        # Apply diff from a specific cloud task

クラウドタスクはchatgpt.com/codexからもアクセスできます。⁴

5. Codex for Chrome [NEW]

Codexは、Chrome向けのブラウザ拡張機能としても提供されており、 CLI、デスクトップアプリ、IDE拡張機能、クラウドに加えて5番目のサーフェスを追加します。この拡張機能は、通常のブラウジングを乗っ取るのではなく、隣り合って動作するように設計されています。Codexは複数のタブにまたがってバックグラウンドで並列に動作し、どのサイトに介入させるかはユーザーがコントロールします。⁹⁰

• タブ並列実行: Codexはフォアグラウンドのタブをロックすることなく、複数のタブで同時に動作します。
• サイト単位の制御: Codexが操作できるWebサイトをallow-listで指定します。デフォルトはアクセス不可です。
• ワークベンチとしてのブラウザ: この拡張機能は、ページが情報の正典となるアプリやWebサイト作業（管理コンソール、社内ダッシュボード、コンテンツ管理UI、チケットシステムなど）に最適です。ローカルリポジトリでの CLI の代替を意図したものではありません。
• 同じ頭脳: Codex for Chromeは、他のサーフェスが使用するのと同じGPT-5.x-Codexのインテリジェンスで動作します。そのため、 CLI で機能するAGENTS.mdやスキル設定があれば、同じ慣習がブラウザ駆動の作業にも引き継がれます。

Codex Chrome拡張機能ドキュメントからインストールしてください。⁹⁰

設定システムの詳細

CodexはTOMLを設定に使用します。優先順位の階層を理解することは重要です。設定が衝突した際にどの値が優先されるかを決定するためです。

優先順位（高いものから低いものへ）

1. セッションオーバーライド（最高）: CLI フラグ（--model、--sandbox、--ask-for-approval、--search、--enable/--disable、--profile）および -c key=value オーバーライド
2. プロジェクト設定（.codex/config.toml、CWDからプロジェクトルートまで上方向に検索され、最も近いディレクトリが優先されます）
3. ユーザー設定（$CODEX_HOME/config.toml、デフォルトは ~/.codex/config.toml）
4. システム設定（Unixでは /etc/codex/config.toml）
5. 組み込みデフォルト（最低）

requirements.toml はポリシー制約レイヤーとして機能し、通常の設定マージ後にユーザーが選択できる値を制限します。Enterprise Deployment を参照してください。

設定ファイルの場所

エキスパートのヒント: CODEX_HOME 環境変数はデフォルトの ~/.codex ディレクトリをオーバーライドします。CI/CDやマルチアカウント構成で役立ちます。

設定リファレンス完全版

# ~/.codex/config.toml — annotated reference

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.5"                      # Recommended model when available
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 272000           # Token count available to active model (override)
model_auto_compact_token_limit = 200000 # Threshold triggering automatic history compaction
model_reasoning_effort = "medium"       # minimal|low|medium|high|xhigh (model-dependent)
model_reasoning_summary = "auto"        # auto|concise|detailed|none
model_verbosity = "medium"              # low|medium|high
personality = "pragmatic"               # none|friendly|pragmatic
review_model = "gpt-5.5"               # Optional model for /review command
oss_provider = "lmstudio"              # lmstudio|ollama (used with --oss)

# ─── Sandbox & Approval ───────────────────────────────
sandbox_mode = "workspace-write"        # read-only|workspace-write|danger-full-access
approval_policy = "on-request"          # untrusted|on-request|never

[sandbox_workspace_write]
writable_roots = []                     # Additional writable paths
network_access = false                  # Allow outbound network
exclude_tmpdir_env_var = false          # Exclude $TMPDIR from sandbox
exclude_slash_tmp = false               # Exclude /tmp from sandbox

# ─── Web Search ────────────────────────────────────────
web_search = "live"                     # Web search mode (constrained by allowed modes)

# ─── Instructions ──────────────────────────────────────
developer_instructions = ""             # Additional injected instructions
model_instructions_file = ""            # Custom instructions file path
compact_prompt = ""                     # Custom history compaction prompt

# ─── Shell Environment ─────────────────────────────────
allow_login_shell = false               # Allow login shell semantics (loads .profile/.zprofile)

[shell_environment_policy]
inherit = "all"                         # all|core|none
ignore_default_excludes = false         # Set true to keep KEY/SECRET/TOKEN vars
exclude = []                            # Glob patterns to exclude
set = {}                                # Explicit overrides
include_only = []                       # Whitelist patterns

# ─── Authentication ────────────────────────────────────
cli_auth_credentials_store = "file"     # file|keyring|auto
forced_login_method = "chatgpt"         # chatgpt|api
mcp_oauth_callback_port = 0            # Fixed port for MCP OAuth callback (0 = random)
mcp_oauth_credentials_store = "auto"   # auto|file|keyring

# ─── History & Storage ─────────────────────────────────
[history]
persistence = "save-all"                # save-all|none
max_bytes = 0                           # Cap size (0 = unlimited)

tool_output_token_limit = 10000         # Max tokens per tool output
log_dir = ""                            # Custom log directory

# ─── UI & Display ──────────────────────────────────────
file_opener = "vscode"                  # vscode|vscode-insiders|windsurf|cursor|none
hide_agent_reasoning = false
show_raw_agent_reasoning = false
check_for_update_on_startup = true

[tui]
notifications = false                   # Enable notifications
notification_method = "auto"            # auto|osc9|bel
animations = true
show_tooltips = true
alternate_screen = "auto"               # auto|always|never
status_line = ["model", "context-remaining", "git-branch"]

# ─── Project Trust ─────────────────────────────────────
project_doc_max_bytes = 32768           # Max AGENTS.md size (32 KiB)
project_doc_fallback_filenames = []     # Alternative instruction filenames
project_root_markers = [".git"]         # Project root detection

# ─── Feature Flags ─────────────────────────────────────
# Use `codex features list` for current names/stages/defaults.
[features]
shell_tool = true                       # Shell command execution (stable)
collaboration_modes = true              # Plan mode (stable)
personality = true                      # Personality selection (stable)
request_rule = true                     # Smart approvals (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
command_attribution = true              # Codex co-author in commits (v0.103.0+)
request_user_input = true               # Allow agent to ask clarifying questions in Default mode (v0.106.0+)
multi_agent = false                     # Enable multi-agent collaboration tools (v0.102.0+)
apply_patch_freeform = false            # Expose freeform apply_patch tool
apps = false                            # ChatGPT Apps/connectors (experimental)
child_agents_md = false                 # AGENTS.md guidance (experimental)
runtime_metrics = false                 # Runtime summary in turns
search_tool = false                     # Enable search_tool_bm25 for Apps discovery

# ─── Multi-Agent Roles (v0.102.0+) ───────────────────
[agents]
max_threads = 4                         # Maximum concurrent agent threads

[agents.explorer]
description = "Read-only codebase navigator"
config_file = "~/.codex/profiles/explorer.toml"

# ─── Notifications ────────────────────────────────────
notify = ["terminal-notifier", "-title", "Codex"]  # Command for notifications

# ─── Per-Project Overrides ────────────────────────────
[projects."/absolute/path/to/repo"]
trust_level = "trusted"                 # Per-project trust override

プロファイル

異なる作業モード向けの名前付き設定プリセットです。

# Define profiles in ~/.codex/config.toml

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

[profiles.careful]
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.auto]
model = "gpt-5.4"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

プロファイルの有効化:

codex --profile fast "quick refactor"
codex --profile careful "security audit"
codex -p auto "fix CI"

エキスパートのヒント: 設定の最上位に profile = "fast" を指定すると、デフォルトプロファイルとして設定できます。セッション単位では --profile でオーバーライドできます。

カスタムモデルプロバイダー

Azure、AWS Bedrock、ローカルモデル、またはプロキシサービスへの接続:

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }
env_key = "AZURE_OPENAI_API_KEY"

# Built-in amazon-bedrock provider (v0.123.0+, first-class in v0.124.0+)
# AWS SigV4 signing + credential-based auth; AWS profile selectable via the
# nested `aws.profile` field (NOT a top-level `aws_profile` key).
# v0.130.0+ also accepts credentials from `aws login` (the AWS console-login
# flow) — Codex resolves the cached console-login session for the chosen
# profile if static keys are absent.
[model_providers.amazon-bedrock]
name = "Amazon Bedrock"

[model_providers.amazon-bedrock.aws]
profile = "default"                   # any profile from ~/.aws/credentials
# Region/credential resolution otherwise follows the standard AWS chain;
# v0.130.0 added support for `aws login` console-login profiles in addition
# to static access keys and IAM role assumption.[^168]

[model_providers.ollama]
name = "Ollama (Local)"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

警告: chat/completions ワイヤー API（wire_api = "chat"）はOpenAIホスト型モデルでは非推奨となり、OpenAIは2026年2月に削除すると発表しました。³⁴ ローカルプロバイダー（Ollama、LM Studio）では引き続きこの形式が受け付けられる場合があります。OpenAIエンドポイントについては、代わりに wire_api = "responses" を使用してください。

--oss フラグでローカルモデルを使用します:

codex --oss "explain this function"               # Uses default OSS provider
codex --oss --local-provider lmstudio "explain"   # Explicit LM Studio
codex --oss --local-provider ollama "explain"      # Explicit Ollama

または設定で指定します:

model_provider = "oss"
oss_provider = "lmstudio"   # or "ollama"

インライン設定オーバーライド

任意の設定値をコマンドラインからオーバーライドできます:

codex -c model="gpt-5.5" "refactor the API"
codex -c 'sandbox_workspace_write.network_access=true' "install dependencies"
codex -c model_reasoning_effort="xhigh" "debug the race condition"

## どのモデルを選ぶべきか

### 利用可能なモデル（2026年4月時点）

| Model | Input / Total Context | Default Reasoning | Best For |
|-------|--------:|-------------------|----------|
| **gpt-5.5**（Codex） | 400K / 400K | `medium` | **新フラッグシップ（2026年4月23日）** — 82.7% Terminal-Bench 2.0 SOTA。ほとんどのCodexタスクで推奨されるデフォルト。**APIでは**：1Mのコンテキストウィンドウ。[^160] |
| **gpt-5.5-pro** | 1M / 1M | `high` | GPT-5.5上の最高エフォート層（2026年4月24日、APIで利用可能）[^160] |
| **gpt-5.4** | 1M / 1M | `medium` | 旧フラッグシップ。GPT-5.5が各サーフェスに展開されるまでデフォルトとして維持 |
| **gpt-5.4-mini** | 400K / 400K | `medium` | サブエージェント業務やシンプルなタスク向け — GPT-5.4のクォータの30%、2倍の速度[^81] |
| **gpt-5.3-codex** | 272K / 400K | `medium` | コーディング特化：複雑なソフトウェアエンジニアリング |
| **gpt-5.3-codex-spark** | 128K / 128K | `high` | ほぼ瞬時のイテレーション、テキストのみ（Proユーザー、Cerebrasパートナーシップ）[^69] |
| **gpt-5.2-codex** | 272K / 400K | `medium` | レガシーモデル。OpenAIは2026年7月23日のシャットダウンに伴う代替として`gpt-5.4`を提示[^165] |
| **gpt-5.1-codex-mini** | 272K / 400K | `medium` | レガシーのコスト重視モデル。OpenAIは2026年7月23日のシャットダウンに伴う代替として`gpt-5.4-mini`を提示[^165] |

> **GPT-5.5（2026年4月23日）** は、複雑なコーディング、コンピューター操作、ナレッジワーク、リサーチワークフローなど、ほとんどのCodexタスクにおいてOpenAIが推奨する選択肢です。Codex CLI / web / desktopでは4月23日からChatGPT Plus / Pro / Business / Enterprise / Edu / Go向けに、OpenAI APIでは4月24日から利用可能となります。**コンテキストウィンドウ：Codexでは400K、APIでは1M** — Codexはサブスクライバー層全体でスループットとコストのバランスを取るためにウィンドウを400Kに制限しています。APIでは1M全体が公開されます。価格（API）：**入力$5 / 出力$30 per MTok**（GPT-5.4レートの2倍。OpenAIはトークン効率の改善後で実質約20%増としています）。ベンチマーク：**82.7% Terminal-Bench 2.0**（公開モデル全体で現行SOTA）、84.9% GDPval（44職種）、78.7% OSWorld-Verified、98.0% Tau2-bench Telecom（プロンプトチューニングなし）。OpenAIはローンチ前にGPT-5.5 + Codexを社内で活用し、サービング基盤を書き直しました — その結果、トークン生成速度が20%向上しています。[^160]
>
> GPT-5.4はすべてのCodexサーフェス（CLI、app、IDE extension、cloud）で引き続き利用可能です。[^66] 正確なモデルリストはアカウントとロールアウト状況によって異なります。ローカルキャッシュをご確認ください：`~/.codex/models_cache.json`。
>
> **非推奨化に関する注記（2026年3月11日）**：GPT-5.1モデルはChatGPTで利用できなくなりました。既存の会話は自動的にGPT-5.3 Instant、GPT-5.4 Thinking、またはGPT-5.4 Proに引き継がれます。GPT-5.1-Codex-Miniは、コスト重視のワークロード向けにAPIおよびCLI経由で引き続き利用できます。[^73]
>
> **無料層に関する注記（2026年5月5日）**：GPT-5.5 Instantは2026年5月5日にChatGPT無料層に展開されました。これによりGPT-5.5ファミリーの対象が有料プランの枠を超えて広がりますが、Codex CLIへのアクセスには引き続き対象となるPlus / Pro / Business / Enterprise / Edu / Goサブスクリプション、またはAPIキーが必要です。[^169]
>
> **GPT-5.4 mini（2026年3月17日）**：GPT-5.4の小型・高速バリアントで、400Kコンテキストを$0.75/$4.50 per MTokで提供 — GPT-5.4のクォータの30%しか消費しません。サブエージェント委譲に最適です：GPT-5.4にプランニングと調整を任せつつ、GPT-5.4 miniのサブエージェントに狭いサブタスク（コードベース検索、ファイルレビュー、ドキュメント処理）を並列で処理させましょう。[^81]

### モデル選択フローチャート

```text
Is this a quick fix or simple question?
├─ Yes → gpt-5.1-codex-mini (fastest, cheapest)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (near-instant, Pro only)
   │  └─ No
   │     ├─ Subagent or parallel subtask (search, review, processing)?
   │     │  ├─ Yes → gpt-5.4-mini (30% of GPT-5.4 quota, 2x faster)
   │     │  └─ No
   │     │     ├─ Pure coding task (refactor, migration, feature build)?
   │     │     │  ├─ Yes → gpt-5.3-codex (coding specialist, 272K context)
   │     │     │  └─ No → gpt-5.5 (new flagship: 400K context in Codex / 1M in API, 82.7% Terminal-Bench 2.0 SOTA)
   └─ Still unsure? → gpt-5.5

Reasoning Effort

応答前にモデルがどれだけ「考える」かを制御します：

サポートされるレベルはモデルに依存します。minimalはGPT-5モデルでのみ利用可能です。すべてのモデルがすべてのレベルをサポートしているわけではありません。

codex -c model_reasoning_effort="xhigh" "find the race condition"

エキスパートのヒント：xhigh推論は同じプロンプトに対してmediumの3〜5倍のトークンを消費する場合があります。追加の思考が見合うほど真に難しい問題のために温存しましょう。

TUIクイック推論コントロール（v0.124.0以降）。⁸⁵ インタラクティブなTUIセッションでは、Alt+, で推論を1段階下げ、Alt+. で1段階上げます — セッション途中の難問に対して、/effortや-cを使わずに一時的にmedium → high → xhighへとランプアップさせたいときに便利です。セッション中にモデルアップグレードを受け入れると、推論は前のレベルを引き継ぐのではなく、新しいモデルのデフォルトにリセットされます。

モデルの切り替え

セッションの途中でモデルを切り替えるには、/modelスラッシュコマンドを使うか、--model / -mで実行ごとに指定します：

codex -m gpt-5.3-codex-spark "pair with me on this component"

Codexの料金は？

機能についてはモデルの選択を、タスクごとに適切なモデルを選ぶ際の指針については意思決定フレームワークもご覧ください。

ChatGPTプラン経由でのアクセス

Codexの利用可否は、お使いのChatGPTプランと組織設定によって異なります。⁵¹

2026年4月の価格更新： Business年払い価格が$25から$20/シート/月に値下げされました。BusinessおよびEnterpriseワークスペースで、従量課金制のCodex専用シートが利用可能になりました。固定シート料金なしで、トークン消費量に基づいて課金されます。⁷⁹ 有料プラン向けのプロモーション2倍レート制限（2026年2月のDesktop Appローンチ時のもの）は引き続き有効です。¹⁶

2026年5月の利用制限ブースト（2026年5月31日まで）： PlusプランのCodexは25倍の5時間制限で稼働し（標準の20倍ブーストに対して）、$100/月のティアは同期間中2倍になります。この期間を活用して、通常の5時間の壁にぶつかることなく、より長いクラウドタスクのバッチや高スループットのエージェント実行を進めましょう。⁸⁹

クレジットコスト

Codexの操作は、プラン割り当てからクレジットを消費します。

EnterpriseおよびEduプランでは、契約割り当てに応じてクレジットがスケールします。現在の使用状況はTUIで/statusを確認してください。

API課金

API経由でCodexを使用する場合、OpenAIは選択したモデルの標準OpenAI API価格に基づいてトークン単位で課金します（適用可能なプロンプトキャッシュ割引も含みます）。最新のレートはAPI公式価格ページをご確認ください。²⁰

コスト最適化の戦略

1. プロファイルを活用する：日常的なタスク向けにgpt-5.1-codex-miniとmodel_reasoning_effort = "low"を組み合わせたfastプロファイルを作成しましょう
2. 高い推論レベルは温存する：xhighは3〜5倍のトークンを消費するため、本当に難しい問題にのみ使用してください
3. --ephemeralを使う：CI/CDではセッション永続化をスキップしてオーバーヘッドを削減します
4. 推論サマリーを最小化する：説明が不要な場合はmodel_reasoning_summary = "none"を設定しましょう
5. execモードでバッチ処理する：codex execは自動化ワークフロー向けにTUIのオーバーヘッドを回避できます
6. 使用状況を監視する：TUIの/statusと組織の課金ダッシュボードを確認してください

実際のコスト例

一般的なタスクでの代表的なAPIコスト（gpt-5.3-codex、標準価格、medium推論）：

コストは推論レベル、キャッシュ、会話の長さによって変動します。日常的なタスクにはgpt-5.1-codex-miniを使うことで、コストを約40〜60%削減できます。キャッシュされた入力トークンは割引価格で課金されます。

隠れたトークンのオーバーヘッド

すべてのツール呼び出しは、目に見えるプロンプトを超えてトークンを追加します。

エキスパート向けTip： TUIの/statusで実際の使用状況を監視しましょう。トークン数には目に見えるメッセージだけでなく、すべてのオーバーヘッドが含まれます。コストが想定外に膨らんだ場合は、接続されているMCPサーバーの数を確認してください。各サーバーがAPI呼び出しごとにツール定義を追加するからです。

チームのコスト管理

チームのコスト管理戦略： - requirements.tomlを設定する — 組織全体でモデルと推論レベルの上限を強制します - CI/CDにはgpt-5.1-codex-miniを使う — 自動化パイプラインで最大限の推論が必要になることはほとんどありません - プロファイルベースの予算管理 — 適切なコスト上限を設けたci、review、devプロファイルを定義します - OpenTelemetryで監視する — エンタープライズ環境では、既存の可観測性スタックに使用状況テレメトリをエクスポートできます

意思決定フレームワーク

各サーフェスの使い分け

各サンドボックスモードの使い分け

各推論レベルの使い分け

Plan モード vs 直接実行

Will Codex need to change more than 3 files?
│
├── YES → Use Plan Mode (/plan)
│         Codex designs the approach BEFORE making changes.
│         You review and approve the plan.
│         Best for: refactors, new features, migrations
│
└── NO → Is the change well-defined?
         │
         ├── YES → Direct execution
         │         Just describe the task. Codex executes immediately.
         │         Best for: bug fixes, small features, test additions
         │
         └── NO → Use Plan Mode (/plan)
                  Let Codex explore and propose an approach first.
                  Best for: unfamiliar codebases, ambiguous requirements

Steer モード: Enter vs Tab

目安：Enter は「止まって、今これを聞いて」。Tab は「終わったら、これもやって」。

Desktop App vs CLI

How do you prefer to work?
│
├── Terminal-first → Use CLI
│   │
│   ├── Single focused task → codex (interactive TUI)
│   ├── Scripted automation → codex exec (non-interactive)
│   └── Quick one-shot → codex exec "prompt" -o result.txt
│
└── Visual/multi-project → Use Desktop App
    │
    ├── Multiple parallel tasks → Multi-thread with worktree isolation
    ├── Visual diff review → Built-in Git diff viewer
    ├── Scheduled automation → Automations tab
    └── Voice-driven → Ctrl+M for voice dictation

どのプロファイル？

タスクに合わせて事前構成済みプロファイルを選択します：

config.toml の設定：

# Default profile
profile = "default"

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"

[profiles.careful]
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"

[profiles.pair]
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

[profiles.ci]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

セッションごとにプロファイルを切り替え：codex --profile careful

サンドボックスと承認システムはどのように動作するのか？

Codexは2層のセキュリティモデルを採用しており、技術的に何が可能かとCodexがいつ人間の承認を求めるかを分離しています。このアプローチはClaude Codeの権限システムとは根本的に異なります。Codexはカーネルレベルで制限を強制するのです。⁵ 組織全体で管理者が強制するrequirements.tomlの制約については、Enterprise Deploymentもご覧ください。

第1層: サンドボックス（何が可能か）

サンドボックスは、OSネイティブのメカニズムを使ってファイルシステムとネットワークアクセスを制御します。

プラットフォーム固有の強制:

• macOS: Appleの Seatbelt フレームワークを sandbox-exec 経由で使用し、ランタイムにコンパイルされるモード固有のプロファイルがカーネルによって強制されます⁶。v0.121.0以降、macOSサンドボックスプロファイルは特定の Unixソケット（例: docker.sock、エディタIPCソケット）を許可リストに登録でき、プライベートDNS解決はデフォルトでブロックされなくなりました。⁸²
• Linux: ファイルシステム制限のための Landlock と、システムコールフィルタリングのための seccomp を使用します。スタンドアロンのヘルパープロセス（codex-linux-sandbox）が多層防御による分離を提供します。⁵ Bubblewrap（bwrap）はベンダー化され、Linuxビルドの一部としてコンパイルされます（v0.100.0でオプションから昇格）⁷。v0.117.0ではレガシーカーネル設定の古いディストリビューションでのサンドボックスの信頼性が向上しました。⁷⁵ v0.129.0ではLinuxでのサンドボックス起動が強化され、ベンダー化されたBubblewrapが上流のセキュリティパッチを含む0.11.2にバンプされました。v0.130.0ではさらに起動の強化が追加されています。⁸⁹⁹¹
• Windows: 制限されたトークンを使うネイティブサンドボックス（v0.100.0で実験的から昇格）。WSLもサポート（Linuxの Landlock + seccomp を継承）。v0.117.0には、より良いプロセス分離のための制限トークンサンドボックスの改善が含まれます。⁷⁵ v0.130.0では、Windowsサンドボックスがworkspace-sandboxユーザー向けにランタイムバイナリを確実に解決できるよう、サンドボックスユーザーにデスクトップランタイムのバイナリキャッシュへのアクセスが付与されます。⁹¹

これが重要な理由: コンテナベースのサンドボックス（Docker）とは異なり、OSレベルのサンドボックスは高速・軽量で、回避が困難です。Codexがシステムコールを見る前に、カーネルが制限を強制するのです。

セキュリティ修正: - zsh-fork サンドボックス回避（v0.106.0）: zsh のフォークによるシェル実行がサンドボックス制限を回避できる脆弱性を修正しました。⁶⁰ 古いバージョンを使用している場合は、すぐにアップグレードしてください。 - 入力サイズの上限（v0.106.0）: 過大なペイロードによるハングを防ぐため、Codexは約100万文字の入力上限を強制するようになりました。⁶⁰ - セキュアな devcontainer プロファイル（v0.121.0）: Docker devcontainer向けの新しい強化されたカスタマープロファイルでは、コンテナ内のサンドボックスに Bubblewrap を使用します。WSL2はサポートされ、WSL1は明示的に拒否されます（BubblewrapはWSL1のカーネルシムと互換性がありません）。⁸² - Guardian レビュー + フック（v0.121.0）: Guardianレビューセッション中はフックが無効化され、pre/post-toolフックがGuardianサブエージェントの判断に干渉できないようになっています。⁸² ロギングや検証にフックを利用している場合、Guardianレビューはそれらをスキップすることに注意してください。完全な監査証跡が必要な場合は、app-serverのオブザーバビリティを代替として利用しましょう。 - Linux /dev ファイルシステム（v0.105.0）: Linuxのサンドボックスコマンドは最小限の /dev ファイルシステムを受け取るようになり、デバイスノードを必要とするツールとの互換性が向上しました。⁶¹

ReadOnlyAccess ポリシー（v0.100.0+）: きめ細かい読み取りアクセス制御のための設定可能なポリシー形式です。workspace-writeモードであっても、Codexがどのディレクトリから読み取れるかを制限するために使用できます。

[sandbox_workspace_write]
read_only_access = ["/etc", "/usr/local/share"]  # Only these paths readable outside workspace

第2層: 承認ポリシー（いつ確認するか）

承認ポリシーは、Codexが人間の確認を求めるために一時停止するタイミングを決定します。

on-failureは古い例や互換性のあるパスにまだ登場しますが、現在のOpenAI設定ドキュメントでは非推奨とされています。インタラクティブな実行にはon-requestを、すでに外部の安全境界を持つ非インタラクティブな実行にはneverを選びましょう。⁸⁷

個別の承認ID（v0.104.0+）

Codexはマルチステップのシェル実行内の各コマンドに、個別の承認IDを割り当てるようになりました。つまり、承認はきめ細かく、シーケンス内の1つのコマンドを承認しても、同じシェル呼び出し内の後続コマンドが自動的に承認されることはないのです。⁴⁹

柔軟な承認制御（v0.105.0+）

承認フローは、追加のサンドボックス権限ときめ細かい拒否をサポートするようになりました。⁶¹

• 追加のサンドボックス権限: コマンドが現在のサンドボックスモードを超えるアクセスを必要とする場合、Codexはモード全体の変更を要求するのではなく、特定の追加権限を要求できます
• きめ細かい拒否: 個別のツール呼び出しをフィードバック付きで拒否することで、Codexは同じコマンドを単純に再試行するのではなく、アプローチを調整できます

ランタイム権限リクエスト（v0.113.0+）

Codexには、モデルがランタイムで追加権限を要求できる組み込みのrequest_permissionsツールが含まれるようになりました。⁶⁹ モデルが昇格したアクセスを必要とするタスクに遭遇した場合、サイレントに失敗したりユーザーに別のフラグで再起動を強いたりする代わりに、TUIの承認フローを通じて特定の権限（ファイルシステムパス、ネットワークアクセスなど）を正式に要求できます。

権限プロファイル（v0.113.0+、v0.128.0で拡張）

権限プロファイルは、ファイルシステムとネットワークのサンドボックスポリシーを、名前付きで再利用可能なセクションに分割します。default_permissionsを:read-only、:workspace、:danger-no-sandboxなどの組み込みプロファイルに設定するか、カスタムの[permissions.<name>]テーブルを指定しましょう。⁸⁷

default_permissions = "project-safe"

[permissions.project-safe.filesystem]
"/usr/local" = "read"
glob_scan_max_depth = 3

[permissions.project-safe.filesystem.":project_roots"]
"." = "write"
"**/*.env" = "none"

[permissions.project-safe.network]
enabled = true
mode = "limited"

[permissions.project-safe.network.domains]
"api.github.com" = "allow"
"registry.npmjs.org" = "allow"

機微なファイルや、プロジェクトルートが書き込み可能な場合でも読み取り不可にしたいglobには、noneを使用します。一回限りのコマンド例外には、プロファイル全体を広く拡張するのではなく、ルールを使うことをお勧めします。⁸⁷

レガシーな --full-auto ガイダンス

古いガイドでは、--full-autoは次のコマンドの便利なエイリアスとして説明されていました。

codex --sandbox workspace-write --ask-for-approval on-request

v0.128.0では、リリースノートで--full-autoが非推奨と記され、現在のCLIのヘルプもインタラクティブな実行向けにこのフラグをリストしなくなりました。代わりに、上記の明示的なフラグか、名前付きの権限プロファイルを使用してください。⁸⁶

サンドボックスの信頼性（v0.129.0）: Linuxサンドボックスの起動強化により、低速なファイルシステムやシンボリックリンクのチェックアウトでの競合が減ります。Windowsサンドボックスの信頼性改善は、長時間実行中に発生していたいくつかのエッジケースのクラッシュに対処します。さらにベンダー化されたBubblewrapは、上流のセキュリティパッチを含む0.11.2にバンプされています。設定変更は不要です。これらを取り込むにはcodex updateを実行してください。⁸⁹

推奨設定

日常の開発（安全なデフォルト）:

sandbox_mode = "workspace-write"
approval_policy = "on-request"

パワーユーザー（フルアクセス、human-in-the-loop）:

sandbox_mode = "danger-full-access"
approval_policy = "untrusted"

この組み合わせはコミュニティ推奨の「スイートスポット」です。最大の権限を持ちながら、すべてのコマンドに承認が必要となります。⁸

CI/CDの自動化:

sandbox_mode = "workspace-write"
approval_policy = "never"

Guardianサブエージェントによるスマート承認（v0.115.0+）

Smart Approvalsは、すべてのアクションに人間の承認を求めるのではなく、レビューリクエストをguardianサブエージェント経由でルーティングできます。guardianセッションは承認をまたいで永続化し、プロンプトキャッシュを再利用して起動オーバーヘッドを回避します。各レビューはクリーンな履歴を取得します（以前の判断が後のレビューに漏れることはありません）。⁷³

config.tomlでレビュアーを設定します。

approvals_reviewer = "guardian_subagent"   # "user" (default) or "guardian_subagent"

これは、approval_policy = "never"で一律に承認をスキップするのではなく、推論を伴う自動レビューが欲しいCI/CDワークフローで特に有用です。

ネットワークアクセスの有効化

Codexはworkspace-writeモードではデフォルトでネットワークアクセスをブロックします。必要なときには有効化しましょう。

# Per-run
codex -c 'sandbox_workspace_write.network_access=true' "install the packages"

# In config.toml
[sandbox_workspace_write]
network_access = true
writable_roots = ["/path/to/extra/dir"]   # Additional writable directories
exclude_slash_tmp = false                  # Prevent /tmp from being writable
exclude_tmpdir_env_var = false             # Prevent $TMPDIR from being writable

WebSocketプロキシサポート（v0.104.0+）

WebSocketトラフィックをプロキシ経由でルーティングする企業環境向けに、CodexはWS_PROXYおよびWSS_PROXY環境変数をサポートするようになりました。⁴⁹

export WSS_PROXY="https://proxy.corp.example.com:8443"
codex "update the README"

これらは既存のHTTPS_PROXYおよびSOCKS5プロキシサポート（v0.93.0+）を補完し、すべてのトランスポート層をカバーします。

サンドボックスのテスト

信頼する前に、サンドボックスの動作を検証しましょう。

codex sandbox macos --permissions-profile :workspace -- ls /etc/passwd   # macOS test
codex sandbox linux --permissions-profile :workspace -- cat /etc/shadow  # Linux test

サンドボックスが正しく動作していれば、どちらのコマンドもworkspaceスコープのプロファイル下で permission denied エラーで失敗するはずです。どちらかのコマンドが成功した場合は、サンドボックス設定の調査が必要です。

AGENTS.md はどのように機能しますか？

AGENTS.md は Codex のプロジェクト指示システムです。現在は Linux Foundation の Agentic AI Foundation が管理するオープン標準⁹です。Codex、Cursor、Copilot、Amp、Jules (Google)、Gemini CLI、Windsurf、Cline、Aider、Zed、Factory、RooCode、そして 60,000 件以上の open source プロジェクトが対応しています。特定の repository やディレクトリ内で Codex がどのように振る舞うかを定義します。AGENTS.md を補完する再利用可能な専門知識パッケージについては、Skillsをご覧ください。

Discovery 階層

Codex は session 開始時にディレクトリツリーをたどり、指示チェーンを構築します。

1. Global（~/.codex/）：AGENTS.override.md > AGENTS.md
2. Project（git root から現在のディレクトリまで）：各階層で AGENTS.override.md > AGENTS.md > fallback filenames の順に確認します
3. Merging：ファイルは root から下に向かって連結されます。近い場所にあるファイルほど prompt の後ろに入り、前の guidance を上書きします

~/.codex/AGENTS.md                     ← Global defaults
  └─ /repo/AGENTS.md                   ← Project-wide rules
      └─ /repo/services/AGENTS.md      ← Service-specific rules
          └─ /repo/services/payments/
               AGENTS.override.md      ← Overrides everything above for this dir

優れた AGENTS.md の条件

Codex 自身の直接的な guidance と community patterns¹⁰に基づくと、次のようになります。

DO: - 具体的に書く："search efficiently" より "Use rg --files for discovery" のほうが優れています - 完了条件を定義する：「done」とは何を意味しますか？（tests pass、lint clean など） - commands を含める：Build、test、lint、format（正確な実行コマンド） - task 別に整理する：Coding、review、release、incident/debug sections - escalation を定義する：blocked になったときや unexpected state に遭遇したときに何をするか

DON’T: - 実行ルールのない style guide 全体を詰め込む - 曖昧な指示を使う（「be careful」「optimize」） - 矛盾する優先順位を混ぜる（speed + exhaustive verification + no runtime budget） - prose documentation を書く（AGENTS.md は operational policy であり、README ではありません）

例：Production AGENTS.md

# Repository Guidelines

## Build, Test, and Development Commands
- Run API (dev): `python3 -m uvicorn main:app --reload`
- Install deps: `pip install -r requirements.txt`
- Lint: `python3 -m ruff check .` (auto-fix: `--fix`)
- Format: `python3 -m ruff format .`
- Tests: `python3 -m pytest -v`
- Coverage: `python3 -m pytest --cov=app --cov-report=term-missing`

## Coding Style & Naming Conventions
- Python 3.11+. Type hints on all functions.
- Ruff enforced: 88-char lines, double quotes, spaces for indent.
- Naming: modules `snake_case.py`, classes `PascalCase`, functions `snake_case`.

## Commit & Pull Request Guidelines
- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`
- Commits should be small and focused.
- PRs must include: description, test plan, and screenshots for UI changes.

## Security
- Never commit secrets. Use `.env` for local config.
- Validate all external API calls with proper error handling.

Agent Session での Secret Handling

Codex から見える履歴は、source code だけでなく security surface として扱ってください。Codex release notes には shell snapshotting と environment-variable redaction の作業が記録されており、memory system は memory writes に secrets が含まれていないかを scan します。しかし、こうした保護があっても、command output、session transcripts、shell snapshots、local logs、helper scripts が credentials を出力してよい安全な場所になるわけではありません。³⁷⁵⁵⁹⁵

運用ルールは単純です。model に inspect させるために secrets を出力しないこと。helper credentials は environment-required config に保持すること。audits では executable source、docs、generated caches、session transcripts、shell snapshots、logs、intentional secret stores を分けること。high-confidence な secret shape が見つかったら local history を redact すること。そして prevention hooks は、manual hygiene loop が実証されてから昇格させることです。公開してよい lesson は surface map と acceptance criteria であり、private token values、exact paths、detector internals ではありません。⁹⁵

Override メカニズム

任意のディレクトリ階層にある AGENTS.override.md は、その scope の通常の AGENTS.md を置き換えます。用途は次のとおりです。

• Release freezes：「No new features, fixes only」
• Incident mode：「All changes must be reviewed by on-call」
• Temporary hardening：「No dependency updates this sprint」

Configuration

# Custom fallback filenames (in addition to AGENTS.md)
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# Increase max size for large instruction files
project_doc_max_bytes = 65536    # 64 KiB (default: 32 KiB)

Scaffold Generation

codex                           # Launch TUI
/init                           # Generate AGENTS.md scaffold

または、instruction chain を検証します。

codex --ask-for-approval never "Summarize your current instructions"

Hooks

Codex は v0.99.0 で hooks（AfterAgent）を導入し、v0.100.0 で AfterToolUse を追加しました。その後、v0.114.0 で SessionStart と Stop events を備えた experimental hooks engine を追加しています。⁷⁰ v0.124.0（2026年4月23日）時点で、hooks は stable です。⁸⁵ 現在は config.toml と requirements.toml に inline で設定でき、別個の hook scripts file は不要です。また、apply_patch や long-running Bash sessions と並んで MCP tools も observe します。これにより system は session lifecycle と tool-level automation をカバーし、Claude Code の hook model との差を埋めています。

利用可能な Hook Events

Hook Configuration

Hooks は .codex/config.toml で設定します。

[[hooks]]
event = "AfterToolUse"
command = "echo 'Tool completed' >> /tmp/codex-log.txt"

[[hooks]]
event = "SessionStart"
command = "echo 'Current date: $(date +%Y-%m-%d)'"

SessionStart hook の stdout は model の context に渡されるため、session 開始時に動的情報（日付、branch names、environment variables）を注入する用途に適しています。

Claude Code Hook Patterns の再現

Claude Code から移行する場合、同様の automation は次のように実現できます。

Expert tip: v0.124.0（2026年4月23日）時点で、hooks engine は stable です。新しい hook events は現在も releases に追加されます。Codex changelogを確認してください。

In-TUI hook browser（v0.129.0）： TUI で /hooks を実行すると、利用可能な hooks を discovery し、現在 active な hooks を確認し、config.toml を編集せずに個々の hooks を切り替えられます。問題のある plugin-bundled hook を troubleshooting するときや、集中して編集する session のために AfterToolUse linter を一時的に無効化するときに便利です。⁸⁹

MCP（Model Context Protocol）とは？ [EXPERIMENTAL]

MCP は、外部ツールやサービスと接続することで Codex の機能を拡張します。codex mcp コマンドグループは現在 experimental として扱われており、コマンドや設定形式はリリース間で変更される可能性があります。Codex は 2 種類のトランスポートをサポートしています。STDIO（ローカルプロセス）と Streamable HTTP（リモートサーバー）です。¹¹

v0.121.0 の MCP 変更点: ツールは namespace 付きで登録されるようになったため、一覧に表示されるツール名は素の名前ではなく <server>:<tool> 形式になります。未修飾のツール名を grep しているスクリプトやプロンプトは更新してください。新しい supports_parallel_tool_calls フラグが同梱の MCP に渡されるようになり、対応を宣言しているサーバーでは並列実行が可能になります。サンドボックス状態のメタデータは MCP ツールメタデータ経由で流れるようになったため、サーバー側で動作を調整できます（例: read-only サンドボックス下で実行中の場合に警告する）。カスタムの codex/sandbox-state リクエストは 削除 されました。代わりにメタデータ経路を使用してください。MCP Apps ロールアウトのフェーズ 3 では tool-call サポートが入りました。deferred-call パターンを使用するサーバー向けに、フラット化された deferred tool calls もサポートされるようになりました。⁸²

MCP サーバーの設定

STDIO サーバー（ローカルプロセス）:

# In ~/.codex/config.toml or .codex/config.toml

[mcp_servers.context7]
enabled = true
required = true                         # Fail startup if unavailable
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "MY_VAR" = "value" }            # Static env vars
env_vars = ["PATH", "HOME"]             # Forward host env vars
cwd = "/path/to/project"                # Optional working directory
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled_tools = ["search", "summarize"]  # Tool allowlist
disabled_tools = ["slow-tool"]           # Tool denylist

HTTP サーバー（リモート）:

[mcp_servers.figma]
enabled = true
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
env_http_headers = { "X-Org-Id" = "FIGMA_ORG_ID" }  # Headers from env vars
startup_timeout_sec = 10
tool_timeout_sec = 60

CLI の管理

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add context7 --env API_KEY=... -- npx -y @upstash/context7-mcp   # With env vars
codex mcp add figma --url https://mcp.figma.com/mcp --bearer-token-env-var FIGMA_OAUTH_TOKEN
codex mcp list                          # List all configured servers
codex mcp list --json                   # JSON output
codex mcp get context7                  # Show server config
codex mcp get context7 --json           # JSON output
codex mcp login <server>                # OAuth flow for HTTP servers
codex mcp logout <server>               # Remove OAuth credentials
codex mcp remove <server>               # Delete server definition

セッション内では、/mcp でアクティブなサーバーと利用可能なツールを確認できます。/mcp verbose（v0.123.0+）⁸⁴ は、完全なサーバー診断、リソース、リソーステンプレートを返します。サーバーの読み込みに失敗している場合や、期待した場所にツールが表示されない場合に便利です。通常の /mcp は高速なままです。

Plugin の MCP 読み込み（v0.123.0+）は、.mcp.json 内の標準 mcpServers スキーマとトップレベルのサーバーマップの両方を受け付けます。そのため、どちらの規約で作成された plugins でも問題なく読み込めます。⁸⁴

Codex を MCP サーバーとして実行する

Codex は、マルチエージェントのオーケストレーション向けに、自身を MCP サーバーとして公開できます。¹²

codex mcp-server                        # Start as MCP server (stdio transport)

このサーバーは 2 つのツールを公開します。 1. codex(): prompt、sandbox、model、approval パラメータ付きで新しいセッションを開始します 2. codex-reply(): threadId と prompt を使って既存セッションを継続します

Agents SDK（Python）で使用する:

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "npx", "args": ["-y", "codex", "mcp-server"]},
    client_session_timeout_seconds=360000,
) as codex_mcp_server:
    agent = Agent(name="Developer", mcp_servers=[codex_mcp_server])
    result = await Runner.run(agent, "Fix the failing tests")

注目すべき MCP サーバー

実践的なパターン

パターン 1: コンテキスト対応の開発 — Context7 とフレームワークのドキュメントを組み合わせると、Codex が常に最新の API 参照を利用できます。

[mcp_servers.context7]
enabled = true
required = true
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

パターン 2: 出力制限 — MCP ツールのレスポンスは、デフォルトで約 25K 文字に切り詰められます。大きなペイロードを返すツール（データベースクエリ、ログ取得など）では、enabled_tools を使って対象を特定のツールに絞り、レスポンスを集中させてください。

パターン 2a: マルチモーダルなツール出力（v0.107.0） — カスタムツールは、テキストに加えてマルチモーダル出力（画像、リッチコンテンツ）も返せるようになりました。これにより、スクリーンショット、図、チャートレンダーなどの視覚的な成果物を生成するツールが、それらを分析用に直接モデルへ渡せます。⁶²

パターン 3: エンタープライズ向け MCP ガバナンス — requirements.toml を通じて、開発者が使用できる MCP サーバーを制限します。

# In /etc/codex/requirements.toml — only approved servers allowed
[mcp_servers.approved-internal]
identity = { command = "npx @company/internal-mcp" }

requirements.toml 内の identity に一致しないサーバーは、起動時にブロックされます。完全なポリシー設定については、エンタープライズ デプロイメントをご覧ください。

Code Mode [EXPERIMENTAL]

Code mode（v0.114.0）は、エージェントのスコープをコード中心の操作に制限することで、より分離されたコーディングワークフローを提供します。⁷⁰ 有効にすると、エージェントは広範なシステム操作を行わず、コードの読み取り、書き込み、テストに集中します。

この機能は experimental です。更新についてはリリースノートをご確認ください。

JavaScript REPL Runtime [REMOVED]

Codex v0.100.0 では experimental な JavaScript REPL runtime（js_repl）が追加され、v0.106.0 では /experimental の画面から利用できるようになりました。⁶⁰ ただし、この案内は現在では履歴情報です。v0.128.0 のリリース changelog には「Remove js_repl feature」と記載されており、現在の機能一覧でも js_repl と js_repl_tools_only はどちらも削除済みとされています。⁸⁶

新しい設定に features.js_repl = true を追加しないでください。再利用可能な実行ロジックが必要な場合は、シェルコマンド、チェックイン済みスクリプト、MCP ツール、または scripts/ ディレクトリを持つ Codex skill を使用してください。

Skillsとは何ですか？

Skillsは、Codexが必要に応じて読み込む、再利用可能でタスク特化型の機能パッケージです。オープンなエージェントスキル標準に従っています。¹³

Skillの構造

my-skill/
  SKILL.md           (required: instructions)
  scripts/           (optional: executable scripts)
  references/        (optional: reference docs)
  assets/            (optional: images, icons)
  agents/openai.yaml (optional: metadata, UI, dependencies)

検出場所

Codexは、ユーザーがインストールしたskillsを$CODEX_HOME/skills（デフォルト: ~/.codex/skills）に保存します。.system/配下の組み込みsystem skillsも含まれます。Codexは、シンボリックリンクされたskillフォルダーにも対応しています。

Skillの作成

SKILL.md形式:

---
name: security-audit
description: Run a thorough security audit on the codebase.
---

## Security Audit Procedure

1. Scan for hardcoded secrets using `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Check for SQL injection: look for string interpolation in queries
3. Verify input validation on all API endpoints
4. Check dependency vulnerabilities: `pip audit` or `npm audit`
5. Review authentication and authorization patterns
6. Report findings with severity levels (Critical/High/Medium/Low)

メタデータ（agents/openai.yaml）:

interface:
  display_name: "Security Audit"
  short_description: "Full codebase security review"
  icon_small: "./assets/shield.svg"
  brand_color: "#DC2626"
  default_prompt: "Run a security audit on this repository"

policy:
  allow_implicit_invocation: false    # Require explicit $skill

dependencies:
  tools:
    - type: "mcp"
      value: "snyk"
      transport: "streamable_http"
      url: "https://mcp.snyk.io/mcp"

Skillsの呼び出し

• 明示的: /skillsメニュー、またはプロンプト内の$skill-nameメンション
• 暗黙的: Codexがタスク説明から一致するskillsを自動検出（allow_implicit_invocation: trueの場合）
• 作成: $skill-creatorを使って、新しいskillを対話形式で構築
• インストール: $skill-installer install <name>を使ってcommunity skillsをインストール

有効化/無効化

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

SkillsとSlash Commandsの違い

Skillsのデバッグ

skillが有効化されない場合:

1. 検出状況を確認: TUIで/skillsに表示されるはずです
2. パスを確認: skillフォルダーが認識される場所（~/.codex/skills/、プロジェクトルート、または/etc/codex/skills/）にあることを確認します
3. enabledを確認: config.tomlでenabled = falseになっているskillsは読み込まれません
4. 暗黙的な有効化を確認: 自動検出に依存している場合は、agents/openai.yamlでallow_implicit_invocation: trueになっていることを確認します
5. キーワードを使う: 暗黙的なマッチング精度を上げるため、プロンプトにskillのdescriptionに含まれる用語を入れます

本番例: Deploy Skill

参照とスクリプトが連携して動作する、完全な複数ファイル構成のskillです。

deploy-skill/
  SKILL.md
  references/
    runbook.md
    rollback-checklist.md
  scripts/
    pre-deploy-check.sh
    smoke-test.sh
  agents/openai.yaml

SKILL.md:

---
name: deploy
description: Deploy the application to staging or production. Runs pre-flight checks, executes deployment, and verifies with smoke tests.
---

## Deployment Procedure

### Pre-flight
1. Run `scripts/pre-deploy-check.sh` to verify:
   - All tests pass
   - No uncommitted changes
   - Branch is up to date with remote
2. Review the runbook at `references/runbook.md` for environment-specific steps.

### Deploy
3. Execute the deployment command for the target environment.
4. Monitor logs for errors during rollout.

### Verify
5. Run `scripts/smoke-test.sh <environment-url>` to confirm critical paths.
6. If smoke tests fail, follow `references/rollback-checklist.md`.

呼び出し例: $deploy to staging または $deploy production with canary rollout

Plugins

Pluginsは、skills、MCP entries、hooks、app connectorsを単一のインストール可能なパッケージに統合します（v0.110.0+）。⁶⁵ v0.117.0以降、pluginsは第一級の機能として扱われます。product-scoped pluginsは起動時に自動同期され、/pluginsでは発見と管理のためのTUI内ブラウザーが提供されます。⁷⁵ v0.128.0では、marketplace installation、remote bundle caching、remote uninstall APIs、plugin-bundled hooks、hook enablement state、external-agent config importにより、pluginワークフローが拡張されました。⁸⁶ v0.129.0（2026年5月7日）では、plugin workspace sharing（plugin setを再公開せずにチームメイトへ共有）、share access controls（受信者ごとの有効化/無効化、取り消し）、source filtering（workspaceが取得するmarketplacesを制限）、そしてCLIではなく/pluginsブラウザーから直接呼び出せるmarketplace operationsが追加されました。⁸⁹ v0.130.0（2026年5月8日）では、plugin packagingの透明性が高まり、共有ワークフローをより細かく制御できるようになりました。⁹¹

• バンドルされたhooksがplugin詳細に表示されます。 /pluginsの詳細ビューに、pluginがバンドルするすべてのlifecycle hook（SessionStart、UserPromptSubmit、Stopなど）が表示されるようになりました。pluginをインストールする前に、セッションに対してどのhooksが登録されるかを正確に確認できます。ツールだけを信頼して入れたpluginが、予期しないhookの副作用を起こすことはもうありません。
• shareContext内のplugin共有メタデータ。 workspaceからpluginが共有されると、共有リンクのペイロードでリンクメタデータ（作成者、スコープ、新鮮さ）が公開されるようになりました。受信側のセッションは出所を表示し、受け入れるかどうかを判断できます。
• 共有設定のdiscoverability controls。 共有設定にはdiscoverability toggleが用意されており、チームはpluginを組織全体で一般に一覧表示できる状態にせず、特定のworkspacesや受信者リストに公開できます。

Plugin Sources

Plugin Discovery

Codexは、セッション開始時にどのpluginsが有効かをモデルへ伝えます（v0.111.0）。これにより、インストール済みのMCPs、apps、skillsを見つけやすくなります。⁶⁵ モデルは、タスクのコンテキストに基づいて、セッション中に関連するpluginsを提案できます。v0.117.0では、product-scoped pluginsが起動時に同期されるため、手動操作なしで最新のpluginカタログを利用できます。⁷⁵

@pluginメンション（v0.112.0+）

インストール済みの任意のpluginを、チャット内で@plugin-nameとして直接参照できます。⁶⁸ pluginにメンションすると、そのコンテキスト（機能、ツール、設定）がモデルのコンテキストウィンドウに自動で含まれます。pluginが何をするものかを説明する必要はありません。

@deploy push this branch to staging with canary rollout
@linter check for unused imports in src/

これは、custom skills、MCP servers、app connectorsを含む、インストール済みのあらゆるpluginで機能します。

Plugin Marketplace（v0.113.0+）

plugin marketplaceには、メタデータ、カテゴリ、評価を含む、より充実した発見機能が追加されました。⁶⁹ インストール時の認証チェックにより、API keysまたはOAuthを必要とするpluginsについて、インストール前に有効な認証情報があることを確認します。uninstall endpointは、pluginsと関連設定をきれいに削除します。

Third-Party Marketplacesの追加（v0.121.0+）

現在のOpenAI Codex docsでは、marketplace source managementはcodex plugin marketplace配下に置かれています。これにより、OpenAIのfirst-party marketplaceを超えたthird-party plugin配布が正式化され、GitHub repo shorthand、HTTP(S) Git URLs、SSH URLs、local marketplace root directoriesに対応します。Git refを固定するには--refを使い、Git-backed marketplace reposの場合のみ--sparse PATHを繰り返し指定します。⁹³

# GitHub repository (shorthand)
codex plugin marketplace add owner/repo

# Arbitrary git URL
codex plugin marketplace add https://git.example.com/team/plugins.git

# SSH Git URL
codex plugin marketplace add [email protected]:team/plugins.git

# Local directory
codex plugin marketplace add /path/to/local/marketplace

# Upgrade or remove a configured marketplace
codex plugin marketplace upgrade <marketplace-name>
codex plugin marketplace remove <marketplace-name>

追加後、そのmarketplaceのpluginsは、デフォルトのものと並んで/pluginsブラウザーに表示されます。App-server callers（IDE/desktop integrations）には、marketplacesをプログラムで登録するための並行endpointがあります。⁸²

セキュリティ上の考慮事項: Third-party marketplacesは、Codexの権限で任意のpluginコードを実行します。追加前にソースを精査し、初回実行時はsandboxed executionを優先してください。

Pluginsの管理

codex plugin marketplace add <src>       # Add a marketplace source
codex plugin marketplace upgrade [name]  # Upgrade one marketplace or all
codex plugin marketplace remove <name>   # Remove a configured marketplace

TUIでは、/plugins（v0.117.0+）を使って、セッションを離れることなく個別のpluginsを対話的に閲覧、インストール、削除できます。⁷⁵

エキスパート向けのヒント: Pluginsは、以前は個別に必要だったMCP config、skill installation、app connector setupを統合します。1つのpluginで3つすべてをバンドルできるため、チームのオンボーディングが速くなり、設定の移植性も高まります。

プランモードとコラボレーション

プランモードでは、変更を実行する前に Codex がアプローチを設計できます。v0.94.0 以降、デフォルトで有効になっています。¹⁴ 「プランモード vs 直接実行」の判断ツリーについては、判断フレームワークを参照してください。

プランモードへの切り替え

/plan                              # Switch to plan mode
/plan "redesign the API layer"     # Plan mode with initial prompt

プランモードで Codex は次のように動作します。 - ファイルを読み取り、コードベースを分析する - 実装プランを提案する - 承認するまで変更を行わない - 専用の TUI ビューでプランをストリーミング表示する

Steer モード

Steer モード（v0.98.0 以降デフォルトで有効）では、Codex が作業中に現在のタスクを中断することなく、新しい指示を注入できます。¹⁴

注入方法は 2 種類あります。

実用例:

# Codex is refactoring the auth module...

[Enter] "Use bcrypt instead of argon2 — we already have it as a dependency"
→ Codex adjusts immediately, mid-turn

[Tab] "Once auth is done, update the migration script too"
→ Codex finishes auth refactor, then starts the migration

Steer モードは TUI で常にアクティブです。Codex が完了するまで待ってから指示を出したい場合は、ターンの完了後に通常どおり入力するだけで構いません。特別なモードは必要ありません。

TUI の機能強化（v0.105.0–v0.106.0）

シンタックスハイライト（v0.105.0）: TUI でフェンス付きコードブロックと差分がインラインでシンタックスハイライトされるようになりました。/theme でカラースキームを選択できます。⁶¹

新しい TUI コマンド（v0.105.0+）:⁶¹

音声入力（v0.105.0、実験的機能）: スペースバーを押すと音声入力でプロンプトを入力できます。この機能は実験的であり、マイクの権限が必要になる場合があります。⁶¹ v0.107.0 では、リアルタイムの音声セッションでマイクとスピーカーのデバイス選択がサポートされ、特定のオーディオ入出力ハードウェアを選べるようになりました。⁶²

その他の改善: - 長いリンクが TUI の行をまたいで折り返された場合でもクリック可能なままになりました（v0.105.0）⁶¹ - ローカルファイルのリンクのフォーマットが改善されました（v0.106.0）⁶⁰ - サブエージェントの Ctrl+C 処理が修正され、子プロセスが正しく終了するようになりました（v0.106.0）⁶⁰

メモリシステム

Codex には、セッションをまたいで事実、設定、プロジェクトコンテキストを保存する永続的なメモリシステム（v0.100.0+）があります。²⁴

メモリコマンド

メモリは ~/.codex/memory/ 配下のマークダウンファイルに保存されます。Codex はセッション開始時にこれらを読み込み、以降のすべてのセッションで動作の判断材料として使用します。

保存に適した内容

メモリは、永続的な設定やプロジェクトの事実を保存するのに最適です。

• プロジェクトの規約: 「このプロジェクトはタブを使用し、スペースは使わない」「API レスポンスには常に meta フィールドを含める」など
• ツールの設定: 「npm の代わりに pnpm を使う」「テストは pytest -x --tb=short で実行する」など
• アーキテクチャの決定: 「auth モジュールは src/middleware/ ではなく src/core/auth/ にある」など
• ワークフローの設定: 「差分を見せる前に必ず linter を実行する」など

パイプラインでのメモリ

codex exec 実行時には、メモリが自動的に読み込まれます。つまり、CI/CD パイプラインやスクリプトはインタラクティブセッションと同じコンテキストの恩恵を受けられるため、呼び出しごとに指示を繰り返す必要はありません。

メモリの改善（v0.101.0–v0.107.0）

• シークレットのサニタイズ: メモリはディスクに書き込まれる前にシークレットがないか自動的にスキャンされます
• CWD 認識: メモリファイルにワーキングディレクトリのコンテキストが含まれるようになり、プロジェクト固有のリコールが可能になりました
• 開発者メッセージの除外: フェーズ 1 のメモリ入力から開発者・システムメッセージが除外され、ユーザーとのやり取りに焦点を絞ることでメモリの品質が向上しました
• 差分ベースの忘却（v0.106.0）: メモリは差分ベースの忘却により古くなった事実を削除するようになり、メモリストアを長期にわたって無駄なく関連性の高い状態に保ちます⁶⁰
• 使用状況に応じた選択（v0.106.0）: メモリの取得が使用状況を考慮するようになり、頻繁にアクセスされるメモリや最近関連性の高いメモリが優先されます⁶⁰
• メモリの設定可能化（v0.107.0）: メモリが完全に設定可能になりました。codex debug clear-memories を使用すると、保存されているすべてのメモリをリセットしてクリーンな状態にできます。無関係なプロジェクト間でコンテキストを切り替えるときや、メモリの状態がずれてしまったときに便利です⁶²
• フェーズ 2 のモデルアップグレード（v0.121.0）: フェーズ 2 のメモリ統合モデルが gpt-5.4 になりました（従来のデフォルトから更新）。フェーズ 2 のパイプラインはセッション間で実行され、フェーズ 1 のトランスクリプトを永続的な事実へと蒸留します。今回のモデル変更により、同じトークンコストでリコール品質が向上しています。⁸²
• TUI メモリメニュー（v0.121.0）: 新しいセッション内 UI で、メモリモード、個別メモリの削除、リセットボタンが利用できるようになりました。メモリのリセットは過去のロールアウトを保持するようになり、リセットしても今後のリコール対象がクリアされるだけで、セッションの再生は壊れません。⁸²

メモリと AGENTS.md の使い分け

ヒント: 無期限に保持すべき事実には /m_update を使ってください。セッション固有のコンテキストであれば、会話の中で Codex に直接伝えるだけで十分です。チームで共有するコンテキストには AGENTS.md を使用してください。

セッション管理

Codex はセッションを ~/.codex/sessions/ 配下に永続化し、CLI とデスクトップの両方の環境で再開、フォーク、マルチスレッドのワークフローを可能にします。

再開（Resume）

中断したところから再開します。

codex resume                          # Interactive picker (sorted by recency)
codex resume <SESSION_ID>             # Resume a specific session
codex exec resume --last "continue"   # Non-interactive: resume most recent

TUI 内で /resume スラッシュコマンドを使用すると、検索機能付きの同じインタラクティブピッカーが開きます。

フォーク（Fork）

現在の進行状況を失うことなく、会話を分岐させて代替案を試せます。

/fork                              # Fork current conversation
/fork "try a different approach"   # Fork with new prompt

フォークは、フォークポイントまでの履歴を共有しながら独立したスレッドを作成します。一方のフォークでの変更は、もう一方には影響しません。アプローチの比較（例: 「フォークして Memcached の代わりに Redis を試す」）や、リスクのある変更を安全に検証する場合に便利です。

スレッドのサブエージェントへのフォーク（v0.107.0）: スレッドを独立したサブエージェントにフォークできるようになり、会話から並列の作業ストリームを生成して自律的に実行できます。これは既存のフォークモデルを拡張したもので、単に会話を分岐させるのではなく、フォークされたスレッドが独自の実行コンテキストを持つサブエージェントになります。⁶² v0.117.0 以降、サブエージェントはパスベースのアドレス（例: /root/agent_a）と構造化されたエージェント間メッセージングを使用し、マルチエージェントの連携をより明示的でデバッグしやすくしています。⁷⁵

スレッド一覧

アクティブなセッションを表示・管理します。

/status                            # Current session info and token usage
/ps                                # Show background terminals in session

デスクトップアプリでは、スレッドはサイドバーに表示され、完全な履歴と差分プレビューを確認できます。

セッションのライフサイクル

セッションは CLI とデスクトップアプリ間で同期されます。一方で開始し、もう一方で続行できます。

非対話モード（codex exec）

codex exec は、スクリプト、CI/CD、自動化のために Codex を非対話的に実行します。¹⁵

基本的な使い方

codex exec "summarize the repository structure"
codex exec --sandbox workspace-write --ask-for-approval on-request "fix the CI failure"
codex exec --json "triage open bugs" -o result.txt

デフォルトでは、codex exec は進行状況／イベントを stderr に、最終的なエージェントメッセージを stdout に出力します。この設計により、標準的な Unix パイプラインと組み合わせて利用できます。

JSON Lines 出力

--json を指定すると、stdout は JSONL イベントストリームになります。

codex exec --json "fix the tests" | jq

イベントタイプ：thread.started、turn.started/completed/failed、item.started/completed、error

{"type":"thread.started","thread_id":"019c5c94-..."}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"..."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}

構造化出力

JSON Schema を使ってレスポンス形式を強制できます。

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

-o / --output-last-message は、最終メッセージをファイルに書き出します。

セッションの再開とレビュー

codex exec resume --last "continue where you left off"
codex exec resume <SESSION_ID> "fix the remaining issues"
codex exec review --base main           # Code review against a branch

主要なフラグ

CI 認証

codex exec は、自動化環境での非対話的な認証のために CODEX_API_KEY をサポートしています。

codex exec 起動バナー（v0.130.0）。 codex exec の起動バナーには、従来の「research preview」という文言が表示されなくなりました。CI で起動時の出力をスクレイピングしている場合、バナーのテキストはよりスリムになっています。構造化された --json イベントは変更されていません。⁹¹

codex remote-control（v0.130.0+）

codex remote-control は、ヘッドレスな app-server を起動するトップレベルコマンドで、別のプロセス（IDE 拡張機能、カスタムオーケストレーター、リモート制御プレーンなど）から駆動されることを想定しています。多くのインテグレーターが手作業で組み合わせていた複数フラグの codex app-server 呼び出しを置き換えるもので、サードパーティ製ツールに対し、デスクトップおよび IDE の各種サーフェスで動作するのと同じ app-server ランタイムへの単一かつ安定したエントリポイントを提供します。⁹¹

# Start a headless, remotely controllable app-server
codex remote-control

# Same lifecycle as a TUI session: thread store, hooks, plugins, MCP, sandbox
# all initialize from your normal config.toml.

大きなスレッド履歴を、すべてのターンを一度にメモリへ展開せずに列挙する必要のある UI を構築する場合は、codex remote-control を以下の app-server ページネーション API と組み合わせて利用してください。

App-Server スレッドのページネーション（v0.130.0+）

app-server クライアントは、3 種類のターンアイテムビューを通じて大きなスレッドをページングできるようになりました。⁹¹

ページネーションは、v0.121.0 で導入された ThreadStore インターフェースと組み合わせて利用することで、長時間実行されるスレッドを効率的に走査できます。とくに、オーケストレーターが rollout ファイルと別マシンに存在する可能性のある remote-control デプロイにおいて有効です。⁸²

app-server のライブ設定リフレッシュ（v0.130.0+）

ライブの app-server スレッドは、再起動を必要とせずに config.toml の変更を取り込むようになりました。設定を編集して保存すれば、次のターンで実行中のスレッドに新しい値が反映されます。これは codex remote-control に対応するバグフィックスでもあります。長時間稼働するヘッドレスサーバーは、停止することなくその場で再構成できます。⁹¹

Codex Cloud とバックグラウンドタスク [EXPERIMENTAL]

ステータス：Codex Cloud は 実験的（experimental） 機能です。インターフェース、価格、提供状況は変更される可能性があります。クラウド環境は OpenAI が管理しており、インフラを直接制御することはできません。

Codex Cloud は、OpenAI が管理する環境でタスクを非同期に実行します。⁴ CI パイプラインへの Codex 統合については、GitHub Action & CI/CD もあわせてご覧ください。

仕組み

1. タスクを送信する（chatgpt.com/codex、Slack 連携、または CLI 経由）
2. Codex がリポジトリを分離されたクラウドサンドボックスにクローンする
3. エージェントが独立して作業する：コードを読み、テストを実行し、変更を加える
4. 完了すると、Codex が PR を作成するか、レビュー用の diff を提示する
5. codex apply <TASK_ID> でローカルに結果を適用する

クラウドでのインターネットアクセス

エージェントのインターネットアクセスは デフォルトでオフ であり、環境ごとに設定します。

• Off：エージェントのインターネットアクセスなし（デフォルト）
• On：オプションでドメイン許可リスト＋ HTTP メソッド制限

Allowed domains: pypi.org, npmjs.com, github.com
Allowed methods: GET, HEAD, OPTIONS

セットアップスクリプトは、エージェントのインターネットがオフの場合でも、依存関係のインストールのためにインターネットを利用できます。

Slack 連携

Slack のチャンネルやスレッドで @Codex をメンションすると、クラウドタスクを開始できます。

前提条件： 1. 対象となる ChatGPT プラン（Plus、Pro、Business、Enterprise、または Edu） 2. 接続済みの GitHub アカウント 3. 少なくとも 1 つの設定済みクラウド環境 4. ワークスペースにインストールされた Slack アプリ

Codex はタスクへのリンクを返信し、完了時に結果を投稿します。

Cloud CLI

codex cloud exec --env <ENV_ID> "Fix failing tests"  # Start a cloud task
codex cloud status <TASK_ID>                          # Check task progress
codex cloud diff <TASK_ID>                            # View task diff
codex cloud list                                      # List recent tasks
codex cloud list --json                               # JSON output
codex cloud apply <TASK_ID>                           # Apply from cloud subcommand
codex apply <TASK_ID>                                 # Apply diff (top-level shortcut)

Codex Desktop App

Codex デスクトップアプリ（macOS および Windows）は、マルチプロジェクト管理に最適化されたグラフィカルインターフェースを提供します。¹⁶ Windows 版は、ネイティブ PowerShell サポートとネイティブ Windows サンドボックスを備えて 2026 年 3 月 4 日にリリースされました。⁶⁶

インストール

codex app                      # Auto-downloads and installs on first run

または直接ダウンロード： Codex.dmg（macOS）｜ Microsoft Store で入手可能（Windows）

主な機能

スレッドモード

各スレッドは作成時に選択する 3 つのモードのいずれかで実行されます。

Worktree 隔離のメカニズム：

Worktree スレッドを開始すると、デスクトップアプリは次の処理を行います。 1. 一時ディレクトリに新しい git worktree（git worktree add）を作成 2. 現在の HEAD から新しいブランチをチェックアウト 3. worktree 内でエージェントを実行 — すべてのファイル変更が隔離される 4. 完了時に差分レビューを表示 — マージし戻す変更を選択

これにより、複数の Worktree スレッドが同じリポジトリ上で衝突なく同時実行できます。それぞれが独自のブランチと作業ディレクトリを持つのです。

オートメーション

オートメーションはアプリ内でローカルに実行されるため、アプリが起動しており、プロジェクトがディスク上で利用可能である必要があります。

• Git リポジトリでは、オートメーションは専用のバックグラウンド worktree（作業ディレクトリから隔離）を使用
• 非 Git プロジェクトでは、実行はプロジェクトディレクトリ内で直接行われる
• オートメーションはデフォルトのサンドボックス設定を使用

オートメーションのセットアップ： 1. デスクトップアプリでプロジェクトを開く 2. サイドバーの Automations タブをクリック 3. トリガー（スケジュール、webhook、または手動）を定義 4. プロンプトを記述し、実行モード（local または worktree）を選択 5. オートメーション実行の reasoning レベルを設定（App v26.312）⁷² 6. オートメーションがスケジュール通りに実行され、結果がレビュー用にキューイングされる

ユースケース例： - Issue トリアージ：新しい issue を自動で分類し優先順位付け - CI 監視：ビルド失敗を監視し修正を提案 - アラート対応：監視アラートに診断分析で対応 - 依存関係更新：セキュリティパッチを確認し適用

結果はレビューキューに表示され、人間の承認を受けます。

Windows サポート

Codex Desktop App は 2026 年 3 月 4 日（App v26.304）に Windows 版がリリースされ、ネイティブ PowerShell サポート、ネイティブ Windows サンドボックス、WSL を必要とせず skills、automations、worktrees を含む完全な機能パリティを備えています。⁶⁶

GitHub Action と CI/CD

公式の GitHub Action は、Codex を CI/CD パイプラインに統合します。¹⁸

基本的な使い方

# .github/workflows/codex.yml
name: Codex
on:
  pull_request:
    types: [opened]

jobs:
  codex:
    runs-on: ubuntu-latest
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          sandbox: workspace-write
          safety-strategy: drop-sudo

設定オプション

出力：final-message、後続のステップ／ジョブ用の最終 Codex 応答テキスト。

セーフティ戦略

アクセス制御

with:
  allow-users: "admin,maintainer"     # Limit who can trigger
  allow-bots: false                   # Block bot-triggered runs

デフォルト：書き込み権限を持つコラボレーターのみが Codex ワークフローをトリガーできます。

Codex SDK

TypeScript SDK は、Codex のエージェント機能をカスタムアプリケーションに組み込みます。¹⁹

インストール

npm install @openai/codex-sdk

基本的な使い方

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();

// Multi-turn conversation
const turn1 = await thread.run("Diagnose CI failures and propose a fix");
console.log(turn1.finalResponse);

const turn2 = await thread.run("Implement the fix and add tests");
console.log(turn2.items);

// Resume a previous session
const resumed = codex.resumeThread("<thread-id>");
await resumed.run("Continue from previous work");

SDK の高度な機能

• runStreamed(...)：中間更新用の非同期イベントストリーム
• outputSchema：JSON 形状の最終出力を強制
• マルチモーダル入力：テキスト + ローカル画像を渡す（{ type: "local_image", path: "..." }）
• 画像ワークフロー（v0.117.0）：view_image が URL を返し、生成された画像は再オープン可能で、画像履歴がセッションの再開後も保持されます⁷⁵
• マルチ環境 view_image（v0.130.0）：複数の環境にまたがるセッション（v0.124.0 でターンごとの環境＋作業ディレクトリ選択とともに導入され、v0.125.0 で sticky 環境により改良）では、view_image がオーケストレーターのローカルファイルシステムではなく、選択された環境を通じてファイルパスを解決するようになりました。リモート環境から添付された画像は、SDK を実行しているホストではなく、その環境の作業ディレクトリを基準に取得されます。⁹¹

スレッドとクライアントの設定

// Custom working directory, skip git check
const thread = codex.startThread({
  workingDirectory: "/path/to/project",
  skipGitRepoCheck: true,
});

// Custom environment and config overrides
const codex = new Codex({
  env: { CODEX_API_KEY: process.env.MY_KEY },
  config: { model: "gpt-5.5" },
});

セッションは ~/.codex/sessions 配下に保持されます。

Runtime：Node.js 18+。

パフォーマンス最適化

コンテキスト管理

コンテキストウィンドウはモデルにより異なります。2026 年 4 月時点で：Codex の GPT-5.5 は 400K（API では 1M）を提供します。GPT-5.4 / GPT-5.4-mini はそれぞれ 1M / 400K（Codex では API 同等）を提供します。GPT-5.3-Codex / GPT-5.2-Codex ファミリーは 272K 入力 + 128K 出力（合計 400K の予算）で動作します。いずれも予想より早く埋まるため、能動的に管理しましょう。

1. /compact を定期的に使用：会話履歴を要約してトークンを解放
2. ローカルドキュメントを提供：高品質な AGENTS.md とローカルドキュメントは、コンテキストを消費する探索オーバーヘッドを削減
3. @ を使って特定のファイルを添付：Codex に探させる代わりにファイルを直接参照
4. プロンプトを焦点を絞ったものに：正確なファイルを指定したスコープ付きプロンプトは、自由な探索よりコンテキストを消費しない

トークン効率

速度最適化

1. gpt-5.3-codex-spark：インタラクティブなペアリング向けの低レイテンシ版
2. --profile fast：低 reasoning の mini モデルが事前設定済み
3. 並列ツール実行：Codex は独立した読み取り／チェックを同時実行するため、これを活かせるようプロンプトを構成
4. 成果駆動のループ：手順ごとの指示の代わりに「実装、テスト、修正、グリーンになったら停止」を依頼

問題のデバッグ方法

よくある問題と解決策

エラーメッセージリファレンス

診断ツール

codex --version                        # Check CLI version
codex login status                     # Verify authentication
codex mcp list                         # Check MCP server status
codex debug app-server --help          # Debug app server issues

セッション内のTUI診断：

/status                                # Token/session overview
/config                                # Inspect effective config values and sources
/compact                               # Summarize history to reclaim context

注意：codex --verboseは有効なトップレベルフラグではありません。上記のdebugサブコマンドとTUI診断を使用してください。

クリーンな再インストール

npm uninstall -g @openai/codex && npm install -g @openai/codex@latest

デバッグモード

codex debug app-server send-message-v2  # Test app-server client

問題の報告

/feedback                              # Send logs to Codex maintainers (in TUI)

またはgithub.com/openai/codex/issuesで問題を報告してください。¹

Codex Security [PREVIEW]

Codex Securityは2026年3月6日にリサーチプレビューを開始し、コンテキスト対応のアプリケーションセキュリティレビューをCodexスタックに導入しました。⁷⁷ ChatGPT Pro、Enterprise、Business、Edu のお客様はCodex web経由で利用できます。

仕組み：Codex Securityはリポジトリを解析してプロジェクト固有の脅威モデルを構築し、実世界での影響度で分類された脆弱性を特定し、サンドボックス環境で検出結果に圧力テストを行って検証します。エージェントは修正案とともに信頼度の高い検出結果を提示し、軽微なバグによるノイズを削減します。

パフォーマンス：リサーチプレビュー期間中、Codex Securityは120万件のコミットをスキャンし、10,561件の重大な脆弱性を特定しました。精度は時間とともに向上し、ノイズは84%削減され、過剰報告された深刻度は90%以上削減され、誤検出率は半減しました。本システムはOpenSSH、GnuTLS、Chromiumで実際の脆弱性を発見し、14件のCVEが割り当てられています。⁷⁷

注意：Codex SecurityはCLIに組み込まれたサンドボックスセキュリティモデルとは別物です。サンドボックスはマシンをCodexから保護し、Codex Securityはコードベースを脆弱性から保護します。

エンタープライズ展開

管理者制御（requirements.toml）

管理者は requirements.toml を介してエンタープライズポリシーを適用します。これは管理者によって強制される設定ファイルで、ユーザーが上書きできないセキュリティ上重要な設定を制約します。²¹

# /etc/codex/requirements.toml

# Restrict which approval policies users can select
allowed_approval_policies = ["untrusted", "on-request", "never"]

# Limit available sandbox modes
allowed_sandbox_modes = ["read-only", "workspace-write"]

# Control web search capabilities
allowed_web_search_modes = ["cached"]

# Allowlist MCP servers by identity (both name and identity must match)
[mcp_servers.approved-server]
identity = { command = "npx approved-mcp-server" }

# Admin-enforced command restrictions
[[rules.prefix_rules]]
pattern = [{ token = "rm" }, { any_of = ["-rf", "-fr"] }]
decision = "forbidden"
justification = "Recursive force-delete is prohibited by IT policy"

[[rules.prefix_rules]]
pattern = [{ token = "sudo" }]
decision = "prompt"
justification = "Elevated commands require explicit approval"

設定を行うユーザーレベルの config.toml とは異なり、requirements.toml はハードな制約レイヤーであり、ユーザーが選択できる値を制限し、ユーザーは上書きできません。管理者の requirements ルールは prompt または forbid のみ可能です（暗黙的に許可することはできません）。

macOS MDM 設定

com.openai.codex プリファレンスドメインを使用して MDM 経由で配布します。²¹ Codex は標準的な macOS MDM ペイロード（Jamf Pro、Fleet、Kandji など）に対応しています。TOML は改行を入れずに base64 でエンコードしてください。

優先順位（高い順）：

1. macOS 管理プリファレンス（MDM）
2. クラウドから取得される requirements（ChatGPT Business / Enterprise）
3. /etc/codex/requirements.toml（ローカルファイルシステム）

クラウド requirements は未設定の requirement フィールドのみを埋めるため、優先度の高い管理レイヤーが常に勝ちます。クラウド requirements はベストエフォートで動作し、取得が失敗またはタイムアウトした場合、Codex はクラウドレイヤーなしで動作を続行します。

OpenTelemetry 統合

Codex は標準の OTel 環境変数から OpenAI API 呼び出しまで、OpenTelemetry のトレースコンテキスト伝播をサポートしています。Codex を起動する前に標準の環境変数を設定してください。

# Point Codex at your OTel collector
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector.internal:4318"
export OTEL_SERVICE_NAME="codex-cli"
export OTEL_RESOURCE_ATTRIBUTES="team=platform,env=production"

# Launch Codex — trace context propagates to all OpenAI API calls
codex

• 標準の OTEL_* 環境変数（エンドポイント、サービス名、リソース属性）が尊重されます
• トレースコンテキストは Codex を経由して API 呼び出しに伝播し、エンドツーエンドのオブザーバビリティを実現します
• リソース属性を使用して、チーム、環境、またはプロジェクトでトレースをタグ付けできます
• プロンプト/ツールログを有効にする際はプライバシー要件に注意してください — トレースにコードスニペットが含まれる可能性があります
• 設定可能な OpenTelemetry トレースメタデータ（v0.130.0+）。 標準の OTEL_RESOURCE_ATTRIBUTES エンベロープに加え、codex-otel クレートは設定可能なトレースメタデータを公開するようになりました。これにより管理者は、呼び出しのたびに OTEL_RESOURCE_ATTRIBUTES をゼロから再構築することなく、組織固有の次元（コストセンター、プロジェクト ID、チケット参照）でトレースをタグ付けできます。同じリリースで提供されたよりリッチなレビュー/フィードバック分析と組み合わせることで、CLI、app-server、remote-control セッション全体で統一されたデバッグおよびトリアージが可能になります。⁹¹

エンタープライズアクセス

• ChatGPT Business / Enterprise / Edu：組織管理者が制御するアクセスで、クラウドから取得される requirements が自動的に適用されます。ID プロバイダー（Okta、Entra ID など）を介した SAML/OIDC による SSO をサポートしています
• API：標準の API 認証、課金、組織/プロジェクト制御。OpenAI は SOC 2 Type II および SOC 3 レポートを公開しています。HIPAA BAA は Enterprise ティアで利用可能です
• Codex SDK：社内ツールやワークフローに組み込み可能
• 大規模なポリシー適用：MDM で配布する requirements_toml_base64 またはファイルシステムレベルの /etc/codex/requirements.toml を使用します

データ取り扱いとコンプライアンス： - OpenAI の Business/Enterprise/API 規約のもと、API の入出力はトレーニングに使用されません - データレジデンシーについては、OpenAI API トラフィックはデフォルトで米国ベースのインフラストラクチャを経由します。EU データレジデンシー要件については、OpenAI のエンタープライズ営業チームにご相談ください - セッショントランスクリプトはローカルに保存され、API 呼び出しのみがマシンを離れます - ChatGPT Enterprise は SOC 2、GDPR、CCPA を含むコンプライアンスフレームワークをサポートしています

ロールアウト戦略

組織向けの推奨段階的ロールアウト：

1. パイロット（フェーズ 1）：3〜5 名のシニアエンジニアに展開し、requirements.toml で untrusted サンドボックスモードと cached ウェブ検索を強制します。AGENTS.md パターンと MCP サーバーのニーズに関するフィードバックを収集します。
2. チーム拡大（フェーズ 2）：チーム全体に展開します。チーム標準の config.toml を MDM またはリポジトリ経由で配布します。信頼できるリポジトリで workspace-write サンドボックスを有効化します。
3. CI 統合（フェーズ 3）：自動 PR レビューおよびテスト生成のために codex-action を CI/CD パイプラインに追加します。コストを予測可能に保つには --ephemeral を使用します。
4. 組織全体（フェーズ 4 以降）：承認された MCP サーバー、サンドボックスポリシー、モデルの許可リストを強制する requirements.toml を伴って MDM 経由で展開します。

監査パターン

Codex の使用状況を追跡し、コンプライアンスを適用します。

• OpenTelemetry トレース：チームごとの API 呼び出し量、トークン使用量、レイテンシを監視
• セッション永続化：コンプライアンスレビューのために ~/.codex/sessions/ を監査します（機密性の高いコンテキストでは --ephemeral で無効化）
• MCP identity の強制：requirements.toml はブロックされたサーバー試行をログに記録します — 不正なツール使用についてレビューしてください
• Git 監査証跡：すべての Codex ファイル変更は標準の git を経由します — ブランチ履歴と PR diff でレビューします

ベストプラクティスとアンチパターン

プロンプトのパターン

1. 制約駆動型プロンプト：境界線を最初に示します。「APIコントラクトは変更しないでください。内部実装のリファクタリングのみ行います」
2. 構造化された再現手順：番号付きの手順は、曖昧な説明よりも優れたバグ修正を生み出します
3. 検証の依頼：「lintと最小限の関連テストスイートを実行してください。コマンドと結果を報告してください」と末尾に記載します
4. ファイル参照：@filenameを使用して特定のファイルをコンテキストに添付します
5. アウトカム駆動型ループ：「実装し、テストを実行し、失敗を修正し、すべてのテストが通った時点でのみ停止してください」。Codexは完了するまで反復します

テストの哲学

コミュニティはテスト駆動型のAIコラボレーションに収束しつつあります：²²

• 完了シグナルとしてテストを事前に定義する
• テストが通るまでCodexに反復させる（red → green → refactor）
• Tiger Styleのプログラミングパターンを採用する
• パッチを依頼する際は、正確なファイルテキストを提供する。CodexはファジーなASTベースのパッチではなく、厳密なマッチングを使用します

コンテキスト管理のベストプラクティス

• Web検索に頼るのではなく、高品質なローカルドキュメントを提供する
• 目次と進捗ファイルを備えた構造化されたmarkdownを維持する（「漸進的開示」）
• パッチの失敗を防ぐため、追跡対象ファイル全体で改行コード（LFとCRLF）を統一する
• 長い指示はコンテキストから押し出されるため、AGENTS.mdは簡潔に保つ

Gitワークフロー

• 馴染みのないリポジトリでCodexを実行する前は、必ず新しいブランチを作成する
• 直接編集ではなく、パッチベースのワークフロー（git diff / git apply）を使用する
• Codexの提案はコードレビューPRのようにレビューする
• コミット前に/diffで変更を確認する

コミュニティのスキルとプロンプト

feiskyer/codex-settingsリポジトリでは、コミュニティが管理する設定が提供されています：²³

再利用可能なプロンプト（~/.codex/prompts/内）： - deep-reflector：開発セッションから学びを抽出 - github-issue-fixer [issue-number]：体系的なバグ分析とPR作成 - github-pr-reviewer [pr-number]：コードレビューのワークフロー - ui-engineer [requirements]：プロダクショングレードのフロントエンド開発

コミュニティのスキル： - claude-skill：Claude Codeに権限モード付きでタスクをハンドオフ - autonomous-skill：進捗追跡を伴うマルチセッションのタスク自動化 - deep-research：並列サブタスクのオーケストレーション - kiro-skill：要件 → 設計 → タスク → 実行のパイプライン

アンチパターン

トークンを浪費し、結果が悪く、ワークフローを苛立たしいものにする一般的なミスです。

コストのアンチパターン

コンテキストのアンチパターン

ワークフローのアンチパターン

プロンプトのアンチパターン

ワークフローレシピ

一般的な開発シナリオのエンドツーエンドパターンです。

レシピ1：新規プロジェクトのセットアップ

mkdir my-app && cd my-app && git init
codex

> Create a FastAPI project with: main.py, requirements.txt, Dockerfile,
  basic health endpoint, and a README. Use async throughout.

> /init

生成されたAGENTS.mdを確認し、自分の規約に合わせて編集してから次を実行します：

> Run the health endpoint test and confirm it passes

レシピ2：日常的な開発フロー

cd ~/project && git checkout -b feature/user-auth
codex

> @src/models/user.py @src/api/auth.py
  Add password reset functionality. Requirements:
  1. POST /api/auth/reset-request (email → sends token)
  2. POST /api/auth/reset-confirm (token + new password)
  3. Tests for both endpoints
  Run tests when done.

/diffでレビューしてからコミットします。

レシピ3：プランモードを使った複雑なリファクタリング

codex

> /plan Migrate the database layer from raw SQL to SQLAlchemy ORM.
  Constraints: don't change any API contracts, keep all existing tests passing.

プランをレビューします。承認するか、steerします：

[Tab] Also add a migration script using Alembic

Codexの実行後、検証します：

> Run the full test suite and report results
> /diff

レシピ4：codex execによるPRレビュー

codex exec --model gpt-5.1-codex-mini \
  "Review the changes in this branch against main. \
   Flag security issues, missed edge cases, and style violations. \
   Format as a markdown checklist." \
  -o review.md

レシピ5：Cloud Tasksによるデバッグ [EXPERIMENTAL]

codex cloud exec --env my-env "Diagnose why the /api/orders endpoint returns 500 \
  for orders with > 100 line items. Check the serializer, database query, \
  and pagination logic. Propose a fix with tests."

後で進捗を確認します：

codex cloud status <TASK_ID>
codex cloud diff <TASK_ID>

完了後、修正をローカルに適用します：

codex apply <TASK_ID>

移行ガイド

Claude Code からの移行

理解しておくべき主な違い：

• サンドボックスは OS レベル：Codex はコンテナではなく Seatbelt/Landlock を使用します。制限はアプリケーション層よりも下位のカーネルレベルで動作します。
• Hooks は拡張中：Codex は現在 5 つの hook イベントをサポートしています。SessionStart、Stop、UserPromptSubmit（v0.114.0〜v0.116.0、実験的）に加えて、AfterAgent（v0.99.0）と AfterToolUse（v0.100.0）です。このシステムはセッションのライフサイクル、プロンプト傍受、ツールレベルの自動化をカバーしますが、Claude Code の 12 種類以上のライフサイクルイベントの方が依然として広範なカバレッジを提供します。まだカバーされていない自動化パターンには、AGENTS.md の指示やスキルを使用してください。
• Sub-agents v2（v0.117.0）：サブエージェントはパスベースのアドレス（例：/root/agent_a）を使用するようになり、構造化されたエージェント間メッセージングとエージェント一覧表示が可能になりました。⁷⁵ これは既存の仕組み（最大同時 6 個、v0.91.0 で 12 から削減）を拡張するものです。マルチエージェントの役割は引き続き設定からカスタマイズ可能です（v0.104.0+）。⁴⁷ v0.105.0 では spawn_agents_on_csv が追加され、進捗追跡と ETA 付きで行ごとのファンアウトが可能になりました。⁶¹ Codex には依然として Claude Code のユーザー指示型委任のための明示的な Task ツール UX が欠けています。委任パターンには cloud tasks や SDK オーケストレーションを使用してください。
• AGENTS.md はクロスツール対応：AGENTS.md は Cursor、Copilot、Amp、Jules、Gemini CLI、および 60,000 を超えるオープンソースプロジェクトで動作します。CLAUDE.md は Claude 専用です。
• プロファイルが手動切り替えに代わる：実行ごとにフラグを変更する代わりに、config.toml でプロファイルを定義します。

GitHub Copilot からの移行

得られるもの： - OS レベルのサンドボックス（Seatbelt/Landlock — コンテナベースに対しカーネル強制） - codex apply によるクラウドタスクの委任 - ワークフロー切り替えのための設定プロファイル - worktree 分離を備えたデスクトップアプリ

Cursor からの移行

クイックリファレンスカード

╔═══════════════════════════════════════════════════════════════╗
║                    CODEX CLI QUICK REFERENCE                  ║
╠═══════════════════════════════════════════════════════════════╣
║                                                               ║
║  LAUNCH                                                       ║
║  codex                      Interactive TUI                   ║
║  codex "prompt"             TUI with initial prompt           ║
║  codex exec "prompt"        Non-interactive mode              ║
║  codex app                  Desktop app                       ║
║  codex resume               Resume previous session           ║
║  codex fork                 Fork a session                    ║
║                                                               ║
║  FLAGS                                                        ║
║  -m, --model <model>        Select model                      ║
║  -p, --profile <name>       Load config profile               ║
║  -s, --sandbox <mode>       Sandbox mode                      ║
║  -C, --cd <dir>             Working directory                 ║
║  -i, --image <file>         Attach image(s)                   ║
║  -c, --config <key=value>   Override config                   ║
║  --ask-for-approval <p>     Approval policy                   ║
║  --oss                      Use local models (Ollama)         ║
║  --search                   Enable live web search            ║
║                                                               ║
║  SLASH COMMANDS (in TUI)                                      ║
║  /compact      Free tokens   /diff        Git diff            ║
║  /review       Code review   /plan        Plan mode           ║
║  /model        Switch model  /status      Session info        ║
║  /fork         Fork thread   /goal        Persisted goal      ║
║  /vim          Modal Vim     /hooks       Browse/toggle hooks ║
║  /init         AGENTS.md scaffold                             ║
║  /mcp          MCP tools     /skills      Invoke skills       ║
║  /ps           Background    /personality Style               ║
║  /permissions  Approval mode /statusline  Footer config       ║
║  /fast         Toggle fast mode (default: on)                ║
║  /copy         Copy last response to clipboard                ║
║  /clear        Clear screen  /theme       Syntax highlighting ║
║                                                               ║
║  TUI SHORTCUTS                                                ║
║  @              Fuzzy file search                             ║
║  !command       Run shell command                             ║
║  Ctrl+G         External editor                               ║
║  Ctrl+L         Clear screen                                  ║
║  Enter          Inject instructions (while running)           ║
║  Esc Esc        Edit previous messages                        ║
║                                                               ║
║  EXEC MODE (CI/CD)                                            ║
║  codex exec --sandbox workspace-write "task" Sandboxed auto   ║
║  codex exec --json -o out.txt "task"    JSON + file output    ║
║  codex exec --output-schema s.json      Structured output     ║
║  codex exec resume --last "continue"    Resume session        ║
║                                                               ║
║  MCP MANAGEMENT [EXPERIMENTAL]                                ║
║  codex mcp add <name> -- <cmd>    Add STDIO server            ║
║  codex mcp add <name> --url <u>   Add HTTP server             ║
║  codex mcp list                    List servers                ║
║  codex mcp login <name>           OAuth flow                  ║
║  codex mcp remove <name>          Delete server               ║
║                                                               ║
║  PLUGINS                                                      ║
║  codex plugin marketplace add <src>     Add marketplace       ║
║  codex plugin marketplace upgrade       Upgrade marketplaces  ║
║                                                               ║
║  CLOUD [EXPERIMENTAL]                                         ║
║  codex cloud exec --env <ID> Start cloud task                 ║
║  codex cloud status <ID>     Check task progress              ║
║  codex cloud diff <ID>       View task diff                   ║
║  codex cloud list            List tasks                       ║
║  codex apply <TASK_ID>       Apply cloud diff locally         ║
║                                                               ║
║  CONFIG FILES                                                 ║
║  ~/.codex/config.toml        User config                      ║
║  .codex/config.toml          Project config                   ║
║  ~/.codex/AGENTS.md          Global instructions              ║
║  AGENTS.md                   Project instructions             ║
║  requirements.toml           Enterprise policy constraints    ║
║                                                               ║
║  SANDBOX MODES                                                ║
║  read-only          Read files only, no mutations             ║
║  workspace-write    Read/write in workspace + /tmp            ║
║  danger-full-access Full machine access                       ║
║                                                               ║
║  APPROVAL POLICIES                                            ║
║  untrusted     Prompt for all mutations                       ║
║  on-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (April 2026)                                          ║
║  gpt-5.5               Recommended default (400K in Codex)   ║
║  gpt-5.5-pro           Highest-effort GPT-5.5 tier            ║
║  gpt-5.4               Prior flagship / fallback              ║
║  gpt-5.4-mini          Subagent work, 2x faster (400K)        ║
║  gpt-5.3-codex         Legacy coding specialist               ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

変更履歴

参照

OpenAI blog URLs に関する注記: 参照 ¹⁶、²⁵〜³⁰、³³、⁶⁴、⁶⁶、⁶⁷、⁷⁶、⁷⁷ は openai.com/index/ の blog posts にリンクしており、Cloudflare bot protection により自動アクセスには HTTP 403 を返します。これらの URL は標準的な web ブラウザからアクセスすると有効です。