Windows (WSL2)에서 OpenClaw 설치하기

Windows에서 개발하다 보면 환경 설정 때문에 골치 아픈 적이 많죠? 특히 Linux 기반으로 설계된 툴을 Windows에서 직접 실행하려고 하면 라이브러리 호환성이나 경로 문제로 시간을 허비하기 일쑤예요. 런타임의 일관성을 유지하고 도구들의 호환성을 확보하려면 Linux 환경을 그대로 사용하는 것이 가장 좋습니다.

OpenClaw는 Windows에서 WSL2(Ubuntu 권장)를 통해 실행하는 것을 추천해요. CLI와 Gateway를 Linux 내부에서 실행하면 Node.js, Bun, pnpm 같은 도구들과 Linux 바이너리를 훨씬 안정적으로 쓸 수 있습니다. 네이티브 Windows 앱은 현재 계획 중이지만, 지금은 WSL2가 가장 확실한 방법이에요.

필요한 것

시작하기 전에 다음 항목들이 준비되었는지 확인해 주세요.

• Windows 10 버전 2004 이상 또는 Windows 11
• Microsoft 공식 WSL2 가이드 참고
• WSL2 내부의 Node.js/Bun/pnpm 환경
• 관리자 권한의 PowerShell

빠른 시작

5분 안에 OpenClaw 설정을 마치는 방법이에요.

1. WSL2 및 Ubuntu 설치

PowerShell을 관리자 권한으로 열고 다음 명령어를 입력하세요.

wsl --install
# 또는 특정 배포판 선택:
wsl --install -d Ubuntu-24.04

설치 후 Windows에서 재부팅을 요청하면 다시 시작해 주세요.

2. systemd 활성화

Gateway 설치를 위해 systemd가 필요합니다. WSL 터미널에서 아래 명령어를 실행하세요.

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

설정 적용을 위해 PowerShell에서 WSL을 종료했다가 다시 엽니다.

wsl --shutdown

3. OpenClaw 설치 (WSL 내부)

이제 WSL 터미널에서 OpenClaw를 내려받고 빌드하세요.

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 첫 실행 시 UI 의존성 자동 설치
pnpm build
openclaw onboard

4. Gateway 서비스 등록

Gateway를 서비스로 등록하려면 다음 중 하나를 실행하고, 안내에 따라 Gateway service를 선택하세요.

openclaw onboard --install-daemon
# 또는
openclaw gateway install
# 또는
openclaw configure

문제 해결

외부 기기에서 WSL 서비스 접속하기 (portproxy)

WSL은 자체 가상 네트워크를 사용하기 때문에, 다른 기기에서 WSL 내부의 Gateway나 SSH에 접속하려면 포트 포워딩이 필요해요. PowerShell을 관리자 권한으로 실행해 아래 스크립트를 사용하세요.

$Distro = "Ubuntu-24.04"
$ListenPort = 2222
$TargetPort = 22

$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
if (-not $WslIp) { throw "WSL IP 찾을 수 없음." }

netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
  connectaddress=$WslIp connectport=$TargetPort

# 방화벽 허용 (최초 1회)
New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
  -Protocol TCP -LocalPort $ListenPort -Action Allow

환경 복구 및 마이그레이션

설치 과정에서 문제가 생기거나 환경을 수리해야 한다면 이 명령어를 사용하세요.

openclaw doctor

설정이나 연결에 대해 더 궁금한 점이 있다면 AI Setup Assistant에게 물어보세요.

다음 단계

• Gateway runbook
• Configuration 가이드