ホーム→
ブログ記事一覧→
【2025年版】OpenAI Codex CLI完全ガイド｜Mac/Windows環境別インストールから実践まで7つの活用例

【2025年版】OpenAI Codex CLI完全ガイド｜Mac/Windows環境別インストールから実践まで7つの活用例

公開日 2025年11月20日(木)

最終更新日 2025年11月20日(木)

要約

OpenAI Codex CLIは、ターミナルから実行できるローカル型AIコーディングエージェントである。自然言語での指示だけでなく、スクリーンショットや手書きスケッチからもコードを生成できる点が特徴だ。本記事では、Mac/Windows環境別のインストール手順、3つの承認モード、7つの実践例、トラブルシューティングまで包括的に解説する。

対象読者: プログラミング初心者〜中級者、AIコーディングツールに興味がある開発者

検証環境: Node.js 22以上、macOS 12+/Windows 11（WSL2）、ChatGPT Plus以上のプラン（2025年11月時点）

この記事を読むことで得られるメリット

この記事を読むことで以下のことが分かる:

OpenAI Codex CLIの特徴と他のツールとの違い
Mac/Windows環境別の詳細なインストール手順
3つの承認モード（Suggest/Auto-Edit/Full-Auto）の使い分け
ToDoアプリ作成からセキュリティチェックまで7つの実践例
よくあるエラー5つとWindows WSL特有の注意点
CI/CD統合やMCP連携などの応用的な使い方

この記事を読むのにかかる時間

約15分

環境

macOS 12+ または Windows 11（WSL2経由）
Node.js 22以上（LTS推奨）
ChatGPT Plus/Pro/Business/Edu/Enterprise アカウント

Codex CLIとは？

Codex CLIは、OpenAIが開発したローカル実行型のAIコーディングエージェントである。主な特徴は以下の通りだ：

ターミナルベース: コマンドラインから直接操作
マルチモーダル対応: テキスト、画像（スクリーンショット、手書きスケッチ）に対応
オープンソース: Rustで実装され、GitHubで公開
高速: Rust実装による高速な動作
セキュリティ重視: ローカル実行で最小限の情報のみ送信
柔軟なモデル選択: GPT-5-Codex、GPT-5、o3、o4-miniなど

公式リソース

公式ドキュメント: https://developers.openai.com/codex/cli/
GitHubリポジトリ: https://github.com/openai/codex
Quickstart: https://developers.openai.com/codex/quickstart/

前提条件

Codex CLIを使用するには、以下の環境が必要である：

必須要件

項目	要件
Node.js	バージョン22以上（LTS推奨）
OS	macOS 12+、Ubuntu 20.04+、Debian 10+、Windows 11（WSL2経由）
アカウント	ChatGPT Plus/Pro/Business/Edu/Enterprise または OpenAI API キー
メモリ	最小4GB（推奨8GB）

オプション

Git: バージョン2.23以上（変更管理用）
WSL2: Windows環境の場合は必須

料金について

ChatGPT Plus/Pro等: 月額約20ドル〜（追加料金なしでCodex CLI利用可）
API キー: 従量課金制（gpt-5-codexモデルの料金が適用）
無料枠: なし（ChatGPT無料プランでは利用不可）

インストール方法

Mac環境でのインストール

Macでは3つのインストール方法が利用可能である。

方法1: npm（推奨）

# Node.jsバージョンを確認
node -v
npm -v

# Codex CLIをグローバルインストール
npm install -g @openai/codex

