Windows (WSL2)

Run OpenClaw on Windows via WSL2 (Ubuntu recommended). Full Linux experience with consistent tooling and compatibility.

WSL2 (Windows Subsystem for Linux 2) is the recommended way to run OpenClaw on Windows. It provides a full Ubuntu Linux environment inside Windows, giving you identical tooling and compatibility to native Linux — the same bash scripts, Node.js binaries, and system services work without modification. OpenClaw also supports native Windows (PowerShell), but WSL2 is more stable and better tested. Setup is straightforward: run `wsl --install` in PowerShell to install WSL2 with Ubuntu, open the Ubuntu terminal, and run the standard OpenClaw installer script. From the WSL2 terminal, everything works exactly as it does on a native Linux machine — systemd services, npm global installs, channel integrations, the full stack. The gateway persists as a systemd user service inside WSL2. Native Windows support exists but has caveats. The PowerShell installer (`install.ps1`) handles basic CLI use, and the gateway can run natively using Windows Scheduled Tasks or Startup folder for auto-launch. However, some features are still maturing on native Windows — `openclaw onboard --non-interactive` requires `--skip-health` when no gateway is running, and Scheduled Task creation can sometimes hang or be denied by group policy. If Scheduled Tasks fail, OpenClaw falls back to a Startup folder login item. For headless Windows setups (servers, unattended machines), enable WSL2 linger so the gateway starts on boot without a user login: `sudo loginctl enable-linger $(whoami)` inside WSL. This is essential for always-on deployments on Windows machines that may reboot for updates. Native Windows companion apps are planned but not yet available — for now, the Control UI in a browser provides the management interface.

Tags: windows, wsl2, local

Use Cases

  • Windows users who want a full Linux-compatible OpenClaw deployment without dual-booting
  • Developers on Windows who use WSL2 for their regular development workflow
  • Quick personal AI assistant setup on a Windows desktop or laptop
  • Organizations with Windows-standardized machines that need AI agent capabilities

Tips

  • Enable systemd in WSL2: add [boot] systemd=true to /etc/wsl.conf and restart WSL with wsl --shutdown
  • Keep all OpenClaw files inside the WSL2 filesystem (~/) for best performance — cross-filesystem access is 10x slower
  • Enable loginctl enable-linger for headless/always-on deployments so the gateway survives logout and reboots
  • Access the Control UI at http://127.0.0.1:18789/ from your Windows browser — WSL2 ports are auto-forwarded
  • Use Windows Terminal for the best WSL2 experience — it supports tabs, profiles, and proper Unicode rendering
  • For native Windows without WSL2, use openclaw onboard --non-interactive --skip-health to bypass health checks during setup
  • Add Windows Defender exclusions for the WSL2 filesystem to prevent scan-induced performance degradation

Known Issues & Gotchas

  • WSL2 requires Windows 10 version 2004+ or Windows 11 — older Windows versions are not supported
  • systemd must be enabled in /etc/wsl.conf ([boot] systemd=true) for the gateway service to work — some WSL2 installs don't enable this by default
  • WSL2 doesn't start automatically on boot by default — enable loginctl enable-linger for always-on deployments
  • Windows Defender may flag Node.js or OpenClaw processes — add exceptions for the WSL2 filesystem to avoid performance issues
  • File I/O between Windows and WSL2 filesystems is slow — keep OpenClaw files inside the WSL2 filesystem (/home/), not on /mnt/c/
  • Native Windows PowerShell install works for CLI use but the gateway is more stable inside WSL2
  • If using Scheduled Tasks on native Windows, group policy may block task creation — the fallback uses the Startup folder instead

Alternatives

  • Linux (Direct)
  • Docker (on Windows)
  • macOS (Local)
  • Cloud VPS

Community Feedback

Run OpenClaw in two commands on WSL2/Ubuntu. The WSL2 path gives you identical behavior to a native Linux machine — no Windows-specific quirks.

— Medium

Setting up OpenClaw on Windows is straightforward if you go the WSL2 route. Native PowerShell works but WSL2 is where the tooling is battle-tested.

— LinkedIn

OpenClaw WSL Quick Setup for Windows 11 — three commands and you're running. The hard part is remembering to enable systemd in wsl.conf.

— GitHub Gist

WSL2 with systemd support is the most reliable path. Native Windows works for basic CLI interactions but the full gateway experience is better inside WSL.

— Meta Intelligence

Frequently Asked Questions

Should I use WSL2 or native Windows?

WSL2 is recommended. It gives you full Linux compatibility, systemd integration, and battle-tested tooling. Native Windows works for basic CLI use but has more edge cases and missing features.

Does OpenClaw auto-start on Windows boot?

In WSL2, enable loginctl enable-linger and install the systemd service with openclaw onboard --install-daemon. On native Windows, it uses Scheduled Tasks or a Startup folder item. WSL2 may need manual configuration to start on boot.

Can I access the Control UI from my Windows browser?

Yes. WSL2 automatically forwards ports to the Windows host. Open http://127.0.0.1:18789/ in any Windows browser after starting the gateway in WSL2.

Why is OpenClaw slow on Windows?

The most common cause is file operations crossing the WSL2/Windows filesystem boundary. Keep all OpenClaw files inside the WSL2 filesystem (/home/user/) — not on /mnt/c/. Also add Windows Defender exclusions for the WSL2 filesystem.

Is a native Windows companion app planned?

Yes, native Windows companion apps are planned but not yet available. Currently, you can use the Control UI in your browser and the CLI from WSL2 or PowerShell for full functionality.

Can I use WhatsApp on WSL2?

Yes. The QR code flow works in the WSL2 terminal. After initial linking, WhatsApp runs headlessly. You can also use the Control UI in your Windows browser for the QR scan.