Codex を Cursor で動かす方法 — ターミナル統合と設定

なぜ今 Cursor と Codex を併用する価値があるのか

Cursor はここ数か月で更新ペースを上げており、2026 年 6 月末には iOS 版モバイルアプリのパブリックベータを公開するなど、エディタ単体に閉じない方向へ広がっている(出典: https://cursor.com/changelog )。一方で OpenAI の Codex CLI は特定の IDE に縛られないターミナル常駐型のエージェントとして安定版を重ね、どの編集環境からでも同じ操作感で呼び出せる中立性を保っている(出典: https://github.com/openai/codex )。この「IDE 側は補完と会話を強化し、CLI 側はファイル横断のタスクを引き受ける」という分業がかみ合うため、両方を入れている開発者にとっては片方に統一するより併用したほうが取りこぼしが減る。Cursor のリポジトリ理解と Codex のエージェント実行を、同じプロジェクト・同じ画面の中で切り替えられる点が、今あえて両立させる実利になる。

Codex CLI と Cursor の関係を整理する

混乱しやすいのは「Cursor にも AI があるのに、なぜ別の Codex を足すのか」という点だ。Cursor の AI 機能はエディタへ密着しており、カーソル位置の補完、選択範囲の書き換え、サイドパネルでの会話といった IDE ネイティブな操作に強い。対して Codex CLI はプロジェクトのルートディレクトリを起点に、複数ファイルの読み書きやコマンド実行を一連のタスクとしてこなすエージェントで、ターミナルが主戦場になる(出典: https://developers.openai.com/codex/cli/ )。

両者は排他ではなく、Cursor が「エディタ」というレイヤー、Codex が「ターミナルで動くエージェント」というレイヤーを担う。Cursor は VS Code をベースにしているため統合ターミナルを標準で持ち、そのターミナルは普段のシェルと同じように任意の CLI を実行できる。したがって Codex を Cursor で使うとは、技術的には「Cursor が開いているプロジェクトの統合ターミナルで Codex CLI を起動する」ことに等しい。エディタを乗り換える必要も、Codex 専用のウィンドウへ移る必要もない。

Cursor のターミナルから Codex を起動する手順

導入は次の順序で進めると迷いにくい。各ステップは独立しているので、すでに済んでいる項目は飛ばしてよい。

1. Cursor で対象のプロジェクトフォルダを開く。Codex はプロジェクトのルートを基準に動くため、リポジトリの最上位を開いておく。
2. 統合ターミナルを表示する。メニューから Terminal を開くか、ショートカットでパネルを呼び出す。ここで開くシェルは普段使っているものと同じで、特別な設定は要らない。
3. Codex CLI をインストールする。npm を使う場合は npm install -g @openai/codex を実行する。導入後に codex --version でバージョンを確認しておくと、後述のつまずきを切り分けやすい(出典: https://github.com/openai/codex )。
4. 初回の認証を済ませる。codex を起動すると ChatGPT アカウントでのサインインか API キーの設定を求められるので、案内に従って認証する。一度通れば以降は省略される(出典: https://developers.openai.com/codex/cli/ )。
5. プロジェクトのルートで codex と入力して起動する。対話プロンプトが立ち上がったら、依頼したい作業を自然文で書く。

Step 起動後の基本的な進め方

起動直後の Codex には、まず狙いを一文で渡すとよい。たとえば「このリポジトリのテストが落ちている原因を調べて直して」のように、対象と期待結果をはっきり書くと、Codex が関連ファイルを読みながら変更案を提示する。変更を適用する前に承認を挟む設計のため、提案内容を Cursor 側のエディタで確認しながら可否を判断できる。Cursor のファイルツリーと Codex の差分提示を見比べる流れが、併用時の標準的な作業リズムになる。

AGENTS.md でプロジェクトの前提を渡す

Codex はプロジェクト直下に置いた AGENTS.md を起動時に読み込み、そこに書いたルールを前提として扱う。Cursor から起動した場合も読み込み対象は同じなので、リポジトリ固有の約束ごとは一度ここへ書いておけば、起動経路によらず一貫した動きになる(出典: https://developers.openai.com/codex/cli/ )。

AGENTS.md に書くと効果が高いのは、ビルドやテストの実行コマンド、ディレクトリ構成の意味、命名やフォーマットの方針、触ってほしくない領域の明示といった「人間なら口頭で補足する暗黙知」だ。これを明文化しておくと、Codex が的外れな変更を出す確率が下がり、承認のやり取りも短くなる。Cursor 側にもプロジェクトのルールを伝える仕組みがあるが、それぞれ読む先が違うため、Codex に守らせたい内容は AGENTS.md に書くのが筋になる。両方を併用するなら、IDE 補完向けの指示と、エージェント実行向けの指示を取り違えないよう、どちらに何を書くかを最初に決めておくとよい。

Cursor の内蔵エージェントと Codex の使い分け

同じプロジェクトに二つの AI がいると、どちらに頼むべきか迷う。判断の軸は「作業がエディタ密着か、タスク一括か」に置くと整理しやすい。

• 1 ファイル内の補完や、選択範囲のリファクタ、その場の小さな書き換えは Cursor の内蔵機能が速い。エディタのカーソルと連動するため往復が短い。
• 複数ファイルにまたがる修正、テストを回しながらの不具合調査、定型的な雛形生成といった「まとまった単位の作業」は Codex に投げると、ファイル横断の実行を一連で引き受けてくれる。
• レビュー前の下調べを Codex に任せ、出てきた変更を Cursor のエディタで読みながら微修正する、という二段構えも実用的だ。

この使い分けは固定ルールではなく、プロジェクトやその日の作業内容で寄せ方が変わる。重要なのは「片方に統一しなければならない」と思い込まないことで、Cursor のターミナルに Codex が同居している以上、依頼先はタスク単位で選び直せる。

よくあるつまずきと対処

最初の数回でつまずく箇所はおおむね決まっている。事前に把握しておくと切り分けが速い。

1. codex が見つからない場合は、グローバルインストールが通っているかを codex --version で確認する。表示されないときは npm のグローバル領域へパスが通っていない可能性がある。
2. 認証で止まる場合は、ChatGPT アカウントでのサインインか API キー設定のどちらを使うかを決め、案内どおりに再実行する。Cursor の統合ターミナルでも手順は通常のターミナルと同じだ(出典: https://developers.openai.com/codex/cli/ )。
3. 変更が勝手に適用されないのは不具合ではなく仕様だ。Codex は既定で適用前に承認を求めるため、提案が出たら可否を返す必要がある。承認の挙動を変えたい場合は公式が示す設定に沿って調整する(出典: https://github.com/openai/codex )。
4. プロジェクトのルール通りに動かないと感じたら、AGENTS.md の記載が不足していないかを見直す。暗黙の前提を書き足すだけで挙動が安定することが多い。

なお Cursor 側の機能や料金、対応プランは更新が速いため、最新の仕様は公式チェンジログで確認するのが確実だ(出典: https://cursor.com/changelog )。

まとめ

Codex を Cursor で使うことの本質は、エディタを乗り換える話ではなく、Cursor の統合ターミナルという既にある場所で Codex CLI を動かす話に尽きる。インストールと初回認証を済ませ、AGENTS.md にプロジェクトの前提を書いておけば、Cursor の補完・会話と Codex のエージェント実行を同じウィンドウの中で役割分担できる。IDE 密着の細かな編集は Cursor、ファイル横断のまとまったタスクは Codex、という軸で依頼先を選び分ければ、二つを無理なく同居させられる。まずは手元のプロジェクトを Cursor で開き、ターミナルから codex を一度起動するところから始めるのがいちばん早い(出典: https://github.com/openai/codex / https://docs.cursor.com )。