Codex CLIで迷っているなら読んでほしい、実践セットアップガイド

2026.04.23

「Codex CLIって、どこから始めればいいの？」

インストールできた。起動もした。でも何を入力すればいいかわからない。AGENTS.mdって何？承認モードはどれを選べばいい？MCPって設定が必要なの？——Codex CLIを使い始めたばかりの頃、こういった疑問が次々と出てきた。

公式ドキュメントは英語で、散らばっている。日本語の記事はインストール手順までは丁寧だが、その先が薄い。実際に動かして分かったことを、ひとつの記事にまとめた。

この記事は、Codex CLIを「インストールしてみたけど迷っている人」と「もう少し使いこなしたい人」に向けて書いています。インストール手順から、承認モードの選び方、AGENTS.mdの書き方、MCP設定、execコマンドによる自動化、IDE統合まで、実践に必要な知識をひとつにまとめています。

Codex CLIを使いこなすための最初の関門は「AGENTS.mdを書くこと」と「承認モードを理解すること」の2点です。この2つさえ整えれば、Codex CLIは別物になります。

Codex CLIとは何か？

Codex CLIとは、OpenAIが提供するターミナルで動作するAIコーディングエージェントのことです。ローカルのターミナルから起動し、自分のコードベースを直接読み込んでファイルの編集・コマンド実行・デバッグを自律的に行います。

ChatGPT版のCodex（クラウドエージェント）とは異なり、Codex CLIはローカルで動くため、インターネット上のサンドボックスではなく自分のマシン上のファイルシステムに直接アクセスします。プライベートなコードを外部に送らずに済む点、インタラクティブに作業を確認しながら進められる点が特徴です。

Apache-2.0ライセンスのオープンソースソフトウェアで、GitHubで公開されています（github.com/openai/codex）。Rustで書かれており、433名以上のコントリビューターが参加する活発なプロジェクトです。

インストールから最初の起動まで

3つのインストール方法

Codex CLIのインストール方法は3つあります。自分の環境に合ったものを選んでください。

方法1：npm（Node.jsが入っている場合）

npm install -g @openai/codex

Node.js 18以上が必要です。インストール後は「codex」コマンドで起動できます。アップデートは「npm update -g @openai/codex」で行います。

方法2：Homebrew（macOSの場合）

brew install –cask codex

macOSユーザーにとっては最も手軽な方法です。Homebrewがない場合は brew.sh から先にインストールしてください。

方法3：バイナリ直接ダウンロード

GitHubのリリースページ（github.com/openai/codex/releases）からプラットフォーム別のバイナリを直接ダウンロードできます。macOS（Apple Silicon / Intel）、Linux（x86_64 / arm64）に対応しています。npmやHomebrewが使えない環境ではこの方法が有効です。

初回起動と認証

インストール後、ターミナルで「codex」と入力すると起動します。初回起動時にはChatGPTアカウントでのサインインが求められます。ChatGPT Plusプラン（月額20ドル）以上が必要です。

起動すると、フルスクリーンのターミナルUIが展開されます。作業したいディレクトリを開いた状態で起動するのが基本です（cd コマンドでプロジェクトに移動してから codex を実行）。起動時に現在のディレクトリを自動的にコンテキストとして読み込みます。

デスクトップアプリ版を使いたい場合は「codex app」コマンドで起動できます。GUIで操作できるため、ターミナルに不慣れな方にはこちらが入りやすいかもしれません。

CI環境やスクリプトからAPIキーで直接認証する場合は、環境変数「CODEX_API_KEY」にAPIキーをセットすることで対話認証をスキップできます。

承認モードを正しく選ぶ

Codex CLIには3つの承認モードがあります。どのモードを選ぶかで、Codexがどこまで自律的に動くかが変わります。ここを理解しないまま使い始めると、意図しないファイル変更や実行が起きることがあります。

3つのモードの違い

