---
title: "Trying It in a Deprecated Environment: Installing OpenClaw on Windows Server 2019"
description: "Infrastructure / Self-hosted AI Agent # Tested in Unsupported Environment: Installing OpenClaw on Windows Server 2019 (Complete Guide) OpenClaw’s official recommendation is WSL2, but Windows Server 2019 does not support WSL2. Despite this limitation, we persisted with a native Windows…"
url: "https://bestnetllc.co.jp/en/docs/trying-it-in-a-deprecated-environment-installing-openclaw-on-windows-server-2019/"
updated: "2026-10-17"
category: Tech Blog
---

# Trying It in a Deprecated Environment: Installing OpenClaw on Windows Server 2019

Infrastructure / Self-hosted AI Agent

# Tested in Unsupported Environment: Installing OpenClaw on Windows Server 2019 (Complete Guide)

OpenClaw’s official recommendation is WSL2, but Windows Server 2019 does not support WSL2. Despite this limitation, we persisted with a native Windows route and successfully overcame **WSL barriers, npm known bugs, missing modules, GPUStack connection issues, and session corruption**— more than a dozen obstacles—to reach dashboard launch and conversation capability. We are publishing complete procedures including pitfalls and the operations support tools we created for those attempting the same environment.

  OpenClaw Windows Server 2019 Node.js pnpm GPUStack vLLM Self-hosted AI   **Disclaimer**
 Windows Server 2019 is not officially supported by OpenClaw. This article is published as a verification record and does not guarantee operation. Application to production environments is not recommended.

## Why We Tested on Server 2019

We had a Windows Server 2019 environment running in-house, and we wanted to control that server directly with OpenClaw. With WSL2, the Linux environment becomes isolated, and access to Windows file systems, processes, and registry becomes mediated through the WSL boundary. With native Windows installation, OpenClaw can call Windows APIs directly, which makes sense for server operation use cases.

  **Prerequisite Knowledge**
 OpenClaw officially supports both WSL2 and native Windows. WSL2 is more stable and recommended, but Server 2019 does not support WSL2, so native route is the only option.

## Environment Configuration

OpenClaw Host

- Windows Server 2019 Datacenter
- OpenClaw v2026.4.5 (pnpm installation)
- Node.js v22.14.0
- Gateway port: 18789

Model & Search Backend

- GPUStack + vLLM 0.17.1
- Qwen2.5-14B-Instruct (Tesla V100 ×2)
- SearXNG (on-premises)
- Custom Provider (OpenAI-compatible)

## The Journey to Confirming WSL2 Unavailability

Initially, we followed the official documentation and tried `wsl --install`. However, we hit issues right from the start.

### Error ① wsl not recognized

Running `wsl --install` resulted in “The term ‘wsl’ is not recognized” error. We resolved this by enabling WSL features with `dism.exe` and restarting the PC.

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

### Error ② `--install` option is invalid

`wsl.exe` exists but `--install` and `--set-default-version` options do not work. This is because the `wsl.exe` version is too old. Obtaining the latest MSI from GitHub did not resolve it.

After investigation, the root cause became clear: **Windows Server 2019 is incompatible with WSL2, and Microsoft has decided not to backport it.** WSL2 is only available on Windows Server 2022 and later.

  **OS Requirements Summary**
 WSL2 is available starting with Windows 10 Build 19041 (May 2020 update) or later; for server editions, Windows Server 2022 or later. WSL2 is not available on Windows Server 2019 (Build 17763).

## Pitfalls List

### ① Node.js not installed

`install.ps1` failed to install Node.js, leaving `node`, `npm`, and `openclaw` unrecognized. Manual MSI installation was necessary.

### ② openclaw command not recognized

npm’s global installation path was not in PATH and disappeared each time a new PowerShell window opened. Machine-level persistence was required.

### ③ npm version floods with MODULE_NOT_FOUND

