OpenAI Codex CLI 完全ガイド｜インストールからAGENTS.md・MCP・組織導入まで実務で使い切る【2026年版】

OpenAI Codex CLI は、ターミナルから自然言語でコードを書かせる オープンソースのコーディングエージェント です。Rust で実装されており、ChatGPT のサブスクリプションまたは OpenAI API キーで認証して使います。Claude Code と並んで「ターミナル型 AI エージェント」のもう一つの主役として 2026 年現在広く採用されています。

ただし、Codex CLI は単なるコード補完ツールではありません。Approval Policy・Sandbox Mode・AGENTS.md・MCP・サブエージェント・Codex Cloud といった「機能の塊」を持っており、設定次第で動作が大きく変わります。「とりあえずインストールして使ってみる」では失敗しやすいツール でもあります。

本記事では、Codex CLI を「個人開発者の導入 5 分 → 実務で使い切る 15 分 → 組織導入 30 分」の 3 段階で体系的に整理します。コマンド一覧の羅列ではなく、どの場面でどの設定を選ぶか を判断軸付きで解説するのが本記事の狙いです。

免責事項: 最新の仕様・料金・コマンドは OpenAI 公式ドキュメント で必ず確認してください。本記事は執筆時点（2026 年 5 月）の情報に基づきます。

1. OpenAI Codex CLI とは（5 分で理解する位置づけ）

結論: Codex CLI は OpenAI が開発したオープンソースのターミナル型 AI コーディングエージェントです。Rust 製で軽量、OS のサンドボックス機構で安全策を担保し、ChatGPT サブスクリプションまたは API キーで認証します。

公式ドキュメントによれば、Codex CLI は「ターミナルから実行できるコーディングエージェント」と位置づけられており、選択したディレクトリ内でコードの読み取り・変更・実行を行います。詳細は Codex 公式 CLI ページ を参照してください。

1-1. Codex CLI の3つの特徴

Codex CLI を他のツールから区別する特徴は次の 3 点です。

1. オープンソースかつ Rust 製: ソースコードは公開されており、性能と起動速度に優れます。バイナリ配布のサイズも小さく、CI 環境への組み込みが容易です。
2. OS のサンドボックス機構による隔離: ファイル書き込み・ネットワークアクセスを OS のサンドボックス機構（macOS の Seatbelt、Linux の Landlock + seccomp 等）で物理的に制限します。アプリケーション層の hook で制御する Claude Code とは設計思想が異なります。
3. マルチサーフェス: ターミナル CLI、Codex Cloud（クラウド実行）、IDE 拡張（VS Code・Cursor・Windsurf 等）の 3 形態で同じ設定（AGENTS.md / config.toml）を共有できます。

1-2. Codex CLI / Codex Cloud / Codex IDE 拡張の関係

「Codex」というブランドの下に複数の製品があるため、最初に整理しておきましょう。

製品	実行場所	用途
Codex CLI	ローカル端末	対話・スクリプト実行・CI 用途
Codex Cloud	OpenAI クラウド	長時間タスク・並列タスク・サンドボックス分離
Codex IDE 拡張	VS Code / Cursor / Windsurf 内	エディタ統合・差分プレビュー

3 つは同じ AGENTS.md と config.toml を共有します。本記事は CLI を中心に扱いますが、Cloud と IDE 拡張への展開も後半で扱います。

1-3. 対応モデル（GPT-5.5 / GPT-5.4 / GPT-5.3-Codex / gpt-5.3-codex-spark）

Codex CLI から呼び出せるモデルは、認証方式（ChatGPT サブスク or API キー）と契約プランによって変わります。2026 年 5 月時点で公式に案内されているのは次のモデルです。

• GPT-5.5: 複雑なコーディング・大規模リファクタリング・推論を要する設計タスク向けの最新フロンティアモデル。OpenAI は Codex 内で最も推奨されるモデルとしています（公式リリース 参照）。
• GPT-5.4: GPT-5 系の標準モデル。コンテキスト長と推論性能のバランス型。
• GPT-5.3-Codex: コーディング特化の派生モデル。トークンコスト最適化向け。
• gpt-5.3-codex-spark: 研究プレビュー版。低レイテンシで対話型コーディングに特化。

セッション中に /model スラッシュコマンドでモデルを切り替えできます。タスクに応じて「設計議論は GPT-5.5、軽量リファクタは GPT-5.3-Codex」のように使い分けるのが実務的です。

詳細は Codex Models 公式ページ を確認してください。なお、各モデルの正確な性能数値・コンテキスト長・料金は変動するため、引用する場合は必ず最新の公式ドキュメントを参照してください。

2. インストールと初回セットアップ（5 分で完了）

結論: Node.js 18 以上が入っている macOS / Linux なら npm install -g @openai/codex と codex の 2 コマンドで起動できます。Windows は PowerShell ネイティブでも動作しますが、長期運用には WSL2 を推奨します。

2-1. システム要件

公式の Quickstart で示されている前提条件は次の通りです。

• macOS（最新 2 メジャーバージョン）/ Linux（主要ディストリビューション）/ Windows（10 以降）
• Node.js 18 以上（npm でインストールする場合）
• ターミナルエミュレータ（macOS 標準ターミナル、iTerm2、WezTerm、Windows Terminal など）
• ChatGPT アカウント（Plus / Pro / Business / Edu / Enterprise いずれか）または OpenAI API キー

