Neovim から Codex CLI を使う方法と設定ファイルの書き方

Codex CLI を Neovim から使う準備

Codex CLI は OpenAI が提供するコマンドラインの AI コーディングエージェントだ。VS Code 拡張が必要な GitHub Copilot や Cursor とは異なり、エディタ非依存のバイナリとして動作するため、Neovim のような任意のターミナル環境からも起動できる。Neovim 側に特別なプラグインがなくても、組み込みのターミナル機能だけで Codex CLI を呼び出す最低限の環境が揃う。セットアップの手間が少ない点は、エディタを固定せず複数の環境で使い回したい開発者にとっての強みになる。CLI は npm パッケージとして配布されており、node と npm がある環境であればプラットフォームを問わず動作する（出典: https://github.com/openai/codex）。

Step 1: Codex CLI のインストール

Codex CLI は npm パッケージとして配布されている。以下のコマンドでグローバルインストールする。

npm install -g @openai/codex

Node.js と npm が入っていない場合は、https://nodejs.org から LTS 版をインストールしてから上記コマンドを実行する。インストール後、codex --version でバージョン番号が表示されれば準備完了だ。初回起動時に OpenAI API キーの入力を求められる。環境変数 OPENAI_API_KEY に設定しておくと、毎回の入力を省ける（出典: https://github.com/openai/codex）。

Step 2: Neovim 組み込みターミナルでの起動確認

Neovim には :terminal（短縮形 :term）コマンドで起動できる組み込みターミナルエミュレータがある。このターミナルバッファの中でシェルコマンドを実行できるため、追加プラグインなしで Codex CLI を呼び出せる。

1. Neovim を開いた状態で :term を実行し、ターミナルバッファを開く
2. ターミナルバッファ内で codex と入力し、インタラクティブモードを起動する
3. 正常に起動したら /help でコマンド一覧を確認する

ターミナルバッファから Neovim のノーマルモードに戻るには Ctrl+\ Ctrl+n を押す。この操作はデフォルトで設定されているため、特別な設定不要で使える。再度ターミナルモードに入るには i または a を押す。

設定ファイルの書き方

Codex CLI の動作は ~/.codex/config.toml で設定する。このファイルがない場合は初回起動時にデフォルト設定で動作するが、Neovim からの利用を念頭に置くといくつかの項目を事前に固定しておくと便利だ。設定ファイルに書いた内容はすべての Codex セッションに適用されるため、一度書けば以降の起動で同じ設定が自動的に読み込まれる。モデルや推論レベルは作業の種類に応じて変更したい場合もあるが、普段の開発で使う値をデフォルトとして設定ファイルに固定しておき、必要に応じてセッション中に /model コマンドで上書きするのが実用的な運用だ（出典: https://developers.openai.com/codex/config-reference）。

~/.codex/config.toml の基本設定

設定ファイルの代表的な項目は以下の通りだ。

model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "network-off"

model は使用するモデルを指定する。model_reasoning_effort は推論レベルで、minimal・low・medium・high・xhigh から選べる。Neovim でのコーディング作業では medium が出発点として適している。sandbox_mode は Codex がファイルを変更したりコマンドを実行する際のネットワーク・ファイルシステムの制限を設定するオプションで、network-off を指定するとネットワーク通信が制限された安全な環境で動作させられる。設定できる値の一覧は公式リファレンス（https://developers.openai.com/codex/config-reference）で確認できる。

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

AGENTS.md はプロジェクトルートに置くマークダウンファイルで、Codex がタスクを開始する前に必ず読む前提情報として機能する。Neovim でコードを書いているリポジトリに AGENTS.md を追加しておくと、依頼のたびにプロジェクト構成や制約を説明する手間が省ける。

書くべき内容の例を以下に示す。

# プロジェクト前提

- 言語: TypeScript 5.x
- テスト: `npm test`（Jest ベース）
- コードフォーマット: Prettier、`npm run format` で適用
- 触らないファイル: .env、docs/ 以下
- コミットメッセージ規約: Conventional Commits

「触らないファイル」を明示しておくことは特に重要で、Codex が意図せず関係のないファイルを変更するリスクを下げる。Neovim 上でファイルを編集しながら依頼するケースでは、現在編集中のファイルとその依存関係を意識した記述にしておくと作業の精度が上がる（出典: https://github.com/openai/codex）。

Neovim プラグインとの連携

Neovim には組み込みターミナルがあるが、プラグインを使うとキーバインドの割り当てやターミナルの管理がより便利になる。よく使われる構成は、フローティングウィンドウでターミナルを開閉できる toggleterm.nvim と Codex CLI の組み合わせだ。この構成では Codex の出力をフローティングウィンドウで確認しながら、メインのコードバッファへ素早く戻れる。Neovim の Lua 設定をすでに使っている場合は、数行の設定を追加するだけで連携環境が整う。フローティングターミナルは画面を占有せず、コードを見ながら Codex の出力を読むのに向いている（出典: https://github.com/akinsho/toggleterm.nvim）。

toggleterm.nvim でキーバインドを作る

toggleterm.nvim は Neovim のプラグインで、フローティングターミナルを任意のキーに割り当てられる。lazy.nvim でのインストール・設定例は以下の通りだ。

