Windows 사용자에게 WSL2가 필요한 이유
OpenClaw은 오픈소스 AI Agent 게이트웨이로, macOS, Linux, Windows 플랫폼을 지원하지만, 공식적으로 Windows 사용자에게는 WSL2(Windows Subsystem for Linux 2)를 통해 실행하는 것을 강력히 권장합니다. WSL2는 완전한 Linux 커널을 지원하여, OpenClaw이 의존하는 다양한 네이티브 모듈과 네트워크 프로토콜을 더 잘 처리할 수 있습니다. 네이티브 Windows 환경에서 실행하면 경로 처리, 파일 감시 및 네이티브 모듈 컴파일 등의 호환성 문제가 발생할 수 있습니다.
이 글에서는 처음부터 Windows에서 WSL2를 설정하고 OpenClaw을 설치하는 방법을 안내합니다.
시스템 요구사항
- Windows 10 버전 2004 이상 또는 Windows 11
- 최소 8GB RAM (16GB 권장)
- 가상화 기능 활성화 (BIOS에서 VT-x/AMD-V 활성화)
- 안정적인 네트워크 연결
WSL2 설치
원클릭 설치 (권장)
관리자 권한으로 PowerShell 또는 Windows Terminal을 열고 실행합니다:
wsl --install
이 명령은 자동으로 다음 작업을 완료합니다: WSL 기능 활성화, 가상 머신 플랫폼 활성화, 최신 Linux 커널 다운로드 및 설치, WSL2를 기본 버전으로 설정, Ubuntu 배포판 설치.
설치 완료 후 컴퓨터를 재부팅해야 합니다.
Ubuntu 첫 실행
재부팅 후, 시작 메뉴에서 Ubuntu를 엽니다. 처음 실행 시 Linux 사용자 이름과 비밀번호를 생성해야 합니다. 설정이 완료되면 Ubuntu의 bash 터미널에 진입합니다.
WSL 버전이 2인지 확인합니다:
wsl --list --verbose
VERSION이 1로 표시되면 전환이 필요합니다:
wsl --set-version Ubuntu 2
Ubuntu 시스템 업데이트
WSL2의 Ubuntu 터미널에 진입한 후, 먼저 시스템을 업데이트합니다:
sudo apt update && sudo apt upgrade -y
기본 개발 도구를 설치합니다:
sudo apt install -y build-essential curl git
Node.js 22 설치
OpenClaw은 Node.js 22+ 버전을 요구합니다. nvm으로 Node.js 버전을 관리하는 것을 권장합니다:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
Node.js 22 설치:
nvm install 22
nvm alias default 22
설치 확인:
node --version
npm --version
Node.js 버전이 22.x.x인지 확인합니다. 특별히 주의: Bun을 Node.js 대체로 사용하지 마세요. Bun은 WhatsApp 및 Telegram 연결 처리 시 알려진 호환성 문제가 있습니다.
OpenClaw 설치
두 가지 설치 방법 중 선택할 수 있습니다.
방법 1: npm 전역 설치
npm install -g openclaw@latest
방법 2: 공식 설치 스크립트
curl -fsSL https://openclaw.ai/install.sh | bash
설치 완료 후 확인:
openclaw --version
초기 설정
OpenClaw의 가이드 프로그램을 실행하여 초기화를 완료합니다:
openclaw onboard --install-daemon
가이드 프로그램은 다음 설정을 안내합니다:
- AI 모델 설정: AI 공급자(OpenAI, Anthropic, Google 등) 선택 및 API 키 입력
- 채팅 플랫폼 연결: 연결할 채팅 앱 설정 (WhatsApp, Telegram, Discord 등)
- 데몬 프로세스 설치: WSL2의 Ubuntu 환경에서 systemd 서비스 설정 (WSL2에서 systemd가 활성화된 경우)
모든 설정은 ~/.openclaw/openclaw.json 파일에 저장됩니다.
WSL2의 systemd 지원 활성화
최신 버전의 WSL2는 systemd를 지원하며, 이는 OpenClaw의 백그라운드 서비스 관리에 매우 중요합니다. systemd가 활성화되어 있는지 확인합니다:
systemctl --version
명령을 사용할 수 없는 경우, systemd를 활성화해야 합니다. WSL 설정 파일을 편집합니다:
sudo nano /etc/wsl.conf
다음 내용을 추가합니다:
[boot]
systemd=true
저장 후, PowerShell에서 WSL을 재시작합니다:
wsl --shutdown
Ubuntu 터미널을 다시 열면 systemd가 작동해야 합니다.
systemd 서비스 설정
openclaw onboard --install-daemon이 자동으로 systemd 서비스를 생성하지 않은 경우, 수동으로 생성할 수 있습니다:
sudo tee /etc/systemd/system/openclaw.service > /dev/null << 'EOF'
[Unit]
Description=OpenClaw AI Agent Gateway
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=사용자이름
ExecStart=/home/사용자이름/.nvm/versions/node/v22.0.0/bin/openclaw start
Restart=always
RestartSec=5
Environment=HOME=/home/사용자이름
Environment=PATH=/home/사용자이름/.nvm/versions/node/v22.0.0/bin:/usr/bin:/bin
[Install]
WantedBy=multi-user.target
EOF
사용자 이름과 Node.js 실제 버전 경로를 교체합니다. 서비스를 활성화하고 시작합니다:
sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw
진단 검사 실행
내장 진단 도구를 사용하여 모든 것이 정상인지 확인합니다:
openclaw doctor
이 명령은 Node.js 버전, 설정 파일 완전성, 네트워크 연결성, 각 플랫폼 연결 상태 등을 확인합니다.
Windows에서 OpenClaw 접근
WSL2에서 실행 중인 서비스는 Windows 브라우저에서 localhost를 통해 직접 접근할 수 있습니다. 브라우저를 열고 다음에 접속합니다:
http://localhost:3000
OpenClaw의 관리 패널을 볼 수 있습니다. WSL2에서 다음을 실행할 수도 있습니다:
openclaw dashboard
WSL2 네트워크 설정 주의사항
포트 포워딩
기본적으로 WSL2는 자동으로 포트를 Windows 호스트에 매핑합니다. Windows에서 접근할 수 없는 경우, Windows 방화벽 설정을 확인하여 3000 포트가 차단되지 않았는지 확인하세요.
외부 접근
LAN의 다른 기기에서 WSL2의 OpenClaw에 접근해야 하는 경우(예: Webhook 콜백 설정), 추가 포트 포워딩 설정이 필요할 수 있습니다:
netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 connectport=3000 connectaddress=$(wsl hostname -I | awk '{print $1}')
파일 시스템 성능 최적화
WSL2에는 두 개의 파일 시스템이 있습니다: Linux 파일 시스템(/home/)과 Windows 파일 시스템(/mnt/c/ 등). OpenClaw의 데이터를 Linux 파일 시스템에 유지하면 최상의 성능을 얻을 수 있습니다. ~/.openclaw 디렉토리를 /mnt/ 아래의 Windows 파티션에 두지 마세요.
WSL2 자동 시작
기본적으로 WSL2는 수동으로 열어야 시작됩니다. Windows 작업 스케줄러를 통해 자동 시작을 구현할 수 있습니다:
PowerShell에서 예약 작업을 생성합니다:
$action = New-ScheduledTaskAction -Execute "wsl.exe" -Argument "-d Ubuntu -- bash -c 'sudo systemctl start openclaw'"
$trigger = New-ScheduledTaskTrigger -AtLogon
Register-ScheduledTask -TaskName "StartOpenClaw" -Action $action -Trigger $trigger -Description "Start OpenClaw in WSL2"
일반적인 문제 해결
WSL2에서 인터넷 연결 불가
DNS 설정을 확인합니다. /etc/wsl.conf를 편집하여 추가합니다:
[network]
generateResolvConf=false
그런 다음 수동으로 DNS를 설정합니다:
sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
메모리 사용량 과다
WSL2는 기본적으로 과도한 메모리를 사용할 수 있습니다. Windows 사용자 디렉토리에 .wslconfig 파일을 생성합니다:
[wsl2]
memory=4GB
swap=2GB
OpenClaw 시작 실패
Linux 파일 시스템에서 실행하고 있는지, Node.js 버전이 22+인지, 네트워크가 정상인지 확인합니다. openclaw doctor를 실행하여 상세한 진단 정보를 얻으세요.
정리
WSL2는 Windows 사용자에게 OpenClaw을 실행하기 위한 최적의 환경을 제공합니다. 이 글의 설정을 통해 Windows 데스크톱 시스템에서 Linux 서버와 거의 동일한 OpenClaw 실행 경험을 얻을 수 있으며, 동시에 Windows 데스크톱 환경의 편리함도 누릴 수 있습니다. WSL2의 성능은 네이티브 Linux에 근접하여, OpenClaw AI Agent 게이트웨이의 실행 요구사항을 완전히 충족합니다.