2-2. インストール 3 方式

公式が案内している 3 つのインストール方法のうち、状況に応じて選びます。

方式	コマンド	向くケース
npm	npm install -g @openai/codex	Node.js が既に入っており、最も標準的
Homebrew	brew install --cask codex	macOS で Homebrew 中心の環境
GitHub Releases	github.com/openai/codex の Releases から OS 別バイナリ	Node.js / Homebrew を入れたくない、最新版を試したい

インストール後は codex --version で動作確認します。バージョンは公式 CHANGELOG で最新を確認してください。

2-3. 認証フロー（ChatGPT サインイン / API キー）

初回 codex 実行時にサインインプロンプトが表示されます。選択肢は 2 つです。

1. ChatGPT アカウント: ブラウザが開き、ChatGPT にログインして承認します。サブスクリプション（Plus / Pro / Business / Edu / Enterprise）に紐づいた利用枠で動作します。
2. OpenAI API キー: OPENAI_API_KEY 環境変数を設定するか、対話プロンプトでキーを入力します。従量課金（トークン課金）で動作します。

# API キーを環境変数で渡す例
export OPENAI_API_KEY="sk-..."
codex

サブスクリプションを既に契約しているなら ChatGPT サインインの方が定額で済むので有利です。API キーは「サブスク枠を超えるヘビーユース」「CI など対話できない環境」で使います。

2-4. セットアップ完了チェックリスト（15 項目）

最初のセッションで以下の 15 項目を順に確認すると、後の運用トラブルを避けやすくなります。

• Node.js 18 以上が node --version で確認できる
• codex --version で最新版（または安定版）が表示される
• 認証済みアカウントが /status スラッシュコマンド（または codex login --status 相当）で表示される
• 初回 codex 実行で対話 TUI が起動する
• /help で組み込みコマンド一覧が表示される
• プロジェクトルートに AGENTS.md が配置されている
• ~/.codex/config.toml が存在し、model / approval_policy / sandbox_mode が明示されている
• OPENAI_API_KEY を使う場合、シェルプロファイル（.zshrc / .bashrc / Microsoft.PowerShell_profile.ps1）に永続化されている
• VS Code / Cursor / Windsurf いずれかの IDE 拡張がインストール済み（必要なら）
• MCP サーバーを使う場合、~/.codex/config.toml の [mcp_servers.<name>] に登録されている
• Codex Cloud を使う場合、組織のクラウド利用許可が下りている
• .gitignore に .codex/ ディレクトリ（セッションキャッシュ）が追加されている
• 機密情報を含むファイルは AGENTS.md で除外対象として明記
• チーム運用なら config.toml の profiles をテンプレ化してリポジトリ管理
• 月次のトークン消費・コストの上限アラートを ~/.codex/config.toml または OpenAI ダッシュボードで設定済み

2-5. Windows ユーザーの WSL2 移行手順

PowerShell ネイティブで Codex CLI を動かすことも可能ですが、fork・exec の挙動差や、シェル制御のサンドボックス精度の問題で、長期運用は WSL2 を推奨します。3 ステップで移行できます。

1. WSL2 を有効化: PowerShell を管理者として起動し、wsl --install を実行（Windows 10 21H2 以降）。Ubuntu 22.04 が既定でインストールされます。
2. WSL 内に Node.js を導入: WSL シェルで curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - 後、sudo apt install -y nodejs で導入。
3. Codex CLI を WSL に再インストール: npm install -g @openai/codex を WSL シェルで実行し、codex を起動。プロジェクトディレクトリは /home/<user>/projects/ に置き、/mnt/c/ 経由でのアクセスは避けます（クロスファイルシステム遅延を回避するため）。

詳細な Windows 環境の注意点は Claude Code インストールガイド も参考にしてください（多くの落とし穴は共通です）。

3. AGENTS.md でプロジェクト指示書を書く

結論: AGENTS.md は Codex がセッション開始時に必ず読むプロジェクト指示書です。Claude Code の CLAUDE.md と同じ役割を果たし、書式は両ツールでほぼ互換です。 AGENTS.md の品質が Codex CLI の出力品質を最も大きく左右します。

3-1. AGENTS.md の役割と書式

AGENTS.md は agents.md という業界共通仕様に基づく Markdown ファイルです。プロジェクトルートに配置すると、Codex CLI（および Cursor / Copilot / Amp / Jules / Gemini CLI / Windsurf / Cline / Aider / Zed など他のエージェント）が起動時に内容を読み、以降のセッションで参照します。

書式に厳密な決まりはありませんが、実務上は次のセクションを含めると効果的です。

• プロジェクト概要: 何を作っているか、技術スタック、デプロイ環境
• コーディング規約: 命名規則、フォーマッタ、テストフレームワーク
• ディレクトリ構造: src/ / tests/ / scripts/ などの役割
• やってほしいこと / やってほしくないこと: 「テストは必ず先に書く」「any 型は使わない」「秘密情報を含むファイルは触らない」など
• コミット規約: メッセージ形式、ブランチ命名、PR テンプレート
• 依存関係の追加ルール: 自由に追加してよいか、レビューを通すか

最初は 100 行程度のシンプルな指示で十分です。運用しながら「Codex がブレやすいポイント」を AGENTS.md に追記していくのが現実的です。

