Codex CLI入門 - ローカル環境でのAIコーディングエージェント

はじめに

OpenAI Codexには、ChatGPTのWebインターフェースからアクセスするクラウド版に加えて、ローカルのターミナルから直接利用できるCodex CLIが用意されています。Codex CLIは、Rustで構築されたオープンソースの軽量コーディングエージェントで、手元のマシン上でファイルの読み取り・編集・コマンド実行を行えます。

本記事では、Codex CLIのインストールから認証設定、基本的な使い方、そしてクラウド版との使い分けまでを解説します。日常の開発作業にCodex CLIを組み込み、AIアシスタントと対話しながら効率的にコーディングできるようになることを目指します。

Codex CLIとは

Codex CLIは、ターミナルから利用できるOpenAIのコーディングエージェントです。クラウド版Codexがリモートのサンドボックス環境でタスクを実行するのに対し、Codex CLIはローカルマシン上で直接動作します。

Codex CLIの特徴

特徴	説明
ローカル実行	手元のファイルシステムに直接アクセスし、編集やコマンド実行を行う
リアルタイム対話	対話形式でCodexとやり取りしながら作業を進められる
オープンソース	Apache-2.0ライセンスでGitHub上に公開されている
高速動作	Rustで実装されており、起動と応答が高速
サンドボックス保護	macOSのSeatbelt、LinuxのLandlockによるセキュリティ保護

クラウド版との違い

flowchart LR
    subgraph "Codex CLI（ローカル）"
        direction TB
        A1[ターミナルで起動] --> B1[ローカルファイルを操作]
        B1 --> C1[コマンドを実行]
        C1 --> D1[リアルタイムで結果確認]
    end
    
    subgraph "Codex Cloud（クラウド）"
        direction TB
        A2[ChatGPTから起動] --> B2[クラウドサンドボックスで実行]
        B2 --> C2[PRを自動作成]
        C2 --> D2[非同期で完了通知]
    end

観点	Codex CLI	Codex Cloud
実行環境	ローカルマシン	クラウドサンドボックス
操作方法	ターミナルコマンド	ChatGPT Webインターフェース
対話形式	リアルタイム	非同期（バックグラウンド実行）
GitHub連携	手動でコミット・プッシュ	PR自動作成
オフライン	不可（API接続が必要）	不可
複数タスク	1セッション1タスク	並列実行可能

前提条件

Codex CLIを利用するには、以下の環境が必要です。

要件	詳細
OS	macOS、Linux（Windowsは実験的サポート、WSL推奨）
Node.js	Node.js 18以降（npm経由でインストールする場合）
ChatGPTプラン	Plus/Pro/Business/Edu/Enterpriseのいずれか、またはAPIキー
Git	バージョン管理されたプロジェクトで最も効果を発揮

インストール

Codex CLIのインストール方法は複数用意されています。

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

Node.js環境がある場合、npmでグローバルインストールできます。

1

npm install -g @openai/codex

Homebrewでインストール（macOS）

macOSユーザーはHomebrewからもインストールできます。

1

brew install --cask codex

バイナリを直接ダウンロード

GitHubのリリースページから、プラットフォームに対応したバイナリを直接ダウンロードすることも可能です。

1
2


# GitHubリリースページ
https://github.com/openai/codex/releases/latest

インストールの確認

インストールが完了したら、バージョンを確認します。

1

codex --version

認証設定

Codex CLIを使用するには、OpenAIへの認証が必要です。認証方法は2種類あります。

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

ChatGPTのサブスクリプション（Plus/Pro/Business/Edu/Enterprise）を持っている場合、アカウントでログインするのがおすすめです。

1

codex

初回起動時、または未ログイン状態でcodexコマンドを実行すると、ログイン方法の選択画面が表示されます。「Sign in with ChatGPT」を選択すると、ブラウザが開いてOAuth認証フローが始まります。

sequenceDiagram
    participant User as ユーザー
    participant CLI as Codex CLI
    participant Browser as ブラウザ
    participant OpenAI as OpenAI

    User->>CLI: codexコマンドを実行
    CLI->>Browser: 認証ページを開く
    Browser->>OpenAI: ログイン情報を送信
    OpenAI->>Browser: アクセストークンを発行
    Browser->>CLI: トークンを返却
    CLI->>User: ログイン完了

認証情報は~/.codex/auth.jsonまたはOSの資格情報ストアに保存され、次回以降は自動的に再利用されます。

APIキーでログイン

OpenAI APIのキーを使用してログインすることも可能です。CI/CD環境やAPIの従量課金で利用したい場合に適しています。

1
2


# 環境変数からAPIキーを読み込んでログイン
printenv OPENAI_API_KEY | codex login --with-api-key

APIキーはOpenAIダッシュボードから取得できます。APIキーを使用する場合、利用料金はAPI料金に基づいて課金されます。

ヘッドレス環境での認証

SSHで接続したリモートサーバーなど、ブラウザが使えない環境では、デバイスコード認証を利用できます。

