Codex CLI を実務に組み込む2026年版ガイド

TL;DR

• Codex CLI は npm install -g @openai/codex でインストールし、OPENAI_API_KEY を設定するだけで即起動できます
• コードレビュー・テスト生成・リファクタリングを自然言語で指示でき、実務タスクを素早く自動化できます
• Claude Code との最大の違いは「sandboxed実行」と --approval-mode による安全制御で、単発タスクに強いポジションです

本記事は「Codex と Claude Code の使い分け2026」シリーズの第2回です。各ツールの使い分け方針については親記事をご覧ください。

Codex CLI とは何か

OpenAI は 2025 年 4 月、ターミナル上で動作するオープンソースのエージェント型ツール「Codex CLI」を公式リリースしました。GPT-4o・o3・o4-mini などのモデルを利用し、コードの変更・コマンド実行・ファイル操作をターミナルで完結させることができます。

ソースコードは GitHub（openai/codex） で公開されており、コミュニティによる拡張も活発です。

Codex CLI でできること

主な用途は以下の4つです。

1. コードレビュー — 変更差分を読んで問題点・改善案を自然言語で指摘
2. テスト生成 — 既存コードから単体テスト・統合テストの雛形を生成
3. リファクタリング — 命名・構造・パターンの改善を自動提案・適用
4. バグ修正・説明 — エラーメッセージから原因を特定し、修正案を提示

Claude Code との違い

同じく「AIコーディングエージェント」の Claude Code と Codex CLI はよく比較されます。選択基準を明確にするため、主要な差異を以下の表にまとめます。

使い分けの基本方針: 単発のコードレビュー・テスト生成など「1つのタスクを素早く完了させたい」場面では Codex CLI が、長期的なコンテキストを保持しながら複数ファイルを横断して作業する場面では Claude Code がそれぞれ強みを発揮します。

AIツール比較2026年版も合わせてご参照ください。

インストール手順

前提条件

• Node.js 22 以上（公式サイトよりインストール）
• OpenAI アカウントと API キー（platform.openai.com で取得）

Node.js バージョンを確認します。

node --version
# v22.x.x 以上であることを確認

グローバルインストール

npm 公式ドキュメントに従い、グローバルインストールを実行します。

npm install -g @openai/codex

macOS で権限エラーが出る場合: sudo npm install -g @openai/codex または、~/.npmrc で prefix を ~/.npm-global に変更してパスを通すことを推奨します（sudo に頼らない方法として公式推奨）。

インストール確認。

codex --version

npx を使って都度実行する方法もあります。

npx @openai/codex --help

認証設定

Codex CLI は OPENAI_API_KEY 環境変数を参照します。

方法1: 環境変数に直接設定

export OPENAI_API_KEY="sk-..."

方法2: .env ファイルに記載（プロジェクトルート）

# .env
OPENAI_API_KEY=sk-...

セキュリティ上、.env は必ず .gitignore に追加してください。

方法3: codex login コマンド

codex login

対話形式で API キーを入力し、~/.codex/auth.json に保存されます。チーム環境では環境変数が推奨です。

基本操作

起動方法

プロジェクトディレクトリで codex を起動します。

cd /path/to/your-project
codex

起動するとインタラクティブなチャットUIが表示されます。タスクを自然言語で入力するだけで、ファイルの読み取り・変更・コマンド実行を自律的に行います。

--approval-mode による実行制御

--approval-mode は Codex CLI の安全性を制御するもっとも重要なオプションです（経験則）。

# 変更を適用する前にすべて確認（推奨・デフォルト）
codex --approval-mode suggest

# すべてのタスクを自動実行（CI環境など）
codex --approval-mode full-auto

# 重要な操作のみ確認
codex --approval-mode manual

初めて使う場合は suggest モードから始めることを強く推奨します。

--model によるモデル指定

# コスト重視
codex --model gpt-4o-mini

# 精度重視（公式値: o3はコーディングベンチマーク最高クラス）
codex --model o3

# バランス型
codex --model gpt-4o

AGENTS.md によるコンテキスト設定

プロジェクトルートに AGENTS.md を置くと、Codex CLI が起動時にその内容を読み込みます。MCP プロトコルの設定と共通する概念で、エージェントに与える「文脈」を明示するものです。

# AGENTS.md（例）

## このリポジトリについて
- TypeScript + Node.js 22 の REST API サーバー
- テストは Vitest を使用
- コードスタイル: ESLint + Prettier 設定に従う

## 禁止事項
- `.env` ファイルへの直接書き込み禁止
- `main` ブランチへの直接プッシュ禁止

## 作業時の注意
- 変更後は必ず `pnpm test` を実行すること

これにより、毎回同じ前提をプロンプトに含める手間を省き、チーム全員が同じコンテキストで Codex CLI を使えます。

実務タスク3選

タスク1 — コードレビュー

codex --approval-mode suggest "このPRの変更点（git diff HEAD~1）をレビューして、問題点と改善提案を日本語で教えて"

