Tools: Running OpenClaw on Windows and Linux: Cross-Platform Guide (2026)

Tools: Running OpenClaw on Windows and Linux: Cross-Platform Guide (2026)

Windows: Why WSL2 and Not Native?

Step-by-Step: OpenClaw on Windows via WSL2

Step 1: Install WSL2 and Ubuntu

Step 2: Enable systemd (Required for Gateway Service)

Step 3: Install Node and OpenClaw

Step 4: Access the Gateway UI

Step 5: Auto-Start Before Windows Login (Headless)

Exposing WSL Services Over Your LAN

Native Linux: Clean and Straightforward

Step 1: Install Node 24

Step 2: Install OpenClaw

Manual Service Setup (Optional)

Headless Linux: Auto-Start Without Login

VPS Quick Path

Shared Troubleshooting: Both Platforms

Gateway won't start

Gateway starts but immediately exits

Can't reach the gateway from another machine

Channel plugins working on macOS but not Linux

Platform Feature Matrix

My Recommendation

Next Steps Most OpenClaw guides assume macOS. But I run in plenty of environments where macOS isn't on the table — Linux servers, Windows machines, headless VPS instances, developer workstations. The good news: OpenClaw runs well on all of them. The setup is just slightly different depending on your platform. This guide covers both Windows (the WSL2 path) and Linux (native install). By the end, you'll have OpenClaw running as a persistent background service, auto-starting on boot, and ready to take your config. You can run OpenClaw natively on Windows, and it works — partially. The CLI basics (openclaw --version, openclaw doctor, openclaw plugins list --json) are fine. But the full gateway experience — daemon management, channel plugins, skills with Linux binaries — needs the Linux runtime. That's what WSL2 gives you. WSL2 isn't a VM you have to babysit. It runs Ubuntu (or any Linux distro) directly inside Windows, with near-native performance. Once it's set up, you mostly forget it's there. Your OpenClaw instance runs inside Ubuntu, but it's accessible from Windows and your local network like any other service. If you're on Windows 10 (build 19041+) or Windows 11, WSL2 is a single command away: That command installs WSL2 and Ubuntu in one shot. Reboot when asked, then open the Ubuntu terminal that appears in your Start menu. Open PowerShell as Administrator and run: Or, if you want a specific Ubuntu version: Reboot if prompted. This is a one-time step. OpenClaw's gateway installs as a systemd user service. WSL2 doesn't enable systemd by default — you need to turn it on manually. Inside your WSL/Ubuntu terminal: Then from PowerShell: Re-open the Ubuntu terminal and verify systemd is running: You should see a running user session tree — not an error. If you skip this step, openclaw gateway install will silently fall back to a startup-folder approach that's less reliable. Inside your WSL/Ubuntu terminal, install Node 24 (recommended): Then install OpenClaw globally: Run the onboarding wizard: This installs the gateway, configures it, and registers a systemd user service. After onboarding, your gateway runs persistently and restarts automatically. The gateway runs on port 18789 inside WSL, but you can reach it from Windows via localhost — WSL2 handles the port forwarding automatically in most cases. Open your Windows browser and navigate to: http://localhost:18789/ If that doesn't work (can happen on older Windows versions), use the WSL IP directly: Take the first IP from that output and use it in the URL. If you're running a Windows machine headlessly — like a home server or a machine you remote into — you'll want OpenClaw to start even before anyone logs in. 1. Enable linger (so your WSL user services start without a login session): 2. Verify gateway service is enabled: 3. Make WSL start at Windows boot (PowerShell as Administrator): Replace Ubuntu with your distro name (wsl --list --verbose to check). After this, the full chain is: Windows boots → WSL2 starts → systemd starts → OpenClaw gateway starts. No login required. WSL runs in a virtual network with its own IP. If you want to reach OpenClaw from another machine on your LAN (or pair nodes remotely), you need to forward a Windows port to the WSL instance. WSL IPs change on restart, so you need a script that refreshes the rule. In PowerShell as Administrator: Other machines on your LAN can then reach OpenClaw at http://<windows-host-ip>:18789/. Use openclaw status --all to confirm remote nodes can connect. On a native Linux machine — Ubuntu, Debian, Fedora, or any standard distro — the setup is more direct. No WSL layer, no portproxy workarounds. Just Node, npm, and systemd. The OpenClaw docs are clear on this: Node is the recommended runtime on Linux. Bun is experimental and has known issues with WhatsApp and Telegram channel plugins. Use Node 24 (or Node 22 LTS as a fallback). Then run the interactive setup: This creates a systemd user service, starts the gateway, and walks you through initial config. The service installs to ~/.config/systemd/user/openclaw-gateway.service. After onboarding, verify the service is running: If you prefer to manage the service yourself — or if onboarding didn't install it — create the unit file manually: Same as WSL — enable linger so your user services survive when nobody is logged in: On most servers this is already set. But it's worth confirming if you're running in a minimal cloud environment. If you're spinning up a fresh VPS (DigitalOcean, Hetzner, Linode) and want OpenClaw running in minutes: That SSH tunnel is important — it keeps the gateway UI local to your machine even though the process runs on the VPS. Don't expose port 18789 directly to the internet. Run the diagnostics tool first: This checks your installation, service status, and common misconfigurations. It often tells you exactly what's wrong and how to fix it. Check the service logs: Common causes: port conflict on 18789, missing config file, or a channel plugin failing to authenticate. On Linux, check that nothing is blocking port 18789: On Windows/WSL, double-check the portproxy rule is set and the firewall allows the port. Run openclaw status --all to see what the agent can reach. This is almost always a Bun vs Node issue. If you installed OpenClaw with Bun on Linux, switch to Node: Here's where each platform stands today: Companion apps for Linux and Windows are planned. The gateway itself is already fully cross-platform — the companion apps are just convenience wrappers for the desktop experience. If you're on Windows and want the full OpenClaw experience: WSL2 + Ubuntu. It's a 20-minute setup and you'll never notice the WSL layer in daily use. The headless auto-start chain (linger + systemd + WSL Scheduled Task) covers the edge case of machines that don't have someone logged in at all times. If you're on Linux — native install, Node runtime, systemd user service. That's it. No WSL needed, no complications. If it's a VPS, use the SSH tunnel for UI access and keep the port firewalled. Either way, once the gateway is running and your config is in place, the platform doesn't matter much. Your agent just works. Once your gateway is running on Windows or Linux: The platform is just the foundation. What you build on top of it is the interesting part. Templates let you quickly answer FAQs or store snippets for re-use. Hide child comments as well For further actions, you may consider blocking this person and/or reporting abuse

