在 Windows 上使用 WSL2 運行 OpenClaw 完整指南

OpenClaw 是一套以設定驅動的多 Agent 框架，核心元件依賴 Unix 工具鏈——Node.js 原生模組、Unix socket、以及 POSIX 檔案系統語意。 這意味著在 Windows 上直接跑 openclaw onboard 會踩到一堆地雷：路徑分隔符號不同、缺少 /proc、部分 npm 套件的 native addon 編譯失敗等等。

好消息是，Windows Subsystem for Linux 2（WSL2）幾乎完美解決了這些問題。WSL2 跑的是真正的 Linux 核心，檔案系統效能接近原生，而且從 Windows 11 22H2 起預設支援 systemd，讓你的 OpenClaw 服務可以像在真正的 Linux 伺服器上一樣運作。

本文將帶你從零開始，在 Windows 上建立一個穩定、高效能的 OpenClaw 開發與運行環境。

為什麼是 WSL2 而不是原生 Windows？

先釐清一個常見疑問：「OpenClaw 用 Node.js 寫的，Windows 也能跑 Node.js 啊？」

技術上沒錯，但實務上會遇到以下問題：

1. Unix socket 相容性：OpenClaw 的 gateway 元件使用 Unix domain socket 做 IPC。Windows 從 1803 開始雖然支援 AF_UNIX，但行為與 Linux 不完全一致，特別是在檔案權限方面。
2. Node.js native addon：部分相依套件需要 node-gyp 編譯 C++ 原始碼。在 Windows 上需要安裝 Visual Studio Build Tools，配置複雜且容易出錯。
3. Shell 腳本：OpenClaw CLI 的部分內部流程依賴 Bash 腳本，在 PowerShell 或 cmd 下無法直接執行。
4. 檔案系統語意：Linux 的大小寫敏感、symlink 處理、檔案鎖定機制與 NTFS 有根本差異。

WSL2 的優勢很明確：

第一步：安裝 WSL2

Windows 11 使用者

打開 PowerShell（以系統管理員身份），執行：

wsl --install

這條命令會自動：

• 啟用「虛擬機器平台」和「Windows 子系統 Linux 版」功能
• 下載並安裝最新的 Linux 核心
• 將 WSL2 設為預設版本
• 安裝 Ubuntu（預設發行版）

安裝完成後重新開機。

Windows 10 使用者

Windows 10 版本 2004（組建 19041）以上也支援 WSL2，但需要手動步驟：

# 啟用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 啟用虛擬機器平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

重新開機後，下載並安裝 WSL2 Linux 核心更新套件^[1]，然後設定預設版本：

wsl --set-default-version 2

最後從 Microsoft Store 安裝 Ubuntu 24.04 LTS。

驗證安裝

wsl --version

你應該看到類似輸出：

WSL 版本: 2.4.x
核心版本: 5.15.x

確認是 WSL 2：

wsl -l -v

  NAME      STATE       VERSION
* Ubuntu    Running     2

第二步：Ubuntu 初始設定

第一次啟動 Ubuntu 會要求你建立使用者帳號和密碼。設定完成後，先更新系統套件：

sudo apt update && sudo apt upgrade -y

安裝必要的開發工具

sudo apt install -y build-essential curl git

build-essential 包含 gcc、g++、make 等工具，是後續 node-gyp 編譯 native addon 的必備條件。

啟用 systemd

從 WSL 0.67.6 版開始，你可以在 WSL2 中啟用 systemd^[2]。這對後續設定 OpenClaw 常駐服務至關重要。

編輯（或建立）/etc/wsl.conf：

[boot]
systemd=true

然後在 PowerShell 中重啟 WSL：

wsl --shutdown

再次進入 Ubuntu，驗證 systemd 是否啟動：

systemctl list-unit-files --type=service | head -20

如果看到一列列的 service 檔案，表示 systemd 已經正常運作。

第三步：安裝 Node.js 22

OpenClaw 需要 Node.js 22 以上。推薦使用 NodeSource 官方 repository：

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

驗證版本：

node --version
# v22.x.x

npm --version
# 10.x.x

如果你習慣使用版本管理工具，也可以用 nvm：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

注意：使用 nvm 時，後續設定 systemd service 需要指定完整的 Node.js 路徑，因為 systemd 不會載入你的 .bashrc。

第四步：安裝並初始化 OpenClaw

安裝 OpenClaw CLI：

npm install -g openclaw

執行初始化精靈：

openclaw onboard

onboard 會引導你完成：

• 選擇 AI 模型供應商（Anthropic、OpenAI 等）
• 設定 API 金鑰
• 建立初始 Agent 設定檔
• 啟動 gateway 服務

初始化完成後，OpenClaw 的 gateway 會開始監聽。預設情況下，儀表板會綁定在 localhost:19080。

驗證 gateway 是否正常

openclaw status

你應該看到 gateway 狀態為 running，以及監聽的 port 資訊。

第五步：從 Windows 瀏覽器存取儀表板

WSL2 最方便的一點是：localhost 在 Windows 和 WSL2 之間是互通的。

