---
title: "비권장 환경에서 실행해 본 결과: Windows Server 2019에 OpenClaw 설치하기"
description: "Infrastructure / Self-hosted AI Agent # 비권장 환경에서 구동해보기: Windows Server 2019에 OpenClaw 설치하기(완전판) OpenClaw의 공식 권장 환경은 WSL2이지만, Windows Server 2019는 WSL2를 지원하지 않습니다. 그럼에도 포기하지 않고 네이티브 Windows 경로로 구동해본 결과, **WSL 장벽·npm 알려진 버그·모듈 누락·GPUStack 연결 문제·세션…"
url: "https://bestnetllc.co.jp/ko/docs/%eb%b9%84%ea%b6%8c%ec%9e%a5-%ed%99%98%ea%b2%bd%ec%97%90%ec%84%9c-%ec%8b%a4%ed%96%89%ed%95%b4-%eb%b3%b8-%ea%b2%b0%ea%b3%bc-windows-server-2019%ec%97%90-openclaw-%ec%84%a4%ec%b9%98%ed%95%98%ea%b8%b0/"
updated: "2026-10-19"
category: Tech Blog
---

# 비권장 환경에서 실행해 본 결과: Windows Server 2019에 OpenClaw 설치하기

Infrastructure / Self-hosted AI Agent

# 비권장 환경에서 구동해보기: Windows Server 2019에 OpenClaw 설치하기(완전판)

OpenClaw의 공식 권장 환경은 WSL2이지만, Windows Server 2019는 WSL2를 지원하지 않습니다. 그럼에도 포기하지 않고 네이티브 Windows 경로로 구동해본 결과, **WSL 장벽·npm 알려진 버그·모듈 누락·GPUStack 연결 문제·세션 손상** 등 두 자릿수에 달하는 장애를 극복하고 대시보드 실행·대화까지 도달할 수 있었습니다. 동일한 환경에서 시도하는 분들을 위해 막히는 지점을 포함한 전체 절차와 작성한 운영 지원 도구를 공개합니다.

  OpenClaw Windows Server 2019 Node.js pnpm GPUStack vLLM Self-hosted AI   **면책 사항**
 Windows Server 2019는 OpenClaw의 공식 지원 대상이 아닙니다. 본 글은 동작을 보증하는 것이 아니며, 검증 목적의 기록으로 공개하고 있습니다. 프로덕션 환경에 적용하는 것은 권장하지 않습니다.

## 왜 Server 2019에서 시도했는가

사내에 가동 중인 Windows Server 2019 환경이 있었고, OpenClaw로 해당 Server를 직접 조작하고 싶다는 동기가 있었습니다. WSL2 경유 시 Linux 환경에 갇혀버려 Windows 파일시스템·프로세스·레지스트리에 대한 접근이 WSL 장벽을 넘어야 합니다. 네이티브 Windows 설치라면 OpenClaw가 Windows API를 직접 호출할 수 있어 Server 조작 용도에 합리적입니다.

  **전제 지식**
 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 기능을 활성화하고 PC를 재시작하여 해결했습니다.

```
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 이상에서만 사용할 수 있습니다.

 **OS 요구사항 정리**
 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에 대한 tool use가 400 오류

vLLM이 `--enable-auto-tool-choice` 없이 실행되면 `400 "auto" tool choice requires ...` 오류가 발생합니다. GPUStack의 백엔드 파라미터에 추가가 필요합니다.

### ⑧ contextWindow가 16k로 오검출

모델 측이 32768이어도 OpenClaw가 16000으로 검출하여 컨텍스트 오버플로우가 빈발합니다. 설정 파일에 수동으로 `contextWindow: 32768`을 작성해야 합니다.

### ⑨ 대시보드가 Internal Server Error

npm 버전에서는 `dist/control-ui/`가 tarball에 포함되지 않아 UI가 표시되지 않습니다. pnpm 버전에서 해결됩니다.

### ⑩ 세션이 heartbeat로 고정됨

컨텍스트 오버플로우를 반복한 결과 main 세션이 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
   ```
3. PowerShell을 닫았다가 다시 열고, `node --version`으로 확인합니다.
4. **스크립트 실행을 허용하고 pnpm을 설정**
   ```
   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
   npm install -g pnpm
   pnpm setup
   ```
     PowerShell을 닫았다가 다시 엽니다.
5. **pnpm으로 OpenClaw 설치**
   ```
   pnpm add -g openclaw@2026.4.5
   ```
