「Codex CLIって、Claude Codeと何が違うの？」
先日、エージェント開発の勉強会でこんな質問を受けました。同席していたエンジニアも「同じくOpenAI製なのになぜ今さら？」と首をかしげていました。
実際に検証してみると、これが想像以上に使い勝手のいいツールでした。--full-autoフラグで本当に”全自動”でリファクタリングをこなし、--sandbox workspace-writeで安全にファイル変更を制限できる設計は、CI/CDパイプラインへの組み込みにも適しています。
この記事では、Codex CLIのインストールから3つのapproval mode、そして実践的なエージェントデモまで、コピペ可能なコード付きで全公開します。Claude Codeとの使い分けも含め、5分で試せるセットアップから始めていきましょう。
AIコーディングツール全体の比較については、AIエージェント構築完全ガイドもあわせてご覧ください。
まず試したい「5分即効」セットアップ3選
即効テクニック1：npmでグローバルインストール
Codex CLIはnpmパッケージとして配布されています。Node.js 18以上がインストールされた環境で以下を実行するだけです。
# グローバルインストール
npm i -g @openai/codex
# バージョン確認
codex --version
# 初回起動（ChatGPTアカウントでの認証が求められる）
codex
動作環境: Node.js 18+、macOS/Linux（Windows はWSL経由で動作）
必要なプラン: ChatGPT Plus/Pro/Business/Edu/Enterprise のいずれか（2026年3月時点）
注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
即効テクニック2：最初のコード生成タスクを投げる
インストール後、プロジェクトディレクトリに移動してcodexコマンドを起動し、自然言語でタスクを指示します。
# プロジェクトディレクトリで起動
cd ~/my-project
codex
# 起動後、インタラクティブモードで指示を入力
# 例: "このリポジトリのREADME.mdを最新のコードに合わせて更新して"
# 例: "src/utils.py の関数に型ヒントを追加して"
ポイント: 起動すると現在のディレクトリをスキャンし、コードベースを理解した上でタスクを処理します。短い指示でも文脈を読んで適切な変更を提案してくれます。
即効テクニック3：非対話モードでワンライナー実行
スクリプトやCIから呼び出す場合は、タスクを引数として直接渡せます。
# ワンライナーでタスク実行（確認ありモード）
codex "src/app.py の全関数にdocstringを追加して"
# --full-autoフラグで確認なし実行（ローカル作業用）
codex --full-auto "テストが失敗しているユニットテストをすべて修正して"
# --jsonフラグでCI/自動化用に構造化出力
codex --json "package.json の依存パッケージのセキュリティ脆弱性を確認して"
動作環境: codex CLI v0.1.0以降（2026年3月時点）
注意: --full-autoは信頼できるリポジトリ・タスクに限定してください。本番環境で使用する前に、必ずテスト環境で動作確認してください。
Codex CLIの3つのapproval mode
Codex CLIの最も重要な設計思想が「どこまで自動で動かすか」のコントロールです。3つのsandboxモードと承認フラグを組み合わせることで、安全性と自動化度のバランスを細かく調整できます。
approval modeの全体像
| モード/フラグ | 動作 | 適した用途 | セキュリティレベル |
|---|---|---|---|
--ask-for-approval on-request |
コマンド実行前に確認 | インタラクティブ作業 | 高 |
--ask-for-approval never |
確認なしで実行 | 自動化・CI（要注意） | 低 |
--full-auto |
on-request + workspace-write の組み合わせ | ローカル自動作業 | 中 |
--sandbox read-only |
ファイル読み込みのみ | 調査・レビュー | 最高 |
--sandbox workspace-write |
作業ディレクトリ内のみ変更可 | 通常の開発作業 | 高 |
--sandbox danger-full-access |
すべての操作を許可 | 専用サンドボックスVM | 最低（要注意） |
最終確認日: 2026-03-27
各モードの使い分け
# 【推奨】通常の開発: 作業ディレクトリ内のみ変更、実行前に確認
codex --sandbox workspace-write --ask-for-approval on-request "〜を修正して"
# ローカル自動作業（--full-autoは workspace-write + on-request の組み合わせ）
codex --full-auto "このプロジェクトのリントエラーをすべて修正して"
# 読み取り専用（コードレビュー・調査のみ）
codex --sandbox read-only "このコードのセキュリティ問題を報告して"
# CI/完全自動（孤立環境でのみ使用）
codex --ask-for-approval never --sandbox danger-full-access "テストを実行して失敗箇所を修正して"
動作環境: codex CLI v0.1.0以降
注意: --sandbox danger-full-accessと--ask-for-approval neverの組み合わせは、信頼できる孤立した環境（専用CIコンテナなど）でのみ使用してください。本番環境で使用する前に、必ずテスト環境で動作確認してください。
インストールから実践デモまで — 3つのシナリオ
シナリオ1：コード生成→テスト実行
TypeScriptプロジェクトで、新しいAPIエンドポイントの実装とテストをCodex CLIに一括依頼する例です。
# プロジェクトディレクトリで Codex CLI を起動
cd ~/my-express-app
codex --full-auto
# 以下をインタラクティブモードで入力:
# "GET /users/:id エンドポイントを実装して。
# ユーザーが見つからない場合は404を返すこと。
# Jest用のユニットテストも合わせて作成して"
Codex CLIは既存のコードベースを読み取り、プロジェクトの命名規則やファイル構造に合わせたコードを生成します。
シナリオ2：AGENTS.md でエージェントに指示書を渡す
Codex CLIはリポジトリルートのAGENTS.mdファイルを自動的に読み込み、プロジェクト固有の制約を守ります。
# AGENTS.md の例
## コーディング規約
- TypeScript strict modeを使用
- 関数はすべてJSDocコメントを付ける
- テストカバレッジは80%以上を維持
## 禁止事項
- console.logの本番コードへの混入禁止
- any型の使用禁止（unknownを使うこと）
## テスト実行方法
npm run test:unit
# AGENTS.md がある状態で起動すると、自動的に読み込まれる
codex --full-auto "新しいAuthServiceクラスを実装して。AGENTS.mdの規約に従うこと"
動作環境: codex CLI v0.1.0以降、Node.js 18+
注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
シナリオ3：OpenAI Agents SDKとの連携
Codex CLIはOpenAI Agents SDKと組み合わせることで、複数のエージェントが協調するワークフローを構築できます。
# agents_sdk_example.py
# 動作環境: Python 3.11+, openai-agents>=0.1.0
# pip install openai-agents
from agents import Agent, Runner
# コードレビュー専門エージェント
code_reviewer = Agent(
name="CodeReviewer",
instructions="""
コードレビューの専門家として、提供されたコードを分析し、
セキュリティ問題、パフォーマンス問題、コーディング規約違反を
それぞれのカテゴリで報告してください。
""",
model="codex-mini-latest", # Codex専用モデル
)
# テスト生成エージェント
test_writer = Agent(
name="TestWriter",
instructions="""
Pythonのpytestを使ったユニットテストの専門家です。
提供されたコードに対して、エッジケースを網羅した
テストコードを生成してください。
""",
model="codex-mini-latest",
)
async def review_and_test(code: str):
# コードレビューを実行
review_result = await Runner.run(
code_reviewer,
input=f"以下のコードをレビューしてください:nn{code}"
)
# テストを生成
test_result = await Runner.run(
test_writer,
input=f"以下のコードのテストを生成してください:nn{code}"
)
return {
"review": review_result.final_output,
"tests": test_result.final_output
}
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
動作環境: Python 3.11+, openai-agents 0.1.0以降
Claude Codeとの比較
| 比較軸 | Codex CLI | Claude Code |
|---|---|---|
| 開発元 | OpenAI | Anthropic |
| ベースモデル | codex-mini-latest, GPT-5系 | Claude Sonnet/Opus |
| インストール | npm i -g @openai/codex | npm i -g @anthropic-ai/claude-code |
| 認証 | ChatGPTアカウント（Plus以上） | Anthropic APIキー or Maxプラン |
| コンテキスト長 | モデル依存（GPT-5: 128K〜） | 最大1Mトークン（Opus 4.6） |
| 並列エージェント | Agents SDK連携で対応 | Agent Teams（内蔵） |
| MCP対応 | Agents SDK経由 | ネイティブ対応 |
| AGENTS.md | 対応（公式サポート） | CLAUDE.mdで同等機能 |
| approval mode | 3段階（read-only/workspace/full） | セキュリティポリシー設定 |
| 月額（2026年3月時点） | ChatGPT Plus $20〜 に込み | Max $20（Sonnet）〜$100（Pro） |
料金情報の最終確認: 2026-03-27（公式サイト参照）
使い分けの判断基準
正直に言うと、どちらが「優れている」かではなく、使い分けが最も現実的です。
- OpenAIエコシステムを使っているチーム（GPT-5, Agents SDK）→ Codex CLI
- 大規模コードベース・マルチエージェント（1Mトークン, Agent Teams）→ Claude Code
- ChatGPT PlusをすでにSubscribeしている → Codex CLIを追加費用なしで試せる
- CI/CDパイプラインへの組み込み → どちらも対応、approval modeが豊富なCodex CLIが使いやすい場面も
【要注意】よくある失敗パターンと回避策
失敗1：–full-autoを本番コードに直接使う
❌ 本番リポジトリで確認なしに--full-autoを実行してコミット前のファイルを書き換えてしまう
⭕ ブランチを切ってから実行、変更内容をgit diffで確認してからコミット
# 正しい使い方
git checkout -b codex-refactor
codex --full-auto "〜を修正して"
git diff # 変更内容を確認
git add -p # 変更を選択的にステージング
なぜ重要か: --full-autoは便利ですが、意図しないファイルを変更する可能性があります。常にgit管理下で使いましょう。
失敗2：AGENTS.mdに曖昧な指示を書く
❌「良いコードを書くこと」「セキュリティに気をつけること」のような抽象的な指示
⭕ 具体的な制約と確認コマンドを明記する
## テスト
- すべての変更後にnpm run testが通ること
- 新しい関数には必ずユニットテストを作成すること
- カバレッジが下がる変更は禁止
## コミット前の確認
npm run lint && npm run test:unit
なぜ重要か: AGENTS.mdに曖昧な指示を書くと、Codexが独自解釈で予期しない変更を加えることがあります。
失敗3：古いCodexモデル（2021年版）と混同する
❌ 「Codex CLIはGitHubCopilotの元になった補完モデルだ」という認識でAPIキーを探し回る
⭕ 2024年以降のCodex CLIはChatGPTアカウントで認証するエージェントツール。旧Codexモデルとは全くの別物
なぜ重要か: 2021年の旧Codex（OpenAI API経由のコード補完モデル）は既にdeprecatedです。現在のCodex CLIはターミナルで動くエージェントであり、ChatGPT Plusアカウントが必要です。
失敗4：Windowsのネイティブ環境で動かそうとする
❌ Windows PowerShellでnpm installして直接実行しようとする
⭕ WSL2（Windows Subsystem for Linux）経由で使う
# WSL2のUbuntu環境で
sudo apt update && sudo apt install nodejs npm
npm i -g @openai/codex
codex --version
なぜ重要か: Codex CLIはmacOS・Linuxがファーストクラスのサポート対象です。Windowsはexperimentalサポートであり、WSL2経由の方が安定します（2026年3月時点）。
セキュリティと運用のベストプラクティス
Codex CLIをチームや本番環境に近い場所で使う場合は、以下の点に注意が必要です。
シークレット管理
# APIキーや認証情報が含まれるファイルは .codexignore で除外
# （.gitignoreと同じ形式）
echo ".env" >> .codexignore
echo "secrets/" >> .codexignore
echo "*.pem" >> .codexignore
sandboxモードの選択基準
| 状況 | 推奨モード |
|---|---|
| コードレビュー・調査 | --sandbox read-only |
| 通常の開発作業 | --sandbox workspace-write |
| ローカルの一括リファクタ | --full-auto（workspace-writeの組み合わせ） |
| CI/CDパイプライン（孤立環境） | --sandbox danger-full-access --ask-for-approval never |
AGENTS.mdによる行動制限
## 禁止事項（AGENTS.mdに明記する）
- 本番データベースへの直接接続禁止
- APIキー・シークレットのハードコード禁止
- .envファイルの変更禁止
- package.jsonのdependencies変更は人間の確認を要する
注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
参考・出典
- Codex CLI — OpenAI Developers — OpenAI公式ドキュメント（参照日: 2026-03-27）
- Command line options – Codex CLI — コマンドラインオプション詳細（参照日: 2026-03-27）
- Agent approvals & security – Codex — セキュリティとapproval mode（参照日: 2026-03-27）
- openai/codex — GitHub — 公式リポジトリ（参照日: 2026-03-27）
- Custom instructions with AGENTS.md — AGENTS.md仕様（参照日: 2026-03-27）
まとめ：今日から始める3つのアクション
- 今日やること:
npm i -g @openai/codexでインストールして、手元のプロジェクトに対してcodex --sandbox read-only "このコードの改善点を教えて"を実行してみる - 今週中: AGENTS.mdを作成してプロジェクト固有のルールを設定。
--full-autoでリファクタリングを試す - 今月中: CI/CDパイプラインへの組み込みを検討。
--jsonフラグで構造化出力を取得して、自動レビューワークフローを構築する
あわせて読みたい:
- AIエージェント構築完全ガイド — フレームワーク選定から本番運用まで
- AIエージェントツール比較 — Dify/n8n/LangChainの選び方
この記事はAIgent Lab編集部がお届けしました。
AIエージェントの導入・研修・開発支援については、株式会社Uravationのお問い合わせフォームからお気軽にご相談ください。
