OpenClaw v2026.2 적용 | 본 문서는 Node.js >= 22 환경과 AI API Key(Anthropic Claude 권장)를 보유하고 있다고 가정합니다.

TL;DR: 5분 만에 OpenClaw 설치 완료. npm/pnpm/bun/Docker 네 가지 방식 지원, 권장 npm install -g openclaw@latest && openclaw onboard. 설정 파일은 ~/.openclaw/openclaw.json에 있으며, openclaw gateway로 시작합니다. Docker 배포, 설정 파일 구조, 일반 문제 해결을 상세히 다룹니다.

사전 요구사항

필수 환경

권장 환경

AI API Key

OpenClaw가 AI 모델에 연결하려면 API Key가 필요합니다. 권장:

💡 권장: Anthropic Claude Opus 4.6은 긴 컨텍스트 처리와 프롬프트 인젝션 방어에 가장 뛰어납니다.

환경 검증

# Node.js 버전 확인
node --version
# 출력 예: v22.12.0

# npm 버전 확인
npm --version
# 출력 예: 10.9.0

# 시스템 정보 확인
uname -a  # Linux/macOS
# 또는
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"  # Windows

설치 방식 비교

flowchart TB
    A[설치 방식 선택] --> B{사용 시나리오?}
    B -->|빠른 체험| C[npm 전역 설치]
    B -->|일상 사용| D[pnpm/bun 설치]
    B -->|프로덕션 배포| E[Docker 배포]
    B -->|개발 기여| F[소스 빌드]
    
    C --> G[5분 완료]
    D --> H[더 빠른 의존성 관리]
    E --> I[환경 격리, 재현 가능]
    F --> J[커스터마이징, 개발 참여]

방식 비교표

방식 1: npm 전역 설치 (초보자 권장)

설치 단계

# 1. 최신 안정판 설치
npm install -g openclaw@latest

# 2. 설치 확인
openclaw --version
# 출력 예: 2026.2.26

# 3. 도움말 보기
openclaw --help

설치 후 디렉터리 구조

/usr/local/lib/node_modules/openclaw/  # 전역 설치 디렉터리
├── bin/
│   └── openclaw                        # 실행 파일
├── lib/
│   └── ...                             # 핵심 라이브러리
└── package.json

~/.openclaw/                            # 사용자 데이터 디렉터리(첫 실행 시 생성)
├── openclaw.json                       # 메인 설정 파일
├── credentials/                       # 채널 인증 정보 저장
├── workspace/                          # Agent 작업 공간
│   ├── AGENTS.md                      # Agent 동작 가이드
│   ├── SOUL.md                        # Agent 성격 설정
│   └── skills/                        # 사용자 정의 스킬
└── logs/                              # 로그 디렉터리

입문 마법사 실행

# 대화형 설정 마법사
openclaw onboard --install-daemon

마법사는 다음을 안내합니다:

sequenceDiagram
    participant U as 사용자
    participant W as 마법사
    participant S as 시스템
    
    U->>W: onboard 시작
    W->>U: 모델 제공자 선택
    U->>W: Anthropic 선택
    W->>U: API Key 입력
    U->>W: Key 붙여넣기
    W->>U: Gateway 포트 선택
    U->>W: 18789(기본값)
    W->>U: 데몬 설치 여부?
    U->>W: 예
    W->>S: systemd/launchd 서비스 생성
    S-->>W: 설치 완료
    W-->>U: 설정 완료!

방식 2: pnpm 설치 (일상 사용 권장)

pnpm 설치

# npm으로 pnpm 설치
npm install -g pnpm

# 또는 독립 스크립트 사용
curl -fsSL https://get.pnpm.io/install.sh | sh -

OpenClaw 설치

# pnpm으로 설치
pnpm add -g openclaw@latest

# 확인
openclaw --version

pnpm 장점

방식 3: bun 설치 (최고 속도)

bun 설치

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# 또는 npm 사용
npm install -g bun

OpenClaw 설치

# bun으로 설치
bun add -g openclaw@latest

# 확인
openclaw --version

bun 장점

방식 4: Docker 배포 (프로덕션 권장)

이미지 가져오기

# 최신 이미지 풀
docker pull openclaw/openclaw:latest

