요즘 핫한 OpenClaw, Docker로 5분 만에 시작하기

Last updated on 
요즘 핫한 OpenClaw, Docker로 5분 만에 시작하기
Photo by BoliviaInteligente / Unsplash
OpenClaw Logo
🦞 최근 개발자 커뮤니티에서 뜨거운 관심을 받고 있는 OpenClaw를 Docker로 쉽고 안전하게 배포하는 방법을 알아봅니다.

OpenClaw란?

OpenClaw는 개인용 AI 어시스턴트 플랫폼으로, WhatsApp, Telegram, Slack, Discord 등 다양한 메시징 플랫폼과 통합되어 작동합니다.

GitHub에서 117k+ stars를 기록하며 빠르게 성장하고 있는 오픈소스 프로젝트입니다.

주요 특징

  • 🌐 멀티 채널 지원: WhatsApp, Telegram, Slack, Discord, iMessage 등
  • 🤖 AI 통합: Claude, GPT 등 최신 LLM 모델 활용
  • 🎯 로컬 우선: 내 서버에서 직접 실행하는 프라이빗한 환경
  • 🛠️ 확장성: 다양한 툴과 자동화 기능 제공

Docker로 설치하는 이유

일반적인 설치 방법도 있지만, Docker를 사용하면 다음과 같은 장점이 있습니다:

✅ Docker 설치가 적합한 경우

  • 격리된 환경이 필요할 때
  • 여러 버전을 쉽게 관리하고 싶을 때
  • 로컬 환경을 깔끔하게 유지하고 싶을 때
  • 서버나 VPS에서 실행할 때

⚠️ Docker가 적합하지 않은 경우

  • 로컬 머신에서 빠른 개발 환경이 필요할 때
  • 리소스가 제한된 환경
💡 참고: Agent 샌드박싱 기능은 Docker를 사용하지만, 전체 Gateway를 Docker로 실행할 필요는 없습니다.

사전 준비사항

시스템 요구사항

1. Docker Desktop 설치

macOS에서 Docker를 사용하려면 먼저 Docker Desktop을 설치해야 합니다.

# Homebrew를 사용한 설치 (권장)
brew install --cask docker

# 또는 공식 웹사이트에서 다운로드
# https://www.docker.com/products/docker-desktop

설치 후 Docker Desktop을 실행하고 상단 메뉴 바에 Docker 아이콘이 표시되는지 확인하세요.

2. Docker Compose 확인

Docker Desktop에는 Docker Compose v2가 기본 포함되어 있습니다.

# Docker Compose 버전 확인
docker compose version
# 출력 예시: Docker Compose version v2.x.x

3. 디스크 공간 확보

  • Docker 이미지와 로그를 위한 최소 5GB 이상의 여유 공간 필요
  • 권장: 10GB 이상

4. 리포지토리 클론

# OpenClaw 리포지토리 클론
git clone https://github.com/openclaw/openclaw.git
cd openclaw

설치 과정

방법 1: 자동 설치 스크립트 (권장)

OpenClaw는 전체 설정을 자동화하는 편리한 스크립트를 제공합니다.

Step 1: 설치 스크립트 실행

# 리포지토리 루트에서 실행
./docker-setup.sh

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

  1. ✅ Gateway 이미지 빌드
  2. ✅ 온보딩 마법사 실행
  3. ✅ 프로바이더 설정 힌트 출력
  4. ✅ Docker Compose를 통한 Gateway 시작
  5. ✅ Gateway 토큰 생성 및 .env 파일에 저장

Step 2: 설정 과정

설치 스크립트가 정상적으로 완료되면, 온보딩 마법사가 자동으로 실행됩니다. 몇가시 설정 항목을 보고 본인에게 맞는 설정으로 진행합니다.

Step 3: 설치 완료 확인

스크립트가 완료되면 다음과 같은 메시지가 표시됩니다:

✅ OpenClaw Gateway is now running!
🌐 Control UI: http://127.0.0.1:18789/
🔑 Token: [your-gateway-token]

