【初心者向け】OpenAI Codex CLI 活用ガイド：AIエージェントの基本操作と設定

OpenAI Codexは、ソフトウェア開発に特化し、自然言語による指示でコードの生成、編集、テストまでを自律的に行うAIコーディングエージェントです。

最新モデルであるGPT-5-Codexは、GPT-5アーキテクチャをベースに、特にエージェント的なコーディングワークフロー向けに高度に最適化されており、従来のモデルを上回る精度と柔軟性を持っています。

本記事では、ターミナルで動作する軽量なオープンソースツール「Codex CLI」に焦点を当て、その導入方法から高度な設定までを解説します。

Codex の概要と利用プラン

Codex CLIとは

Codex CLI (Codex Command Line Interface) は、ターミナル内で動作するオープンソースのコーディングエージェントです。ユーザーのローカルマシン上でコードを読み込み、変更し、コマンドを実行できる能力を持ち、自然言語による指示でプログラミングタスクを自動化します。

Codexは、CLIだけでなく、VS CodeやCursorなどのIDE拡張機能や、GitHubとの連携、ChatGPTモバイルアプリなど、多様なインターフェースで利用可能です。

利用可能なプランと料金

Codexは、ChatGPTの有料プラン（Plus、Pro、Team、Edu、Enterprise）に標準で含まれています。
これらのプランに加入していれば、追加料金なしで利用できます。

また、プランの上限を超えた場合や、プランに加入していない場合は、OpenAIのAPIキーを設定することで従量課金モードで利用することも可能です。

インストールと認証

前提条件

Codex CLIを使用する際の推奨環境は以下の通りです。

• OS:
  macOSまたはLinuxが公式サポートされています。
  Windowsでは、WSL2 (Windows Subsystem for Linux 2) 経由での実行が推奨されています。
  （ただし、v0.22.0以降ではWSLなしでも動作可能という報告もあります）
• Node.js:
  バージョン22以降（LTS推奨）が必要です。
• Git:
  バージョン2.23以降が推奨されます（特に自動PRヘルパー機能を利用する場合）。

インストール方法

最も簡単なインストール方法は、npmまたはHomebrewを使用する方法です。

参考：OpenAI Developers Codex CLI

npm install -g @openai/codex
# または
brew install codex

Codex CLIは自動アップデートではないため、定期的に最新版に更新することが推奨されます。

認証と起動

1. 認証:
   初回起動時にブラウザが自動的に開き、ChatGPTアカウントでのログインが求められます。
   指示に従ってログインすれば連携が完了します。
   • もしAPIキーで課金したい場合は、export OPENAI_API_KEY=...を設定して起動します。
     ただし、ChatGPTプランを利用する場合は、既存のOPENAI_API_KEY環境変数を一旦外す必要があります。
2. 起動:
   ターミナルで codex コマンドを実行します。
3. ログインエラーの場合:
   codexと入力してもうまくいかずURLが表示される場合は、codex loginを実行すると解決する場合があります。

エージェントの基本操作とコマンド

Codex CLIは対話形式のセッションで動作します。

タスクの指示と実行

起動後、対話形式で自然言語を使ってCodexにタスクを指示します。

Codexはタスクを実行し、ファイル変更やコマンド実行を提案します。

• プロンプトの改行:
  入力中に改行したい場合は、Ctrl + J（またはShift + Enterなど）を押します。
• 推論のキャンセル:
  実行中の推論やタスクを中断したい場合は、Escキーを押します。

主要なスラッシュコマンド

CLIの対話セッション内では、スラッシュコマンド（/）を使って操作や設定の確認ができます。

承認モード（安全レベル）の設定補足

Codexは、ローカル環境のコードの読み書きやコマンド実行を行うため、セキュリティに配慮した承認モードを採用しています。/approvalsコマンドを実行することで、この承認モードを選択できます。

