なぜNemoClawにWSL2が必要なのか
NemoClawのサンドボックス（OpenShellコンテナ）はLinux上で動作する設計のため、Windows環境ではWSL2（Windows Subsystem for Linux 2）が必須です。
WSL2はWindowsカーネル上で実際のLinuxカーネルを動作させる仕組みで、従来のWSL1と比較して以下の利点があります。
- 完全なLinuxカーネル互換 — Dockerがネイティブに動作
- GPU Passthrough — NVIDIA GPUをWSL2内で直接利用可能
- ファイルシステム性能 — Linuxネイティブのext4ファイルシステムで高速なI/O
- Dockerの完全サポート — Docker Desktop WSL2バックエンドにより低オーバーヘッド
WSL2でNemoClawを動かすためのシステム要件
| 項目 | 最低要件 | 推奨 |
|---|---|---|
| OS | Windows 10 21H2 | Windows 11 Pro |
| CPU | 4 vCPU | 8コア以上 |
| メモリ | 8GB | 16GB以上（32GB推奨） |
| ストレージ | SSD 20GB空き | SSD 100GB以上 |
| GPU（ローカル推論時） | GeForce GTX 1060 6GB | GeForce RTX 4060 Ti 16GB以上 |
| WSLカーネル | 5.10.43.3以上 | 最新版 |
| Docker Desktop | 4.30以上 | 最新版 |
Cloud NIM推論のみ使用する場合はGPU不要です。ローカル推論（nim-local / vLLM）を使用する場合はNVIDIA GPUが必要です。
WSL2のセットアップ手順
Step 1: WSL2の有効化
PowerShellを管理者権限で開き、以下のコマンドを実行します。
# WSL2を一括インストール（Windows 10 21H2以降 / Windows 11）
wsl --install
# 再起動を求められたら再起動する手動で有効化する場合は以下の2つの機能を個別に有効化します。
# 仮想マシンプラットフォームの有効化
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
# WSLの有効化
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
# PC再起動後にWSL2をデフォルトに設定
wsl --set-default-version 2Step 2: Ubuntu 22.04 LTSのインストール
# Ubuntu 22.04 LTSをインストール
wsl --install -d Ubuntu-22.04
# インストール確認
wsl -l -v
# NAME STATE VERSION
# Ubuntu-22.04 Running 2初回起動時にユーザー名とパスワードを設定します。このパスワードはsudoコマンドで使用します。
注意: VERSIONが「1」になっている場合は、以下で変換してください。
wsl --set-version Ubuntu-22.04 2Step 3: WSL2のリソース設定
WSL2はデフォルトでホストマシンの50%のメモリを使用します。NemoClaw用に適切なリソースを割り当てます。
WindowsのC:\Users\ユーザー名\.wslconfigファイルを作成（または編集）します。
[wsl2]
memory=8GB
swap=4GB
processors=4
localhostForwarding=trueメモリ32GBのPCではmemory=12GB、64GBのPCではmemory=16GBに設定することを推奨します。
設定変更後、WSL2を再起動します。
# PowerShellで実行
wsl --shutdown
# 再度Ubuntu起動で新しい設定が適用されるNVIDIA GPU Passthroughの設定
WSL2でNVIDIA GPUを使用するための設定手順です。NemoClawでローカル推論を行う場合に必要です。
NVIDIA GPUドライバのインストール（Windows側）
重要: ドライバはWindows側にのみインストールします。WSL2内にはインストールしないでください。
- NVIDIA公式サイトから最新のドライバをダウンロード
- インストール後、PCを再起動
- WSL2のUbuntuを起動
# WSL2内でGPU認識を確認
nvidia-smi
# 出力例:
# +------------------------------------------+
# | NVIDIA-SMI 560.xx Driver Version: 560.xx|
# | CUDA Version: 12.x |
# +------------------------------------------+
# | GPU Name | Memory-Usage |
# | 0 RTX 4090 | 300MiB / 24564MiB |
# +------------------------------------------+CUDA Toolkitのインストール（WSL2内）
vLLMプロファイルでローカル推論を行う場合は、WSL2内にCUDA Toolkitをインストールします。
# CUDA Toolkit 12.x（WSL-Ubuntu用）
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-wsl-ubuntu.pin
sudo mv cuda-wsl-ubuntu.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/12.4.0/local_installers/cuda-repo-wsl-ubuntu-12-4-local_12.4.0-1_amd64.deb
sudo dpkg -i cuda-repo-wsl-ubuntu-12-4-local_12.4.0-1_amd64.deb
sudo cp /var/cuda-repo-wsl-ubuntu-12-4-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cuda-toolkit-12-4
# パス設定
echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
# 確認
nvcc --version注意: Cloud NIMやnim-localプロファイルを使用する場合、CUDA Toolkitのインストールは不要です。
Docker Desktop GPU対応の有効化
Docker DesktopがWSL2内のGPUを認識できるように設定します。
- Docker Desktop → Settings → General → 「Use the WSL 2 based engine」にチェック
- Settings → Resources → WSL Integration → Ubuntu-22.04を有効化
# GPU対応Dockerコンテナの動作確認
docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi
# ホストと同じGPU情報が表示されればOK--gpus allオプションが使用できない場合は、NVIDIA Container Toolkitをインストールしてください。
# NVIDIA Container Toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart dockerNemoClawのインストール（WSL2内）
WSL2のUbuntuターミナルを開き、以下の手順でNemoClawをインストールします。
依存パッケージのインストール
# システム更新
sudo apt update && sudo apt upgrade -y
# Node.js 20 LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# Python 3.11+
sudo apt install -y python3 python3-pip python3-venv
# その他必要パッケージ
sudo apt install -y git curl build-essential
# バージョン確認
node --version # v20.x.x
python3 --version # Python 3.11.x
docker --version # Docker version 27.x.xNemoClawインストールとセットアップ
# プロジェクトディレクトリはLinuxファイルシステム内に作成
cd ~
mkdir -p projects && cd projects
# NemoClawインストール
curl -fsSL https://nvidia.com/nemoclaw.sh | bash
# 初回セットアップ
nemoclaw setup
# GPU搭載: Option 2 (nim-local) を選択
# GPU非搭載: Option 1 (Cloud NIM) を選択重要: プロジェクトファイルは必ず/home/ユーザー名/以下に作成してください。/mnt/c/以下（Windowsのマウントパス）では性能が大幅に低下し、パーミッションの問題も発生します。
WSL2環境でのトラブルシューティング
「No assignable GPU found」エラー
特にWindows Homeで発生する既知のバグ（GitHub Issue #152）です。
チェックリスト:
- WindowsのNVIDIAドライバが最新版か確認
- WSL2を再起動: PowerShellで
wsl --shutdown後に再起動 - WSL2内で
nvidia-smiが正常出力するか確認 - Docker内で
docker run --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smiが動くか確認 - すべて正常なのにNemoClawがGPUを認識しない場合 → Cloud NIMに切り替え
nemoclaw config set inference.provider cloud-nimセットアップのStep 7で無限ループ
サンドボックス検出が無限ループに入る場合の対処法です。
- Docker Desktopを完全に再起動（Quit → 再起動）
.wslconfigのメモリ設定を確認（8GB以上を推奨）- WSL2を再起動:
wsl --shutdown - NemoClawのセットアップをリセット:
nemoclaw setup --reset
Docker Desktopの「Troubleshoot → Reset to factory defaults」も有効ですが、既存のコンテナ・イメージが全て削除されるため注意してください。
ネットワーク接続の問題
WSL2はデフォルトでNAT接続を使用するため、企業ネットワーク（VPN接続時など）で名前解決の問題が発生することがあります。
# DNSの問題が疑われる場合
cat /etc/resolv.conf
# nameserver が不正な場合は以下で修正
# resolv.confの自動生成を無効化
sudo sh -c 'echo "[network]\ngenerateResolvConf = false" > /etc/wsl.conf'
# DNSを手動設定
sudo sh -c 'echo "nameserver 8.8.8.8\nnameserver 8.8.4.4" > /etc/resolv.conf'
# WSL再起動
# PowerShellで: wsl --shutdownディスク容量不足
WSL2の仮想ディスク（ext4.vhdx）は自動で拡張されますが、縮小はされません。ディスク容量が逼迫した場合の対処法です。
# WSL2内のディスク使用状況確認
df -h /
# Dockerのディスク使用状況
docker system df
# 不要なDockerリソースを削除
docker system prune -a --volumesNemoClawのサンドボックスイメージだけで約10〜20GBを消費するため、WSL2のディスクイメージに50GB以上の空きを確保しておくことを推奨します。
WSL2でのパフォーマンス最適化
- ファイルはLinuxファイルシステムに配置 —
/mnt/c/ではなく/home/以下を使用。I/O性能が10〜100倍向上 - VS Code Remote WSL拡張を使用 — Windows側のVS Codeから直接WSL2内のファイルを編集。ファイルコピー不要
- メモリの適切な割り当て —
.wslconfigでWSL2のメモリ上限を設定し、Windowsとのバランスを取る - 不要なディストリビューションを停止 — 使用しないWSLディストリビューションは
wsl --terminateで停止 - Docker BuildKitの有効化 — 環境変数
DOCKER_BUILDKIT=1でビルド高速化