OpenAI Codex CLI：セットアップ完全ガイド (2026年版)

OpenAI Codex CLI: 2026年版完全セットアップガイド

OpenAIの Codex CLI は、コードベースの読み取り、ファイルの作成・編集、シェルコマンドの実行、そしてプログラミングタスクの反復的な解決を可能にするコマンドラインAIコーディングエージェントです。ターミナルに常駐するAIペアプログラマーだと考えてください。IDEベースのツールとは異なり、Codex CLI はテキストインターフェースを通じて動作するため、高速でスクリプト化が可能であり、SSH越しでも動作します。

このガイドでは、インストールから高度な使用パターンまで、すべてを網羅しています。

Codex CLIとは？

Codex CLI は、OpenAIが公開しているオープンソースのターミナル型コーディングエージェントです。OpenAIのモデル（主に o4-mini や GPT-4o）を使用してコードベースを理解し、マルチステップのタスクを実行します。主な機能は以下の通りです：

• ファイルの読み書き -- プロジェクト内をナビゲートし、ファイルを修正できます
• シェルコマンドの実行 -- テストの実行、パッケージのインストール、ビルドコマンドの実行が可能です
• マルチステップの推論 -- 複数のファイルにわたる複雑なタスクを計画し、実行します
• サンドボックス実行 -- 安全のため、コマンドはサンドボックス環境で実行されます
• 会話コンテキスト -- セッション全体を通じてコンテキストを維持します

前提条件

Codex CLI をインストールする前に、以下が準備されていることを確認してください：

要件	最小バージョン	確認コマンド
Node.js	22+	node --version
npm	9+	npm --version
Git	2.0+	git --version
OpenAI API key	--	platform.openai.com/api-keys

インストール

npm経由でインストール

npm install -g @openai/codex

インストールの確認

codex --version

APIキーの設定

Codex CLI には OpenAI API key が必要です。環境変数として設定してください：

# シェルプロファイル（~/.bashrc, ~/.zshrc など）に追加
export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"

シェルをリロードします：

source ~/.zshrc  # または ~/.bashrc

キーが設定されているか確認します：

echo $OPENAI_API_KEY

基本的な使い方

インタラクティブモード

プロジェクトディレクトリで Codex CLI をインタラクティブモードで起動します：

cd /path/to/your/project
codex

プロンプトが表示されるので、自然言語で指示を入力します：

> Fix the failing tests in the auth module

Codex はテストの失敗を分析し、関連ファイルを読み取り、修正案を提示します。

ワンショットモード

インタラクティブモードに入らずに単一の指示を実行します：

codex "add input validation to the signup endpoint"

パイプ入力

分析のためにコンテンツを Codex にパイプします：

cat error.log | codex "explain these errors and suggest fixes"
git diff HEAD~3 | codex "write a changelog entry for these changes"

設定

設定ファイル

~/.codex/config.json に設定ファイルを作成します：

{
  "model": "o4-mini",
  "approval_mode": "suggest",
  "sandbox": "docker"
}

プロジェクトレベルの設定

プロジェクトのルートに codex.md ファイルを作成し、Codex にプロジェクトのコンテキストを提供します：

# Project: MyApp

## Tech Stack
- TypeScript, React, Next.js
- PostgreSQL with Prisma ORM
- Tailwind CSS

## Conventions
- Use functional components with hooks
- Use `pnpm` as the package manager
- Tests go in `__tests__/` directories next to source files
- Use kebab-case for file names

## Important
- Never modify files in the `migrations/` directory directly
- Always run `pnpm test` after making changes
- Environment variables are in `.env.local` (do not commit)

Codex はこのファイルを自動的に読み取り、すべてのやり取りのコンテキストとして使用します。

承認モード

Codex CLI には、エージェントの自律性を制御する3つの承認モードがあります：

モード	ファイル編集	シェルコマンド	最適な用途
suggest	承認が必要	承認が必要	学習、レビュー
auto-edit	自動	承認が必要	信頼できるファイル変更
full-auto	自動	自動	スクリプティング、CIパイプライン

起動時にモードを設定できます：

# suggest モード（最も安全、デフォルト）
codex --approval-mode suggest "refactor the auth module"

# auto-edit モード（ファイル変更は承認、コマンドは確認）
codex --approval-mode auto-edit "add unit tests for the User model"

# full-auto モード（すべて自動承認）
codex --approval-mode full-auto "fix all ESLint errors"

実践的な例

例 1: 失敗しているテストの修正

codex "run the tests, identify failures, and fix them"

Codex は以下の手順を実行します：

1. テストスイートを実行して失敗を特定
2. 失敗したテストファイルとソースファイルを読み取り
3. 根本原因を分析
4. ピンポイントで修正を適用
5. テストを再実行して検証

例 2: 新機能の追加

codex "add a rate limiting middleware to the Express API using express-rate-limit. \
Limit to 100 requests per 15 minutes per IP. Add tests."

