OpenAI公式のコーディングエージェントCLI。インストール・認証・自律性モード、そしてClaude Codeとの比較を30分で。

OpenAI が独自のコーディングエージェント CLI を提供している。Codex CLI は Anthropic の Claude Code に相当する OpenAI 版で、GPT-5（または o1/o3 ライン）上で動作し、自律的なシェル実行・複数ファイル編集・プランして実行するフローを提供する。

このガイドはCodex CLIをセットアップし — Claude CodeまたはCursorをすでに使っている前提で — どのタスクをCodexに任せるべきかを説明する。初めての方はClaude Code セットアップと併せて読んでください。

一つのツールだけで全てを解決しようとするのではなく、ツールの強みに合わせて使い分けることが重要だと考える。Claude CodeとCodex CLIはライバルではなく、役割の違いからだ — 長いコンテキスト作業はClaude Codeへ、推論重視のタスクはCodex CLIへというように。

TL;DR

Node.js 20+ → npm install -g @openai/codex → codex → ブラウザ認証
OpenAI APIキーまたはChatGPT Plus/Proサブスクリプションを使用
デフォルトは承認モード（各コマンドを確認）— --auto-edit / --full-auto で自律性を上げる
モデルを選択: --model gpt-5 または o3（性能とコストのトレードオフ）
Claude Codeとの役割分担: §5参照

前提条件

Node.js 20+（mac/dev-toolchain または windows/initial-setup）
OpenAIアカウント — platform.openai.com またはChatGPT Plus/Pro
git管理されたプロジェクト

1. Codex CLIの位置づけ

これは OpenAI の ファーストパーティ コーディングエージェント CLI だ。OpenAI モデルを呼び出すサードパーティツール（Cursor、Aider、Continue）とは異なり、Codex CLI は OpenAI 自身の公式リリースだ。

Claude Codeとの共通点

ターミナルで自律実行
複数ファイル編集・シェルコマンド・git統合
プロジェクトコンテキスト（Codexは .codex/ ディレクトリに保存）
プラン → 実行 → 検証ワークフロー

違い

項目	Codex CLI	Claude Code
モデル	GPT-5 · o3 · o4	Claude Opus / Sonnet / Haiku
コンテキストウィンドウ	200K（モデルにより異なる）	1M（Opus/Sonnet 4）
自律性フラグ	`--auto-edit`、`--full-auto`	パーミッションモード + hooks
認証	APIキーまたはChatGPTサブスクリプション	APIキーまたはPro/Maxサブスクリプション
料金	トークン課金またはPlus（$20）/Pro（$200）	トークン課金またはPro（$20）/Max（$100/$200）
MCP サポート	部分的（開発中）	フル
IDE統合	別途IDE拡張機能	VS Code · JetBrains · CLI

向いているユーザー

ChatGPT Plus/Proをすでに使っている — Codex CLIが含まれる
OpenAIエコシステムに既に投資している — Embeddings、DALL·Eなどとキーを共有できる
長い思考を要するタスクでo3/o4の推論優位性が欲しい
GPT-5マルチモーダルが必要 — 画像/図表を入力として使いたい

2. インストール

2.1 npmグローバル

npm install -g @openai/codex
codex --version

インストールが失敗したりパーミッションエラーが出る場合は、Claude Code セットアップ §1.1のnpm-prefixの回避策を参照してください。

2.2 初回実行

cd ~/projects/my-repo
codex

ブラウザタブが開いてOpenAIログイン → アクセスを許可 → CLIに戻りる。トークンはOSキーチェーンに保存される。

2.3 認証オプション

3つの方法:

# A. ChatGPT Plus/Pro（サブスクリプション）
codex auth login --use-chatgpt
 
# B. OpenAI APIキー
codex auth login --use-api
# → OPENAI_API_KEYを読み取るかプロンプトで入力
 
# C. Codex.comアカウント専用（ベータ）
codex auth login --use-codex

確認:

codex auth status
# Account: <email>
# Plan: ChatGPT Plus / API tier 2

3. 自律性モード

デフォルトは保守的 — 全てのシェルコマンドと編集を確認する。自律性レベル:

フラグ	動作	リスク
（デフォルト）	コマンドと編集の前に毎回確認	低
`--auto-edit`	編集は自動、シェルは引き続き確認	中
`--full-auto`	全て自動（危険）	高

推奨: ツールを十分試すまでデフォルトを維持し、慣れたリポジトリで --auto-edit に切り替えましょう。

codex --auto-edit
> Refactor the auth module into smaller files

4. コアコマンド

4.1 セッションを開始する

codex
> Plan: add a password reset feature

自然言語プロンプト → Codex がプランを提案 → 承認 → 実行。

