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

要点: Codexは、コードベースを読み取り、OSレベルのsandbox内でコマンドを実行し、ファイルにパッチを適用し、タスクをクラウドへ委譲する、複数の利用面を持つコーディングエージェントです。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）、料金はMTokあたり$5/$30、Terminal-Bench 2.0で82.7%のSOTAです。⁸³ CLI v0.140.0（stable、2026年6月15日）時点では、/usageで日次・週次・累計のアカウント token activity を表示でき、codex delete / /deleteからセッションを完全削除できます（確認の安全策付き）。また、/importでClaude Codeからセットアップ、プロジェクト設定、最近のチャットを選択的に移行でき、@を入力するとデフォルトでファイル、plugins、skillsの統合mentions menuが開きます。さらに、managed Amazon Bedrock API-key authenticationが、CLIおよびMCP OAuth認証情報向けの暗号化ローカルストレージとあわせて提供されました。一方、実験的な/realtime音声コントロールはTUIから削除されています。¹⁰² CLI v0.139.0（stable、2026年6月9日）時点では、code modeからstandalone web searchを直接呼び出せるようになりました（ネストされたJavaScript tool callsからの呼び出しを含む）。結果はプレーンテキストで受け取れます。tool/connectorの入力スキーマは、大規模スキーマやMCPとの互換性を高めるためにoneOf/allOf構造を保持するようになり、codex doctorにはeditorとpagerの環境詳細が追加されました（JSONでは機密値をredactします）。plugin marketplaceではcodex plugin marketplace list --jsonにsourcesが表示され、キャッシュ済みカタログの一覧表示も高速化されています。¹⁰³ v0.138.0（6月8日）では、macOSとWindowsでCLIセッションをdesktop appへ引き継ぐ/appが追加され、ローカル画像パスがモデルに提示されるようになりました。reasoning-effortの選択はより柔軟になり、plugin automationには構造化されたJSON出力が追加されています。¹⁰⁴ v0.137.0（6月4日）では、multi-agent v2（runtimeをthreadごとに保持、follow-upとmetadata defaultsの整理、hide_spawn_agent_metadataはデフォルトtrue）、F13〜F24のTUI keybindings、turnごとのcatalog resolutionを備えたv1 skills extensionが提供されました。¹⁰⁵ CLI v0.135.0（2026年5月28日）時点では、codex doctorがより詳しいenvironment、Git、terminal、app-server、thread inventoryを報告します。TUIがremote経由で接続されている場合、/statusにはremote connection detailsとserver versionが表示されます。vim modeにはtext-object編集、word/line-end挙動の改善、設定可能なinterrupt-turnが追加されました。/permissionsはnamed permission profilesを理解し、custom profilesも表示します。パッケージ化されたCodex buildsは、対応macOS上で同梱のpatched zsh helperを検出して使用します。また、Python SDKはthreadおよびturn API向けに扱いやすいSandbox presetsを公開しています。¹⁰⁷ v0.134.0（2026年5月26日）では、case-insensitiveな本文一致とresult previewsを備えたローカル会話履歴の検索が導入され、CLI、TUI permissions、sandbox flows全体で--profileが主要なprofile selectorになりました（legacy profile configsは移行ガイダンス付きで拒否されます）。MCPセットアップは、サーバーごとのenvironment targetingとstreamable HTTP servers向けのOAuth optionsで改善されました。connector tool schemasは、ローカル$ref/$defsを保持し、肥大化したschemasを圧縮することで信頼性が高まりました。read-only MCP toolsは、readOnlyHintをadvertiseしている場合にconcurrently実行できるようになり、extension tools向けにconversation historyを含む、より豊かなextensionとhook contextも追加されています。¹⁰¹ v0.133.0（2026年5月21日）では、goalsがデフォルトで有効になり、専用ストレージとprogress trackingが追加されました。codex remote-controlにはforeground readiness/statusとdaemon-style start/stopが加わりました。permission profilesにはlist APIs、inheritance、managed requirements.toml、runtime refresh、より強いWindows sandbox integrationが追加されました。plugin discoveryではinstalled versions、marketplace roots、remote collectionsが表示されます。extensionsはsubagent start/stop、tool execution、turn metadata、async approval/turn processingを監視できます。5月21日のCodex app updateでは、最前面のMac windows向けAppshots、app/IDE/CLI全体でのGoal mode GA、in-app browser annotationの改善、対象Macユーザー向けのopt-in locked Computer Useが追加されました。⁹⁹¹⁰⁰ v0.132.0（2026年5月20日）では、Python SDKのfirst-class auth、よりシンプルなtext-only turn APIs、より豊かなTurnResult、codex exec resume --output-schema、TUI startupの高速化、auth-backed remote executor registration、app-server turnsでのimage-fidelity preservationが追加されました。legacy --full-autoではなく、明示的なsandbox/approval flagsまたはpermission profilesを引き続き優先してください。js_replは削除されたままです。^{86878991969798}

Codexは複数の利用面を持つコーディングエージェントとして動作します。コードを書くチャットボットではありません。CLIはコードベースを読み取り、sandbox内でコマンドを実行し、ファイルにパッチを適用し、MCP経由で外部サービスへ接続し、長時間実行されるタスクをクラウドへ委譲します。実行はローカルですが、思考はグローバルです。働き方に応じて、同じ知能が5つの異なるsurfaceを支えます。ブラウザーを乗っ取らずにCodexをブラウザー内で動かせる新しいChrome extensionもその1つです。⁹⁰

Codexを気軽に使う場合と効果的に使う場合の違いは、5つの中核システムを理解しているかどうかです。 これらを習得すると、Codexは強力な増幅装置になります。

1. 設定システム: config.tomlで挙動を制御します
2. Sandbox & approval model: Codexが実行できることを制御します
3. AGENTS.md: プロジェクトレベルの運用契約を定義します
4. MCP protocol: 外部サービスへ機能を拡張します
5. Skills system: 再利用可能なドメイン知識をパッケージ化します

私は数か月にわたり、本番コードベース、CI/CDパイプライン、チームワークフローでClaude Codeと並行してCodexを使ってきました。このガイドは、その経験を、使い始めた当時に欲しかった完全な参照資料としてまとめたものです。すべての機能に、実際の構文、現実的な設定例、経験豊富なユーザーでもつまずきやすいedge casesを含めています。

安定性に関する注記: [EXPERIMENTAL]またはunder developmentと記載された機能は、リリース間で変更される可能性があります。v0.133.0（2026年5月21日）時点では、goalsはデフォルトで有効、permission profilesはfirst-classなmanaged surface、plugin discoveryはより調査しやすく、remote-controlはforegroundまたはdaemonized app-server commandとして実行しやすくなっています。Codex Cloudとcode modeは引き続きexperimentalまたはunder developmentです。一方、core CLI、sandboxing、AGENTS.md、config.toml、Skills、hooks、multi-agent tools、plugins、Browser、Computer Use、Appshotsは、platformとplanに応じてstableまたはdocumented user-facing surfacesです。v0.132.0ではPython SDK authとstructured resume automationが補完されました。v0.131.0では、codex doctor、統合@ mention search、marketplace CLI commands、version-aware plugin sharing、runtime enable/disable付きdaemon-managed remote-control、registry-backed environments、追加のWindows sandbox hardeningが導入されています。⁹⁶⁹⁷⁹⁸ Legacy --full-autoは引き続きdeprecatedで、js_replも削除されたままです。⁸⁶⁸⁷

重要ポイント

