今さら聞けないCodex CLI入門：OpenAIのターミナル型AIコーディングエージェント完全ガイド

AIコーディングアシスタントの進化が止まりません。GitHub Copilot、Claude Code、Cursor…と様々なツールが登場する中、OpenAIが満を持してリリースしたのが「Codex CLI」です。

「名前は聞いたことあるけど、まだ触ってない」「Claude Codeとの違いがわからない」「設定が難しそうで手が出せない」——そんな方のために、Codex CLIの基本から実践的な使い方まで、徹底的に解説していきます。

Codex CLIとは何か

Codex CLIは、OpenAIが開発したオープンソースのターミナルベースAIコーディングエージェントです。Rustで構築されており、高速かつ効率的に動作します。

従来のCodex API（現在は非推奨）とは全く異なり、ローカル環境で動作するエージェント型ツールとして設計されています。ターミナル上でリポジトリを読み込み、ファイルを編集し、コマンドを実行できる——つまり、開発者のペアプログラミングパートナーとして機能します。

Codex製品の全体像

OpenAIのCodexは現在、以下の形態で提供されています：

これらは全て同じChatGPTアカウントで連携しており、ローカル環境とクラウドサンドボックス間でシームレスに作業を引き継げます。

利用プラン

Codex CLIは以下のプランに含まれています：

• ChatGPT Plus
• ChatGPT Pro
• ChatGPT Business
• ChatGPT Edu
• ChatGPT Enterprise

API経由での利用も可能で、その場合はOpenAI APIキーで認証します。

インストール方法

対応プラットフォーム

Codex CLIは macOS、Windows、Linux に対応しています。

npmでのインストール（推奨）

npm install -g @openai/codex

Homebrewでのインストール（macOS）

brew install --cask codex

GitHubリリースからの直接ダウンロード

GitHub Releasesから、お使いのプラットフォーム向けのバイナリをダウンロードすることも可能です。ダウンロード後、codexにリネームしてPATHの通った場所に配置してください。

インストールの確認

codex --version

バージョン情報が表示されれば、インストール成功です。

認証・ログイン

ChatGPTアカウントでのログイン（推奨）

codex login

ブラウザが開き、ChatGPTアカウントでのOAuth認証が行われます。Plus、Pro、Team、Edu、Enterpriseプランをお持ちの場合は、この方法が推奨されます。

APIキーでのログイン

APIキーを使用する場合：

printenv OPENAI_API_KEY | codex login --with-api-key

または、対話的にAPIキーを入力することも可能です。

ログイン状態の確認

codex login status

ログアウト

codex logout

基本的な使い方

インタラクティブモードの起動

codex

これだけで、フルスクリーンのターミナルUI（TUI）が起動します。リポジトリを読み込み、ファイルを編集し、コマンドを実行できる対話型セッションが始まります。

初期プロンプト付きで起動

codex "このコードベースを説明して"

起動と同時にタスクを指定できます。

ワンショット実行

codex "このプロジェクトの概要を教えて" --quiet

インタラクティブUIを使わず、単発で質問に回答してもらう場合に便利です。

利用可能なモデル

Codex CLIでは、以下のモデルが利用可能です：

セッション中にモデルを切り替えることも可能です：

/model

設定ファイル（config.toml）

Codex CLIの設定は ~/.codex/config.toml に保存されます。IDE拡張機能とCLIで共有されるため、一度設定すれば両方に反映されます。

基本的な設定例

# 使用するモデル
model = "gpt-5-codex"

# 承認ポリシー
approval_policy = "on-request"

# サンドボックスモード
sandbox_mode = "workspace-write"

# 推論の努力レベル（low/medium/high）
model_reasoning_effort = "high"

# ネットワークアクセスの設定
[sandbox_workspace_write]
network_access = false

# 環境変数の制御
[shell_environment_policy]
include_only = ["PATH", "HOME"]

# 機能フラグ
[features]
web_search_request = true
shell_snapshot = true

主要な設定項目

approval_policy（承認ポリシー）

コマンド実行前にユーザーの承認を求めるタイミングを制御します。

sandbox_mode（サンドボックスモード）

ファイルシステムとネットワークへのアクセス範囲を制御します。

プロファイルの活用

用途別にプロファイルを定義しておくと便利です：

# デフォルト設定
model = "gpt-5-codex"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

# 開発用プロファイル
[profiles.dev]
model_reasoning_effort = "high"
model_verbosity = "high"
approval_policy = "on-failure"

