この手順は、Codex CLI を WSL（Ubuntu）にインストールし、Windows側の VS Code を Remote - WSL で接続して利用するための備忘録的なマニュアルです。自分で調べながら実践した内容をまとめてみました。
さらに、venv_test のような 別ディレクトリの venv を必ず使って実行するために、./tools/py と ./tools/pip を作って venv固定します。
内容は記事投稿時点のものなので最新の情報は公式などを参照してください。
想定環境
- Windows + WSL2（Ubuntu）
- Windows側 VS Code（Remote - WSL を使用）
- venv 例：
~/venv_test（中にbin/pythonがある） - 編集対象例：
~/venv_test/scripts/（配下の深い階層も編集対象）
以後、
~/venv_testや~/venv_test/scriptsは環境に合わせて置き換えてください。
0) まず「WSL接続の VS Code」になっているか確認
0-1. WSL2の確認（Windows PowerShell or コマンドプロンプト）
wsl -l -v
VERSION 2 の Ubuntu が対象です。
0-2. VS Code に Remote - WSL を入れる
VS Code の拡張機能から WSL（Remote - WSL） をインストール。
0-3. WSL側でプロジェクトへ移動し、そこから VS Code を起動（推奨）
WSLターミナルで下記入力
cd ~/venv_test/scripts
code .
VS Code 左下が WSL: ... になっていればOKです。
0-4. VS Code の「統合ターミナル」が WSL か確認
VS Code で ターミナル → 新しいターミナル を開き、次を実行
uname -a
pwd
uname -a が Linux、pwd が /home/... なら WSL 側です。
1) よくある事故：WSLなのにWindows側のnpm/codexを拾って「node not found」になる
典型エラー：
/mnt/c/Users/<you>/AppData/Roaming/npm/codex: exec: node: not found
原因：WSLのPATHにWindows側のNode/npmが混ざっており、WSLなのにWindows側の npm / codex を拾っている。
1-1. まず現状確認（WSLターミナル）
type -a npm
type -a node
type -a codex
NG例
npm is /mnt/c/Program Files/nodejs/npmcodex is /mnt/c/Users/.../npm/codexnode: not found
→ 次の「nvm + Node」を入れて、WSL側に揃えます。
2) WSL側に Node.js / npm を用意（nvm 推奨）
2-1. nvm を入れる
sudo apt update
sudo apt install -y curl ca-certificates
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
source ~/.bashrc
2-2. Node を入れる（例：22）
nvm install 22
nvm use 22
nvm alias default 22
node -v
npm -v
3) Codex CLI を WSL にインストール
3-1. インストール
npm i -g @openai/codex
hash -r
3-2. 正しくWSL側の codex を拾っているか確認
which codex
codex --version
type -a codex
OK条件
-
which codexが/home/<user>/.nvm/.../bin/codexのように WSL側 -
codex --versionがcodex-cli x.y.z
type -a codexに Windows側が残って見えても、which codexが WSL側なら動作上はOKです（PATH優先順でWSLが勝っている）。
4) 新しいターミナルでも毎回nvmが有効になるよう固定（推奨）
新しいターミナルで node が消える／また Windows側に戻る場合に備えて、~/.bashrc に追記します。
4-1. 追記（WSLターミナル）
cat >> ~/.bashrc << 'EOF'
# --- Ensure nvm default node is active in interactive shells ---
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
nvm use default >/dev/null 2>&1
hash -r
EOF
4-2. 反映して確認
source ~/.bashrc
which node
node -v
which codex
codex --version
5) venv を “必ず” 使わせる（venv_test などが別ディレクトリでもOK）
Codexはコマンド実行時に環境が変わることがあるため、source activate だけに頼ると python が system 側に戻る場合があります。
一番事故が少ないのは venvの python/pip をパス固定した入口を作る方法です。
5-1. venv の python/pip の実体を確認
ls -la ~/venv_test/bin/python
ls -la ~/venv_test/bin/pip
存在しないなら、venvの実パスに合わせて以後の $HOME/venv_test を置換してください。
5-2. プロジェクトルートに tools/py と tools/pip を作る
（例：~/venv_test/scripts）
cd ~/venv_test/scripts
mkdir -p tools
cat > tools/py << 'EOF'
#!/usr/bin/env bash
exec "$HOME/venv_test/bin/python" "$@"
EOF
chmod +x tools/py
cat > tools/pip << 'EOF'
#!/usr/bin/env bash
exec "$HOME/venv_test/bin/pip" "$@"
EOF
chmod +x tools/pip
5-3. venv 固定が効いているか確認
./tools/py -c "import sys; print(sys.executable)"
./tools/pip -V
ここで .../venv_test/bin/python が出ればOKです。
6) VS Code（WSL接続）の統合ターミナルから Codex を起動
6-1. 起動場所（重要）
Codex は「起動したディレクトリ配下」を編集対象とするため、編集したい範囲を含むディレクトリで起動します。起動時にOpenAIへのログインが必要です。
例：
cd ~/venv_test/scripts
codex
6-2. 起動直後に必ず venv を確認（Codex内で実行）
Codex のプロンプトで下記入力
./tools/py -c "import sys; print(sys.executable)"
./tools/pip -V
6-3. Codex に「実行ルール」を一度だけ宣言（コピペ推奨）
Codexのプロンプトに文章で下記を指示：
- 以後、Python実行は
./tools/pyを使う - pip は
./tools/pip - pytest は
./tools/py -m pytest -
pythonやpipを直接使わない
7) pip install がCodex内で失敗する（DNS/到達不可）場合
Codex のサンドボックス設定によって、Codex内からの pip install が失敗することがあります。
選択肢A（おすすめ）：インストールだけ Codex外の通常WSLターミナルで実施
VS Codeで 別の統合ターミナルを開いて、そこで
cd ~/venv_test/scripts
./tools/pip install -U pytest
./tools/py -m pytest
選択肢B：Codex内でも pip install したい（プロジェクトだけネット許可）
プロジェクト直下に .codex/config.toml を作る
cd ~/venv_test/scripts
mkdir -p .codex
cat > .codex/config.toml << 'EOF'
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = true
EOF
反映には Codex 再起動が必要：
- Codex画面で
/quit - シェルに戻って
codex
なお、
network_accessは “true/false” の二択として提供されており、「localhostだけ許可」のような細かい制御は設定だけではできません（必要ならOS側FW等で外部制御が必要です）。
8) WSLg（GUI）が Codex 実行だと出ない場合の切り分け
手動実行ではGUIが出るのに、Codexの実行だけ Cannot connect to "None" になる場合があります。まずは状況確認。
8-1. WSLg の環境変数とソケット確認
echo "DISPLAY=$DISPLAY"
echo "WAYLAND_DISPLAY=$WAYLAND_DISPLAY"
echo "XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR"
ls -la /tmp/.X11-unix/X0 || true
ls -la /mnt/wslg/runtime-dir/wayland-0 || true
8-2. 最小 pyglet テスト（X接続できるか）
./tools/py - << 'PY'
import os
print("DISPLAY", os.environ.get("DISPLAY"))
import pyglet
w = pyglet.window.Window(visible=False, width=64, height=64)
print("window created OK")
w.close()
PY
-
window created OK→ X接続はOK。アプリ側の設定/初期化を疑う -
Cannot connect to "None"→ Codex実行の制約（サンドボックス）の影響が疑わしい-
network_access=trueにすると通る環境もあります（副作用としてGUIが通ることがある） - それでもダメなら、GUI実行は Codex外（通常WSLターミナル）に分離するのが安定です
-
9) 最終チェック（これが通れば導入完了）
WSL（VS Code統合ターミナル）で下記入力
which codex
codex --version
./tools/py -c "import sys; print(sys.executable)"
./tools/pip -V
- codex が
/home/...側 - python/pip が
~/venv_test側
になっていれば完成です。
付録：Codexの再起動方法
- Codex画面で
/quit（または/exit） - シェルプロンプトに戻ったら
codexを実行
付録：よくあるエラー早見表
A) codex: exec: node: not found
- WSLなのにWindowsのnpm/codexを拾っている
→ nvmでWSL側にNodeを入れ、which codexが/home/...になるまで直す
B) Codex内の pip install がDNSエラー/到達不可
-
network_accessが無効
→.codex/config.tomlでnetwork_access=true、またはインストールだけ通常ターミナルで実施
C) GUIが Cannot connect to "None"
- WSLgの環境変数/ソケット確認 → 最小pygletテスト
→network_access=trueで改善する場合あり。ダメならGUI実行を分離
D) CUDA初期化が Error 304
-
nvidia-smiが見えてもCUDAは別
→ Codex外（通常ターミナル）で実行を推奨。必要ならサンドボックス設定の見直し