docs: add Windows prerequisites page and WSL troubleshooting

.agents/skills/nemoclaw-user-get-started/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "nemoclaw-user-get-started"
-description: "Installs NemoClaw, launches a sandbox, and runs the first agent prompt. Use when onboarding, installing, or launching a NemoClaw sandbox for the first time."
+description: "Installs NemoClaw, launches a sandbox, and runs the first agent prompt. Use when onboarding, installing, or launching a NemoClaw sandbox for the first time. There are additional Windows-only prerequisites before the Quickstart to install NemoClaw on Windows."
 ---
 
 <!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
@@ -90,6 +90,10 @@ curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uni
 
 For troubleshooting installation or onboarding issues, see the Troubleshooting guide (see the `nemoclaw-user-reference` skill).
 
+## Reference
+
+- [Windows Prerequisites for NemoClaw](references/windows-setup.md)
+
 ## Related Skills
 
 - `nemoclaw-user-configure-inference` — Switch inference providers to use a different model or endpoint

.agents/skills/nemoclaw-user-get-started/references/windows-setup.md

@@ -0,0 +1,96 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+# Windows Prerequisites
+
+NemoClaw runs inside Windows Subsystem for Linux (WSL 2) on Windows.
+Complete these steps before following the Quickstart (see the `nemoclaw-user-get-started` skill).
+Linux and macOS users do not need this page and can go directly to the Quickstart.
+
+> **Note:** This guide has been tested on x86-64.
+
+## Prerequisites
+
+Verify the following before you begin:
+
+- Windows 10 (build 19041 or later) or Windows 11.
+- Hardware requirements are the same as the Quickstart (see the `nemoclaw-user-get-started` skill).
+
+## Enable WSL 2
+
+Open an elevated PowerShell (Run as Administrator):
+
+```console
+$ wsl --install --no-distribution
+```
+
+This enables both the Windows Subsystem for Linux and Virtual Machine Platform features.
+
+Reboot if prompted.
+
+## Install and Register Ubuntu
+
+After reboot, open an elevated PowerShell again:
+
+```console
+$ wsl --install -d Ubuntu
+```
+
+Let the distribution launch and complete first-run setup (pick a Unix username and password), then type `exit` to return to PowerShell.
+
+> **Warning:** Do not use the `--no-launch` flag.
+> The `--no-launch` flag downloads the package but does not register the distribution with WSL.
+> Commands like `wsl -d Ubuntu` fail with "There is no distribution with the supplied name" until the distribution has been launched at least once.
+
+Verify the distribution is registered and running WSL 2:
+
+```console
+$ wsl -l -v
+```
+
+Expected output:
+
+```text
+  NAME      STATE           VERSION
+* Ubuntu    Running         2
+```
+
+## Install Docker Desktop
+
+Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) with the WSL 2 backend (the default on Windows 11).
+
+After installation, open Docker Desktop Settings and confirm that WSL integration is enabled for your Ubuntu distribution (Settings > Resources > WSL integration).
+
+Verify from inside WSL:
+
+```console
+$ wsl
+$ docker info
+```
+
+`docker info` prints server information.
+If you see "Cannot connect to the Docker daemon", confirm that Docker Desktop is running and that WSL integration is enabled.
+
+## Set Up Local Inference with Ollama (Optional)
+
+If you plan to select Ollama as your inference provider during onboarding, install it inside WSL before running the NemoClaw installer:
+
+```console
+$ curl -fsSL https://ollama.com/install.sh | sh
+```
+
+If Ollama is also running on the Windows side, quit it before running `nemoclaw onboard` (system tray > right-click > Quit).
+The Windows and WSL instances bind to the same port and conflict.
+
+The onboarding process starts Ollama in WSL if it is not already running.
+You can also start it yourself beforehand with `ollama serve`.
+
+## Next Step
+
+Your Windows environment is ready.
+Open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with the Quickstart (see the `nemoclaw-user-get-started` skill) to install NemoClaw and launch your first sandbox.
+
+All NemoClaw commands run inside WSL, not in PowerShell.
+
+## Troubleshooting
+
+For Windows-specific troubleshooting, see the Windows Subsystem for Linux section (see the `nemoclaw-user-reference` skill) in the Troubleshooting guide.

.agents/skills/nemoclaw-user-reference/references/troubleshooting.md

@@ -376,6 +376,72 @@ $ nemoclaw <name> logs
 
 Use `--follow` to stream logs in real time while debugging.
 
