OpenClaw 완벽 가이드 시리즈 2/5

OpenClaw 설치 전 반드시 완료해야 할 윈도우 환경 세팅을 정리했습니다. PowerShell 관리자 실행, WSL2 + Ubuntu 설치, Chocolatey, Node.js 22 설치까지 모든 명령어와 함께 초보자도 따라할 수 있도록 안내합니다.

 

OpenClaw 완벽 가이드 시리즈 2/5

← 이전 글: 1부 프롤로그 — OpenClaw란?

OpenClaw 설치, 왜 첫 시도에 실패하는 사람이 많을까요?

대부분 OpenClaw 자체가 아니라 "환경 세팅"에서 막힙니다. Node.js 버전이 안 맞거나, WSL이 꼬이거나, PowerShell 권한 문제로 진행이 안 되는 경우가 대부분이죠.

이 글에서는 OpenClaw 설치 전에 반드시 완료해야 할 윈도우 환경 세팅 4단계를 초보자도 따라할 수 있도록 모든 명령어와 함께 안내합니다. 이 바닥 공사만 제대로 하면, 다음 단계인 실제 설치에서 막힐 일이 거의 없습니다.

 

 

목차

1. 전체 흐름 한눈에 보기

2. Step 1: PowerShell 관리자 권한 실행

3. Step 2: WSL2 + Ubuntu 설치

4. Step 3: Chocolatey 설치 (윈도우용 패키지 관리자)

5. Step 4: Node.js 22 이상 설치

6. Step 5: Git 및 필수 도구 설치

7. 최종 점검 체크리스트

8. 자주 막히는 지점 FAQ

9. 다음 글 안내

---

1. 전체 흐름 한눈에 보기

OpenClaw를 설치하기 전에 완료해야 할 환경 세팅은 크게 4단계입니다. 각 단계는 이전 단계가 완료되어야 다음 단계가 정상적으로 진행되므로, 반드시 순서대로 따라와 주세요.

 

 

핵심 포인트: OpenClaw는 Node.js 22 이상이 필수 런타임입니다. 그리고 윈도우에서는 WSL2(Windows Subsystem for Linux) 위에서 운영하는 것이 공식 권장 방식입니다. 직접 윈도우에서도 돌릴 수 있지만, 트러블슈팅이 어렵고 호환성 문제가 잦아서 WSL2를 강력히 추천합니다.

---

2. Step 1: PowerShell 관리자 권한 실행

모든 설치 작업의 시작점입니다. PowerShell을 반드시 관리자 권한으로 실행해야 합니다. 일반 사용자 권한으로는 WSL 설치나 시스템 변경이 불가능합니다.

실행 방법

키보드에서 Win 키를 누르고 "PowerShell"을 입력한 뒤, 검색 결과에서 "관리자 권한으로 실행"을 클릭합니다. 또는 시작 메뉴를 마우스 오른쪽 버튼으로 클릭해서 "터미널(관리자)"를 선택해도 됩니다.

실행 정책 설정

윈도우의 보안 정책 때문에 외부 스크립트 실행이 막혀 있을 수 있습니다. 아래 명령어로 현재 세션에서만 임시로 실행 정책을 우회합니다. (시스템 전체 설정을 바꾸는 게 아니라 지금 열린 창에서만 적용되므로 안전합니다.)

# 현재 PowerShell 세션에서만 실행 정책 우회 (안전)
Set-ExecutionPolicy Bypass -Scope Process -Force

확인 방법: 명령 실행 후 아무 에러 메시지 없이 다음 줄로 넘어가면 정상입니다. "변경하시겠습니까?" 같은 확인 메시지가 뜨면 Y를 입력하세요.

---

3. Step 2: WSL2 + Ubuntu 설치

 

 

WSL2가 뭔가요?

WSL은 Windows Subsystem for Linux의 약자로, 윈도우 안에서 리눅스를 돌리는 기술입니다. 가상머신(VirtualBox 등)보다 훨씬 가볍고 빠르며, 윈도우 파일 시스템과도 자유롭게 연동됩니다.

쉽게 말해 "윈도우를 그대로 쓰면서, 필요할 때 리눅스 터미널을 열어 쓸 수 있는 기능"입니다. OpenClaw뿐 아니라 대부분의 오픈소스 개발 도구가 리눅스 환경에서 가장 안정적으로 작동하기 때문에, 개발자라면 WSL2를 설치해두는 것이 여러모로 유용합니다.

설치 명령어

관리자 PowerShell에서 아래 명령어를 실행합니다. 이 한 줄이면 WSL2 엔진 + Ubuntu가 한 번에 설치됩니다.

# WSL2 + Ubuntu 한 번에 설치 (관리자 PowerShell)
wsl --install

설치 후 해야 할 것

1) 재부팅: 설치가 완료되면 컴퓨터를 재부팅해야 합니다. "나중에 재부팅" 하지 말고 바로 해주세요. 재부팅 없이는 WSL2가 제대로 작동하지 않습니다.

