WSL2におけるCodex実行エラー解決レポート

1. 現象

WSL2 (Ubuntu) 環境で codex コマンドを実行した際、以下のエラーが発生して起動に失敗する。

エラー内容:

Error: Missing optional dependency @openai/codex-linux-x64. Reinstall Codex: npm install -g @openai/codex@latest

発生時の状況:

  • Windows側には codex がインストールされている。
  • Claude や Gemini などの他のCLIツールは問題なく動作していた。
  • type -a codex を確認すると、Windows側のパス（/mnt/c/...）が優先、あるいは唯一の実行元として認識されていた。

2. 原因分析

今回のエラーは、「OSアーキテクチャの不一致」と「コマンド検索パスの優先順位」の2点に起因していました。

  • バイナリ依存性の問題:Claude 等は純粋なJavaScriptのみで動作するため、Windows側のファイルをLinux版Node.jsで実行可能。一方、Codex は実行速度やサンドボックス機能のためにLinux専用のバイナリ部品を必要とする。Windows側にインストールされたパッケージにはこのLinux用部品が含まれないためエラーとなった。
  • パスの混在:WSL2の環境変数 $PATH にWindows側のnpmパスが含まれており、Linux側に実体がない状態で codex と打つと、自動的にWindows側の不適切なバイナリを呼び出していた。

3. 解決策

Windows側とUbuntu側の環境を「共有」するのではなく、それぞれに最適なバイナリを「共存」させる構成に変更しました。

手順 A: WSL2側への直接インストール

WSL2のターミナルから、Linux環境専用のパッケージをインストール。

Bash

# WSL2内のNode.js環境にインストール
npm install -g @openai/codex@latest

手順 B: 実行優先順位の確認と修正

type -a codex を実行し、Ubuntu側のパス（/home/c2kp/...）がリストの先頭に来ていることを確認。

手順 C: シェルキャッシュのリセット

パスが正しくても古い記憶（ハッシュ）でWindows側を見に行く場合があるため、以下のコマンドでリセット。

Bash

hash -r

4. 補足：追加の最適化

Codexが安全にコードを実行するための隔離環境（サンドボックス）を構築するため、Ubuntu側に不足していた依存パッケージを導入しました。

Bash

sudo apt update && sudo apt install -y bubblewrap

5. 最終結果

  • 動作: codex コマンドだけで、Linux専用バイナリを用いた正常起動を確認。
  • 共存: Windows環境（PowerShell等）ではWindows版、WSL2環境ではLinux版が、それぞれ $PATH の優先順位に従って自動的に使い分けられる状態となった。
  • モデル: GPT-5.5 (Agentic model) へのアクセスおよびコード解析機能が正常に動作中。

AI,プログラム開発

Posted by iwadjp