あるいはファイルを指定して。

codex --approval-mode suggest "src/api/users.ts のセキュリティリスクとコード品質の問題を指摘して"

出力例:

【問題点】
1. Line 42: SQL クエリに未サニタイズの入力値が渡されています（SQLインジェクションリスク）
2. Line 67: エラーハンドリングが不足しています。catch ブロックが空です

【改善提案】
1. パラメータ化クエリまたは ORM を使用してください
2. catch ブロックにロギングとユーザーへのエラーレスポンスを追加してください

AIコードレビューの導入ガイドでは、組織的にレビュー知見を蓄積する方法も解説しています。

タスク2 — テスト生成

codex --approval-mode suggest "src/utils/validation.ts の関数それぞれに対して Vitest の単体テストを生成して、tests/utils/validation.test.ts に保存して"

Codex CLI はファイルの内容を読み取り、各関数のテストケース（正常系・異常系・境界値）を自動生成します。生成後は必ず内容を確認してください（経験則：自動生成テストは100%そのまま使えるわけではなく、ビジネスロジックの確認が必要）。

AIペアプログラミングのパターン集も参考になります。

タスク3 — リファクタリング

codex --approval-mode suggest "src/services/payment.ts をリファクタリングして。関数を小さく分割し、変数名をより説明的にして。変更はgit diffで確認したい"

--approval-mode suggest では変更適用前にdiffが表示されます。y で適用、n でスキップできます。

AI駆動の開発計画では、こうした自動化を開発フロー全体に組み込む方法を解説しています。

よくあるエラーと解決策

エラー1: Error: OPENAI_API_KEY is not set

原因: 環境変数が設定されていない。

# 確認
echo $OPENAI_API_KEY

# 設定（.bashrc / .zshrc に追記推奨）
export OPENAI_API_KEY="sk-..."

エラー2: Error: model not found

原因: モデル名が不正、またはそのモデルへのAPIアクセス権限がない。

# 正しいモデル名を確認（公式値: 2025年時点の主要モデル）
codex --model gpt-4o        # OK
codex --model gpt4o         # NG（ハイフンが必要）

エラー3: sandbox でコマンドが拒否される

原因: macOS の Apple Seatbelt により、sandbox 外のパスへのアクセスが制限される。

# sandbox を無効化（非推奨・テスト環境のみ）
codex --no-sandbox

# 推奨: AGENTS.md でアクセス許可パスを明示する

エラー4: EACCES: permission denied（グローバルインストール時）

原因: グローバル npm ディレクトリへの書き込み権限がない。

# npm のグローバルディレクトリをホームに変更
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @openai/codex

まとめ・初回タスク完走チェックリスト

以下のステップをすべて実行したら、Codex CLI の実務導入は完了です。

• Node.js 22 以上がインストールされている
• npm install -g @openai/codex でインストール完了
• OPENAI_API_KEY を環境変数に設定
• codex --version でバージョン確認
• プロジェクトに AGENTS.md を作成
• codex --approval-mode suggest "..." で最初のタスクを実行
• 出力結果を確認し、必要に応じて修正を適用

次のステップとして、AIペアプログラミングのパターン集で、Codex CLI を日常的な開発フローに組み込む具体例を確認することをおすすめします。

FAQ

Q1. Codex CLI のインストール方法は？

npm install -g @openai/codex でグローバルインストールします。Node.js 22 以上が必要です。npx @openai/codex で都度実行することも可能です。

Q2. Codex CLI と Claude Code はどう違いますか？

最大の違いは使用するAIモデルです。Codex CLI は OpenAI（GPT-4o / o3）、Claude Code は Anthropic（Claude Sonnet）を使用します。機能面では Codex CLI の --approval-mode と sandbox 実行が安全制御に優れており、単発タスク向けです。Claude Code は長期コンテキストとマルチファイル編集に強みがあります。

Q3. Codex CLI でコードレビューをするには？

codex --approval-mode suggest "このファイルのコードをレビューして" のように自然言語で指示します。git diff を使った差分レビューも可能です。

Q4. 認証方法は？

OPENAI_API_KEY 環境変数を設定するか、codex login コマンドで対話的に認証します。API キーは OpenAI プラットフォーム で発行できます。

Q5. テストを自動生成できますか？

はい。codex --approval-mode suggest "src/utils.ts のテストを生成して tests/ に保存して" のように指示すると、関数ごとの単体テストを生成します。生成後は内容を確認・修正してから使用してください。

本記事はシリーズ「Codex と Claude Code の使い分け2026」の一部です。タスク別の使い分け指針は親記事をご参照ください。

References

1. OpenAI Codex CLI 公式リリースブログ — 公式リリース
2. openai/codex GitHub リポジトリ — 公式ドキュメント・ソースコード
3. OpenAI プラットフォームドキュメント — APIキー・モデル情報
4. Node.js 公式ダウンロード — 前提条件のインストール
5. パッケージインストールドキュメント — インストール手順の詳細