Windows에서 OpenClaw 설치하기

윈도우 환경에서 새로운 개발 도구를 설치하다 보면 환경 설정 문제로 막히는 경우가 종종 있죠. 특히 리눅스 기반 도구들을 윈도우에서 매끄럽게 실행하는 것은 생각보다 까다로운 작업이 될 수 있어요.

OpenClaw를 Windows에 설치하는 방법은 간단하지만, 윈도우만의 특이사항 몇 가지를 미리 알아두면 좋습니다. 직접 테스트해 본 결과, PowerShell을 이용한 네이티브 방식과 WSL2를 이용한 방식 두 가지가 있어요.

요약: 안정적인 환경을 원하신다면 WSL2를 강력히 추천해요. PowerShell은 빠른 테스트용으로는 괜찮지만 몇 가지 제한 사항이 있습니다.

필요한 것

시작하기 전에 다음 사항들을 확인해 주세요.

• Windows 10 (버전 1903 이상) 또는 Windows 11
• PowerShell 5.1 이상 (최신 Windows에는 기본 설치되어 있어요)
• API key: Anthropic, OpenAI, Google 중 하나 (또는 무료 로컬 모델을 위한 Ollama)

Node.js가 설치되어 있지 않다면 설치 프로그램이 자동으로 처리해 줍니다.

Quick Start: PowerShell 방법 (빠르지만 제한적)

⚠️ 주의: PowerShell 네이티브 설치는 공식 팀에서 아직 완벽하게 테스트하지 않았으며, 도구 호환성 문제가 발생할 수 있습니다. 실제 서비스 운영 용도라면 WSL2를 사용하세요.

PowerShell을 관리자 권한으로 열고 아래 명령어를 실행하세요.

iwr -useb https://openclaw.ai/install.ps1 | iex

설치 프로세스

1. Node.js 22+ 버전을 확인합니다. (없을 경우 winget, Chocolatey, Scoop을 통해 설치)
2. npm install -g openclaw@latest 명령어를 실행합니다.
3. 설정 마법사를 시작합니다.

설치 옵션 선택

PowerShell 설치 프로그램은 두 가지 방식을 지원해요.

# 기본 권장 사항: npm으로 설치
iwr -useb https://openclaw.ai/install.ps1 | iex

# 대안: GitHub 소스에서 직접 설치
iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git

# git 설치 시 커스텀 디렉토리 지정
iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -GitDir "C:\openclaw"

WSL2 방법 (권장 사항)

OpenClaw를 본격적으로 사용하거나 가장 안정적인 경험을 원하신다면 WSL2가 정답이에요. 윈도우 안에서 완전한 Linux 환경을 사용할 수 있습니다.

1단계: WSL2 설치

PowerShell을 관리자 권한으로 열고 입력하세요.

wsl --install

설치가 끝나면 컴퓨터를 재부팅해 주세요.

1.5단계: systemd 활성화 (필수)

재부팅 후 Ubuntu를 열고 다음 명령어를 실행하세요.

# OpenClaw Gateway를 위한 systemd 활성화
sudo nano /etc/wsl.conf

파일에 아래 내용을 추가합니다.

[boot]
systemd=true

저장(Ctrl+O, Enter, Ctrl+X)한 뒤, PowerShell에서 WSL을 재시작하세요.

wsl --shutdown
wsl

2단계: Ubuntu 설정

재부팅 후 Ubuntu가 자동으로 실행되면 사용자 이름과 비밀번호를 생성하세요.

3단계: WSL에 OpenClaw 설치

Ubuntu 터미널에서 아래 명령어를 실행합니다.

curl -fsSL https://openclaw.ai/install.sh | bash

이제 리눅스 환경에서 OpenClaw를 사용할 준비가 끝났습니다.

설치 후: 설정 마법사

설치가 완료되면 설정 마법사가 자동으로 시작됩니다. 다음 항목들을 구성하게 됩니다.

1. AI Model Provider

Provider	특징
Anthropic (Claude)	전반적으로 성능이 가장 좋으며 API key가 필요합니다.
OpenAI	코딩 작업에 훌륭합니다.
Google Gemini	무료 티어를 사용할 수 있습니다.
Ollama	100% 무료이며 로컬에서 실행됩니다.

2. Chat Channel

OpenClaw와 대화할 채널을 선택하세요.

• WhatsApp, Telegram, Discord, iMessage 중 선택 가능합니다.

3. Gateway Daemon

안내에 따라 Gateway를 백그라운드 서비스(daemon)로 설치하세요.

openclaw onboard --install-daemon

이렇게 하면 OpenClaw가 백그라운드에서 계속 실행됩니다.

설치 확인

# 버전 확인
openclaw --version

# 진단 도구 실행
openclaw doctor

# 대시보드 열기
openclaw dashboard

문제 해결

”openclaw is not recognized” 에러

npm 글로벌 bin 폴더가 PATH에 등록되지 않았을 때 발생합니다.

해결 방법:

# npm prefix 확인
npm config get prefix

# 결과값 뒤에 \bin을 붙여 PATH에 추가하세요.
# 보통 이 경로입니다: %AppData%\npm

설정 후 PowerShell을 다시 여세요.

”spawn git ENOENT” 에러

소스 설치를 위해서는 Git for Windows가 필요합니다.

해결 방법:

1. git-scm.com/download/win에서 Git 다운로드
2. 기본 설정으로 설치
3. PowerShell을 다시 열고 재시도

Node.js 버전 문제

구버전 Node.js를 사용 중이라면 업데이트가 필요합니다.

# winget 사용 시
winget install OpenJS.NodeJS.LTS

# Chocolatey 사용 시
choco install nodejs-lts

# Scoop 사용 시
scoop install nodejs-lts

Windows Defender 차단 문제

OpenClaw 디렉토리를 제외 목록에 추가하세요.

1. Windows 보안 → 바이러스 및 위협 방지
2. ‘설정 관리’ 클릭
3. ‘제외’ 항목에서 ‘제외 추가 또는 제거’ 클릭
4. 폴더 추가: %AppData%\npm\node_modules\openclaw

여전히 도움이 필요하신가요? 모든 문서를 학습한 AI Setup Assistant가 윈도우 관련 문제를 실시간으로 도와드릴 수 있습니다.

PowerShell vs WSL2 비교

항목	PowerShell	WSL2
설정 시간	2분	10분
안정성	보통	매우 우수
쉘 도구	제한적	리눅스 전체 도구 사용 가능
업데이트	간편함	간편함

추천: 가볍게 시작하고 싶다면 PowerShell을 먼저 써보세요. 더 세밀한 제어가 필요하거나 문제가 발생한다면 WSL2로 전환하는 것이 좋습니다.

다음 단계

• 전체 설치 가이드 → — 모든 플랫폼 공통 사항
• Telegram 연결하기 → — 스마트폰에서 제어하기
• Docker 배포 → — 격리된 컨테이너 환경 설정
• 로컬 AI 사용하기 → — API 비용 없이 사용하기

---

도움이 필요하면 OpenClaw Discord에 방문하거나 공식 문서를 확인해 보세요.