例 3: コードのリファクタリング

codex "refactor the database queries in src/services/ to use the repository pattern. \
Keep the existing tests passing."

例 4: コードレビュー

git diff main | codex "review this diff for bugs, security issues, and style problems"

例 5: ドキュメント作成

codex "generate JSDoc comments for all exported functions in src/utils/"

例 6: デバッグ

codex "the /api/users endpoint returns 500 when the email contains a plus sign. \
Find and fix the bug."

高度な使用法

CI/CDでの利用

Codex CLI は、CI/CDパイプライン用の非インタラクティブモードで実行できます：

# .github/workflows/codex-fix.yml
name: Auto-fix lint errors
on:
  push:
    branches: [main]

jobs:
  fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm install -g @openai/codex
      - run: codex --approval-mode full-auto "fix all ESLint errors and format with Prettier"
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      - run: git diff
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "fix: auto-fix lint errors via Codex CLI"

カスタムシステムプロンプト

専門的なタスクのためにデフォルトのシステムプロンプトを上書きします：

codex --system-prompt "You are a security auditor. Review code for vulnerabilities only." \
  "audit the authentication flow"

モデルの選択

タスクの複雑さに応じてモデルを選択します：

# 高速で安価なタスク
codex --model o4-mini "fix the typo in the README"

# 複雑な推論タスク
codex --model o3 "redesign the caching layer to handle cache stampedes"

サンドボックスのオプション

Codex はさまざまなサンドボックス戦略をサポートしています：

# Docker サンドボックス（full-auto モードに推奨）
codex --sandbox docker "install dependencies and run the test suite"

# ネットワーク無効化サンドボックス
codex --sandbox network-disabled "refactor the parser module"

# サンドボックスなし（注意して使用してください）
codex --sandbox none "run the deployment script"

Codex CLI と他のCLIツールの比較

機能	Codex CLI	Claude Code	Aider
プロバイダー	OpenAI	Anthropic	マルチプロバイダー
デフォルトモデル	o4-mini	Claude Sonnet	設定可能
ファイル編集	可能	可能	可能
シェルコマンド	可能（サンドボックス）	可能	限定的
承認モード	3つのモード	ツールごと	自動/手動
オープンソース	はい	いいえ	はい
MCP サポート	いいえ	はい	いいえ
Git 連携	基本的	高度	高度
料金	API利用料	API利用料	無料 (BYOK)

コスト管理

Codex CLI の料金は OpenAI API のトークン使用量に基づきます。以下は概算のコストガイドです：

タスクタイプ	推定コスト	モデル
単純な修正 (1-2 ファイル)	$0.01-0.05	o4-mini
機能追加 (3-5 ファイル)	$0.05-0.20	o4-mini
複雑なリファクタリング (10+ ファイル)	$0.20-1.00	o4-mini
アーキテクチャの再設計	$1.00-5.00	o3

コストを抑えるためのヒント

1. プロンプトを具体的にする。 曖昧な指示はやり取りの回数を増やします。
2. ほとんどのタスクに o4-mini を使用する。 コーディングタスクの90%を十分にこなせます。
3. 大きなタスクを小さく分割する。 各タスクは新鮮なコンテキストで開始されます。
4. codex.md ファイルを活用する。 適切なプロジェクトコンテキストは、探索的な読み取りを減らします。

トラブルシューティング

"Command not found: codex"

# インストールされているか確認
npm list -g @openai/codex

# 再インストール
npm install -g @openai/codex

# PATHを確認
echo $PATH

"Invalid API key"

# キーを検証
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  | head -c 200

Codex が誤った変更を行う場合

• suggest モードを使用し、適用前にレビューできるようにします。
• プロジェクトの codex.md ファイルに詳細なコンテキストを追加します。
• 指示をより具体的にします。
• 複雑なタスクを、小さく焦点の絞られたステップに分割します。

Docker サンドボックスの問題

# Dockerが起動しているか確認
docker ps

# Codex サンドボックスイメージをプル
docker pull openai/codex-sandbox:latest

AIを活用したアプリケーションの構築

Codex CLI はコードを書くのに優れていますが、もしアプリケーションで画像、動画、音声、あるいはアバターを生成する必要がある場合は、コードと並行してメディア生成APIが必要になるでしょう。Hypereal AI は、Codex CLI で構築されたプロジェクトに統合できるAIメディア生成用の統一APIを提供しており、インテリジェントなコード生成とAIパワーによるメディア作成の両方を一つのワークフローで実現できます。

まとめ

OpenAI Codex CLI は強力なターミナルベースのコーディングエージェントです。npm install -g @openai/codex でインストールし、OPENAI_API_KEY を設定、プロジェクトに codex.md ファイルを作成してコンテキストを提供しましょう。学習時は suggest モード、信頼できる変更には auto-edit、スクリプトやCIパイプラインには full-auto を使用してください。ほとんどのタスクにおいて、o4-mini が速度、品質、コストの最適なバランスを提供します。