OpenAI Codex 活用完全ガイド｜使い方・ユースケース・運用ワークフローからClaude Code併用・組織導入まで【2026年版】

OpenAI Codex は、ターミナルやクラウド、IDE から自然言語でコードを書かせる AI コーディングエージェント です。Rust 製の Codex CLI を中心に、Codex Cloud・IDE 拡張・Codex アプリといった複数のサーフェスを持ち、Claude Code と並ぶ「AI コーディングの主役」として 2026 年現在広く採用されています。

ただし「Codex をどう活用するか」は、インストールや使い方の手順だけでは見えてきません。単発のコード生成にとどめるのか、7 時間の自走タスクに任せるのか、Skills や Automations で定型ワークフローを自動化するのか、CI に組み込んで組織全体の生産性を底上げするのか――活用の段階によって、得られる成果も必要な設定もまったく変わります。

本記事は、Codex の活用を 「4 つの活用レベル」「ユースケース 10 選」「運用ワークフロー自動化」 の 3 軸で体系化する Codex 活用のピラーガイド です。使い方・料金・Claude Code との使い分けといった基礎も網羅しつつ、「次に何を読めば活用を一段深められるか」まで設計しています。各テーマの詳細は専門スポーク記事へ接続しているので、自分の段階に合った入口から読み進めてください。

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

1. OpenAI Codex とは（CLI / Cloud / アプリ / IDE 拡張の全体像）

結論: Codex は OpenAI が開発した AI コーディングエージェントの総称で、ローカルの Codex CLI を中心に、Codex Cloud・IDE 拡張・Codex アプリの 4 サーフェスで同じ設定（AGENTS.md / config.toml）を共有します。本記事は活用の中核となる CLI を軸に、Cloud／アプリ／IDE への展開も扱います。

公式ドキュメントによれば、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 / IDE 拡張 / Codex アプリの関係

「Codex」というブランドの下に複数の製品があるため、最初に整理しておきましょう。どのサーフェスから使っても活用の考え方（活用レベルとユースケース）は共通です。

4 つは同じ AGENTS.md と config.toml を共有します。本記事は活用の中核となる CLI を中心に扱いますが、Cloud／IDE／アプリへの展開も随所で触れます。CLI と Cloud の使い分けは Codex Cloud と CLI の違い・使い分けガイド で詳しく解説しています。

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. Codex 活用の全体像 — 4 つの活用レベルと使い分けマップ

結論: Codex の活用は「単発タスク → 自走 → ワークフロー自動化 → 組織 CI 統合」の 4 レベルで段階化できます。多くの解説は機能を羅列するだけですが、活用は "どこまで任せるか" の階段で考えると、次に何を学ぶべきかが明確になります。

「Codex 活用方法」を調べると、コマンドや機能の説明は山ほど見つかります。しかし実務でつまずくのは「結局、自分はどのレベルまで Codex に任せるべきか」という地図がないことです。そこで本記事では、活用を 4 つのレベルに整理します。

2-1. 活用レベル別マップ（L1 → L4）

この地図の使い方はシンプルです。いまの自分がどのレベルにいるかを特定し、一つ上のレベルの「深掘り先」記事へ進む ――それだけで活用は着実に一段深まります。L1 で止まっている人が大半なので、L2 以降に進むだけで投資対効果が跳ね上がります。

2-2. レベル別に「何が変わるか」

• L1 → L2: 指示の粒度が「タスク」から「ゴール」に変わります。AGENTS.md と PLANS.md を整え、Approval Policy を緩めて自走させるのが鍵です（§6・§7）。
• L2 → L3: 「毎回手で出す指示」を Skills（定型プロンプトの型化）や Automations（定期・イベント駆動の自動実行）に移します。ここから Claude Code との分業（設計は Claude Code、並列実行は Codex）も視野に入ります。
• L3 → L4: 自動化を個人の端末から CI/CD に引き上げます。approval_policy = "never" + コンテナ内 workspace-write を CI プロファイルとして固定し、PR レビューやテスト修正を組織の標準フローに組み込みます。

2-3. 読み手別の入口（3 層 + 活用レベル）

自分の段階に合った入口から読み進めれば、全 16 章を頭から読まなくても活用に必要な部分にたどり着けます。

3. Codex 活用ユースケース 10 選（開発 6 ＋ 業務 4）

結論: Codex の活用先は「開発タスク」だけではありません。開発 6 種に加え、仕様→PoC 高速化・ドキュメント生成・データ整形・非エンジニアの社内ツール作成といった業務活用 4 種まで広げると、チーム全体の生産性に効きます。

「Codex 活用事例」「Codex ユースケース」で求められているのは、抽象的な機能説明ではなく "何に使えて、どれくらい効くか" の具体像です。ここでは開発 6 ＋業務 4 の計 10 ユースケースを、想定効果とともに一覧化します。

3-1. ユースケース一覧（◎ 特に効く / ○ 効く）

開発系 6 種の具体的な手順は本節 3-5 で詳しく解説します。ここでは活用の "幅" を俯瞰し、自分の業務でどこに当てはめられるかを掴んでください。

3-2. 開発ユースケース（1〜6）のポイント

