原生 Windows 安裝 OpenClaw 完整指南 - 不裝 WSL2 的替代方案

2025-03-04 OpenClaw Windows 原生安裝 AI 助手

大家好！昨天我們發布了 WSL2 安裝指南，收到了很多回饋。有朋友問：「能不能在原生 Windows 上安裝 OpenClaw？不想用 WSL2。」

答案是：可以，但有門檻。

今天這篇指南，我會詳細示範如何在原生 Windows 上安裝 OpenClaw，包括所有可能遇到的坑和解決方案。這是經過 30+ 次安裝測試總結出的完整流程。

⚠️ 重要聲明：官方態度 vs 實際可行性

官方文件立場： - OpenClaw 官方推薦使用 WSL2 - 原生 Windows 安裝未正式文件化 - 社群回饋原生安裝成功率約 60-70%

實際情況： - 原生 Windows 可以執行 OpenClaw - 需要完整的 C++ 編譯環境 - 適合有 Windows 開發經驗的使用者 - 某些功能（如 WhatsApp 通道）可能有相容性問題

本指南適用人群： - ✅ 有 Windows 開發經驗，熟悉 PowerShell - ✅ 需要直接存取 Windows 檔案系統 - ✅ 不想使用 WSL2 虛擬化 - ✅ 願意花時間排查潛在問題

不建議使用原生安裝的情況： - ❌ Windows 新手 - ❌ 需要 WhatsApp/Telegram 通道（WSL2 更穩定） - ❌ 追求最簡單安裝體驗 - ❌ 生產環境部署

系統需求

元件	最低需求	建議設定
作業系統	Windows 10 1903+	Windows 11 22H2+
Node.js	22.0.0+	22.x LTS 最新版
記憶體	4GB	8GB+
磁碟空間	5GB	10GB+
權限	管理員權限	管理員權限
網路	穩定網際網路	能存取 GitHub/npm

完整安裝流程

第一階段：準備工作（關鍵！）

原生 Windows 安裝失敗的主要原因：依賴不完整。請嚴格按照順序安裝。

1.1 安裝 Node.js 22+

步驟：

存取 Node.js 官網
下載 LTS 版本（22.x 或更高）
執行安裝程式，選擇預設選項
安裝完成後，重新啟動 PowerShell

驗證：

node --version
npm --version

預期輸出：

v22.x.x
10.x.x

⚠️ 常見錯誤： - 如果版本低於 22，請解除安裝後重新安裝 - 如果指令不存在，檢查 PATH 環境變數

1.2 安裝 Git

OpenClaw 安裝過程需要 Git 拉取依賴。

使用 winget 安裝（推薦）：

winget install Git.Git

或者下載安裝： 1. 存取 Git for Windows 2. 下載並執行安裝程式 3. 選擇預設選項即可

驗證：

git --version

預期輸出：

git version 2.x.x.windows.1

1.3 安裝 CMake

node-llama-cpp 依賴需要 CMake。

使用 winget 安裝：

winget install Kitware.CMake

驗證：

cmake --version

預期輸出：

cmake version 3.x.x

1.4 安裝 Python（node-gyp 依賴）

某些 npm 套件需要 Python 進行編譯。

使用 winget 安裝：

winget install Python.Python.3.11

⚠️ 重要： 安裝時勾選 "Add Python to PATH"

驗證：

python --version

1.5 安裝 Visual Studio Build Tools（最關鍵！）

這是原生 Windows 安裝最容易失敗的環節。node-gyp 需要完整的 C++ 編譯工具鏈。

方法一：使用 winget（推薦）

winget install Microsoft.VisualStudio.2022.BuildTools

方法二：手動下載 1. 存取 Visual Studio Build Tools 2. 下載並執行安裝程式

安裝後必須設定的元件：

開啟 Visual Studio Installer → 選擇 Modify → 勾選：

✅ Desktop development with C++（桌面 C++ 開發）
✅ MSVC v143 - VS 2022 C++ build tools
✅ Windows 10/11 SDK
✅ C++ CMake tools for Windows

驗證：

# 檢查 MSVC 編譯器
cl

# 應該輸出編譯器版本資訊

⚠️ 如果沒有安裝完整： 安裝 OpenClaw 時會報錯：

error MSB8020: The build tools for v143 cannot be found.
error: Failed to compile llama.cpp