3-2. AGENTS.md vs CLAUDE.md（移行チェックリスト）

両者は仕様レベルでほぼ互換ですが、細部に違いがあります。Claude Code から Codex CLI に移行する（または併用する）場合は次のチェックリストで差分を確認してください。

• 基本構造（Markdown 見出し階層、コードブロック使用法）はそのまま流用可
• Claude Code 固有のメタフィールド（!CLAUDE.md プレフィックス等）は AGENTS.md では不要
• Hooks 設定（Claude Code 側の .claude/hooks/）は Codex の [hooks] セクション or config.toml に移行
• サブエージェント定義は Codex 側で [agents.<name>] セクションに書き直す
• Tool 制限（Claude Code の allowedTools）は Codex 側で sandbox_mode + approval_policy に再マッピング

両方を併用するなら、AGENTS.md を真実の源とし、CLAUDE.md には See AGENTS.md だけを書く（または逆）方法で重複を避けられます。

3-3. /init で AGENTS.md を自動生成する

Codex CLI には /init というスラッシュコマンドがあり、リポジトリをスキャンして AGENTS.md のドラフトを自動生成します。最初の AGENTS.md を作る際は次の流れが効率的です。

1. プロジェクトルートで codex を起動
2. /init を実行（Codex がディレクトリ構造・package.json・README を解析）
3. 生成された AGENTS.md ドラフトを確認し、手動で「やってほしくないこと」「ドメイン固有のルール」を追記
4. git commit でリポジトリに含める

3-4. チーム共有のベストプラクティス

• AGENTS.md は 必ず Git に commit する（個人ごとの差を作らない）
• 個人の好み（モデル選択、approval_policy）は ~/.codex/config.toml に書く
• プロジェクト共通のチームルールは AGENTS.md と <repo>/.codex/config.toml（profiles）に書く
• AGENTS.md は 500 行を超えると Codex が情報を取りこぼしやすくなる傾向があるため、サブモジュール（AGENTS.frontend.md 等）に分割する運用が現実的

4. Approval Policy と Sandbox Mode（セキュリティ設計）

結論: Codex CLI は「Approval Policy（人間の承認）」と「Sandbox Mode（OS の物理隔離）」の二重で安全策を取ります。両者の組み合わせを理解しないと、本番マシンを壊すリスクがあります。

4-1. Approval Policy 3 種

Approval Policy は「Codex が何かする前に人間に確認するか」の方針です。Codex CLI では UI 上の表示名と config.toml の値が別になっており、対応関係は次の通りです（正確な値は Codex CLI Configuration Reference を必ず確認してください）。

UI 表示名	config.toml 値	意味	向くシーン
Read-only	untrusted	書き込み・コマンド実行はすべて都度承認、読み取りのみ自動	不慣れなリポジトリの探索
Auto（既定）	on-request	書き込みやコマンド実行の前に都度承認	個人のローカル開発（推奨）
Full Access	never	一切承認を求めない（完全自動）	CI / 隔離 VM のみ

公式の Codex CLI Features で、それぞれの正確な範囲と推奨条件が説明されています。本番マシンで never（Full Access）は絶対に避けてください。

4-2. Sandbox Mode 3 種

Sandbox Mode は「ファイルシステム / ネットワークへの物理アクセス範囲」を OS レベルで制限します。

モード	書き込み可能範囲	ネットワーク	既定の用途
read-only	なし	なし	探索・コードレビュー
workspace-write	現在のワークディレクトリ内のみ	なし（必要時に許可）	通常開発（推奨）
danger-full-access	マシン全体	あり	完全隔離環境のみ

ほとんどの実務では workspace-write が安全側のデフォルト です。Codex CLI が rm -rf ~/ や curl | bash を試みても、ワークディレクトリ外に副作用が漏れません。

4-3. 使い分けマトリクス

Approval Policy と Sandbox Mode は組み合わせで意味を持ちます。実務でよく使う組み合わせを示します（左列は config.toml 値）。

approval_policy	sandbox_mode	想定シーン
untrusted	read-only	リポジトリ探索・コードレビュー
on-request	workspace-write	個人の日常開発（推奨デフォルト）
never	workspace-write	CI / 隔離コンテナでの自動実行
never	danger-full-access	一時的な実験 VM のみ。本番厳禁

4-4. エンタープライズでの推奨設定

• 個人開発端末: approval_policy = "on-request" + sandbox_mode = "workspace-write"
• CI / GitHub Actions: approval_policy = "never" + sandbox_mode = "workspace-write"（コンテナ内）
• 本番ホスト: Codex CLI を直接インストールしない。必要なら踏み台ホスト経由で実行

機密データを扱うチームは、AGENTS.md の冒頭に「秘密情報を含むファイルは触らない」「.env / secrets/ ディレクトリには書き込まない」と明示し、Codex Cloud にデータを送信する設定（/cloud 等）は明示的にオフにしてください。OPENAI_API_KEY のような機密性の高い環境変数は、MCP サーバー子プロセスに継承されないよう shell_environment_policy で制御することも検討してください。

5. config.toml で挙動を細かく制御

結論: ~/.codex/config.toml（ユーザー共通設定）と <repo>/.codex/config.toml（プロジェクト固有設定）の 2 ファイルで、Codex CLI のほぼすべての挙動をコントロールできます。