# クイックタスク用
[profiles.quick]
model_reasoning_effort = "low"
approval_policy = "never"

# 分析専用（読み取りのみ）
[profiles.analyze]
sandbox_mode = "read-only"
model_reasoning_effort = "high"

# 完全自動化
[profiles.auto]
sandbox_mode = "danger-full-access"
approval_policy = "never"

プロファイルを指定して起動：

codex --profile dev "このコードをリファクタリングして"

スラッシュコマンド

インタラクティブセッション中に使用できるスラッシュコマンドを覚えておくと、作業効率が大幅に向上します。

主要なスラッシュコマンド

/reviewコマンドの活用

/review

このコマンドを実行すると、Codexが現在の変更をレビューし、以下のような項目をチェックします：

• 潜在的なバグ
• パフォーマンスの問題
• セキュリティ上の懸念
• コードスタイルの一貫性

ベースブランチを指定してレビューすることも可能で、プルリクエスト前の確認に最適です。

AGENTS.md：プロジェクト固有の指示

AGENTS.mdは、Codexに対するプロジェクト固有の指示を定義するファイルです。リポジトリのルートに配置することで、Codexがセッション開始時に自動的に読み込みます。

配置場所と優先順位

1. グローバルスコープ：~/.codex/AGENTS.md（またはAGENTS.override.md）
2. プロジェクトスコープ：プロジェクトルートから現在のディレクトリまでの各階層

AGENTS.override.mdが存在する場合、通常のAGENTS.mdより優先されます。

AGENTS.mdの例

# プロジェクト指示

## コーディング規約
- TypeScriptを使用
- ESLintルールに従う
- 関数にはJSDocコメントを必須とする

## テスト
- Jest + React Testing Libraryを使用
- 新機能には必ずユニットテストを追加

## 禁止事項
- any型の使用禁止
- console.logを本番コードに残さない
- 直接DOMを操作しない（React経由のみ）

## 推奨パターン
- カスタムフックの活用
- コンポーネントの単一責任原則
- エラーバウンダリの実装

/initで雛形を作成

/init

このコマンドで、プロジェクトに適したAGENTS.mdの雛形を自動生成できます。

セッションの継続（Resume）

Codexはセッションの履歴をローカルに保存しています。前回の作業を引き継いで再開できます。

最近のセッションを選択して再開

codex resume

最近のセッション一覧がピッカーで表示され、選択したセッションを再開できます。

直近のセッションを自動的に再開

codex resume --last

フォローアップ付きで再開

codex resume --last "さっきの続きで、エラーハンドリングを追加して"

非インタラクティブモード（exec）

CI/CDや自動化スクリプトでCodexを使用する場合、execコマンドが便利です。

基本的な使い方

codex exec "テストを実行して失敗を修正"

JSON出力

codex exec --json "コードの問題点を分析"

ストリーミングでJSON Lines形式の出力を受け取れます。

出力をファイルに保存

codex exec --output-file result.md "READMEを更新"

Web検索機能

CodexにはファーストパーティのWeb検索ツールが組み込まれています。

設定での有効化

[features]
web_search_request = true

[sandbox_workspace_write]
network_access = true

コマンドラインでの有効化

codex --search "最新のReact 19の変更点を調べて"

Web検索が有効な場合、Codexはタスクに必要な最新情報をインターネットから取得できます。

コードレビュー機能

Codexの強力な機能の一つが、専用のコードレビュー機能です。

ブランチ差分のレビュー

/review

レビュープリセットが開き、以下のオプションから選択できます：

• Review against a base branch：ベースブランチとの差分をレビュー
• Review working tree：ワーキングツリーの変更をレビュー

レビューの特徴

• 優先度付きのフィードバック
• アクション可能な改善提案
• ワーキングツリーを変更しない非破壊的な分析
• テストカバレッジの不足を検出

MCP（Model Context Protocol）との連携

Codexは外部ツールとの連携のため、MCPサーバーをサポートしています。

MCPサーバーの設定

[mcp_servers.my-server]
command = "npx"
args = ["-y", "@my-org/mcp-server"]

CLIでの管理

# サーバーの一覧
codex mcp list

# サーバーの追加
codex mcp add my-server --command "npx -y @my-org/mcp-server"

# サーバーの表示
codex mcp show my-server

Codex自体をMCPサーバーとして起動

codex mcp

他のMCPクライアント（OpenAI Agents SDKなど）からCodexを利用できます。