Suggest（提案モード）：ファイルの読み込みだけ自動実行され、編集・コマンド実行はすべて人間の承認が必要です。最も慎重なモードで、Codexが何をしようとしているかを1ステップずつ確認できます。初めて使う場合や、重要なリポジトリを扱う場合に適しています。

Auto-edit（自動編集モード）：ファイルの読み込みと編集は自動で行われますが、シェルコマンドの実行（テストの実行・パッケージのインストールなど）は承認が必要です。ファイルを変更するのは問題ないが、外部への影響がある操作は手動で確認したい場合に適しています。

Full-auto（完全自動モード）：ファイルの読み込み・編集・シェルコマンドの実行すべてが承認なしで自動実行されます。最も強力ですが、コードとデータの両方に影響する操作が無制限に行われます。信頼できるリポジトリで、かつ自分が内容を把握しているプロジェクトに限定して使うことを推奨します。

どのモードを選ぶべきか

モードはCLI起動時の引数で指定できます。設定ファイル（~/.codex/config.toml）に「approval_policy」を記述すればデフォルトを変更できます。優先順位は「CLIの引数＞プロファイル設定＞ config.toml ＞デフォルト」の順です。

実際に使ってみての使い分けの目安として、初回・見知らぬコードベースではSuggestモード、慣れたプロジェクトの日常的なタスクではAuto-editモード、CI/CDや自動化スクリプトではFull-autoモード（ただし環境を隔離した状態で）という選択が現実的です。

「Approve This Session」という選択肢もあります。これはセッション中だけ一時的に自動承認を有効にするオプションで、普段はSuggestで使いつつ、特定の作業中だけ承認なしで進めたい場合に役立ちます。

AGENTS.mdを最初に書くべき理由

Codex CLIを使い始める前にやるべき最重要タスクが、AGENTS.mdの作成です。AGENTS.mdとは、プロジェクトのルートディレクトリに置くMarkdownファイルで、Codexにプロジェクト固有のルール・制約・期待を永続的に伝えるための設定ファイルです。

AGENTS.mdがないと何が起きるか。実際に経験したのは、Codexがプロジェクトで使っていないパッケージマネージャー（yarnではなくnpm）でライブラリをインストールしようとしたこと、コミットメッセージの形式がプロジェクトの規約と異なったこと、既存のESLint設定を無視してコードを書いたことです。AGENTS.mdを書いてから、これらのミスがほぼなくなりました。

グローバルAGENTS.mdとプロジェクトAGENTS.md

AGENTS.mdは2種類の場所に置けます。

グローバル設定（~/.codex/AGENTS.md）：どのプロジェクトでも共通に適用されるルールを書きます。例として、使用するシェル（zsh/bash）、コミットメッセージのデフォルトフォーマット、絶対に実行してはいけないコマンド（rm -rf など）の禁止リスト、preferred editorの設定などが入ります。

プロジェクト設定（リポジトリルートの AGENTS.md）：そのリポジトリ固有のルールを書きます。グローバル設定を上書き・補足する形で機能します。プロジェクトの言語・フレームワーク、テスト実行方法、ディレクトリ構成のルール、変更禁止ファイルなどを記述します。

Codexはタスクを開始する前に、グローバルのAGENTS.mdとプロジェクトのAGENTS.mdを両方読み込み、指示の文脈として使います。「codex explain –show-context」コマンドを実行すると、Codexが実際にロードしている設定ファイルの内容を確認できます。

実際のAGENTS.md記述例

以下はTypeScriptのWebアプリプロジェクト向けAGENTS.mdの記述例です（実際の内容を参考に）。

記述する内容の例として、「このプロジェクトはTypeScript + Next.jsで書かれています」「パッケージマネージャーはpnpmを使います。npmやyarnは使わないでください」「新機能には必ずJestのユニットテストを追加してください」「コードを変更したらESLint（pnpm lint）を通してください」「コミットメッセージはAngular Commitスタイル（feat/fix/chore/docs）で書いてください」「src/config/secrets.ts は絶対に変更しないでください」というものが挙げられます。