5-1. 主要設定項目

代表的な設定キーは次の通りです。詳細は Codex CLI Reference に掲載されています。

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[history]
persistence = "all"

[shell_environment_policy]
inherit = "all"
include_only = ["PATH", "HOME", "LANG"]

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "."]

model でデフォルトモデルを指定し、approval_policy と sandbox_mode で前章の挙動を固定化します。

5-2. プロファイル切替（個人開発 / チーム / CI 用）

[profiles.<name>] セクションを使うと、シーン別の設定セットを切り替えられます。

[profiles.solo]
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.team]
model = "gpt-5.4"
approval_policy = "untrusted"
sandbox_mode = "workspace-write"

[profiles.ci]
model = "gpt-5.3-codex"
approval_policy = "never"
sandbox_mode = "workspace-write"

実行時に codex --profile ci のように指定すれば、CI ではコスト最適化モデル、個人開発では最新モデル、と使い分けできます。

5-3. 共有設定の運用パターン

• ユーザー個人設定（~/.codex/config.toml）: モデルの好み、認証情報、profiles
• プロジェクト共通設定（<repo>/.codex/config.toml）: チーム共通の profiles、MCP サーバー定義、approval_policy のチーム標準
• AGENTS.md: 自然言語での指示、コーディング規約、ディレクトリ役割

3 つを役割ごとに分けて運用すると、個人とチームの設定衝突を避けられます。

6. 主要コマンドとスラッシュコマンド

結論: Codex CLI は対話モード（codex）と非対話モード（codex exec）の 2 系統に分かれます。日常開発は対話モード、CI と自動化は exec モードで使い分けます。

6-1. codex（対話モード）

引数なしの codex でフルスクリーン TUI が起動します。自然言語で指示を出すと、Codex がプランを提案し、Approval Policy に従って承認を求めながら実行します。

codex

プロンプトを初期入力として渡すこともできます。

codex "AGENTS.md を読み、TypeScript の strict mode を有効化する手順を実行して"

6-2. codex exec / codex e（スクリプト用）

非対話・ヘッドレスでの実行モードです。CI、cron、シェルスクリプトに組み込む用途です。

codex exec "テストを実行し、失敗していたら原因を README に追記して"

--json フラグで JSON 形式の結果を取得でき、後続処理に渡せます。

6-3. codex resume（セッション再開）

ローカルに保存されたセッションを再開します。--last で最新セッションに直接戻れます。

codex resume --last

6-4. codex cloud exec（クラウドタスク）

Codex Cloud 上で非同期にタスクを実行します。長時間タスクや並列タスクに向きます。

codex cloud exec "依存関係をすべてアップデートし、テストが通る範囲で PR を作成して"

--attempts N で複数結果を比較し、最良案を選ぶ運用も可能です。

6-5. スラッシュコマンド（/init /model /review /fork /agents …）

セッション内で / から始まるコマンドを使うと、メタ操作を実行できます。代表例は次の通りです。

• /init: AGENTS.md の自動生成
• /model <name>: 使用モデルの切り替え
• /review: 直前の変更を別 Codex エージェントにレビューさせる
• /fork: 現在の会話を分岐させて別案を試す
• /agents: サブエージェントの起動・管理
• /clear: コンテキストのリセット
• /compact: 過去の会話を圧縮してコンテキストを節約
• /help: 全コマンド一覧の表示

実装するスラッシュコマンドは CHANGELOG で随時追加されるため、最新一覧は Codex CLI Reference を参照してください。

7. MCP（Model Context Protocol）で外部ツール連携

結論: MCP は Codex CLI に「ファイルシステム」「GitHub」「Slack」など外部ツールへのアクセスを与える仕組みです。設定は ~/.codex/config.toml で行い、CLI と IDE 拡張で共通利用できます。

Codex MCP 公式ドキュメント によれば、Codex CLI は STDIO ベースと HTTP ベースの MCP サーバーをサポートします。設定キーは [mcp_servers.<server-name>] というテーブル記法を使う点に注意してください（配列テーブル [[mcp_servers]] ではありません）。

7-1. MCP の役割と config.toml 設定

MCP サーバーは「Codex から呼び出せる外部ツール」です。デフォルトの Codex はファイル読み書きと shell 実行しかできませんが、MCP を追加することで GitHub の Issue 検索、Slack への通知、データベースへの問い合わせなどが可能になります。

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

[mcp_servers.github.env]
GITHUB_TOKEN = "ghp_..."

7-2. おすすめ MCP サーバー 5 選

実務で導入効果が高い MCP サーバーを 5 つ挙げます。

1. filesystem — ワークディレクトリ外のディレクトリにも限定的にアクセス
2. GitHub — Issue / PR / 検索の操作
3. Slack — タスク完了通知、エラー通知
4. Linear / Jira — チケット参照・更新
5. Web search（Perplexity / Exa など） — 最新ドキュメントの参照

それぞれの導入方法は各 MCP サーバーの公式リポジトリを参照してください。

7-3. Codex 自身を MCP サーバーとして公開する

Codex CLI は別のエージェント（Claude Code 等）から呼び出される MCP サーバーとしても動作します。codex serve mcp のようなサブコマンド（または相当の設定）で公開でき、Claude Code から Codex のリソースを呼び出す「マルチエージェント連携」が可能です。詳細は最新の MCP 公式 を確認してください。

