왜 Docker인가?
Docker에서 OpenClaw를 실행하면 베어메탈 설치에 비해 세 가지 주요 이점이 있습니다:
- 1.보안 격리: 에이전트가 호스트 시스템에 대한 접근이 제한된 컨테이너 내에서 실행됩니다. 악성 스킬이나 프롬프트 인젝션이 파일에 접근하려고 시도하면, 컨테이너 경계가 피해 범위를 제한합니다.
- 2.재현 가능성: 같은 Docker 이미지가 어떤 기기에서든 동일하게 실행됩니다 — 노트북, VPS, 또는 Raspberry Pi.
- 3.쉬운 정리: 처음부터 다시 시작하고 싶으신가요? 컨테이너를 제거하고 새 것을 생성하세요. 남은 파일도, 깨진 Node.js 설치도 없습니다.
사전 요구사항
- •Docker Desktop (macOS/Windows) 또는 Docker Engine (Linux)
- •Docker Compose v2 (Docker Desktop에 포함)
- •컨테이너에 최소 2 GB RAM 사용 가능
- •AI API 키 (Anthropic, OpenAI, 또는 기타 지원되는 제공업체)
빠른 시작
옵션 A: 공식 Docker Compose (추천)
OpenClaw 저장소를 클론하고 내장 Docker 설정을 사용하세요:
git clone https://github.com/openclaw/openclaw.git
cd openclaw
필요한 디렉토리와 구성을 생성하는 설정 스크립트를 실행하세요:
bash docker-setup.sh
- •
~/.openclaw/— 구성, SOUL.md, API 키 - •
~/openclaw/workspace/— 에이전트가 접근할 수 있는 파일
컨테이너 내에서 온보딩 마법사를 실행하세요:
docker compose run --rm openclaw-cli onboard
프롬프트에 따라 API 키를 설정하고 채팅 플랫폼을 연결하세요. 그런 다음 게이트웨이를 시작하세요:
docker compose up -d openclaw-gateway
에이전트가 이제 백그라운드에서 실행되고 있습니다.
옵션 B: 사전 빌드된 이미지
저장소를 클론하고 싶지 않다면, 공식 사전 빌드 이미지를 사용하세요:
docker run -d \
--name openclaw \
--restart unless-stopped \
-v ~/.openclaw:/root/.openclaw \
-v ~/openclaw/workspace:/root/workspace \
-p 3000:3000 \
ghcr.io/openclaw/openclaw:latest
Docker Compose 레퍼런스
프로덕션 사용을 위한 주석이 달린 docker-compose.yml입니다:
version: "3.8"
services:
openclaw-gateway:
image: ghcr.io/openclaw/openclaw:latest
container_name: openclaw
restart: unless-stopped
ports:
- "3000:3000" # Web UI
volumes:
- ~/.openclaw:/root/.openclaw # Config and data
- ~/openclaw/workspace:/root/workspace # Agent workspace
environment:
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
- OPENAI_API_KEY=${OPENAI_API_KEY}
- TZ=Asia/Shanghai # Set your timezone
mem_limit: 2g # Prevent runaway memory usage
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
같은 디렉토리에 API 키가 포함된 .env 파일을 생성하세요:
ANTHROPIC_API_KEY=sk-ant-xxxxx
OPENAI_API_KEY=sk-xxxxx
환경 변수
| 변수 | 필수 | 설명 |
|---|---|---|
ANTHROPIC_API_KEY | 예* | Claude API 키 |
OPENAI_API_KEY | 아니오 | GPT API 키 (OpenAI 사용 시) |
OPENCLAW_PORT | 아니오 | 웹 UI 포트 (기본값: 3000) |
OPENCLAW_HOME | 아니오 | 컨테이너 내 데이터 디렉토리 |
TZ | 아니오 | 예약된 작업의 타임존 |
*최소 하나의 AI 제공업체 키가 필요합니다.
컨테이너 관리
# View logs
docker logs -f openclaw
# Stop the agent
docker compose stop
# Start the agent
docker compose up -d
# Restart after config changes
docker compose restart
# Update to latest version
docker compose pull
docker compose up -d
# Enter the container shell
docker exec -it openclaw bash
# Run CLI commands inside container
docker exec openclaw openclaw skill list
docker exec openclaw openclaw status
보안 강화
파일 시스템 접근 제한
에이전트가 실제로 필요한 디렉토리만 마운트하세요. 전체 홈 디렉토리를 마운트하는 것을 피하세요:
volumes:
- ~/.openclaw:/root/.openclaw:rw # Config (read-write)
- ~/documents:/root/docs:ro # Documents (read-only)
네트워크 격리
에이전트가 로컬 네트워크 서비스에 접근할 필요가 없다면 네트워크를 제한하세요:
networks:
openclaw-net:
driver: bridge
internal: false # Set to true to block all external access
읽기 전용 루트 파일 시스템
최대 보안을 위해 루트 파일 시스템을 읽기 전용으로 만들고 특정 경로에만 쓰기를 허용하세요:
read_only: true
tmpfs:
- /tmp
- /run
업데이트
OpenClaw는 자주 릴리스됩니다. Docker 배포를 업데이트하려면:
docker compose pull # Pull latest image
docker compose up -d # Recreate container with new image
docker image prune -f # Clean up old images
구성과 데이터는 마운트된 볼륨에 유지되므로 업데이트는 비파괴적입니다.
문제 해결
컨테이너가 즉시 충돌하는 경우: docker logs openclaw로 로그를 확인하세요. 일반적인 원인: 누락된 API 키, 부족한 메모리, 또는 포트 충돌.
WhatsApp QR 코드가 표시되지 않는 경우: 인터랙티브 모드로 온보딩을 실행하세요: docker compose run --rm openclaw-cli onboard. QR 코드는 렌더링을 지원하는 터미널이 필요합니다.
마운트된 볼륨의 권한 오류: 호스트 디렉토리가 존재하고 사용자가 소유하고 있는지 확인하세요: mkdir -p ~/.openclaw ~/openclaw/workspace.
높은 메모리 사용량: docker-compose.yml에서 mem_limit: 2g를 설정하여 컨테이너가 과도한 RAM을 소비하는 것을 방지하세요.
자세한 내용은 공식 Docker 문서와 저장소의 docker-compose.yml을 참조하세요.