Codex の使い方：CLI、IDE 拡張、Codex Cloud、デスクトップアプリの完全入門ガイド

初めて Codex を使うとき、いきなりプロジェクト全体のリファクタリングを頼む必要はありません。まずリポジトリを開き、20 分ほどで検証できる小さなタスクを 1 つ渡しましょう。

入口選びの全体像

OpenAI Codex は、単一の端末ツールでも、単一のプラグインでもありません。複数の入口から使える coding agent です。公式ドキュメントでは CLI、IDE extension、Codex app、Codex web/cloud という名前が出てきます。認証と基礎能力は近いものの、向いている場面は違います。

4 つの入口の比較表

入口	定義	向いている場面	典型的なユーザー	制約
CLI	ローカル端末で動く coding agent	既存のローカルリポジトリ、小さな変更、コマンドライン作業	端末をよく使う人、CI 環境	ローカルに Git リポジトリが必要。変更はローカルファイルとして見える
IDE Extension	エディタのサイドバーで協作する入口	現在のエディタ作業、open files / selected code による短いコンテキスト	VS Code / Cursor / Windsurf / JetBrains ユーザー	エディタ環境に依存する。複雑なタスクは Cloud に委任できる
Codex App	デスクトップの command center	複数スレッド、worktree、automations、Git 管理	複数タスクを並行処理したいローカルユーザー	macOS / Windows で利用可能。Linux の可用性は公式ページで確認
Codex Cloud/Web	GitHub に接続するクラウド agent	リモートリポジトリ、PR、非同期タスク、PC から離れる作業	チームユーザー、リモートリポジトリ中心の作業	Enterprise workspace では admin setup が必要な場合がある

認証方式と機能差

Codex には 2 つの認証方式があります。ただし、使える機能は同じではありません。

認証方式	利用できる入口	Cloud 機能の可用性	向いている場面
ChatGPT account（Plus/Pro/Business/Edu/Enterprise）	すべての入口（CLI/IDE/App/Cloud）	GitHub code review、Slack などの cloud-based features を含む	個人の有料ユーザー、チーム
API Key	CLI、SDK、IDE Extension	GitHub code review、Slack などの cloud-based features は含まない	CI 環境、API 課金で使いたい場面

価格、利用枠、具体的な機能の開放状況は、公式 pricing ページと自分の account dashboard で確認してください。API key でログインして Cloud 機能が使えなくても、それは故障ではなく surface の違いです。

CLI 入口

CLI はローカル端末で動く coding agent です。選択したディレクトリのコードを読み、ファイルを変更し、コマンドを実行し、結果を確認できます。すでにローカルリポジトリがある場面に向いています。

CLI の定義と場面

CLI の中心的な役割は、ローカルリポジトリの中で作業することです。コードを読む、ファイルを変更する、テストを走らせる、lint を走らせる、エラーを確認する、diff を作る。エディタでファイルを開いていなくても、端末でタスクを説明すれば始められます。

CLI に向いている場面：

• ローカルに Git リポジトリがある
• 複数ファイルにまたがる、またはコマンドで検証するタスク
• git diff や commit のために変更をローカルで見たい
• CI 環境や自動化スクリプトから呼びたい

CLI に向いていない場面：

• ローカルリポジトリがない（まず clone が必要）
• 今開いている 1 ファイルだけを触りたい（IDE extension のほうが自然）
• リモートリポジトリの PR workflow が必要（Cloud のほうが合う）

CLI のインストールとログイン

インストールとログイン手順は変わることがあります。ここでは大枠だけを押さえ、具体的なコマンドは公式 CLI ページを確認してください。

1. 公式 CLI ページでインストール方法を選ぶ：現在の公式ページでは standalone installer が案内されています。古い記事では npm install に触れている場合がありますが、現時点の公式ページを優先します。
2. 初回起動：インストール後に codex を実行すると、ログインが案内されます。
3. ログイン方式：ChatGPT account または API key を選べます。ChatGPT account はすべての surface を含みます。API key は CLI / SDK / IDE extension 向けで、Cloud 機能は含みません。

CLI は macOS、Windows、Linux をサポートします。Windows では PowerShell native sandbox または WSL2 を使えますが、細部は公式 CLI ページに従ってください。

CLI のよく使うコマンド

