今日から使える CodexCLI 実用ガイド

CodexCLI

Last updated at 2025-08-18Posted at 2025-08-11

はじめに

CodexCLI は、ターミナル環境で動作する軽量なコーディングエージェントです。単にインストールして終わりではなく、安全な慣らし運転から自動編集、そして CI 連携まで、段階的に習熟度を上げながら活用できるように設計されています。初日から無理なく使い始められる設計思想が特徴的です。(GitHub)

この記事の要点

インストール方法
最も手軽な方法は npm を使用することです：
```
npm i -g @openai/codex
codex
```
macOS をお使いの場合は Homebrew も選択肢となります：
```
brew install codex
codex
```
公式の GitHub Releases からは、各OS向けのスタンドアロンバイナリも配布されています。(GitHub, Homebrew Formulae)
認証方式（2パターン）
① Sign in with ChatGPT（Plus / Pro / Team）：最新モデル（例：gpt-5）を追加料金なしで使用できます。
② API キー（OPENAI_API_KEY）による従量課金方式。セッション中でも切り替えが可能です。(GitHub)
安全に開始するための段階的アプローチ
最初は**提案モード（Suggest）で動作を確認し、慣れてきたら自動編集（Auto Edit）へ移行、長時間の作業にはフルオート（Full Auto）**を適用するという段階的な習熟が推奨されます。各モードの詳細な仕様や切り替え方法は、公式ヘルプセンターに体系的にまとめられています。(OpenAI Help Center)
サンドボックスの実装
macOS では Seatbelt 技術、Linux では Landlock と seccomp を組み合わせたセキュリティ機構を採用しています。コンテナ環境では無効になる場合があるため、必要に応じて明示的な許可設定が必要です。(GitHub)
Windows での利用
WSL2 上で Linux 手順をそのまま適用する方法が最も効率的です。wsl --install コマンドでWSL2を導入し、VS Code の Remote - WSL 拡張機能を組み合わせることで、快適な開発環境を構築できます。WSL から Windows 側のブラウザを開く際は wslview ユーティリティが便利です。(Microsoft Learn, Visual Studio Code, WSL Utilities)

1. Codex / CodexCLI の技術的位置づけ

OpenAI のコーディング支援ツール群において、それぞれの役割は以下のように整理されます：

Codex Web：クラウドベースのエージェント。ブラウザインターフェースを通じて利用します。
CodexCLI：本記事で解説するローカル実行型のツール。ローカルファイルシステムのコードを直接読み取り、パッチ提案・ファイル編集・コマンド実行を行います。重要な点として、モデルへ送信されるのは「高レベルの文脈情報」であり、コードベース全体が無差別にアップロードされる設計ではありません。(GitHub, OpenAI Help Center)

2. 動作要件と推奨環境の詳細

項目	要件／推奨事項
OS	macOS 12以降 / Ubuntu 20.04以降 / Debian 10以降 / Windows 11（WSL2経由）
Git	バージョン 2.23以降（差分管理や PR 作成支援機能で活用）
メモリ	最小4GB（8GB以上を推奨）

これらの要件は、公式 README の System requirements セクションに基づいています。(GitHub)

3. インストール手順（3つの方法）

3.1 npm を使用する方法（最も簡単）

Node.js がインストールされている環境では、以下のコマンドで導入できます：

npm install -g @openai/codex
codex

3.2 Homebrew を使用する方法（macOS / Linux）

Homebrew が導入済みの環境では：

brew install codex
codex

3.3 公式バイナリを直接ダウンロードする方法（macOS / Linux）

# 例: Linux x86_64 アーキテクチャの場合
curl -L -o codex.tar.gz \
  https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz
tar xzf codex.tar.gz
mv codex-* codex && chmod +x codex
sudo mv codex /usr/local/bin/
codex

技術的な補足：sudo npm install -g は権限関連のトラブルを引き起こしやすいため、nvm（Node Version Manager）と組み合わせた npm -g の使用が推奨されます。これにより、ユーザー権限でのグローバルインストールが可能になります。(GitHub, Homebrew Formulae)

4. 認証メカニズム（ChatGPT 連携または API キー）

4.1 ChatGPT プランによるサインイン（推奨方法）

codex   # 起動後、"Sign in with ChatGPT" オプションを選択

Plus、Pro、または Team プランのアカウントを持っている場合、gpt-5 などの最新モデルに追加料金なしでアクセス可能です。過去に API キー課金で使用していた場合は、codex --version で バージョン 0.20.0 以上であることを確認し、codex login で再認証することで、スムーズに移行できます。(GitHub)