• 5つのサーフェス、1つの頭脳: CLI、desktop app、IDE extension、cloud tasks、新しい Chrome extension は、すべて同じ 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 以上のオープンソースプロジェクトで機能します。一度書けば、どこでも使えます。
• Profiles でコンテキスト切り替えの負担を減らす: 名前付きの設定プリセット（fast、careful、auto）を定義し、--profile で切り替えられます。
• コンテキスト管理が重要: GPT-5.5 は Codex で 400K、API で 1M のコンテキストウィンドウを提供します。GPT-5.4 mini も、低レイテンシの subagent 作業向けに 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          │
└─────────────────────────────────────────────────────────┘

Core Layer: GPT-5.x モデルファミリーがすべてを動かしています。2026年4月23日時点では、利用できる場合、gpt-5.5 が推奨モデルです。Codex では 400K コンテキスト（API では 1M）、Terminal-Bench 2.0 SOTA で 82.7% を達成しています。gpt-5.4 はロールアウト中のフォールバック既定値のままです（1M コンテキスト、ネイティブな computer use）。⁸³⁶⁴ ファイルを読み、パッチを書き、shell コマンドを実行し、コードベースについて推論します。コンテキストがいっぱいになると、Codex は会話を圧縮して空き容量を作ります。このレイヤーではトークンを消費します。

Security Layer: Codex が実行するすべてのコマンドは、OSレベルのサンドボックスを通過します。macOS では、Apple の Seatbelt フレームワークがカーネルレベルの制限を適用します。Linux では、Landlock + seccomp がファイルシステムと syscall へのアクセスをフィルタリングします。サンドボックスはコンテナ内ではなく、カーネルレベルで動作します。そのうえで approval policy が、人間の確認を求めるタイミングを決定します。

Extension Layer: MCP は外部サービス（GitHub、Figma、Sentry）に接続します。Skills は、Codex が必要に応じて読み込む再利用可能なワークフローをパッケージ化します。Apps は ChatGPT connectors に接続します。Web search は、インターネットからリアルタイムのコンテキストを追加します。

Surface Layer: CLI は terminal のパワーユーザーと自動化向けです。Desktop app は、マルチスレッドのプロジェクト管理に使います。IDE extension は、編集、コンパイル、テストのループ向けです。Cloud は、独立して実行される非同期タスクに使います。

重要なポイント: ほとんどのユーザーは 1つのサーフェスだけを使います。パワーユーザーは 5つすべてを使います。長時間実行タスクには Cloud、決定論的な repo 操作には CLI、密なコーディングループには IDE extension、計画と調整には desktop app、サインイン済みのブラウザワークフローには Chrome を使います。

目次

1. Codex をインストールするには？
2. クイックスタート: 最初のセッション
3. 主要なインタラクションサーフェス
4. 設定システムの詳細
5. どのモデルを選ぶべきですか？
6. Codex のコストは？
7. 判断フレームワーク
8. Sandbox & Approval System はどう動作しますか？
9. AGENTS.md はどう動作しますか？
10. Hooks
11. MCP（Model Context Protocol）とは？
12. Code Mode
13. JavaScript REPL Runtime
14. Skills とは？
15. Plugins
16. Plan Mode & Collaboration
17. Memory System
18. Session Management
19. Non-Interactive Mode (codex exec)
20. Codex Cloud & Background Tasks
21. Codex Desktop App
22. GitHub Action & CI/CD
23. Codex SDK
24. Performance Optimization
25. 問題をデバッグするには？
26. Enterprise Deployment
27. Best Practices & Anti-Patterns
28. Workflow Recipes
29. Migration Guide
30. Quick Reference Card
31. Changelog
32. References

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

Package Managers

# 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

Direct Install Script（v0.106.0以降）

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

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

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

Binary Downloads

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

システム要件

• macOS: Apple SiliconまたはIntel（Seatbeltによる完全なsandboxサポート）
• Linux: x86_64またはarm64（Landlock + seccompによるsandbox）
• Windows: 制限付きトークンによるネイティブsandbox（v0.100.0で実験的機能から昇格）。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キーチェーン）、auto（利用可能ならkeyring、そうでなければfileにフォールバック）です。

Shell Completions

# 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.133.0

Quick Start: 最初のセッション

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は実行せずに計画を作成します。計画を確認し、承認すると実行が始まります。

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

Terminal UI は、次の要素を備えたフルスクリーンアプリです。

• Composer: プロンプトを入力し、@ でファイルを添付し、! プレフィックスでシェルコマンドを実行できます
• Output pane: モデルのストリーミング応答、ツール呼び出し、コマンド出力を表示します
• Status bar: モデル、トークン使用量、git ブランチ、sandbox mode を表示します

主な TUI ショートカット:

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

TUI で利用できる Slash commands:

ワークフローピッカーの再設計（v0.129.0）: 再設計されたピッカーにより resume と fork にアクセスしやすくなりました。また、新しい raw scrollback mode により、コマンドやモデル出力をそのままコピーしたいときに、レンダリング前の transcript をスクロールできます。長いデバッグセッションの切り分けや、出力を別のツールにパイプするときに便利です。⁸⁹

統合された @ mentions メニュー（v0.140.0）: composer で @ を入力すると、デフォルトでファイル、plugins、skills を横断する単一の mentions メニューが開くようになりました。ファイルだけを添付する従来のフローに代わり、1回のキー入力で任意のプロジェクトリソースを参照できます。¹⁰²

2. Codex Desktop App（macOS + Windows）

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

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

• Multi-tasking: 異なるプロジェクトにまたがって、複数の並列 agents を同時に実行できます
• Git worktree isolation: 各スレッドは repo の分離されたコピー上で作業します
• Inline diff review: アプリを離れずに変更を stage、revert、commit できます
• Integrated terminal: コマンド実行用にスレッドごとの terminal を使えます
• Conversation forking: 会話を分岐して別案を検討できます
• Floating pop-out windows: 会話を切り離して移動可能なウィンドウにできます
• Automations: 定期タスク（issue triage、CI monitoring、alert response）をスケジュールできます
• Appshots: 最前面の Mac アプリウィンドウを、スクリーンショットと利用可能なテキスト付きでスレッドに添付できます
• In-app browser comments: ローカルまたは公開ページをプレビューし、要素や領域にコメントを残して、Codex に正確なビジュアルフィードバックへ対応させられます
• Computer Use: スコープを限定した GUI 作業のために、許可した Mac アプリを Codex に操作させられます。対象となる remote Mac Computer Use ターンでは、ロックされた使用は opt-in です

アプリと CLI の使い分け: 複数の作業ストリームを調整する場合や、ビジュアルな diff review が必要な場合はデスクトップアプリを使います。terminal の合成しやすさ、スクリプト化、CI/CD 統合を重視する場合は CLI を使ってください。

3. IDE Extension（VS Code, Cursor, Windsurf）

Codex IDE extension は、エディタに直接統合されます。

• Agent mode by default: ファイルを読み、編集し、コマンドを実行します
• Inline edits: アクティブなファイルに対して、コンテキストに応じた提案を行います
• Shared sessions: セッションは CLI と IDE extension の間で同期されます
• Same authentication: ChatGPT アカウントまたは API key でサインインします

VS Code Marketplace または Cursor/Windsurf extension stores からインストールできます。³

4. Codex Cloud [EXPERIMENTAL]

Cloud tasks は、OpenAI が管理する環境で非同期に実行されます。

• Fire and forget: ローカルマシンとは独立して実行されるタスクをキューに入れられます
• Parallel execution: 複数の cloud tasks を同時に実行できます
• PR creation: Codex が完了した作業から pull requests を作成します
• Local apply: codex apply <TASK_ID> で cloud の結果をローカル repo に取り込めます

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

Cloud tasks は chatgpt.com/codex からも利用できます。⁴

5. Codex for Chrome [NEW]

Codex は Chrome 用のブラウザ拡張機能としても提供され、CLI、デスクトップアプリ、IDE extension、cloud に続く5つ目のインターフェースを追加します。この拡張機能は、通常のブラウジングを乗っ取るのではなく、並走するように設計されています。Codex はバックグラウンドで複数タブをまたいで並列に動作し、どのサイトに触れるかは利用者が制御できます。⁹⁰

