openclaw-windows

openclaw-windows-install

안녕하세요! 오늘은 OpenClaw를 Windows 시스템에 설치하는 방법을 알아보겠습니다. 여러분 컴퓨터에서 직접 돌릴 수 있는 이 오픈소스 개인 AI 어시스턴트, 정말 편리하죠.

클라우드 AI 서비스에 데이터를 맡기는 게 지겹고, 완전히 제어 가능하면서 로컬 파일에도 접근하고 실제 작업도 수행할 수 있는 AI 어시스턴트를 원하신다면 OpenClaw가 딱 맞는 선택입니다.

OpenClaw란?

OpenClaw는 셀프 호스팅 AI 게이트웨이로, 이런 기능들을 제공합니다:

  • 📱 여러 채팅 플랫폼 연결 (WhatsApp, Telegram, Discord, WeChat 등)
  • 🤖 다양한 AI 모델 연동 (OpenAI, Claude, Gemini, 로컬 모델 등)
  • 📁 로컬 파일 시스템과 API 접근
  • ⚙️ 단순 채팅을 넘어 실제 작업 수행
  • 🔒 온전히 내 컴퓨터에서 실행, 데이터 외부 유출 없음

핵심 장점: - 셀프 호스팅 - 내 하드웨어에서 실행, 내가 컨트롤 - 멀티 채널 - 하나의 게이트웨이로 여러 채팅 앱 동시 서비스 - 오픈소스 - MIT 라이선스, 커뮤니티 주도 - 낮은 진입 장벽 - Node.js 22+, 5분이면 설치 완료

시스템 요구사항

시작하기 전에 시스템이 아래 요구사항을 만족하는지 확인하세요:

구성 요소 요구사항 설명
운영체제 Windows 10/11 Windows 11 권장
Node.js 22 이상 필수! 구버전은 실패합니다
메모리 최소 4GB 8GB+ 권장
디스크 공간 2GB 여유 공간 설치 및 캐시용
네트워크 안정적인 인터넷 연결 의존성 다운로드 및 API 호출용

⚠️ 중요 안내

Windows 사용자는 반드시 WSL2를 사용해야 합니다!

OpenClaw의 Windows 공식 지원 경로는 **WSL2(Windows Subsystem for Linux 2)**입니다. 이론적으로 네이티브 Windows에서도 돌릴 수 있겠지만 각종 호환성 문제에 부딪히게 됩니다. 이 가이드에서는 WSL2 방식을 자세히 다룹니다.

1단계: WSL2 설치

방법 1: 원클릭 설치 (권장)

PowerShell이나 명령 프롬프트를 관리자 권한으로 열고 다음을 실행하세요:

POWERSHELL 
wsl --install

이 명령은 다음 작업을 수행합니다: 1. WSL 기능 활성화 2. 가상 머신 플랫폼 기능 활성화 3. Ubuntu를 기본 배포판으로 설치 4. 컴퓨터 재시작 요청

재시작 후 Ubuntu가 자동으로 열리고 사용자 이름과 비밀번호 설정을 요청합니다.

방법 2: 수동 설치

원클릭 설치가 실패하면 수동으로 진행하세요:

POWERSHELL 
# 1. WSL 기능 활성화
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 2. 가상 머신 플랫폼 활성화
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 3. 컴퓨터 재시작
shutdown /r /t 0

# 4. 재시작 후 WSL2를 기본 버전으로 설정
wsl --set-default-version 2

# 5. Microsoft Store에서 Ubuntu 설치
# 또는 다음 명령 실행:
wsl --install -d Ubuntu

WSL2 설치 확인

POWERSHELL 
# WSL 버전 확인
wsl --version

# 설치된 배포판 목록 확인
wsl --list --verbose

# Ubuntu가 WSL2를 사용하도록 설정
wsl --set-version Ubuntu 2

예상 출력:

  NAME      STATE           VERSION
* Ubuntu    Running         2

2단계: WSL2에서 Node.js 22 설치

OpenClaw는 Node.js 22 이상이 필요합니다. 설치 실패의 가장 흔한 원인입니다!

방법 1: NodeSource 사용 (권장)

Ubuntu 터미널에서 다음을 실행하세요:

BASH 
# 1. 패키지 목록 업데이트
sudo apt update

# 2. curl 설치 (아직 없다면)
sudo apt install -y curl

# 3. NodeSource 설정 스크립트 다운로드 및 실행
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 4. Node.js 설치
sudo apt install -y nodejs

# 5. 설치 확인
node --version
npm --version

예상 출력:

v22.x.x
10.x.x

방법 2: nvm 사용 (Node 버전 관리자)

여러 Node.js 버전을 관리해야 한다면:

BASH 
# 1. nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 2. 셸 설정 리로드
source ~/.bashrc

# 3. Node.js 22 설치
nvm install 22

# 4. 기본 버전으로 설정
nvm use 22
nvm alias default 22

