Docker

Docker는 선택 사항입니다. 컨테이너화된 Gateway를 원하거나 Docker 흐름을 검증하려는 경우에만 사용하세요.

# Docker가 나에게 적합한가요?

• 예: 격리된 일회용 Gateway 환경이 필요하거나 로컬 설치 없이 호스트에서 OpenClaw를 실행하려는 경우입니다.
• 아니요: 자신의 머신에서 실행 중이고 가장 빠른 개발 루프만 원하는 경우입니다. 대신 일반 설치 흐름을 사용하세요.
• 샌드박싱 참고: 기본 샌드박스 백엔드는 샌드박싱이 활성화된 경우 Docker를 사용하지만, 샌드박싱은 기본적으로 꺼져 있으며 전체 Gateway를 Docker에서 실행할 필요는 없습니다. SSH 및 OpenShell 샌드박스 백엔드도 사용할 수 있습니다. 샌드박싱을 참조하세요.

# 사전 요구 사항

• Docker Desktop(또는 Docker Engine) + Docker Compose v2
• 이미지 빌드를 위한 최소 2GB RAM(pnpm install은 1GB 호스트에서 종료 코드 137로 OOM 종료될 수 있음)
• 이미지와 로그를 저장할 충분한 디스크 공간
• VPS/공개 호스트에서 실행하는 경우 네트워크 노출을 위한 보안 강화, 특히 Docker DOCKER-USER 방화벽 정책을 검토하세요.

# 컨테이너화된 Gateway

./scripts/docker/setup.sh

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

docker compose run --rm openclaw-cli dashboard --no-open

# WhatsApp (QR)
docker compose run --rm openclaw-cli channels login

# Telegram
docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

# Discord
docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

# 수동 흐름

설정 스크립트를 사용하는 대신 각 단계를 직접 실행하려면:

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js onboard --mode local --no-install-daemon
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'
docker compose up -d openclaw-gateway

# 환경 변수

설정 스크립트는 다음 선택적 환경 변수를 허용합니다.

관리자는 하나의 Plugin 소스 디렉터리를 패키지된 소스 경로 위에 마운트하여 패키지된 이미지에 대해 번들 Plugin 소스를 테스트할 수 있습니다. 예: OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. 마운트된 해당 소스 디렉터리는 동일한 Plugin ID에 대해 일치하는 컴파일된 /app/dist/extensions/synology-chat 번들을 재정의합니다.

# 관측 가능성

OpenTelemetry 내보내기는 Gateway 컨테이너에서 OTLP 컬렉터로 나가는 방향입니다. 게시된 Docker 포트가 필요하지 않습니다. 이미지를 로컬에서 빌드하고 번들 OpenTelemetry exporter를 이미지 내부에서 사용할 수 있게 하려면 해당 런타임 의존성을 포함하세요.

export OPENCLAW_EXTENSIONS="diagnostics-otel"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"
export OTEL_SERVICE_NAME="openclaw-gateway"
./scripts/docker/setup.sh

패키지된 Docker 설치에서는 내보내기를 활성화하기 전에 ClawHub에서 공식 @openclaw/diagnostics-otel Plugin을 설치하세요. 사용자 지정 소스 빌드 이미지는 여전히 OPENCLAW_EXTENSIONS=diagnostics-otel로 로컬 Plugin 소스를 포함할 수 있습니다. 내보내기를 활성화하려면 config에서 diagnostics-otel Plugin을 허용하고 활성화한 다음 diagnostics.otel.enabled=true를 설정하거나 OpenTelemetry 내보내기의 config 예시를 사용하세요. 컬렉터 인증 헤더는 Docker 환경 변수가 아니라 diagnostics.otel.headers를 통해 구성됩니다.

Prometheus metrics는 이미 게시된 Gateway 포트를 사용합니다. clawhub:@openclaw/diagnostics-prometheus를 설치하고 diagnostics-prometheus Plugin을 활성화한 다음 스크레이프하세요.

http://<gateway-host>:18789/api/diagnostics/prometheus