• Parallel tab execution: Codex は前面タブをロックせず、複数のタブを同時に操作します。
• Per-site control: Codex が操作できる Web サイトを allow-list で指定します。デフォルトではアクセス権はありません。
• Browser as the workbench: この拡張機能は、ページ自体が信頼できる情報源になるアプリや Web サイト作業に最適です。admin consoles、internal dashboards、content-management UIs、ticket systems などが対象であり、ローカル repo に対する CLI の代替ではありません。
• Same brain: Codex for Chrome は、他のインターフェースと同じ GPT-5.x-Codex の知能で動作します。そのため、CLI で機能する AGENTS.md や skills 設定の規約は、ブラウザ駆動の作業にもそのまま引き継がれます。

Codex Chrome extension docs からインストールできます。⁹⁰

設定システムの詳細

Codex は設定に TOML を使用します。競合が発生したときにどの設定が優先されるかを決めるため、優先順位の階層を理解しておくことが重要です。

優先順位（高い順）

1. Session overrides（最高）: CLI flags（--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile）と -c key=value overrides
2. Project config（.codex/config.toml、CWD から project root へ向かって検出され、最も近いディレクトリが優先されます）
3. User config（$CODEX_HOME/config.toml、デフォルトは ~/.codex/config.toml）
4. System config（Unix では /etc/codex/config.toml）
5. Built-in defaults（最低）

requirements.toml は、通常の config マージ後にユーザーが選択できる値を制限する policy constraint layer として機能します。詳しくは Enterprise Deployment をご覧ください。

Config ファイルの場所

Expert tip: CODEX_HOME environment variable は、デフォルトの ~/.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 = 400000           # 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
service_tier = "fast"                  # Preferred service tier for new turns
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
sqlite_home = ""                        # Override SQLite-backed resumable state location

# ─── 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)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
enable_request_compression = true       # zstd request compression where supported (stable)
fast_mode = true                        # Service-tier selection and Fast-tier commands (stable)
goals = true                            # Goal mode; stable and on by default in v0.133.0+
hooks = true                            # Lifecycle hooks (stable)
multi_agent = true                      # Enable multi-agent collaboration tools (stable)
personality = true                      # Personality selection (stable)
plugins = true                          # Plugin system (stable)
plugin_hooks = true                     # Plugin-bundled hooks (stable)
plugin_sharing = true                   # Workspace plugin sharing (stable)
browser_use = true                      # In-app browser automation (stable)
browser_use_external = true             # Chrome extension browser use (stable)
computer_use = true                     # macOS Computer Use (stable, plan/region gated)
in_app_browser = true                   # Shared rendered-page preview (stable)
image_generation = true                 # Image-generation tool (stable)
guardian_approval = true                # Auto-review approval path (stable)
skill_mcp_dependency_install = true     # Prompt/install missing skill MCP deps (stable)
tool_suggest = true                     # Tool/plugin suggestion surface (stable)
workspace_dependencies = true           # Workspace dependency discovery (stable)
memories = true                         # Memories (experimental)
network_proxy = false                   # Sandboxed networking proxy (experimental)
prevent_idle_sleep = true               # Keep machine awake during active turns (experimental)
terminal_resize_reflow = true           # Terminal reflow improvements (experimental)

# Removed or deprecated feature names still appear in `codex features list`
# for migration diagnostics. Do not set removed flags such as
# `collaboration_modes`, `request_rule`, `codex_git_commit`,
# `apply_patch_freeform`, `search_tool`, or `js_repl` in new configs.

# ─── 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

Profiles

作業モードごとに使える名前付きの設定プリセットです。

# 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"

profile を有効化します。

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

Expert tip: config のトップレベルで profile = "fast" を設定すると、デフォルトの profile を指定できます。セッションごとに上書きする場合は --profile を使います。

カスタム Model Providers

Azure、AWS Bedrock、ローカルモデル、proxy services に接続します。