リモートサーバー（VPS等）での認証：ブラウザが利用できない環境では、**SSHポートフォワーディング（ssh -L 1455:localhost:1455）**を設定することで、ローカルマシンのブラウザ経由で認証を完了できます。(GitHub)

4.2 API キーによる認証（従量課金方式）

export OPENAI_API_KEY="sk-..."  # まずはシェルセッション限定で設定
codex

ChatGPT 経由でログイン済みの場合でも、セッション中に /logout コマンドを実行することで、API キー利用モードへ切り替えることができます。(GitHub)

5. 安全な導入のための段階的アプローチ

初めて CodexCLI を使用する際は、以下の段階的なアプローチを推奨します：

Git 管理下のリポジトリで codex を起動します（差分管理により安全性を確保）。
最初は Suggest（提案）モードで動作を観察します（すべての提案は都度承認が必要）。
動作に問題がないことを確認したら Auto Edit モードへ移行し、さらに長時間の作業では Full Auto モードを活用します。

各モードの詳細な定義と切り替え方法（--auto-edit / --full-auto フラグ、セッション中の /mode コマンド）は、公式ヘルプセンターに体系的にまとめられています。(OpenAI Help Center)

6. サンドボックスとモードの技術的詳細

6.1 3つの承認モードの技術仕様と使い分け

モード	技術的な動作	適用場面
Suggest（既定）	ファイル読み取りを行い、編集案やコマンド案を提示（実行には明示的な承認が必要）	安全な探索、コードレビュー、既存コードの理解
Auto Edit	ファイル編集は自動実行、コマンド実行時のみ承認を要求	大規模なリネーム、コード整形、一括置換作業
Full Auto	編集とコマンド実行を自律的に実行。カレントディレクトリ配下のサンドボックス内で動作、ネットワークは既定で無効	ビルドエラーの自動修復、プロトタイプの反復開発

これらのモードは内部的に approval_policy と sandbox_mode という2つのパラメータの組み合わせとして実装されています。(OpenAI Help Center, GitHub)

6.2 OS別のサンドボックス実装の技術詳細

各OSにおけるサンドボックス機構の実装は以下の通りです：

macOS：Apple の Seatbelt 技術（sandbox-exec コマンド経由）を使用
Linux：Landlock（ファイルシステムアクセス制御）と seccomp（システムコールフィルタリング）の組み合わせ
コンテナ環境（Docker等）：ホストOSやコンテナランタイムの設定によってはサンドボックスが無効になる場合があります。この場合、コンテナ側で適切な制約を設定するか、リスクを理解した上で --sandbox danger-full-access または --dangerously-bypass-approvals-and-sandbox オプションを使用します。(GitHub)

7. よく使用するコマンドの詳細

# 対話型UIを起動
codex

# 初期プロンプトを指定して起動
codex "fix lint errors in src/"

# 非対話モード（CI環境などで使用）
codex exec "explain utils.ts"

# 特定のモデルを指定（Completions API と同様の記法）
codex -m o3 "add unit tests to parser"

# 動作モードの切り替え
codex --auto-edit
codex --full-auto

より詳細な CLI リファレンスは、公式 README に記載されています。(GitHub)

8. 実践的な使用例（そのまま適用可能）

8.1 未知のリポジトリの構造を短時間で把握

git clone <repository-url>
cd <repository-name>
codex "このリポジトリの全体構造を分析し、アーキテクチャを要約してください。また、改善可能な点を5つ提案してください"

8.2 大規模な機械的編集作業（Auto Edit モード）

codex --auto-edit "src配下のすべての*.jsxファイルを*.tsxにリネームし、関連するimport文も同時に更新してください"

8.3 バグの再現から修正、テスト追加まで（Full Auto モード）

codex --full-auto "npm test で失敗しているテストケースを特定し、原因を修正した上で、回帰テストを追加してください"

9. コンテキスト拡張：AGENTS.md と config.toml の活用

9.1 `AGENTS.md`（プロジェクト固有の規約や知識の埋め込み）

CodexCLI は 複数の AGENTS.md ファイルを階層的にマージする仕組みを持っています：

~/.codex/AGENTS.md（ユーザー個人のグローバル設定）
リポジトリルートの AGENTS.md（プロジェクト全体の規約）
カレントディレクトリの AGENTS.md（特定機能やサブモジュール固有の規約）

# プロジェクト開発規約
- コーディング規約: ESLint + Prettier を strict モードで適用
- 例外処理: try-catch を使用する際は、必ず理由をコメントで明記
- テスト記述: given/when/then パターンに従って記述
- コミットメッセージ: Conventional Commits 形式を厳守