Code Block

Copy

wsl --install wsl --install wsl --install wsl --install wsl --install wsl --install wsl --list --online wsl --install -d Ubuntu-24.04 wsl --list --online wsl --install -d Ubuntu-24.04 wsl --list --online wsl --install -d Ubuntu-24.04 sudo tee /etc/wsl.conf >/dev/null <<'EOF' [boot] systemd=true EOF sudo tee /etc/wsl.conf >/dev/null <<'EOF' [boot] systemd=true EOF sudo tee /etc/wsl.conf >/dev/null <<'EOF' [boot] systemd=true EOF wsl --shutdown wsl --shutdown wsl --shutdown systemctl --user status systemctl --user status systemctl --user status curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - sudo apt-get install -y nodejs curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - sudo apt-get install -y nodejs curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - sudo apt-get install -y nodejs npm i -g openclaw@latest npm i -g openclaw@latest npm i -g openclaw@latest openclaw onboard --install-daemon openclaw onboard --install-daemon openclaw onboard --install-daemon wsl hostname -I wsl hostname -I wsl hostname -I sudo loginctl enable-linger "$(whoami)" sudo loginctl enable-linger "$(whoami)" sudo loginctl enable-linger "$(whoami)" systemctl --user enable openclaw-gateway systemctl --user enable openclaw-gateway systemctl --user enable openclaw-gateway schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM $Distro = "Ubuntu-24.04" $ListenPort = 18789 $TargetPort = 18789 $WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0] if (-not $WslIp) { throw "WSL IP not found." } netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort ` connectaddress=$WslIp connectport=$TargetPort New-NetFirewallRule -DisplayName "OpenClaw Gateway LAN" -Direction Inbound ` -Protocol TCP -LocalPort $ListenPort -Action Allow $Distro = "Ubuntu-24.04" $ListenPort = 18789 $TargetPort = 18789 $WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0] if (-not $WslIp) { throw "WSL IP not found." } netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort ` connectaddress=$WslIp connectport=$TargetPort New-NetFirewallRule -DisplayName "OpenClaw Gateway LAN" -Direction Inbound ` -Protocol TCP -LocalPort $ListenPort -Action Allow $Distro = "Ubuntu-24.04" $ListenPort = 18789 $TargetPort = 18789 $WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0] if (-not $WslIp) { throw "WSL IP not found." } netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort ` connectaddress=$WslIp connectport=$TargetPort New-NetFirewallRule -DisplayName "OpenClaw Gateway LAN" -Direction Inbound ` -Protocol TCP -LocalPort $ListenPort -Action Allow curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - sudo apt-get install -y nodejs curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - sudo apt-get install -y nodejs curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - sudo apt-get install -y nodejs curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash - sudo dnf install nodejs curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash - sudo dnf install nodejs curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash - sudo dnf install nodejs npm i -g openclaw@latest npm i -g openclaw@latest npm i -g openclaw@latest openclaw onboard --install-daemon openclaw onboard --install-daemon openclaw onboard --install-daemon systemctl --user status openclaw-gateway systemctl --user status openclaw-gateway systemctl --user status openclaw-gateway mkdir -p ~/.config/systemd/user cat > ~/.config/systemd/user/openclaw-gateway.service <<'EOF' [Unit] Description=OpenClaw Gateway After=network-online.target Wants=network-online.target [Service] ExecStart=/usr/local/bin/openclaw gateway --port 18789 Restart=always RestartSec=5 [Install] WantedBy=default.target EOF systemctl --user daemon-reload systemctl --user enable --now openclaw-gateway mkdir -p ~/.config/systemd/user cat > ~/.config/systemd/user/openclaw-gateway.service <<'EOF' [Unit] Description=OpenClaw Gateway After=network-online.target Wants=network-online.target [Service] ExecStart=/usr/local/bin/openclaw gateway --port 18789 Restart=always RestartSec=5 [Install] WantedBy=default.target EOF systemctl --user daemon-reload systemctl --user enable --now openclaw-gateway mkdir -p ~/.config/systemd/user cat > ~/.config/systemd/user/openclaw-gateway.service <<'EOF' [Unit] Description=OpenClaw Gateway After=network-online.target Wants=network-online.target [Service] ExecStart=/usr/local/bin/openclaw gateway --port 18789 Restart=always RestartSec=5 [Install] WantedBy=default.target EOF systemctl --user daemon-reload systemctl --user enable --now openclaw-gateway sudo loginctl enable-linger "$(whoami)" sudo loginctl enable-linger "$(whoami)" sudo loginctl enable-linger "$(whoami)" openclaw doctor openclaw doctor openclaw doctor # Linux / WSL journalctl --user -u openclaw-gateway -n 50 --no-pager # Linux / WSL journalctl --user -u openclaw-gateway -n 50 --no-pager # Linux / WSL journalctl --user -u openclaw-gateway -n 50 --no-pager ss -tlnp | grep 18789 ss -tlnp | grep 18789 ss -tlnp | grep 18789 npm i -g openclaw@latest # forces Node runtime openclaw doctor npm i -g openclaw@latest # forces Node runtime openclaw doctor npm i -g openclaw@latest # forces Node runtime openclaw doctor - Provision a $4–6/month Ubuntu droplet or instance - SSH in and install Node 24 - Run npm i -g openclaw@latest - Run openclaw onboard --install-daemon - From your local machine: ssh -N -L 18789:127.0.0.1:18789 user@your-vps-ip - Open http://127.0.0.1:18789/ in your browser and paste your token - macOS: Full support — companion app, menu bar, voice control, Canvas, all channel plugins - Linux (native): Full gateway support — all channel plugins, systemd service, headless operation. No companion app yet. - Windows via WSL2: Same as Linux — full gateway, all plugins, systemd service. No native companion app. - Windows native (no WSL): CLI basics only. Gateway and channel plugins have limitations. WSL2 is the recommended path. - Set up your workspace architecture — the file structure that makes your agent persistent and intelligent - Connect to Slack or another channel so you can actually talk to your agent - Add cron jobs to automate your first daily tasks - Pair physical nodes if you want your agent to reach other machines on your network