Codex Cloud vs Codex CLI 完全比較 2026｜10軸マトリクス・codex cloud exec・コスト実測・移行ガイドまで網羅

OpenAI Codex は 2025 年に Codex CLI が公開されて以降、Codex Cloud・Codex IDE Extension が相次いで整備され、2026 年 5 月時点では 「ターミナル（CLI）」「ブラウザ/スマホ（Cloud）」「エディタ（IDE Extension）」の 3 つの入口から同じエージェント基盤を呼び出せる構成になりました。最新の Codex CLI は Cloud にタスクを委譲・取得する codex cloud exec 系コマンドを備えており、CLI と Cloud は「対立する選択肢」ではなく「役割分担する道具」として設計されています。

しかし日本語 SERP には、Codex 全体ガイドの一部として Cloud に触れる記事は多いものの、「Cloud と CLI をどう使い分けるか」「codex cloud exec の挙動」「コスト差は実際どうなるか」を専用に解説した記事はほぼ存在しません。本記事では公式ドキュメント（developers.openai.com/codex/）を一次ソースとして、Codex の 3 形態を 10 軸で中立比較し、codex cloud exec 完全リファレンス・コスト実測比較・AGENTS.md / config.toml の互換性・移行ガイド・失敗パターン 5 選・併用パターンまで体系化します。

免責事項: 本記事はすべて 2026 年 5 月時点の公開仕様に基づきます。Codex のモデル名・料金体系・コマンド仕様は変動が激しい領域のため、最終確認は必ず Codex 公式ドキュメント および Codex 公式料金ページ で行ってください。本記事のコマンド例・オプション仕様は codex --help / codex cloud --help で最新版と突き合わせることを推奨します。

結論 — 60 秒で読む Codex Cloud vs CLI 使い分け

迷ったら以下のいずれかを基準にしてください。

結論を一行で言えば: CLI は「手元の対話・自動化」、Cloud は「並列・長時間・モバイル」、IDE Extension は「エディタ内の橋渡し」です。3 形態を排他選択せず役割分担で組み合わせるのが 2026 年現在の現実解です。

技術仕様キーポイント早見表

• Codex Cloud はクラウド分離環境で複数タスクをバックグラウンド並列実行できる。GitHub 連携と PR 作成が標準、認証は ChatGPT サインイン必須。
• Codex CLI は Rust 製ローカルエージェント。codex で TUI、codex exec で非対話実行、codex cloud exec で Cloud にタスク委譲が可能。
• Codex IDE Extension は VS Code / Cursor / Windsurf / JetBrains に対応。Cloud へのタスク委譲と diff 適用が IDE 内で完結。
• 料金は ChatGPT Plus（$20）から利用可能。Cloud / CLI / IDE はすべて同じプランの利用枠を共有する。
• AGENTS.md は 3 形態で共通読み込みされるが、config.toml の Sandbox / Approval / MCP 設定は CLI / IDE 固有で Cloud には反映されない。
• Cloud のキャッシュはコンテナ単位で最大 12 時間、setup script 変更時に自動無効化される。
• Internet Access はエージェントフェーズではデフォルト OFF。許可ドメインリストと HTTP メソッド制限を組み合わせて細粒度で制御する。

Codex の 3 形態を整理（Cloud / CLI / IDE Extension）

Codex は単一のエージェント基盤を持ち、入口の違いで「実行環境」「対話モデル」「セキュリティ境界」が変わります。それぞれの位置づけを公式仕様に沿って整理します。

Codex Cloud とは

Codex Cloud は、OpenAI のコーディングエージェントをクラウドの分離環境で背景実行するサービスです（出典: Codex Cloud 公式ドキュメント, 2026 年 5 月時点）。chatgpt.com/codex/ の Web UI、ChatGPT モバイルアプリ、Codex CLI の codex cloud exec、Codex IDE Extension の「Delegate to Cloud」など複数の入口から起動できます。

主な特徴は次のとおりです。