第二階段：安裝 OpenClaw

2.1 清理舊安裝（如果有）

# 解除安裝舊版本
npm uninstall -g openclaw

# 清理 npm 快取
npm cache clean --force

# 刪除設定目錄（可選，會遺失設定）
Remove-Item -Recurse -Force $env:USERPROFILE\.openclaw -ErrorAction SilentlyContinue

2.2 安裝 OpenClaw CLI

使用管理員權限開啟 PowerShell，執行：

npm install -g openclaw@latest

安裝過程可能持續 5-15 分鐘，因為需要編譯原生模組。

⚠️ PowerShell 注意事項：

PowerShell 不支援 && 語法，如果要執行多個指令，使用 ;：

# ❌ 錯誤（bash 語法）
npm cache clean --force && npm install -g openclaw

# ✅ 正確（PowerShell 語法）
npm cache clean --force; npm install -g openclaw

2.3 驗證安裝

openclaw --version
openclaw --help

預期輸出：

openclaw/2026.x.x windows-x64 node-v22.x.x

第三階段：初始化設定

3.1 執行設定精靈

openclaw onboard --install-daemon

設定步驟：

選擇閘道類型： Local（本機）或 Remote（遠端）
選擇 AI 模型： Anthropic/OpenAI/Google 等
輸入 API Key： 提前準備好
選擇通訊通道： Web UI/Telegram/Discord 等
安裝守護行程： 選擇 Yes 實現開機自啟

3.2 設定 Windows 開機自啟

OpenClaw 的 daemon 在 Windows 上需要使用 工作排程器。

手動建立工作排程：

開啟 工作排程器（Task Scheduler）
建立 基本工作
名稱：OpenClaw Gateway
觸發程序：登入時
動作：啟動程式
程式/指令碼： C:\Users\你的使用者名稱\AppData\Roaming\npm\openclaw.cmd
引數： gateway start
完成建立

進階設定： - 勾選 "不管使用者是否登入都要執行" - 勾選 "使用最高權限執行" - 在"條件"中取消"只有在電腦使用交流電源時才啟動此工作"

3.3 啟動閘道

# 啟動閘道
openclaw gateway start

# 檢視狀態
openclaw gateway status

# 檢視日誌
openclaw gateway logs

3.4 存取 Web 控制面板

開啟瀏覽器存取：

http://127.0.0.1:18789/

如果提示輸入 token，在設定精靈中會產生。

常見錯誤及解決方案

錯誤 1：Git 未找到

錯誤資訊：

npm error syscall spawn git
npm error enoent
npm error spawn git ENOENT

原因： 系統未安裝 Git 或 Git 不在 PATH 中

解決方案：

# 安裝 Git
winget install Git.Git

# 重新啟動 PowerShell 後驗證
git --version

錯誤 2：CMake 下載失敗

錯誤資訊：

[node-llama-cpp] Failed to download cmake
Error: connect ETIMEDOUT

原因： 網路問題導致 CMake 下載失敗

解決方案：

# 手動安裝 CMake
winget install Kitware.CMake

# 驗證
cmake --version

錯誤 3：Visual Studio C++ 工具鏈缺失

錯誤資訊：

gyp ERR! find VS
gyp ERR! find VS msvs_version not set from command line or npm config
gyp ERR! find VS checking VS2022 not found
gyp ERR! find VS not found: most reliable installation method is missing

原因： 未安裝 Visual Studio Build Tools 或 C++ 工作負載

解決方案：

安裝 Visual Studio Build Tools： powershell winget install Microsoft.VisualStudio.2022.BuildTools
開啟 Visual Studio Installer
點選 Modify
勾選 Desktop development with C++
確保包含以下元件： - MSVC v143 - VS 2022 C++ build tools - Windows 10/11 SDK - C++ CMake tools for Windows
重新啟動 PowerShell
重新安裝 OpenClaw： powershell npm uninstall -g openclaw npm cache clean --force npm install -g openclaw@latest

錯誤 4：node-gyp 編譯失敗

錯誤資訊：

gyp ERR! build error
gyp ERR! stack Error: `C:\Program Files\Microsoft Visual Studio\2022\BuildTools\MSBuild\Current\Bin\MSBuild.exe` failed with exit code: 1