ポイントは「Codexがやりそうなミス」を先回りして禁止することです。プロジェクトで過去にCodexが誤った操作をした場合、その内容をAGENTS.mdに明記すれば次回から防げます。AGENTS.mdは育てていくものと考えると、継続的に品質が上がります。

/initコマンドで自動生成する

「codex /init」スラッシュコマンドをCodexの起動後に入力すると、Codexがカレントリポジトリを分析してAGENTS.mdのスカフォールドを自動生成してくれます。使用言語・フレームワーク・パッケージマネージャー・テスト設定などを自動検出してひな形を作成するため、ゼロから書くより格段に効率的です。生成されたファイルを確認・編集してリポジトリの規約に合わせれば完成です。

実践的な指示の出し方

指示を具体的にするコツ

Codex CLIへの指示は、具体的であるほど結果が良くなります。「バグを直して」と「tests/auth.test.tsのline 42のassertionが失敗している。原因を調べ、修正し、修正理由をコメントとして追加して」では、出力の品質が大きく変わります。

指示を具体的にするための4つの要素を意識するとうまくいきます。「何をするか（動詞）」「どのファイル・どの箇所か（対象）」「どのような結果を期待するか（成果）」「制約条件はあるか（制限）」の4点を指示に含めると、Codexの動作が安定します。

また、エラーが起きている場合はエラーメッセージをそのままCodexに貼り付けるのが最も効率的です。「TypeError: Cannot read properties of undefined」というエラーがあれば、ログごと渡すだけで原因の特定から修正まで自動で行ってくれます。

画像を使って指示する

Codex CLIはPNG・JPEGなどの画像ファイルを読み込めます。UIのスクリーンショットを添付して「このデザインに合わせてCSSを修正して」と指示したり、エラー画面のスクリーンショットを添付して「この画面のエラーを修正して」と伝えたりすることができます。

実際に使ってみてわかったのは、UIデザインの修正や、画面上に表示されているエラーの解消に画像添付が特に効果的だということです。デザイナーからもらったFigmaのスクリーンショットを貼って「このUIに近づけて」という使い方が、言葉で説明するより圧倒的に速くなります。

IDE統合（VS Code・Cursor・Windsurf）

Codex CLIはVS Code・Cursor・WindsurfなどのIDEと統合できます。エディタを閉じずにCodexを呼び出して、編集結果をそのまま確認できるため、ターミナルとエディタを行き来する手間が省けます。

VS Code拡張機能の場合は、VS CodeのExtensionsパネルで「Codex」を検索してインストールします。インストール後、コマンドパレット（Cmd+Shift+P）から「Codex: Open」で起動できます。CLIと同じ設定ファイル（~/.codex/config.toml）を共有するため、MCPサーバーやAGENTS.mdの設定を別途行う必要はありません。

ただし、2025年12月時点でGitHubのIssueで報告されているように、config.tomlで定義したMCPサーバーがCLIでは認識されるがVS Code拡張では認識されないというセッション分離の問題があります。MCPを積極的に使いたい場合は、現時点ではCLIから使うのがより安定しています。

CLIとIDE拡張は同じ設定ファイルを共有しているため、どちらで使っても同じAGENTS.mdとconfig.tomlが適用されます。片方で設定すれば、もう一方でも使えます。

MCP連携の設定方法

MCP（Model Context Protocol）とは、Codexが外部のツール・データソースに接続するための標準プロトコルです。SlackやNotionやデータベースなど、コードベース外のシステムをCodexから参照・操作するために使います。

設定は~/.codex/config.tomlに記述します。各MCPサーバーは「[mcp_servers.サーバー名]」というテーブル形式で定義し、「command」パラメータ（必須）でサーバー起動コマンドを指定します。