+(windows-wsl-2)=
+
+## Windows Subsystem for Linux
+
+For environment setup steps, see Windows Prerequisites (see the `nemoclaw-user-get-started` skill).
+
+### `wsl --install --no-distribution` returns Forbidden (403)
+
+Check your network connectivity.
+If you are behind a VPN, try reconnecting or switching to a different network.
+
+### `wsl -d Ubuntu` says "There is no distribution with the supplied name"
+
+The Ubuntu package was installed with `--no-launch` but never registered.
+Run `ubuntu.exe install --root` from PowerShell to register it, or reinstall without `--no-launch`:
+
+```console
+$ wsl --unregister Ubuntu
+$ wsl --install -d Ubuntu
+```
+
+### `docker info` fails inside WSL
+
+Confirm that Docker Desktop is running and that WSL integration is enabled for Ubuntu (Settings > Resources > WSL integration).
+Then restart WSL:
+
+```console
+$ wsl --shutdown
+$ wsl -d Ubuntu
+$ docker info
+```
+
+### Ollama inference fails or hangs in WSL
+
+Ollama configures context length based on your hardware.
+On some GPUs (for example RTX 3500), the default context length is not sufficient for OpenClaw.
+Force a larger context length:
+
+```console
+$ pkill -f 'ollama serve'
+$ OLLAMA_CONTEXT_LENGTH=16384 ollama serve
+```
+
+Verify that Ollama inference works:
+
+```console
+$ echo "Hello" | ollama run <model-id>
+```
+
+Replace `<model-id>` with the model you selected during onboarding (for example `qwen3.5:4b`).
+
+If `ollama serve` fails with `Error: listen tcp 127.0.0.1:11434: bind: address already in use`, check whether Ollama is configured for automatic startup:
+
+```console
+$ sudo systemctl status ollama
+```
+
+If it is active, stop it first, then start with the custom context length:
+
+```console
+$ sudo systemctl stop ollama
+$ OLLAMA_CONTEXT_LENGTH=16384 ollama serve
+```
+
+For additional troubleshooting, see the Quickstart (see the `nemoclaw-user-get-started` skill) and Windows Setup (see the `nemoclaw-user-get-started` skill) pages.
+
 ## Podman
 
 Podman is not a tested runtime.

docs/get-started/windows-setup.md