なお、MCP の基本概念は Claude Code の MCP 連携ガイド でも詳しく解説しています。Claude Code と Codex CLI の MCP は同じプロトコルに準拠しているため、知識はほぼ流用できます。

8. サブエージェントで並列タスク処理

結論: Codex CLI のサブエージェントは「明示的に起動したときだけ」呼び出される並列実行機能です。複雑タスクを役割別に分担できますが、トークン消費が想定の何倍にもなりやすい諸刃の剣です。

8-1. サブエージェントとは（明示起動の哲学）

Codex のサブエージェントは、Claude Code のサブエージェントと似ていますが、設計思想として 「明示的に起動したときだけ動く」 という方針があります。曖昧な指示で自動的にサブエージェントが乱立しないようになっています。

/agents スラッシュコマンドで一覧表示・起動・停止を制御します。

8-2. ロール定義の書き方（[agents] セクション）

config.toml に [agents] セクションを書くと、独自の役割を持つサブエージェントを定義できます。

[agents.test-runner]
description = "テスト実行と失敗ログ解析"
model = "gpt-5.3-codex"
approval_policy = "never"
sandbox_mode = "workspace-write"

[agents.doc-writer]
description = "コードから JSDoc・README を生成"
model = "gpt-5.5"

8-3. 並列実行の落とし穴とトークン管理

サブエージェントを 5 個並列起動すると、トークン消費は単純計算で 5 倍になります。さらに、各サブエージェントが独自にコンテキストを構築するため、消費が加速します。次の運用ルールが安全です。

• 同時実行は最大 3 つまで
• 各サブエージェントのコンテキストは可能な限り狭くする（特定ファイルだけ渡す）
• /agents コマンドで実行中エージェントをこまめに確認
• API キー利用時は OpenAI ダッシュボードで月次予算アラートを必ず設定

9. 業務シナリオで使い切る（5 例）

Codex CLI の実力は、抽象的なコマンド説明よりも具体的な業務シナリオで見たほうがわかりやすいです。代表的な 5 つを示します。

9-1. オンボーディング（既存リポジトリ把握）

新しいリポジトリにジョインしたとき、最初の半日を Codex CLI に手伝わせる流れです。

1. codex を起動し、approval_policy = "untrusted"（UI 名 Read-only）、sandbox_mode = "read-only" に設定
2. 主要ディレクトリの役割と、エントリーポイントのファイルを箇条書きで教えて と指示
3. 続いて 主要なドメイン概念を抽出し、用語集を AGENTS.md に追記して と指示（書き込みは都度承認）
4. 出力結果をレビューし、/fork で別解釈も試す

これでドキュメントが薄いレガシーリポジトリでも、半日で全体像を掴めます。

9-2. TDD で新機能を実装

1. 仕様を AGENTS.md（または会話内）で詳細に伝える
2. 先に失敗するテストを書いて と指示（Red フェーズ）
3. テストが正しく書かれていることを人間が確認
4. テストが通る最小実装を書いて と指示（Green フェーズ）
5. 重複・命名を整理して と指示（Refactor フェーズ）
6. 各ステップで Approval を都度承認

Codex CLI は TDD のサイクルとの相性がよく、特に Green フェーズで「テスト駆動で最小実装に絞る」指示が効きやすい傾向があります。

9-3. 大規模リファクタリング

20 ファイル以上にまたがる名前変更や API シグネチャ変更は、人手では工数が膨らみがちです。

1. 影響範囲を codex exec "src/ 以下で getUserData 関数のすべての呼び出し箇所を列挙して" --json で把握
2. AGENTS.md に「getUserData を fetchUser に統一する」というルールを追記
3. codex exec "変更計画を README.refactor.md に書き、確認後に実行して" で計画フェーズと実行フェーズを分離
4. テストがすべて通ることを codex exec "テストを実行し、失敗があれば原因を出力" --json で確認

途中で Codex がブレるリスクがあるため、必ず git diff を人間がレビューしてからコミットします。

9-4. CI/CD パイプライン統合

GitHub Actions で Codex CLI を呼ぶワークフローを構築すると、PR 作成・コードレビュー・自動テスト修正を自動化できます。例として「PR が来たら Codex CLI が変更要約コメントを投稿する」フローを作る場合、codex exec --json で要約を生成し、結果を gh pr comment で投稿するスクリプトを Actions に登録します。

CI で実行する際の注意点は次の通りです。

• approval_policy = "never" を config.toml で明示
• sandbox_mode はコンテナ内なら workspace-write で十分
• OPENAI_API_KEY は GitHub Actions Secrets で渡す
• 1 ジョブあたりのトークン消費上限を OpenAI ダッシュボードの予算アラートで設定する（CLI 側のフラグ名は最新リファレンスを確認）

9-5. コードレビュー・PR 自動化

PR 作成時に Codex の /review を別エージェントとして呼び出すと、独立した「別の Codex」が変更内容をレビューしてコメントを返します。同じセッションの Codex が自分の出力を自己評価するよりも、別エージェントによる客観的なレビューのほうがバグ検出率が高い傾向があります。

/review の出力を Markdown 化して GitHub の PR コメントに投稿するフックを CI に組み込めば、人間のレビュー前に「最初の網」を Codex に張らせる運用が可能です。