Packages like `@larksuiteoapi/node-sdk`, `@slack/web-api`, `@buape/carbon`, and `grammy` were missing one by one. **Known bug in npm 2026.4.x (issue #61787)** resolved by switching to pnpm.

### ④ Git not installed

Git is required for npm dependency resolution but was not installed. Git for Windows installation was necessary before retry.

### ⑤ pnpm approve-builds required

After pnpm installation, build scripts for `openclaw`, `sharp`, `koffi` and others were pending approval. `pnpm approve-builds -g` was needed to approve all, then reinstall.

### ⑥ NODE_OPTIONS leftover breaks commands

Reusing a session with `NODE_OPTIONS=--stack-size=65536` caused all subsequent openclaw commands to fail with “is not allowed in NODE_OPTIONS” error. Clearing with `$env:NODE_OPTIONS=""` was necessary.

### ⑦ GPUStack tool use returns 400 error

vLLM started without `--enable-auto-tool-choice` resulted in `400 "auto" tool choice requires ...` error. Adding this parameter to GPUStack backend settings was required.

### ⑧ contextWindow misdetected as 16k

Even when the model supported 32768 tokens, OpenClaw detected it as 16000, causing frequent context overflow. Manual edit of `contextWindow: 32768` in the config file was necessary.

### ⑨ Dashboard shows Internal Server Error

npm version did not include `dist/control-ui/` in the tarball and UI did not display. Resolved with pnpm version.

### ⑩ Session locked to heartbeat

Repeated context overflow caused the main session to be recognized as heartbeat, preventing normal conversation. Deleting the sessions directory and resetting was necessary.

### ⑪ Plugin RangeError slows startup

`amazon-bedrock`, `google`, `minimax` plugins threw `Maximum call stack size exceeded` at startup, causing minutes of delay. Clearing NODE_OPTIONS resolved it.

### ⑫ `store` field warning

GPUStack logs show `fields were present in the request but ignored: {'store'}` repeatedly. Does not affect operation but indicates OpenClaw sending unnecessary fields.

## Complete Installation Procedure

1. **Install 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
   ```
     Close and reopen PowerShell.
2. **Manually install 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
   ```
     Close and reopen PowerShell, verify with `node --version`.
3. **Enable script execution and set up pnpm**
   ```
   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
   npm install -g pnpm
   pnpm setup
   ```
     Close and reopen PowerShell.
4. **Install OpenClaw with pnpm**
   ```
   pnpm add -g openclaw@2026.4.5
   ```
5. **Approve build scripts and reinstall**
   ```
   pnpm approve-builds -g
   # Select all (space to select all) → Enter → y
   pnpm add -g openclaw@2026.4.5
   ```
     OpenClaw build takes approximately 2 minutes.
6. **Persist PATH at Machine level**
   ```
   $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
   ```
     Select **Custom Provider** for model provider, GPUStack `/v1` endpoint as Base URL, and `OpenAI-compatible` for compatibility.
8. **Manually fix 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
   ```
     Adjust provider name to match your environment.
9. **Launch Gateway and verify operation**
   ```
   $env:NODE_OPTIONS=""
   openclaw gateway run
   ```
     Once `[gateway] ready` appears, open another window and run `openclaw dashboard`.

## GPUStack Configuration (vLLM Backend Parameters)

To enable tool use (function calling), add the following to the model’s backend parameters in the GPUStack management dashboard.

### Backend Parameters (Required)

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

### Important Notes

- The message “Changes apply only after instance deletion and recreation” appears; model restart is required after saving
- Tesla V100 (compute capability 7.0) cannot use FlashAttention2 and falls back to TRITON backend, but operation is normal
- `--tool-call-parser hermes` is entered space-delimited in the same field

## Session Recovery Procedure

Repeated context overflow can cause the main session to be recognized as heartbeat, preventing normal conversation. Delete the sessions directory to reset.

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

   **Warning**
 Deleting the sessions directory permanently loses conversation history. Back up important conversations before executing.

## Operations Support Tool Created: OpenClaw PATH Manager

To eliminate the manual PATH configuration overhead, we created a PowerShell script and a browser-based diagnostic UI tool.

### PATH Diagnostic UI (Browser)

An interactive tool with 3 tabs. Run the command from the “Status Check” tab in PowerShell and paste the output; it automatically diagnoses whether PATH is correctly set for Node.js, pnpm, npm, and openclaw. If there are issues, it automatically switches to the “PATH Fix” tab and displays correction commands.

### ocstart.ps1 (PowerShell)

Save to desktop and double-click to access a menu for PATH configuration, Gateway start/stop, dashboard, and TUI. Eliminates the need to manually set PATH each time.

### Contents of 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 to Desktop and Create Shortcut

```
# 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()
```

## Operational Verification Checklist

- Dashboard displays in browser (`http://127.0.0.1:18789`)
- Model provider connection shows `Verification successful`
- Chat gets responses in `main` session
- GPUStack logs show `POST /v1/chat/completions HTTP/1.1" 200 OK`
- Gateway is registered as Scheduled Task and auto-starts on login
- SearXNG search is configured
- Session screen TOKENS display shows `xxxxx / 32768` (not 16000)

## Summary

Deploying OpenClaw to the unsupported Windows Server 2019 environment proved challenging due to multiple known bugs and environment-specific constraints. The three most critical insights from this work are:

- **Use pnpm instead of npm**: npm 2026.4.x has a critical bug breaking dependencies
- **Check PATH and NODE_OPTIONS every time**: They disappear when opening new windows; automate with `ocstart.ps1`
- **Add `--enable-auto-tool-choice --tool-call-parser hermes` to GPUStack vLLM parameters**: Without these, tool use returns 400 error

  **Conclusion**
 OpenClaw installation on Windows Server 2019 is possible. However, **using pnpm**, **persisting PATH**, and **configuring GPUStack backend parameters correctly** are essential. If you can migrate to an environment with WSL2 support (Server 2022 or later), that path is significantly easier.

This article’s procedures are based on OpenClaw v2026.4.5, vLLM 0.17.1, and GPUStack as of April 2026. Behavior may differ with version changes. Additionally, Windows Server 2019 is not officially supported by OpenClaw, so operation is not guaranteed.