為何我們在 Server 2019 上進行測試 #

我們公司內部有一台正在運作的 Windows Server 2019 環境，希望能直接以 OpenClaw 控制該伺服器。 若採用 WSL2，Linux 環境會被隔離，對 Windows 檔案系統、程序與登錄檔的存取都必須透過 WSL 邊界進行中介。 若以原生 Windows 方式安裝，OpenClaw 便能直接呼叫 Windows API，這對於伺服器維運的使用情境更為合理。

環境配置 #

確認 WSL2 無法使用的過程 #

一開始我們依照官方文件嘗試執行 wsl --install，但一開始就遇到問題。

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

經調查後，根本原因終於明朗：Windows Server 2019 與 WSL2 不相容，且 Microsoft 已決定不予回溯支援。 WSL2 僅適用於 Windows Server 2022 以後的版本。

陷阱清單 #

完整安裝流程 #

1. 安裝 Git for Windows

   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。
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 進行確認。
3. 啟用指令碼執行並設定 pnpm

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

   關閉並重新開啟 PowerShell。
4. 以 pnpm 安裝 OpenClaw

   pnpm add -g openclaw@2026.4.5

5. 核准建置腳本並重新安裝

   pnpm approve-builds -g
   # Select all (space to select all) → Enter → y
   pnpm add -g openclaw@2026.4.5

   OpenClaw 建置大約需要 2 分鐘。
6. 在 Machine 層級持久化 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 ';')

7. 初始設定（Onboarding）

   $env:NODE_OPTIONS=""
   openclaw onboard

   模型供應商請選擇 Custom Provider，Base URL 填入 GPUStack 的 /v1 端點，相容模式選擇 OpenAI-compatible。
8. 手動修正 contextWindow

   $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

   供應商名稱請依實際環境調整。
9. 啟動 Gateway 並確認運作

   $env:NODE_OPTIONS=""
   openclaw gateway run

   出現 [gateway] ready 後，另開一個視窗執行 openclaw dashboard。

GPUStack 設定（vLLM 後端參數） #

若要啟用工具呼叫（function calling）功能，請在 GPUStack 管理主控台的模型後端參數中加入以下內容。

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

工作階段復原流程 #

反覆發生上下文溢位可能導致主要工作階段被誤判為 heartbeat，無法正常對話。此時可刪除 sessions 目錄以重置。

openclaw gateway stop
Remove-Item "$env:USERPROFILE\.openclaw\agents\main\sessions" -Recurse -Force
New-Item "$env:USERPROFILE\.openclaw\agents\main\sessions" -ItemType Directory
openclaw gateway run

我們製作的維運支援工具：OpenClaw PATH Manager #

為了免去手動設定 PATH 的繁瑣作業，我們製作了一支 PowerShell 指令碼，以及一個以瀏覽器操作的診斷 UI 工具。

ocstart.ps1 內容 #

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) {
  Write-Host "Stopping Gateway..."
  & openclaw gateway stop
  exit
}

Write-Host "OpenClaw PATH configured"
Write-Host "openclaw: $((Get-Command openclaw -EA SilentlyContinue).Source)"

$action = Read-Host "[1] Start Gateway  [2] Stop Gateway  [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 }
  default { Write-Host "Cancelled" }
}

儲存至桌面並建立捷徑 #

# Save script to desktop
$script | Out-File "$env:USERPROFILE\Desktop\ocstart.ps1" -Encoding UTF8

# Create shortcut
$ws = New-Object -ComObject WScript.Shell
$sc = $ws.CreateShortcut("$env:USERPROFILE\Desktop\OpenClaw Launcher.lnk")
$sc.TargetPath = "powershell.exe"
$sc.Arguments = '-ExecutionPolicy Bypass -File "C:\Users\Administrator\Desktop\ocstart.ps1"'
$sc.WorkingDirectory = "$env:USERPROFILE\Desktop"
$sc.IconLocation = "powershell.exe,0"
$sc.Save()

運作驗證檢查清單 #

• 瀏覽器中可顯示主控台（http://127.0.0.1:18789）
• 模型供應商連線顯示 Verification successful
• 在 main 工作階段中，聊天可取得回覆
• GPUStack 日誌顯示 POST /v1/chat/completions HTTP/1.1" 200 OK
• Gateway 已註冊為排程工作，並於登入時自動啟動
• 已完成 SearXNG 搜尋設定
• 工作階段畫面的 TOKENS 顯示為 xxxxx / 32768（而非 16000）

總結 #

將 OpenClaw 部署至不受支援的 Windows Server 2019 環境，因多項已知錯誤與環境限制而充滿挑戰。 本次作業中最重要的三項洞見如下：

• 改用 pnpm 而非 npm：npm 2026.4.x 存在會破壞相依關係的重大錯誤
• 每次都要檢查 PATH 與 NODE_OPTIONS：開啟新視窗時會消失，請以 ocstart.ps1 自動化處理
• 在 GPUStack 的 vLLM 參數中加入 --enable-auto-tool-choice --tool-call-parser hermes：若未加入，工具呼叫會回傳 400 錯誤