CLI には interactive と non-interactive の 2 種類の入口があります。初心者がまず知っておくとよい 6 つのコマンドまたは flag 群は次のとおりです。コマンド名は変わる可能性があるため、正確な構文は CLI reference で確認してください。

コマンド	用途	例
codex	端末で対話しながら進める interactive mode	codex
codex exec	CI や script に向く non-interactive mode	codex exec "fix the CI failure"
codex login	ログインまたはアカウント切り替え	codex login
codex update	CLI の更新	codex update
codex doctor	環境設定と問題の確認	codex doctor
よく使う flags	権限、モデル、sandbox などを調整	--sandbox read-only、--model、--ask-for-approval

CLI reference には codex apply、codex cloud、codex app など、さらに多くのコマンドや flags があります。成熟度が異なるコマンドもあります。初心者はまず interactive mode を覚え、必要になったら codex exec の自動化へ進みましょう。

CLI での最初のタスク

最初のタスクの原則はシンプルです。既存のリポジトリを選び、20 分ほどで検証できるタスクを Codex に渡します。

公式 best practices では、よい prompt には 4 つの要素を含めることが推奨されています。

Prompt の要素	説明	例
Goal	目標	”README の古いインストールコマンドを修正する”
Context	背景	”これは Node.js プロジェクトです。README には npm install とありますが、実際には yarn を使います”
Constraints	制約	”README だけを変更してください。他のファイルは変更しないでください。変更後に node README-example.js を実行し、コマンドが動くことを確認してください”
Done when	完了条件	”README のコマンドが更新され、node README-example.js が期待どおりの結果を出したとき”

最初のタスクに向いている例：

• README の古いコマンドやリンクを直す
• 足りないテストを 1 つ追加する、または失敗しているテストを直す
• 明確なエラーがある小さな bug を直す
• TODO コメントを 1 つ片付ける
• 1 つの module に簡単な型注釈を足す

最初のタスクにしないほうがよい例：

• secret や本番データに触れる作業
• 大規模リファクタリングや完全な新機能
• “性能を最適化して”のように検証条件が曖昧な作業

CLI の検収チェックリスト

CLI がタスクを終えたら、次の順序で確認します。

1. diff を見る：端末で git diff を実行し、変更が意図どおりか確認します。「完了しました」という返答だけを信じないでください。
2. テストを実行する：プロジェクトにテストがあるなら、npm test など該当するコマンドを実行します。
3. lint / typecheck を実行する：用意されている場合は、新しいエラーが増えていないか確認します。
4. コマンド出力を確認する：タスクに「このコマンドを実行する」が含まれていたら、出力が期待どおりか見ます。
5. 最初のタスクに secret を渡さない：機密設定に関係する場合、本当に agent が編集する必要があるかを先に人間が確認します。

検収できたら commit または push します。想定と違う変更だった場合は Git で戻し、prompt を絞って再実行します。

IDE Extension 入口

IDE extension は、Codex をエディタのサイドバーで使う入口です。すでにエディタで作業しているときに向いています。強みはコンテキストが短く、鋭いことです。open files、selected code、@file 参照を使えば、端末でプロジェクト全体を説明しなくても始められます。

IDE の定義と場面

IDE extension はエディタそのものを置き換えるものではありません。Codex を coding agent としてエディタ workflow に組み込むものです。現在開いているファイル、選択したコード片、@file で明示したファイルがコンテキストになるため、局所的な変更では精度を上げやすくなります。

IDE extension に向いている場面：

• VS Code / Cursor / Windsurf / JetBrains で作業している
• 現在のファイル、または少数の関連ファイルを扱う
• エディタ内で変更を見ながら進めたい
• 特定ファイルをコンテキストとして明示したい

IDE extension に向いていない場面：

• エディタ環境がない（CLI のほうが簡単）
• 長時間バックグラウンドで走らせたい（Cloud に委任できる）
• 多数のファイルや複雑なコマンド flow を扱う（CLI または Cloud が向く）

対応 IDE

IDE extension は次のエディタをサポートします。最新の可用性は公式 IDE ページを確認してください。

エディタ	説明
VS Code	公式サポート
Cursor	VS Code fork で、VS Code extension と互換
Windsurf	VS Code fork で、VS Code extension と互換
JetBrains	Rider、IntelliJ、PyCharm、WebStorm などをサポート。可用性は公式ページを確認

