Skip to main content

How to Install OpenClaw on Windows (WSL) — The Complete Guide

I spent an entire evening and morning installing OpenClaw on Windows WSL. This guide documents every step, every error, and every fix — so you can do it in under 3 hours instead of 12.

What you'll have at the end: A fully working OpenClaw agent running 24/7 on your Windows machine, connected to your messaging platform (Feishu/Lark, Telegram, Discord, etc.), powered by a cloud AI model.

Before You Start​

What You Need​

  • Windows 10/11 with WSL2 enabled
  • 8GB+ RAM (16GB recommended)
  • An AI model API key — one of the following:
    • ChatGPT Plus subscription (uses OAuth, no extra cost)
    • OpenAI API key (pay-as-you-go)
    • Anthropic (Claude) API key
    • OpenRouter account (access multiple models)
  • A messaging platform account — Feishu/Lark, Telegram, Discord, or WhatsApp
  • Stable internet connection (if you're in China, you'll need mirror configurations — covered below)

Time Estimate​

StepTime
WSL + Node.js setup15-30 min
Install OpenClaw10-20 min
Install Homebrew10-30 min (varies by network)
Run onboard wizard20-30 min
Configure messaging platform15-30 min
Install skills & fix dependencies20-40 min
Total1.5-3 hours

Step 1: Set Up WSL2​

If you already have WSL2 running, skip to Step 2.

Open PowerShell as Administrator and run:

wsl --install

Restart your computer when prompted. After reboot, a Ubuntu terminal will open automatically. Set your username and password — remember this password, you'll need it for sudo commands later.

Verify WSL2 is working:

wsl --version

You should see WSL version 2.x.

Why WSL and not native Windows?

OpenClaw's official installer detects Windows and recommends WSL2. Most AI tools are built for Linux. Running in WSL2 gives you better compatibility, faster file operations, and proper permission management. Think of it as running a Linux computer inside your Windows machine.

Step 2: Install Node.js​

Inside your WSL terminal, install Node.js using nvm (Node Version Manager). Don't use apt install nodejs — it usually installs an outdated version.

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Reload your shell
source ~/.bashrc

# Install Node.js 22 (LTS)
nvm install 22

# Verify
node -v  # Should show v22.x.x
npm -v   # Should show 10.x.x

Step 3: Install OpenClaw​

Now install OpenClaw globally:

npm install -g openclaw@latest

What to expect:

  • You'll see some npm warn deprecated messages — these are harmless warnings, not errors.
  • The install downloads large packages including AI model libraries (~500MB+). This takes 5-10 minutes.
  • The terminal may appear "stuck" with a spinning cursor (|, /, -, \). This is normal. It's compiling native modules in the background.
If it seems stuck for more than 10 minutes

If you're in China and the download is extremely slow, use a mirror:

npm install -g openclaw@latest --registry=https://registry.npmmirror.com

How to know it succeeded:

openclaw --version
# Should output: 2026.x.x

If you see a version number, congratulations — OpenClaw is installed.

Step 4: Install Homebrew (Critical for Skills)​

Many OpenClaw skills depend on tools installed via Homebrew. Without Homebrew, most skills will fail to install.

Standard Installation​

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

⚠️ If You're in China: Use a Mirror​

The standard Homebrew installer downloads from GitHub, which is often blocked or extremely slow in China. You'll see errors like:

error: RPC failed; curl 56 GnuTLS recv error (-9)
fatal: early EOF
Failed 5 times doing: /usr/bin/git fetch

Fix: Use the Chinese community mirror script:

/bin/bash -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"

When prompted, select 1 (Tsinghua University mirror) for the fastest speed.