• 並列タスク: 1 リポジトリで複数タスクを同時にバックグラウンド実行
• GitHub 統合: リポジトリ接続後、PR 作成・コメントへの返信が標準機能
• Environments: タスクごとの実行環境（依存関係・コンテナイメージ・環境変数）をテンプレート化
• Internet Access 制御: エージェントフェーズはデフォルト OFF、許可ドメインと HTTP メソッドを細かく制限可能
• 対応プラン: ChatGPT Plus / Pro / Business / Edu / Enterprise。Free プランでは利用不可
• 認証: ChatGPT サインイン必須（API キーでは Cloud に到達できない）

「クラウドにジョブを投げて、後で結果を回収する」発注型のワークフローに最適化されています。

Codex CLI とは

Codex CLI は OpenAI が公開する Rust 製のローカルエージェントです。npm i -g @openai/codex か Homebrew でインストールでき、初回起動時に ChatGPT アカウントまたは API キーで認証します。

主要機能は次のとおりです。

• 対話モード (codex): TUI を起動して、リポジトリ内で会話しながらファイル編集・コマンド実行
• 非対話モード (codex exec "<prompt>"): スクリプト・CI から呼び出す自動実行モード
• Cloud 連携コマンド (codex cloud exec / codex cloud list / codex cloud status / codex cloud diff / codex cloud apply): CLI から Cloud タスクを起動・取得・適用（個別オプションは Codex CLI のバージョンで変動するため、最新仕様は codex cloud --help で確認）
• モデル切替 (/model): モデル（記事執筆時点で GPT-5.4 系・GPT-5.3-Codex 系などが選択可能、最新リストは TUI 内 /model で確認）と reasoning level（low / medium / high）の切替
• サブエージェント: 長時間タスクを並列分割して同時実行
• MCP 対応: Model Context Protocol 経由で社内 DB・Jira・Slack 等の外部ツールに接続
• Sandbox / Approval mode: macOS は Seatbelt、Linux は Landlock を使った OS-level の権限隔離

「手元でリポジトリを触りながら、すぐに反映を確認する」対話型ワークフローと、「CI で自動的にレビュー・パッチを回す」スクリプト型ワークフローの両方に対応します。

Codex IDE Extension とは

Codex IDE Extension は、エディタ内で Codex を呼び出せる公式拡張機能です。対応 IDE は VS Code / VS Code Insiders / Cursor / Windsurf / JetBrains（Rider / IntelliJ / PyCharm / WebStorm）。対応 OS は macOS / Windows / Linux のいずれも安定対応です。

主要機能は次のとおりです。

• コンテキスト連携: 開いているファイル、選択範囲、@file 参照で関連性の高い回答を得る
• 3 段階の Approval Mode: Chat（読み取りのみ）/ Agent（編集可・コマンドは確認）/ Agent (Full Access)（無制限）
• Cloud 委譲: 長時間タスクをクラウドへ送り、IDE 内で進捗監視・diff プレビュー・ローカル適用
• 画像生成: エディタを離れずに画像生成・編集
• 認証: ChatGPT アカウントまたは API キーの両対応

IDE Extension は「CLI と Cloud の橋渡し」役として機能し、エディタを離れずに 3 形態を行き来できます。

10 軸 完全比較表（コアコンテンツ）

3 形態の機能差を 10 軸で並列に整理した比較表です。

この表だけで判断できない場合は、後述の「タスク別おすすめ表」を併せて確認してください。

Codex Cloud の詳細仕様

Codex Cloud を活用する上で押さえるべき公式仕様を、項目別に深掘りします。

何ができるか（並列 / 長時間 / GitHub 連携）

Codex Cloud は「読む・編集する・実行する」をクラウド側のコンテナで行うエージェントです（出典: Codex Cloud 公式, 2026 年 5 月時点）。chatgpt.com/codex/ から GitHub アカウントを連携すると、対象リポジトリに対して以下の操作が可能になります。

• 自然言語で「テスト全実行してレポートして」「feature/x のリファクタを提案」「依存関係を最新化して PR を出して」と指示し、クラウドで非同期実行
• 1 リポジトリに対し複数タスクを並列起動（Review / Implement / Investigate / Fix を同時進行）
• GitHub Issue / PR のコメント内で @codex メンションするとタスク発火
• 完了後は PR ベースで差分レビューし、マージはユーザー操作で行う