이 경로는 Gateway 인증으로 보호됩니다. 별도의 공개 /metrics 포트나 인증되지 않은 reverse-proxy 경로를 노출하지 마세요. Prometheus metrics를 참조하세요.

# 상태 확인

컨테이너 probe 엔드포인트(인증 불필요):

curl -fsS http://127.0.0.1:18789/healthz   # liveness
curl -fsS http://127.0.0.1:18789/readyz     # readiness

Docker 이미지에는 /healthz를 ping하는 내장 HEALTHCHECK가 포함되어 있습니다. 확인이 계속 실패하면 Docker는 컨테이너를 unhealthy로 표시하고 오케스트레이션 시스템이 이를 다시 시작하거나 교체할 수 있습니다.

인증된 심층 상태 스냅샷:

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

# LAN과 loopback

scripts/docker/setup.sh는 기본적으로 OPENCLAW_GATEWAY_BIND=lan을 설정하므로 Docker 포트 게시를 통해 호스트에서 http://127.0.0.1:18789에 접근할 수 있습니다.

• lan(기본값): 호스트 브라우저와 호스트 CLI가 게시된 Gateway 포트에 도달할 수 있습니다.
• loopback: 컨테이너 네트워크 네임스페이스 내부의 프로세스만 Gateway에 직접 도달할 수 있습니다.

# 호스트 로컬 provider

OpenClaw가 Docker에서 실행될 때 컨테이너 내부의 127.0.0.1은 호스트 머신이 아니라 컨테이너 자체입니다. 호스트에서 실행되는 AI provider에는 host.docker.internal을 사용하세요.

번들 Docker 설정은 이러한 호스트 URL을 LM Studio 및 Ollama 온보딩 기본값으로 사용하며, docker-compose.yml은 Linux Docker Engine에서 host.docker.internal을 Docker의 호스트 Gateway에 매핑합니다. Docker Desktop은 macOS와 Windows에서 이미 동일한 호스트 이름을 제공합니다.

호스트 서비스도 Docker에서 도달할 수 있는 주소에서 수신 대기해야 합니다.

lms server start --port 1234 --bind 0.0.0.0
OLLAMA_HOST=0.0.0.0:11434 ollama serve

자체 Compose 파일이나 docker run 명령을 사용하는 경우 같은 호스트 매핑을 직접 추가하세요. 예: --add-host=host.docker.internal:host-gateway.

# Bonjour / mDNS

Docker 브리지 네트워킹은 일반적으로 Bonjour/mDNS 멀티캐스트 (224.0.0.251:5353)를 안정적으로 전달하지 않습니다. 따라서 번들 Compose 설정은 브리지가 멀티캐스트 트래픽을 떨어뜨릴 때 Gateway가 crash-loop에 빠지거나 광고를 반복적으로 다시 시작하지 않도록 기본값을 OPENCLAW_DISABLE_BONJOUR=1로 설정합니다.

Docker 호스트에는 게시된 Gateway URL, Tailscale 또는 wide-area DNS-SD를 사용하세요. 호스트 네트워킹, macvlan 또는 mDNS 멀티캐스트가 작동하는 것으로 알려진 다른 네트워크에서 실행하는 경우에만 OPENCLAW_DISABLE_BONJOUR=0을 설정하세요.

주의 사항과 문제 해결은 Bonjour discovery를 참조하세요.

# 저장소 및 지속성

Docker Compose는 OPENCLAW_CONFIG_DIR를 /home/node/.openclaw에, OPENCLAW_WORKSPACE_DIR를 /home/node/.openclaw/workspace에 바인드 마운트하므로 해당 경로는 컨테이너 교체 후에도 유지됩니다. 두 변수 중 하나가 설정되지 않은 경우 번들 docker-compose.yml은 ${HOME}/.openclaw(workspace 마운트의 경우 ${HOME}/.openclaw/workspace)로 폴백하고, HOME 자체도 없는 경우 /tmp/.openclaw로 폴백합니다. 이렇게 하면 최소 환경에서 docker compose up이 빈 소스 volume spec을 내보내지 않습니다.