4.2 スラッシュコマンド

セッション内:

/help — コマンド一覧
/init — プロジェクトを解析して AGENTS.md を作成
/model gpt-5 — モデルを切り替え
/clear — コンテキストをリセット
/exit — 終了

4.3 `AGENTS.md` — プロジェクトガイダンス

CLAUDE.md に相当するCodexのファイル。プロジェクトルートに:

# AGENTS.md
 
## スタック
- Next.js 16 + TypeScript strict
- Supabase + Postgres
- pnpm 11
 
## コマンド
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`
 
## 規約
- `any`型禁止
- ルート: kebab-case
- コミット: `[Project] type: description`
 
## 作業原則
- 5ファイル以上の変更前にプランを立てる
- テスト + lint + ビルドが通るまで「完了」にしない
- シークレットは絶対コミットしない

セッション開始時に自動ロードされる。機能的には CLAUDE.md とほぼ同じだ。

Claude Code と両方使う場合: CLAUDE.md と AGENTS.md に内容を重複させるか、AGENTS.md のみ保持して CLAUDE.md から @AGENTS.md で参照してください。

5. Claude Code vs Codex CLI — タスクマッピング

タスク	選択	理由
1Mコンテキストの複数ファイル作業	Claude Code	Opus/Sonnet 4の1Mウィンドウ
長い推論（デバッグ、アーキテクチャ）	Codex CLI（o3）	推論モデルの優位性
コード + 画像（スクリーンショット解析）	Codex CLI（GPT-5マルチモーダル）	画像入力
変更後の自律検証	Claude Code	hooks + verifyシステム
OpenAIエコシステム統合（embeddingsなど）	Codex CLI	統合キー
MCP サーバー（Linear、Notionなど）	Claude Code	フルMCP
コスト最小化	すでに持っているサブスクリプション	APIトークンを節約

どちらも同じリポジトリで競合なく動作します（両方とも git ベース）。

6. 料金（2026年5月時点）

APIの料金（Codex CLI）

モデル	入力	出力	単価
GPT-5	$1.25 / 1M	$10 / 1M	入力コストが低い
o3	$2 / 1M	$8 / 1M	推論最適化
o4-mini	$0.3 / 1M	$1.2 / 1M	コスパ最高

サブスクリプション

プラン	価格	Codex CLI使用
ChatGPT Plus	$20/月	GPT-5制限付き、一部o3
ChatGPT Pro	$200/月	ほぼ無制限

実際の費用は異なる。APIのフルスタック開発者の概算: $30〜100/月。ヘビーユーザーはProが有利だ。

7. 確認

# 1. インストール済み
codex --version
 
# 2. 認証
codex auth status
 
# 3. プロジェクトファイル
ls -la AGENTS.md .codex/
 
# 4. 最初のコマンドテスト
echo "create a hello.py that prints 'hello'" | codex --auto-edit

4つ全て通ればセットアップ完了だ。

8. トラブルシューティング

`codex: command not found`

npmプレフィックスを確認: npm config get prefix の /bin がPATH上にある必要がある
新しいターミナルを開いて再試行

ブラウザ認証が開かない

ヘッドレス環境（WSL2/SSH）: CLI に表示された URL をブラウザに手動でコピー
それでも失敗する場合は ~/.codex/auth.json を削除し、codex auth login --use-api でキーを指定してください

「Insufficient quota」

OpenAIの使用上限に達しました — platform.openai.com/usage
無料枠は非常に制限されている。Tier 1+（$10プリペイド後に有効化）が実用的な最低水準だ

CodexとClaude Codeが同じファイルを同時に編集する

一方ずつ実行するか、片方が終わるまで待つ
または .codex-lock スタイルのセンチネルファイルを .gitignore に追加して調整する

`--full-auto` で行き過ぎた変更をされた

すぐに Ctrl+C
git reset --hard HEAD または git stash で復元
以降は --auto-edit を使いましょう

MCP サーバーが接続できない

2026年5月時点で、Codex CLIのMCPサポートは部分的（ベータ）だ
フルMCP統合にはClaude Codeを使用してください

9. 次のステップ

Claude Code セットアップ — /ai-agents/claude-code
Cursor セットアップ — /ai-agents/cursor-setup
Copilot セットアップ — /ai-agents/github-copilot
マルチツールワークフロー — /ai-agents/multi-tool-workflow

参考リンク

変更履歴

2026-05-16: 初版。Codex CLIインストール + 3つの認証方法 + 自律性モード + AGENTS.md + Claude Code比較表 + 6つのトラブルシューティング。

OpenAI Codex CLI セットアップ — Claude CodeおよびCursorとの比較