@@ -0,0 +1,120 @@
+---
+title:
+  page: "Windows Prerequisites for NemoClaw"
+  nav: "Windows Prerequisites"
+description:
+  main: "Complete these steps on Windows before running the NemoClaw Quickstart: enable WSL 2, install Ubuntu, and configure Docker Desktop."
+  agent: "There are additional Windows-only prerequisites before the Quickstart to install NemoClaw on Windows."
+keywords: ["nemoclaw windows wsl2 setup", "nemoclaw install windows docker desktop"]
+topics: ["generative_ai", "ai_agents"]
+tags: ["openclaw", "openshell", "sandboxing", "nemoclaw", "windows", "wsl"]
+content:
+  type: reference
+  difficulty: technical_beginner
+  audience: ["developer", "engineer"]
+status: published
+---
+
+<!--
+  SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+# Windows Prerequisites
+
+NemoClaw runs inside Windows Subsystem for Linux (WSL 2) on Windows.
+Complete these steps before following the [Quickstart](quickstart.md).
+Linux and macOS users do not need this page and can go directly to the Quickstart.
+
+:::{note}
+This guide has been tested on x86-64.
+:::
+
+## Prerequisites
+
+Verify the following before you begin:
+
+- Windows 10 (build 19041 or later) or Windows 11.
+- Hardware requirements are the same as the [Quickstart](quickstart.md).
+
+## Enable WSL 2
+
+Open an elevated PowerShell (Run as Administrator):
+
+```console
+$ wsl --install --no-distribution
+```
+
+This enables both the Windows Subsystem for Linux and Virtual Machine Platform features.
+
+Reboot if prompted.
+
+## Install and Register Ubuntu
+
+After reboot, open an elevated PowerShell again:
+
+```console
+$ wsl --install -d Ubuntu
+```
+
+Let the distribution launch and complete first-run setup (pick a Unix username and password), then type `exit` to return to PowerShell.
+
+:::{warning}
+Do not use the `--no-launch` flag.
+The `--no-launch` flag downloads the package but does not register the distribution with WSL.
+Commands like `wsl -d Ubuntu` fail with "There is no distribution with the supplied name" until the distribution has been launched at least once.
+:::
+
+Verify the distribution is registered and running WSL 2:
+
+```console
+$ wsl -l -v
+```
+
+Expected output:
+
+```text
+  NAME      STATE           VERSION
+* Ubuntu    Running         2
+```
+
+## Install Docker Desktop
+
+Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) with the WSL 2 backend (the default on Windows 11).
+
+After installation, open Docker Desktop Settings and confirm that WSL integration is enabled for your Ubuntu distribution (Settings > Resources > WSL integration).
+
+Verify from inside WSL:
+
+```console
+$ wsl
+$ docker info
+```
+
+`docker info` prints server information.
+If you see "Cannot connect to the Docker daemon", confirm that Docker Desktop is running and that WSL integration is enabled.
+
+## Set Up Local Inference with Ollama (Optional)
+
+If you plan to select Ollama as your inference provider during onboarding, install it inside WSL before running the NemoClaw installer:
+
+```console
+$ curl -fsSL https://ollama.com/install.sh | sh
+```
+
+If Ollama is also running on the Windows side, quit it before running `nemoclaw onboard` (system tray > right-click > Quit).
+The Windows and WSL instances bind to the same port and conflict.
+
+The onboarding process starts Ollama in WSL if it is not already running.
+You can also start it yourself beforehand with `ollama serve`.
+
+## Next Step
+
+Your Windows environment is ready.
+Open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with the [Quickstart](quickstart.md) to install NemoClaw and launch your first sandbox.
+
+All NemoClaw commands run inside WSL, not in PowerShell.
+
+## Troubleshooting
+
+For Windows-specific troubleshooting, see the [Windows Subsystem for Linux section](../reference/troubleshooting.md#windows-subsystem-for-linux) in the Troubleshooting guide.

docs/index.md

@@ -241,6 +241,7 @@ Release Notes <about/release-notes>
 :hidden:
 
 Quickstart <get-started/quickstart>
+Windows Prerequisites <get-started/windows-setup>
 ```
 
 ```{toctree}

docs/reference/troubleshooting.md

@@ -406,6 +406,72 @@ $ nemoclaw <name> logs
 
 Use `--follow` to stream logs in real time while debugging.
 
+(windows-wsl-2)=
+
+## Windows Subsystem for Linux
+
+For environment setup steps, see [Windows Prerequisites](../get-started/windows-setup.md).
+
+### `wsl --install --no-distribution` returns Forbidden (403)
+
+Check your network connectivity.
+If you are behind a VPN, try reconnecting or switching to a different network.
+
+### `wsl -d Ubuntu` says "There is no distribution with the supplied name"
+
+The Ubuntu package was installed with `--no-launch` but never registered.
+Run `ubuntu.exe install --root` from PowerShell to register it, or reinstall without `--no-launch`:
+
+```console
+$ wsl --unregister Ubuntu
+$ wsl --install -d Ubuntu
+```
+
+### `docker info` fails inside WSL
+
+Confirm that Docker Desktop is running and that WSL integration is enabled for Ubuntu (Settings > Resources > WSL integration).
+Then restart WSL:
+
+```console
+$ wsl --shutdown
+$ wsl -d Ubuntu
+$ docker info
+```
+
+### Ollama inference fails or hangs in WSL
+
+Ollama configures context length based on your hardware.
+On some GPUs (for example RTX 3500), the default context length is not sufficient for OpenClaw.
+Force a larger context length:
+
+```console
+$ pkill -f 'ollama serve'
+$ OLLAMA_CONTEXT_LENGTH=16384 ollama serve
+```
+
+Verify that Ollama inference works:
+
+```console
+$ echo "Hello" | ollama run <model-id>
+```
+
+Replace `<model-id>` with the model you selected during onboarding (for example `qwen3.5:4b`).
+
+If `ollama serve` fails with `Error: listen tcp 127.0.0.1:11434: bind: address already in use`, check whether Ollama is configured for automatic startup:
+
+```console
+$ sudo systemctl status ollama
+```
+
+If it is active, stop it first, then start with the custom context length:
+
+```console
+$ sudo systemctl stop ollama
+$ OLLAMA_CONTEXT_LENGTH=16384 ollama serve
+```
+
+For additional troubleshooting, see the [Quickstart](../get-started/quickstart.md) and [Windows Setup](../get-started/windows-setup.md) pages.
+
 ## Podman
 
 Podman is not a tested runtime.