---
title: 在不推薦的環境中嘗試運行：在 Windows Server 2019 上安裝 OpenClaw
description: "基礎架構／自架 AI 代理 # 在不受支援的環境中測試：在 Windows Server 2019 上安裝 OpenClaw（完整指南） OpenClaw 官方建議使用 WSL2，但 Windows Server 2019 並不支援 WSL2。 即便有此限制，我們仍堅持採用原生 Windows 路線，成功克服了 **WSL 障礙、npm 已知錯誤、模組缺失、GPUStack 連線問題與工作階段損毀** 等十餘項障礙，最終達成主控台啟動與對話功能。 我們將完整流程（包含各種陷阱）以及我們為此環境打造的維運支援工具一併公開，供嘗試相同環境的讀者參考。 OpenClaw Windows Server 2019 Node.js pnpm GPUStack vLLM 自架 AI **免責聲明** Windows Server…"
url: "https://bestnetllc.co.jp/zh-hant/docs/%e5%9c%a8%e4%b8%8d%e6%8e%a8%e8%96%a6%e7%9a%84%e7%92%b0%e5%a2%83%e4%b8%ad%e5%98%97%e8%a9%a6%e9%81%8b%e8%a1%8c%ef%bc%9a%e5%9c%a8-windows-server-2019-%e4%b8%8a%e5%ae%89%e8%a3%9d-openclaw/"
updated: "2026-06-08"
category: Tech Blog
---

# 在不推薦的環境中嘗試運行：在 Windows Server 2019 上安裝 OpenClaw

基礎架構／自架 AI 代理

# 在不受支援的環境中測試：在 Windows Server 2019 上安裝 OpenClaw（完整指南）

OpenClaw 官方建議使用 WSL2，但 Windows Server 2019 並不支援 WSL2。 即便有此限制，我們仍堅持採用原生 Windows 路線，成功克服了 **WSL 障礙、npm 已知錯誤、模組缺失、GPUStack 連線問題與工作階段損毀** 等十餘項障礙，最終達成主控台啟動與對話功能。 我們將完整流程（包含各種陷阱）以及我們為此環境打造的維運支援工具一併公開，供嘗試相同環境的讀者參考。

  OpenClaw Windows Server 2019 Node.js pnpm GPUStack vLLM 自架 AI   **免責聲明**
 Windows Server 2019 並非 OpenClaw 官方支援的作業系統。 本文以驗證紀錄的形式公開，並不保證可正常運作。 不建議套用於正式環境。

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

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

  **前提知識**
 OpenClaw 官方同時支援 WSL2 與原生 Windows。 WSL2 較為穩定且是官方建議的方式，但 Server 2019 不支援 WSL2，因此原生路線是唯一選擇。

## 環境配置

OpenClaw 主機

- Windows Server 2019 Datacenter
- OpenClaw v2026.4.5（pnpm 安裝）
- Node.js v22.14.0
- Gateway 連接埠：18789

模型與搜尋後端

- GPUStack + vLLM 0.17.1
- Qwen2.5-14B-Instruct（Tesla V100 ×2）
- SearXNG（自建）
- Custom Provider（相容 OpenAI）

## 確認 WSL2 無法使用的過程

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

### 錯誤① 無法辨識 wsl

執行 `wsl --install` 出現「無法辨識『wsl』詞彙」的錯誤。 我們透過 `dism.exe` 啟用 WSL 功能並重新啟動電腦後解決了此問題。

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

### 錯誤② `--install` 選項無效

雖然 `wsl.exe` 存在，但 `--install` 與 `--set-default-version` 選項無法運作。 原因是 `wsl.exe` 的版本過舊。 即使從 GitHub 取得最新的 MSI 也無法解決問題。

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

  **作業系統需求摘要**
 WSL2 自 Windows 10 Build 19041（2020 年 5 月更新）起即可使用；伺服器版則需 Windows Server 2022 以上版本。 Windows Server 2019（Build 17763）無法使用 WSL2。

## 陷阱清單

### ① 未安裝 Node.js

`install.ps1` 未能成功安裝 Node.js，導致 `node`、`npm`、`openclaw` 均無法辨識。必須手動安裝 MSI。

### ② 無法辨識 openclaw 指令

npm 的全域安裝路徑未加入 PATH，且每次開啟新的 PowerShell 視窗都會消失。必須進行電腦（Machine）層級的持久化設定。

### ③ npm 版本大量出現 MODULE_NOT_FOUND

`@larksuiteoapi/node-sdk`、`@slack/web-api`、`@buape/carbon`、`grammy` 等套件接連缺失。**這是 npm 2026.4.x 的已知錯誤（issue #61787）**，改用 pnpm 後解決。

### ④ 未安裝 Git

npm 相依性解析需要 Git，但系統並未安裝。必須先安裝 Git for Windows 再重試。

### ⑤ 需要 pnpm approve-builds