# 5. 확인
node --version

⚠️ 자주 발생하는 오류 해결

오류 1: node: command not found

BASH 
# npm 전역 경로 확인
npm prefix -g

# PATH에 추가 (~/.bashrc에 추가)
export PATH="$(npm prefix -g)/bin:$PATH"
source ~/.bashrc

오류 2: 권한 문제

BASH 
# npm 권한 문제 해결
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

3단계: OpenClaw 설치

방법 1: 공식 설치 스크립트 (권장)

Ubuntu 터미널에서 다음을 실행하세요:

BASH 
# 원클릭 설치
curl -fsSL https://openclaw.sh/install | bash

설치 과정에서 다음이 수행됩니다: 1. OpenClaw CLI 다운로드 2. 전역 npm에 설치 3. 설정 디렉터리 ~/.openclaw 생성 4. 대화형 설정 마법사 시작

방법 2: npm으로 수동 설치

BASH 
# OpenClaw 전역 설치
npm install -g openclaw

# 설치 확인
openclaw --version

설치 후 확인

BASH 
# 시스템 건강 상태 확인
openclaw doctor

# 실행 상태 확인
openclaw status

# 웹 컨트롤 패널 열기
openclaw dashboard

4단계: 초기 설정 완료

설치가 끝나면 OpenClaw가 자동으로 대화형 설정 마법사를 시작합니다. 자동으로 시작되지 않으면 수동으로 실행하세요:

BASH 
openclaw onboard --install-daemon

설정 단계 상세

1. AI 모델 제공업체 선택

OpenClaw는 다양한 AI 모델을 지원합니다:

  • OpenAI (GPT-4, GPT-3.5)
  • Anthropic (Claude 3/3.5)
  • Google (Gemini Pro/Flash)
  • 로컬 모델 (LM Studio, Ollama 등 경유)

추천 설정: - 품질 우선 → Claude 3.5 Sonnet - 가성비 우선 → Gemini 2.0 Flash - 프라이버시 우선 → 로컬 Qwen/Llama 모델

설정 마법사에서 API 키를 입력하세요.

2. 통신 채널 설정

OpenClaw와 어떤 방식으로 소통할지 선택하세요:

  • Web UI - 브라우저 접근 (기본 활성화)
  • Telegram - Bot Token 필요
  • WhatsApp - QR 코드 스캔 필요
  • Discord - Bot Token 필요
  • 건너뛰기 - 나중에 설정

초보자 제안: 먼저 Web UI를 사용하고 익숙해진 뒤 다른 채널을 설정하세요.

3. 스킬(Skills) 활성화

OpenClaw의 스킬 시스템은 다양한 작업 수행을 가능하게 합니다:

  • ✅ 파일 작업 - 파일 읽기/쓰기, 콘텐츠 검색
  • ✅ 웹 검색 - 실시간 네트워크 정보 획득
  • ✅ 코드 실행 - Python/Shell 스크립트 실행
  • ✅ 정기 작업 - 알림 및 자동화 설정
  • ✅ 멀티모달 - 이미지 및 문서 처리

제안: 모두 활성화하세요. 설정 파일에서 권한 제한이 가능합니다.

4. 데몬 설치

OpenClaw가 계속 실행되도록 시스템 서비스로 설치하는 것을 권장합니다:

BASH 
# 설정 마법사에서 "Install Daemon" 선택
# 또는 수동 실행:
openclaw gateway install
openclaw gateway start

5단계: OpenClaw 시작하기

웹 컨트롤 패널 접근

BASH 
openclaw dashboard

브라우저에서 http://127.0.0.1:18789/가 열립니다.

주요 기능: - 💬 AI 어시스턴트와 채팅 - 📊 세션 기록 확인 - ⚙️ 설정 및 스킬 관리 - 📅 정기 작업 설정 - 📝 로그 확인

주요 CLI 명령

BASH 
# 상태 확인
openclaw status

# 건강 진단
openclaw doctor

# 사용 가능한 모델 목록
openclaw models list

# 메모리 검색
openclaw memory search "키워드"

# 문서 보기
openclaw docs

# 게이트웨이 재시작
openclaw gateway restart

# OpenClaw 업데이트
openclaw update

첫 작업 예시

Web UI나 채팅에서 다음을 시도해 보세요:

"Hello OpenClaw!"라는 내용으로 테스트 파일을 만들어 줘

오늘의 기술 뉴스를 검색해 줘

내 데스크톱에 있는 readme.txt 파일을 읽고 요약해 줘

자주 발생하는 문제 해결

문제 1: openclaw: command not found

원인: npm 전역 경로가 PATH에 없음

해결 방법:

BASH 
# 경로 확인
npm prefix -g

# ~/.bashrc에 추가
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 또는 터미널을 다시 열기

문제 2: WSL2 네트워크 문제

