홈 튜토리얼 카테고리 Skills 소개
ZH EN JA KO
설치 및 배포

Windows 시스템에 OpenClaw 설치하기 상세 튜토리얼

· 11 분 소요

들어가며

OpenClaw는 오픈소스, 자체 호스팅 AI 어시스턴트 플랫폼으로, WhatsApp, Telegram, Discord 등 다양한 메신저 채널에 연결할 수 있으며 Claude, OpenAI, Ollama 등 주요 대규모 언어 모델을 지원합니다. 본 문서에서는 Windows 시스템에서 OpenClaw를 설치하고 구성하는 방법을 상세히 안내합니다.

환경 요구 사항

설치를 시작하기 전에 시스템이 다음 요구 사항을 충족하는지 확인하십시오.

항목 최소 요구 사항 권장 구성
운영 체제 Windows 10 21H2 Windows 11 23H2+
Node.js 22.0+ 22 LTS 최신 버전
메모리 2 GB 4 GB+
디스크 공간 500 MB 2 GB+
네트워크 외부 네트워크 접근 가능 안정적인 광대역 연결

1단계: Node.js 설치

OpenClaw는 Node.js 22 이상이 필요합니다. 여러 버전 간 편리하게 전환할 수 있도록 nvm-windows를 사용하여 Node.js 버전을 관리하는 것을 권장합니다.

방법 1: nvm-windows 사용 (권장)

  1. nvm-windows 릴리스 페이지에서 최신 nvm-setup.exe를 다운로드합니다.

  2. 설치 프로그램을 실행하고 안내에 따라 설치를 완료합니다.

  3. 관리자 권한으로 PowerShell을 열고 다음 명령어를 실행합니다.

# 사용 가능한 Node.js 버전 확인
nvm list available

# Node.js 22 LTS 설치
nvm install 22

# Node.js 22로 전환
nvm use 22

# 설치 확인
node --version
npm --version

방법 2: Node.js 직접 설치

Node.js 공식 사이트에서 22 LTS 버전의 Windows 설치 패키지를 다운로드하고, 설치 프로그램을 실행하여 "필수 도구 자동 설치" 옵션을 선택합니다.

설치 완료 후 새 PowerShell 창을 열어 확인합니다.

node --version
# 출력이 v22.x.x여야 합니다

npm --version
# 출력이 10.x.x 이상이어야 합니다

2단계: OpenClaw 설치

PowerShell을 열고 전역 설치 명령어를 실행합니다.

npm install -g openclaw@latest

설치 완료 후 정상적으로 설치되었는지 확인합니다.

openclaw --version

버전 번호가 출력되면 설치가 성공한 것입니다.

자주 발생하는 설치 문제

권한 오류가 발생하는 경우 다음 방법을 시도해 보십시오.

# 방법 1: npm 전역 설치 디렉토리 설정
npm config set prefix "$env:APPDATA\npm"

# 방법 2: 관리자 권한으로 PowerShell을 실행한 후 설치 명령어 재실행
npm install -g openclaw@latest

네트워크 문제가 발생하는 경우 npm 미러를 설정할 수 있습니다.

# 타오바오 미러 소스 사용
npm config set registry https://registry.npmmirror.com

# 설치 완료 후 공식 소스로 복원
npm config set registry https://registry.npmjs.org

3단계: 초기 구성

OpenClaw를 처음 실행할 때 초기 구성 마법사를 완료해야 합니다.

openclaw onboard

마법사가 다음 설정을 안내합니다.

  1. AI 모델 제공업체 선택 — Claude, OpenAI, Ollama, Gemini, OpenRouter 등 지원
  2. API 키 입력 — 선택한 모델 제공업체에 맞는 키를 입력
  3. 통신 채널 선택 — 연동할 메신저 플랫폼 선택
  4. 게이트웨이 포트 설정 — 기본값은 18789

구성이 완료되면 파일이 다음 위치에 저장됩니다.

%USERPROFILE%\.config\openclaw\openclaw.json5

아무 텍스트 편집기로 이 파일을 열어 수동으로 편집할 수 있습니다.

4단계: OpenClaw 시작

openclaw up

시작 후 다음과 유사한 출력이 표시됩니다.

[OpenClaw] Gateway started on port 18789
[OpenClaw] Model provider: Claude (claude-sonnet-4-20250514)
[OpenClaw] Channels: ready
[OpenClaw] Dashboard: http://localhost:18789/dashboard

브라우저에서 http://localhost:18789/dashboard에 접속하면 관리 패널에 진입할 수 있습니다.

실행 상태 확인

# 실행 상태 확인
openclaw doctor

# 실행 로그 확인
openclaw logs

# 서비스 재시작
openclaw restart

5단계: Windows 환경 변수 설정

어떤 터미널 창에서든 OpenClaw를 정상적으로 사용하려면 시스템 환경 변수를 확인하고 설정하는 것이 좋습니다.

