왜 WSL2가 아닌 네이티브 방식을 선택했는가 #

Windows 11에서는 wsl --install 한 번으로 WSL2와 Ubuntu가 실행되기 때문에,
보통은 WSL2 방식이 압도적으로 편리합니다.
그럼에도 네이티브 방식을 선택한 이유는, Windows 머신 자체를 조작하고 싶다는 목적이 있기 때문입니다.

환경 구성 #

설치 절차 #

1. Git for Windows 설치 #

   npm 종속성 해결에 git이 필요합니다. 관리자 PowerShell에서 실행합니다.

   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을 닫고 다시 열어서 git --version으로 확인합니다.

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으로 v22.x.x가 표시되면 정상입니다.

3. 스크립트 실행 정책과 pnpm 설정 #

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
   npm install -g pnpm
   pnpm setup

   PowerShell을 닫았다가 다시 엽니다.

4. pnpm으로 OpenClaw 설치 #

   $env:NODE_OPTIONS=""
   pnpm add -g openclaw@2026.4.5

   다운로드 완료 후 빌드 스크립트를 승인합니다.

   pnpm approve-builds -g
   # 스페이스 키로 전체 선택 → Enter → y
   pnpm add -g openclaw@2026.4.5

   openclaw 빌드에 약 2분이 소요됩니다.

5. PATH를 Machine 레벨에서 영구 설정 #

   새로운 PowerShell을 열 때마다 PATH가 사라지는 문제를 방지합니다.

   $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 ';')
   Write-Host "openclaw:" (Get-Command openclaw -EA SilentlyContinue).Source

6. 온보딩 #

   $env:NODE_OPTIONS=""
   openclaw onboard

   마법사에서 다음을 설정합니다.

   • 보안 경고: Yes로 계속
   • Setup mode: QuickStart
   • Config handling (기존 설정이 감지된 경우): Reset으로 처음부터 시작
   • 모델 프로바이더: Custom Provider
   • Base URL: http://<GPUStack의 IP>/v1
   • API Key 제공 방법: Paste API key now
   • Endpoint compatibility: OpenAI-compatible
   • Model ID: GPUStack에서 실행 중인 모델명
   • 채널: Skip for now
   • 스킬 종속성: Skip for now
   • 웹 검색: SearXNG Search → URL 입력
   • Hooks: session-memory만 활성화
   「Config handling」화면이 나타난 경우
   다른 머신이나 과거 설치에서 만든 설정 파일이 남아 있으면,
   온보딩 초반에 Existing config detected → Config handling이라는 선택지가 표시됩니다.
   처음부터 다시 시작하려면 Reset을 선택하세요.

7. contextWindow 수동 수정 #

   온보딩 완료 후 OpenClaw가 모델의 컨텍스트 길이를 잘못 감지할 수 있습니다.
   설정 파일을 직접 수정합니다(프로바이더 이름은 환경에 맞게 변경하세요).

   $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

8. Gateway 실행 및 동작 확인 #

   $env:NODE_OPTIONS=""
   openclaw gateway run

   [gateway] ready가 표시되면 별도 창에서 대시보드를 엽니다.

   $env:NODE_OPTIONS=""
   openclaw dashboard

   main 세션에서 대화할 수 있으면 완료입니다.

9. ocstart.ps1을 바탕화면에 저장 #

   매번 PATH와 NODE_OPTIONS를 설정하는 번거로움을 덜어주는 바로가기를 만듭니다.

   $script = @'
   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) { openclaw gateway stop; exit }
   $action = Read-Host "[1] Gateway起動  [2] 停止  [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 }
   }
   '@
   $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 `"$env:USERPROFILE\Desktop\ocstart.ps1`""
   $sc.Save()
   Write-Host "완료"

GPUStack 측 설정 #

GPUStack 관리 화면에서 모델의 백엔드 파라미터에 다음을 추가하고 모델을 재시작합니다.

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

Server 2019와의 비교 #

동작 확인 체크리스트 #

• openclaw --version이 표시됨
• [gateway] ready가 로그에 표시됨
• 대시보드(http://127.0.0.1:18789)가 브라우저에서 열림
• main 세션에서 채팅에 응답이 반환됨
• GPUStack 로그에 POST /v1/chat/completions HTTP/1.1" 200 OK가 표시됨
• 세션 화면의 TOKENS가 xxxxx / 32768로 표시됨
• SearXNG 검색이 기능함

정리 #

Windows 11에서의 네이티브 설치는 Server 2019에서 확립한 절차를 거의 그대로 활용할 수 있었습니다.
pnpm을 사용하고・PATH를 영구화하며・NODE_OPTIONS를 초기화한다는 세 가지 원칙은 Windows 11에서도 변함없습니다.

Server 2019와 다른 점으로, Windows 11에서는 WSL2를 사용할 수 있어
용도에 따라 경로를 구분할 수 있다는 것이 큰 장점입니다.
Windows 자체를 조작시키고 싶은 경우는 네이티브,
AI 에이전트로서의 범용 용도라면 WSL2로, 목적에 맞춰 선택하시기 바랍니다.