OpenAI Codex インストール・アップデート手順（Volta環境）

結論：やるべきこと

Volta環境でCodexをインストール・アップデートする場合は、以下のコマンドを使う：

volta install @openai/codex

確認：

codex --version

Voltaがパッケージを直接管理するため、npm install -g より安全で確実。

問題の概要

Volta環境でCodexのインストールやアップデートを行う際、以下のようなエラーが発生することがある：

Volta error: Could not remove directory
at C:\Users\<ユーザー名>\AppData\Local\Volta\tools\image\packages\@openai/codex

Please ensure you have correct permissions to the Volta directory.

主な原因

Windows環境では以下の要因でエラーが発生しやすい：

• ファイルロック: 他のプロセスがファイルを使用中
• 権限不足: 管理者権限が必要な場合がある
• 不完全な前回インストール: 中断されたインストールの残骸

この問題はClaude Codeでも発生する。詳細はClaude Code バージョン管理トラブルシューティングを参照。

解決策

方法1: volta installを使う（推奨）

volta install @openai/codex

バージョン確認：

codex --version

方法2: アンインストールしてから再インストール

volta install でエラーが出る場合、まずアンインストールを試す：

volta uninstall @openai/codex
volta install @openai/codex

方法3: 手動でディレクトリを削除（最終手段）

上記で解決しない場合のみ、手動削除を行う。

重要: @openai/codex だけを削除し、他の @openai/* パッケージを巻き込まないこと。

PowerShellで削除：

# Codexディレクトリのみを削除
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Volta\tools\image\packages\@openai\codex" -ErrorAction Stop

# 再インストール
volta install @openai/codex

Git Bashで削除（PowerShellで失敗する場合）：

rm -rf "$LOCALAPPDATA/Volta/tools/image/packages/@openai/codex"

PowerShellで削除できない場合、ファイルがロックされている可能性がある。Git Bashは異なる方法でファイルにアクセスするため、成功することがある。

削除後、PowerShellで再インストール：

volta install @openai/codex

方法4: 特定バージョンを指定してインストール

最新版でエラーが発生する場合、別のバージョンを試す。

利用可能なバージョンを確認：

npm view @openai/codex versions --json

特定バージョンをインストール：

volta install @openai/[email protected]

失敗時の戻し方：

# 問題のあるバージョンをアンインストール
volta uninstall @openai/codex

# 動作確認済みのバージョンを再インストール
volta install @openai/[email protected]

トラブルシューティング

権限エラーが続く場合

1. 使用中のプロセスを確認: codex を使用しているターミナルをすべて閉じる
2. 管理者権限で実行: PowerShellを管理者として起動して再試行
3. 権限を確認:

   Get-Acl "$env:LOCALAPPDATA\Volta\tools\image\packages\@openai\codex"
   

エラーログの確認

Voltaはエラー詳細をログに書き出す：

Get-Content "$env:LOCALAPPDATA\Volta\log\volta-error-*.log" | Select-Object -Last 50

Voltaでのグローバルパッケージ管理

Voltaを使っている場合、npmグローバルパッケージもVolta経由で管理される。

ディレクトリ構成

C:\Users\<ユーザー名>\AppData\Local\Volta\
├── bin\
│   └── codex.exe  ← 実際に呼ばれるshim
└── tools\
    └── image\
        └── packages\
            └── @openai\
                └── codex\  ← 実際のパッケージ

Voltaコマンド一覧

Claude CodeとCodexの比較（インストール方法）

AGENTS.mdの設定方法についてはCustom instructions with AGENTS.mdを参照。

参考リンク

• EACCESS permission issue with npm install -g @openai/codex
• Cannot update codex
• npm global installation fails on Windows - Volta
• Custom instructions with AGENTS.md - OpenAI

まとめ

1. Volta環境では volta install を使う
2. エラー時は volta uninstall → volta install を試す
3. 手動削除は最終手段、@openai/codex のみを対象にする
4. 権限エラーが続く場合はファイルロックや権限設定を確認