直接在 Windows 的瀏覽器打開：

http://localhost:19080

你應該能看到 OpenClaw 的儀表板介面。

首次連線的裝置配對

OpenClaw 有裝置配對機制——新的瀏覽器連線需要核准。回到 WSL2 終端機：

openclaw devices list

你會看到一個 pending 狀態的裝置，核准它：

openclaw devices approve <device-id>

重新整理瀏覽器，就能正常使用儀表板了。

進階：LAN 存取設定

如果你想從同一區域網路的其他裝置（手機、平板）存取 OpenClaw 儀表板，需要做 port forwarding。

WSL2 使用虛擬網路介面卡，外部裝置無法直接連到 WSL2 的 localhost。你需要用 Windows 的 netsh 做 port proxy^[3]。

設定 portproxy

在 PowerShell（系統管理員）執行：

# 取得 WSL2 的 IP
$wslIP = (wsl hostname -I).Trim().Split(" ")[0]

# 設定 port forwarding
netsh interface portproxy add v4tov4 `
  listenport=19080 `
  listenaddress=0.0.0.0 `
  connectport=19080 `
  connectaddress=$wslIP

開放 Windows 防火牆

New-NetFirewallRule -DisplayName "OpenClaw Dashboard" `
  -Direction Inbound `
  -Protocol TCP `
  -LocalPort 19080 `
  -Action Allow

現在你可以從同一網路的任何裝置，用 http://<你的-windows-ip>:19080 存取儀表板。

注意：WSL2 IP 會變動

每次重啟 WSL2，它的 IP 可能會改變。你可以寫一個 PowerShell 腳本在開機時自動更新 portproxy：

# update-wsl-portproxy.ps1
$wslIP = (wsl hostname -I).Trim().Split(" ")[0]

netsh interface portproxy delete v4tov4 listenport=19080 listenaddress=0.0.0.0
netsh interface portproxy add v4tov4 `
  listenport=19080 `
  listenaddress=0.0.0.0 `
  connectport=19080 `
  connectaddress=$wslIP

Write-Host "Port proxy updated to WSL IP: $wslIP"

用 Task Scheduler 設定開機自動執行這個腳本。

Docker Desktop 替代方案

有些使用者偏好用 Docker 來運行 OpenClaw，而不是直接安裝在 WSL2 裡。這也是可行的，但有幾點要注意。

方案 A：Docker Desktop + WSL2 後端

Docker Desktop 可以使用 WSL2 作為後端引擎，這是最簡單的方式：

1. 安裝 Docker Desktop for Windows
2. 在設定中啟用「Use the WSL 2 based engine」
3. 拉取 OpenClaw 映像檔：

docker pull openclaw/openclaw-stack:latest

4. 啟動容器：

docker run -d \
  --name openclaw \
  -p 19080:19080 \
  -v openclaw-data:/data \
  -e OPENCLAW_GATEWAY_TOKEN=your-token-here \
  openclaw/openclaw-stack:latest

重要：務必設定 OPENCLAW_GATEWAY_TOKEN 環境變數。如果不設定，每次容器重啟都會產生新的 gateway token，導致已配對的裝置全部失效。

方案 B：WSL2 內直接使用 Docker Engine

如果你不想安裝 Docker Desktop（例如授權限制），可以直接在 WSL2 的 Ubuntu 裡安裝 Docker Engine：

# 安裝 Docker 官方 GPG 金鑰
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 新增 repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安裝
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

# 讓目前使用者不用 sudo 就能用 docker
sudo usermod -aG docker $USER

需要 systemd 已啟用，Docker 的 service 才會自動啟動。

效能調校

WSL2 的效能已經很好，但還有一些技巧可以讓 OpenClaw 跑得更順。

記憶體限制

WSL2 預設會佔用系統最多 50% 或 8GB 的記憶體（取較小值）。如果你的機器記憶體充裕，可以調高上限。

在 Windows 的使用者目錄建立 .wslconfig：

# %UserProfile%\.wslconfig
[wsl2]
memory=8GB
processors=4
swap=4GB

檔案系統效能

最重要的一條規則：把 OpenClaw 的所有檔案放在 WSL2 的 Linux 檔案系統內（/home/你的帳號/），不要放在 /mnt/c/ 下。

跨檔案系統存取（從 WSL2 讀寫 NTFS 掛載的 /mnt/c）的效能比原生 ext4 慢上 5-10 倍^[4]。這對 OpenClaw 的 gateway 啟動速度和 Agent 回應延遲影響很大。

# 好：在 Linux 檔案系統內
cd ~
openclaw onboard

# 不好：在 Windows 檔案系統掛載點
cd /mnt/c/Users/你的帳號/openclaw  # 效能極差

排除 Windows Defender 掃描

Windows Defender 即時保護會掃描 WSL2 的檔案系統操作，拖慢 I/O。你可以把 WSL2 的虛擬磁碟排除：

# PowerShell (系統管理員)
Add-MpPreference -ExclusionPath "\\wsl$\Ubuntu"
Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\Packages\CanonicalGroupLimited*"

DNS 解析優化