# 현재 PATH에 npm 전역 디렉토리가 포함되어 있는지 확인
$env:PATH -split ';' | Where-Object { $_ -like '*npm*' }

# 포함되어 있지 않으면 수동으로 추가
[System.Environment]::SetEnvironmentVariable(
    'PATH',
    "$env:PATH;$env:APPDATA\npm",
    'User'
)

6단계: Windows 서비스로 설정 (선택 사항)

시스템 시작 시 OpenClaw가 자동으로 실행되도록 하려면 node-windows를 사용하여 Windows 서비스로 등록할 수 있습니다.

node-windows 설치

npm install -g node-windows

서비스 설치 스크립트 생성

아무 디렉토리에 install-service.js 파일을 생성합니다.

const { Service } = require('node-windows');
const path = require('path');

// openclaw의 실제 경로 찾기
const openclawPath = path.join(
  process.env.APPDATA, 'npm', 'node_modules', 'openclaw', 'bin', 'openclaw.js'
);

const svc = new Service({
  name: 'OpenClaw',
  description: 'OpenClaw AI Assistant Platform',
  script: openclawPath,
  scriptOptions: 'up',
  nodeOptions: [],
  workingDirectory: process.env.USERPROFILE,
});

svc.on('install', () => {
  console.log('OpenClaw 서비스 설치 완료, 시작 중...');
  svc.start();
});

svc.on('start', () => {
  console.log('OpenClaw 서비스가 시작되었습니다');
});

svc.install();

관리자 권한으로 실행합니다.

node install-service.js

서비스 관리

설치가 완료되면 Windows 서비스 관리자에서 OpenClaw 서비스를 찾을 수 있으며, 명령줄로도 관리할 수 있습니다.

# 서비스 상태 확인
Get-Service -Name 'OpenClaw'

# 서비스 중지
Stop-Service -Name 'OpenClaw'

# 서비스 시작
Start-Service -Name 'OpenClaw'

# 서비스 재시작
Restart-Service -Name 'OpenClaw'

7단계: Windows 방화벽 설정

로컬 네트워크의 다른 기기에서 OpenClaw에 접근해야 하는 경우 방화벽 포트를 개방해야 합니다.

# 관리자 권한으로 실행
New-NetFirewallRule `
  -DisplayName "OpenClaw Gateway" `
  -Direction Inbound `
  -Protocol TCP `
  -LocalPort 18789 `
  -Action Allow

개방 후 로컬 네트워크의 다른 기기에서 http://사용자의IP:18789로 OpenClaw Dashboard에 접근할 수 있습니다.

PowerShell 실행 정책 안내

OpenClaw 실행 시 "스크립트를 로드할 수 없습니다" 오류가 발생하면 PowerShell 실행 정책을 조정해야 할 수 있습니다.

# 현재 정책 확인
Get-ExecutionPolicy

# 로컬 스크립트 허용으로 설정
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Windows Terminal 활용 팁

Windows Terminal에서 OpenClaw를 사용하는 것을 권장하며, 전용 프로필을 만들 수 있습니다.

  1. Windows Terminal 설정을 엽니다
  2. "새 프로필 추가"를 클릭합니다
  3. 이름을 OpenClaw로 설정합니다
  4. 명령줄에 pwsh -NoExit -Command "openclaw up"을 입력합니다
  5. 시작 디렉토리를 %USERPROFILE%로 설정합니다

이렇게 하면 해당 프로필을 열 때마다 자동으로 OpenClaw가 시작됩니다.

설치 확인

위 단계를 모두 완료한 후 진단 명령어를 실행하여 모든 것이 정상인지 확인합니다.

openclaw doctor

이 명령어는 다음을 점검합니다.

  • Node.js 버전이 요구 사항을 충족하는지
  • 구성 파일이 유효한지
  • 네트워크 연결이 정상인지
  • 설정된 모델 제공업체가 사용 가능한지
  • 설정된 통신 채널이 연결 가능한지

마무리

이로써 Windows 시스템에서 OpenClaw의 설치와 구성이 완료되었습니다. 다음 단계로 진행할 수 있습니다.

  • 구성 파일 가이드를 읽고 openclaw.json5의 각 설정을 심층적으로 이해하기
  • 원하는 메신저 플랫폼 연동하기
  • 커스텀 스킬 플러그인 만들기
  • 여러 AI 모델을 배포하고 지능형 라우팅 구성하기

문제가 발생하면 openclaw doctor를 실행하여 자가 점검하거나 문제 해결 문서를 참조하십시오.

OpenClaw는 무료 오픈소스 개인 AI 어시스턴트로, WhatsApp, Telegram, Discord 등 다양한 플랫폼을 지원합니다
더 많은 튜토리얼 Skills 다운로드

관련 튜토리얼

OpenClaw 설치 방법
OpenClaw Docker 배포 완전 가이드
OpenClaw VPS 서버 배포 완전 가이드