After Installation: Configure Your Shell (Don't Skip This!)​

After Homebrew installs, it shows "Next steps" with commands you must run. They look like this:

(echo; echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"') >> ~/.bashrc
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"

Verify it works:

brew --version
# Should output: Homebrew 4.x.x

Also Install uv (Python Package Manager)​

Some skills require uv. Install it now to avoid errors later:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

Step 5: Run the Onboard Wizard​

This is the interactive setup that configures your AI model, messaging platform, and skills.

openclaw onboard --install-daemon

The wizard walks you through several choices. Here's what to pick:

5.1 Choose Your AI Model (The "Brain")​

You'll see options like:

  • OpenAI Codex (ChatGPT OAuth) — uses your existing ChatGPT Plus/Pro subscription
  • OpenAI API — pay-per-use, requires API key
  • Anthropic (Claude) — great for coding tasks
  • OpenRouter — access multiple models through one API
Which model to choose?

If you have ChatGPT Plus: Select "OpenAI Codex (ChatGPT OAuth)". This lets you use GPT-5.4 without extra API costs. The wizard will give you a URL to open in your browser, log into ChatGPT, and paste a callback URL back into the terminal.

If you want maximum flexibility: Select "OpenRouter". You can switch between GPT-5.4, Claude, Gemini, and more through one account. Costs a few dollars per month for typical usage.

If you don't want to spend anything: You can run a local model via Ollama, but expect much slower responses without a GPU.

5.2 Choose Your Messaging Platform​

Select the platform you want to chat with OpenClaw through. The wizard supports Telegram, Discord, WhatsApp, Feishu/Lark, Slack, and more.

5.3 Choose Your Search Provider​

You'll see options including Brave Search, Gemini (Google Search), Perplexity, and others.

Recommended: Gemini (Google Search) — it provides the best global coverage and has a generous free tier. You'll need a Gemini API key from Google AI Studio.

5.4 Install Skills​

The wizard shows a list of optional skills. Select with Space, confirm with Enter.

Recommended starter skills:

  • 🐙 github — interact with GitHub repos
  • 📄 nano-pdf — read and summarize PDFs
  • 🧾 summarize — summarize long documents
  • 🧩 clawhub — OpenClaw's official plugin hub

Don't select everything — you can always add more later with openclaw skill install <name>.

Skill installation may fail initially

If you see errors like "brew not installed" or "uv not installed", don't panic. Complete the wizard first, then fix these with openclaw doctor --fix (covered in Step 7).

Step 6: Connect Feishu/Lark (If You Chose It)​

If you selected Feishu/Lark as your messaging platform, you need to create a self-built app in the Feishu Developer Console.

6.1 Create a Feishu App​

  1. Go to open.feishu.cn
  2. Click Developer Console → Create App → Enterprise Self-built App
  3. In Credentials & Basic Info, copy your App ID and App Secret
  4. Under App Features → Bot, click Enable

6.2 Configure Permissions​

In the Feishu developer console, enable these permissions:

  • im:message — send and receive messages
  • im:message.p2p_msg:readonly — read direct messages
  • im.message.receive_v1 — event subscription for receiving messages

6.3 Connection Mode​

The wizard asks you to choose between WebSocket and Webhook.

Choose WebSocket (default). It works behind NAT/firewalls without needing a public URL. The agent connects outward to Feishu's servers, so it works even on your home network.

In the Feishu developer console, go to Event Subscriptions and enable "Receive events via WebSocket".

6.4 Group Chat Policy​

Choose Allowlist for safety. This means the agent only responds in groups you explicitly approve. You can always change this later.

To find your group's chat_id: add the bot to a group, send it a message, and check the OpenClaw logs for:

[Feishu] Ignoring message from unauthorized group: oc_xxxxx

Copy that oc_xxxxx ID into your allowlist config.

6.5 Publish Your App​

Important: In Feishu developer console, go to Version Management & Publishing, create a new version, and approve it. The app won't work until published.

Step 7: Fix Dependencies with Doctor​

After completing the wizard, run the diagnostic tool:

openclaw doctor --fix

This scans your setup and automatically fixes issues. Common fixes include:

  • Installing missing Homebrew packages (gh, ffmpeg, poppler-utils)
  • Setting up the systemd service for 24/7 operation
  • Enabling system lingering (keeps the agent running after you close the terminal)

If you still have 45+ missing skill requirements​

Make sure Homebrew and uv are properly installed, then:

source ~/.bashrc
openclaw doctor --fix

If some skills still fail, you can install their dependencies manually:

# For GitHub skill
brew install gh

# For PDF skills
brew install poppler

# For media skills
brew install ffmpeg

Step 8: Start Your Agent​

If the systemd service was set up during onboard:

systemctl --user start openclaw-gateway.service
systemctl --user enable openclaw-gateway.service

Or start manually:

openclaw gateway start

Verify It's Running​

systemctl --user status openclaw-gateway.service

You should see active (running).

Step 9: Test It!​

Go to your messaging platform and send a message to your OpenClaw bot. Try these:

  • What can you do? — see available capabilities
  • Search today's AI news and summarize — tests search + summarization
  • List files in my home directory — tests local system access
  • Remind me to check email in 30 minutes — tests scheduling
Your First "Wow" Moment

Try asking OpenClaw to analyze a topic in depth. For example: "Research the latest developments in AI agents, analyze the top 3 frameworks, and send a summary to my chat." The quality and depth of the response will surprise you — it feels like having a senior analyst on call 24/7.

Troubleshooting​

Homebrew installation stuck / network errors​

Symptom: Terminal shows remote: Enumerating objects: 323889 and then errors like GnuTLS recv error.

Fix: Use the Chinese mirror script:

/bin/bash -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"

npm install stuck with spinning cursor​

Symptom: Terminal shows a spinning | / / / - / \ with no progress for 10+ minutes.

Fix:

  1. Press Ctrl+C to cancel
  2. Try with verbose output: npm install -g openclaw@latest --verbose
  3. If in China, add mirror: --registry=https://registry.npmmirror.com

Feishu bot not responding​

Symptom: You send messages but get no reply.

Checklist:

  1. Is the gateway running? Check with systemctl --user status openclaw-gateway.service
  2. Did you publish the app version in Feishu developer console?
  3. Is the bot added to the group?
  4. Is the group's chat_id in your allowlist? Check logs for Ignoring message from unauthorized group
  5. Did you enable WebSocket event subscription in Feishu console?

Permission errors after security hardening​

Symptom: You tightened permissions and now features stopped working.

Fix: OpenClaw uses a tiered permission system. Start with broader permissions, test that everything works, then gradually restrict. You can always check current permissions with:

openclaw security audit --deep

Duplicate Feishu plugin warning​

Symptom: duplicate plugin id detected warning in doctor output.

Fix: Move the duplicate extension out of the extensions directory:

mv ~/.openclaw/extensions/feishu ~/feishu_plugin_backup
openclaw doctor

Memory search not working​

Symptom: Doctor shows "no embedding provider configured".

Fix: Set up Gemini as your embedding provider:

openclaw config set agents.defaults.memorySearch.provider google
echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

What's Next?​

Now that OpenClaw is running, explore these guides:

  • Get Daily AI News Delivered Automatically — set up automated news briefings
  • Use OpenClaw as a Coding Assistant — pair programming with your agent
  • Configure Advanced Skills — expand what your agent can do
  • Security Best Practices — lock down permissions properly

This guide was written from real installation experience on Windows 11 + WSL2 (Ubuntu) in March 2026. OpenClaw version: 2026.3.8. If you find any steps that are outdated, please let us know.