Next steps:
1. Open the Control UI in your browser
2. Paste the token in Settings → Token
3. Start chatting with your AI assistant!

방법 2: 수동 설치 (고급 사용자)

더 세밀한 제어가 필요한 경우 수동으로 설치할 수 있습니다.

Step 1: 이미지 빌드

# OpenClaw 이미지 빌드
docker build -t openclaw:local -f Dockerfile .

Step 2: 온보딩 실행

# 온보딩 마법사 실행
docker compose run --rm openclaw-cli onboard

Step 3: Gateway 시작

# Gateway 컨테이너 백그라운드 실행
docker compose up -d openclaw-gateway

Step 4: 상태 확인

# 실행 중인 컨테이너 확인
docker compose ps

# 로그 확인
docker compose logs -f openclaw-gateway

설정 및 활용

1. Control UI 접속

브라우저에서 다음 주소로 접속합니다:

http://127.0.0.1:18789/

토큰 입력

Settings → Token 메뉴에서 설치 시 생성된 토큰을 입력합니다.

💡 토큰을 잊어버렸다면?

2. 채널 설정

Telegram 연동

# Telegram 봇 토큰 추가
docker compose run --rm openclaw-cli channels add \
  --channel telegram \
  --token "YOUR_BOT_TOKEN"
💡 Telegram 봇 토큰 발급 방법:Telegram에서 @BotFather 검색/newbot 명령어 입력봇 이름과 사용자 이름 설정발급된 토큰 복사

Discord 연동

# Discord 봇 토큰 추가
docker compose run --rm openclaw-cli channels add \
  --channel discord \
  --token "YOUR_DISCORD_TOKEN"

3. 추가 마운트 설정 (선택사항)

호스트의 추가 디렉토리를 컨테이너에 마운트하려면:

# 환경 변수 설정
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"

# 설정 반영을 위해 재실행
./docker-setup.sh

마운트 옵션 설명:

  • :ro - 읽기 전용 (Read-Only)
  • :rw - 읽기/쓰기 (Read-Write)

4. 컨테이너 홈 디렉토리 영구 저장 (선택사항)

컨테이너 재생성 시에도 데이터를 유지하려면:

# 볼륨 설정
export OPENCLAW_HOME_VOLUME="openclaw_home"

# 설정 반영
./docker-setup.sh

5. 추가 패키지 설치 (선택사항)

이미지에 시스템 패키지를 포함하려면:

# 필요한 패키지 지정
export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential git curl jq"

# 이미지 재빌드
./docker-setup.sh

고급 설정

샌드박스 이미지 빌드

보안이 중요한 환경에서는 Agent 샌드박스 이미지를 구축할 수 있습니다:

# 기본 샌드박스 이미지
scripts/sandbox-setup.sh

# 개발 도구가 포함된 샌드박스
scripts/sandbox-common-setup.sh

# 브라우저 기능이 포함된 샌드박스
scripts/sandbox-browser-setup.sh

Health Check

# Gateway 상태 확인
docker compose exec openclaw-gateway \
  node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

정상 작동 시 출력:

{
  "status": "healthy",
  "version": "vYYYY.M.D",
  "uptime": "2h 30m"
}

문제 해결

자주 발생하는 문제와 해결 방법

1. 권한 오류 (EACCES)

증상:

Error: EACCES: permission denied, open '/home/node/.openclaw/...'

해결:

# macOS에서 권한 수정
sudo chown -R 1000:1000 ~/.openclaw

컨테이너는 node 사용자(uid 1000)로 실행되므로, 호스트의 마운트된 디렉토리도 동일한 권한이 필요합니다.

2. 이미지를 찾을 수 없음

증상:

Error: image not found: openclaw-sandbox:bookworm-slim

해결:

# 샌드박스 이미지 빌드
scripts/sandbox-setup.sh

3. 포트 충돌

증상:

Error: port 18789 is already in use

해결:

# 사용 중인 프로세스 확인
lsof -i :18789

# 또는 docker-compose.yml에서 포트 변경
# ports:
#   - "19000:18789"  # 다른 포트로 변경

