OpenClaw Windows 完整安裝指南 - WSL2 設定詳解

2025-03-03 OpenClaw Windows WSL2 AI 助手

大家好！今天我們來談談如何在 Windows 系統上安裝 OpenClaw —— 一個可以運行在你自己機器上的開源個人 AI 助手。

如果你厭倦了把資料交給雲端 AI 服務，想要一個完全可控、能存取本地檔案、能執行實際任務的 AI 助手，那麼 OpenClaw 正是你需要的。

什麼是 OpenClaw？

OpenClaw 是一個自託管的 AI 閘道，它可以：

📱 連接多個聊天平台（WhatsApp、Telegram、Discord、微信等）
🤖 對接各種 AI 模型（OpenAI、Claude、Gemini、本地模型等）
📁 存取你的本地檔案系統和 API
⚙️ 執行實際任務而不僅僅是聊天
🔒 完全運行在你的機器上，資料不出本地

核心優勢： - 自託管 - 運行在你的硬體上，由你掌控 - 多通道 - 一個閘道同時服務多個聊天應用 - 開源 - MIT 授權條款，社群驅動 - 低門檻 - Node.js 22+，5 分鐘即可完成安裝

系統需求

在開始之前，請確認你的系統符合以下需求：

元件	需求	說明
作業系統	Windows 10/11	建議 Windows 11
Node.js	22 或更高版本	必須！舊版本會失敗
記憶體	最低 4GB	建議 8GB+
磁碟空間	2GB 可用空間	用於安裝和快取
網路	穩定的網際網路連線	用於下載相依套件和 API 呼叫

⚠️ 重要提示

Windows 使用者必須使用 WSL2！

OpenClaw 在 Windows 上的官方支援路徑是透過 WSL2（Windows Subsystem for Linux 2）。雖然理論上可以在原生 Windows 上運行，但會遇到各種相容性問題。本指南將詳細介紹 WSL2 方案。

第一步：安裝 WSL2

方法一：一鍵安裝（推薦）

以系統管理員身份開啟 PowerShell 或命令提示字元，執行：

wsl --install

這個指令會： 1. 啟用 WSL 功能 2. 啟用虛擬機器平台功能 3. 安裝 Ubuntu 作為預設發行版 4. 要求重新啟動電腦

重新啟動後，Ubuntu 會自動開啟，要求你設定使用者名稱和密碼。

方法二：手動安裝

如果一鍵安裝失敗，可以手動執行：

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

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

# 3. 重新啟動電腦
shutdown /r /t 0

# 4. 重新啟動後，設定 WSL2 為預設版本
wsl --set-default-version 2

# 5. 從 Microsoft Store 安裝 Ubuntu
# 或者執行：
wsl --install -d Ubuntu

驗證 WSL2 安裝

# 檢查 WSL 版本
wsl --version

# 查看已安裝的發行版
wsl --list --verbose

# 確保 Ubuntu 使用 WSL2
wsl --set-version Ubuntu 2

預期輸出：

  NAME      STATE           VERSION
* Ubuntu    Running         2

第二步：在 WSL2 中安裝 Node.js 22

OpenClaw 需要 Node.js 22 或更高版本。這是最常見的安裝失敗原因！

方法一：使用 NodeSource（推薦）

在 Ubuntu 終端機中執行：

# 1. 更新套件清單
sudo apt update

# 2. 安裝 curl（如果尚未安裝）
sudo apt install -y curl

# 3. 下載並執行 NodeSource 設定腳本
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 4. 安裝 Node.js
sudo apt install -y nodejs

# 5. 驗證安裝
node --version
npm --version

預期輸出：

v22.x.x
10.x.x

方法二：使用 nvm（Node 版本管理器）

如果你需要管理多個 Node.js 版本：

# 1. 安裝 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 2. 重新載入 shell 設定
source ~/.bashrc

# 3. 安裝 Node.js 22
nvm install 22

# 4. 設定為預設版本
nvm use 22
nvm alias default 22

# 5. 驗證
node --version

⚠️ 常見錯誤排解

錯誤 1：node: command not found

# 檢查 npm 全域路徑
npm prefix -g

# 加入到 PATH（加入到 ~/.bashrc）
export PATH="$(npm prefix -g)/bin:$PATH"
source ~/.bashrc

錯誤 2：權限問題

# 修正 npm 權限問題
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