Cloud は「30 分以上かかる、ローカルマシンを占有したくない、複数を並列で回したい」タスクに最適です。逆に「1〜2 分で結果が欲しい」「ローカルの実環境で動かしたい」タスクには CLI のほうが向きます。

Environments の仕組み

Codex Cloud の Environments は、タスク実行用のコンテナ環境を再利用可能な単位で定義する仕組みです（出典: Codex Cloud Environments 公式, 2026 年 5 月時点）。1 つの Environment は次の要素で構成されます。

• ベースコンテナイメージ: 既定では universal イメージ（共通言語・パッケージ・ツールがプリインストール）。Python・Node.js のバージョンを固定したいときは Environment 側で指定
• セットアップスクリプト: npm / yarn / pnpm / pip / pipenv / poetry の依存解決はテンプレで自動。これらに収まらない場合はカスタムスクリプトを記述
• 環境変数とシークレット: 環境変数はタスク全体で参照可能。シークレットはセットアップフェーズのみ参照可能で、エージェントフェーズ開始前にコンテナから削除される
• ツール選択: タスク実行時に許可するツール群（テストランナー、ビルドツール等）を指定
• キャッシング: コンテナの状態は最大 12 時間キャッシュされ、追従質問・新規タスクが高速化される

Environment はリポジトリ単位ではなく**「リポジトリ × ユースケース」単位で複数定義できる**ため、たとえば「フロントエンドのテスト実行用」「バックエンドのマイグレーション用」「セキュリティ監査用」と用途別に Environments を分離できます。

Internet Access の制御

Codex Cloud の Internet Access は、エージェントフェーズ中の外部ネットワーク到達性を制御する設定です（出典: Codex Cloud Internet Access 公式, 2026 年 5 月時点）。デフォルトは OFF（エージェントフェーズではインターネット不可）で、必要に応じて有効化します。

設計上の選択肢は以下のとおりです。

セキュリティリスクとして、Internet Access をオンにした場合は次のリスクが顕在化します。

• プロンプトインジェクション: 信頼できないコンテンツが指示を上書きする
• コード・シークレットの流出: 外部 POST 経由で秘匿情報が漏れる
• マルウェアや脆弱な依存関係のダウンロード: 信頼できない CDN・パッケージレジストリの混入

実運用では「セットアップフェーズだけネット ON / エージェントフェーズは OFF」がデフォルト推奨です。エージェントフェーズで外部 API を叩く必要がある場合のみ、HTTP メソッドを GET 系に制限したうえで Allowlist にドメインを追加します。

キャッシュ 12 時間とシークレットの原則

Codex Cloud のコンテナは最大 12 時間状態がキャッシュされます。これにより同じリポジトリへの追従質問・新規タスクは、依存解決を再実行せずに高速起動できます。

ただし、12 時間キャッシュには 2 つの注意点があります。

1. 古い依存関係を引きずるリスク: package.json を更新した直後など、setup script に変更がないままタスクを投げると、キャッシュされた古い node_modules が使われる可能性がある。明示的にキャッシュ無効化したい場合は setup script の末尾にバージョン文字列を含めるなど、ハッシュを変える運用が必要
2. シークレットの自動削除: シークレットはセットアップフェーズのみ参照可能で、エージェントフェーズ開始前にコンテナから削除されます。つまり「ビルド時の NPM_TOKEN」のような用途には使えるが、「実行時に外部 API を叩くための OPENAI_API_KEY」のような用途は環境変数（シークレットではなく通常の環境変数）として扱う必要がある

setup script を変更すると Codex はキャッシュを自動的に無効化し、次回タスク時にフルセットアップを再実行します。これを意図せず誘発するとタスク起動が遅くなるため、setup script は安定化させる運用が望ましいです。

料金プランと利用枠

Codex Cloud は ChatGPT Plus / Pro / Business / Edu / Enterprise のすべてで利用可能です（Free プランでは利用不可）。料金は ChatGPT のサブスクリプションに含まれており、追加課金なしで Cloud の利用枠が付与されます。

具体的な月額・利用枠は変動が激しいため、最新の正確な数値は Codex 公式料金ページ を必ず確認してください。以下は 2026 年 5 月時点の米国本国価格（米ドル・税別）に基づく一般的な関係です。

