Windows (WSL2)

建議透過 WSL2 在 Windows 上執行 OpenClaw（推薦 Ubuntu）。CLI + Gateway 在 Linux 環境內運行，確保執行環境一致且工具相容性更佳（Node/Bun/pnpm、Linux 執行檔、skills）。原生 Windows 可能比較麻煩。WSL2 提供完整的 Linux 體驗——一行指令即可安裝：wsl --install。

原生 Windows 配套應用程式仍在規劃中。

安裝（WSL2）

• 快速開始（在 WSL 內操作）
• 安裝與更新
• 官方 WSL2 指南（Microsoft）：https://learn.microsoft.com/windows/wsl/install

原生 Windows 現況

原生 Windows CLI 的流程持續改善中，但 WSL2 仍是建議路徑。

目前在原生 Windows 上運作良好的功能：

• 透過 install.ps1 的網站安裝程式
• 本機 CLI 使用，例如 openclaw --version、openclaw doctor 和 openclaw plugins list --json
• 內嵌的本機 agent/provider 初步測試，例如：

openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."

目前的限制：

• openclaw onboard --non-interactive 仍預期可連線的本機 Gateway，除非你傳入 --skip-health
• openclaw onboard --non-interactive --install-daemon 和 openclaw gateway install 會優先嘗試 Windows 排程工作
• 若排程工作建立被拒絕，OpenClaw 會退回到每位使用者的啟動資料夾登入項目，並立即啟動 Gateway
• 若 schtasks 本身卡住或停止回應，OpenClaw 現在會快速中止該路徑並退回替代方案，不會永遠等待
• 排程工作在可用時仍是首選，因為它提供更好的 supervisor 狀態

若只想要原生 CLI 而不需要 Gateway 服務安裝，使用以下指令：

openclaw onboard --non-interactive --skip-health
openclaw gateway run

若確實想要在原生 Windows 上使用受管啟動：

openclaw gateway install
openclaw gateway status --json

若排程工作建立被阻擋，退回的服務模式仍會透過目前使用者的啟動資料夾在登入後自動啟動。

Gateway

• Gateway 操作手冊
• 設定

Gateway 服務安裝（CLI）

在 WSL2 內：

openclaw onboard --install-daemon

或：

openclaw gateway install

或：

openclaw configure

出現提示時選擇 Gateway service。

修復／遷移：

openclaw doctor

Gateway 在 Windows 登入前自動啟動

對於無頭設定，確保完整的開機鏈即使沒有人登入 Windows 也能運行。

1) 讓使用者服務在未登入時持續運行

在 WSL 內：

sudo loginctl enable-linger "$(whoami)"

2) 安裝 OpenClaw Gateway 使用者服務

在 WSL 內：

openclaw gateway install

3) 在 Windows 開機時自動啟動 WSL

以系統管理員身分開啟 PowerShell：

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM

將 Ubuntu 替換為你的發行版名稱，可從以下指令查看：

wsl --list --verbose

驗證啟動鏈

重新開機後（Windows 登入前），在 WSL 中檢查：

systemctl --user is-enabled openclaw-gateway
systemctl --user status openclaw-gateway --no-pager

進階：透過 LAN 公開 WSL 服務（portproxy）

WSL 有自己的虛擬網路。若其他機器需要連到 WSL 內 運行的服務（SSH、本機 TTS 伺服器或 Gateway），你必須將 Windows 連接埠轉發至目前的 WSL IP。WSL IP 在重啟後會改變，因此可能需要更新轉發規則。

範例（以系統管理員身分執行 PowerShell）：

$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

允許該連接埠通過 Windows 防火牆（一次性操作）：

New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
  -Protocol TCP -LocalPort $ListenPort -Action Allow

WSL 重啟後更新 portproxy：

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

說明：

• 從其他機器 SSH 時目標為 Windows 主機 IP（例如：ssh user@windows-host -p 2222）。
• 遠端節點必須指向可到達的 Gateway URL（不是 127.0.0.1）；使用 openclaw status --all 確認。
• 使用 listenaddress=0.0.0.0 開放區域網路存取；127.0.0.1 則僅限本機。
• 若想自動化，註冊一個排程工作在登入時執行更新步驟。

WSL2 逐步安裝

1) 安裝 WSL2 + Ubuntu

以系統管理員身分開啟 PowerShell：

wsl --install
# 或明確指定發行版：
wsl --list --online
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 --shutdown

重新開啟 Ubuntu，驗證：

systemctl --user status

3) 安裝 OpenClaw（在 WSL 內）

在 WSL 內依照 Linux 快速開始流程操作：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 首次執行時自動安裝 UI 相依套件
pnpm build
openclaw onboard

完整指南：快速開始

Windows 配套應用程式

目前尚無 Windows 配套應用程式。歡迎有興趣的開發者貢獻。