モード名 (公式用語)	ファイル編集	コマンド実行	説明
Read Only (Suggest)	提案のみ	提案のみ	最も安全なモード。変更や実行には必ずユーザーの承認が必要です。
Auto (Auto Edit)	自動実行	承認必須	ワークスペース内のファイル編集は自動で行いますが、シェルコマンドの実行には承認が必要です。
Full Access (Full Auto)	自動実行	自動実行	ファイル編集とコマンド実行の両方を自動で行います。開発スピードは上がりますが、リスクが高いため、慎重な使用が推奨されます。

注意点: Full Accessモードであっても、デフォルトではネットワークを使用するコマンドや作業ディレクトリ以外のファイルへの編集コマンドは実行されません。

AGENTS.mdと高度な設定

Codexエージェントの振る舞いをカスタマイズし、プロジェクトに最適化するための設定方法について解説します。

AGENTS.md の役割と利用

AGENTS.mdは、エージェントのためのREADMEとされており、コーディングエージェントに詳細なコンテキストと指示を与えるためのオープンなMarkdown形式のファイルです。

なぜ AGENTS.md が必要か

通常のREADME.mdが人間向けのクイックスタートや貢献ガイドラインであるのに対し、AGENTS.mdはビルド手順、テストコマンド、コーディング規約といった、AIエージェントが正確に作業するために必要な詳細な情報を補完します。

このファイルを独立させることで、エージェントに明確で予測可能な指示の場所を提供し、通常のREADMEを簡潔に保つことができます。

記述内容の例

AGENTS.mdに含めるセクションとして推奨されるものには、以下があります。

• プロジェクトの概要
• ビルドおよびテストコマンド (例: 依存関係のインストール pnpm install、テストの実行 pnpm test)。
• コードスタイルガイドライン (例: TypeScript厳密モード、シングルクォート、セミコロンなし)。
• 追加の指示 (コミットメッセージやプルリクエストのガイドライン、セキュリティ上の注意点など)。

AGENTS.md の作成と更新

• 自動作成:
  CLIの/initコマンドを実行すると、Codexが現在のリポジトリの状況を読み取り、AGENTS.mdファイルを自動的に作成（または既存のものを更新）してくれます。
• ネストされたファイル:
  大規模なモノレポでは、サブプロジェクトごとにAGENTS.mdを配置でき、エージェントはディレクトリツリー内で最も近いファイルを自動的に読み取り、その指示が優先されます。
• 互換性:
  このオープンフォーマットは、Codexだけでなく、Gemini CLIやAiderなど、多くのAIコーディングツールで共通して利用できます。

#AGENTS.md例
/initコマンドで作成

# Repository Guidelines

## プロジェクト構成とモジュール構成
- `codex cli/` はローカルストレージ対応ToDoアプリの静的ソースです。UIと状態管理は単一の `index.html` に集約されています。
- `vscode/` にはHTML整形用スクリプト（`modify.py`）、HTML抽出補助（`parse.py`）、CLIゲーム（`chess_animals.py`）があり、Webビュー向けアセットは `extension/` 配下に配置されています。
- `vscode-cli/` はCodex紹介ページのスタイルガイド、`test/web/` はUI検証用のミニマルなサンプル群、`kiji-codex-cli/` はスクリーンショットなどの参照アセット置き場です。

## 開発・ビルド・テストコマンド
- 静的ページの確認は対象ディレクトリで `python -m http.server 4173` を実行し、`http://localhost:4173` を開いてください。
- アニマル将棋CLIはリポジトリルートで `python vscode/chess_animals.py` を実行します。
- CSS差分適用は `python vscode/modify.py`、HTMLテキスト抽出は `pip install beautifulsoup4` 後に `python vscode/parse.py` を使います。

```bash
cd "codex cli"
python -m http.server 4173
```