-- lazy.nvim での設定例
{
  "akinsho/toggleterm.nvim",
  config = function()
    require("toggleterm").setup({
      direction = "float",
      float_opts = {
        border = "curved",
      },
    })
    vim.keymap.set("n", "<leader>t", "<cmd>ToggleTerm<cr>", { noremap = true, silent = true })
  end,
}

ターミナルを開いたら codex を実行してインタラクティブモードを起動する。<leader>t を再度押すとターミナルが閉じ、コードバッファに戻れる。さらに <leader>t を押すと Codex のセッション状態を保ったまま再表示できるため、長い作業の途中でコードを読んで戻るといった操作が自然にできる。

floaterm を使う場合

floaterm（vim-floaterm）を使っている場合も同様の設定が可能だ。Vimscript での設定例は以下の通りだ。

" floaterm での設定例
let g:floaterm_width = 0.8
let g:floaterm_height = 0.8
nnoremap <leader>t :FloatermToggle<cr>
tnoremap <leader>t <C-\><C-n>:FloatermToggle<cr>

<leader>t でターミナルを開閉し、中で codex を起動する流れは toggleterm.nvim と同じだ。どちらのプラグインも Neovim の組み込みターミナルをラップしているだけなので、Codex CLI の動作自体には影響しない（出典: https://github.com/voldikss/vim-floaterm）。

実務での使い方パターン

Codex CLI を Neovim のターミナルから使う際の典型的なパターンを整理する。すべてのパターンで共通するのは、「依頼前に git 状態を確認する」「AGENTS.md で前提を渡す」「差分を必ず読む」の三点だ。この基本動作を守ることで、Codex の変更が意図した範囲に収まりやすくなり、予期しない上書きも防ぎやすい。Neovim で差分を確認するなら、:!git diff をコマンドラインモードで実行するか、diffview.nvim のようなプラグインを使うと読みやすい（出典: https://github.com/openai/codex）。

バグ修正を依頼する

バグ修正を依頼する際は、バグが再現するコマンドまたはエラーメッセージを具体的に渡す。Neovim でコードを確認した後、ターミナルバッファで Codex インタラクティブモードを開き、以下のように依頼する。

src/api/user.ts の createUser 関数で、
メールアドレスが空文字のときに TypeError が出ています。
バリデーション処理を修正してください。
変更範囲は src/api/user.ts のみに限定してください。

依頼後、Codex が変更を提案したら git diff で差分を確認する。変更が意図した範囲に収まっているか、他のファイルへの意図しない波及がないかをコードバッファで読んでから承認する。

テストコードを生成させる

テストコードの生成は Codex が得意とするタスクの一つだ。Neovim で実装ファイルを開きながら、ターミナルバッファで以下のように依頼できる。

src/utils/dateFormatter.ts の formatDate 関数について、
__tests__/dateFormatter.test.ts にユニットテストを追加してください。
- タイムゾーンが異なる場合のケース
- null・undefined が渡された場合のエラーハンドリング
- 閏年の日付処理
を含めてください。AGENTS.md を確認してください。

テスト生成後は npm test で通過を確認し、失敗したケースがあれば追加で修正を依頼する。

リファクタリングを依頼する

既存コードのリファクタリングを依頼する場合は、変更範囲を明確に絞る。「プロジェクト全体を最適化して」という広すぎる依頼は避け、「src/components/UserCard.tsx の render 関数内の条件分岐を整理する」のように対象を限定する。依頼が具体的であるほど Codex の出力が管理しやすい差分になり、レビューも短時間で終わる（出典: https://github.com/openai/codex）。

Neovim + Codex CLI の注意点と補足

Neovim から Codex CLI を利用する際に知っておくべき点を整理する。VS Code 拡張のような GUI ベースの AI コーディングツールと比べると、ターミナルベースの操作になるため差分の視覚的な確認は自分で行う必要がある。git diff、git diff --cached を活用してコードの変化を追うのが基本的な手順だ（出典: https://github.com/openai/codex）。

サンドボックスモードについては、config.toml の sandbox_mode で制御できる。network-off を設定することで Codex がネットワーク通信を行う操作を制限したまま動かせる。Neovim でローカルのコードベースを扱う場合は、外部ネットワークへのアクセスが不要なことが多いため、この設定が安全面で適している。

大規模なリポジトリで使う場合は、Codex が読み込むコンテキストの範囲を意識する。AGENTS.md で「触らないファイル」を明示することに加え、依頼文でも「src/api/ 以下のみを対象にする」のように範囲を限定するとよい。コンテキストが広すぎると応答が遅くなったり、意図しないファイルへの変更が提案されることがある。Codex CLI の context compaction 機能は v0.141 から強化されており、長時間のセッションでも作業精度が維持されやすくなっている（出典: https://github.com/openai/codex/releases）。

codex exec コマンドを使うと、非インタラクティブな単発の依頼も出せる。Neovim の :!codex exec "fix the failing test in src/api" のようにコマンドラインモードから直接実行することも可能で、インタラクティブセッションを開かずに短い作業を依頼したい場合に使える。ただし、変更内容の確認は依頼後に git diff で行う必要がある点はインタラクティブモードと同様だ（出典: https://github.com/openai/codex）。