在 Windows (WSL2) 上運行 OpenClaw

每次在 Windows 處理開發環境，最頭痛的就是遇到 Linux 專屬的工具或二進制檔案。你可能試過各種相容層，但最後還是發現環境不一致導致一堆莫名其妙的 Bug，或是編譯過程直接噴出一堆錯誤。

要在 Windows 上順暢執行 OpenClaw，我強烈建議你直接用 WSL2（推薦 Ubuntu）。讓 CLI 和 Gateway 跑在 Linux 內部，這樣能確保你的 Node/Bun/pnpm 和 Linux 二進制檔案保持環境一致，避開原生 Windows 可能遇到的相容性地雷。

需要準備的東西

WSL2: 推薦使用 Ubuntu 分發版
Node.js 環境: 包括 Bun 或 pnpm 等工具
Linux 知識: 熟悉基本的 Linux 指令與套件管理

快速開始

要在 5 分鐘內跑起來，請照著這幾個步驟做：

1. 安裝 WSL2 與 Ubuntu

打開你的 PowerShell（管理員權限），執行：

wsl --install
# 或者指定版本：
wsl --install -d Ubuntu-24.04

如果 Windows 要求重啟，請先重新啟動電腦。

2. 啟用 systemd

這是安裝 Gateway 服務的必要條件。在你的 WSL 終端機輸入：

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

接著回到 PowerShell 關閉 WSL 讓設定生效：

wsl --shutdown

重啟 Ubuntu 後，檢查狀態：

systemctl --user status

3. 安裝 OpenClaw

在 WSL 內部執行以下指令：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
openclaw onboard

Gateway 服務安裝

你可以透過以下任一指令來安裝 Gateway 背景服務：

openclaw onboard --install-daemon
# 或者
openclaw gateway install
# 或者
openclaw configure

在提示時選擇 Gateway service 即可。

進階：透過區域網路 (LAN) 存取 WSL 服務

WSL 有自己的虛擬網路。如果你需要從其他機器存取 WSL 裡的 Gateway 或 SSH，你必須把 Windows 的 Port 轉發到 WSL 的 IP。

請用 管理員權限 開啟 PowerShell 執行（注意：WSL IP 在重啟後會改變，屆時需重新執行）：

$Distro = "Ubuntu-24.04"
$ListenPort = 2222
$TargetPort = 22

$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 "WSL SSH $ListenPort" -Direction Inbound `
  -Protocol TCP -LocalPort $ListenPort -Action Allow

如果之後需要重設轉發規則：

netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
  connectaddress=$WslIp connectport=$TargetPort | Out-Null

提示：

從外部連線時，請指向 Windows 主機的 IP。
遠端 Node 必須設定一個可以被連到的 Gateway URL，不要用 127.0.0.1。
你可以使用 openclaw status --all 來確認連線狀態。

疑難排解

如果你遇到服務異常或環境損壞，可以嘗試修復：

修復或遷移：執行 openclaw doctor 檢查環境問題。
Windows 原生應用：目前還沒有原生的 Windows 桌面程式，如果你有興趣貢獻程式碼，歡迎參與開發。

如果你在安裝過程中卡住了，可以詢問我們的 AI Setup Assistant 獲取即時協助。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。