6. **빌드 스크립트를 승인하고 재설치**
   ```
   pnpm approve-builds -g
   # 모두 선택(스페이스바로 전체 선택)→ Enter → y
   pnpm add -g openclaw@2026.4.5
   ```
     `openclaw` 빌드에는 약 2분이 소요됩니다.
7. **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 ';')
   ```
8. **온보딩**
   ```
   $env:NODE_OPTIONS=""
   openclaw onboard
   ```
     모델 프로바이더는 **Custom Provider**, Base URL은 GPUStack의 `/v1` 엔드포인트, 호환성은 `OpenAI-compatible`을 선택합니다.
9. **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
   ```
     프로바이더 이름은 환경에 맞게 변경하세요.
10. **Gateway 시작 및 동작 확인**
    ```
    $env:NODE_OPTIONS=""
    openclaw gateway run
    ```
      `[gateway] ready`가 표시되면 별도 창에서 `openclaw dashboard`를 실행합니다.

## GPUStack 측 설정(vLLM 백엔드 파라미터)

tool use(함수 호출)를 활성화하려면, GPUStack 관리 화면에서 모델의 백엔드 파라미터에 다음을 추가합니다.

### 백엔드 파라미터(필수)

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

### 주의사항

- “변경사항은 인스턴스를 삭제하고 재생성한 후에만 적용됩니다”라고 표시되므로, 저장 후 모델 재시작이 필요
- Tesla V100(compute capability 7.0)에서는 FlashAttention2를 사용할 수 없어 TRITON 백엔드로 폴백되지만 동작은 정상
- `--tool-call-parser hermes`는 값을 같은 필드에 공백으로 구분하여 입력

## 세션 손상 시 재설정 절차

컨텍스트 오버플로를 반복하면, main 세션이 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가 설정되어 있는지 자동 진단합니다. NG가 있으면 “PATH 수정” 탭으로 자동 전환되어 수정 명령을 표시합니다.

### 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 "Gateway를 중지합니다..."
  & openclaw gateway stop
  exit
}

Write-Host "OpenClaw PATH 설정 완료"
Write-Host "openclaw: $((Get-Command openclaw -EA SilentlyContinue).Source)"

$action = Read-Host "[1] Gateway 시작  [2] Gateway 중지  [3] 대시보드  [4] TUI  [5] 상태`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 "취소" }
}
```

### 바탕화면에 저장 및 바로가기 생성

```
# 스크립트를 바탕화면에 저장
$script | Out-File "$env:USERPROFILEDesktopocstart.ps1" -Encoding UTF8

# 바로가기 생성
$ws = New-Object -ComObject WScript.Shell
$sc = $ws.CreateShortcut("$env:USERPROFILEDesktopOpenClaw起動.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이 아님)

## 요약

Windows Server 2019라는 비권장 환경에 OpenClaw를 도입하는 것은 여러 알려진 버그와 환경 고유의 제약이 겹쳐 쉽지 않은 작업이었습니다. 이번 작업에서 가장 중요했던 지식을 정리하면 다음 3가지입니다.

- **npm이 아닌 pnpm을 사용**: 2026.4.x에서는 npm을 통해 설치하면 종속성이 손상되는 심각한 버그가 있음
- **PATH와 NODE_OPTIONS를 매번 확인**: 새 창을 열 때마다 설정이 사라지므로 `ocstart.ps1`로 자동화
- **GPUStack의 vLLM 파라미터에 `--enable-auto-tool-choice --tool-call-parser hermes` 추가**: 이것이 없으면 tool use가 400 에러 발생

  **결론**
 Windows Server 2019에 OpenClaw를 설치하는 것은 가능합니다. 단, **pnpm을 사용할 것**·**PATH를 영구적으로 설정할 것**·**GPUStack 백엔드 파라미터를 올바르게 설정할 것**이라는 3가지 조건이 필수입니다. WSL2를 사용할 수 있는 환경(Server 2022 이상)으로 이전할 수 있다면 훨씬 더 쉽습니다.

본 문서의 절차는 2026년 4월 시점의 OpenClaw v2026.4.5·vLLM 0.17.1·GPUStack에 기반하고 있습니다. 버전이 변경되면 동작이 달라질 수 있습니다. 또한 Windows Server 2019는 OpenClaw의 공식 지원 대상이 아니므로 동작을 보장하지 않습니다.