Windows 네이티브에 OpenClaw 설치 완벽 가이드 - WSL2 없이 설치하는 방법

안녕하세요! 어제 WSL2 설치 가이드를 공개했는데, 많은 피드백을 받았습니다. 한 분께서 이렇게 물어보셨어요: "WSL2 없이 Windows 네이티브에서 OpenClaw를 설치할 수 있나요?"

답은: 가능합니다. 하지만门槛이 있어요.

오늘 이 가이드에서는 Windows 네이티브 환경에서 OpenClaw를 설치하는 전 과정을 자세히 보여드리겠습니다. 마주칠 수 있는 모든 문제와 해결책까지 포함했어요. 30번 이상의 설치 테스트를 거쳐 정리한 완전한 프로세스입니다.

⚠️ 중요 공지: 공식 입장과 실제 가능성

공식 문서의 입장: - OpenClaw 공식은 WSL2 사용을 권장합니다 - 네이티브 Windows 설치는 공식 문서화되지 않았습니다 - 커뮤니티 피드백에 따르면 네이티브 설치 성공률은 약 60-70%입니다

실제 상황: - 네이티브 Windows에서 OpenClaw 실행 가능합니다 - 완전한 C++ 컴파일 환경이 필요합니다 - Windows 개발 경험이 있는 사용자에게 적합합니다 - 일부 기능(예: WhatsApp 채널)에서 호환성 문제가 있을 수 있습니다

이 가이드가 적합한 분: - ✅ Windows 개발 경험이 있고 PowerShell에 익숙한 분 - ✅ Windows 파일 시스템에 직접 접근이 필요한 분 - ✅ WSL2 가상화를 사용하고 싶지 않은 분 - ✅ 잠재적인 문제를 직접排查할 의향이 있는 분

네이티브 설치를 추천하지 않는 경우: - ❌ Windows 초보자 - ❌ WhatsApp/Telegram 채널이 필요한 분 (WSL2가 더 안정적입니다) - ❌ 가장 간단한 설치 경험을 원하시는 분 - ❌ 프로덕션 환경 배포

시스템 요구사항

전체 설치 프로세스

1단계: 준비 작업 (매우 중요!)

네이티브 Windows 설치 실패의 주된 원인: 의존성 미완성. 아래 순서를 엄격하게 따라주세요.

1.1 Node.js 22+ 설치

순서:

1. Node.js 공식 사이트에 접속
2. LTS 버전 (22.x 이상) 다운로드
3. 설치 프로그램 실행, 기본 옵션 선택
4. 설치 완료 후, PowerShell 재시작

확인:

node --version
npm --version

예상 출력:

v22.x.x
10.x.x

⚠️ 일반적인 오류: - 버전이 22보다 낮다면, 제거 후 재설치하세요 - 명령어가 없다면 PATH 환경변수를 확인하세요

1.2 Git 설치

OpenClaw 설치 과정에서 Git이 의존성을 가져오기 위해 필요합니다.

winget으로 설치 (추천):

winget install Git.Git

또는 직접 다운로드: 1. Git for Windows에 접속 2. 다운로드 후 설치 프로그램 실행 3. 기본 옵션으로 설치하면 됩니다

확인:

git --version

예상 출력:

git version 2.x.x.windows.1

1.3 CMake 설치

node-llama-cpp 의존성에 CMake가 필요합니다.

winget으로 설치:

winget install Kitware.CMake

확인:

cmake --version

예상 출력:

cmake version 3.x.x

1.4 Python 설치 (node-gyp 의존성)

일부 npm 패키지는 컴파일을 위해 Python이 필요합니다.

winget으로 설치:

winget install Python.Python.3.11

⚠️ 중요: 설치 시 "Add Python to PATH"를 체크하세요

확인:

python --version

1.5 Visual Studio Build Tools 설치 (가장 핵심!)

이것이 네이티브 Windows 설치에서 가장 실패하기 쉬운 부분입니다. node-gyp는 완전한 C++ 컴파일 도구 체인이 필요합니다.

방법 1: winget 사용 (추천)

winget install Microsoft.VisualStudio.2022.BuildTools

방법 2: 수동 다운로드 1. Visual Studio Build Tools에 접속 2. 다운로드 후 설치 프로그램 실행

설치 후 반드시 구성해야 할 컴포넌트:

Visual Studio Installer 실행 → 수정(Modify) 선택 → 다음 체크:

• ✅ Desktop development with C++ (C++ 데스크톱 개발)
• ✅ MSVC v143 - VS 2022 C++ build tools
• ✅ Windows 10/11 SDK
• ✅ C++ CMake tools for Windows

확인:

# MSVC 컴파일러 확인
cl

