내 PC/서버에 직접 설치해 텔레그램·디스코드로 제어하는 셀프호스팅 AI 에이전트 플랫폼입니다.
외부 서버 없이 로컬 환경에서 Claude, GPT 등 LLM을 연결해 나만의 AI 직원을 구성할 수 있습니다.
AI 에이전트에게 명령어 실행(exec)이나 파일 접근 권한을 주었다가, 실수로 내 컴퓨터의 중요한 파일이 삭제되거나 시스템이 망가지면 어떡할까 걱정되신 적 있으신가요? 로컬 서버나 개인 NAS에서 셀프호스팅 AI를 직접 운영하고 싶지만, 보안 사고가 두려워 강력한 자동화 기능을 마음껏 쓰지 못하는 분들께 이번 편이 완벽한 해답이 됩니다.
이번 27편에서는 openclaw docker 활용법을 처음부터 끝까지 다룹니다. Docker 컨테이너로 AI를 완전히 격리된 가상의 방(Sandbox)에 가두어, 호스트 시스템에 어떠한 영향도 미치지 않으면서 강력한 자동화 기능을 안심하고 사용하는 방법을 마스터합니다.
지난 편(이전: OpenClaw 클라우드 배포 — Railway·Render 무료 호스팅 설정)에서는 Railway와 Render PaaS 플랫폼에 OpenClaw를 배포하여 24시간 클라우드 AI 비서를 완성했습니다.
왜 openclaw docker로 운영해야 할까? — 격리·일관성·자동화 3가지 핵심 이점
Docker는 소프트웨어 실행에 필요한 모든 환경을 하나의 '컨테이너(Container)'라는 가상 박스에 담아 구동하는 기술입니다. OpenClaw를 Docker로 운영하면 npm 방식이나 PaaS 배포와는 차원이 다른 세 가지 강점을 얻게 됩니다.
- 완벽한 격리(Isolation): AI가 시스템 명령어(
exec)를 실행하더라도 그 영향은 컨테이너 내부로만 제한됩니다. 호스트 PC나 Mac은 절대 안전합니다. - 환경 일관성(Consistency): Node.js 버전 충돌, 의존성 패키지 오류 같은 복잡한 openclaw 설치 에러를 겪을 필요가 없습니다. 이미지를 내려받으면 즉시 실행됩니다.
- 무중단 백그라운드 운영:
--restart unless-stopped옵션으로 터미널을 닫아도, 심지어 서버를 재부팅해도 AI가 자동으로 다시 켜지는 완전한 자동화 환경을 구성할 수 있습니다.
docker run 명령어로 OpenClaw 즉시 실행하기
Docker가 설치되어 있다면 복잡한 npm 설치 과정 없이 아래 명령어 하나로 최신 버전의 OpenClaw를 즉시 띄울 수 있습니다. -v 옵션으로 내 컴퓨터의 설정 폴더와 컨테이너 내부 폴더를 연결(Volume 마운트)하는 것이 데이터 영구 보존의 핵심입니다.
- 설정 데이터 저장 폴더 생성AI의 기억과 설정이 저장될 로컬 디렉토리를 미리 생성합니다.
# OpenClaw 설정 파일과 데이터가 저장될 로컬 디렉토리 생성 mkdir -p ~/.openclaw- Docker 컨테이너로 OpenClaw 백그라운드 실행아래 명령어를 그대로 복사하여 터미널에 붙여넣으세요.
-d옵션으로 백그라운드 실행,--restart unless-stopped으로 자동 재시작이 활성화됩니다. # Docker 컨테이너로 OpenClaw 게이트웨이 백그라운드(-d) 실행 docker run -d \ --name openclaw-agent \ --restart unless-stopped \ -v ~/.openclaw:/root/.openclaw \ -p 18789:18789 \ openclaw/openclaw:latest gateway run- 실행 상태 및 로그 확인컨테이너가 정상적으로 실행되었는지 로그를 확인합니다. 게이트웨이 시작 메시지가 출력되면 성공입니다. 브라우저에서
http://localhost:18789로 접속해 AI 패널을 열어보세요. # 실시간 로그 확인 (Ctrl+C로 로그 화면 종료, 컨테이너는 계속 실행) docker logs -f openclaw-agent- 컨테이너 중지 및 재시작 명령어설정 변경 후 재시작이 필요할 때 사용하는 명령어입니다.
# 컨테이너 중지 docker stop openclaw-agent # 컨테이너 재시작 docker restart openclaw-agent # 컨테이너 삭제 (데이터는 ~/.openclaw에 유지됨) docker rm openclaw-agent
-v ~/.openclaw:/root/.openclaw 볼륨 마운트 옵션 덕분에 AI의 기억과 설정 파일은 컨테이너 내부가 아닌 여러분의 실제 하드디스크에 저장됩니다. 컨테이너를 삭제하고 다시 만들어도 과거 대화 기록과 설정이 그대로 유지됩니다.Docker Compose로 볼륨·환경 변수까지 한 번에 관리하기
매번 긴 docker run 명령어를 입력하는 것이 번거롭다면, Docker Compose를 활용하세요. docker-compose.yml 파일 하나에 모든 설정을 담아두고 docker compose up -d 한 줄로 실행·관리할 수 있습니다. 환경 변수(API 키)도 .env 파일로 깔끔하게 분리됩니다.
docker-compose.yml 작성 예시
version: "3.9"
services:
openclaw:
image: openclaw/openclaw:latest
container_name: openclaw-agent
restart: unless-stopped
ports:
- "18789:18789"
volumes:
- ~/.openclaw:/root/.openclaw
environment:
- OPENCLAW_AUTH_TOKEN=${OPENCLAW_AUTH_TOKEN}
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
- TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
command: gateway run같은 폴더에 .env 파일을 만들어 실제 키 값을 입력하고, .gitignore에 .env를 추가해 두면 코드 저장소에 절대 키가 노출되지 않습니다.
# Docker Compose로 백그라운드 실행
docker compose up -d
# 로그 확인
docker compose logs -f
Docker Sandbox(샌드박스) 설정 — 서브 에이전트와 크론 작업 격리 실행
OpenClaw 2026년 아키텍처는 Docker 컨테이너 기술을 한 단계 더 깊이 활용하는 샌드박스(Sandbox) 기능을 지원합니다. 이 기능을 활성화하면 백그라운드에서 실행되는 서브 에이전트(Subagents)나 크론(Cron) 작업들을 또 다른 격리된 Docker 컨테이너 안에서 실행하도록 만들 수 있습니다. 메인 AI와 자동화 작업을 이중으로 격리하는 최고 수준의 보안 아키텍처입니다.
openclaw.json에 Sandbox 블록 추가하기
{
"sandbox": {
"mode": "non-main"
}
}- non-main: 메인 DM 세션은 호스트에서 빠르게 실행하고, 서브 에이전트·크론 작업만 격리된 컨테이너에서 실행합니다. 성능과 보안의 균형이 잡힌 권장 설정입니다.
- all: 모든 대화와 작업을 격리 컨테이너에서 실행합니다. 가장 안전하지만 시스템 자원을 더 소비합니다.
/var/run/docker.sock)에 접근할 수 있어야 합니다. docker run 명령어에 -v /var/run/docker.sock:/var/run/docker.sock 마운트 옵션과 -e OPENCLAW_INSTALL_DOCKER_CLI=1 환경 변수를 추가하세요.📎 공식 문서 Docker 섹션 보기 →
docker run으로 즉시 실행, Docker Compose로 설정 관리, Sandbox 모드로 서브 에이전트까지 격리. openclaw docker의 3단계 보안 아키텍처가 완성됩니다.
실전 팁과 주의사항
- 볼륨 마운트는 항상 필수:
-v ~/.openclaw:/root/.openclaw옵션 없이 실행하면 컨테이너 삭제 시 모든 대화 기록과 설정이 영구 소멸합니다. 절대 빠뜨리지 마세요. - 이미지 최신 버전 유지:
docker pull openclaw/openclaw:latest를 주기적으로 실행해 보안 패치가 포함된 최신 이미지로 업데이트하세요. 이후docker restart openclaw-agent로 재시작합니다. - Sandbox + 고위험 스킬 조합:
exec,browser스킬을 사용할 때는 반드시 Sandbox 모드를 함께 활성화하세요. 격리 없이 고위험 스킬을 사용하면 AI의 실수가 호스트 시스템 전체에 영향을 미칩니다. - npm 방식 vs. Docker 방식 선택: 단순 기능 테스트에는 npm 설치가 빠르고, 개인 서버에서 24시간 운영하거나 고위험 스킬을 사용할 계획이라면 반드시 Docker 환경을 선택하세요.
자주 묻는 질문 (FAQ)
- Docker 코딩이나 리눅스를 잘 몰라도 openclaw docker를 쓸 수 있나요?
- 물론입니다! Docker의 장점이 바로 '설정이 완료된 박스'를 그대로 가져다 쓴다는 점입니다. 본문에 작성된
docker run명령어 블록을 그대로 복사해 터미널에 붙여넣기만 하면, 복잡한 Python이나 Node.js 설정 없이 1분 만에 설치와 실행이 완료됩니다. - 컨테이너를 껐다 켜면 과거 대화 내용(메모리)이 날아가지 않나요?
- 이를 방지하기 위해 본문의 명령어에
-v ~/.openclaw:/root/.openclaw볼륨 마운트 옵션을 넣었습니다. AI의 기억과 설정 파일은 컨테이너 내부가 아닌 여러분의 실제 하드디스크에 저장되므로, 컨테이너를 삭제하고 다시 만들어도 데이터가 완벽하게 보존됩니다. - Sandbox 모드의 "non-main"과 "all"의 차이는 무엇인가요?
non-main은 메인 챗봇 응답은 빠른 호스트 환경에서, 서브 에이전트·크론 작업만 격리 컨테이너에서 실행합니다. 성능과 보안의 균형이 잡혀 있어 대부분의 사용 환경에 권장됩니다.all모드는 모든 작업을 격리하므로 가장 안전하지만 시스템 자원을 조금 더 소비합니다.- npm 설치와 Docker 설치 중 무엇을 더 추천하시나요?
- 단순히 기능 테스트만 해보고 싶다면 npm 기반의 스크립트 설치가 빠르고 편합니다. 하지만 민감한 데이터가 있는 개인 서버에서 24시간 운영하거나
exec,browser같은 고위험 스킬을 사용할 계획이라면, 시스템 보호를 위해 반드시 Docker 환경으로 구축하시기를 강력히 추천합니다.
이 글이 도움이 됐다면 댓글로 여러분의 경험을 알려주세요! 🙌
openclaw docker 설정에서 막히는 부분은 댓글에 남겨주세요 — 직접 답변드립니다.
📬 새 편 알림 받기 → AI 활용 가이드 구독
댓글