2) Ubuntu 초기 설정: 재부팅 후 시작 메뉴에서 "Ubuntu"를 실행하면, 처음 한 번만 사용자 이름과 비밀번호를 설정하라는 화면이 나옵니다. 이때 설정하는 비밀번호는 Ubuntu 내부에서만 사용되는 것이니, 윈도우 비밀번호와 다르게 설정해도 됩니다. (꼭 기억해두세요!)

3) 버전 확인: 설정이 끝났으면 PowerShell에서 아래 명령으로 WSL2가 제대로 설치되었는지 확인합니다.

# WSL 버전 확인
wsl -l -v

# 예상 결과:
# NAME      STATE           VERSION
# Ubuntu    Running         2        ← VERSION이 2여야 합니다

주의: VERSION이 1로 표시되면 WSL1으로 설치된 것입니다. 이 경우 wsl --set-version Ubuntu 2 명령으로 업그레이드해야 합니다. WSL1으로는 OpenClaw 구동 시 문제가 생길 수 있습니다.

---

4. Step 3: Chocolatey 설치

Chocolatey가 뭔가요?

Chocolatey는 윈도우용 패키지 관리자입니다. macOS의 Homebrew, Ubuntu의 apt와 같은 역할이죠. Node.js, Git 같은 개발 도구를 한 줄 명령어로 설치·업데이트·삭제할 수 있어서, 개발 환경 세팅 시간을 크게 단축해줍니다.

"내가 직접 홈페이지 들어가서 설치 파일 다운로드하면 안 되나?" — 물론 됩니다. 하지만 Chocolatey를 쓰면 버전 관리와 업데이트가 편하고, 여러 도구를 동시에 설치할 수 있어서 효율적입니다.

설치 명령어

# 관리자 PowerShell에서 Chocolatey 설치
Set-ExecutionPolicy Bypass -Scope Process -Force
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

설치 확인

설치가 끝나면, PowerShell을 닫고 새로 열어서(역시 관리자 권한으로) 아래 명령으로 확인합니다. 새 창에서 확인하는 이유는 PATH 환경변수가 기존 창에는 반영되지 않기 때문입니다.

# Chocolatey 버전 확인 (새 PowerShell에서)
choco -v

# 예상 결과: 2.4.x 같은 버전 번호가 출력되면 성공

---

5. Step 4: Node.js 22 이상 설치

이 단계가 가장 중요합니다. OpenClaw의 런타임이 Node.js 22 이상이기 때문에, 버전이 낮으면 설치 자체가 실패합니다. Node.js를 설치하는 방법은 두 가지가 있으며, 상황에 따라 하나만 선택하면 됩니다.

방법 A: 윈도우에서 직접 설치 (간단)

Chocolatey를 이용해 윈도우 환경에 Node.js LTS를 설치합니다. 가장 간단한 방법입니다.

# 관리자 PowerShell에서
choco install nodejs-lts -y

# 설치 후 새 PowerShell을 열어서 확인
node -v   # v22.x.x 이상이어야 함
npm -v    # 10.x.x 이상이어야 함

방법 B: WSL(Ubuntu) 내에서 설치 (추천)

WSL2 환경에서 OpenClaw를 운영할 계획이라면, Ubuntu 내부에 Node.js를 설치하는 것이 더 안정적입니다. nvm(Node Version Manager)을 사용하면 여러 버전의 Node.js를 자유롭게 전환할 수 있어 편리합니다.

# Ubuntu(WSL) 터미널에서 실행

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

# 2. 터미널을 닫고 다시 열기 (또는 아래 명령 실행)
source ~/.bashrc

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

# 4. 버전 확인
node -v   # v22.x.x
npm -v    # 10.x.x

방법 A vs 방법 B, 어떤 걸 선택해야 하나요?

OpenClaw를 WSL2 환경에서 운영할 예정이라면 → 방법 B (nvm + WSL) 추천

WSL 없이 윈도우에서 직접 운영하고 싶다면 → 방법 A (Chocolatey) 선택

둘 다 설치해도 충돌은 없지만, 혼란을 피하려면 하나만 선택하는 것이 좋습니다.

---

6. Step 5: Git 및 필수 도구 설치

Git은 OpenClaw 소스를 다운로드하거나, 문제가 생겼을 때 특정 버전으로 되돌리는 데 필요합니다. 꼭 Git을 잘 알아야 하는 건 아니지만, 설치해두면 이후 단계에서 편합니다.

윈도우에서 설치

# 관리자 PowerShell에서
choco install git -y

WSL(Ubuntu)에서 설치

# Ubuntu 터미널에서
sudo apt update
sudo apt install -y git curl ca-certificates build-essential

build-essential은 C/C++ 컴파일러 등 빌드 도구 모음으로, 일부 npm 패키지가 네이티브 모듈을 컴파일할 때 필요합니다. 미리 설치해두면 나중에 "node-gyp 에러" 같은 골치 아픈 문제를 예방할 수 있습니다.

