OpenClaw는 CLI 관리, 백그라운드 서비스, Control UI 및 다양한 메시징 채널을 지원하는 AI Agent Gateway입니다. Windows 사용자는 PowerShell 스크립트, npm, 또는 Windows Hub 데스크톱 애플리케이션을 통해 OpenClaw를 설치할 수 있습니다. 이 문서에서는 Windows 환경에서의 시스템 요구 사항, 설치 방법, 서비스 설정 및 문제 해결 방법을 안내합니다.

시스템 요구 사항

• 운영 체제: Windows 10/11 (Windows 네이티브 또는 WSL2)
• Node.js: v24 (권장) 또는 v22.19 이상
• 패키지 관리자 (수동 설치 시): npm, pnpm, 또는 bun
• 권한: PowerShell 실행 정책이 설치 스크립트 실행을 허용해야 합니다.

참고: WSL2 환경에서도 OpenClaw를 설치할 수 있으며, 이는 더 나은 격리성을 제공합니다. 안정적인 프로덕션 환경을 위해서는 WSL2 내에 설치하는 것을 권장합니다.

설치 방법

1. PowerShell 일괄 설치 (권장)

관리자 권한이 있는 PowerShell 또는 일반 PowerShell에서 다음 명령을 실행합니다:

Invoke-RestMethod -Uri https://openclaw.ai/install.ps1 -UseBasicParsing | Invoke-Expression

이 스크립트는 자동으로 다음을 수행합니다:

• 운영 체제 감지
• Node.js 설치 (필요시)
• OpenClaw CLI 설치
• 초기 설정(onboarding) 과정 시작

초기 설정 건너뛰기 (CI/자동화 환경)

iex ((New-Object System.Net.WebClient).DownloadString('https://openclaw.ai/install.ps1')) -NoOnboard

2. npm 전역 설치

Node.js 환경이 이미 구성되어 있다면 다음 명령어를 사용합니다:

npm install -g openclaw@latest
openclaw onboard --install-daemon

pnpm 사용 시

pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

bun 사용 시

bun add -g openclaw@latest
openclaw onboard --install-daemon

3. Windows Hub 데스크톱 애플리케이션

Windows 사용자는 OpenClaw Hub 네이티브 애플리케이션을 설치하여 GUI 기반 설치 마법사, 시스템 트레이 아이콘, 로컬 채팅, Node 모드 및 로컬 MCP 모드 등 다양한 기능을 이용할 수 있습니다. 명령줄 사용을 선호하지 않는 개인 사용자에게 적합합니다.

설치 후 초기 설정 (Onboarding)

다음 명령어로 초기 설정 과정을 시작합니다:

openclaw onboard --install-daemon

이 과정에서 다음을 설정합니다:

1. AI Provider API 키 (예: OpenAI, Anthropic)
2. Gateway 모드
3. 백그라운드 데몬 설치

Windows 백그라운드 데몬

OpenClaw는 우선적으로 예약 작업(Scheduled Task)을 생성하여 데몬으로 실행합니다. 예약 작업 생성에 실패하면 시작 프로그램(Startup Folder)에 등록하여 실행합니다.

설치 검증

다음 명령어를 실행하여 설치가 정상적으로 되었는지 확인합니다:

openclaw --version
openclaw doctor
openclaw gateway status

Control UI 접속

Gateway는 기본적으로 18789 포트를 사용합니다. 웹 브라우저에서 다음 주소로 접속합니다:

http://127.0.0.1:18789/

처음 접속 시, 설정(Settings) 메뉴에서 초기 설정 과정 중에 생성된 Gateway Token을 입력해야 합니다.

주요 명령어

• Gateway 상태 확인: openclaw gateway status
• Gateway 시작: openclaw gateway start
• Gateway 중지: openclaw gateway stop
• 시스템 상태 점검: openclaw doctor
• 최신 버전 업데이트: openclaw update --channel stable

소스 코드로부터 설치 (개발자용)

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build
pnpm link --global
openclaw onboard --install-daemon

일반적인 문제 해결

1. openclaw 명령어 미인식

Node.js 전역 설치 경로가 시스템 PATH 환경 변수에 포함되어 있는지 확인합니다:

node -v
npm prefix -g

$(npm prefix -g) 경로를 시스템 PATH에 추가하고 터미널을 다시 시작하십시오.

2. Gateway 시작 실패

openclaw doctor 또는 openclaw gateway status 명령어로 상태를 확인합니다. 포트 18789 충돌 여부와 API 키 설정을 점검하십시오.

3. Control UI 접속 시 'Unauthorized' 오류

새로운 Gateway Token을 발급받아 설정에 다시 입력합니다:

openclaw dashboard --no-open

4. Windows 네이티브 vs WSL2 선택

• Windows 네이티브: 개인 PC에서 로컬 테스트 및 OpenClaw Hub 사용에 적합합니다.
• WSL2: Linux 환경과 유사하여 개발 및 장기 실행 서비스에 더 안정적입니다.

제거 방법

npm uninstall -g openclaw

또한, 사용자 홈 디렉토리 내의 OpenClaw 설정 폴더(기본값: .openclaw)와 예약 작업 또는 시작 프로그램 항목을 수동으로 삭제해야 합니다.

Windows 환경에서 OpenClaw를 가장 빠르게 설치하는 방법은 PowerShell 일괄 설치 스크립트를 이용하는 것입니다. 프로덕션 또는 서버 환경에서는 Docker를 사용하여 격리성을 높이는 것을 권장하며, 이 경우 Linux 배포판 설치 가이드를 참조하십시오.