OpenClaw 2026 최종 설치 가이드: 처음부터 개인 AI 비서 배포하기

빠른 결론: 설치 경로부터 선택하세요

대부분의 독자는 다음 기준으로 바로 선택할 수 있습니다.
개인 컴퓨터에서는 npm을 우선 사용하고, 서버에서 장기간 실행할 때는 Docker를 선택하세요. 빠르게 체험만 하고 싶다면 원클릭 스크립트가 적합합니다.
먼저 Node 버전과 네트워크 환경을 확인한 뒤 설치하면 ‘설치 실패와 반복 재시도’로 낭비하는 시간을 대부분 줄일 수 있습니다.

새벽 두 시, 저는 화면에 뜬 17번째 오류 메시지를 멍하니 바라보고 있었습니다.

“Cannot find module ‘@anthropic-ai/sdk’”라는 빨간 문구를 본 지도 벌써 사흘째였습니다. 수많은 오픈 소스 프로젝트를 다뤄 본 개발자로서 웬만한 설치 실패는 다 겪어 봤다고 생각했습니다. 하지만 OpenClaw 배포 과정에서는 ‘자신만만함’에서 ‘현실을 의심하는 지경’까지 이르는 감정의 변화를 제대로 경험했습니다.

솔직히 Mac Mini에서 첫 대화를 마침내 실행했을 때의 성취감은 처음 “Hello World”를 출력했던 순간에 견줄 만했습니다. OpenClaw는 일단 설치만 끝내면 정말 매력적입니다. WhatsApp, Telegram, Discord는 물론 iMessage에서도 언제든 Claude나 GPT-4 같은 최고 수준의 AI를 호출할 수 있고, 데이터는 완전히 비공개로 유지되어 개인정보 유출을 걱정하지 않아도 됩니다.

문제는 설치 과정이 초보자에게 그다지 친절하지 않다는 점입니다.

이 가이드에서는 과장된 약속을 하거나 이미 열 번은 읽어 봤을 공식 문서의 군더더기를 늘어놓지 않겠습니다. 제가 직접 마주친 문제, 시도한 방법, 최종적으로 성공한 절차를 있는 그대로 알려 드립니다. Windows 사용자든, Mac 사용자든, 서버 배포 경험이 많은 사람이든 자신에게 맞는 방법을 찾을 수 있습니다. Windows의 공식 설치 안내는 Windows 네이티브와 WSL2를 모두 다룹니다. 아래 Linux 명령줄 절차를 그대로 활용하려는 경우에는 WSL2가 대체로 더 편합니다.

저렴하게 ‘새우 키우기’: ArkClaw로 AI Agent의 진입 장벽 낮추기

최근 인기를 끄는 OpenClaw(바닷가재)는 유용하지만 설정 과정이 지나치게 복잡하다고 느끼시나요? ByteDance Volcano Engine의 ArkClaw는 진입 장벽을 크게 낮췄습니다. 서버와 Token 설정을 씨름할 필요 없이 클릭 한 번으로 24시간 온라인 상태에서 브라우저를 제어하고, 스크립트를 실행하며, 일정을 관리하는 ‘AI 일꾼’을 이용할 수 있습니다.

무엇보다 가격이 저렴합니다. 월 요금은 9.9위안이며, 제 초대 코드 ZLKUK54M을 사용해 여기에서 가입하면 8.9위안에 이용할 수 있습니다. 프로그래머라면 Coding Plan Pro에 가입해 무료로 사용할 수도 있습니다.

설치 전 준비: 바로 시작하지 마세요

많은 사람이 ‘원클릭 설치 스크립트’를 보면 신이 나서 바로 복사해 붙여 넣습니다. 하지만 잠시 멈추세요.

OpenClaw에는 엄격한 시스템 요구 사항이 있으며, 이를 건너뛰면 이후 과정에서 계속 문제가 발생합니다. 공식 문서와 커뮤니티 피드백을 기준으로 다음 항목을 확인해야 합니다.

Node.js 버전(공식 요구 사항과 동일)

공식 설치 문서에는 Node 24 권장, **최소 Node 22.14+**라고 명시되어 있으며, 원클릭 스크립트도 요구 사항을 충족하지 않으면 안내를 표시합니다. 제가 Node 20으로 시도했을 때는 의존성 문제가 발생했지만, 24로 업그레이드한 뒤에는 훨씬 원활했습니다.

node --version

v22.14보다 낮다면 최소 v22.14로 업그레이드하거나 v24를 바로 설치하세요(권장). Windows 사용자도 24.x를 우선 사용하는 것이 좋습니다.