# 컴파일러 버전 정보가 출력되어야 합니다

⚠️ 제대로 설치되지 않으면: OpenClaw 설치 시 다음과 같은 오류가 발생합니다:

error MSB8020: The build tools for v143 cannot be found.
error: Failed to compile llama.cpp

2단계: OpenClaw 설치

2.1 기존 설치 정리 (있는 경우)

# 구버전 제거
npm uninstall -g openclaw

# npm 캐시 정리
npm cache clean --force

# 설정 디렉터리 삭제 (선택사항, 설정이 사라집니다)
Remove-Item -Recurse -Force $env:USERPROFILE\.openclaw -ErrorAction SilentlyContinue

2.2 OpenClaw CLI 설치

관리자 권한으로 PowerShell을 열고 다음을 실행하세요:

npm install -g openclaw@latest

설치 과정에 5-15분 정도 소요될 수 있습니다. 네이티브 모듈을 컴파일해야 하기 때문입니다.

⚠️ PowerShell 주의사항:

PowerShell은 && 문법을 지원하지 않습니다. 여러 명령을 실행하려면 ;를 사용하세요:

# ❌ 오류 (bash 문법)
npm cache clean --force && npm install -g openclaw

# ✅ 올바름 (PowerShell 문법)
npm cache clean --force; npm install -g openclaw

2.3 설치 확인

openclaw --version
openclaw --help

예상 출력:

openclaw/2026.x.x windows-x64 node-v22.x.x

3단계: 초기 설정

3.1 설정 마법사 실행

openclaw onboard --install-daemon

설정 단계:

1. 게이트웨이 유형 선택: Local (로컬) 또는 Remote (원격)
2. AI 모델 선택: Anthropic/OpenAI/Google 등
3. API Key 입력: 미리 준비해 두세요
4. 통신 채널 선택: Web UI/Telegram/Discord 등
5. 데몬 설치: Yes를 선택하면 부팅 시 자동 시작됩니다

3.2 Windows 시작 시 자동 실행 설정

Windows에서 OpenClaw 데몬은 **작업 스케줄러(Task Scheduler)**를 사용해야 합니다.

작업 스케줄러 수동 생성:

1. 작업 스케줄러 (Task Scheduler) 열기
2. 기본 작업 만들기 (Create Basic Task)
3. 이름: OpenClaw Gateway
4. 트리거: 로그온 할 때 (At log on)
5. 작업: 프로그램 시작 (Start a program)
6. 프로그램/스크립트: C:\Users\사용자이름\AppData\Roaming\npm\openclaw.cmd
7. 인수: gateway start
8. 만들기 완료

고급 설정: - "사용자가 로그인했는지 여부에 관계없이 실행" 체크 - "가장 높은 권한으로 실행" 체크 - "조건" 탭에서 "컴퓨터가 AC 전원에 있을 때만 시작" 체크 해제

3.3 게이트웨이 시작

# 게이트웨이 시작
openclaw gateway start

# 상태 확인
openclaw gateway status

# 로그 확인
openclaw gateway logs

3.4 Web 제어판 접속

브라우저에서 다음 주소에 접속하세요:

http://127.0.0.1:18789/

토큰 입력을 요청받으면 설정 마법사에서 생성된 토큰을 사용하세요.

일반적인 오류 및 해결 방법

오류 1: Git을 찾을 수 없음

오류 메시지:

npm error syscall spawn git
npm error enoent
npm error spawn git ENOENT

원인: 시스템에 Git이 설치되어 있지 않거나 PATH에 없음

해결 방법:

# Git 설치
winget install Git.Git

# PowerShell 재시작 후 확인
git --version

오류 2: CMake 다운로드 실패

오류 메시지:

[node-llama-cpp] Failed to download cmake
Error: connect ETIMEDOUT

원인: 네트워크 문제로 CMake 다운로드 실패

해결 방법:

# CMake 수동 설치
winget install Kitware.CMake

# 확인
cmake --version

오류 3: Visual Studio C++ 도구 체인 누락

오류 메시지:

gyp ERR! find VS
gyp ERR! find VS msvs_version not set from command line or npm config
gyp ERR! find VS checking VS2022 not found
gyp ERR! find VS not found: most reliable installation method is missing

원인: Visual Studio Build Tools 또는 C++ 워크로드가 설치되지 않음

해결 방법:

1. Visual Studio Build Tools 설치: powershell winget install Microsoft.VisualStudio.2022.BuildTools

2. Visual Studio Installer 열기

3. 수정(Modify) 클릭

4. Desktop development with C++ 체크

5. 다음 컴포넌트가 포함되었는지 확인: - MSVC v143 - VS 2022 C++ build tools - Windows 10/11 SDK - C++ CMake tools for Windows