1

codex login --device-auth

表示されたURLをローカルマシンのブラウザで開き、ワンタイムコードを入力して認証を完了します。

ログイン状態の確認

現在のログイン状態を確認するには、以下のコマンドを実行します。

1

codex login status

使用可能なモデル

Codex CLIでは複数のモデルを選択できます。用途に応じて使い分けることで、パフォーマンスとコストを最適化できます。

推奨モデル

モデル	特徴	用途
gpt-5.2-codex	最も高度なコーディングモデル	複雑なリファクタリング、大規模な実装
gpt-5.1-codex-mini	高速で低コスト、制限内使用量が最大4倍	シンプルなタスク、頻繁な対話

その他のモデル

モデル	説明
gpt-5.1-codex-max	長時間のエージェントタスク向けに最適化
gpt-5.2	汎用的なエージェントタスク向け
gpt-5.1	コーディングとエージェントタスク向け（gpt-5.2の前世代）
gpt-5-codex	長時間タスク向け（gpt-5.1-codexの前世代）

モデルの指定方法

モデルは起動時のフラグで指定できます。

1
2
3
4
5


# 最新の高性能モデルを使用
codex -m gpt-5.2-codex

# 高速・低コストのミニモデルを使用
codex -m gpt-5.1-codex-mini

デフォルトモデルを設定するには、設定ファイル（~/.codex/config.toml）に記述します。

1

model = "gpt-5.2-codex"

セッション中にモデルを切り替えるには、/modelスラッシュコマンドを使用します。

/model gpt-5.1-codex-mini

基本的な使い方

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

最も基本的な使い方は、プロジェクトディレクトリでCodex CLIを起動することです。

1
2


cd your-project
codex

フルスクリーンのターミナルUI（TUI）が起動し、対話形式でCodexとやり取りできます。

プロンプトを指定して起動

起動時に直接プロンプトを渡すこともできます。

1

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

画像を入力として使用

スクリーンショットやデザイン仕様を入力として渡すことも可能です。

1
2
3
4


codex -i screenshot.png "このエラーを説明して"

# 複数の画像を渡す場合
codex --image img1.png,img2.jpg "これらの図を要約して"

セッションの再開

前回のセッションを続きから再開できます。

1
2
3
4
5
6
7
8


# セッション選択画面を開く
codex resume

# 最新のセッションを直接再開
codex resume --last

# 特定のセッションIDを指定
codex resume <SESSION_ID>

承認モードとサンドボックス

Codex CLIは、安全性を確保するために承認モードとサンドボックス機能を備えています。

承認モード

承認モードは、Codexがアクションを実行する前に確認を求めるタイミングを制御します。

モード	説明
Auto（デフォルト）	ワークスペース内のファイル読み書き・コマンド実行は自動承認、範囲外は確認を求める
Read-only	ファイルの読み取りのみ許可、変更やコマンド実行は承認が必要
Full Access	すべてのアクションを承認なしで実行（信頼できる環境でのみ使用）

セッション中に承認モードを変更するには、/approvalsスラッシュコマンドを使用します。

/approvals

コマンドラインで指定する場合は、--ask-for-approvalフラグを使用します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 常に承認を求める
codex --ask-for-approval untrusted

# 失敗時のみ承認を求める
codex --ask-for-approval on-failure

# リクエスト時のみ承認を求める
codex --ask-for-approval on-request

# 承認を求めない
codex --ask-for-approval never

サンドボックスモード

サンドボックスモードは、Codexが実行するコマンドのファイルシステムとネットワークへのアクセスを制限します。

モード	説明
read-only	読み取り専用アクセス
workspace-write	ワークスペース内への書き込みを許可
danger-full-access	すべてのアクセスを許可（危険）

1
2


# ワークスペースへの書き込みを許可
codex --sandbox workspace-write

フルオートモード

頻繁な確認なしで作業を進めたい場合は、--full-autoフラグが便利です。

1

codex --full-auto

このフラグは、--ask-for-approval on-requestと--sandbox workspace-writeを組み合わせたショートカットです。

便利なスラッシュコマンド

Codex CLIでは、スラッシュコマンドを使って特殊な操作を実行できます。

コマンド	説明
`/model`	使用するモデルを変更
`/approvals`	承認モードを変更
`/review`	コードレビューを実行
`/status`	現在のセッション状態と使用量を表示
`/fork`	現在のセッションを分岐して新しいスレッドを作成
`/exit`	セッションを終了

コードレビューの実行

/reviewコマンドを使用すると、ローカルでコードレビューを実行できます。

/review

以下のレビューオプションが表示されます。

Review against a base branch: ベースブランチとの差分をレビュー
Review uncommitted changes: ステージング済み・未ステージングの変更をレビュー
Review a commit: 特定のコミットをレビュー
Custom review instructions: カスタム指示でレビュー

設定ファイル

Codex CLIの動作は、設定ファイル（~/.codex/config.toml）でカスタマイズできます。