安裝 pnpm 後，`openclaw`、`sharp`、`koffi` 等套件的建置腳本處於待核准狀態。需執行 `pnpm approve-builds -g` 全部核准後再重新安裝。

### ⑥ NODE_OPTIONS 殘留導致指令失敗

沿用設有 `NODE_OPTIONS=--stack-size=65536` 的工作階段時，後續所有 openclaw 指令都會出現「is not allowed in NODE_OPTIONS」錯誤而失敗。必須以 `$env:NODE_OPTIONS=""` 清除該變數。

### ⑦ GPUStack 工具呼叫回傳 400 錯誤

啟動 vLLM 時未加上 `--enable-auto-tool-choice`，導致出現 `400 "auto" tool choice requires ...` 錯誤。必須在 GPUStack 後端設定中加入此參數。

### ⑧ contextWindow 被誤判為 16k

即使模型本身支援更大的上下文，OpenClaw 仍偵測為 16000，導致頻繁發生上下文溢位。必須在設定檔中手動修改為 `contextWindow: 32768`。

### ⑨ 主控台顯示 Internal Server Error

npm 版本的封裝檔（tarball）未包含 `dist/control-ui/`，導致 UI 無法顯示。改用 pnpm 版本後解決。

### ⑩ 工作階段被鎖定為 heartbeat

反覆發生上下文溢位，導致主要工作階段被誤判為 heartbeat，無法正常對話。必須刪除 sessions 目錄並重新初始化。

### ⑪ 外掛 RangeError 拖慢啟動速度

`amazon-bedrock`、`google`、`minimax` 等外掛在啟動時擲出 `Maximum call stack size exceeded`，造成數分鐘的延遲。清除 NODE_OPTIONS 後解決。

### ⑫ `store` 欄位警告

GPUStack 日誌中反覆出現 `fields were present in the request but ignored: {'store'}`。雖不影響運作，但顯示 OpenClaw 傳送了不必要的欄位。

## 完整安裝流程

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 Filesnodejs',
     "$env:APPDATAnpm",
     "$env:LOCALAPPDATApnpm"
   )
   $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.openclawopenclaw.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.openclawopenclaw.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
```

### 重要注意事項

- 系統會顯示「變更僅在刪除並重新建立實例後才會生效」的訊息，儲存後需要重新啟動模型
- Tesla V100（計算能力 7.0）無法使用 FlashAttention2，會回退至 TRITON 後端，但運作正常
- `--tool-call-parser hermes` 需以空白分隔，填入同一欄位中

## 工作階段復原流程

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

```
openclaw gateway stop
Remove-Item "$env:USERPROFILE.openclawagentsmainsessions" -Recurse -Force
New-Item "$env:USERPROFILE.openclawagentsmainsessions" -ItemType Directory
openclaw gateway run
```

   **警告**
 刪除 sessions 目錄會永久遺失對話紀錄。執行前請先備份重要對話內容。

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

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

### PATH 診斷 UI（瀏覽器）

這是一個具有 3 個分頁的互動式工具。在「Status Check」分頁中，於 PowerShell 執行指令並貼上輸出結果，工具便會自動診斷 Node.js、pnpm、npm、openclaw 的 PATH 設定是否正確。如有問題，會自動切換至「PATH Fix」分頁並顯示修正指令。

### ocstart.ps1（PowerShell）

儲存至桌面後雙擊執行，即可透過選單進行 PATH 設定、Gateway 啟動／停止、主控台以及 TUI 操作。可省去每次手動設定 PATH 的麻煩。

### ocstart.ps1 內容

```
param([switch]$Stop)

$env:NODE_OPTIONS=""

$paths = @(
  'C:Program Filesnodejs',
  "$env:APPDATAnpm",
  "$env:LOCALAPPDATApnpm"
)
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:USERPROFILEDesktopocstart.ps1" -Encoding UTF8

# Create shortcut
$ws = New-Object -ComObject WScript.Shell
$sc = $ws.CreateShortcut("$env:USERPROFILEDesktopOpenClaw Launcher.lnk")
$sc.TargetPath = "powershell.exe"
$sc.Arguments = '-ExecutionPolicy Bypass -File "C:UsersAdministratorDesktopocstart.ps1"'
$sc.WorkingDirectory = "$env:USERPROFILEDesktop"
$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 錯誤

  **結論**
 在 Windows Server 2019 上安裝 OpenClaw 是可行的。 不過，**使用 pnpm**、**持久化 PATH**，以及**正確設定 GPUStack 後端參數**都是不可或缺的條件。 若能遷移至支援 WSL2 的環境（Server 2022 以上），該路線會輕鬆許多。

本文流程係以 2026 年 4 月當下的 OpenClaw v2026.4.5、vLLM 0.17.1 與 GPUStack 為基準。 隨版本變更，行為可能有所不同。 此外，Windows Server 2019 並非 OpenClaw 官方支援的環境，因此不保證能正常運作。