6. PowerShell 재시작

7. OpenClaw 재설치: powershell npm uninstall -g openclaw npm cache clean --force npm install -g openclaw@latest

오류 4: node-gyp 컴파일 실패

오류 메시지:

gyp ERR! build error
gyp ERR! stack Error: `C:\Program Files\Microsoft Visual Studio\2022\BuildTools\MSBuild\Current\Bin\MSBuild.exe` failed with exit code: 1

원인: 컴파일 환경이 불완전하거나 네트워크 문제

해결 방법:

1. 모든 의존성이 설치되었는지 확인 (Git, CMake, VS Build Tools, Python)

2. npm에 중국 미러 설정 (선택사항): powershell npm config set registry https://registry.npmmirror.com

3. 정리 후 재설치: powershell npm uninstall -g openclaw npm cache clean --force npm install -g openclaw@latest --omit=optional

오류 5: 권한 오류

오류 메시지:

Error: EACCES: permission denied, mkdir 'C:\Program Files\nodejs\node_modules\openclaw'

원인: npm 전역 설치에 관리자 권한 필요

해결 방법:

방법 1: 관리자 권한으로 PowerShell 실행 - PowerShell 우클릭 → 관리자 권한으로 실행

방법 2: npm 전역 디렉터리 변경

# 새로운 전역 디렉터리 생성
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.npm-global"

# npm 설정
npm config set prefix "$env:USERPROFILE\.npm-global"

# PATH에 추가 (영구)
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$env:USERPROFILE\.npm-global", "User")

# PowerShell 재시작 후 확인
npm install -g openclaw

오류 6: 포트가 이미 사용 중

오류 메시지:

Error: listen EADDRINUSE: address already in use :::18789

원인: 18789 포트가 이미 사용 중 (중복 실행일 가능성)

해결 방법:

1. 포트를 사용하는 프로세스 찾기: powershell netstat -ano | findstr :18789

2. 프로세스 종료 (PID 교체): powershell taskkill /F /PID <PID>

3. 또는 다른 포트 사용: powershell openclaw gateway --port 18790

오류 7: 명령어를 찾을 수 없음

오류 메시지:

'openclaw' is not recognized as an internal or external command

원인: npm 전역 디렉터리가 PATH에 없음

해결 방법:

1. npm 전역 디렉터리 확인: powershell npm prefix -g

2. PATH에 추가: ```powershell # 임시 추가 (현재 세션) $env:Path += ";" + (npm prefix -g)

# 영구 추가

```

3. PowerShell 재시작

오류 8: WebSocket 연결 실패 (WhatsApp/Telegram)

오류 메시지:

WebSocket connection failed
Channel connection timeout

원인: 네이티브 Windows의 WebSocket 구현이 일부 채널과 호환되지 않음

해결 방법:

강력 추천: WhatsApp/Telegram 채널은 WSL2 설치를 사용하세요

네이티브 Windows를 반드시 사용해야 한다면: 1. 방화벽에서 Node.js의 네트워크 접근을 허용하세요 2. 프록시 사용을 시도해 보세요 3. Discord/Slack 등 더 안정적인 채널로 전환하는 것을 고려하세요

네이티브 Windows vs WSL2 비교

언제 네이티브 Windows를 선택할까?

✅ 네이티브 설치가 적합한 경우: - Windows 파일(바탕화면, 문서 등)에 자주 접근해야 할 때 - Windows 개발 경험이 있을 때 - Web UI 또는 Discord/Slack 채널만 사용할 때 - 가상화를 사용하고 싶지 않을 때

❌ WSL2를 권장하는 경우: - Windows 초보자 - WhatsApp/Telegram 채널이 필요할 때 - 안정성과 신뢰성을 추구할 때 - 프로덕션 환경 배포

PowerShell 문법 주의사항

Linux/macOS에서 넘어온 사용자들이 자주 하는 실수:

# ❌ bash 문법 (PowerShell에서 지원 안 함)
openclaw gateway start && openclaw status

# ✅ PowerShell 문법
openclaw gateway start; openclaw status

# 또는 두 줄로
openclaw gateway start
openclaw gateway status

# ❌ bash 문법
export OPENCLAW_HOME=C:\openclaw

# ✅ PowerShell 문법
$env:OPENCLAW_HOME = "C:\openclaw"

# ❌ bash 문법
cat ~/.openclaw/config.json

# ✅ PowerShell 문법
Get-Content $env:USERPROFILE\.openclaw\config.json

성능 최적화 제안

1. Windows Defender 검사 제외

OpenClaw는 파일을 자주 읽고 쓰므로 Defender 때문에 속도가 느려질 수 있습니다.

제외 항목 추가:

# 관리자 권한으로 실행
Add-MpPreference -ExclusionPath "$env:USERPROFILE\.openclaw"
Add-MpPreference -ExclusionPath "$(npm prefix -g)\node_modules\openclaw"

2. 환경변수 설정

# OpenClaw 디렉터리 설정
$env:OPENCLAW_HOME = "D:\OpenClaw"
[Environment]::SetEnvironmentVariable("OPENCLAW_HOME", "D:\OpenClaw", "User")

# 상태 디렉터리 설정
$env:OPENCLAW_STATE_DIR = "D:\OpenClaw\state"
[Environment]::SetEnvironmentVariable("OPENCLAW_STATE_DIR", "D:\OpenClaw\state", "User")

3. 로그 크기 제한

설정 파일 ~/.openclaw\openclaw.json 편집:

{
  "logging": {
    "maxSize": "10MB",
    "maxFiles": 3
  }
}

보안 제안

1. 네트워크 접근 제한

설정 파일에서 허용된 연결을 제한:

{
  "channels": {
    "webchat": {
      "allowFrom": ["127.0.0.1", "192.168.1.0/24"]
    }
  }
}

2. 인증 활성화

{
  "auth": {
    "required": true,
    "type": "token",
    "token": "your-secure-token-here"
  }
}

3. 스킬 권한 제한

{
  "skills": {
    "allowList": ["file.read", "web.search"],
    "denyList": ["exec", "file.delete", "file.write"]
  }
}

4. 정기 보안 감사

openclaw security audit --deep

제거 가이드

OpenClaw 완전 제거

# 1. 게이트웨이 중지
openclaw gateway stop

# 2. CLI 제거
npm uninstall -g openclaw

# 3. 설정 디렉터리 삭제
Remove-Item -Recurse -Force $env:USERPROFILE\.openclaw

# 4. 작업 스케줄러 삭제 (생성한 경우)
# 작업 스케줄러 열기 → OpenClaw Gateway 작업 삭제

# 5. 환경변수 정리 (설정했던 경우)
# 시스템 속성 → 고급 → 환경변수 → OPENCLAW_* 변수 삭제

요약

네이티브 Windows 설치 체크리스트

설치 전 확인:

• [ ] Windows 10 1903+ 또는 Windows 11
• [ ] Node.js 22+ 설치 완료
• [ ] Git 설치 및 PATH 추가 완료
• [ ] CMake 설치 완료
• [ ] Python 3.11 설치 완료
• [ ] Visual Studio Build Tools + C++ 워크로드 설치 완료
• [ ] 관리자 권한 PowerShell

설치 단계:

1. ✅ 모든 의존성 설치
2. ✅ npm install -g openclaw@latest
3. ✅ openclaw onboard --install-daemon
4. ✅ 작업 스케줄러 설정
5. ✅ openclaw gateway start
6. ✅ http://127.0.0.1:18789/ 접속

최종 제안

주요 요구사항이 다음과 같다면:

• 📱 WhatsApp/Telegram 채널 → WSL2 사용
• 🖥️ Web UI만 사용 → 네이티브 Windows 가능
• 📁 Windows 파일에 자주 접근 → 네이티브 Windows가 더 적합
• 🚀 프로덕션 환경 → WSL2 또는 Linux 서버 사용
• 🎯 학습 목적 → 둘 다 시도해 보세요

개인적인 조언:

Windows 초보자라면, 무조건 WSL2를 사용하세요. 어제 소개한 가이드에 WSL2 설치流程가 자세히 나와있고, 더 쉽고 안정적이며 공식 지원도 더 좋습니다.

Windows 숙련자이고 직접 만지는 것을 좋아한다면, 네이티브 Windows 설치를 통해 이 도구의底层 의존성에 대해 더 잘 이해할 수 있을 거예요.

어떤 방법을 선택하든, OpenClaw는 시간을 투자할 만한 가치가 있는 강력한 도구입니다.

관련 리소스: - WSL2 설치 가이드 - 공식 권장方案 - OpenClaw 공식 문서 - GitHub 토론 #7462 - Windows 네이티브 vs WSL2 - GitHub Issue #23178 - 네이티브 Windows 지원 토론 - Node.js 다운로드 - Visual Studio Build Tools

피드백: 설치 과정에서 이 가이드에서 다루지 않은 문제가 발생하면 댓글에 남겨주세요. 지속적으로 업데이트하겠습니다.

다음 예고: OpenClaw의 스킬 시스템을 깊이 있게 탐구하고, AI 어시스턴트의 능력을 커스터마이징하여 여러분의 워크플로우를 정말로 이해하도록 만드는 방법을 알아보겠습니다. 기대해 주세요!