基本的な設定例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# デフォルトモデル
model = "gpt-5.2-codex"

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

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

# 推論の深さ（high/medium/low）
model_reasoning_effort = "high"

# 機能フラグ
[features]
web_search_request = true  # Web検索を有効化
undo = true                # Undoを有効化

設定の優先順位

設定は以下の優先順位で適用されます（上が最優先）。

CLIフラグ（--modelなど）
プロファイル値（--profileで指定）
config.tomlの値
組み込みのデフォルト値

非対話型モードでの実行

スクリプトやCI/CDパイプラインでCodex CLIを使用する場合は、codex execコマンドを使用します。

1
2
3
4
5
6
7
8


# 単一のタスクを実行
codex exec "CIの失敗を修正して"

# JSON形式で出力
codex exec --json "テストカバレッジを改善して"

# 最終メッセージをファイルに出力
codex exec -o result.txt "READMEを更新して"

フルオートモードと組み合わせることで、承認なしで自動実行できます。

1

codex exec --full-auto "リンターエラーを修正して"

クラウド版Codexとの連携

Codex CLIからクラウド版Codex（Codex Cloud）のタスクを操作することも可能です。

クラウドタスクの一覧表示

1

codex cloud list

クラウドタスクの実行

1

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

クラウドタスクの差分を適用

クラウドで実行されたタスクの結果をローカルに適用するには、codex applyコマンドを使用します。

1

codex apply <TASK_ID>

ユースケース別の使い分け

Codex CLIが適している場面

即座のフィードバックが必要な場合: リアルタイムで対話しながらコードを改善したい
小〜中規模のタスク: 単一ファイルの修正、関数の実装、バグ修正など
ローカル環境固有の作業: 環境設定、ローカルテストの実行など
実験的な作業: 複数のアプローチを試しながら最適解を探る

クラウド版Codexが適している場面

大規模なタスク: 複数ファイルにまたがるリファクタリング、新機能の実装
非同期での実行: バックグラウンドでタスクを実行し、完了を待つ
複数タスクの並列処理: 複数のIssueを同時に処理する
GitHub PRの自動作成: コードレビューフローに直接統合する

併用パターン

実際の開発では、両者を組み合わせて使用するのが効果的です。

flowchart TD
    A[開発タスク] --> B{タスクの性質}
    B -->|小規模・即座の対話| C[Codex CLI]
    B -->|大規模・非同期| D[Codex Cloud]
    C --> E[ローカルで編集・テスト]
    D --> F[PRを自動作成]
    E --> G[手動でコミット・プッシュ]
    F --> H[レビュー・マージ]
    G --> H

トラブルシューティング

認証エラーが発生する場合

1
2
3


# ログアウトして再認証
codex logout
codex login

Windowsで問題が発生する場合

WindowsではWSL（Windows Subsystem for Linux）の使用が推奨されています。

1
2
3
4


# WSL環境でCodexを実行
wsl
cd /mnt/c/your-project
codex

使用量制限に達した場合

使用量制限に達した場合は、gpt-5.1-codex-miniモデルに切り替えることで、約4倍の使用量で利用を継続できます。

1

codex -m gpt-5.1-codex-mini

または、ChatGPTクレジットを購入して使用量を拡張できます。

まとめ

Codex CLIは、ローカル環境でAIコーディングエージェントを活用するための強力なツールです。

npmまたはHomebrewで簡単にインストールできる
ChatGPTアカウントまたはAPIキーで認証し、すぐに利用開始できる
インタラクティブモードでリアルタイムに対話しながらコーディングできる
承認モードとサンドボックスでセキュリティを確保できる
クラウド版Codexと併用することで、タスクの性質に応じた最適なワークフローを構築できる

次の記事では、Codex CLIを既存の開発ワークフロー（シェルスクリプト、Git hook、CI/CD）に統合する実践的な方法を解説します。

はじめに#

Codex CLIとは#

Codex CLIの特徴#

クラウド版との違い#

前提条件#

インストール#

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

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

バイナリを直接ダウンロード#

インストールの確認#

認証設定#

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

APIキーでログイン#

ヘッドレス環境での認証#

ログイン状態の確認#

使用可能なモデル#

推奨モデル#

その他のモデル#

モデルの指定方法#

基本的な使い方#

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

プロンプトを指定して起動#

画像を入力として使用#

セッションの再開#

承認モードとサンドボックス#

承認モード#

サンドボックスモード#

フルオートモード#

便利なスラッシュコマンド#

コードレビューの実行#

設定ファイル#

基本的な設定例#

設定の優先順位#

非対話型モードでの実行#

クラウド版Codexとの連携#

クラウドタスクの一覧表示#

クラウドタスクの実行#

クラウドタスクの差分を適用#

ユースケース別の使い分け#

Codex CLIが適している場面#

クラウド版Codexが適している場面#

併用パターン#

トラブルシューティング#

認証エラーが発生する場合#

Windowsで問題が発生する場合#

使用量制限に達した場合#

まとめ#

参考リンク#