(GitHub)

9.2 `~/.codex/config.toml`（グローバル設定の例）

# 基本設定
model = "gpt-5"                      # 既定で使用するモデル
approval_policy = "on-request"       # 必要に応じて承認を求める
sandbox_mode = "workspace-write"     # 作業フォルダ内への書き込みを許可
disable_response_storage = true      # ZDR（Zero Data Retention）組織向け設定

# サンドボックスのネットワーク設定（必要に応じて）
[sandbox_workspace_write]
network_access = false               # ネットワークアクセスを無効化

技術的な注記：旧ドキュメントでは ask_for_approval / sandbox という表記も見られますが、現在は approval_policy / sandbox_mode の組み合わせによる、より細かい制御方式に統一されています。(GitHub)

10. MCP（Model Context Protocol）連携の技術仕様

~/.codex/config.toml の mcp_servers セクションに MCP サーバーを登録することで、外部ツールとの連携が可能です。この仕組みは Claude や Cursor の mcpServers 設定と概念的には類似していますが、TOML 形式であるためキー名が異なる点に注意が必要です。

[mcp_servers.example]
command = "npx"
args = ["-y", "your-mcp-server"]
env = { "API_KEY" = "your-api-key-value" }

さらに、codex mcp コマンドを使用することで、CodexCLI 自体を MCP サーバーとして起動する実験的機能も提供されています。(GitHub)

11. CI/CD パイプラインでの非対話的運用（GitHub Actions の例）

- name: Update changelog via Codex
  run: |
    npm install -g @openai/codex
    export OPENAI_API_KEY="${{ secrets.OPENAI_KEY }}"
    codex exec --full-auto "analyze recent commits and update CHANGELOG.md for the next release"

codex exec コマンドを使用することで、非対話的な自動化スクリプトとして組み込むことができます。(GitHub)

12. セキュリティとプライバシーに関する技術的考察

よくある誤解と実際の動作

ローカル実行の原則：ファイル操作やコマンド実行はすべてローカルマシン上で行われます。モデルに送信されるのは、プロンプトと必要最小限の高レベルコンテキスト情報のみです。(OpenAI Help Center)
ネットワークアクセスの制御：Full Auto モードでも、基本動作はカレントディレクトリ配下のサンドボックス内に制限され、ネットワークアクセスは既定で無効化されています。(OpenAI Help Center)
企業向けのZDR（Zero Data Retention）対応：組織のデータ保護ポリシーに準拠するため、disable_response_storage = true を設定することで、応答の保存を無効化できます。(GitHub)

13. トラブルシューティング（技術的な対処法）

ログイン認証の問題

codex --version で バージョン 0.20.0 以上であることを確認します。問題が継続する場合は、~/.codex/auth.json を削除してから codex login で再認証を行います。リモート環境では SSH ポートフォワーディング（ssh -L 1455:localhost:1455）を設定します。(GitHub)

Docker / WSL でのサンドボックス動作不良

ホストシステムまたはコンテナランタイムが Landlock / seccomp をサポートしているか確認します。サポートされていない場合は、コンテナ側で適切なセキュリティ制約を設定するか、リスクを理解した上で --sandbox danger-full-access オプションを使用します。(GitHub)

モード設定の混乱

起動時のフラグは --auto-edit / --full-auto を使用し、セッション中の切り替えは /mode コマンドで行います。(OpenAI Help Center)

バージョンアップデート

codex --upgrade コマンドで最新版への更新が可能です。(OpenAI Help Center)

14. Windows 環境での詳細なセットアップ手順（WSL2 経由）

技術的な推奨事項：WSL2 上に Linux 環境を構築し、その中で CodexCLI を動作させる方法が最も安定しています。エディタは VS Code（Remote - WSL 拡張）、実行は WSL ターミナル、認証URLは wslview を経由して Windows 側のブラウザで開く構成が効率的です。

14.1 WSL2 のインストール（Windows 11）

管理者権限の PowerShell で以下を実行：

wsl --install
# 既にインストール済みの場合は更新
wsl --update

詳細な手順は Microsoft の公式ドキュメントを参照してください。(Microsoft Learn)

14.2 基本的な開発ツールの導入（WSL内）

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl ca-certificates build-essential

14.3 Node.js を nvm 経由でインストール

curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
export NVM_DIR="$HOME/.nvm"; . "$NVM_DIR/nvm.sh"
nvm install --lts
node -v && npm -v

14.4 CodexCLI のインストールと起動確認

npm install -g @openai/codex
codex --version
codex