L1 のオンボーディング・TDD・バグ修正は、Approval Policy を on-request（UI 名 Auto）にした日常運用で十分こなせます。L2 の大規模リファクタは計画フェーズと実行フェーズを分離し（3-5）、L4 の CI 統合は Codex × GitHub Actions 自動化ガイド で実装手順を解説しています。

3-3. 業務・DX 活用ユースケース（7〜10）のポイント

開発以外の活用こそ、Codex の裾野を広げる鍵です。

• 仕様 → PoC 高速化: 企画メモや要件を渡し、「動く最小プロトタイプ」を生成させる。ビジネス側が手触りで仕様を検証でき、手戻りを減らせます。
• ドキュメント生成: コードベースから README・API リファレンス・用語集を生成。L1 で最も費用対効果が高い用途の一つです。
• データ整形・分析: CSV やログの整形、集計・可視化スクリプトの自動生成。非エンジニアでも Codex アプリ経由で依頼できます。
• 非エンジニアの社内ツール: 定型業務を自動化する小規模スクリプトを、対話だけで内製。情報システム部門の負荷を下げます。

3-4. 一次ソース: OpenAI 社内の Codex 活用パターン

OpenAI 自身が公開している「Codex の活用方法」資料では、社内での代表的な活用として リファクタリング / テスト生成 / バグ修正 / スキャフォールド（雛形生成）/ ドキュメント生成 の 5 パターンが挙げられています（OpenAI 公式 Codex ページ 参照）。本記事のユースケース 10 選は、この一次情報を起点に業務活用まで拡張したものです。"開発元自身がどう使っているか" は、活用方針を決めるうえで最も信頼できる出発点になります。

3-5. 開発シナリオ実践（手順詳説）

ユースケースの "幅" を押さえたら、代表的な開発シナリオを手順レベルで見ていきましょう。抽象的なコマンド説明よりも、具体的な業務フローで見たほうが活用イメージが掴めます。

オンボーディング（既存リポジトリ把握 / L1）

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

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

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

TDD で新機能を実装（L1）

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

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

大規模リファクタリング（L2 自走）

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 を人間がレビューしてからコミットします。長時間の自走として回す場合は §4-3 の 3 ステップ（AGENTS.md → PLANS.md → 投入）が安定します。

CI/CD パイプライン統合（L4）

GitHub Actions で Codex を呼ぶワークフローを構築すると、PR 作成・コードレビュー・自動テスト修正を自動化できます。例として「PR が来たら Codex が変更要約コメントを投稿する」フローを作る場合、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 ダッシュボードの予算アラートで設定する

実装の全手順は Codex × GitHub Actions 自動化ガイド で解説しています。

コードレビュー・PR 自動化（L3）

PR 作成時に Codex の /review を別エージェントとして呼び出すと、独立した「別の Codex」が変更内容をレビューしてコメントを返します。同じセッションの Codex が自分の出力を自己評価するよりも、別エージェントによる客観的なレビューのほうがバグ検出率が高い傾向があります。/review の出力を Markdown 化して GitHub の PR コメントに投稿するフックを CI に組み込めば、人間のレビュー前に「最初の網」を Codex に張らせる運用が可能です。

4. Codex 運用ワークフロー自動化（Skills / Automations / 自走 / CI）

結論: 活用レベル L3〜L4 の核が「ワークフロー自動化」です。毎回手で出していた指示を Skills で型化し、Automations で定期・イベント駆動にし、7 時間自走や CI 統合で人の介在を減らします。単発の使い方から一段引き上げる、活用の本丸です。

「Codex workflows」「Codex 自動化」「Codex Skills / Automations」で検索する層が求めているのは、定型作業を Codex に恒久的に肩代わりさせる仕組み です。ここでは自動化を 4 つの段で接続します。

4-1. Skills — 定型プロンプトを型化する

毎回似た指示（「テストを実行して失敗を README に追記」「依存を更新して PR を作成」など）を出しているなら、それは Skill 化の候補です。Skills は定型プロンプト＋手順をひとまとめにし、ワンコマンドで呼び出せるようにする仕組みです。属人的な「うまいプロンプト」をチーム資産に変えられます。

4-2. Automations — 定期・イベント駆動で自動実行

Automations は、スケジュール（毎朝・毎週）や GitHub イベント（PR 作成時など）をトリガーに Codex タスクを自動起動する仕組みです。「毎朝、前日の依存更新をチェックして PR を出す」「PR が来たら要約コメントを投稿する」といった反復作業を、人が起動しなくても回せます。

4-3. 7 時間自走の 3 ステップ（AGENTS.md → PLANS.md → 投入）

長時間タスクを Codex に自走させる場合、いきなり丸投げするとブレます。次の 3 ステップが安定します。

1. AGENTS.md を整える: プロジェクトの前提・規約・禁止事項を明文化（§6）。自走の品質はここで決まります。
2. PLANS.md で計画を固定: ゴールを与えて Codex に計画を書かせ、PLANS.md として保存。人間が計画段階でレビューします。
3. 計画を投入して自走: 承認済みの計画に沿って実行させ、Approval Policy を緩めて長時間タスクを回します。途中の git diff は必ず人間が確認します。