Cursor や Windsurf で作業している場合、Codex extension とエディタ内蔵の AI 機能は並行して使えます。Codex は別の coding agent として、タスクに応じて切り替えるものです。

IDE のインストールとログイン

インストールとログイン手順は公式 IDE ページに従います。

1. 拡張マーケットプレイスからインストール：VS Code / Cursor / Windsurf / JetBrains の拡張マーケットプレイスで Codex extension を検索します。
2. ログイン方式：ChatGPT account または API key を使えます。ChatGPT account はすべての surface を含みます。API key は Cloud 機能を含みません。

IDE のコンテキスト能力

IDE extension の中心的な価値は、エディタのコンテキストを使えることです。

コンテキスト	説明	例
Open files	現在開いているファイルがコンテキストになる	example.tsx を開くと、Codex はその内容を直接見られる
Selected code	選択したコード片がコンテキストになる	関数を選択して、説明やリファクタリングを依頼する
@file 参照	@filename で他のファイルを明示する	@example.tsx この component の型定義を確認して
Reasoning effort	推論の深さを調整する	low/medium/high。複雑なタスクでは高めを使う

IDE には Chat、Agent、Agent Full Access mode もあります。違いは権限と自動化の度合いです。初心者はまずデフォルトの Agent mode を使い、慣れてから調整しましょう。

IDE から Cloud へ委任する

IDE extension はタスクを Codex Cloud に委任できます。向いているのは次のような場面です。

• 長時間走る可能性があるタスク
• リモートリポジトリを扱うタスク
• PC から離れても実行を続けたいタスク
• 複雑なタスクをバックグラウンドで走らせ、後から結果を見たい場合

よく使う slash commands は次のようなものです。名前は変わる可能性があるため、IDE features ページを確認してください。

コマンド	用途
/cloud	現在のタスクを Cloud に委任する
/local	ローカルでタスクを実行する
/review	base branch、未コミット変更、commit を review する
/status	Cloud タスクの状態を見る

/cloud で委任すると、IDE にタスク状態が表示されます。Cloud タスクが終わったら戻って diff と結果を確認します。

Codex App 入口

Codex app はデスクトップの command center です。位置づけは、複数スレッドと Git 管理の作業台であり、単なる別のチャット画面ではありません。CLI と IDE extension の履歴や設定を拾えるため、既存プロジェクトで作業を続けやすくなります。

App の定義と場面

App の中心は、複数スレッド管理、worktree、automations、Git 操作です。複数タスクを並行して進めたい、diff pane と Git 統合がほしい、というローカルユーザーに向いています。

App に向いている場面：

• 複数の task thread を同時に扱いたい
• worktree で並行作業を分離したい
• 視覚的な diff pane と Git 操作が必要
• デスクトップ上で terminal も統合したい

App に向いていない場面：

• 今開いているファイルだけを直したい（IDE extension のほうが自然）
• ローカルリポジトリがない（Cloud を使うか、まず clone する）
• 1 つの簡単なタスクだけを走らせたい（CLI のほうが速い）

App のプラットフォーム対応

Codex app は macOS と Windows をサポートします。Linux の可用性は公式 app ページで確認してください。

App のインストールとログイン

インストールとログイン手順は公式 app ページに従います。

1. ダウンロードとインストール：公式 app ページから macOS / Windows の installer を入手します。
2. ログイン方式：ChatGPT account または API key を使えます。API key では一部機能が使えない場合があります。詳細は公式ページを確認してください。
3. プロジェクトを選ぶ：初回起動時にローカルプロジェクトディレクトリの選択が案内されます。

App Thread Mode

App には Local、Worktree、Cloud の 3 つの thread mode があります。

Thread Mode	説明	向いている場面
Local	現在のプロジェクトディレクトリで直接作業する	小さな変更、単一スレッド、初回メッセージのデフォルト
Worktree	分離された worktree を作る	並行タスク、変更の分離、衝突の回避
Cloud	Codex Cloud に委任する	リモートリポジトリ、PR、長時間タスク

Worktree mode の詳しい使い方は後続の専門記事に回します。初心者はまず Local mode からで十分です。

App の主要機能

App の主な機能は次のとおりです。