운영체제 호환성

• macOS: 12.0(Monterey) 이상, Intel과 Apple Silicon 모두 지원
• Windows: Windows 네이티브와 WSL2를 모두 공식 지원하며, 전체 기능의 안정적인 사용을 위해 공식 문서에서는 WSL2를 더 권장
• Linux: Ubuntu 20.04+, Debian 11+, CentOS 8+ 등 일반적인 배포판에서 주로 테스트됨

API Key 준비

OpenClaw 자체는 ‘Gateway’일 뿐이므로 실제로 사용하려면 구체적인 AI 서비스와 연결해야 합니다. 현재 Claude(Anthropic), OpenAI, Google Gemini 등을 지원합니다. 가장 좋은 경험을 위해 Claude API Key를 하나 이상 준비하는 것이 좋습니다.

중국 내 사용자를 위한 특별 안내

중국에서는 npm 공식 레지스트리가 매우 느리므로 미리 Taobao 미러로 변경하는 것이 좋습니다.

npm config set registry https://registry.npmmirror.com

API 호출을 위한 네트워크도 문제입니다. Anthropic과 OpenAI API는 모두 해외 네트워크 환경이 필요합니다. 안정적인 해외 연결이 없다면 규정을 준수하는 중계 방안을 찾아보세요.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

방법 1: 원클릭 스크립트 설치(가장 빠름, 5분이면 완료)

다음 조건에 해당한다면 이 방법을 바로 선택하세요.

• 운영체제가 macOS, Linux 또는 WSL2임
• 복잡한 설정 없이 빠르게 체험하고 싶음
• 시스템 변경을 어느 정도 허용할 수 있음

설치 명령

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

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

1. Node.js 버전 확인(요구 버전보다 낮으면 업그레이드 안내)
2. openclaw npm 패키지 전역 설치
3. 필요한 설정 파일 디렉터리 생성(~/.openclaw/)
4. 시스템 서비스 설정(선택 사항)

설치 후 초기화

openclaw onboard --install-daemon

이 단계에서는 API Key를 입력하고 기본 대화 채널을 설정합니다. 안내대로 진행하면 되며 특별히 주의할 부분은 없습니다.

설치 확인

openclaw --version

버전 번호가 출력되면 설치에 성공한 것입니다. 모든 과정이 순조롭다면 실제로 5분이면 충분합니다.

하지만 솔직히 말씀드리면 이 ‘원클릭’ 스크립트는 제 Ubuntu 서버 한 대에서 권한 문제로 두 번이나 실패했습니다. 비슷한 문제가 발생하더라도 당황하지 말고 아래의 npm 수동 설치 방법을 확인하세요.

방법 2: npm 전역 설치(가장 유연하며 숙련 사용자에게 권장)

제가 가장 자주 사용하고 가장 추천하는 설치 방식입니다. 단계는 조금 더 많지만 문제가 발생했을 때 원인을 찾기 쉽고 시스템에 미치는 영향도 더 작습니다.

1단계: Node.js 환경 확인

# 버전 확인
node --version

# 버전이 낮다면 nvm으로 관리하는 것을 권장
# macOS/Linux에 nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Node 24 설치
nvm install 24
nvm use 24

2단계: OpenClaw 설치

npm install -g openclaw@latest

@latest를 사용하면 최신 버전을 설치할 수 있습니다. OpenClaw는 업데이트가 잦으며, 2026년 2월 기준 버전은 이미 v2026.2.24에 도달했습니다.

설치 중 EACCES 권한 오류가 발생한다면(macOS에서 흔함) npm 전역 디렉터리 권한이 제대로 설정되지 않은 것입니다. 다음과 같이 해결합니다.

# 전용 디렉터리 생성
mkdir ~/.npm-global

# npm이 새 디렉터리를 사용하도록 설정
npm config set prefix '~/.npm-global'

# PATH에 추가
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 재설치
npm install -g openclaw@latest

3단계: 설정 초기화

openclaw onboard --install-daemon

이 단계에서는 대화형 안내에 따라 다음 작업을 완료합니다.

1. 연결할 AI 제공업체 선택(Claude, OpenAI, Gemini 등)
2. 해당 API Key 입력
3. 메시지 채널 설정(Telegram Bot, Discord 등)
4. 시스템 서비스 설정(선택 사항이지만 권장)

4단계: Gateway 시작 및 확인