第三步：安裝 OpenClaw

方法一：官方安裝腳本（推薦）

在 Ubuntu 終端機中執行：

# 一鍵安裝
curl -fsSL https://openclaw.sh/install | bash

安裝過程會： 1. 下載 OpenClaw CLI 2. 安裝到全域 npm 3. 建立設定目錄 ~/.openclaw 4. 啟動互動式設定精靈

方法二：使用 npm 手動安裝

# 全域安裝 OpenClaw
npm install -g openclaw

# 驗證安裝
openclaw --version

安裝後驗證

# 檢查系統健康狀態
openclaw doctor

# 查看執行狀態
openclaw status

# 開啟 Web 控制面板
openclaw dashboard

第四步：完成初始化設定

安裝完成後，OpenClaw 會自動啟動互動式設定精靈。如果沒有自動啟動，可以手動執行：

openclaw onboard --install-daemon

設定步驟詳解

1. 選擇 AI 模型提供者

OpenClaw 支援多種 AI 模型：

OpenAI (GPT-4, GPT-3.5)
Anthropic (Claude 3/3.5)
Google (Gemini Pro/Flash)
本地模型 (透過 LM Studio、Ollama 等)

建議設定： - 追求品質 → Claude 3.5 Sonnet - 追求性價比 → Gemini 2.0 Flash - 隱私優先 → 本地 Qwen/Llama 模型

在設定精靈中輸入你的 API Key。

2. 設定通訊通道

你可以選擇如何與 OpenClaw 互動：

Web UI - 瀏覽器存取（預設開啟）
Telegram - 需要 Bot Token
WhatsApp - 需要掃描 QR Code
Discord - 需要 Bot Token
跳過 - 稍後設定

新手建議： 先使用 Web UI，熟悉後再設定其他通道。

3. 啟用技能（Skills）

OpenClaw 的技能系統允許它執行各種任務：

✅ 檔案操作 - 讀寫檔案、搜尋內容
✅ Web 搜尋 - 即時取得網路資訊
✅ 程式碼執行 - 執行 Python/Shell 腳本
✅ 排程任務 - 設定提醒和自動化
✅ 多模態 - 處理圖片和文件

建議： 全部啟用，可以在設定檔中限制權限。

4. 安裝守護程式

為了讓 OpenClaw 持續運行，建議安裝為系統服務：

# 在設定精靈中選擇「Install Daemon」
# 或者手動執行：
openclaw gateway install
openclaw gateway start

第五步：開始使用 OpenClaw

存取 Web 控制面板

openclaw dashboard

這會在瀏覽器中開啟 http://127.0.0.1:18789/

主要功能： - 💬 與 AI 助手聊天 - 📊 查看對話歷史 - ⚙️ 管理設定和技能 - 📅 設定排程任務 - 📝 查看日誌

常用 CLI 指令

# 查看狀態
openclaw status

# 健康檢查
openclaw doctor

# 查看可用模型
openclaw models list

# 搜尋記憶
openclaw memory search "關鍵字"

# 查看文件
openclaw docs

# 重新啟動閘道
openclaw gateway restart

# 更新 OpenClaw
openclaw update

第一個任務範例

在 Web UI 或聊天中嘗試：

幫我建立一個測試檔案，內容是「Hello OpenClaw!」

搜尋一下今天的技術新聞

讀取我桌面上的 readme.txt 檔案並總結

常見問題排解

問題 1：`openclaw: command not found`

原因： npm 全域路徑不在 PATH 中

解決方案：

# 檢查路徑
npm prefix -g

# 加入到 ~/.bashrc
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 或者重新開啟終端機

問題 2：WSL2 網路問題

症狀： 無法下載相依套件或連線 API

解決方案：

# 在 Windows PowerShell 中執行
wsl --shutdown

# 重新啟動 WSL
wsl

# 檢查 DNS
cat /etc/resolv.conf

# 如果需要使用公用 DNS
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

問題 3：權限錯誤

症狀： EACCES: permission denied

解決方案：

# 修正 npm 權限
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) ~/.openclaw

# 或者使用 nvm 避免 sudo

問題 4：閘道無法啟動

檢查日誌：

openclaw gateway status
openclaw gateway logs

常見原因： - 連接埠被佔用（預設 18789） - 設定檔錯誤 - API Key 無效

解決方案：