증상: 의존성 다운로드 또는 API 연결 불가

해결 방법:

BASH 
# Windows PowerShell에서 실행
wsl --shutdown

# WSL 재시작
wsl

# DNS 확인
cat /etc/resolv.conf

# 공개 DNS 사용이 필요한 경우
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

문제 3: 권한 오류

증상: EACCES: permission denied

해결 방법:

BASH 
# npm 권한 복구
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) ~/.openclaw

# 또는 nvm을 사용하여 sudo 회피

문제 4: 게이트웨이 시작 불가

로그 확인:

BASH 
openclaw gateway status
openclaw gateway logs

흔한 원인: - 포트 충돌 (기본 18789) - 설정 파일 오류 - API 키 유효하지 않음

해결 방법:

BASH 
# 포트 점유 확인
netstat -tlnp | grep 18789

# 다시 설정
openclaw onboard

# 게이트웨이 재시작
openclaw gateway restart

문제 5: Node.js 버전过低

버전 확인:

BASH 
node --version

Node.js 업그레이드:

BASH 
# nvm 사용 시
nvm install 22
nvm use 22
nvm alias default 22

# NodeSource 사용 시
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

고급 설정

설정 파일 수정

설정 파일은 ~/.openclaw/openclaw.json에 있습니다.

예시 설정:

JSON 
{
  "channels": {
    "webchat": {
      "enabled": true,
      "port": 18789
    },
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN"
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  },
  "skills": {
    "allowList": ["file.read", "file.write", "web.search"],
    "denyList": ["exec"]
  }
}

환경 변수

환경 변수로 경로를 커스터마이징할 수 있습니다:

BASH 
# 설정 디렉터리 커스터마이징
export OPENCLAW_HOME=/custom/path

# 상태 디렉터리 커스터마이징
export OPENCLAW_STATE_DIR=/custom/state

# 설정 파일 커스터마이징
export OPENCLAW_CONFIG_PATH=/custom/config.json

보안 강화

프로덕션 환경 권장 사항:

  1. 접근 출처 제한
JSON 
{
  "channels": {
    "webchat": {
      "allowFrom": ["192.168.1.0/24"]
    }
  }
}
  1. 인증 활성화
JSON 
{
  "auth": {
    "required": true,
    "token": "your-secure-token"
  }
}
  1. 스킬 권한 제한
JSON 
{
  "skills": {
    "allowList": ["file.read", "web.search"],
    "denyList": ["exec", "file.delete"]
  }
}

성능 최적화

메모리 최적화

메모리가 부족하다면:

JSON 
{
  "runtime": {
    "maxMemory": "2GB",
    "sessionLimit": 5
  }
}

시작 최적화

BASH 
# 불필요한 스킬 비활성화
openclaw skills disable unused-skill

# 경량 모델 사용
openclaw model set gemini-2.0-flash

다음 단계

설치 완료 후 다음을 진행해 보세요:

  1. 📚 공식 문서 읽기 - docs.openclaw.ai
  2. 🔧 스킬 시스템 탐색 - 사용 가능한 스킬과 예시 확인
  3. 🤖 자동화 설정 - 정기 작업 및 알림 설정
  4. 🔌 더 많은 채널 연결 - Telegram, WhatsApp 등 추가
  5. 👥 커뮤니티 가입 - Discord 커뮤니티

요약

Windows에서 OpenClaw 설치의 전체 과정:

  1. ✅ WSL2 및 Ubuntu 설치
  2. ✅ Node.js 22+ 설치
  3. ✅ OpenClaw 설치 스크립트 실행
  4. ✅ 초기 설정 완료
  5. ✅ 사용 시작!

전체 과정은 약 10-15분이 소요됩니다. 단계가 많아 보이지만 대부분 한 번만 설정하면 됩니다.

핵심 포인트: - ⚠️ 반드시 WSL2를 사용하세요, 네이티브 Windows는 시도하지 마세요 - ⚠️ Node.js는 22 이상이어야 합니다 - ⚠️ 설치 후 openclaw doctor로 상태 확인 - ✅ 부팅 시 자동 시작을 위해 데몬 설치 권장

OpenClaw는 강력한 도구입니다. 한 번 설정하고 나면 24시간 AI 어시스턴트로서 파일 관리, 정보 검색, 자동화 워크플로우 등 다양한 작업을 처리해 줄 것입니다.

설치 중 문제가 생기면 공식 문서를 참조하거나 댓글을 남겨 주세요!

관련 자료: - OpenClaw 공식 문서 - OpenClaw GitHub 저장소 - WSL2 공식 문서 - Node.js 다운로드 - OpenClaw 커뮤니티 Discord

다음 예고: OpenClaw의 스킬 시스템을 깊이 있게 다루고, AI 어시스턴트가 복잡한 워크플로우를 자동으로 수행하도록 설정하는 방법을 알려드리겠습니다. 기대해 주세요!