앞 단계에서 openclaw onboard --install-daemon을 실행했다면 일반적으로 로컬 Gateway 서비스가 이미 등록되어 있습니다. 먼저 다음 명령으로 확인하세요.

openclaw gateway status

포그라운드에서 디버깅하며 터미널을 열어 두고 로그를 확인하려면 다음 명령을 사용합니다.

openclaw gateway

설치된 시스템 서비스를 명시적으로 시작하거나 중지하려면 공식 CLI와 동일한 다음 명령을 사용합니다.

openclaw gateway start
openclaw gateway stop

방법 3: Docker 설치(가장 안전하며 서버 배포에 권장)

OpenClaw를 VPS, NAS 또는 장기간 안정적으로 실행해야 하는 환경에서 운영하려면 Docker가 가장 현명한 선택입니다. 컨테이너 격리를 통해 AI Agent의 오작동이 호스트 시스템에 영향을 주는 것을 효과적으로 막을 수 있습니다. 농담처럼 들릴 수 있지만, 실제로 OpenClaw 인스턴스가 파일을 잘못 삭제한 사례도 있습니다.

1단계: Docker 환경 확인

docker --version
docker-compose --version

엄격한 버전 요구 사항은 없지만 Docker 20.10 이상을 권장합니다.

2단계: 설정 파일 디렉터리 생성

mkdir -p ~/openclaw-data/config
mkdir -p ~/openclaw-data/data

3단계: Docker Compose 파일 준비

# docker-compose.yml
version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ~/openclaw-data/config:/app/config
      - ~/openclaw-data/data:/app/data
    environment:
      - NODE_ENV=production
      - ANTHROPIC_API_KEY=${{ANTHROPIC_API_KEY}}
      - OPENAI_API_KEY=${{OPENAI_API_KEY}}

4단계: 환경 변수 설정

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

# .env 파일 생성
cat > ~/openclaw-data/.env << EOF
ANTHROPIC_API_KEY=your_claude_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
EOF

5단계: 컨테이너 시작

cd ~/openclaw-data
docker-compose up -d

6단계: 로그로 상태 확인

docker logs -f openclaw

“OpenClaw Gateway started on port 3000”이 표시되면 성공한 것입니다.

참고로 Docker 방식에는 한 가지 추가 장점이 있습니다. Mac Mini, Raspberry Pi 또는 Docker를 실행할 수 있는 어떤 장치에든 배포한 뒤 휴대전화의 Telegram이나 WhatsApp에서 언제든 호출할 수 있습니다. 실제로 많은 사람이 이런 용도로 OpenClaw를 사용합니다.

Windows: WSL2 상세 절차(선택 경로)

WSL2를 선택했다면 아래 내용은 본문의 Linux 절차를 따를 때 자주 마주치는 문제입니다. Windows 네이티브 설치도 공식 지원되므로 필요에 따라 설치 문서를 확인하면 됩니다.

문제 1: WSL 버전이 올바르지 않음

# WSL 버전 확인
wsl --list --verbose

Version 1로 표시된다면 업그레이드해야 합니다.

# PowerShell(관리자 권한)에서 실행
wsl --set-version Ubuntu 2

문제 2: WSL2 메모리 부족

OpenClaw는 실행 중 일정량의 메모리를 사용하며, WSL2 기본 설정으로는 부족할 수 있습니다. Windows 사용자 디렉터리에 .wslconfig 파일을 만드는 것이 좋습니다.

[wsl2]
memory=4GB
processors=2

그런 다음 WSL을 다시 시작합니다.

wsl --shutdown

문제 3: Windows 방화벽 차단

Windows 브라우저에서 WSL2 내부에서 실행 중인 OpenClaw 웹 인터페이스에 접근하려면 Windows 방화벽에서 해당 포트를 허용해야 할 수 있습니다.

Mac Mini에서 OpenClaw 실행하기

Mac Mini는 전력 소모가 적고 조용하며 성능도 충분해 OpenClaw를 실행하기에 상당히 좋은 선택입니다. 제가 사용하는 M1 Mac Mini도 이미 3개월 동안 안정적으로 실행되고 있습니다.

M 시리즈 칩 주의 사항

Docker 이미지는 ARM64를 지원하는 버전을 선택해야 합니다. 최신 OpenClaw 공식 이미지는 Apple Silicon을 네이티브로 지원하므로 Rosetta 변환이 필요하지 않습니다.

# docker-compose.yml에서 플랫폼 지정(일반적으로 필요 없지만 pull 실패 시 시도)
services:
  openclaw:
    platform: linux/arm64
    image: openclaw/openclaw:latest