10. Claude Code との使い分け・併用

結論: 2026 年現在、senior な開発チームは「Claude Code を設計と精密編集に、Codex CLI を並列実行と CI に」割り当てる併用パターンが定着しつつあります。 単独で完結させる必要はありません。

10-1. 設計思想の違い

観点	Claude Code	Codex CLI
ライセンス	Anthropic 製の商用ライセンス（一部 SDK は公開）	オープンソース（Rust 製）
安全策	アプリ層 hooks による許可制	OS のサンドボックス機構（macOS の Seatbelt、Linux の Landlock + seccomp 等）による隔離
強み	多ファイル refactor、設計推論、長文コンテキスト	並列実行、CI 統合、低レイテンシ
プラットフォーム依存	Anthropic エコシステム	OpenAI エコシステム

詳細な比較は Claude Code vs OpenAI Codex CLI 比較 で網羅しています。本記事では「実務での使い分け」に絞ります。

10-2. タスク特性別の使い分けマトリクス

タスクの特性ごとに、どちらが向くかを整理しました。

タスク	推奨ツール	理由
12 ファイル以上にまたがる構造変更	Claude Code	長文コンテキストと依存把握
単発スクリプト・cron バッチ	Codex CLI	Rust 製の起動速度・サンドボックス
設計議論・アーキ判断	Claude Code	推論力と長文要約
大量並列タスク（10 PR 並走）	Codex CLI	サブエージェント設計と Cloud 実行
TDD で 1 機能を仕上げる	どちらでも可	スタイルの好みで選ぶ
CI 内での自動テスト修正	Codex CLI	exec モードと CI 連携の成熟度
既存リポジトリのオンボーディング探索	Claude Code	リポジトリ全体把握の精度
GitHub PR 自動レビュー	Codex CLI	/review 別エージェントの分離

10-3. 両方使う「2026 年現在の senior 開発チームのスタンダード」

両方使う場合の運用パターンは次が現実的です。

• 設計と精密編集を Claude Code、並列実行と CI を Codex CLI が担当
• 同じリポジトリで AGENTS.md（Codex 用）と CLAUDE.md（Claude Code 用）を共存させる
• 一方を真実の源とし、他方は See AGENTS.md のみ書く（重複防止）
• サブスクは「Anthropic Max + ChatGPT Pro」のような併用が senior 開発者の標準的支出

10-4. AGENTS.md と CLAUDE.md の共存

両ファイルが共存する場合、内容のずれが混乱を生みます。次のいずれかを選びます。

• パターン A: AGENTS.md を正、CLAUDE.md は See AGENTS.md のみ
• パターン B: CLAUDE.md を正、AGENTS.md は See CLAUDE.md のみ
• パターン C: 両方に同じ内容を書く（同期を Git pre-commit hook で強制）

長期運用ではパターン A（AGENTS.md を正）が業界標準になりつつあります。AGENTS.md は agents.md という共通仕様で 60,000 以上の OSS プロジェクトが採用しており、将来的にツールを切り替えても資産が残るためです。

なお、Claude Code の詳細な使い方は Claude Code 完全ガイド を参照してください。

11. 料金プランとコスト試算

結論: ChatGPT サブスクリプション（Plus $20 〜 Enterprise）で Codex を使うのが既定の入り口で、ヘビーユース時に API キー従量課金を併用するのが現実的です。

最新の料金は OpenAI Codex 公式ページ と Help Center を必ず確認してください。本節は執筆時点の概要です。

11-1. ChatGPT サブスクで使う

Codex は ChatGPT Plus / Pro / Business / Edu / Enterprise すべてに含まれます。2026 年 4 月以降、Pro プランは Pro $100 と上位の Pro $200 の 2 段階構成になっており、ヘビーユーザー向けに並列度・コンテキスト上限が拡張されています。プランごとの利用上限（5 時間ごとのタスク数、長時間タスクの並列度など）は OpenAI 側で随時調整されています。サブスク料金内に Codex 利用枠が含まれるため、「ChatGPT を既に契約しているなら追加コストはゼロ」が出発点です。

11-2. API キーで使う

サブスク枠を超える使い方（CI で大量実行、サブエージェントを多数並列、24 時間連続稼働）は API キーの従量課金が向きます。GPT-5.5・GPT-5.4・GPT-5.3-Codex それぞれにトークン単価があり、入力トークンと出力トークンで料金が異なります。詳細は OpenAI 公式の料金ページで最新情報を確認してください。Anthropic 側の従量課金の感覚をつかみたい場合は Anthropic API 入門 も参考になります。

11-3. 月額コスト試算テーブル（4 パターン）

実務でよくある 4 つの使い方の月額目安です。あくまで概算で、実際の数値はトークン消費とプロンプト設計次第で大きく変わります。

パターン	想定使用	月額目安	コメント
個人開発（軽量）	ChatGPT Plus のみ	$20	1 日 1〜2 セッション程度なら十分
小規模チーム	ChatGPT Pro $100 × 3 名	$300	チーム内で並列実行を許容するレベル
ヘビーユーザー	ChatGPT Pro $200 × 数名 + API 補助	$600 + 従量	長時間タスクと並列度を最大化したい場合
API ヘビーユース	API 従量課金中心	$500 〜 $2,000	CI で毎日数百タスク、長時間タスク中心