• Plus（$20/月、米ドル・税別）: 個人開発者の入門枠。CLI / IDE / Cloud すべてに 1 つの利用枠が共有される
• Pro（$200/月、米ドル・税別）: 終日ヘビーに使う個人向け。Cloud の並列枠が大幅拡張
• Business: 組織導入の標準。シート単価で利用、データはデフォルトで学習に使われない
• Enterprise: 大規模組織向け。SSO・監査ログ・契約 SLA が付帯

API 経由（API キーで CLI / IDE を使う）の場合は、入力・キャッシュ入力・出力それぞれのトークン単価による従量課金になります。Cloud は API キーで起動できないため、API 従量課金で Cloud を使う方法は提供されていません。

Codex CLI の詳細仕様

Codex CLI を運用するうえで知っておくべき仕様を整理します。

インストールと認証

# npm でインストール（推奨）
npm i -g @openai/codex

# または Homebrew
brew install codex

# 初回起動
codex

初回起動時に ChatGPT アカウントでブラウザ認証するか、API キー（環境変数 OPENAI_API_KEY）でログインします。ChatGPT アカウントでログインすると、ChatGPT プランの利用枠を消費して動作します。API キーは API 従量課金になり、組織のガバナンスを統一しやすいですが、Codex Cloud には接続できない点に注意してください。

macOS / Linux は安定対応、Windows は WSL 経由が推奨される実験的サポートです。

主要コマンドと TUI

Codex CLI の主要コマンドを表にまとめます。

TUI 内では /model、/approval、/quit などのスラッシュコマンドでセッション制御を行います。スクリーンショットをドラッグ＆ドロップで添付すれば、UI 修正タスクなど視覚情報込みの指示も可能です。

Sandbox と Approval mode

Codex CLI の安全機構は「Sandbox（物理的に何ができるか）」と「Approval mode（何をする前に確認するか）」の 2 層で構成されます（出典: Sandboxing 公式 および Agent approvals & security 公式, 2026 年 5 月時点）。

Sandbox は OS の隔離機構を使って、Codex が触れる範囲を技術的に縛る仕組みです。

• macOS: Seatbelt（sandbox-exec）
• Linux: Landlock + seccomp
• デフォルト挙動: ネットワーク OFF、書き込みは作業ディレクトリのみ

config.toml の sandbox_workspace_write セクションで、network_access・追加書き込みパス・読み取り専用パスを細かく指定できます。例:

[sandbox_workspace_write]
network_access = false
writable_roots = ["./tmp", "./build"]
exclude_tmpdir_env_var = true
exclude_slash_tmp = true

※ キー名は変更されることがあるため、最新の正しいキー名は公式ドキュメントの該当ページまたは codex --help で確認してください。

Approval mode はエージェントが何かをする前に人間に確認を求めるルールです。CLI では 3 段階あります。

codex --approval-policy agent で起動時に固定するか、TUI 内で /approval を実行して動的に切り替えます。Sandbox と Approval mode は独立に設定できるため、「Sandbox は厳しく、Approval は緩い」「Sandbox は緩いが Approval は都度確認」のような組み合わせも可能です。

サブエージェントと MCP

Codex CLI は長時間タスクを並列分割するためのサブエージェント機能を備えています。親エージェントが「テスト失敗を調べて」と指示すると、子エージェントが個別のテストファイル単位で並列に調査し、結果をマージして親に返します。サブエージェントごとに別のモデル・推論レベル・ツール権限を割り当てられるため、「重い処理は high reasoning、軽い処理は medium reasoning」のようなコスト最適化が可能です。

MCP (Model Context Protocol) は、外部ツールを Codex CLI から呼び出すための標準プロトコルです。~/.codex/config.toml の [[mcp_servers]] セクションで MCP サーバを登録すると、社内 DB・Jira・Slack・カレンダー・社内ドキュメント検索など、任意のツールを Codex のエージェントに使わせられます。

Cloud は MCP サーバを任意登録できず、Environments で提供されるツールのみを使える点が CLI との大きな違いです。社内システム連携を行う場合は CLI が現実的な選択肢になります。

料金プランと利用枠