WSL2 預設使用自動產生的 /etc/resolv.conf，有時解析速度較慢。你可以關閉自動產生，改用公開 DNS：

# /etc/wsl.conf
[network]
generateResolvConf = false

sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
sudo chattr +i /etc/resolv.conf  # 防止被覆蓋

常見問題排除

問題 1：openclaw onboard 卡住不動

症狀：執行 openclaw onboard 後，畫面停在某個步驟不再有輸出。

原因：通常是網路問題。WSL2 的網路走 NAT，部分公司的 VPN 或防火牆會干擾。

解決方法：

# 測試外部連線
curl -v https://api.anthropic.com

# 如果失敗，嘗試重啟 WSL2 的網路
wsl --shutdown  # 在 PowerShell 執行

如果你使用公司 VPN，可能需要設定 WSL2 的 DNS 指向 VPN 的 DNS 伺服器。

問題 2：localhost 無法從 Windows 存取

症狀：WSL2 裡 curl localhost:19080 正常，但 Windows 瀏覽器打不開。

原因：某些 Windows 版本的 localhost 轉發有 bug。

解決方法：

# 嘗試用 WSL2 的實際 IP
wsl hostname -I
# 假設輸出 172.28.xxx.xxx

# 在瀏覽器打開 http://172.28.xxx.xxx:19080

或是用上面介紹的 portproxy 方法。

問題 3：重啟後 OpenClaw 沒有自動啟動

症狀：每次開機都要手動進 WSL2 啟動 OpenClaw。

原因：WSL2 在沒有活動 session 時會自動關閉（約 8 秒後^[5]）。

解決方法：

# 方法 1：讓 WSL2 在背景持續運行
wsl --exec dbus-launch true

或在 Task Scheduler 設定開機自動執行：

wsl -d Ubuntu -u root -- systemctl start openclaw

更完整的做法是搭配 systemd user service，詳見我們的另一篇文章。

問題 4：磁碟空間被 WSL2 吃滿

症狀：Windows 磁碟空間不斷減少，但 WSL2 裡 df -h 顯示使用量不大。

原因：WSL2 的虛擬磁碟（.vhdx）只會自動增長，不會自動縮減。

解決方法：

# 先關閉 WSL
wsl --shutdown

# 壓縮虛擬磁碟
# 路徑通常在 %LOCALAPPDATA%\Packages\CanonicalGroupLimited.Ubuntu*\LocalState\
diskpart
select vdisk file="C:\Users\你的帳號\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu24.04LTS_xxx\LocalState\ext4.vhdx"
compact vdisk
exit

問題 5：Node.js native addon 編譯失敗

症狀：npm install -g openclaw 時出現 node-gyp 編譯錯誤。

解決方法：

# 確認 build-essential 已安裝
sudo apt install -y build-essential python3

# 清除 npm cache 重試
npm cache clean --force
npm install -g openclaw

常駐服務設定

如果你希望 OpenClaw 在 WSL2 啟動時自動運行，最乾淨的方式是用 systemd user service。

首先確認 systemd 已啟用（見前面的步驟），然後建立 service 檔案：

mkdir -p ~/.config/systemd/user/

cat > ~/.config/systemd/user/openclaw.service << 'EOF'
[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/openclaw gateway start
Restart=on-failure
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=default.target
EOF

啟用服務：

systemctl --user daemon-reload
systemctl --user enable openclaw.service
systemctl --user start openclaw.service

確認狀態：

systemctl --user status openclaw.service

為了讓 user service 在沒有登入 session 的情況下也能運行，需要啟用 linger：

sudo loginctl enable-linger $USER

不想自己搞？考慮託管方案

如果你覺得上述設定太麻煩，或者你需要一個隨時可用、不用擔心 WSL2 狀態的 OpenClaw 環境，可以考慮 ClawTank——一個託管的 OpenClaw 平台。

ClawTank 為每個使用者提供獨立的 OpenClaw 容器，附帶自動 TLS、子網域路由和 Telegram bot 整合。不用管 WSL2 的 IP 變動、portproxy 設定或磁碟空間問題。

當然，如果你享受自己折騰環境的過程（很多開發者確實如此），本文的設定方式能給你最大的控制權和靈活性。

總結

在 Windows 上跑 OpenClaw，WSL2 是目前最佳解法。回顧整個流程：

1. 安裝 WSL2 並選擇 Ubuntu
2. 啟用 systemd
3. 安裝 Node.js 22
4. 執行 openclaw onboard
5. 從 Windows 瀏覽器透過 localhost 存取儀表板
6. （選配）設定 LAN 存取的 portproxy
7. （選配）用 systemd user service 做常駐運行

把握一個原則：所有 OpenClaw 的檔案都放在 Linux 檔案系統內，這一點做到了，效能和穩定性都不會有問題。

References

1. Microsoft WSL2 Linux kernel update package
2. Systemd support in WSL
3. Accessing WSL2 networking from LAN
4. WSL2 filesystem performance
5. WSL2 auto shutdown behavior
6. OpenClaw documentation
7. NodeSource Node.js distributions
8. Docker Engine on Ubuntu