백그라운드에서 상시 실행

macOS에서는 launchd로 서비스를 관리하는 것이 좋습니다. 설치할 때 사용한 --install-daemon 옵션이 plist 파일을 자동으로 생성하지만, 수동으로 설치했다면 직접 설정해야 할 수 있습니다.

# 서비스 상태 확인
launchctl list | grep openclaw

# 수동 로드
launchctl load ~/Library/LaunchAgents/ai.openclaw.daemon.plist

OpenClaw에서 자주 발생하는 오류 해결

절차를 그대로 따르더라도 다양한 문제가 발생할 수 있습니다. 자주 발생하는 오류와 해결 방법을 정리했습니다.

오류 1: “Cannot find module” 유형

원인: npm 설치가 불완전하거나 버전이 호환되지 않음

해결:

npm uninstall -g openclaw
npm cache clean --force
npm install -g openclaw@latest

오류 2: “EACCES: permission denied”

원인: npm 전역 디렉터리 권한 문제

해결: 앞의 npm 설치 섹션에 나온 권한 문제 해결 절차를 참고하세요.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

오류 3: API 호출에서 401/403 반환

원인: API Key가 유효하지 않거나 사용 한도가 소진됨

확인:

# 설정 확인
openclaw config get

# 다시 설정
openclaw config set anthropic.apiKey=your_new_key

오류 4: Docker 컨테이너가 계속 재시작됨

원인: 환경 변수 설정 오류 또는 포트 충돌

확인:

# 상세 로그 확인
docker logs openclaw

# 포트 사용 여부 확인
lsof -i :3000

오류 5: 메시지 채널에서 응답을 받지 못함

원인: Webhook 설정 오류 또는 네트워크 연결 실패

확인:

• Telegram: Bot Token이 올바르고 Webhook URL에 접근할 수 있는지 확인
• Discord: Bot 권한이 올바르게 설정되고 Intents가 활성화되어 있는지 확인
• 중국 내 서버: Telegram/Discord 서버에 접근할 수 있는지 확인

설치 후 권장 설정

OpenClaw 설치를 마친 뒤 다음 설정을 적용하면 사용 경험을 더 개선할 수 있습니다.

1. 여러 AI 제공업체 설정

Claude와 GPT-4를 모두 설정하는 것이 좋습니다. 한 서비스가 불안정할 때 다른 서비스로 자동 전환할 수 있습니다.

2. 시스템 전역 단축키 설정

macOS에서는 Alfred + Workflow를, Windows에서는 PowerToys Run을 사용하면 어디서나 빠르게 호출할 수 있습니다.

3. 설정 정기 백업

# 설정 파일은 모두 ~/.openclaw/에 있음
cp -r ~/.openclaw ~/openclaw-backup-$(date +%Y%m%d)

4. 실행 상태 모니터링

Docker 배포에는 다음과 같은 상태 확인을 추가하는 것이 좋습니다.

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 30s
  timeout: 10s
  retries: 3

마무리

설치 방법을 아직 결정하지 못했다면 다음과 같이 선택하세요.

• 최대한 빨리 체험하고 싶음 → 원클릭 스크립트
• 일상적으로 주력 사용 → npm 전역 설치
• 서버에서 장기간 실행 → Docker

OpenClaw 설치는 생각만큼 어렵지 않습니다. 많은 ‘함정’은 문서가 충분히 친절하지 않고 오류 메시지가 명확하지 않아 생깁니다. 이 가이드가 시행착오를 줄이는 데 도움이 되기를 바랍니다.

마지막으로 조금 다른 이야기를 해 보겠습니다. OpenClaw 배포는 단순히 소프트웨어 하나를 설치하는 일에 그치지 않습니다. 데이터의 비공개성, 자율적인 통제, 특정 플랫폼에 종속되지 않는다는 AI 활용 태도를 뜻하기도 합니다. AI 기능이 점점 강력해지는 지금, 이런 ‘주권 의식’은 생각보다 더 중요할 수 있습니다.

이제 직접 사용해 보세요. 문서에서 다루지 않은 문제가 생기면 댓글로 함께 이야기해 주세요. 제가 겪은 문제는 여러분이 생각하는 것보다 더 많을지도 모릅니다.

다음 글

• OpenClaw 설치 문제 해결: Node, Docker, WSL2 및 API 오류
• OpenClaw 설정 상세 가이드: openclaw.json 완전 정복
• OpenClaw 보안 설정 완전 가이드: 5단계 방어