原因： 編譯環境不完整或網路問題

解決方案：

確保已安裝所有依賴（Git、CMake、VS Build Tools、Python）
設定 npm 使用國內鏡像（可選）： powershell npm config set registry https://registry.npmmirror.com
清理後重新安裝： powershell npm uninstall -g openclaw npm cache clean --force npm install -g openclaw@latest --omit=optional

錯誤 5：權限錯誤

錯誤資訊：

Error: EACCES: permission denied, mkdir 'C:\Program Files\nodejs\node_modules\openclaw'

原因： npm 全域安裝需要管理員權限

解決方案：

方法一：使用管理員權限執行 PowerShell - 右鍵 PowerShell → 以管理員身份執行

方法二：修改 npm 全域目錄

# 建立新的全域目錄
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.npm-global"

# 設定 npm
npm config set prefix "$env:USERPROFILE\.npm-global"

# 新增到 PATH（永久）
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$env:USERPROFILE\.npm-global", "User")

# 重新啟動 PowerShell 後驗證
npm install -g openclaw

錯誤 6：連接埠被佔用

錯誤資訊：

Error: listen EADDRINUSE: address already in use :::18789

原因： 18789 連接埠已被佔用（可能是重複啟動）

解決方案：

查詢佔用連接埠的行程： powershell netstat -ano | findstr :18789
終止行程（替換 PID）： powershell taskkill /F /PID <PID>
或者使用其他連接埠： powershell openclaw gateway --port 18790

錯誤 7：指令不存在

錯誤資訊：

'openclaw' 不是內部或外部指令，也不是可執行的程式

原因： npm 全域目錄不在 PATH 中

解決方案：

查詢 npm 全域目錄： powershell npm prefix -g
新增到 PATH： ```powershell # 暫時新增（目前工作階段） $env:Path += ";" + (npm prefix -g)

# 永久新增

```

重新啟動 PowerShell

錯誤 8：WebSocket 連線失敗（WhatsApp/Telegram）

錯誤資訊：

WebSocket connection failed
Channel connection timeout

原因： 原生 Windows 的 WebSocket 實作與某些通道不相容

解決方案：

強烈建議： 對於 WhatsApp/Telegram 通道，使用 WSL2 安裝

如果必須使用原生 Windows： 1. 確保防火牆允許 Node.js 存取網路 2. 嘗試使用代理 3. 考慮切換到 Discord/Slack 等更穩定的通道

原生 Windows vs WSL2 對比

特性	原生 Windows	WSL2 (Ubuntu)
安裝難度	⭐⭐⭐⭐ 困難	⭐⭐ 簡單
依賴複雜度	高（需手動安裝）	低（套件管理器）
檔案存取	✅ 直接存取	⚠️ 透過 /mnt/c
效能	⭐⭐⭐⭐ 原生	⭐⭐⭐ 虛擬化損耗
相容性	⚠️ 部分通道問題	✅ 官方推薦
維護成本	高	低
適合場景	Windows 開發	生產環境

何時選擇原生 Windows？

✅ 適合原生安裝的情況： - 需要頻繁存取 Windows 檔案（如桌面、文件） - 有 Windows 開發經驗 - 僅使用 Web UI 或 Discord/Slack 通道 - 不想使用虛擬化

❌ 建議使用 WSL2 的情況： - Windows 新手 - 需要 WhatsApp/Telegram 通道 - 追求穩定可靠 - 生產環境部署

PowerShell 語法注意事項

從 Linux/macOS 轉過來的使用者容易犯的錯誤：

# ❌ bash 語法（PowerShell 不支援）
openclaw gateway start && openclaw status

# ✅ PowerShell 語法
openclaw gateway start; openclaw status

# 或者分兩行
openclaw gateway start
openclaw gateway status

# ❌ bash 語法
export OPENCLAW_HOME=C:\openclaw

# ✅ PowerShell 語法
$env:OPENCLAW_HOME = "C:\openclaw"

# ❌ bash 語法
cat ~/.openclaw/config.json

# ✅ PowerShell 語法
Get-Content $env:USERPROFILE\.openclaw\config.json

效能最佳化建議

1. 排除 Windows Defender 掃描

OpenClaw 頻繁讀寫檔案，可能被 Defender 拖慢。

新增排除項：

