OpenClaw Docker 배포 완전 가이드

Docker 배포를 선택하는 이유

OpenClaw을 장기간 안정적으로 운영해야 하는 사용자에게는 Docker 배포가 npm 직접 설치보다 더 좋은 선택입니다. 몇 가지 확실한 장점이 있습니다: 환경 격리로 의존성 충돌 방지, 원클릭 시작/중지로 편리한 운영, 컨테이너 재시작 시 서비스 자동 복구, 이미지 태그만 변경하면 되는 간편한 버전 업그레이드.

이 글에서는 Docker Compose를 이용한 배포를 처음부터 완성하는 방법을 안내합니다. 개인 서버, 가정용 NAS, 클라우드 호스팅 모두에 적용할 수 있습니다.

사전 준비

서버에 다음 도구가 설치되어 있는지 확인하세요:

Docker Engine 24+
Docker Compose v2+ (최신 버전에는 Docker CLI에 내장되어 있습니다)

설치 확인:

docker --version
docker compose version

Docker가 아직 설치되지 않았다면 Docker 공식 문서를 참고하여 설치하세요.

docker-compose.yml 작성

프로젝트 디렉토리를 만들고 Compose 설정 파일을 작성합니다:

mkdir -p ~/openclaw-docker && cd ~/openclaw-docker

다음 내용으로 docker-compose.yml 파일을 생성합니다:

version: "3.8"

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./config:/root/.config/openclaw
      - ./data:/root/.openclaw
    environment:
      - NODE_ENV=production
      - TZ=Asia/Shanghai
    env_file:
      - .env

이 설정은 다음을 수행합니다:

공식 이미지 openclaw/openclaw:latest 사용
Gateway 포트 18789을 호스트에 매핑
설정 디렉토리와 데이터 디렉토리를 마운트하여 영속화
타임존을 서울로 설정 (필요에 따라 변경 가능)
.env 파일에서 민감한 환경 변수 로드

환경 변수 설정

.env 파일을 만들어 API 키 등 민감한 정보를 저장합니다:

# .env
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxxx

실제로 사용하는 공급자의 키만 입력하면 됩니다. .env 파일에는 민감한 정보가 포함되어 있으므로, 버전 관리 시스템에 커밋되지 않도록 주의하세요.

설정 파일 생성

config 디렉토리에 OpenClaw의 핵심 설정 파일을 만듭니다:

mkdir -p config

config/openclaw.json5 파일을 생성합니다:

{
  // AI 모델 공급자 설정
  providers: {
    anthropic: {
      enabled: true,
      defaultModel: "claude-sonnet-4-20250514"
    }
  },

  // Gateway 설정
  gateway: {
    port: 18789,
    host: "0.0.0.0"  // Docker 컨테이너 내에서는 모든 인터페이스를 리스닝해야 합니다
  },

  // 채널 설정 (필요에 따라 활성화)
  channels: {}
}

host를 반드시 0.0.0.0으로 설정해야 합니다. 그렇지 않으면 컨테이너 외부에서 Gateway에 접근할 수 없습니다.

컨테이너 시작

모든 준비가 완료되면 서비스를 시작합니다:

docker compose up -d

컨테이너 실행 상태를 확인합니다:

docker compose ps

openclaw 컨테이너가 running 상태인 것을 확인할 수 있습니다.

로그 확인

실시간 로그를 확인합니다. 문제를 해결할 때 매우 유용합니다:

docker compose logs -f openclaw

최근 100줄의 로그만 확인하려면:

docker compose logs --tail 100 openclaw

시작 과정에서 API 연결 오류가 발생하면 대부분 키 설정이 잘못된 경우입니다. .env 파일의 키가 올바른지 확인하세요.

일상적인 운영 작업

서비스 중지:

docker compose down

서비스 재시작:

docker compose restart

최신 버전으로 업그레이드:

docker compose pull
docker compose up -d

이렇게 하면 최신 이미지를 받아와서 컨테이너를 재생성합니다. 설정과 데이터는 볼륨으로 마운트되어 있으므로 유실되지 않습니다.

컨테이너에 접속하여 디버깅:

docker exec -it openclaw sh

컨테이너 내부에서 openclaw doctor를 실행하여 진단할 수 있습니다.

데이터 백업

설정과 데이터가 호스트의 ./config과 ./data 디렉토리에 마운트되어 있으므로 백업이 매우 간단합니다:

tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz config data .env

정기적으로 백업하는 것을 권장하며, 특히 업그레이드 전에는 반드시 백업하세요.

리버스 프록시 설정 (선택사항)

도메인을 통해 OpenClaw에 접속하려면, 앞단에 Nginx 리버스 프록시를 추가할 수 있습니다. docker-compose.yml에 Nginx 서비스를 추가하거나, 호스트의 Nginx 설정에 다음을 추가합니다:

server {
    listen 443 ssl;
    server_name openclaw.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

WebSocket의 Upgrade 헤더 설정이 중요합니다. OpenClaw의 실시간 통신이 이에 의존합니다.

마무리

Docker 배포를 사용하면 OpenClaw 운영이 매우 편리해집니다. 한번 설정해 놓으면, 이후에는 로그 확인과 정기적인 업그레이드만 신경 쓰면 됩니다. 문제가 발생하면 OpenClaw 공식 문서를 참고하거나, OpenClaw GitHub 저장소에 이슈를 등록하세요. 더 많은 기능 소개는 OpenClaw을 방문해 주세요.