Codex CLI の利用枠は Cloud と共有されます（ChatGPT サインインの場合）。API キーで使う場合は、入力・キャッシュ入力・出力それぞれのトークン単価による従量課金になります。

「ヘビーに CLI を使うが Cloud は不要」というケースでも、ChatGPT Plus に加入しておくと CLI 単体で API 従量課金より安く済むケースが多いです。逆に「CI から codex exec を不定期に大量呼び出しする」ような用途は API 従量課金のほうが上限がなく運用しやすいです。利用枠の超過時の挙動（ハードキャップで停止 / 速度低下 / 課金継続）はプランごとに異なるため、必ず公式の料金ページを確認してください。

タスク別おすすめ表（8 タスク種別）

実務でよくあるタスクと、推奨するプラットフォームをマトリクスで整理します。

上記は「単独で使う場合の推奨」ですが、実際には併用パターン（後述）のほうが効率的なケースが多いです。たとえば「Cloud で大規模リファクタを並列実行 → CLI で結果を取り込みデバッグ → IDE Extension で最終調整」という流れが標準テンプレートになります。

codex cloud exec 完全リファレンス

Codex CLI から Cloud を操作する codex cloud サブコマンド群の挙動を、コマンド単位で詳細解説します。具体的なオプション名は Codex CLI のバージョンによって追加・変更されるため、CI に組み込む前に必ず codex cloud --help で最新仕様を確認してください。

exec / list / status / diff / apply 全コマンド

codex cloud exec

Cloud にタスクを投げる基本コマンドです。TUI を起動せず非対話で実行されます。

codex cloud exec "Run all tests and report results"
codex cloud exec --env <ENV_ID> "Refactor the auth module"
codex cloud exec --attempts 3 "Find and fix all type errors"

• --env <ENV_ID>: 使用する Environment を指定。省略時はデフォルト Environment
• --attempts <N>: 同じプロンプトで複数試行（1〜4 推奨）。試行ごとに別 task-id が発行される
• 戻り値: タスク ID（後続の codex cloud status / codex cloud apply で参照）

非対話なので CI から呼び出して結果を待つ、あるいは投げっぱなしにして後で codex cloud list で回収する運用ができます。

codex cloud list

進行中・完了済みの Cloud タスクを一覧表示します。

codex cloud list
codex cloud list --status running
codex cloud list --limit 20

各タスクの task-id・状態（running / completed / failed）・プロンプト概要・経過時間が表示されます。

codex cloud status <task-id>

特定タスクの詳細状態を取得します。

codex cloud status abc123

進捗ログ、現在実行中のツール、推定残り時間が表示されます。スクリプトから完了待ちする場合はこのコマンドをポーリングします。

codex cloud diff <task-id>

完了タスクが行った変更の diff を表示します。

codex cloud diff abc123
codex cloud diff abc123 --format json

--format json で構造化された変更内容を取得し、jq などで加工することも可能です。

codex cloud apply <task-id>

Cloud タスクの差分をローカルリポジトリに適用します。

codex cloud apply abc123
codex cloud apply abc123 --branch feature/codex-cloud-apply

--branch で新規ブランチに適用すれば、現在の作業を汚染せず Cloud 結果をレビューできます。merge コンフリクトが発生した場合は通常の git merge 同様に手動解決が必要です。

オプション一覧とサンプル

CI / GitHub Actions から呼び出す典型例:

codex cloud exec \
  --env prod-env \
  --attempts 2 \
  "依存パッケージを最新化して通常テストとセキュリティテストを実行"

JSON 出力で結果を受け取り、後続処理に渡す例:

codex cloud diff $(codex cloud list --status completed --limit 1 --format json | jq -r '.[0].id') --format json > result.json

スクリプトから完了待ち + 自動適用するパターン（タイムアウト付き）:

# 注: --format json の対応有無は CLI バージョンに依存。
# 未対応の場合は codex cloud list --status running --limit 1 で
# 別経路でタスクIDを取得してください。

MAX_WAIT_SEC=3600
ELAPSED=0
TASK_ID=$(codex cloud exec "テストを全実行" --format json | jq -r '.task_id')