마운트된 해당 config 디렉터리는 OpenClaw가 다음을 보관하는 위치입니다.

• 동작 config용 openclaw.json
• 저장된 provider OAuth/API-key 인증용 agents/<agentId>/agent/auth-profiles.json
• OPENCLAW_GATEWAY_TOKEN 같은 env 기반 런타임 비밀 값용 .env

설치된 다운로드 가능 Plugin은 마운트된 OpenClaw 홈 아래에 패키지 상태를 저장하므로 Plugin 설치 기록과 패키지 루트는 컨테이너 교체 후에도 유지됩니다. Gateway 시작은 번들 Plugin 의존성 트리를 생성하지 않습니다.

VM 배포의 전체 지속성 세부 정보는 Docker VM Runtime - 무엇이 어디에 유지되는가를 참조하세요.

디스크 증가 핫스팟: /tmp/openclaw/ 아래의 media/, 세션 JSONL 파일, cron/runs/*.jsonl, 설치된 Plugin 패키지 루트, 순환 파일 로그를 확인하세요.

# 셸 헬퍼(선택 사항)

일상적인 Docker 관리를 더 쉽게 하려면 ClawDock을 설치하세요.

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

이전 scripts/shell-helpers/clawdock-helpers.sh 원시 경로에서 ClawDock을 설치했다면, 로컬 헬퍼 파일이 새 위치를 따르도록 위 설치 명령을 다시 실행하세요.

그런 다음 clawdock-start, clawdock-stop, clawdock-dashboard 등을 사용하세요. 모든 명령은 clawdock-help를 실행해 확인할 수 있습니다. 전체 헬퍼 가이드는 ClawDock을 참조하세요.

export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh

export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh

docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

FROM node:24-bookworm
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
RUN corepack enable
WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build
ENV NODE_ENV=production
CMD ["node","dist/index.js"]

# VPS에서 실행하나요?

바이너리 포함, 지속성, 업데이트를 포함한 공유 VM 배포 단계는 Hetzner (Docker VPS) 및 Docker VM Runtime을 참조하세요.

# 에이전트 샌드박스

Docker 백엔드와 함께 agents.defaults.sandbox를 활성화하면 Gateway 자체는 호스트에 유지하면서 Gateway가 격리된 Docker 컨테이너 안에서 에이전트 도구 실행(셸, 파일 읽기/쓰기 등)을 실행합니다. 이렇게 하면 전체 Gateway를 컨테이너화하지 않고도 신뢰할 수 없거나 멀티테넌트 에이전트 세션 주위에 강한 경계를 둘 수 있습니다.

샌드박스 범위는 에이전트별(기본값), 세션별 또는 공유로 설정할 수 있습니다. 각 범위는 /workspace에 마운트된 자체 워크스페이스를 가집니다. 또한 도구 허용/거부 정책, 네트워크 격리, 리소스 제한, 브라우저 컨테이너를 구성할 수 있습니다.

전체 구성, 이미지, 보안 참고 사항, 멀티 에이전트 프로필은 다음을 참조하세요.

• 샌드박싱 -- 전체 샌드박스 참조
• OpenShell -- 샌드박스 컨테이너에 대한 대화형 셸 접근
• 멀티 에이전트 샌드박스 및 도구 -- 에이전트별 오버라이드

# 빠른 활성화

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
      },
    },
  },
}

기본 샌드박스 이미지를 빌드하세요(소스 checkout에서).

scripts/sandbox-setup.sh

소스 checkout이 없는 npm 설치의 경우, 인라인 docker build 명령은 샌드박싱 § 이미지 및 설정을 참조하세요.

# 문제 해결

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

# 관련 문서

• 설치 개요 — 모든 설치 방법
• Podman — Docker의 Podman 대안
• ClawDock — Docker Compose 커뮤니티 설정
• 업데이트 — OpenClaw를 최신 상태로 유지하기
• 구성 — 설치 후 Gateway 구성