機能	説明
Diff pane	ファイル変更を視覚的に確認し、chunk 単位で stage / revert できる
Git 操作	commit / push / create PR などの Git workflow を扱える
統合 terminal	macOS では Cmd+J で terminal を開ける。ショートカットは公式ページで確認
IDE 同期	IDE extension と app が同じプロジェクトで同期できる
MCP settings 共有	CLI / IDE / app で MCP settings を共有できる

App には in-app browser もあります。ただし、ログインが必要なページやユーザーブラウザの profile が必要なページには向きません。その場合は外部ブラウザで開くのが安全です。

Codex Cloud/Web 入口

Codex web/cloud は GitHub account に接続し、Codex がリモートリポジトリで作業して PR を作成できる入口です。チーム、リモートリポジトリ、PC から離れても続けたいタスクに向いています。

Cloud の定義と場面

Cloud の中心は「リモートリポジトリ + PR + 非同期タスク」です。クラウド上にコンテナを作り、repo を checkout し、setup script を実行し、タスクを進め、diff と回答を返します。

Cloud に向いている場面：

• ローカルで変更したくないリモートリポジトリ
• Codex に PR 作成や review を任せたい PR workflow
• PC から離れても続けたい作業
• 複数人で review するチーム workflow

Cloud に向いていない場面：

• ローカルの小さな変更（CLI または IDE が合う）
• 初めてのタスク（先にローカルで検証したほうがよい）
• 何度も細かくやり取りするタスク（Cloud は非同期）

Cloud に向くタスク

Cloud に向くタスクは次のとおりです。

タスク種別	説明
PR review	リモートリポジトリの PR を review する
複雑または長時間の作業	時間がかかるタスクを実行する
並行タスク	複数タスクを同時に委任する
リモートリポジトリの変更	ローカル checkout に触れずに変更する

最初から大規模リファクタリングや完全な新機能を Cloud に投げるのは避けましょう。まず CLI または IDE でローカル検証を経験し、結果の見方に慣れてから Cloud を使います。

Enterprise workspace では admin setup が必要な場合があります。公式 Cloud ページと workspace policy を確認してください。

Cloud の流れ

Cloud task はおおよそ 5 つのステップで進みます。

1. コンテナ作成：Cloud が実行環境を作ります。
2. Checkout repo：GitHub からリポジトリを checkout します。
3. setup script 実行：設定済みの setup script があれば実行します。
4. Agent loop 実行：agent がコマンドを実行し、結果を確認し、完了まで進めます。
5. diff と回答を返す：タスク完了後、diff と回答が表示されます。

コンテナキャッシュは最長 12 時間です。現在の cache policy は公式 Cloud environments ページで確認してください。

Cloud の安全メモ

Cloud にはいくつか重要な安全境界があります。

安全項目	説明
Secrets は setup でのみ利用可能	Secrets は setup scripts で利用でき、agent phase の前に削除されます。agent phase が secret を読む script に依存しないようにしてください。
Agent phase はデフォルトで internet off	Agent phase では internet access がデフォルトで off です。limited または unrestricted access を設定できますが、外部サービスに届く前提で書かないでください。
Cache は最長 12 時間	コンテナ cache は長期保存ではありません。状態がずっと残るとは考えないでください。

詳しい安全設定は、後続の権限、sandbox、secret の記事で扱います。

次のステップ

最初のタスクを終えたあと、Codex が 2 回目、3 回目も同じ失敗を繰り返すなら、AGENTS.md のプロジェクト規約を書くタイミングです。AGENTS.md は coding agent 向けのプロジェクト説明ファイルで、毎回同じ文脈を prompt に書かなくて済むようにします。

後続テーマ：

• AGENTS.md プロジェクト規約：プロジェクトの指示を残し、毎回の説明を減らす。
• Worktree 並行分離：複数タスクを並行して進め、変更の衝突を避ける。
• Cloud 実践：リモートリポジトリ、PR、環境設定。
• 権限、sandbox、secret：安全境界と設定。
• 3 ツール比較：Codex vs Claude Code vs Cursor を実プロジェクトで比較。
• codex exec 自動化：CI 呼び出しと script automation。

関連記事：

• 2026 年の AI coding tools overview
• Claude Code CLI 効率化ガイド
• Cursor workflow 実践
• Codex gateway と harness