[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.
# v0.140.0+ adds managed Amazon Bedrock API-key authentication, and stores
# CLI and MCP OAuth credentials in encrypted local storage.[^184]
[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"

Warning: chat/completions wire API（wire_api = "chat"）は、OpenAI-hosted models では deprecated となり、OpenAI は 2026年2月に削除すると発表しています。³⁴ Local providers（Ollama、LM Studio）では、この形式を引き続き受け付ける場合があります。OpenAI endpoints では、代わりに wire_api = "responses" を使用してください。

--oss flag でローカルモデルを使用します。

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

または config で設定します。

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

Inline Config Overrides

command line から任意の config 値を上書きします。

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月時点）

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%向上しています。⁸³

GPT-5.4はすべてのCodexサーフェス（CLI、app、IDE extension、cloud）で引き続き利用可能です。⁶⁴ 正確なモデルリストはアカウントとロールアウト状況によって異なります。ローカルキャッシュをご確認ください：~/.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経由で引き続き利用できます。⁷¹

無料層に関する注記（2026年5月5日）：GPT-5.5 Instantは2026年5月5日にChatGPT無料層に展開されました。これによりGPT-5.5ファミリーの対象が有料プランの枠を超えて広がりますが、Codex CLIへのアクセスには引き続き対象となるPlus / Pro / Business / Enterprise / Edu / Goサブスクリプション、またはAPIキーが必要です。⁹²

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のサブエージェントに狭いサブタスク（コードベース検索、ファイルレビュー、ドキュメント処理）を並列で処理させましょう。⁷⁶

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

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

Sandbox と承認システムはどのように動作しますか？

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

レイヤー 1: Sandbox（何が可能か）

Sandbox は、OS ネイティブの仕組みを使ってファイルシステムとネットワークアクセスを制御します。

プラットフォーム別の強制方法:

• macOS: Apple の Seatbelt フレームワークを sandbox-exec 経由で使用します。モード別のプロファイルは実行時にコンパイルされ、カーネルによって強制されます⁶。v0.121.0 時点では、macOS sandbox プロファイルで特定の Unix sockets（例: docker.sock、エディター IPC sockets）を allowlist でき、private DNS resolution もデフォルトではブロックされなくなりました。⁸²
• Linux: ファイルシステム制限には Landlock、syscall filtering には seccomp を使用します。スタンドアロンのヘルパープロセス（codex-linux-sandbox）が多層防御の分離を提供します。⁵ Bubblewrap（bwrap）は Linux ビルドの一部として vendored され、コンパイルされます（v0.100.0 で optional から昇格）⁷。v0.117.0 では、古い kernel configuration を持つ古い distro での sandbox の信頼性が改善されました。⁷⁵ v0.129.0 では Linux の sandbox 起動が強化され、vendored Bubblewrap が upstream security patches を含む 0.11.2 に更新されました。v0.130.0 では、さらに起動時の強化が追加されています。⁸⁹⁹¹
• Windows: restricted tokens を使うネイティブ sandbox です（v0.100.0 で experimental から昇格）。WSL もサポートされています（Linux の Landlock + seccomp を継承）。v0.117.0 には、より良いプロセス分離のための restricted-token sandbox 改善が含まれます。⁷⁵ v0.130.0 では、sandbox ユーザーに desktop runtime binary cache へのアクセスを付与し、Windows sandbox が workspace-sandbox ユーザー向けに runtime binaries を確実に解決できるようになりました。⁹¹

なぜ重要か: container-based sandboxing（Docker）とは異なり、OS レベルの sandboxing はより高速で軽量であり、脱出も困難です。Codex が system call を見る前に、カーネルが制限を強制します。

セキュリティ修正: - zsh-fork sandbox bypass（v0.106.0）: zsh forking 経由の shell 実行で sandbox 制限を回避できる脆弱性を修正しました。⁶⁰ 以前のバージョンを使用している場合は、すぐにアップグレードしてください。 - 入力サイズ上限（v0.106.0）: Codex は、過度に大きな payload によるハングを防ぐため、約 100万文字の入力上限を強制するようになりました。⁶⁰ - Secure devcontainer profile（v0.121.0）: Docker devcontainers 向けの新しい強化済み customer profile では、コンテナー内の sandboxing に Bubblewrap を使用します。WSL2 はサポートされていますが、WSL1 は明示的に拒否されます（Bubblewrap は WSL1 の kernel shim と互換性がありません）。⁸² - Guardian review + hooks（v0.121.0）: Guardian review session 中は hooks が 無効化 されるため、pre/post-tool hooks が Guardian subagent の判断に干渉できません。⁸² ログ記録や検証に hooks を使っている場合、Guardian review ではそれらがスキップされる点に注意してください。完全な監査証跡が必要な場合は、app-server observability にフォールバックします。 - Linux /dev filesystem（v0.105.0）: Linux 上の sandboxed commands は最小限の /dev ファイルシステムを受け取るようになり、device nodes を想定するツールとの互換性が向上しました。⁶¹

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

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

レイヤー 2: Approval Policy（いつ確認するか）

Approval policy は、Codex が人間の確認を求めて一時停止するタイミングを決定します。

on-failure は一部の古い例や互換性パスにまだ登場しますが、現在の OpenAI 設定ドキュメントでは deprecated とされています。対話的な実行には on-request を、外部の安全境界がすでにある非対話的な実行には never を推奨します。⁸⁷

個別の Approval IDs（v0.104.0+）

Codex は、複数ステップの shell 実行内の各 command に個別の approval ID を割り当てるようになりました。つまり承認は細粒度です。シーケンス内の 1 つの command を承認しても、同じ shell invocation 内の後続 command が自動的に承認されるわけではありません。⁴⁹

柔軟な Approval Controls（v0.105.0+）

approval flow は、追加の sandbox permissions と細かな rejection をサポートするようになりました。⁶¹

• 追加の sandbox permissions: command が現在の sandbox mode を超えるアクセスを必要とする場合、Codex は完全な mode change を要求するのではなく、特定の追加権限をリクエストできます
• 細かな rejection: 個別の tool calls を feedback 付きで拒否できるため、Codex は同じ command を単に再試行するのではなく、アプローチを調整できます

Runtime Permission Requests（v0.113.0+）

Codex には、モデルが実行時に追加権限をリクエストできる組み込みの request_permissions tool が含まれるようになりました。⁶⁹ モデルが elevated access を必要とするタスクに遭遇した場合、黙って失敗したり、ユーザーに別の flags で再起動を求めたりする代わりに、TUI approval flow を通じて特定の権限（filesystem paths、network access など）を正式にリクエストできます。

Permission Profiles（v0.113.0+、v0.128.0 と v0.133.0 で拡張）

Permission profiles は、ファイルシステムとネットワークの sandbox policies を名前付きで再利用可能なセクションに分割します。default_permissions には、:read-only、:workspace などの built-in profile を設定するか、カスタムの [permissions.<name>] table を指定します。⁸⁷ v0.133.0 では、profiles が managed surface として強化されました。list APIs は利用可能な profile metadata を公開し、profiles は相互に継承でき、managed requirements.toml は permission requirements を宣言でき、active profiles は実行時に更新され、Windows sandbox setup は個別の ad hoc policy ではなく resolved profile を使用するようになりました。⁹⁸

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"

project root が書き込み可能な場合でも読み取られるべきではない機密ファイルや globs には、none を使用します。一回限りの command 例外には、profile を広く拡張するよりも rules を優先してください。⁸⁷

従来の --full-auto ガイダンス

古いガイドでは、--full-auto は次の便利な alias として説明されていました。

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

v0.128.0 では、release notes で --full-auto が deprecated とされ、現在の CLI help には interactive runs 向けとして表示されなくなっています。代わりに、上記の明示的な flags または名前付き permissions profile を使用してください。⁸⁶

Sandbox reliability（v0.129.0）: Linux sandbox startup hardening により、遅いファイルシステムや symlinked checkouts での race が減ります。Windows sandbox reliability improvements は、long-running runs 中の複数の edge-case crashes に対応しています。また、vendored Bubblewrap は upstream security patches を含む 0.11.2 に更新されました。設定変更は不要です。これらを取り込むには codex update を実行してください。⁸⁹

推奨設定

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

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

Power user（full access、人間が確認）:

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

この組み合わせは、community-recommended の「sweet spot」です。最大限の capability を持ちながら、すべての command に承認が必要になります。⁸

CI/CD automation:

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

Guardian Subagent による Smart Approvals（v0.115.0+）

Smart Approvals では、すべての action に人間の承認を求める代わりに、review requests を guardian subagent にルーティングできます。guardian session は approvals をまたいで永続化され、prompt cache を再利用し、startup overhead を避けます。各 review は clean history を持ちます（過去の判断が後続 review に漏れることはありません）。⁷³

config.toml で reviewer を設定します。

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

これは、approval_policy = "never" で一律に許可するのではなく、reasoning を伴う automated review を行いたい CI/CD workflows で特に便利です。

Network Access の有効化

Codex は workspace-write モードでは、デフォルトで network access をブロックします。必要な場合に有効化します。

# 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 Proxy Support（v0.104.0+）

WebSocket traffic を proxy 経由でルーティングする企業環境向けに、Codex は WS_PROXY と WSS_PROXY environment variables をサポートするようになりました。⁴⁹

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

これらは既存の HTTPS_PROXY と SOCKS5 proxy support（v0.93.0+）を補完し、すべての transport layers をカバーします。

Sandbox のテスト

信頼する前に sandbox の挙動を検証してください。

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

sandbox が正しく動作している場合、workspace-scoped profile の下では、どちらの command も permission denied error で失敗するはずです。どちらかの command が成功した場合、sandbox configuration を調査する必要があります。

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 変更点: Tools は namespace 付きで登録されるようになったため、一覧に表示される tool 名は単独の名前ではなく <server>:<tool> 形式になります。修飾なしの tool 名を grep している scripts や prompts があれば更新してください。新しい supports_parallel_tool_calls フラグが同梱の MCP に渡されるようになり、サポートを宣言するサーバーでは並列実行が可能になります。Sandbox 状態のメタデータは MCP tool メタデータ経由で流れるようになったため、サーバー側で挙動を調整できます（例: read-only sandbox で実行中なら警告する）。カスタムの codex/sandbox-state request は 削除 されました。代わりにメタデータ経路を使ってください。MCP Apps ロールアウトの Phase 3 もここに入り、tool-call サポートが追加されています。deferred-call パターンを使うサーバーでは、flattened deferred tool calls もサポートされるようになりました。⁸²

MCP Servers の設定

STDIO servers（ローカルプロセス）:

# 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 servers（リモート）:

[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 でアクティブなサーバーと利用可能な tools を確認できます。/mcp verbose（v0.123.0+）⁸⁴ は、サーバー診断、resources、resource templates の完全な情報を返します。サーバーの読み込みに失敗している場合や、期待した場所に tools が表示されない場合に便利です。通常の /mcp は高速なままです。

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

Codex を MCP Server として実行する

Codex は、multi-agent orchestration 向けに自身を MCP server として公開できます。¹²

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

サーバーは 2 つの tools を公開します。 1. codex(): prompt、sandbox、model、approval parameters を指定して新しいセッションを開始します 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 Servers

実用的なパターン

Pattern 1: Context-aware development — Context7 をフレームワークの docs と組み合わせると、Codex が常に最新の API 参照を利用できます。

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

Pattern 2: Output limits — MCP tool の応答は、デフォルトで約 25K 文字に切り詰められます。大きな payload を返す tools（database queries、log captures など）では、enabled_tools を使って特定の tools に絞り、応答を集中させてください。

Pattern 2a: Multimodal tool output（v0.107.0） — Custom tools は、text に加えて multimodal output（images、rich content）を返せるようになりました。これにより、screenshots、diagrams、chart renders などの視覚的な成果物を生成する tools が、それらを分析用に model へ直接渡せます。⁶²

Pattern 3: Enterprise MCP governance — requirements.toml を使って、開発者が利用できる MCP servers を制限します。

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

requirements.toml 内の identity に一致しない server は、起動時にブロックされます。ポリシー設定全体については、Enterprise Deployment を参照してください。

Code Mode [EXPERIMENTAL]

Code mode（v0.114.0）は、agent のスコープを code-focused operations に制限することで、より分離された coding workflow を提供します。⁷⁰ 有効にすると、agent はより広範なシステム操作を行わず、code の読み取り、書き込み、テストに集中します。

v0.139.0 時点で、code mode は standalone web search を直接 呼び出せます。nested JavaScript tool calls からの呼び出しも含まれ、結果は plaintext で受け取ります。そのため、code-mode flow は sandboxed coding context から離れずに live information を取得できます。¹⁰³

この機能は experimental です。更新については release notes を確認してください。

JavaScript REPL Runtime [REMOVED]

Codex v0.100.0 では experimental な JavaScript REPL runtime（js_repl）が追加され、v0.106.0 では /experimental surface 経由で昇格されました。⁶⁰ ただし、この案内は現在では履歴情報です。v0.128.0 の release changelog には「Remove js_repl feature」と記載されており、現在の機能一覧では js_repl と js_repl_tools_only の両方が removed とされています。⁸⁶

新しい configs に features.js_repl = true を追加しないでください。繰り返し実行可能なロジックが必要な場合は、shell commands、checked-in scripts、MCP tools、または scripts/ directory を持つ Codex skill を使ってください。

Skillsとは何ですか？

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

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)

Metadata (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の場合）
• Creator: $skill-creatorを使って、新しいskillを対話的に作成します
• Installer: $skill-installer install <name>を使って、community skillsをインストールします

有効化/無効化

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

SkillsとSlash Commandsの違い

Skillsをデバッグする

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

1. 検出を確認: /skillsでTUIに一覧表示されるはずです
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エントリ、hooks、app connectorsを1つのインストール可能なパッケージに統合します（v0.110.0以降）。⁶⁵ v0.117.0以降、pluginsは第一級の機能になりました。product-scoped pluginsは起動時に自動同期され、/pluginsでは発見と管理のためのTUI内ブラウザーが提供されます。⁷⁵ v0.128.0では、marketplaceインストール、リモートバンドルキャッシュ、リモートアンインストールAPI、plugin同梱hooks、hookの有効化状態、external-agent configインポートにより、pluginワークフローが拡張されました。⁸⁶ v0.129.0（2026年5月7日）では、plugin workspace sharing（再公開せずにpluginセットをチームメイトへ共有）、share access controls（受信者ごとの有効化/無効化、取り消し）、source filtering（workspaceが取得するmarketplaceを制限）、そしてCLIではなく/pluginsブラウザーから直接呼び出せるmarketplace operationsが追加されました。⁸⁹ v0.133.0（2026年5月21日）では、plugin発見の監査がしやすくなりました。リスト出力がmarketplaceを認識し、インストール済みバージョンが見えるようになり、marketplaceルートが一覧表示され、リモートpluginコレクションも、結果がどのregistry由来か推測せずに確認できます。⁹⁸ v0.130.0（2026年5月8日）では、pluginパッケージングの透明性が高まり、共有ワークフローをより細かく制御できるようになりました。⁹¹

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

Plugin Sources

Plugin Discovery

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

@plugin Mentions（v0.112.0以降）

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

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

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

Plugin Marketplace（v0.113.0以降）

plugin marketplaceには、メタデータ、カテゴリ、評価を使ったより豊富な発見機能が含まれるようになりました。⁶⁹ インストール時の認証チェックでは、APIキーやOAuthを必要とするpluginsについて、インストール前に有効な認証情報があるかを検証します。アンインストールendpointにより、pluginsと関連設定をきれいに削除できます。

サードパーティMarketplacesの追加（v0.121.0以降）

現在のOpenAI Codex docsでは、marketplace source管理はcodex plugin marketplace配下に置かれています。これにより、OpenAIのファーストパーティmarketplaceを超えたサードパーティplugin配布が正式化され、GitHub repo shorthand、HTTP(S) Git URLs、SSH URLs、ローカルmarketplaceルートディレクトリがサポートされます。Git refを固定するには--refを使い、--sparse PATHの繰り返し指定はGitベースのmarketplace reposにのみ使用してください。⁹³

# 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呼び出し元（IDE/desktop統合）には、marketplacesをプログラムで登録するための並列endpointも用意されています。⁸²

セキュリティ上の考慮事項: サードパーティ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インストール、app connectorセットアップを統合します。1つのpluginに3つすべてを同梱できるため、チームのオンボーディングが速くなり、設定の可搬性も高まります。

Plan Modeとコラボレーション

Plan modeでは、Codexが変更を実行する前にアプローチを設計できます。デフォルトで有効です（v0.94.0以降）。¹⁴ 「Plan Mode vs Direct Execution」の判断ツリーについては、Decision Frameworksをご覧ください。

Plan Modeに入る

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

plan modeでは、Codexは次のことを行います。 - ファイルを読み、コードベースを分析します - 実装計画を提案します - 承認するまで変更は行いません - 専用のTUIビューに計画をストリーミングします

Steer Mode

Steer mode（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 modeはTUIで常に有効です。Codexの完了を待ってから指示したい場合は、ターン完了後に通常どおり入力するだけでかまいません。特別なモードは不要です。

TUIの強化（v0.105.0〜v0.106.0）

Syntax highlighting（v0.105.0）: TUIは、フェンス付きコードブロックとdiffをインラインでsyntax-highlightするようになりました。配色を選ぶには/themeを使います。⁶¹

新しいTUI commands（v0.105.0以降）:⁶¹

音声文字起こし（v0.105.0、experimental）: スペースバーを押すと、音声文字起こしでプロンプトを口述できます。この機能はexperimentalであり、マイク権限が必要になる場合があります。⁶¹ v0.107.0以降、realtime音声セッションはマイクとスピーカーデバイスの選択をサポートしており、特定の音声入力/出力ハードウェアを選べます。⁶² v0.140.0で削除: experimentalな/realtime音声コントロールとその音声依存関係はTUIから削除されました。スペースバーによる音声文字起こしには影響ありません。¹⁰²

その他の改善: - 長いリンクは、TUI行をまたいで折り返されてもクリック可能なままになりました（v0.105.0）⁶¹ - ローカルファイルリンクの表示形式が改善されました（v0.106.0）⁶⁰ - TUI markdownでは、OSC 8メタデータによりWebリンクがクリック可能に保たれます。また、窮屈なテーブルは、リンク先を失わずに読みやすいkey/value recordsへフォールバックします（v0.136.0）¹⁰⁶ - sub-agents向けのCtrl+C処理が修正され、child processesを適切に終了できるようになりました（v0.106.0）⁶⁰

Memory System

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

Memory Commands

メモリは~/.codex/memory/配下のmarkdownファイルに保存されます。Codexはセッション開始時にそれらを読み込み、以後すべてのセッションでの動作に反映します。

保存すべき内容

メモリは、永続的な好みやプロジェクト上の事実に最も向いています。

• プロジェクトの慣例: 「このプロジェクトではスペースではなくタブを使う」または「APIレスポンスには必ずmetaフィールドを含める」
• ツールの好み: 「npmではなくpnpmを使う」または「pytest -x --tb=shortでテストを実行する」
• アーキテクチャ上の決定: 「authモジュールはsrc/middleware/ではなくsrc/core/auth/にある」
• ワークフローの好み: 「diffを見せる前に必ずlinterを実行する」

PipelineでのMemory

codex execを実行すると、メモリは自動的に読み込まれます。つまり、CI/CD pipelineやスクリプトでもインタラクティブセッションと同じコンテキストを利用でき、呼び出しのたびに指示を繰り返す必要はありません。

Memoryの改善（v0.101.0〜v0.107.0）

• シークレットのサニタイズ: メモリはディスクに書き込まれる前に、自動的にシークレットが含まれていないかスキャンされます
• CWD対応: プロジェクト固有の想起のために、メモリファイルに作業ディレクトリのコンテキストが含まれるようになりました
• Developer messageの除外: Developer/system messagesはphase-1 memory inputから除外され、ユーザーとのやり取りに焦点を当てることでメモリ品質が向上します
• Diffベースの忘却（v0.106.0）: メモリはdiffベースの忘却を使って古くなった事実を削除するようになり、memory storeを長期的に軽く、関連性の高い状態に保ちます⁶⁰
• 使用状況を考慮した選択（v0.106.0）: Memory retrievalは使用状況を考慮するようになり、頻繁にアクセスされたメモリや最近関連性が高かったメモリを優先します⁶⁰
• 設定可能なメモリ（v0.107.0）: メモリは完全に設定可能になりました。codex debug clear-memoriesを使うと、保存済みメモリをすべてリセットして白紙の状態にできます。無関係なプロジェクト間でコンテキストを切り替えるときや、メモリ状態がずれてきたときに便利です⁶²
• Phase-2 model upgrade（v0.121.0）: phase-2 memory consolidation modelは、以前のデフォルトからgpt-5.4になりました。phase-2 pipelineはセッション間で実行され、phase-1 transcriptを永続的な事実へと抽出します。このモデル変更により、同じtoken costで想起品質が向上します。⁸²
• TUI memories menu（v0.121.0）: 新しいセッション内UIで、memory mode、個別メモリ削除、reset buttonを操作できるようになりました。Memory resetは過去のrolloutsを無効化せずに保持するようになったため、セッション再生を壊さず、将来の想起対象だけをクリアできます。⁸²

Memory vs AGENTS.md

Tip: 無期限に保持したい事実には/m_updateを使います。セッション固有のコンテキストは、会話の中でCodexに直接伝えてください。チームで共有するコンテキストにはAGENTS.mdを使います。

Session Management

Codexはセッションを~/.codex/sessions/配下に永続化し、CLIとdesktop surfacesの間でresume、fork、multi-thread workflowsを可能にします。

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 slash commandを使うと、検索付きの同じインタラクティブpickerが開きます。

Fork

現在の進行状況を失わずに、会話を分岐して別案を検討できます。

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

Forkでは、fork pointまで同じ履歴を共有する独立したthreadが作成されます。一方のforkでの変更は、もう一方には影響しません。アプローチを比較したい場合（例: 「forkしてMemcachedではなくRedisを試す」）や、リスクのある変更を安全に検討したい場合に便利です。

Thread forking into sub-agents（v0.107.0）: Threadsを独立したsub-agentsへforkできるようになり、会話から自律的に実行される並列work streamsを生み出せます。これは既存のfork modelを拡張するものです。単に会話を分岐するのではなく、forkされたthreadが独自のexecution contextを持つsub-agentになります。⁶² v0.117.0時点では、sub-agentsはpath-based addresses（例: /root/agent_a）とstructured inter-agent messagingを使うため、multi-agent coordinationがより明示的でデバッグしやすくなっています。⁷⁵

Thread Listing

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

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

desktop appでは、threadsはsidebarに表示され、完全な履歴とdiff previewsを確認できます。

Session Lifecycle

セッションはCLIとdesktop appの間で同期されます。一方で開始し、もう一方で続行できます。

非対話モード（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 パイプラインと組み合わせやすくなっています。

セッションのアーカイブ（v0.136.0）

履歴を削除せずに、resume/fork の一覧を整理するため、セッションをアーカイブできます。TUI では /archive、シェルでは次のようにアーカイブします。¹⁰⁶

codex archive <session-id>     # archive a session
codex unarchive <session-id>   # restore it

アーカイブ済みのセッションは、アーカイブを解除するまで resume や fork 操作の対象外になります。終了させるつもりだったセッションを誤って継続しないためのガードレールです。同じリリースでは、codex app-server --stdio により editor/host 統合向けに app-server を stdio モードで起動できるようになり、/diff はリポジトリ提供の Git ヘルパーを実行できないようになりました（コマンド安全性の修正）。Windows では、管理者向けの alpha プロビジョニング経路として codex sandbox setup --elevated が追加されています。¹⁰⁶

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 は、別プロセスから駆動されることを想定した headless app-server を起動するトップレベルコマンドです。IDE 拡張、カスタムオーケストレーター、リモート制御プレーンなどで利用できます。多くのインテグレーターが手作業で組み合わせていた複数フラグの codex app-server 呼び出しを置き換え、desktop と IDE サーフェスの下で提供されているものと同じ app-server runtime への、サードパーティツール向けの単一で安定したエントリーポイントを提供します。⁹¹ v0.133.0 では、このコマンドの実行時の形が改善されています。フォアグラウンドコマンドのように実行し、準備完了を待ち、マシンステータスを報告しつつ、長時間動作するコントローラー構成向けに明示的な daemon 形式の start / stop コマンドも提供できます。⁹⁸

# 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.

すべての turn を一度にメモリへ読み込まず、大規模な thread 履歴を列挙する必要がある UI を構築する場合は、codex remote-control を下記の app-server pagination API と組み合わせてください。

App-Server Thread Pagination（v0.130.0+）

app-server クライアントは、3 つの異なる turn item view を通じて大規模な thread をページングできるようになりました。⁹¹

v0.121.0 で導入された ThreadStore インターフェースと pagination を組み合わせると、長時間実行される thread を効率よくたどれます。特に、orchestrator が rollout ファイルとは別のマシンにある remote-control デプロイで有効です。⁸²

Live App-Server Config Refresh（v0.130.0+）

live app-server thread は、再起動しなくても config.toml の変更を取り込むようになりました。config を編集して保存すると、実行中の thread は次の turn で新しい値を反映します。これは codex remote-control に対応するバグ修正です。長時間動作する headless server を停止せず、その場で再設定できます。⁹¹

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

Status: Codex Cloud は experimental 機能です。インターフェース、価格、提供状況は変更される可能性があります。cloud environment は OpenAI が管理し、インフラストラクチャはユーザーが制御しません。

Codex Cloud は、OpenAI 管理環境でタスクを非同期に実行します。⁴ Codex を CI パイプラインに統合する方法については、GitHub Action & CI/CD も参照してください。

仕組み

1. タスクを送信します（chatgpt.com/codex、Slack 統合、または CLI 経由）
2. Codex が repo を隔離された cloud sandbox に clone します
3. エージェントが独立して作業します。コードを読み、テストを実行し、変更を加えます
4. 完了すると、Codex が PR を作成するか、レビュー用の diff を提供します
5. codex apply <TASK_ID> で結果をローカルに適用します

Cloud でのインターネットアクセス

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

• Off: エージェントのインターネットアクセスなし（デフォルト）
• On: 任意のドメイン allowlist + HTTP メソッド制限

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

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

Slack 統合

Slack チャンネルまたは thread で @Codex にメンションすると、cloud task を開始できます。

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

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 desktop app（macOS および Windows）は、複数プロジェクトの管理に最適化されたグラフィカルインターフェースを提供します。¹⁶ Windows 版は、ネイティブ PowerShell サポートとネイティブ Windows sandbox を備えて、2026年3月4日にリリースされました。⁶⁶

インストール

codex app                      # Auto-downloads and installs on first run

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

主な機能

Appshots、ブラウザーコメント、Computer Use

5月21日のアプリアップデートにより、desktop app は単なるスレッドマネージャーではなく、より強力なコンテキスト面になりました。Codex が操作する前に別の Mac アプリの状態を必要とする場合は、Appshots を使います。Codex は最前面のウィンドウ、アプリが公開している表示中/画面外の利用可能なテキストを取得し、その添付をセッション履歴にローカル保存します。⁹⁹

Web や frontend 作業では、ページが未認証ならまず アプリ内ブラウザー を使います。Codex とユーザーが共有できるレンダリング済みプレビューを提供し、クリック、スクリーンショット、アセットダウンロード、読み取り専用 inspection JavaScript などの browser-use アクションをサポートします。さらに、ページ領域にコメントを付けて、次のターンで Codex に対応させることもできます。⁹⁹ サインイン済みサイトでは、引き続き Chrome extension を使ってください。

Computer Use は、構造化された統合やブラウザープレビューではタスクを検証できない場合に限って使います。許可済みの Mac アプリを検査して操作できますが、ファイル編集や shell commands には Codex の承認と sandbox ルールが適用されます。locked use の範囲も狭く保たれます。Mac ロック後のアクティブな信頼済み Computer Use ターンの間だけ、Codex は許可済みアプリへ一時的にアクセスでき、再ロック保護とローカル入力検出が働きます。⁹⁹

スレッドモード

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

Worktree 分離の仕組み:

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

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

Automations

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

• Git repos では、automations は専用のバックグラウンド worktrees を使います（作業ディレクトリから分離されます）
• 非 Git プロジェクトでは、実行はプロジェクトディレクトリで直接行われます
• Automations はデフォルトの sandbox 設定を使います

automation の設定: 1. desktop app でプロジェクトを開きます 2. サイドバーの Automations タブをクリックします 3. トリガー（schedule、webhook、または manual）を定義します 4. プロンプトを書き、実行モード（local または worktree）を選択します 5. automation run の reasoning level を設定します（App v26.312）⁷² 6. Automations はスケジュールどおりに実行され、結果を review 用にキューへ入れます

使用例: - Issue triage: 新しい issue を自動的に分類し、優先順位付けします - CI monitoring: ビルド失敗を監視し、修正案を提示します - Alert response: 監視アラートに対して診断分析で対応します - Dependency updates: セキュリティパッチを確認して適用します

結果は、人間の承認用 review queue に表示されます。

Windows サポート

Codex Desktop App は、2026年3月4日（App v26.304）に Windows でリリースされました。ネイティブ PowerShell サポート、ネイティブ Windows sandbox に加え、WSL を必要とせずに skills、automations、worktrees を含む完全な機能同等性を備えています。⁶⁶

GitHub Action & CI/CD

公式 GitHub Action は、Codex を CI/CD pipeline に統合します。¹⁸

基本的な使い方

# .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。後続の steps/jobs で使う最終 Codex response text です。

Safety Strategies

Access Controls

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

デフォルト: write access を持つ collaborator だけが Codex workflows をトリガーできます。

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(...): 途中経過の更新に使える非同期イベントストリーム
• Python SDK auth（v0.132.0+）: API キーログイン、ChatGPT のブラウザー／デバイスコードフロー、アカウント確認、ログアウトが、正式な SDK パスとして扱われます。⁹⁷
• テキストのみの turn 簡易機能（v0.132.0+）: Python turn API はプレーン文字列を受け取り、収集された項目、タイミング、使用量を含む、より豊富な TurnResult メタデータを返します。⁹⁷
• outputSchema: JSON 形式の最終出力を強制します
• マルチモーダル入力: テキストとローカル画像（{ type: "local_image", path: "..." }）を渡せます
• 画像ワークフロー（v0.117.0）: view_image は URL を返し、生成された画像は再度開けるようになり、画像履歴はセッション再開後も保持されます⁷⁵
• マルチ環境 view_image（v0.130.0）: 複数環境にまたがるセッション（v0.124.0 で turn ごとの環境と作業ディレクトリ選択として導入され、v0.125.0 で固定環境として改良）では、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 に保存されます。

ランタイム: 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. 成果主導のループ: 手順を逐一指示する代わりに、「実装し、テストし、修正し、green になったら止める」と依頼します

問題をデバッグするには？

よくある問題と解決策

エラーメッセージ参照

診断ツール

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 で issue を作成してください。¹

Codex Security [PREVIEW]

Codex Security は 2026年3月6日に research preview に入り、コンテキストを理解したアプリケーションセキュリティレビューを Codex スタックにもたらしました。⁷⁷ Codex web 経由で、ChatGPT Pro、Enterprise、Business、Edu のお客様が利用できます。

仕組み: Codex Security はリポジトリを分析してプロジェクト固有の脅威モデルを構築し、現実世界での影響に基づいて分類された脆弱性を特定します。さらに、サンドボックス環境で検出結果に負荷をかけて検証します。エージェントは修正案とともに、より信頼度の高い検出結果を提示し、重要でないバグによるノイズを減らします。

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

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

Enterprise Deployment

管理者コントロール（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 はユーザーが選択できる値を制限する強制的な制約レイヤーであり、ユーザーはこれを上書きできません。管理者要件ルールで指定できるのは prompt または forbid のみです（暗黙的に許可することはありません）。

macOS MDM 設定

com.openai.codex preference domain を使用して MDM 経由で配布します。²¹ Codex は標準的な macOS MDM payload（Jamf Pro、Fleet、Kandji など）に対応しています。TOML は、行の折り返しなしで base64 としてエンコードします。

優先順位（高い順）:

1. macOS managed preferences（MDM）
2. Cloud-fetched requirements（ChatGPT Business / Enterprise）
3. /etc/codex/requirements.toml（ローカルファイルシステム）

Cloud requirements は未設定の requirement フィールドだけを補完するため、優先順位の高い managed レイヤーが常に優先されます。Cloud requirements はベストエフォートです。取得に失敗したりタイムアウトしたりした場合、Codex は cloud レイヤーなしで続行します。

OpenTelemetry 統合

Codex は、標準の OTel 環境変数から OpenAI API 呼び出しまで、OpenTelemetry trace-context の伝播に対応しています。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_* 環境変数が尊重されます（endpoint、service name、resource attributes）
• Trace context は Codex を通じて API 呼び出しへ伝播し、エンドツーエンドの可観測性を実現します
• Resource attributes を使って、team、environment、project ごとに trace にタグを付けられます
• prompt/tool logging を有効にする場合は、プライバシー要件に注意してください。trace に code snippets が含まれる可能性があります
• 設定可能な OpenTelemetry trace metadata（v0.130.0+）。 標準の OTEL_RESOURCE_ATTRIBUTES envelope に加えて、codex-otel crate は設定可能な trace metadata を公開するようになりました。これにより管理者は、呼び出しごとに OTEL_RESOURCE_ATTRIBUTES をゼロから組み直すことなく、組織固有のディメンション（cost-center、project ID、ticket reference）で trace にタグを付けられます。同じリリースで追加された、より豊富な review/feedback analytics と組み合わせることで、CLI、app-server、remote-control sessions 全体のデバッグとトリアージを統合できます。⁹¹

Enterprise Access

• ChatGPT Business / Enterprise / Edu: 組織管理者がアクセスを制御し、cloud-fetched requirements が自動的に適用されます。ID プロバイダー（Okta、Entra ID など）経由の SAML/OIDC による SSO に対応しています
• API: 標準の API auth、billing、org/project controls。OpenAI は SOC 2 Type II および SOC 3 レポートを公開しています。Enterprise tier では HIPAA BAA も利用できます
• Codex SDK: 内部ツールやワークフローに組み込めます
• 大規模なポリシー適用: MDM で配布する requirements_toml_base64 またはファイルシステムレベルの /etc/codex/requirements.toml を使用します

データ処理とコンプライアンス: - API の入力/出力は、OpenAI の Business/Enterprise/API terms の下ではトレーニングに使用されません - データレジデンシーについては、OpenAI API traffic はデフォルトで米国ベースのインフラストラクチャを経由します。EU データレジデンシー要件がある場合は、OpenAI の Enterprise sales team に相談してください - Session transcripts はローカルに保存されます。マシン外へ出るのは API calls のみです - ChatGPT Enterprise は、SOC 2、GDPR、CCPA などのコンプライアンスフレームワークに対応しています

Rollout Strategy

組織向けには、次の段階的なロールアウトを推奨します。

1. Pilot（Week 1-2）: 3〜5人の senior engineers にデプロイし、requirements.toml で untrusted sandbox mode と cached web search を強制します。AGENTS.md patterns と MCP server needs についてフィードバックを集めます。
2. Team expansion（Week 3-4）: チーム全体へ展開します。チーム標準の config.toml を MDM または repo 経由で配布します。信頼済み repositories では workspace-write sandbox を有効にします。
3. CI integration（Week 5-6）: 自動 PR review と test generation のため、CI/CD pipelines に codex-action を追加します。コストを予測しやすく保つために --ephemeral を使用します。
4. Org-wide（Month 2+）: 承認済みの MCP servers、sandbox policies、model allowlists を requirements.toml で強制し、MDM 経由でデプロイします。

Audit Patterns

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

• OpenTelemetry traces: チームごとの API call volume、token usage、latency を監視します
• Session persistence: コンプライアンスレビューのために ~/.codex/sessions/ を監査します（機密性の高い context では --ephemeral で無効化します）
• MCP identity enforcement: requirements.toml はブロックされた server attempts を記録します。不正な tool usage がないか確認してください
• Git audit trail: Codex によるすべてのファイル変更は標準の git を通ります。branch history と PR diffs でレビューします

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

Prompting パターン

1. 制約主導のプロンプト: 最初に境界条件を示します。「API contracts は変更しないでください。内部実装だけをリファクタリングしてください。」
2. 構造化された再現手順: あいまいな説明よりも、番号付きの手順のほうがバグ修正の精度が上がります
3. 検証リクエスト: 最後に「lint と、関連する最小のテストスイートを実行してください。コマンドと結果を報告してください。」と書きます
4. ファイル参照: @filename を使って、特定のファイルをコンテキストに添付します
5. 成果主導のループ: 「実装し、テストを実行し、失敗を修正し、すべてのテストが通ったときだけ停止してください。」Codex は完了するまで反復します

テスト哲学

コミュニティでは、テスト駆動の AI コラボレーションに収束しています:²²

• 完了シグナルとして、先にテストを定義します
• テストが通るまで Codex に反復させます（red → green → refactor）
• Tiger Style programming パターンを採用します
• パッチを依頼するときは、正確なファイル本文を提供します。Codex は fuzzy な AST ベースのパッチではなく、厳密な一致を使います

Context 管理のベストプラクティス

• web search に頼るのではなく、高品質なローカルドキュメントを提供します
• 目次や進捗ファイルを含む、構造化された markdown を維持します（「progressive disclosure」）
• パッチ失敗を防ぐため、追跡対象ファイル全体で改行コード（LF vs CRLF）を正規化します
• 長い指示はコンテキストから押し出されるため、AGENTS.md は簡潔に保ちます

Git Workflow

• 不慣れな repo で Codex を実行する前に、必ず新しい branch を作成します
• 直接編集ではなく、パッチベースの workflow（git diff / git apply）を使います
• Codex の提案は code review PR と同じようにレビューします
• commit 前に /diff で変更を確認します

コミュニティ Skills と Prompts

feiskyer/codex-settings repository では、コミュニティ管理の設定が提供されています:²³

再利用可能な prompts（~/.codex/prompts/ 内）: - deep-reflector: 開発セッションから学びを抽出します - github-issue-fixer [issue-number]: 体系的なバグ分析と PR 作成を行います - github-pr-reviewer [pr-number]: Code review workflows - ui-engineer [requirements]: 本番品質の frontend development

コミュニティ skills: - claude-skill: 権限モード付きでタスクを Claude Code に引き継ぎます - autonomous-skill: 進捗 tracking 付きの複数セッション task automation - deep-research: 並列 sub-task orchestration - kiro-skill: 要件 → デザイン → タスク → 実行の pipeline

アンチパターン

tokens を浪費したり、低品質な結果を生んだり、扱いにくい workflow を作ったりする、よくあるミスです。

Cost アンチパターン

Context アンチパターン

Workflow アンチパターン

Prompt アンチパターン

Workflow Recipes

一般的な開発シナリオ向けの、end-to-end パターンです。

Recipe 1: 新規 Project Setup

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

Recipe 2: Daily Development Flow

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 でレビューしてから、commit します。

Recipe 3: Plan Mode を使った複雑なリファクタリング

codex

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

plan をレビューします。承認するか、方向を調整します:

[Tab] Also add a migration script using Alembic

Codex の実行後に検証します:

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

Recipe 4: codex exec を使った PR Review

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

Recipe 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 から

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

• Sandbox は OS レベルです: Codex はコンテナではなく Seatbelt/Landlock を使用します。制限はアプリケーション層より下のカーネルレベルで動作します。
• Hooks は拡張中です: Codex は現在、5つの hook events に対応しています。SessionStart、Stop、UserPromptSubmit（v0.114.0〜v0.116.0、実験的）に加え、AfterAgent（v0.99.0）と AfterToolUse（v0.100.0）です。このシステムは、セッションライフサイクル、プロンプトのインターセプト、ツールレベルの自動化をカバーします。ただし、Claude Code の12以上のライフサイクルイベントのほうが、まだより広い範囲を扱えます。まだカバーされていない自動化パターンには、AGENTS.md instructions または skills を使用してください。
• Sub-agents v2（v0.117.0）: Sub-agents は、構造化されたエージェント間メッセージングとエージェント一覧に対応した、パスベースのアドレス（例: /root/agent_a）を使用するようになりました。⁷⁵ これは既存の仕組み（同時実行は最大6、v0.91.0で12から削減）を拡張するものです。マルチエージェントの roles は、引き続き config でカスタマイズできます（v0.104.0以降）。⁴⁷ v0.105.0 では、進捗追跡と ETA 付きで行ごとに fanout する spawn_agents_on_csv が追加されました。⁶¹ Codex には、ユーザー主導の委任に使える Claude Code の明示的な Task tool UX はまだありません。委任パターンには、cloud tasks または SDK orchestration を使用してください。
• AGENTS.md はツール横断です: AGENTS.md は Cursor、Copilot、Amp、Jules、Gemini CLI、そして60,000以上のオープンソースプロジェクトで機能します。CLAUDE.md は Claude 専用です。
• Profiles が手動切り替えを置き換えます: 実行ごとに flags を変更する代わりに、config.toml で profiles を定義します。

GitHub Copilot から

得られるもの: - OS レベルのサンドボックス化（Seatbelt/Landlock — コンテナベースではなくカーネルで強制） - codex apply による cloud task delegation - ワークフロー切り替え用の config profiles - worktree isolation を備えた desktop app

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 に関する注記: References ¹⁶、²⁵〜³⁰、³³、⁶⁴、⁶⁶、⁶⁷、⁷⁶、⁷⁷ は openai.com/index/ の blog posts にリンクしていますが、Cloudflare bot protection により自動アクセスでは HTTP 403 が返されます。これらの URL は、通常の web ブラウザからアクセスすると有効です。