為何我們選擇原生路徑而非 WSL2 #

在 Windows 11 上，只需一道 wsl --install 指令即可安裝 WSL2 與 Ubuntu，
因此一般而言，WSL2 路徑要輕鬆得多。
儘管如此，我們仍選擇了原生路徑，原因在於我們的目標是希望能操作 Windows 機器本身。

環境設定 #

安裝步驟 #

1. 安裝 Git for Windows #

   npm 相依性解析需要用到 Git。請在系統管理員 PowerShell 中執行。

   curl.exe -L -o git.exe "https://github.com/git-for-windows/git/releases/download/v2.47.1.windows.1/Git-2.47.1-64-bit.exe"
   .\git.exe /VERYSILENT /NORESTART
   Start-Sleep -Seconds 30

   關閉並重新開啟 PowerShell，然後以 git --version 進行確認。

2. 安裝 Node.js 22 LTS #

   curl.exe -L -o nodejs.msi "https://nodejs.org/dist/v22.14.0/node-v22.14.0-x64.msi"
   msiexec /i nodejs.msi /quiet /norestart
   Start-Sleep -Seconds 30

   關閉並重新開啟 PowerShell。以 node --version 確認顯示為 v22.x.x。

3. 指令碼執行原則與 pnpm 設定 #

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
   npm install -g pnpm
   pnpm setup

   關閉並重新開啟 PowerShell。

4. 以 pnpm 安裝 OpenClaw #

   $env:NODE_OPTIONS=""
   pnpm add -g openclaw@2026.4.5

   下載完成後，核准建置腳本。

   pnpm approve-builds -g
   # Select all with spacebar → Enter → y
   pnpm add -g openclaw@2026.4.5

   建置 OpenClaw 大約需要 2 分鐘。

5. 在電腦（Machine）層級永久保存 PATH #

   避免每次開啟新的 PowerShell 時 PATH 都消失。

   $paths = @(
     'C:\Program Files\nodejs',
     "$env:APPDATA\npm",
     "$env:LOCALAPPDATA\pnpm"
   )
   $current = [System.Environment]::GetEnvironmentVariable('PATH','Machine')
   $entries = ($current -split ';') + $paths | Select-Object -Unique
   [System.Environment]::SetEnvironmentVariable('PATH', ($entries -join ';'), 'Machine')
   $env:PATH = ($entries -join ';')
   Write-Host "openclaw:" (Get-Command openclaw -EA SilentlyContinue).Source

6. 引導設定（Onboarding） #

   $env:NODE_OPTIONS=""
   openclaw onboard

   在精靈中設定以下項目：

   • 安全性警告：選擇 Yes 繼續
   • 設定模式：QuickStart
   • 設定檔處理方式（若偵測到既有設定）：選擇 Reset 從頭開始
   • 模型提供者：Custom Provider
   • Base URL：http://<GPUStack IP>/v1
   • API 金鑰輸入方式：Paste API key now
   • 端點相容性：OpenAI-compatible
   • 模型 ID：GPUStack 上執行的模型名稱
   • Channel：Skip for now
   • 技能相依性：Skip for now
   • 網頁搜尋：SearXNG Search → 輸入 URL
   • Hooks：僅啟用 session-memory
   若出現「Config handling」畫面
   若偵測到在其他機器上建立的設定檔，或先前安裝所留下的設定檔，
   在引導設定開始時就會出現 Existing config detected → Config handling 選項。
   若要從頭開始，請選擇 Reset。

7. 手動修正 contextWindow #

   引導設定完成後，OpenClaw 可能會誤判模型的內容脈絡長度。
   請直接編輯設定檔（將提供者名稱改為符合你環境的名稱）。

   $config = Get-Content "$env:USERPROFILE\.openclaw\openclaw.json" | ConvertFrom-Json
   $config.models.providers.'custom-10-255-253-205'.models[0].contextWindow = 32768
   $config.models.providers.'custom-10-255-253-205'.models[0].maxTokens = 8192
   $config | ConvertTo-Json -Depth 20 | Set-Content "$env:USERPROFILE\.openclaw\openclaw.json" -Encoding UTF8

8. 啟動 Gateway 並確認運作 #

   $env:NODE_OPTIONS=""
   openclaw gateway run

   當日誌中出現 [gateway] ready 時，請在另一個視窗中開啟儀表板。

   $env:NODE_OPTIONS=""
   openclaw dashboard

   若能在 main 工作階段中進行對話，即代表安裝完成。

9. 將 ocstart.ps1 儲存至桌面 #

   建立捷徑，即可省去每次都要設定 PATH 與 NODE_OPTIONS 的麻煩。

   $script = @'
   param([switch]$Stop)
   $env:NODE_OPTIONS=""
   $paths = @('C:\Program Files\nodejs', "$env:APPDATA\npm", "$env:LOCALAPPDATA\pnpm")
   foreach ($p in $paths) {
     if (($env:PATH -split ';') -notcontains $p) { $env:PATH += ";$p" }
   }
   if ($Stop) { openclaw gateway stop; exit }
   $action = Read-Host "[1] Start Gateway  [2] Stop  [3] Dashboard  [4] TUI  [5] Status`n> "
   switch ($action) {
     '1' { openclaw gateway run }
     '2' { openclaw gateway stop }
     '3' { openclaw dashboard }
     '4' { openclaw tui }
     '5' { openclaw gateway status; openclaw doctor }
   }
   '@
   $script | Out-File "$env:USERPROFILE\Desktop\ocstart.ps1" -Encoding UTF8
   
   $ws = New-Object -ComObject WScript.Shell
   $sc = $ws.CreateShortcut("$env:USERPROFILE\Desktop\OpenClaw Start.lnk")
   $sc.TargetPath = "powershell.exe"
   $sc.Arguments = "-ExecutionPolicy Bypass -File `"$env:USERPROFILE\Desktop\ocstart.ps1`""
   $sc.Save()
   Write-Host "Complete"

GPUStack 設定 #

請在 GPUStack 管理面板的模型後端參數中新增以下內容，並重新啟動模型。

--max-model-len 32768
--generation-config vllm
--enable-auto-tool-choice
--tool-call-parser hermes

與 Server 2019 的比較 #

運作驗證檢查清單 #

• openclaw --version 能顯示輸出結果
• 日誌中出現 [gateway] ready
• 瀏覽器可開啟儀表板（http://127.0.0.1:18789）
• 在 main 工作階段中對話能得到回應
• GPUStack 日誌顯示 POST /v1/chat/completions HTTP/1.1" 200 OK
• 工作階段畫面的 TOKENS 顯示 xxxxx / 32768
• SearXNG 搜尋功能正常運作

總結 #

在 Windows 11 上進行原生安裝，幾乎可以直接沿用為 Server 2019 建立的步驟。
使用 pnpm、永久保存 PATH、清空 NODE_OPTIONS——這三項原則在 Windows 11 上依然不變。

與 Server 2019 的一項重要差異在於，Windows 11 多了 WSL2 這個選項，
可依使用情境選擇不同的路徑。
若想操作 Windows 本身，請使用原生安裝；
若是一般用途的 AI 代理，則使用 WSL2——請依目標來選擇。