検証データでは、AGENTS.md を整備することで実行時間の短縮・トークン削減につながったという報告もあり、自走の前提整備は投資対効果が高い工程です。

4-4. CI 統合（L4）への接続

Skills と Automations で個人レベルの自動化が固まったら、それを CI/CD に引き上げます。approval_policy = "never" + コンテナ内 sandbox_mode = "workspace-write" を CI プロファイルとして固定し、codex exec --json の出力を gh pr comment などに連携します。GitHub Actions での具体的な実装は Codex × GitHub Actions 自動化ガイド で、Claude Code と役割分担しながら自動化する設計は Claude Code × Codex 併用ワークフロー で解説しています。

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

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

5-1. システム要件

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

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

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

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

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

5-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 など対話できない環境」で使います。

5-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 ダッシュボードで設定済み

5-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 インストールガイド も参考にしてください（多くの落とし穴は共通です）。

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

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

6-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 に追記していくのが現実的です。

6-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 だけを書く（または逆）方法で重複を避けられます。

6-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 でリポジトリに含める

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

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

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

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

7-1. Approval Policy 3 種

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

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

7-2. Sandbox Mode 3 種

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

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

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

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

7-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 で制御することも検討してください。

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

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

8-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 で前章の挙動を固定化します。

8-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 ではコスト最適化モデル、個人開発では最新モデル、と使い分けできます。

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

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

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

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

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

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

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

codex

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

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

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

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

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

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

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

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

codex resume --last

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

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

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

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

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

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

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

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

10. 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]] ではありません）。

10-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_..."

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

結論: 2026 年現在、senior な開発チームは「Claude Code を設計と精密編集に、Codex CLI を並列実行と CI に」割り当てる併用パターンが定着しつつあります。 単独で完結させる必要はありません。チームでの分業手順を体系的に知りたい場合は Claude Code × Codex 併用ワークフロー完全ガイド（20タスク振り分け・AGENTS.md ↔ CLAUDE.md 同時運用・CI YAML）を参照してください。

12-1. 設計思想の違い

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

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

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

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

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

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

役割分担を前提にした具体的な併用ワークフロー（どのタスクをどちらに振り、成果物をどう受け渡すか）は Claude Code × Codex 併用ワークフロー で手順化しています。活用レベル L3 のワークフロー自動化を二刀流で進める際の設計図として参照してください。

12-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 完全ガイド を参照してください。

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

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

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

プラン別の詳細な比較（無料枠・従量課金・損益分岐点）は Codex 料金プラン徹底比較 で深掘りしています。本節は活用の判断に必要な範囲に絞ります。

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

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

「Codex は無料で使えるか／無料はいつまでか」という質問もよく聞かれます。新規ユーザー向けに一定期間・一定額の無料クレジットが付与されるキャンペーンが提供されることがありますが、付与額・対象プラン・期限は時期によって変わるため、最新の条件は OpenAI Codex 公式ページ で必ず確認してください。恒常的に無料で使い続けられる枠ではなく、本格活用にはサブスクまたは API 課金が前提になります。

13-2. API キーで使う

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

15. Codex 活用の失敗パターン集（5 つの落とし穴）

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

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

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

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

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

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

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

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

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

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

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

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

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

16-1. PoC（2 週間）

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

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

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

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

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

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

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

この段階（活用レベル L4）の具体的なワークフロー実装は Codex × GitHub Actions 自動化ガイド を参照してください。組織標準として CI に常駐させる設定とスクリプト例を解説しています。

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

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

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

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

よくある質問

まとめ

OpenAI Codex は、Claude Code と並ぶ AI コーディングの標準ツールです。「使い方」を覚えるだけでなく、活用をどこまで深めるかで成果が変わります。本記事で押さえてほしいポイントは次の 5 点です。

1. 活用は 4 つのレベルで段階化する: L1 単発 → L2 自走 → L3 ワークフロー自動化 → L4 組織 CI 統合。いまの自分の一つ上を狙うと投資対効果が伸びる
2. ユースケースは開発 6 ＋業務 4 に広がる: オンボーディング・TDD・大規模リファクタだけでなく、PoC 高速化・ドキュメント生成・非エンジニアの社内ツールまで活用先がある
3. AGENTS.md と config.toml が出力品質を最も大きく左右する: 設定なしで使うと真価が出ない。Skills / Automations での自動化が活用の本丸
4. Claude Code との併用が 2026 年のスタンダード: 設計・精密編集は Claude Code、並列実行・CI は Codex
5. エンタープライズ導入は PoC → チーム → 部門 → 全社 CI の 4 ステップで段階展開

まずは活用レベル L1 として npm install -g @openai/codex から始め、AGENTS.md の初版を Git に置きましょう。次の一段を深めたくなったら、Codex Cloud と CLI の使い分け（L2 自走）、Codex × GitHub Actions 自動化（L4 統合）、Claude Code × Codex 併用ワークフロー（L3 二刀流）、Codex 料金プラン比較、Claude Code vs Codex 比較 を、自分の活用レベルに合わせて読み進めてください。

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