4. 컨테이너가 시작되지 않음

진단:

# 로그 확인
docker compose logs openclaw-gateway

# 상세 로그
docker compose logs -f --tail=100 openclaw-gateway

일반적인 해결책:

# 컨테이너 재시작
docker compose restart openclaw-gateway

# 완전 재빌드
docker compose down
docker compose build --no-cache
docker compose up -d

5. 네트워크 연결 문제

증상: Control UI에 접속할 수 없음

해결:

# Docker 네트워크 확인
docker network ls

# Gateway가 실행 중인지 확인
docker compose ps

# 호스트에서 포트 접근 테스트
curl http://localhost:18789/health

6. 메모리 부족

증상: 컨테이너가 자주 재시작됨

해결:

# docker-compose.yml 수정
# services:
#   openclaw-gateway:
#     deploy:
#       resources:
#         limits:
#           memory: 2G  # 메모리 제한 증가

유용한 명령어 모음

컨테이너 관리

# Gateway 시작
docker compose up -d openclaw-gateway

# Gateway 중지
docker compose stop openclaw-gateway

# Gateway 재시작
docker compose restart openclaw-gateway

# 모든 컨테이너 중지
docker compose down

# 로그 실시간 확인
docker compose logs -f openclaw-gateway

# CLI 명령어 실행
docker compose run --rm openclaw-cli [command]

데이터 관리

# 볼륨 목록 확인
docker volume ls

# 사용하지 않는 볼륨 정리
docker volume prune

# 전체 데이터 백업 (설정 + 워크스페이스)
tar -czf openclaw-backup.tar.gz ~/.openclaw/

디버깅

# 컨테이너 내부 접속
docker compose exec openclaw-gateway bash

# 특정 명령어 실행
docker compose exec openclaw-gateway cat ~/.openclaw/openclaw.json

# 리소스 사용량 확인
docker stats openclaw-gateway

Shell Helper 설치 (편의 기능)

일상적인 Docker 관리를 쉽게 하려면 ClawDock 헬퍼를 설치하세요:

# ClawDock 헬퍼 다운로드
mkdir -p ~/.clawdock && \
curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh \
  -o ~/.clawdock/clawdock-helpers.sh

# zsh 설정에 추가
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc
source ~/.zshrc

사용 가능한 명령어

clawdock-start        # Gateway 시작
clawdock-stop         # Gateway 중지
clawdock-restart      # Gateway 재시작
clawdock-logs         # 로그 확인
clawdock-dashboard    # 대시보드 URL 확인
clawdock-help         # 전체 명령어 목록

보안 고려사항

1. 토큰 관리

# .env 파일 권한 설정
chmod 600 .env

# Git에서 제외 (이미 .gitignore에 포함됨)
echo ".env" >> .gitignore

2. 방화벽 설정

로컬 환경에서만 사용한다면:

# docker-compose.yml
services:
  openclaw-gateway:
    ports:
      - "127.0.0.1:18789:18789"  # 로컬호스트만 허용

3. 업데이트

# 최신 코드 가져오기
git pull origin main

# 이미지 재빌드
docker compose build --no-cache

# 재시작
docker compose up -d

성능 최적화

빌드 캐시 활용

# Docker 빌드 캐시 확인
docker system df

# 불필요한 캐시 정리
docker builder prune

리소스 제한 설정

# docker-compose.yml
services:
  openclaw-gateway:
    deploy:
      resources:
        limits:
          cpus: '2'      # CPU 코어 수 제한
          memory: 4G     # 메모리 제한
        reservations:
          memory: 2G     # 최소 보장 메모리

프로덕션 배포 팁

1. 로그 로테이션

# docker-compose.yml
services:
  openclaw-gateway:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

2. 자동 재시작 설정

# docker-compose.yml
services:
  openclaw-gateway:
    restart: unless-stopped

3. Health Check 설정

# docker-compose.yml
services:
  openclaw-gateway:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

마무리

이 가이드를 통해 macOS 환경에서 OpenClaw를 Docker로 성공적으로 배포하셨기를 바랍니다!

참고 링크