# 起動確認
codex


             _,+=+==+=+,_
         _+/*|._/|/\||;|+/*+_
       ,;*;~\**`    `"*\**+__+,
      ;*~**"            ,,|||_*\
     \|~/'            ,_/|=|./;'|
    \|*/`           ,~/|;^/` \|\=|
   |+*\/           ~+|\*/'    ~|/|
   ||=|`           |\|~^\     |^|"|
   ||,", +~==;;;=++_\*|_!\,   _|;"!
   ^|= *_\\,!/,"~//|  \*;_"|,,!/\=
    \\\_| """""**"`    `:*+_///",`
     \*\_\,               _*,"|,'
      '"+; ++_         _.*,"*_/
        ':*+,"*~;=+;;/=*""',*
           "~"~_;___-=_.=*`

方法2: Homebrew

# Homebrewでインストール
brew install codex

# 起動確認
codex

方法3: mise（開発環境管理ツール使用時）

mise use -g codex
codex

Windows環境でのインストール（WSL2経由）

Windows環境では、WSL2（Windows Subsystem for Linux 2）を使用する。ネイティブWindowsは実験的サポートのため、WSL2の使用を強く推奨する。

Step 1: WSL2のインストール

管理者権限のPowerShellで実行：

# WSL2をインストール
wsl --install

# 再起動後、WSLバージョンを確認
wsl -l -v

# WSL2でない場合は変更
wsl --set-version Ubuntu 2

Step 2: WSL内でのNode.jsとCodex CLIインストール

WSLターミナルを開き、以下を実行：

# nvmのインストール
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

# ターミナルを再起動、またはsourceで読み込み
source ~/.bashrc

# Node.js 22をインストール
nvm install 22
nvm use 22

# Node.jsバージョン確認
node -v

# Codex CLIのインストール
npm install -g @openai/codex

# 起動確認
codex

Step 3: VS Code統合設定（オプション）

VS Codeの設定ファイル（settings.json）に以下を追加：

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

初回認証

初回起動時に認証が必要である。以下の方法がある：

方法1: ChatGPTアカウントでサインイン（推奨）

codex

起動後、ブラウザが開きChatGPTアカウントでログインする。

方法2: API キーで認証

# 環境変数に設定
export OPENAI_API_KEY="your-api-key-here"

# またはログインコマンドを使用
codex login --api-key

.envファイルを作業ディレクトリに配置する方法も可能である：

echo "OPENAI_API_KEY=your-api-key-here" > .env

初回のみの確認

注意書き読んでEnter

  Before you start:

  Decide how much autonomy you want to grant Codex
  For more details see the Codex docs

  Codex can make mistakes
  Review the code it writes and commands it runs

  Powered by your ChatGPT account
  Uses your plan's rate limits and training data
preferences

  Press Enter to continue

Codexがファイル編集などを行う際に許可を必要とするか選択

Welcome to Codex, OpenAI's command-line coding agent

✓ Signed in with your ChatGPT account

> You are running Codex in /Users/・・・

  Since this folder is version controlled, you may wish to allow Codex to work in this
  folder without asking for approval.

› 1. Yes, allow Codex to work in this folder without asking for approval
  2. No, ask me to approve edits and commands

設定完了

╭─────────────────────────────────────────────╮
│ >_ OpenAI Codex (v0.60.1)                   │
│                                             │
│ model:     gpt-5.1-codex   /model to change │
│ directory: ~/git/tmp                        │
╰─────────────────────────────────────────────╯

基本的な使い方

起動方法

対話型モード（デフォルト）

codex

インタラクティブなターミナルUIが起動し、対話的にコーディングを進められる。

非対話型実行（execコマンド）

codex exec "タスクの説明"
# または短縮形
codex e "タスクの説明"

単発のタスク実行に便利である。

プロンプト直接指定

codex "Reactでカウンターアプリを作成して"

基本コマンド

セッション内で使用できる主なコマンド：

コマンド	説明
`/init`	プロジェクト理解のための初期化（AGENTS.md生成）
`/model`	AIモデル切り替え
`/mode`	承認モード切り替え
`/compact`	会話履歴を要約してトークン節約
`/new`	新しいセッション開始
`/quit`	終了
`/status`	使用統計の表示
`/mcp`	有効なMCPサーバー確認

3つの承認モード

Codex CLIには3つの承認モードがある：

1. Suggest（デフォルト）

動作: 読み取り専用、すべての変更を確認してから適用
用途: 最も安全、初心者におすすめ
特徴: コード変更・コマンド実行すべてに承認が必要

2. Auto-Edit

動作: ファイル編集は自動、コマンド実行は承認必要
用途: ファイル編集を信頼できる場合
特徴: 効率的だが、破壊的なコマンドは手動承認

3. Full-Auto

動作: 完全自動化
用途: 信頼できる簡単なタスク、CI/CD環境
特徴: すべて自動実行、注意が必要

承認モードの切り替え：

# セッション内で切り替え
/mode

# 起動時に指定
codex --mode auto-edit

プロジェクト初期化

新しいプロジェクトで作業を始める場合、まず初期化を実行する：

cd your-project
codex
/init

これにより、プロジェクトのコンテキストを理解するためのAGENTS.mdファイルが生成される。

実践例

例1: ToDoアプリの作成

最もシンプルな例として、ToDoアプリを作成してみる：

codex "ToDoアプリを作成して。React + TypeScript + Tailwind CSSを使用してください"

Codex CLIは以下を自動的に行う：

プロジェクト構造の作成
必要なパッケージのインストール
コンポーネントの実装
スタイリングの適用

例2: テスト自動生成

既存のコードにテストを追加：

codex "すべての関数にユニットテストを追加して。Jestを使用してください"

例3: README自動生成

プロジェクトのREADMEを自動作成：

codex "このプロジェクトのREADMEを自動生成して。関数一覧、パラメータ説明、使用例を含めてください"

例4: セキュリティチェック

セキュリティ脆弱性を検索：

codex "セキュリティ脆弱性を検索し、レビュー報告書を作成してください"

例5: 画像からコード生成（マルチモーダル）

手書きのスケッチやスクリーンショットからコードを生成：

codex
# プロンプト: "添付した手書きスケッチから、モダンでシックな2カラムレイアウトのブログサイトを作成してください"
# 画像をドラッグ＆ドロップで添付

例6: リファクタリング

既存コードの改善：

codex "ダッシュボードコンポーネントをReact Hooksにリファクタリングして"

例7: マイグレーション生成

データベーススキーマの変更：

codex "ユーザーテーブルにemailカラムを追加するマイグレーションを生成して"

主要機能の詳細

コードレビュー機能

コミット前に別のエージェントがコードをレビューする機能である：

codex "このコードをレビューして、改善点を提案してください"

自動的に以下をチェック：

セキュリティ脆弱性
パフォーマンスの問題
コーディング規約違反
潜在的なバグ

Webサーチ機能

最新情報を検索しながらコードを生成する。

設定ファイル（~/.codex/config.toml）で有効化：

[tools]
web_search = true

または起動時フラグ：

codex --search "最新のReact 19の機能を使ってコンポーネント作成"

モデル切り替え

タスクに応じてAIモデルを切り替えられる：

# 起動時に指定
codex --model gpt-5

# セッション内で切り替え
/model

利用可能なモデル：

GPT-5-Codex: コーディング特化（デフォルト）
GPT-5: 深い分析が必要な場合
o3、o4-mini: 推論モデル
GPT-4o: 汎用モデル

MCP（Model Context Protocol）連携

第三者ツールとの連携機能である。

MCPサーバーの追加

# CLIコマンドで追加
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 確認
codex mcp

設定ファイルで追加

~/.codex/config.tomlを編集：

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.playwright]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-playwright"]

推奨MCPサーバー

Context7: 最新の開発者ドキュメントアクセス
Figma: デザインツール連携
Playwright: ブラウザ自動化
GitHub: GitHubリポジトリ操作
Sentry: エラー追跡

スクリプト実行（CI/CD統合）

繰り返しワークフローを自動化：

# JSONL形式で結果をストリーミング出力
codex exec --output jsonl "タスクの説明"

GitHub Actions統合例：

- name: Update changelog via Codex
  run: |
    npm install -g @openai/codex
    export OPENAI_API_KEY="${{ secrets.OPENAI_KEY }}"
    codex exec -a auto-edit --quiet "update CHANGELOG for next release"

設定のカスタマイズ

設定ファイルの場所

~/.codex/
├── config.toml      # グローバル設定
├── AGENTS.md        # 全会話に反映される指示
└── sessions/        # セッション履歴

推奨設定例（`~/.codex/config.toml`）

# モデル設定
model = "gpt-5-codex"
model_reasoning_effort = "high"

# サンドボックス設定
sandbox_mode = "workspace-write"
approval_policy = "on-failure"

# UI設定
hide_agent_reasoning = true

# ツール設定
[tools]
web_search = true

# 通知設定（macOS）
[notifications]
sound = "Glass"

# MCP設定例
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

`~/.codex/AGENTS.md`で全会話に指示を反映

すべての会話に自動的に反映される指示を設定できる：

# Codex エージェント設定

## 言語設定
日本語で簡潔かつ丁寧に回答してください。

## コーディングスタイル
- TypeScriptを使用
- コメントは日本語
- テストは必須
- セキュリティを最優先

## プロジェクト構造
- src/: ソースコード
- tests/: テストコード
- docs/: ドキュメント

トラブルシューティング

よくあるエラーと解決方法

エラー1: Missing OpenAI API key

Missing OpenAI API key. Set the environment variable OPENAI_API_KEY and re-run this command.

解決方法：

# 環境変数を設定
export OPENAI_API_KEY="your-api-key-here"

# または.envファイルを作業ディレクトリに配置
echo "OPENAI_API_KEY=your-api-key-here" > .env

# またはログインコマンドで認証
codex login --api-key

エラー2: codexコマンドが見つからない

codex: command not found

解決方法：

# インストール確認
which codex

# パスが通っていない場合、再インストール
npm install -g @openai/codex

# またはnpmのグローバルパスを確認
npm config get prefix

エラー3: Node.jsバージョンエラー

Error: Node.js version 22 or higher is required

解決方法：

# Node.jsバージョン確認
node -v

# nvmでNode.js 22をインストール
nvm install 22
nvm use 22

# または公式サイトからダウンロード
# https://nodejs.org/

エラー4: トークン制限に到達

Token limit reached

解決方法：

# 会話履歴を要約
/compact

# 新しいセッション開始
/new

# または5時間待つ（自動リセット）

エラー5: 生成されたコードが動かない

対処法：

生成されたコードは必ず自分で検証・修正すること。エラーメッセージをCodexに伝えて修正依頼：

codex "このエラーを修正してください: [エラーメッセージ]"

重要: 公開されているCodex関連の調査によると、生成コードは約43%の確率で誤りを含む可能性がある。必ず自分で検証することが重要である。

Windows WSL特有の注意点

注意点1: ファイルシステムの配置

/mnt/c/...でのファイル操作は低速化の原因
~/code/配下のLinuxホームディレクトリでリポジトリ管理を推奨
Windowsエクスプローラーから\\wsl$\Ubuntu\home\<user>でアクセス可能

注意点2: WSL2の設定

WSL2は必須である。WSL1では動作しない可能性が高い。

# WSLバージョン確認
wsl -l -v

# WSL2に変更
wsl --set-version Ubuntu 2

注意点3: メモリ/CPU割り当て

.wslconfigファイルで調整：

[wsl2]
memory=8GB
processors=4

注意点4: VS Code拡張機能が反応しない

解決方法：

Visual Studio Build Tools（C++ワークロード）をインストール
wsl --updateを実行
VS Codeのsettings.jsonでWSL使用を明示的に指定

日本語使用時の注意点

日本語指示は可能だが、英語の方が精度が高い傾向がある
特定の日本語文字でエラーが発生する場合は、英語での指示を推奨
~/.codex/AGENTS.mdに日本語での回答指示を記載することで改善できる

応用的な使い方

CI/CD環境での自動実行

# 完全自動モードで実行
codex exec --full-auto --sandbox workspace-write "CHANGELOGを最新のコミットで更新"

推論レベルの調整

複雑なタスクには推論レベルを上げることで精度が向上する：

# ~/.codex/config.toml
model_reasoning_effort = "high"  # low, medium, high

セッション管理

# 過去のセッションを再開
codex resume <session-id>

# 最新セッションを再開
codex resume

シェル補完の設定

# Bash、Zsh、Fish、PowerShell用スクリプト生成
codex completion

ライセンスと注意事項

コード品質の検証

生成コードは必ず自分で検証・修正すること
セキュリティ脆弱性がないか確認が必要である
テストを必ず実行しよう

ライセンス問題

Codexは公開コードから学習しているため、類似コードが生成される可能性がある
大規模なコード片は出所を確認することを推奨する

プライバシーとセキュリティ

ローカル実行で最小限の情報のみがOpenAIに送信される
機密情報を含むコードを扱う場合は、サンドボックスモードを適切に設定すること

まとめ

OpenAI Codex CLIは、2025年4月にリリースされた強力なAIコーディングエージェントである。以下のポイントを押さえて活用しよう：

重要ポイント

インストールは簡単: npm一行でインストール可能
ChatGPT有料プラン必須: Plus/Pro/Team等のアカウントが必要
3つの承認モード: Suggest（安全）、Auto-Edit（効率的）、Full-Auto（完全自動）
マルチモーダル対応: テキストだけでなく、画像からもコード生成可能
MCP連携: Figma、GitHub、Playwrightなど外部ツールと連携
コード検証は必須: 生成コードは必ず自分で確認・修正

次のステップ

公式ドキュメントを読む: https://developers.openai.com/codex/cli/
QuickStartで実際に試す: https://developers.openai.com/codex/quickstart/
コミュニティの記事を参考にする（Zenn、Qiita等）
小さなタスクから始めて、徐々に複雑なタスクに挑戦

Codex CLIを活用することで、コーディングの生産性を大きく向上させることができる。ぜひ、実際に試してみてほしい。

よくある質問（FAQ）

Q1: Codex CLIは無料で使えるか？

いいえ、ChatGPT Plus（月額約20ドル）以上のプランが必要である。または、OpenAI API キーを使用した従量課金制での利用も可能だ。

Q2: WindowsでネイティブにCodex CLIを使えるか？

実験的サポートのみである。WSL2経由での利用を強く推奨する。ネイティブWindowsでは動作が不安定な可能性が高い。

Q3: 生成されたコードの著作権はどうなるか？

Codexは公開コードから学習しているため、類似コードが生成される可能性がある。大規模なコード片は出所を確認し、ライセンスを遵守すること。

Q4: Codex CLIはオフラインで使えるか？

いいえ、OpenAI APIとの通信が必要なため、インターネット接続が必須である。

Q5: 日本語でのプロンプトは英語と同じ精度か？

英語の方が精度が高い傾向がある。日本語でエラーが発生する場合は、英語での指示を推奨する。

Claudeでいい感じのYOUTUBEサムネイルを作る方法があるので紹介したい

Claude AI

2025年8月10日(日)

この記事を読む

microCMSでMCPサーバーを使用してコンテンツの入稿をしてみた

AI MCP

2025年8月12日(火)

この記事を読む

Webエンジニアなら確実に押さえておきたい最強のAIサービス Perplexity編

2025年5月1日(木)

この記事を読む

Webエンジニアなら確実に押さえておきたい最強のAIサービス Vrew編

2025年8月10日(日)

この記事を読む

AIブラウザ活用事例20選｜すぐ実践できるプロンプトも紹介

AI ドキュメント作成 ChatGPT

2025年11月18日(火)

この記事を読む

【2025年版】OpenAI Codex CLI完全ガイド｜Mac/Windows環境別インストールから実践まで7つの活用例

AI OpenAI Codex CLI

2025年11月20日(木)

この記事を読む

「実例付き」必ず押さえておきたい画像生成AIプロンプトテクニック6選

Claude AI プロンプトエンジニアリング ChatGPT Gemini

2025年10月5日(日)

この記事を読む

Anthropic vs OpenAI徹底比較2025｜企業市場逆転とAGI開発の二つの哲学

Claude Claude Code AI OpenAI Anthropic ChatGPT

2025年11月3日(月)

この記事を読む

Screen Studio完全ガイド：Macで簡単にプロフェッショナルな動画を作成する方法

macOS ScreenStudio AI

2025年9月2日(火)

この記事を読む

GitHub Copilotのパワーを最大限活用するためのベストプラクティス

ソフトウェア開発 VSCode GitHub Copilot AI

2025年5月3日(土)

この記事を読む

情報発信を継続するための効率的なワークフロー: AI活用で実現する持続可能なアウトプット戦略

Claude AI

2025年8月10日(日)

この記事を読む

AI時代のナレッジ管理

Claude Code プロンプトエンジニアリング Cursor AI MCP Claude

2025年10月16日(木)

この記事を読む

Web系エンジニア実践例｜情報収集から個人開発まで完全AI化の手法

Claude AI プロンプトエンジニアリング ChatGPT Gemini n8n

2025年9月21日(日)

この記事を読む

Cursor実践マニュアル：エージェントモード・ルール設定・MCPサーバー構築の全て

AI Cursor

2025年7月30日(水)

この記事を読む

Agent Skillsで実現する特化型エージェント構築 - Claudeの新機能を徹底解説

Claude Code プロンプトエンジニアリング Cursor AI MCP Claude ドキュメント作成

2025年10月19日(日)

この記事を読む

Webエンジニアなら確実に押さえておきたい最強のAIサービスイルシル編

2025年8月10日(日)

この記事を読む

ブログ管理人

masayan

Full Stack Engineer

📍 大阪, Japan

🎯 Specialties

MCP Server Clean Architecture Test Automation

⚡ Focus

AI-Driven Dev Claude Code

【2025年版】OpenAI Codex CLI完全ガイド｜Mac/Windows環境別インストールから実践まで7つの活用例

目次

要約

この記事を読むことで得られるメリット

この記事を読むのにかかる時間

環境

Codex CLIとは？

公式リソース

前提条件

必須要件

オプション

料金について

インストール方法

Mac環境でのインストール

方法1: npm（推奨）

方法2: Homebrew

方法3: mise（開発環境管理ツール使用時）

Windows環境でのインストール（WSL2経由）

Step 1: WSL2のインストール

Step 2: WSL内でのNode.jsとCodex CLIインストール

Step 3: VS Code統合設定（オプション）

初回認証

方法1: ChatGPTアカウントでサインイン（推奨）

方法2: API キーで認証

初回のみの確認

基本的な使い方

起動方法

対話型モード（デフォルト）

非対話型実行（execコマンド）

プロンプト直接指定

基本コマンド

3つの承認モード

1. Suggest（デフォルト）

2. Auto-Edit

3. Full-Auto

プロジェクト初期化

実践例

例1: ToDoアプリの作成

例2: テスト自動生成

例3: README自動生成

例4: セキュリティチェック

例5: 画像からコード生成（マルチモーダル）

例6: リファクタリング

例7: マイグレーション生成

主要機能の詳細

コードレビュー機能

Webサーチ機能

モデル切り替え

MCP（Model Context Protocol）連携

MCPサーバーの追加

設定ファイルで追加

推奨MCPサーバー

スクリプト実行（CI/CD統合）

設定のカスタマイズ

設定ファイルの場所

推奨設定例（~/.codex/config.toml）

~/.codex/AGENTS.mdで全会話に指示を反映

トラブルシューティング

よくあるエラーと解決方法

エラー1: Missing OpenAI API key

エラー2: codexコマンドが見つからない

エラー3: Node.jsバージョンエラー

エラー4: トークン制限に到達

エラー5: 生成されたコードが動かない

Windows WSL特有の注意点

注意点1: ファイルシステムの配置

注意点2: WSL2の設定

注意点3: メモリ/CPU割り当て

注意点4: VS Code拡張機能が反応しない

日本語使用時の注意点

応用的な使い方

CI/CD環境での自動実行

推論レベルの調整

セッション管理

シェル補完の設定

ライセンスと注意事項

コード品質の検証

ライセンス問題

プライバシーとセキュリティ

まとめ

推奨設定例（`~/.codex/config.toml`）

`~/.codex/AGENTS.md`で全会話に指示を反映