# 또는 버전 지정
docker pull openclaw/openclaw:2026.2

기본 실행

# 최소 실행
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  -e ANTHROPIC_API_KEY=your_key_here \
  openclaw/openclaw:latest

# 로그 확인
docker logs -f openclaw

Docker Compose 설정

docker-compose.yml 생성:

version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./openclaw-data:/root/.openclaw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      # 또는 설정 파일 사용
      # - OPENCLAW_CONFIG=/root/.openclaw/openclaw.json
    healthcheck:
      test: ["CMD", "openclaw", "health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

서비스 시작:

# .env 파일 생성
echo "ANTHROPIC_API_KEY=your_key_here" > .env

# 시작
docker-compose up -d

# 상태 확인
docker-compose ps

# 로그 확인
docker-compose logs -f

Docker 네트워크 설정

# docker-compose.yml 확장 설정
services:
  openclaw:
    # ... 기타 설정
    networks:
      - openclaw-net

  # 선택: 리버스 프록시
  caddy:
    image: caddy:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
    networks:
      - openclaw-net

networks:
  openclaw-net:
    driver: bridge

방식 5: 소스 빌드 (개발자)

저장소 클론

# 메인 저장소 클론
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 의존성 설치(pnpm 권장)
pnpm install

# 빌드
pnpm build

# 실행
pnpm openclaw onboard

개발 모드

# 개발 모드(자동 리로드)
pnpm gateway:watch

# 테스트 실행
pnpm test

# 코드 검사
pnpm lint

설정 파일 상세

설정 우선순위

CLI 인자 > 환경 변수 > 설정 파일 > 기본값

디렉터리 구조

~/.openclaw/
├── openclaw.json           # 메인 설정 파일
├── openclaw.json.backup    # 자동 백업
├── credentials/            # 민감 인증 정보(자동 암호화)
│   ├── telegram.json
│   ├── whatsapp.json
│   └── discord.json
├── workspace/              # Agent 작업 공간
│   ├── AGENTS.md          # 전역 동작 가이드
│   ├── SOUL.md            # Agent 성격
│   ├── TOOLS.md           # 사용자 정의 도구 설명
│   ├── USER.md            # 사용자 정보
│   └── skills/            # 스킬 디렉터리
│       ├── gmail/
│       │   └── SKILL.md
│       └── calendar/
│           └── SKILL.md
├── sessions/              # 세션 데이터
├── logs/                  # 로그 파일
│   ├── gateway.log
│   └── agent.log
└── cache/                 # 캐시 데이터

최소 설정

~/.openclaw/openclaw.json:

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

전체 설정 예시

{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "thinkingLevel": "high",
    "verboseLevel": "normal"
  },
  "gateway": {
    "port": 18789,
    "bind": "loopback",
    "host": "127.0.0.1"
  },
  "channels": {
    "telegram": {
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "pairing",
      "allowFrom": []
    },
    "whatsapp": {
      "allowFrom": ["+8613800138000"],
      "groups": {
        "*": { "requireMention": true }
      }
    },
    "discord": {
      "token": "YOUR_DISCORD_TOKEN",
      "guilds": {}
    }
  },
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "off"
      }
    }
  },
  "models": {
    "fallback": [
      {
        "model": "anthropic/claude-sonnet-4",
        "condition": "rate_limit"
      }
    ]
  },
  "webhooks": [],
  "cron": []
}

설정 항목 설명

환경 변수

OpenClaw는 환경 변수로 설정을 덮어쓸 수 있습니다:

# API Keys
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# 채널 설정
export TELEGRAM_BOT_TOKEN="123456:ABC..."
export DISCORD_BOT_TOKEN="..."

# Gateway 설정
export OPENCLAW_PORT=18789
export OPENCLAW_BIND="loopback"

시작 및 검증

Gateway 시작

# 포그라운드 실행(디버그 모드)
openclaw gateway --verbose

# 백그라운드 실행(데몬)
openclaw gateway --daemon

# 포트 지정
openclaw gateway --port 18790

실행 상태 검증

# 상태 확인
openclaw doctor

