Windows & WSL2 Setup
How ClawManager installs and runs OpenClaw on Windows using WSL2 and Ubuntu, with automatic setup for everything you need.
Why WSL2?
OpenClaw is built for Linux and macOS. On Windows, it runs inside WSL2 (Windows Subsystem for Linux), which provides a full Linux environment without the overhead of a virtual machine.
ClawManager handles the entire setup process automatically. You don't need to touch the command line. Just click Install OpenClaw and ClawManager will:
- • Detect whether WSL2 is available
- • Install Ubuntu 24.04 if needed
- • Enable systemd (required for the gateway service)
- • Install Node.js, npm, Git, and other prerequisites inside WSL
- • Install OpenClaw and start the gateway
- • Set up port forwarding so ClawManager (on the Windows side) can reach the gateway (inside WSL)
System Requirements
Where to Find It
The setup wizard appears automatically when you first launch ClawManager and OpenClaw isn't installed yet. You can also access it anytime:
- • Standard View: Globe icon in the top bar, then 🏠 Home category, then 🚀 Setup tab
- • Advanced View: Setup page in the sidebar
🚀 The Setup Flow
ClawManager runs a series of checks when the Setup page loads. Depending on your system state, you'll see one of three scenarios:
Scenario 1: WSL2 not installed
ClawManager detects that WSL isn't available and shows a blue info panel explaining what will happen. Clicking Install OpenClaw runs:
- • An elevated PowerShell window opens (Windows will ask for admin approval)
- • Windows may require a reboot to complete WSL2 installation
- • After reboot, reopen ClawManager and the installer picks up where it left off
Scenario 2: WSL2 installed, systemd disabled
ClawManager detects that WSL is present but systemd (needed for the gateway service) is off. This is common on older WSL setups. An amber panel explains the fix.
Clicking Install OpenClaw automatically updates /etc/wsl.conf, restarts WSL (takes a few seconds), then continues with the full install.
No reboot needed for this step. WSL restarts in a few seconds, then setup continues automatically.
Scenario 3: WSL2 ready, OpenClaw not installed
WSL and systemd are good to go. ClawManager shows a security notice (see below) and the Install OpenClaw button. One click handles everything:
- • Installs or updates Node.js, npm, and Git inside WSL
- • Installs OpenClaw via npm
- • Preserves any existing configuration
- • Starts the gateway service
- • Sets up Windows port forwarding (so ClawManager on the Windows side can connect to the gateway inside WSL)
🔒 Security Notice
Before installing, ClawManager shows a security warning that you must read and accept. The key points:
Beta software
OpenClaw installs a local AI gateway that can execute shell commands, read and write files, and call external APIs on your behalf.
Personal by default
Your agent runs under your user account. Fine for a personal machine, but not safe for shared or multi-user servers without additional lock-down.
Recommended baseline
- • Keep
~/.openclaw/owned by your user with700permissions - • Review tool permissions before enabling powerful tools
- • Do not expose the gateway port to untrusted networks
You must check the "I understand this is personal-by-default" checkbox before the Install button becomes active.
System Checks
The Setup page runs automatic checks on your system. Each shows a status indicator:
| Check | What it verifies |
|---|---|
| WSL | WSL2 available, distro detected (name, version) |
| Node.js | Installed and version 18+ |
| npm | Package manager available |
| Git | Version control installed |
| CA Certificates | SSL certificates present (needed for HTTPS) |
| OpenClaw | Installed, version, and binary path |
| Config | Configuration file exists and is valid |
| Auth | At least one AI provider configured with a default model |
| Gateway Service | Systemd service installed (checks systemd is enabled) |
| Gateway Running | Gateway process active and dashboard reachable |
Click Refresh status at any time to re-run all checks. This is useful after a reboot or manual fix.
Installer Output
During installation, a collapsible output panel shows live progress. You can expand it to see exactly what the installer is doing. If something fails, the error details appear here.
The installer is safe to re-run. If it fails partway through (e.g. a network issue), click Refresh status then Install OpenClaw again. It picks up where it left off and preserves any existing configuration.
Port Forwarding (Automatic)
WSL2 has its own network namespace, meaning the gateway running inside WSL isn't directly reachable from Windows at 127.0.0.1:18789.
After a successful install, ClawManager automatically sets up a Windows port proxy (using netsh) so that 127.0.0.1:18789on the Windows side forwards to the gateway inside WSL. This happens silently in the background.
If the port proxy fails (e.g. due to permissions), ClawManager logs it but doesn't block you. You can retry by clicking Refresh status.
✅ After Setup
When all checks pass, you see a green checkmark: OpenClaw installed and gateway running. From here, the Setup Wizard continues with:
- 1. Hatch Your Agent — name, personality, emoji
- 2. Connect a Model — add an AI provider
- 3. Configure Tools — choose a tool preset
These steps are the same on all platforms. See Getting Started for the full walkthrough.
🔧 Troubleshooting
❓ WSL install asks for a reboot
This is normal for first-time WSL2 installs. Reboot, then reopen ClawManager. The Setup page will detect the newly installed WSL and continue.
❓ "Systemd is disabled" keeps showing
Try restarting WSL manually. Open PowerShell and run wsl --shutdown, wait 5 seconds, then click Refresh status in ClawManager.
❓ Gateway not reachable after install
The port proxy may not have been set up. Open an elevated PowerShell and run: netsh interface portproxy add v4tov4 listenport=18789 listenaddress=127.0.0.1 connectport=18789 connectaddress=127.0.0.1Then click Refresh status.
❓ Install failed partway through
Click Refresh status then Install OpenClaw again. The installer is idempotent and picks up where it left off. Check the installer output panel for specific error messages.
❓ Virtualization not enabled
WSL2 requires hardware virtualization. Restart your PC, enter BIOS/UEFI settings, and enable VT-x (Intel) or AMD-V (AMD). The exact menu location varies by motherboard manufacturer.
Next Steps
Continue with the Getting Started guide to set up your first agent, or head to Troubleshooting for more help. For security best practices, see Security.