画像入力

Codexはスクリーンショットやデザインスペックの画像を読み取ることができます。

コマンドラインで画像を添付

codex --image design-mockup.png "このモックアップをReactコンポーネントとして実装して"

複数画像の添付

codex --image before.png,after.png "この2つの画面の違いを実装して"

対応形式：PNG、JPEG、GIF、WebP

セキュリティとベストプラクティス

サンドボックスの活用

デフォルトのworkspace-writeモードでは：

• ネットワークアクセスは無効
• ワークスペース外への書き込みは不可
• .git/と.codex/は読み取り専用

推奨される安全対策

1. Gitチェックポイントの作成：Codexを実行する前にコミットを作成し、必要に応じてロールバックできるようにする
2. 承認モードの適切な選択：
   • 重要なデプロイメントには--suggest（Read Only）
   • 開発環境での通常タスクには--full-auto
3. 生成されたCI/CD設定のレビュー：本番環境向けの設定は必ず人間がレビュー
4. YOLOモードは慎重に：--yolo（--dangerously-bypass-approvals-and-sandbox）は、外部で隔離された環境でのみ使用

Codex Cloudとの連携

ターミナルからCodex Cloudタスクを操作することも可能です。

タスクのブラウズと実行

codex cloud

インタラクティブピッカーが開き、アクティブなタスクや完了したタスクを確認できます。

直接タスクを実行

codex cloud exec --env ENV_ID "オープンなバグを要約"

ベストオブN実行

codex cloud exec --env ENV_ID --attempts 3 "この問題を修正"

複数の解決策を生成させ、最も良いものを選択できます。

シェル補完の設定

タブ補完を有効にすると、コマンド入力が快適になります。

Bash

codex completion bash >> ~/.bashrc
source ~/.bashrc

Zsh

echo 'eval "$(codex completion zsh)"' >> ~/.zshrc
source ~/.zshrc

Fish

codex completion fish > ~/.config/fish/completions/codex.fish

トラブルシューティング

よくある問題と解決策

承認プロンプトがリセットされる

~/.codex/config.tomlのデフォルトモード設定を確認してください。プロファイルやコマンドラインフラグが競合している可能性があります。

Codexが頻繁に承認を求める

Read OnlyモードからAutoモードに切り替えてみてください：

/approvals auto

意図しない編集が行われる

Read Onlyモードに戻し、diffを手動でレビューしてください：

/approvals readonly

AGENTS.mdが読み込まれない

• ファイルが空でないことを確認
• codex statusでワークスペースルートを確認
• AGENTS.override.mdが上位ディレクトリにないか確認

デバッグ情報の収集

/feedback

問題報告時に必要なログや診断情報を収集できます。

実践的なワークフロー例

1. コードリファクタリング

# Read Onlyモードで開始
codex "この関数をリファクタリングする提案をして"

# 提案を確認
/diff

# 問題なければAutoモードに切り替えて適用
/approvals auto

2. ドキュメント生成

# AGENTS.mdを初期化
/init

# ドキュメント生成を依頼
codex "READMEとAPIドキュメントを更新して"

# 長い会話はcompactで整理
/compact

3. コードレビュー

# レビューを実行
/review

# 特定のファイルにフォーカス
codex "src/components/UserForm.tsxのセキュリティ問題をチェック"

4. テスト駆動開発

# フルオートモードで起動
codex --full-auto "テストを実行して、失敗したテストを修正"

まとめ

Codex CLIは、ターミナルで動作する強力なAIコーディングエージェントです。

主なメリット：

• オープンソースでRust製の高速動作
• 柔軟な承認・サンドボックス設定でセキュリティを確保
• AGENTS.mdによるプロジェクト固有のカスタマイズ
• セッションの継続機能で文脈を維持
• コードレビュー機能で品質を向上
• MCP連携で拡張性を確保

Claude CodeやCursorとの使い分け：

• 軽量なターミナル作業 → Codex CLI
• 長時間の非同期タスク → Codex Cloud
• エディタ統合重視 → Codex IDE拡張 or Cursor
• Anthropicモデル利用 → Claude Code

AIコーディングアシスタントは、もはや「使うかどうか」ではなく「どう使いこなすか」の時代です。Codex CLIをワークフローに組み込んで、開発効率を次のレベルに引き上げましょう。

---

参考リンク：

• Codex CLI公式ドキュメント
• GitHub – openai/codex
• Codex CLI Quickstart