# 檢查連接埠佔用
netstat -tlnp | grep 18789

# 重新設定
openclaw onboard

# 重新啟動閘道
openclaw gateway restart

問題 5：Node.js 版本過低

檢查版本：

node --version

升級 Node.js：

# 如果使用 nvm
nvm install 22
nvm use 22
nvm alias default 22

# 如果使用 NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

進階設定

修改設定檔

設定檔位於 ~/.openclaw/openclaw.json

設定範例：

{
  "channels": {
    "webchat": {
      "enabled": true,
      "port": 18789
    },
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN"
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  },
  "skills": {
    "allowList": ["file.read", "file.write", "web.search"],
    "denyList": ["exec"]
  }
}

環境變數

可以透過環境變數自訂路徑：

# 自訂設定目錄
export OPENCLAW_HOME=/custom/path

# 自訂狀態目錄
export OPENCLAW_STATE_DIR=/custom/state

# 自訂設定檔
export OPENCLAW_CONFIG_PATH=/custom/config.json

安全加固

正式環境建議：

限制存取來源

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

啟用身份驗證

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

限制技能權限

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

效能優化

記憶體優化

如果記憶體有限，可以：

{
  "runtime": {
    "maxMemory": "2GB",
    "sessionLimit": 5
  }
}

啟動優化

# 停用不必要的技能
openclaw skills disable unused-skill

# 使用輕量級模型
openclaw model set gemini-2.0-flash

下一步

安裝完成後，你可以：

📚 閱讀官方文件 - docs.openclaw.ai
🔧 探索技能系統 - 查看可用技能和範例
🤖 設定自動化 - 建立排程任務和提醒
🔌 連接更多通道 - 新增 Telegram、WhatsApp 等
👥 加入社群 - Discord 社群

總結

在 Windows 上安裝 OpenClaw 的完整流程：

✅ 安裝 WSL2 和 Ubuntu
✅ 安裝 Node.js 22+
✅ 執行 OpenClaw 安裝腳本
✅ 完成初始化設定
✅ 開始使用！

整個過程大約需要 10-15 分鐘。雖然步驟看起來多，但大部分是一次性設定。

關鍵要點： - ⚠️ 必須使用 WSL2，不要嘗試原生 Windows - ⚠️ Node.js 必須是 22 或更高版本 - ⚠️ 安裝後執行 openclaw doctor 檢查狀態 - ✅ 建議安裝守護程式實現開機自啟

OpenClaw 是一個強大的工具，一旦設定完成，它會成為你的 24 小時 AI 助手，幫助你處理各種任務。無論是檔案管理、資訊搜尋還是自動化工作流程，它都能勝任。

如果你在安裝過程中遇到問題，歡迎查看官方文件或留言！

下期預告： 我們將深入探討 OpenClaw 的技能系統，教你如何让 AI 助手自動執行複雜的工作流程。敬請期待！

詳細說明如何在 Windows 11/10 上透過 WSL2 安裝 OpenClaw 個人 AI 助手，包含 WSL2 設定、Node.js 環境建置、常見問題排解和最佳實踐，Windows 開發者快速上手指南。

OpenClaw Windows 完整安裝指南 - WSL2 設定詳解

什麼是 OpenClaw？

系統需求

⚠️ 重要提示

第一步：安裝 WSL2

方法一：一鍵安裝（推薦）

方法二：手動安裝

驗證 WSL2 安裝

第二步：在 WSL2 中安裝 Node.js 22

方法一：使用 NodeSource（推薦）

方法二：使用 nvm（Node 版本管理器）

⚠️ 常見錯誤排解

第三步：安裝 OpenClaw

方法一：官方安裝腳本（推薦）

方法二：使用 npm 手動安裝

安裝後驗證

第四步：完成初始化設定

設定步驟詳解

1. 選擇 AI 模型提供者

2. 設定通訊通道

3. 啟用技能（Skills）

4. 安裝守護程式

第五步：開始使用 OpenClaw

存取 Web 控制面板

常用 CLI 指令

第一個任務範例

常見問題排解

問題 1：openclaw: command not found

問題 2：WSL2 網路問題

問題 3：權限錯誤

問題 4：閘道無法啟動

問題 5：Node.js 版本過低

進階設定

修改設定檔

環境變數

安全加固

效能優化

記憶體優化

啟動優化

下一步

總結

問題 1：`openclaw: command not found`