OpenAI Codex基礎 CLIエージェント入門

OpenAI Codexとは

Codex CLIはOpenAIが2025年にオープンソース公開したターミナルベースのコーディングエージェントです。自然言語で指示を出すと、GPT-4oやo3-miniが背後でコードを生成し、サンドボックス内で実行まで行います。IDEを開かず、ターミナルだけで開発作業を完結させる設計思想が根底にあります。

ChatGPTがブラウザ上の対話ツールであるのに対し、Codex CLIはローカルのファイルシステムに直接アクセスする点が決定的に異なります。コードの読み書き、テスト実行、git操作、ドキュメント生成まで、開発者がターミナルで行うあらゆる操作をAIが代行できるわけです。

%%{init:{'theme':'dark','themeVariables':{'primaryColor':'#00A5BF','primaryBorderColor':'#007A8F','primaryTextColor':'#e8e8e8','lineColor':'#00A5BF','secondaryColor':'#1a1a1a','background':'#141414','mainBkg':'#1a1a1a','nodeBorder':'#00A5BF'}}}%%
graph LR
  A["ユーザー指示
(自然言語)"] --> B["Codex CLI
ローカルPC"]
  B --> C["OpenAI API
GPT-4o / o3-mini"]
  C --> D["コード生成
コマンド生成"]
  D --> E["サンドボックス
隔離実行環境"]
  E --> F["実行結果
ファイル変更"]
  F -.->|フィードバック| B

インストールとバージョン確認

バージョン番号は更新されるため異なっていて問題ありません。コマンドが認識されればインストール完了です。

動作環境と料金

サンドボックス実行とは

Codex CLIの最大の特徴は、コマンド実行をサンドボックス(隔離環境)内で行うことです。ネットワークアクセスはデフォルトで遮断され、ファイルシステムもプロジェクトディレクトリに制限されます。仮にAIが危険なコマンドを生成しても、システム全体への影響を防げる設計になっています。

Claude Code vs Codex CLI

基本操作

Codex CLIの操作はシンプルで、codex "指示文" がすべての起点になります。ファイルの読み書き、コード生成、テスト実行、検索まで自然言語で指示するだけ。プログラミング言語の構文を覚える必要はありません。

自然言語での指示方法

指示は具体的に書くほど精度が上がります。「いい感じに」は通じません。何を、どのファイルに、どんな形式で、が伝わるかどうかで出力品質が決まります。

ファイルの読み書き

Codex CLIはプロジェクト内のファイルを読み取り、変更内容を差分(diff)として表示します。suggestモードでは変更の承認を求められ、auto-editモードではファイル変更は自動適用されます。

プロジェクト構造の理解

Codex CLIは起動時にカレントディレクトリのファイル構造を把握します。package.json、tsconfig.json、pyproject.tomlなどの設定ファイルがあれば技術スタックを自動認識し、適切なコードを生成できます。

実行モード

Codex CLIには3つの実行モードがあり、安全性と自動化度のバランスを選べます。チーム開発で他人のコードを触るときはsuggest、個人プロジェクトで速度を優先するならfull-auto、というように場面で使い分けるのが実践的です。

3つのモード比較

モードの指定方法

%%{init:{'theme':'dark','themeVariables':{'primaryColor':'#00A5BF','primaryBorderColor':'#007A8F','primaryTextColor':'#e8e8e8','lineColor':'#00A5BF','secondaryColor':'#1a1a1a','background':'#141414','mainBkg':'#1a1a1a','nodeBorder':'#00A5BF'}}}%%
flowchart TD
  START["タスクの性質は?"] --> Q1{"本番コードを直接変更する?"}
  Q1 -->|Yes| SUG["suggest
全ステップ手動確認"]
  Q1 -->|No| Q2{"シェルコマンドの
自動実行が必要?"}
  Q2 -->|No| AE["auto-edit
ファイルは自動、シェルは確認"]
  Q2 -->|Yes| Q3{"プロジェクトは
個人 or チーム?"}
  Q3 -->|個人| FA["full-auto
全自動(サンドボックス内)"]
  Q3 -->|チーム| AE

コマンドライン引数リファレンス

full-autoが安全な理由 -- サンドボックスの技術的な仕組み

full-autoモードではすべてのコマンドがサンドボックス内で実行されます。OSごとに異なる隔離技術が使われています。

ネットワーク遮断の仕組みを具体的に説明すると、LinuxではDockerコンテナ起動時にiptablesルールが自動設定されます。全てのoutbound通信をデフォルトDROPし、codex.tomlのallow_networkに列挙されたドメインのみACCEPTルールを追加する方式です。DNSも制御対象で、許可リスト外のドメインは名前解決すらできません。

ファイルシステムの隔離は、プロジェクトディレクトリをread-writeマウント、テンポラリ領域をtmpfsとしてマウントし、それ以外のパスへのアクセスを遮断します。仮にAIが rm -rf / を実行しても、サンドボックス内のファイルにしか影響しません。

• ネットワーク隔離 -- 外部への通信はデフォルトで全遮断。codex.tomlで許可リストを定義した場合のみ通信可能
• ファイルシステム制限 -- プロジェクトディレクトリ外への書き込みは不可
• プロセス制限 -- システムレベルの操作(sudoなど)は実行不可

AGENTS.mdとcodex.toml

Codex CLIにプロジェクト固有のルールを教えるには、AGENTS.mdとcodex.tomlの2つのファイルを使います。Claude CodeにおけるCLAUDE.mdと同じ役割。プロジェクトの技術スタック、コーディング規約、禁止事項をあらかじめ定義しておくことで、AIの出力品質が安定します。

AGENTS.md -- エージェント向け指示書

プロジェクトルートに置く Markdown ファイルです。Codex CLIはタスク実行時にこのファイルを自動的に読み込み、ルールに従ったコードを生成します。

AGENTS.mdの推奨構成

codex.toml -- Codex固有の設定

codex.tomlはCodex CLIの挙動をカスタマイズする設定ファイルです。モデル選択、サンドボックスの許可リスト、環境変数の注入などを定義します。

AGENTS.md vs CLAUDE.md

AGENTS.md vs CLAUDE.md -- 構文の具体的な違い

どちらもMarkdownファイルであることは同じですが、推奨される構成と各ツールの読み取り方に違いがあります。

テンプレートファイルはこちらからダウンロードできます。

Copilot/Claude Codeとの使い分け

CLIエージェントだけでも3つ(Codex CLI、Claude Code、Copilot CLI)、IDEエージェントを含めると5つ以上の選択肢があります。どれか1つに絞る必要はなく、タスクに応じた使い分けが合理的です。

3ツール詳細比較

%%{init:{'theme':'dark','themeVariables':{'primaryColor':'#00A5BF','primaryBorderColor':'#007A8F','primaryTextColor':'#e8e8e8','lineColor':'#00A5BF','secondaryColor':'#1a1a1a','background':'#141414','mainBkg':'#1a1a1a','nodeBorder':'#00A5BF'}}}%%
flowchart TD
  START["何をしたい?"] --> Q1{"IDE上でコード補完?"}
  Q1 -->|Yes| COP["GitHub Copilot"]
  Q1 -->|No| Q2{"ターミナルで自律的に
コード生成・実行?"}
  Q2 -->|Yes| Q3{"OpenAI API を
使いたい?"}
  Q2 -->|No| COP
  Q3 -->|Yes| CODEX["Codex CLI"]
  Q3 -->|Anthropic API| Q4{"MCP連携 or
大規模リファクタ?"}
  Q4 -->|Yes| CC["Claude Code"]
  Q4 -->|軽いタスク| CODEX

併用パターン

得意/不得意の具体例

判断シナリオ: このタスクにはどのツール?

3つの実務的なシナリオで、ツール選択の思考プロセスを追体験してみてください。

セキュリティ

サンドボックスが安全性の根幹だと説明しましたが、設定を誤れば穴が開きます。このセクションではサンドボックスの仕組みを深掘りし、ネットワーク制御、APIキー管理、full-autoモードのリスクと対策を具体的に扱います。

サンドボックスの仕組み

Codex CLIのサンドボックスは、codex.tomlで定義された設定に基づいてコンテナ環境を構築します。

ネットワークアクセス制御

full-autoモードでnpm installを実行したい場合、registry.npmjs.orgへのアクセスを許可する必要があります。許可リストに含まれないドメインへのアクセスはすべてブロックされます。

codex.toml サンドボックス設定の完全例

APIキー管理

• 環境変数で設定 -- export OPENAI_API_KEY=sk-... が推奨。.envファイルの使用も可
• .envファイルはgitignore必須 -- .gitignore に .env を必ず含める
• コード内にハードコーディングしない -- AGENTS.mdの禁止事項にも明記する
• キーのローテーション -- 定期的にキーを再生成し、古いキーを失効させる

full-autoモードのリスクと対策

チェックリストをダウンロードできます。

実践ワークフロー

Codex CLIを実務で使う場面を3つのワークフローに絞って紹介します。レガシーコードのリファクタリング、テスト自動生成、ドキュメント自動生成。いずれも日常的に発生するタスクで、Codex CLIの効果を体感しやすいものを選びました。

ワークフロー1: レガシーコードのリファクタリング

古いJavaScriptのコードをモダンなTypeScriptに書き換える。手作業だと数時間かかる変換作業を、Codex CLIなら指示1回で処理できます。

ワークフロー2: テスト自動生成

既存コードに対してユニットテストを一括生成します。正常系・異常系・エッジケースを指定するのがポイント。

ワークフロー3: ドキュメント自動生成

ソースコードからAPIドキュメントやREADMEを自動生成します。JSDocコメントの追加も含めて指示できます。

トレンド

Codex CLIは2025年のオープンソース公開から急速に進化しています。単体ツールとしての改善だけでなく、OpenAIのエージェントプラットフォーム全体の中での位置づけが変わりつつあります。

OpenAI Agent Platform

OpenAIは2025年からエージェント構築のためのプラットフォームを整備し始めました。Codex CLIはその中の「開発者向けローカルエージェント」という位置づけです。Responses APIを介してより高度なタスク分解やツール呼び出しが可能になりつつあります。

Codexの進化ロードマップ

Responses API連携

OpenAIのResponses APIは、従来のChat Completions APIを拡張したもので、エージェント向けのツール呼び出し機能を標準化しています。Codex CLIの内部もこのAPIを活用しており、将来的にはカスタムツールの定義や外部サービス連携がResponses API経由で統一される見通しです。

マルチエージェント対応の展望

複数のCodexエージェントが協調して作業するシナリオが研究されています。例えば、フロントエンド担当エージェントとバックエンド担当エージェントが分業し、APIの整合性を保ちながら並列でコードを生成する、といった使い方。OpenAIのAgents SDKがこの基盤を提供しつつあります。

総合ハンズオン: CodexでREST APIサーバーを一気に構築

このコースで学んだ全知識を統合し、Codex CLIだけでREST APIサーバーをゼロから構築します。AGENTS.md設計から始めて、プロジェクト初期化、API実装、テスト生成、ドキュメント生成、動作確認までの6ステップを60分で完了させてください。

ゴール

書籍管理APIを構築します。以下の機能を持つExpressサーバーを、Codex CLIの操作だけで作り上げてください。

• GET /books -- 書籍一覧の取得
• GET /books/:id -- 特定書籍の取得
• POST /books -- 書籍の登録
• PUT /books/:id -- 書籍の更新
• DELETE /books/:id -- 書籍の削除