OpenAI Codex CLI:セットアップ完全ガイド (2026年版)
OpenAIのコマンドラインコーディングエージェントのインストール、設定、および使用方法
Hyperealで構築を始めよう
Kling、Flux、Sora、Veoなどに単一のAPIでアクセス。無料クレジットで開始、数百万規模まで拡張可能。
クレジットカード不要 • 10万人以上の開発者 • エンタープライズ対応
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 は以下の手順を実行します:
- テストスイートを実行して失敗を特定
- 失敗したテストファイルとソースファイルを読み取り
- 根本原因を分析
- ピンポイントで修正を適用
- テストを再実行して検証
例 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 |
コストを抑えるためのヒント
- プロンプトを具体的にする。 曖昧な指示はやり取りの回数を増やします。
- ほとんどのタスクに o4-mini を使用する。 コーディングタスクの90%を十分にこなせます。
- 大きなタスクを小さく分割する。 各タスクは新鮮なコンテキストで開始されます。
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 が速度、品質、コストの最適なバランスを提供します。