設定の例として、GitHubのMCPサーバーを追加する場合は以下のように記述します。

[mcp_servers.github] という見出しを書く
command = “npx -y @modelcontextprotocol/server-github” を記述する
必要な環境変数（GITHUBトークンなど）をenvセクションに追加する

MCPサーバーの追加はCLIコマンドでも行えます。「codex mcp」コマンドを実行するとMCPの管理メニューが開き、GUIで追加・削除・有効無効の切り替えができます。プロジェクト固有のMCPサーバーを設定したい場合は、リポジトリ内の「.codex/config.toml」（信頼済みプロジェクトのみ）に記述します。

OpenAIは現時点で約90種類のセキュリティレビュー済みプラグインを提供しています。Slack連携・Notion連携・GitHub連携・データベース接続など、よく使われるツールは公式プラグインで対応していることが多いため、まずOpenAIのプラグインカタログを確認することをおすすめします。

execコマンドでCI/CDと自動化に使う

Codex CLIには非対話型で実行するための「exec」コマンドがあります。ターミナルUIを開かず、与えた指示をそのまま実行して結果をstdoutに出力するモードです。CI/CDパイプラインやシェルスクリプトからCodexを呼び出す際に使います。

基本的な使い方として、「codex exec “fix the failing tests”」のように記述します。短縮形として「codex e “…”」も使えます。実行結果をJSONで受け取りたい場合は「–json」フラグを追加すると、改行区切りのJSONイベントストリームが出力されます。スクリプトでCodexの出力をパースして次の処理に繋げたい場合に便利です。

CI環境（GitHub ActionsやCircleCIなど）でCodexを使う場合の推奨設定として、環境変数「CODEX_API_KEY」にAPIキーをシークレットとしてセットして認証を行い、Codex を Full-autoモードで実行しますが、その際に作業ディレクトリを隔離（サンドボックス化）することが重要です。ファイルの変更が意図しない範囲に及ぶリスクを防ぐため、必ずCI環境内での実行に限定してください。

また、2026年初頭に実験的な「codex exec-server」サブコマンドが追加されました。これはリモートやアプリサーバーのワークフロー向けの独立したWebSocketエンドポイントとして機能します。まだ実験的な機能ですが、Codexをサーバーとして常駐させて外部からHTTP/WebSocketでトリガーするユースケースに対応しています。

Remote TUIモードでリモート開発に使う

Remote TUIモードとは、Codexのアプリサーバーをリモートマシン上で動かし、ターミナルUIをローカルから操作する機能です。コード・クレデンシャル・実行環境がリモートサーバー上にあるが、インタラクティブなTUI操作はローカルで行いたい場合に使います。

典型的なユースケースとして、本番に近いLinuxサーバー上でCodexを動かしながら、手元のMacのターミナルからTUIで指示を出す、というパターンがあります。コードとデータがリモートにあるため、ローカルにクローンせずに作業できます。

認証にはWebSocketのケイパビリティトークンまたは署名済みベアラートークンを使います。セキュアな接続が前提で設計されているため、オープンなネットワーク越しに使う場合はSSHトンネルを介すことをおすすめします。

よくある失敗と対処法

起動後に何をすればいいかわからない：まずプロジェクトのディレクトリで起動しているか確認してください。「/init」コマンドを実行するとAGENTS.mdのひな形が生成されます。その後「このプロジェクトのREADMEを確認してコードの概要を教えて」と聞くところから始めると、Codexが何を理解しているかを把握できます
Codexが意図とは違うファイルを変更した：承認モードをSuggestに変更し、1ステップずつ確認しながら進めてください。AGENTS.mdに「変更してはいけないファイル・ディレクトリ」を明示することで予防できます
同じミスを繰り返す：Codexが繰り返す誤りはAGENTS.mdに禁止事項として追記してください。「〇〇のライブラリを使わないこと」「〇〇のコマンドを実行する前に確認すること」といった形で記述します
CLI版でMCPが動かない：config.tomlのパスと構文を確認してください。「codex explain –show-context」でロードされている設定を確認できます。VS Code拡張とCLIでMCPの認識が異なる場合は、CLIから使うことを推奨します
大きなリポジトリで動作が遅い：.codexignore ファイルを作成して、node_modules・dist・.git などCodexが読む必要のないディレクトリを除外することで速度が改善します