while [[ $ELAPSED -lt $MAX_WAIT_SEC ]]; do
  STATUS=$(codex cloud status "$TASK_ID" --format json | jq -r '.status')
  [[ "$STATUS" == "completed" ]] && break
  [[ "$STATUS" == "failed" ]] && { echo "Task failed"; exit 1; }
  sleep 10
  ELAPSED=$((ELAPSED + 10))
done

[[ $ELAPSED -ge $MAX_WAIT_SEC ]] && { echo "Timeout after ${MAX_WAIT_SEC}s"; exit 2; }
codex cloud apply "$TASK_ID" --branch "codex/$TASK_ID"

レスポンスとエラー処理

codex cloud 系コマンドは以下の代表的なエラーを返します。

CI で安定運用する場合は、これらのエラーを grep で検知して再試行ロジックを組むか、--attempts 2 程度を標準にしておくと中断耐性が上がります。

Cloud vs CLI コスト実測比較

同じタスクを Cloud と CLI で実行した場合のコスト差を、3 種類の代表タスクで比較します。

軽量タスク（5 分）/ 中量（15 分）/ 大規模（45 分+）

以下は ChatGPT Plus（$20/月、米ドル・税別）契約下での代表値（2026 年 5 月時点、汎用モデルを中程度の reasoning レベルで使用した場合の概算）。実数値はモデル選択・推論レベル・対話の長さで変動するため、目安として扱ってください。

結論: 5 分の軽量タスクは CLI が高速、15 分以上は Cloud の並列性が効き、30 分以上では Cloud がコスト・体感ともに優位になります。Cloud のコンテナ起動オーバーヘッドは筆者環境の実測で通常 1〜3 分のため、5 分以下のタスクには相対的に重く感じます（公式の確定値ではなく実測体感値です）。

Plus / Pro / Business 月額換算

「1 か月でどのくらいのタスクを回せるか」を試算します。利用枠は変動するため、ここではプラン別の典型的な使用感を示します。

ヘビーユースで上限に当たり始める閾値はモデル・推論レベルで変わるため、最新は Codex 公式料金ページ を確認してください（出典: Codex 公式料金ページ, 2026 年 5 月時点）。

「Cloud をどのくらい並列で回せるか」は Plus と Pro で体感差が最も大きい部分です。組織で複数人がヘビーに使う想定なら Business / Enterprise のシート単価制が安定運用しやすくなります。

AGENTS.md と config.toml の互換性マトリクス

Codex の挙動を定義する設定ファイルは主に 2 種類あります。3 形態でどちらが読まれるかを表で整理します。

AGENTS.md は 3 形態すべてで読み込まれるため、「コーディング規約」「ブランチ命名規則」「テストコマンド」など、形態に依存しない指示は AGENTS.md に集約するのが最適解です。

一方、config.toml で書く Sandbox / Approval / MCP の設定は CLI / IDE 専用です。CLI で「agent-full-access がデフォルト」と書いておいても Cloud には反映されないので、Cloud の自律度は Cloud UI / Environment 側で別途設定してください。

Cloud → CLI / CLI → Cloud 移行ガイド

既存の運用から別形態に移行する手順を整理します。

CLI 主体から Cloud 主体へ

CLI で運用しているプロジェクトを Cloud にも対応させる手順:

1. AGENTS.md の見直し: config.toml で表現していたルールのうち、コーディング規約・テストコマンド・依存関係セットアップ手順を AGENTS.md に移植
2. Environment の作成: chatgpt.com/codex/ で対象リポジトリを連携し、Environment を作成。setup script に CI と同じ依存解決コマンドを入れる
3. シークレットの再配置: API キーや GitHub トークンは、「セットアップフェーズで使うもの」をシークレットに、「実行時に使うもの」を環境変数に分けて登録
4. Internet Access の決定: 既存の CI が外部 API に依存していれば、エージェントフェーズの Internet Access を許可ドメインリスト + GET 系メソッド限定で有効化
5. 動作確認: codex cloud exec "現状の最も小さなテストを実行" で疎通確認

Cloud 主体から CLI 主体へ

Cloud で運用しているプロジェクトを CLI 主体に切り替える手順:

1. config.toml の作成: ~/.codex/config.toml を新規作成し、Sandbox（sandbox_workspace_write）と Approval mode を本番運用に合わせて設定
2. MCP 連携の追加: Cloud の Environment で使っていたツールに相当する MCP サーバを [[mcp_servers]] に登録
3. 認証方式の選択: 組織のガバナンスに応じて API キー（OPENAI_API_KEY）か ChatGPT アカウントを選択
4. 対話 vs codex exec: 開発者ごとの作業は対話モード、CI / バッチは codex exec でスクリプト化
5. 動作確認: codex exec "テストを実行" で同一タスクが動くかチェック

AGENTS.md / config.toml の互換性ポイント

「AGENTS.md に書くべきこと」「config.toml に書くべきこと」を整理します。

• AGENTS.md に集約すべき: コーディング規約、ブランチ命名、テストコマンド、ディレクトリ規約、PR ルール、コミットメッセージ規約
• config.toml に集約すべき: Sandbox の境界、Approval mode、MCP サーバ、モデル既定値、ローカル固有のショートカット

「Cloud と CLI で動作が違う」と感じたら、AGENTS.md と config.toml の役割分担が混線していないかを最初に疑ってください。

失敗パターン 5 選

Codex Cloud を使い始めたチームがハマりがちな典型的な失敗を整理します。

1. ファイル永続性を忘れてキャッシュ後にリセットされる

Cloud のコンテナはタスク完了後に破棄され、12 時間のキャッシュも setup script 変更で無効化されます。「Cloud で生成した中間ファイル」をそのまま次のタスクで使おうとすると失敗します。

対処: 永続化が必要な成果物は、必ず git commit してリポジトリに反映するか、codex cloud apply でローカルに取り込んでから次のステップに進めてください。

2. Internet Access OFF のまま npm install 系が落ちる

エージェントフェーズの Internet Access がデフォルト OFF なので、エージェントが追加で pip install や npm install を実行しようとすると失敗します。

対処: 依存解決は必ずセットアップフェーズで完結させ、setup script に明示する。エージェントフェーズで動的に依存を追加させたい場合のみ、Internet Access を許可ドメイン + GET 系限定で有効化します。

3. シークレットをエージェントフェーズで参照しようとして失敗

Cloud のシークレットはセットアップフェーズのみ参照可能で、エージェントフェーズ開始前に削除されます。「実行時に API キーが必要」なケースで、シークレットに登録すると Codex が「key not found」で失敗します。

対処: 「セットアップで使う認証情報」だけシークレットに、「実行時に使う鍵」は通常の環境変数として登録します。後者は Codex のログから漏洩リスクが高まる点に留意し、Internet Access を厳しめにします。

4. HTTP メソッド制限で POST API テストが落ちる

Internet Access のオプションで HTTP メソッドを GET / HEAD / OPTIONS のみに制限していると、POST / PUT / PATCH を使う API のテストが落ちます。

対処: テストで POST が必要な場合は、HTTP メソッド制限を緩和するか、テスト対象 API をモックする。「絶対に外部 POST を出さない」前提でメソッド制限している場合は、Cloud ではなく CLI のサンドボックス内でテストを完結させる選択もあります。

5. AGENTS.md に CLI 固有設定を書いて Cloud で無視される

AGENTS.md は 3 形態共通で読まれますが、ここに「Sandbox は read-only」「/model gpt-5.3-codex をデフォルトにする」など CLI 固有設定を書いても、Cloud は config.toml を読まないため反映されません。

対処: AGENTS.md には「人間にとってのプロジェクトルール」を書き、エージェント実行環境の設定は config.toml（CLI / IDE）と Environment（Cloud）に分けて書きます。

おすすめ併用パターン（並列 + 対話）

Codex の真価は単独利用ではなく、3 形態の組み合わせで発揮されます。代表的な併用テンプレートを 3 つ紹介します。

パターン A: Cloud で並列発火 → CLI で取り込みデバッグ

1. chatgpt.com/codex/ で複数の改修タスクを Cloud に並列発火
   - PR-1: テスト追加
   - PR-2: 依存更新
   - PR-3: パフォーマンス調査

2. 完了したものから CLI で取り込み
   $ codex cloud list --status completed
   $ codex cloud apply <task-id> --branch feat/<task-name>