## コーディングスタイルと命名規約
- HTML/CSS/JS は2スペースインデント、PythonはPEP 8準拠の4スペースを原則とします。
- JavaScriptの変数・関数は `camelCase`、CSSクラスは `kebab-case`、Pythonは `snake_case` を徹底してください。
- 静的アセットは `assets/` など既存の構造にしたがい、画像ファイル名は英小文字+ハイフンで統一します。

## テストガイドライン
- 主要ブラウザ（Chromium系/Firefox/Safari想定）でToDoアプリと紹介ページの表示崩れ、ローカルストレージの永続化を手動確認してください。
- Pythonスクリプトは `python -m compileall vscode` で構文検証し、`parse.py` はサンプルHTMLで抽出結果をレビューします。
- 将来的にUI検証を自動化する場合はPlaywrightまたはVitest導入を想定し、`test/` 配下に配置してください。

## コミット・Pull Requestガイドライン
- 既存履歴は未整備のため、`feat: ...` / `fix: ...` 形式のConventional Commits採用を推奨します。
- コミットは論理単位で分割し、生成物やスクリーンショットは別コミットとするかリリースノートに添付してください。
- PRでは概要、影響範囲、手動テスト結果、関連チケットIDを記載し、UI変更時は比較スクリーンショットを添えてください。

## セキュリティと設定メモ
- ローカルストレージへ保存するデータは平文です。個人情報やAPIキーは投入しないでください。
- 追加ライブラリを導入する場合は `package.json` ではなく、CDN利用か静的バンドルを検討し、依存関係をREADMEに追記してください。
- Python依存を増やす場合は `requirements.txt` を新規作成し、仮想環境利用手順をREADMEに追記することを推奨します。

エージェントの振る舞いのカスタマイズ

デフォルト設定の上書き: 共通の指示はホームディレクトリ内の~/.codex/AGENTS.mdに記述することで、すべての会話に自動で読み込ませることができます。

• 日本語対応の例: 日本語で簡潔かつ丁寧に回答してください この指示を~/.codex/AGENTS.mdに記述することで、デフォルトの応答を日本語に設定できます。

高度な動作設定（config.toml）

Codex CLIの永続的な動作設定は、~/.codex/config.tomlファイル（TOML形式）で行います。

• 推論レベルの恒常的な設定:
  GPT-5はタスクに応じて思考時間（推論レベル）を動的に調整しますが、デフォルトのmediumからより深く考えるhighに固定できます。 model_reasoning_effort = "high"
• 承認ポリシーの簡素化:
  ファイル変更の承認を減らす設定が可能です。 approval_policy = "on-failure" # 失敗時のみ確認 sandbox_mode = "workspace-write" # プロジェクトディレクトリ内のみ自動修正を許可
• MCP連携:
  config.toml内でMCP (Model Context Protocol) サーバーを設定することで、データベースやSlackなどの外部システムとの連携が可能になります。

#config.toml設定例

model = "gpt-5-codex"
model_reasoning_effort = "high" 
hide_agent_reasoning = true
network_access = true

安全に利用するための重要ポイント

Codexは非常に強力なツールですが、安全に使うためには以下の点を必ず守ってください。

Gitでの管理を徹底する

Codex CLIはコードを直接編集・削除する可能性があります。

必ずGitで管理されたプロジェクト内で実行し、重要な作業前には必ずコミットしておきましょう。

そうすることで、いつでも元の状態に戻せます。

出力結果を必ず確認・検証する

Codexは高度なコードを生成しますが、そのまま使うのは危険です。

最終的な品質保証は人間の責任です。提案を反映する前に、必ず開発者自身がレビューし、テストで動作を確認してください。

セキュリティとプライバシーへの配慮

Codexは隔離環境（サンドボックス）で動作するため、元のコードに直接影響を与えることなく生成や検証が可能です。

ただし、機密情報を含むコードを扱う場合には注意が必要です。

プロンプトや差分の一部がOpenAIのクラウドに送信されることを理解し、社内ポリシーに沿って慎重に取り扱いましょう。