# WSLが `wsl --install -d ` で進まない/失敗するときの切り分け手順 AIコーディングエージェント（Codex CLI等）をWSL経由でWindows上から使おうとして、 `wsl --install -d Ubuntu` がインストール0%のまま固まる、または後続のカーネル更新 パッケージ適用で失敗するケースの原因切り分け手順。特に「非対話・非管理者権限で動く 自動化エージェント（AIコーディングツール等）」からこの状況に遭遇したときに、 どこまでが自動化可能でどこからが人間の物理操作を要するかを明確にする。 ## 症状パターンと原因の対応表 | 症状 | 原因 | 自動化可否 | |---|---|---| | `wsl --install -d Ubuntu` がダウンロード段階(0%)で止まる | ネットワーク起因のカーネル更新パッケージDL失敗 | 手動カーネルパッケージ（`wsl_update_x64.msi`、Microsoft公式配布）を別途ダウンロード・インストールしてから再実行で解決することが多い | | `HCS_E_HYPERV_NOT_INSTALLED` エラー | **BIOSでハードウェア仮想化(Intel VT-x / AMD-V)が無効** | **自動化不可・真の物理操作**（BIOS/UEFI画面に入って設定変更が必要） | | `Get-WindowsOptionalFeature` / `dism` が "requires elevation" で失敗 | 実行中のシェルが管理者権限で起動されていない | 管理者権限のシェルを人間に1回開いてもらう必要がある（UAC昇格は非対話プロセスから突破不可能） | | WSL機能有効化直後に再起動せず進めて失敗 | Windows機能の有効化は再起動して初めて反映される | 再起動を促すだけで自動化可能（再起動自体は`shutdown /r /t N`で非管理者でも予約可能） | ## 診断コマンド（PowerShell、非管理者権限で実行可） ```powershell # 1. 現在のシェルが管理者権限か確認（これがFalseなら多くの操作が失敗する） [Security.Principal.WindowsPrincipal]::new([Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltinRole]::Administrator) # 2. WSLのインストール試行（エラーメッセージに真の原因が出る。文字化けする場合はUTF-8指定でも改善しないことがあるため、 # エラーコード文字列（HCS_E_HYPERV_NOT_INSTALLED等）で判定するほうが確実） wsl --install -d Ubuntu --no-launch ``` ## 自動化エージェントとしての対処方針 1. まず非対話・非管理者のまま `wsl --install` を試す 2. 詰まったら上記診断コマンドでエラーコードを取得し、上の対応表で原因を分類する 3. **BIOS操作が必要と判明したら、それ以上ソフトウェア側の回避策を探さない**（`--allow-native`等の 代替フラグを試すより先に、これは人間にしか実行できない操作だと認めて報告する） 4. 人間にBIOS操作を依頼する際は、機種依存（起動キーがDel/F2/F10等）のため汎用的な案内文言にし、 「仮想化（Virtualization Technology / VT-x / SVM Mode）を有効にする」という設定名を明示する 5. BIOS変更ができない/したくない場合の代替手段（AIコーディングツールの提供元が持つ他の実行系統、 例：ネイティブ実行モード、別のサンドボックス方式等）があれば、それを次善策として使う。ただし ネイティブ実行モードには「ファイル書き込みが保存されない」等の既知の制約があることが多いため、 実際に使う前に軽微なテストで書き込みが反映されるか確認してから本番作業に使うこと ---