価格はすべて公式の USD 表記です（日本円換算は為替変動の影響を受けるため本記事では USD のままで統一しています）。

「サブスクとAPIを併用する」のも一般的です。日常はサブスクで賄い、CI とサブエージェント並列実行だけ API キーで動かす、という二重化です。

11-4. コスト最適化のコツ

• 軽量タスクは gpt-5.3-codex を指定して単価を下げる
• /compact をこまめに使ってコンテキストを圧縮
• サブエージェントの同時起動は 3 つまで
• AGENTS.md を整理して「Codex が探索に消費するトークン」を減らす
• 大規模リファクタリングは Codex Cloud で実行し、ローカル端末のコストを抑える

Claude Code 側の料金プランは Claude Code 料金プラン を参照してください。両プラットフォームの併用コストを試算する際の参考になります。

12. エラー逆引きインデックス（10 項目）

Codex CLI で頻発するエラーを症状ベースで整理しました。エラーメッセージで本記事内検索すると、該当箇所にたどり着けます。

12-1. 認証エラー: Your access token could not be refreshed

• 原因: OAuth トークンの期限切れ、または ChatGPT 側のセッション破棄
• 対処: codex logout 後に codex login で再認証。ChatGPT 側で 2 要素認証を最近変更していないか確認

12-2. Sandbox エラー: sandbox: permission denied / EACCES

• 原因: sandbox_mode = "read-only" のままで書き込みを試みた、もしくはワークディレクトリ外への書き込み
• 対処: ~/.codex/config.toml の sandbox_mode を workspace-write に変更。ワークディレクトリ外を触る必要がある場合は AGENTS.md にその旨を明記し、Approval Policy を on-request にする

12-3. モデル選択エラー: model not available / you may not have access to it

• 原因: 指定したモデル（例: gpt-5.5）が現在のプランで利用不可
• 対処: /model スラッシュコマンドでモデルを切り替える（利用可能モデル一覧の確認方法は最新の Codex CLI Reference を参照）。プラン制限の場合は ChatGPT Pro 以上にアップグレード

12-4. MCP 接続エラー: MCP server failed to start

• 原因: config.toml で指定した command が存在しない、または環境変数が不足
• 対処: which <command> でフルパスを確認し、config.toml の command をフルパスで書く。[mcp_servers.env] で必要な環境変数を明示

12-5. ネットワーク制限エラー: Network access blocked / connection refused

• 原因: sandbox_mode がネットワーク無効、または企業プロキシで OpenAI API がブロック
• 対処: 必要な MCP サーバーのみネットワーク許可するよう config.toml で個別設定。企業環境では HTTPS_PROXY 環境変数を設定し、プロキシ経由で接続

12-6. サブエージェントトークン超過: Subagent budget exceeded

• 原因: サブエージェントの同時起動数が多すぎる、コンテキストが肥大化
• 対処: /agents で実行中エージェントを停止。同時実行数を 3 までに減らす。各サブエージェントへ渡すコンテキストを最小化

12-7. AGENTS.md が認識されない

• 原因: AGENTS.md がプロジェクトルートにない、ファイル名のスペル違い、サイズが大きすぎる
• 対処: codex 起動時のログで「AGENTS.md detected」が出ているか確認。ファイル名は厳密に AGENTS.md（大文字）。500 行を超える場合はサブモジュールに分割

12-8. PowerShell 動作不安定: Codex command exited unexpectedly

• 原因: Windows ネイティブの PowerShell でサンドボックスが想定通りに動作しない
• 対処: 2-5 節の手順で WSL2 に移行。一時的な回避策として Codex Cloud に重い処理を移譲

12-9. Codex Cloud タスク失敗: Cloud task timed out / Cloud sandbox unavailable

• 原因: 長時間タスクで上限到達、または Cloud 側の一時障害（具体的なタイムアウト上限は最新の OpenAI ヘルプセンターを参照）
• 対処: タスクを小さく分割。Cloud 障害は OpenAI ステータスページ で確認

12-10. その他のよくある不具合

• セッションが消える: ~/.codex/sessions/ が破損していないか確認、codex resume --last で復旧
• 出力が文字化け: ターミナルのロケールを LANG=ja_JP.UTF-8 に設定
• npm install -g @openai/codex が失敗: Node.js のバージョンが古い、グローバルインストール権限の問題（macOS なら nodenv / Volta を推奨）

13. Codex CLI 失敗パターン集（5 つの落とし穴）

実務で「やってしまいがちな失敗」を 5 つ挙げます。それぞれ「症状 → 原因 → 対処」の 3 段構造で整理しました。

13-1. Full Access モード乱用で本番副作用

• 症状: pip install や npm install -g がローカル端末全体に影響
• 原因: 試しに sandbox_mode = "danger-full-access" のまま長期間使っていた
• 対処: 既定を workspace-write に戻し、Full Access は隔離 VM のみで使う運用ルールに変更

13-2. AGENTS.md なしで指示がブレる

• 症状: 同じ指示でもセッションごとに異なる結果。テストの書き方が日替わり
• 原因: AGENTS.md がない、または存在しても 50 行未満で情報不足
• 対処: 最低限「ディレクトリ役割」「コーディング規約」「やってほしくないこと」の 3 セクションは記述。100 〜 300 行を目安に整える

13-3. Codex Cloud に秘密情報送信