# 以管理員身份執行
Add-MpPreference -ExclusionPath "$env:USERPROFILE\.openclaw"
Add-MpPreference -ExclusionPath "$(npm prefix -g)\node_modules\openclaw"

2. 設定環境變數

# 設定 OpenClaw 目錄
$env:OPENCLAW_HOME = "D:\OpenClaw"
[Environment]::SetEnvironmentVariable("OPENCLAW_HOME", "D:\OpenClaw", "User")

# 設定狀態目錄
$env:OPENCLAW_STATE_DIR = "D:\OpenClaw\state"
[Environment]::SetEnvironmentVariable("OPENCLAW_STATE_DIR", "D:\OpenClaw\state", "User")

3. 限制日誌大小

編輯設定檔 ~/.openclaw\openclaw.json：

{
  "logging": {
    "maxSize": "10MB",
    "maxFiles": 3
  }
}

安全建議

1. 限制網路存取

在設定檔中限制允許的連線：

{
  "channels": {
    "webchat": {
      "allowFrom": ["127.0.0.1", "192.168.1.0/24"]
    }
  }
}

2. 啟用身分驗證

{
  "auth": {
    "required": true,
    "type": "token",
    "token": "your-secure-token-here"
  }
}

3. 限制技能權限

{
  "skills": {
    "allowList": ["file.read", "web.search"],
    "denyList": ["exec", "file.delete", "file.write"]
  }
}

4. 定期安全稽核

openclaw security audit --deep

解除安裝指南

完全解除安裝 OpenClaw

# 1. 停止閘道
openclaw gateway stop

# 2. 解除安裝 CLI
npm uninstall -g openclaw

# 3. 刪除設定目錄
Remove-Item -Recurse -Force $env:USERPROFILE\.openclaw

# 4. 刪除工作排程（如果建立了）
# 開啟工作排程器 → 刪除 OpenClaw Gateway 工作

# 5. 清理環境變數（如果設定了）
# 系統內容 → 進階 → 環境變數 → 刪除 OPENCLAW_* 變數

總結

原生 Windows 安裝清單

安裝前確認：

[ ] Windows 10 1903+ 或 Windows 11
[ ] Node.js 22+ 已安裝
[ ] Git 已安裝並新增到 PATH
[ ] CMake 已安裝
[ ] Python 3.11 已安裝
[ ] Visual Studio Build Tools + C++ 工作負載已安裝
[ ] 管理員權限 PowerShell

安裝步驟：

✅ 安裝所有依賴
✅ npm install -g openclaw@latest
✅ openclaw onboard --install-daemon
✅ 設定工作排程器
✅ openclaw gateway start
✅ 存取 http://127.0.0.1:18789/

最終建議

如果你的主要需求是：

📱 WhatsApp/Telegram 通道 → 使用 WSL2
🖥️ 僅 Web UI → 原生 Windows 可以
📁 頻繁存取 Windows 檔案 → 原生 Windows 更適合
🚀 生產環境 → 使用 WSL2 或 Linux 伺服器
🎯 學習體驗 → 兩種都試試

我的個人建議：

如果你是 Windows 新手，直接用 WSL2。昨天的指南已經詳細說明了 WSL2 安裝流程，更簡單、更穩定、官方支援更好。

如果你是 Windows 老手，享受折騰的過程，原生 Windows 安裝會讓你更瞭解這個工具的底層依賴。

無論選擇哪種方式，OpenClaw 都是一個強大的工具，值得投入時間設定。

相關資源： - WSL2 安裝指南 - 官方推薦方案 - OpenClaw 官方文件 - GitHub 討論 #7462 - Windows 原生 vs WSL2 - GitHub Issue #23178 - 原生 Windows 支援討論 - Node.js 下載 - Visual Studio Build Tools

問題回饋： 如果在安裝過程中遇到本指南未涵蓋的問題，歡迎在留言區留言，我會持續更新這篇文章。

下期預告： 我們將深入探討 OpenClaw 的技能系統，教你如何自訂 AI 助手的能力，讓它真正理解你的工作流程。敬請期待！

詳細講解如何在原生 Windows 系統上安裝 OpenClaw（不使用 WSL2），包含完整依賴安裝、PowerShell 設定、常見錯誤解決方案和效能對比，Windows 使用者快速上手的完整指南。