3. CLI 対話モードで微調整・最終レビュー
   $ codex
   > 「PR-1 の追加テストで、エッジケースを 3 つ追加して」

4. ローカルで git push → 通常の PR レビューフローへ

「人間が見ながら回す対話」と「クラウドに任せる長時間処理」が綺麗に分離できます。

パターン B: CLI で設計 → Cloud に長時間タスク委譲 → IDE Extension で監視

1. CLI 対話モードで設計を詰める
   $ codex
   > 「auth モジュールのリファクタ計画を立てて、影響範囲を列挙して」

2. 計画に納得したら CLI から Cloud に委譲
   > codex cloud exec --env prod-env "上の計画に従って実装して PR を出して"

3. IDE Extension の Cloud パネルで進捗をリアルタイム監視
   - 完了したら diff プレビュー
   - 問題なければ「Apply to Local」でブランチに適用

4. IDE 内で `@file` 参照しながら最終調整

設計の精度を CLI で人間が握り、実装の重い部分を Cloud に投げる「司令塔 + 実働部隊」モデルです。

パターン C: モバイル指示 + CI 自動レビュー

1. 移動中、ChatGPT モバイルアプリから @codex でタスク発火
   - 例: 「main の最新の PR を読んで、セキュリティ観点でレビュー」

2. GitHub Actions に組み込んだ `codex exec` で自動 PR レビュー（後述の YAML 例を参照）

3. デスクで CLI / IDE Extension で結果を確認・補足

Cloud（モバイル）でタスク起動、CLI（CI）で自動レビュー、IDE で最終確認、という時間軸で 3 形態を使い分けるパターンです。組織導入後にスケールしやすい構成です。

GitHub Actions の最小例:

name: Codex PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Codex CLI
        run: npm i -g @openai/codex
      - name: Run Codex review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: codex exec "新規 PR の差分をレビューしてコメント"

FAQ

まとめ — Codex 3 形態を使い分ける指針

Codex Cloud と Codex CLI は対立する選択肢ではなく、役割分担で組み合わせる前提のツール群です。本記事の要点を再掲します。

• CLI の主戦場: 5〜30 分の対話デバッグ、CI 連携、手元での自動化スクリプト
• Cloud の主戦場: 30 分以上の長時間タスク、並列バッチ、PR 自動レビュー、モバイル指示
• IDE Extension の役割: エディタ内での修正、Cloud と CLI の橋渡し
• AGENTS.md は 3 形態共通、config.toml は CLI / IDE 専用、Cloud 設定は Environment 側
• キャッシュ 12 時間とシークレットの自動削除を理解しないと典型的な失敗を踏みやすい
• Internet Access は「セットアップ ON、エージェントフェーズ OFF、必要時のみ許可ドメイン + GET 系限定」が定石

組織の Codex 導入では「全員 Cloud 主体」「全員 CLI 主体」のどちらも極端で、開発フェーズ・タスク種別に応じた 3 形態の使い分けが成果に直結します。Environment 設計と AGENTS.md / config.toml の役割分担を最初に決めておくことで、Cloud と CLI の往復で生じるオーバーヘッドを最小化できます。

関連記事として、AI コーディング全体の選び方は AI コーディングツール比較 2026、Claude Code との比較は Claude Code vs Codex CLI 比較 を参照してください。Codex CLI を Claude Code と併用する設計判断は Claude Code 日本語ガイド、MCP 連携の詳細は Claude Code MCP 連携 に整理しています。

koromo の Codex 導入支援

koromo は、Codex Cloud / CLI / IDE Extension の組織導入を「Environment 設計から AGENTS.md / config.toml の役割分担、CI 連携、運用ガイドライン策定まで一気通貫」で支援しています。Codex の 3 形態を排他選択ではなく役割分担で組むことで、開発リードタイムを短縮しつつセキュリティ境界を明確化できます。

「Codex を全社展開したいが、Cloud と CLI の使い分けで現場が混乱している」「CI に組み込みたいが Sandbox / Approval mode の設計が不安」「Environment を業務別に設計したい」といった課題は、koromo のお問い合わせ からご相談ください。