よくある質問

Q1. Codex CLIとChatGPT版Codexは何が違いますか？

Codex CLIはローカルのターミナルで動作し、自分のマシン上のファイルに直接アクセスします。インタラクティブに確認しながら作業できる点、コードが外部サンドボックスに送られない点が特徴です。ChatGPT版（クラウドエージェント）はGitHubと連携してクラウド上で動作し、バックグラウンドで複数タスクを並行処理してプルリクエストを自動作成します。用途に応じて使い分けるのがベストです。

Q2. Codex CLIを使うのにChatGPTのプランは必要ですか？

ChatGPTアカウント（Plusプラン以上推奨）を使って認証するのが標準的な方法です。ただし、OpenAIのAPIキーを持っている場合は、CODEX_API_KEY環境変数にセットすることでChatGPTプランなしでも利用できます。APIの従量課金が発生するため、使用量によってはChatGPTプランの方がコスト効率が良い場合があります。

Q3. 承認モードはどこで設定できますか？

複数の方法があります。起動時のCLI引数（–full-auto、–auto-edit など）、~/.codex/config.toml の approval_policy 設定、または起動後のTUI画面内での切り替えが可能です。プロジェクトごとにデフォルトのモードを変えたい場合は、プロジェクトの .codex/config.toml に記述することで、そのリポジトリでの起動時に自動的に適用されます。

Q4. AGENTS.mdはリポジトリにコミットすべきですか？

チームでCodexを使う場合はコミットすることを推奨します。全員が同じCodexの動作ルールを共有でき、新しいメンバーがリポジトリをクローンしてCodexを使い始めた際にもプロジェクトのルールが自動的に適用されます。ただし、グローバルな~/.codex/AGENTS.mdには個人の設定を書くため、こちらはコミットせずローカルに保持します。

Q5. Codex CLIで中断したセッションを再開できますか？

はい、セッション再開機能があります。Codex CLIを起動すると、直前のセッションを再開するオプションが表示されます。長時間かかるタスクの途中でターミナルを閉じてしまった場合でも、コンテキストを維持したまま作業を続けられます。

Q6. MCPサーバーはどれを入れればいいですか？

用途に応じて異なりますが、最初に入れて損がないのはGitHub MCPサーバーとfetch（Web取得）MCPサーバーです。GitHub MCPサーバーはIssueやPRの内容をCodexが参照できるようになるため、コードと課題管理を繋げた作業が可能になります。fetch MCPサーバーはライブラリのドキュメントなど外部URLの内容をCodexが取得できるようになります。OpenAIのプラグインカタログで公式対応済みのものから選ぶと設定がシンプルです。

Q7. execコマンドはどんな場面で使いますか？

主にCI/CDパイプラインや定期実行バッチで使います。GitHub Actionsのワークフローに「codex exec “テストが失敗しているPRのコードを修正して”」を組み込んだり、毎朝実行するスクリプトでCodexに定期的なコード品質チェックを実行させたりといった使い方があります。–json フラグを使うとJSONで結果を受け取れるため、後続の処理にデータを渡す自動化システムを構築できます。

Q8. Windowsでも使えますか？

はい、2026年3月にWindows版が正式リリースされました。WSL（Windows Subsystem for Linux）なしでネイティブに動作します。インストールはnpm（npm install -g @openai/codex）またはGitHubのリリースページからWindows用バイナリをダウンロードする方法があります。VS Code拡張機能もWindows上で同様に使えます。