---

7. 최종 점검 체크리스트

 

 

모든 설치가 끝났으면, 아래 4개 명령을 실행해서 전부 정상 출력되는지 확인합니다. 하나라도 에러가 나면 해당 단계로 돌아가 다시 확인해주세요.

# PowerShell 또는 Ubuntu 터미널에서
wsl -l -v       # Ubuntu VERSION 2
node -v         # v22.x.x 이상
npm -v          # 10.x.x 이상
git --version   # git version 2.x.x

항목	명령어	기대 결과	안 되면?
WSL2	wsl -l -v	Ubuntu, VERSION 2	Step 2 재확인, BIOS 가상화 확인
Node.js	node -v	v22.x.x 이상	Step 4 재설치, 터미널 새로 열기
npm	npm -v	10.x.x 이상	Node.js와 함께 설치됨, Node 재설치
Git	git --version	2.x.x	Step 5 재확인

축하합니다! 4개 모두 정상 출력되면 환경 세팅이 완료된 것입니다. 이제 OpenClaw를 설치할 준비가 되었습니다. 다음 글에서는 Claude/Gemini API 키를 발급받는 방법을 안내합니다.

---

8. 자주 막히는 지점 FAQ

Q. wsl --install이 실패해요

가장 흔한 원인은 세 가지입니다.

1) 관리자 권한: PowerShell을 일반 사용자로 열었다면 관리자 권한으로 다시 실행하세요.

2) 가상화 비활성화: WSL2는 하드웨어 가상화(VT-x 또는 AMD-V)가 필요합니다. 컴퓨터 재시작 시 BIOS에 진입해서(보통 F2, Del, F10 키) 가상화 옵션을 켜야 합니다. 메인보드 제조사마다 위치가 다르니 "내 메인보드 모델명 + 가상화 활성화"로 검색해보세요.

3) Windows 업데이트: Windows 10 버전 2004(빌드 19041) 이상이 필요합니다. winver를 실행해서 현재 버전을 확인하고, 오래된 경우 Windows Update를 먼저 진행하세요.

Q. Chocolatey 설치 중 ExecutionPolicy 에러가 떠요

아래 명령을 먼저 실행한 후 다시 시도하세요. "현재 세션에서만" 실행 정책을 우회하는 것이라 시스템 보안에 영향을 주지 않습니다.

Set-ExecutionPolicy Bypass -Scope Process -Force

Q. node -v를 치면 "명령을 찾을 수 없다"고 나와요

Node.js 설치 후 기존 터미널 창에서는 PATH가 반영되지 않을 수 있습니다. 터미널을 완전히 닫고 새로 열어서 다시 시도하세요. 그래도 안 되면, 시스템 환경변수에서 Node.js 경로가 PATH에 포함되어 있는지 확인해야 합니다.

Q. WSL Ubuntu에서 sudo apt update가 실패해요

네트워크 문제일 가능성이 높습니다. 회사 VPN이나 프록시를 사용 중이라면 일시적으로 끈 후 다시 시도하세요. DNS 문제일 경우 sudo nano /etc/resolv.conf에서 nameserver를 8.8.8.8로 변경하면 해결되는 경우가 많습니다.

Q. 윈도우 Node.js와 WSL Node.js, 둘 다 설치해야 하나요?

아니요, 하나만 선택하세요. OpenClaw를 WSL에서 운영할 예정이면 WSL Ubuntu 안에만 설치하면 되고, 윈도우에서 운영할 예정이면 윈도우에만 설치하면 됩니다. 양쪽 다 설치해도 동작하지만, 어디서 실행하고 있는지 혼란스러울 수 있습니다.

---

9. 다음 글 안내

 

 

다음 글 예고: 3부 — Claude/Gemini API 키 발급 가이드

환경 세팅이 끝났으니, 이제 OpenClaw의 "두뇌"가 될 AI 모델의 API 키를 발급받을 차례입니다. 다음 글에서는 Anthropic Claude API와 Google Gemini API의 키 발급 절차를 스크린샷과 함께 단계별로 안내하고, 발급받은 키를 안전하게 보관하는 방법까지 다룹니다.

---

📌 관련 글

· OpenClaw 완벽 가이드 1/5 — 프롤로그: OpenClaw란?

· OpenClaw 완벽 가이드 3/5 — Claude/Gemini API 키 발급 (다음 글)

· 2026년 AI 6대 핵심 트렌드 총정리

---

참고 자료: Microsoft WSL 공식 설치 문서 · Chocolatey 공식 설치 문서 · nvm 공식 GitHub · Node.js 공식 사이트

이 글은 공식 문서/README 기반으로 실사용 관점에서 재구성한 정리글입니다. UI/정책은 업데이트로 바뀔 수 있으니 공식 문서를 함께 참고하세요.