---
title: 在非推荐环境中尝试运行：在 Windows Server 2019 上安装 OpenClaw
description: "基础设施 / 自托管 AI Agent # 在非推荐环境中尝试运行：在 Windows Server 2019 上安装 OpenClaw（完整指南） OpenClaw 官方推荐使用 WSL2，但 Windows Server 2019 并不支持 WSL2。 尽管存在这一限制，我们仍坚持走原生 Windows 路线，成功克服了 **WSL 障碍、npm 已知 bug、模块缺失、GPUStack 连接问题以及会话损坏** 等十余个障碍，最终实现了控制台启动与对话能力。 我们将完整的操作步骤（包括各种坑点）以及我们为面临相同环境的用户创建的运维支持工具一并公开。 OpenClaw Windows Server 2019 Node.js pnpm GPUStack vLLM 自托管 AI…"
url: "https://bestnetllc.co.jp/zh-hans/docs/%e5%9c%a8%e9%9d%9e%e6%8e%a8%e8%8d%90%e7%8e%af%e5%a2%83%e4%b8%ad%e5%b0%9d%e8%af%95%e8%bf%90%e8%a1%8c%ef%bc%9a%e5%9c%a8-windows-server-2019-%e4%b8%8a%e5%ae%89%e8%a3%85-openclaw/"
updated: "2026-06-08"
category: Tech Blog
---

# 在非推荐环境中尝试运行：在 Windows Server 2019 上安装 OpenClaw

基础设施 / 自托管 AI Agent

# 在非推荐环境中尝试运行：在 Windows Server 2019 上安装 OpenClaw（完整指南）

OpenClaw 官方推荐使用 WSL2，但 Windows Server 2019 并不支持 WSL2。 尽管存在这一限制，我们仍坚持走原生 Windows 路线，成功克服了 **WSL 障碍、npm 已知 bug、模块缺失、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
- 网关端口：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 不兼容，微软已决定不会为其回溯适配。** 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 窗口时都会消失。需要将其设置为机器级持久化。

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

`@larksuiteoapi/node-sdk`、`@slack/web-api`、`@buape/carbon`、`grammy` 等模块相继缺失。这是 **npm 2026.4.x 的已知 bug（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 版本的安装包中未包含 `dist/control-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. **将 PATH 持久化到 Machine 级别**
   ```
   $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
   ```
     请根据您的环境调整 provider 名称。
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 个选项卡的交互式工具。在 PowerShell 中运行”状态检查”选项卡里的命令并粘贴输出结果，它会自动诊断 Node.js、pnpm、npm、openclaw 的 PATH 是否配置正确。若存在问题，会自动切换到”PATH 修复”选项卡并显示修正命令。

### ocstart.ps1（PowerShell）

保存到桌面后双击即可打开菜单，用于配置 PATH、启动/停止 Gateway、打开 dashboard 与 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 环境中充满挑战，原因在于多个已知 bug 以及该环境特有的限制。 本次工作中最重要的三点经验如下：

- **使用 pnpm 而非 npm**：npm 2026.4.x 存在破坏依赖关系的严重 bug
- **每次都要检查 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 官方支持的环境，因此不保证可正常运行。