• 症状: .env ファイルや顧客データが Cloud に送信されている疑い
• 原因: AGENTS.md に「Cloud に送らないディレクトリ」が書かれていない
• 対処: AGENTS.md 冒頭で secrets/ や .env* を明示除外。Codex Cloud を使う前に必ず git status で秘密情報がコミット対象外であることを確認

13-4. サブエージェント連発でトークン枯渇

• 症状: 月額予算が想定の 3 倍。OpenAI ダッシュボードで予算超過アラート
• 原因: /agents で 5 個以上を同時起動、各エージェントが独自にコンテキストを構築
• 対処: 同時実行を 3 つに制限。max_agents 等のキーがあれば config.toml で固定。月次予算アラートを OpenAI ダッシュボードで必ず設定

13-5. PowerShell ネイティブ運用の落とし穴

• 症状: codex のサンドボックスが想定通りに効かない、fork 後のセッションが復元できない
• 原因: Windows ネイティブ PowerShell でサンドボックス機構が部分的にしかサポートされていない
• 対処: 2-5 節の手順で WSL2 に移行。短期的には approval_policy = "on-request" にしてエラー検出可能性を高める

14. エンタープライズ導入ロードマップ（4 ステップ）

組織として Codex CLI を採用する場合、いきなり全社展開は失敗しやすいです。次の 4 ステップで段階的に進めるのが現実的です。

14-1. PoC（2 週間）

• 対象: 開発者 3〜5 名の特定チーム
• 設定: sandbox_mode = "workspace-write"、approval_policy = "on-request"
• 目的: AGENTS.md の初版を作る、Codex がどのタスクで効率化されるかを定量的に測る
• 出口条件: 「1 タスク当たりの所要時間がどれくらい短縮されたか」を数値で報告

14-2. チーム導入（1 ヶ月）

• 対象: PoC 参加者を含む 1 チーム全員（10 〜 15 名）
• 設定: チーム共通 <repo>/.codex/config.toml、AGENTS.md を Git で管理
• 目的: チーム標準のプロンプト・スラッシュコマンドを整備
• 出口条件: チーム内の Codex 利用率が 70% 以上、AGENTS.md の更新頻度が安定

14-3. 部門展開（3 ヶ月）

• 対象: 開発部門全体（複数チーム）
• 設定: 部門共通の AGENTS.md テンプレート、MCP サーバー（GitHub / Slack / Linear）を共通基盤で運用
• 目的: 部門全体の生産性向上、セキュリティ統制の確立
• 出口条件: セキュリティ事故ゼロ、コスト予算内、Codex 利用率 70% 以上

14-4. 全社 CI 統合（6 ヶ月）

• 対象: 全社の CI/CD パイプライン
• 設定: approval_policy = "never" + sandbox_mode = "workspace-write" の CI プロファイル
• 目的: 自動テスト修正・PR 要約・コードレビューの自動化
• 出口条件: PR レビュー時間の短縮、テスト修正の自動化率向上

14-5. 経営層への説明資料テンプレ

経営層に提案する際は次のフレームで整理します。

• 課題: 開発生産性のボトルネック（仕様→実装の時間、リファクタの工数）
• 解決: Codex CLI 導入（PoC で実証済み）
• 効果: タスク所要時間 X%短縮、レビュー時間 Y%短縮
• リスク: トークンコスト・秘密情報流出・依存度の集中
• 対策: 予算アラート、AGENTS.md による情報統制、Claude Code との併用で依存リスク分散
• 投資回収: 月額 $X のサブスク・API コストに対し、節約された人時の貨幣換算で N ヶ月で回収

組織導入の議論を進めたい場合は、koromo の AI 戦略・CAIO 代行サービス もご相談ください。Claude Code / Codex CLI どちらが自社に向くか、PoC 設計から組織展開まで支援可能です。

15. よくある質問（FAQ）

まとめ

OpenAI Codex CLI は、ターミナル型 AI コーディングエージェントとして Claude Code と並ぶもう一つの標準ツールです。本記事で押さえてほしいポイントは次の 5 点です。

1. Codex CLI は OS のサンドボックス機構による物理隔離が特徴: Approval Policy と Sandbox Mode の組み合わせが安全策の核
2. AGENTS.md と config.toml が出力品質を最も大きく左右する: 設定なしで使うと真価が出ない
3. Claude Code との併用が 2026 年のスタンダード: 設計・精密編集は Claude Code、並列実行・CI は Codex CLI
4. 料金はサブスク＋API の二重化が現実的: 日常はサブスク、CI とヘビー並列は API キー
5. エンタープライズ導入は PoC → チーム → 部門 → 全社 CI の 4 ステップで段階展開

導入で迷ったら、まずは個人開発で npm install -g @openai/codex から始め、AGENTS.md の初版を Git に置くところまで進めてください。チーム導入のフェーズに入ったら、Claude Code vs OpenAI Codex CLI 比較、AI コーディングツール比較表 2026、Claude Code 完全ガイド も合わせて読むと、自社に合うプラットフォーム選択が明確になります。

組織導入の戦略設計や、Claude Code と Codex CLI のどちらが向くかの判断にお悩みの場合は、koromo の AI 戦略・CAIO 代行サービス にご相談ください。PoC 設計から全社展開まで、生成 AI を「導入したのに使われない」状態にしない伴走支援を提供しています。