Installing Clawdbot on Windows (via WSL2)

Clawdbot on Windows is primarily supported through WSL2 (Windows Subsystem for Linux). Native Windows support is not yet complete (no standalone .exe or GUI app). Official documentation recommends WSL2 for best compatibility, allowing you to run a Linux environment on Windows and use the same CLI and Gateway features as Linux. This guide covers Windows 10/11 (as of early 2026). Prerequisites: Windows 10 build 19041+ or Windows 11, virtualization enabled (check VT-x/AMD-V in BIOS).

Installation Steps

Step 1: Install WSL2 + Ubuntu

Open PowerShell as Administrator (Win + X → Windows PowerShell (Admin))
Run one-command install:
```
wsl --install
```
This automatically installs WSL2 and default Ubuntu distribution (if not already installed).
Restart computer (if prompted)
First Ubuntu launch: Search "Ubuntu" in Start menu, open terminal, set username and password
Update Ubuntu:
```
sudo apt update && sudo apt upgrade -y
```
Enable systemd (required for Gateway installation, WSL2 doesn't enable by default):
- Edit /etc/wsl.conf (create if doesn't exist):
```
sudo nano /etc/wsl.conf
```
  Add content:
```
[boot]
systemd=true
```
- Save and exit, restart WSL: In PowerShell run wsl --shutdown, then reopen Ubuntu terminal

Step 2: Install Node.js and Dependencies in WSL Ubuntu

Install Node.js v22+ (recommended using NodeSource):

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Verify: node --version (should be ≥ v22) and npm --version
Optional: Install pnpm (faster):
```
npm install -g pnpm
```

Step 3: Install Clawdbot CLI

Global installation:

npm install -g clawdbot@latest

Or with pnpm:

pnpm add -g clawdbot@latest

Verify: clawdbot --version

Step 4: Run Onboarding and Install Daemon

Run setup wizard (installs Gateway as service):
```
clawdbot onboard --install-daemon
```
This guides you through configuring API keys (Claude/OpenAI), channels (WhatsApp, Telegram, etc.), and skills. Daemon installs as systemd service for background operation (though WSL restart after Windows reboot requires manual WSL restart).
For local models like Ollama, install in WSL first (curl -fsSL https://ollama.com/install.sh | sh), then specify in configuration

Step 5: Configure Gateway and Test

Start Gateway (if not automatic):
```
clawdbot gateway --port 18789
```
Connect channels: clawdbot channels login (e.g., scan WhatsApp QR code)
Test: From Windows browser, access http://127.0.0.1:18789/ (Gateway dashboard), or send commands to Clawdbot from phone messaging app
Configuration stored in WSL's ~/.clawdbot/

The entire process typically takes 15-30 minutes. Clawdbot in WSL can access Windows filesystem (via /mnt/c/), but browser automation features run Chromium instances in WSL (requires additional headless configuration). For 24/7 operation, keep WSL terminal open or use Task Scheduler to auto-start WSL + Clawdbot.

Common Issues and Solutions

Windows user feedback indicates WSL2 installation is relatively stable, but common issues center on WSL configuration, permissions, and service persistence. Below are common problems from official troubleshooting, GitHub issues, and community sources (YouTube/Reddit/X), sorted by frequency. Diagnostic tool: run clawdbot doctor to check issues.

Issue	Description	Solution
WSL not installed or wrong version	`wsl --install` fails, or WSL1 instead of WSL2.	Ensure Windows is updated; manually enable: In "Turn Windows features on or off", check "Windows Subsystem for Linux" and "Virtual Machine Platform"; run `wsl --set-default-version 2`; refer to Microsoft official: learn.microsoft.com/windows/wsl/install.
systemd not enabled, daemon install fails	`clawdbot onboard --install-daemon` errors with "systemd not available".	In WSL, create/edit `/etc/wsl.conf` add `[boot] systemd=true`; `wsl --shutdown` to restart WSL; verify: `systemctl --version` should show systemd.
Node.js installation fails or version too low	npm command unavailable, or dependency errors.	Reinstall v22+ with NodeSource script; if using nvm: `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh \| bash`, then `nvm install 22`.
Gateway service not persistent, stops after Windows restart	After daemon install, WSL shutdown loses service.	WSL services need manual restart: Use Windows Task Scheduler to create task (trigger: at logon), action: `wsl -d Ubuntu -u $USER -- clawdbot gateway`; or keep WSL terminal open.
Port conflicts or localhost access fails	Dashboard `127.0.0.1:18789` won't open, or browser tools fail.	Check Windows Firewall allows port; in WSL bind `--host 0.0.0.0`; use Windows browser to access WSL localhost (requires WSL2 network bridging); kill processes: `pkill node`.
Channel connection issues (WhatsApp QR not showing)	QR code doesn't render in WSL terminal, or expires.	Use `clawdbot channels login --debug`; ensure WSL has network; or use Windows browser proxy to access Gateway UI for scanning; reset: `clawdbot channels reset whatsapp`.
Permission or path issues	npm global install fails, or file access errors.	Use sudo install (not recommended long-term); set npm prefix: `npm config set prefix ~/.npm-global` and add to PATH; WSL file permissions: `chmod -R 755 ~/.clawdbot`.
Performance/memory insufficient	Crashes when running in WSL, especially on low-spec PCs.	Increase WSL memory in Windows settings (.wslconfig file: `[wsl2] memory=4GB`); add Windows swap; upgrade hardware or use cloud VPS instead.
Browser automation not working	Playwright/CDP can't launch Chromium.	Install dependencies in WSL: `sudo apt install -y chromium-browser libnss3 libatk-bridge2.0-0`; configure headless mode; or use remote browser (like Browserless).
Update or compatibility issues	WSL conflicts after Windows updates.	Run `wsl --update`; reinstall Clawdbot: `npm uninstall -g clawdbot && npm install -g clawdbot@latest`; check GitHub issues (e.g., tool call bugs).

Most issues stem from WSL's inherent characteristics. Community feedback shows once systemd and Node are configured, subsequent use is smooth. Native Windows support (standalone app) is on the roadmap but currently relies on WSL. If you encounter specific error logs, share for detailed analysis.