# 출력 예:
# ✓ Node.js version: v22.12.0
# ✓ OpenClaw version: 2026.2.26
# ✓ Gateway running on port 18789
# ✓ API key configured
# ✓ Workspace directory exists

Web 콘솔 접속

Gateway 시작 후 브라우저에서 접속:

http://127.0.0.1:18789

Web Control UI가 표시됩니다:

대화 테스트

# 명령줄 테스트
openclaw agent --message "안녕, 자기소개 해줘"

# 출력 예:
# 안녕하세요! 저는 OpenClaw 어시스턴트입니다. 도와드릴 수 있어요...

일반 문제 해결

문제 1: 포트 사용 중

증상:

Error: EADDRINUSE: address already in use 127.0.0.1:18789

해결 방법:

# 포트 사용 프로세스 찾기
lsof -i :18789
# 또는
netstat -tlnp | grep 18789

# 프로세스 종료
kill -9 <PID>

# 또는 다른 포트 사용
openclaw gateway --port 18790

문제 2: API Key 무효

증상:

Error: Invalid API key

해결 방법:

# 설정 검증
openclaw config get agent.model

# 환경 변수 확인
echo $ANTHROPIC_API_KEY

# 재설정
openclaw onboard

문제 3: Node 버전이 너무 낮음

증상:

Error: OpenClaw requires Node.js >= 22.0.0

해결 방법:

# nvm으로 버전 전환
nvm install 22
nvm use 22
nvm alias default 22

# 확인
node --version

문제 4: 권한 문제

증상:

Error: EACCES: permission denied

해결 방법:

# npm 권한 수정
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) ~/.openclaw

# 또는 nvm으로 Node.js 관리(권장)

문제 5: Docker 네트워크 문제

증상:

Error: Cannot connect to Gateway from container

해결 방법:

# 네트워크 확인
docker network ls
docker network inspect bridge

# host 네트워크 사용
docker run --network host ...

# 또는 포트 올바르게 매핑
docker run -p 127.0.0.1:18789:18789 ...

문제 6: 인증 정보 손실

증상:

Warning: Telegram credentials not found

해결 방법:

# 채널 재로그인
openclaw channels login telegram

# 인증 파일 확인
ls ~/.openclaw/credentials/

# 인증 백업
cp -r ~/.openclaw/credentials/ ~/.openclaw/credentials.backup/

문제 7: 메모리 부족

증상:

Error: JavaScript heap out of memory

해결 방법:

# Node.js 메모리 제한 증가
export NODE_OPTIONS="--max-old-space-size=8192"
openclaw gateway

# 또는 Docker에서
docker run -e NODE_OPTIONS="--max-old-space-size=8192" ...

업데이트 및 유지보수

OpenClaw 업데이트

# npm 업데이트
npm update -g openclaw@latest

# pnpm 업데이트
pnpm update -g openclaw@latest

# Docker 업데이트
docker pull openclaw/openclaw:latest
docker-compose up -d

# 버전 확인
openclaw --version

릴리스 채널 전환

# 안정판(권장)
openclaw update --channel stable

# 베타판
openclaw update --channel beta

# 개발판(최신 기능, 불안정 가능)
openclaw update --channel dev

백업 및 복구

# 설정 백업
tar -czvf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

# 설정 복구
tar -xzvf openclaw-backup-20260226.tar.gz -C ~/

# 핵심 파일만 백업
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
cp -r ~/.openclaw/credentials/ ~/.openclaw/credentials.backup/

다음 단계

환경 구축이 완료되었습니다. 다음을 진행하세요:

1. 첫 채널 설정 → 다음 편: 채널 설정 입문
2. 첫 Skill 설치 → Web UI에서 검색 후 설치
3. Agent 성격 커스터마이징 → ~/.openclaw/workspace/SOUL.md 편집

본 편 요약:

• 5가지 설치 방식과 적용 시나리오 파악
• 설정 파일 구조와 우선순위 이해
• 시작·검증 및 일반 문제 해결 학습
• 업데이트·유지보수 기본 작업 이해

업데이트 기록:

• 2026-02-26: 초판 발행, OpenClaw v2026.2 기준

시리즈 네비게이션:

• ← 이전: OpenClaw 입문 소개
• → 다음: 채널 설정: Telegram부터 시작