왜 Server 2019에서 시도했는가 #

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

환경 구성 #

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

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 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 ';')

8. 온보딩

   $env:NODE_OPTIONS=""
   openclaw onboard

   모델 프로바이더는 Custom Provider, Base URL은 GPUStack의 /v1 엔드포인트, 호환성은 OpenAI-compatible을 선택합니다.
9. 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

   프로바이더 이름은 환경에 맞게 변경하세요.
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

세션 손상 시 재설정 절차 #

컨텍스트 오버플로를 반복하면, main 세션이 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 "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:USERPROFILE\Desktop\ocstart.ps1" -Encoding UTF8

# ショートカットを作成
$ws = New-Object -ComObject WScript.Shell
$sc = $ws.CreateShortcut("$env:USERPROFILE\Desktop\OpenClaw起動.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이 아님)

요약 #

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 에러 발생