Docker

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

Docker가 나에게 적합한가요?

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

사전 요구 사항

• Docker Desktop(또는 Docker Engine) + Docker Compose v2
• 이미지 빌드용 RAM 최소 2GB(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

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

docker load -i openclaw-image.tarexport OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh --offline

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

# WhatsApp (QR)docker compose run --rm openclaw-cli channels login # Telegramdocker compose run --rm openclaw-cli channels add --channel telegram --token "<token>" # Discorddocker 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-daemondocker 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

환경 변수

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

공식 Docker 이미지는 Homebrew를 포함하지 않습니다. 온보딩 중 OpenClaw는 brew가 없는 Linux 컨테이너에서 실행 중일 때 brew 전용 skill 의존성 설치 프로그램을 숨깁니다. 이러한 의존성은 사용자 지정 이미지로 제공하거나 수동으로 설치해야 합니다. Debian 패키지에서 사용할 수 있는 의존성의 경우 이미지 빌드 중 OPENCLAW_IMAGE_APT_PACKAGES를 사용하세요. 레거시 OPENCLAW_DOCKER_APT_PACKAGES 이름도 계속 허용됩니다. Python 의존성에는 OPENCLAW_IMAGE_PIP_PACKAGES를 사용하세요. 이는 이미지 빌드 중 python3 -m pip install --break-system-packages를 실행하므로 패키지 버전을 고정하고 신뢰하는 패키지 인덱스만 사용하세요. 소스 빌드는 기본적으로 OPENCLAW_DOCKER_BUILD_NODE_OPTIONS를 --max-old-space-size=8192로 설정하고, tsdown wrapper가 컨테이너 메모리 제한을 존중할 수 있도록 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB는 설정하지 않습니다. 또한 런타임 이미지가 빌드 후 선언 파일을 제거하므로 기본값으로 OPENCLAW_DOCKER_BUILD_SKIP_DTS=1을 사용합니다. Docker가 ResourceExhausted, cannot allocate memory를 보고하거나 tsdown 중단이 발생하면 Docker builder 메모리 제한을 늘리거나, 예를 들어 OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096처럼 더 작은 명시적 힙으로 다시 시도하세요.

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

Observability

OpenTelemetry 내보내기는 Gateway 컨테이너에서 사용자의 OTLP collector로 outbound로 수행됩니다. 게시된 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 소스를 포함할 수 있습니다. 내보내기를 활성화하려면 구성에서 diagnostics-otel Plugin을 허용하고 활성화한 다음, diagnostics.otel.enabled=true를 설정하거나 OpenTelemetry 내보내기의 구성 예시를 사용하세요. collector 인증 헤더는 Docker 환경 변수가 아니라 diagnostics.otel.headers를 통해 구성됩니다.

Prometheus metric은 이미 게시된 Gateway 포트를 사용합니다. clawhub:@openclaw/diagnostics-prometheus를 설치하고, diagnostics-prometheus Plugin을 활성화한 다음 scrape하세요.

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

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

상태 확인

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

curl -fsS http://127.0.0.1:18789/healthz   # livenesscurl -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 대 루프백

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

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

호스트 로컬 제공자

OpenClaw가 Docker에서 실행될 때 컨테이너 내부의 127.0.0.1은 호스트 머신이 아니라 컨테이너 자체입니다. 호스트에서 실행되는 AI 제공자에는 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.0OLLAMA_HOST=0.0.0.0:11434 ollama serve

자체 Compose 파일이나 docker run 명령을 사용하는 경우, 예를 들어 --add-host=host.docker.internal:host-gateway처럼 동일한 호스트 매핑을 직접 추가하세요.

Docker의 Claude CLI 백엔드

공식 OpenClaw Docker 이미지는 Claude Code를 미리 설치하지 않습니다. OpenClaw를 실행하는 컨테이너 사용자 내부에 Claude Code를 설치하고 로그인한 다음, 이미지 업그레이드가 바이너리나 Claude 인증 상태를 지우지 않도록 해당 컨테이너 홈을 영구화하세요.

새 Docker 설치의 경우 설정을 실행하기 전에 영구 /home/node 볼륨을 활성화하세요.

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

기존 Docker 설치의 경우 먼저 스택을 중지하고 현재 Docker .env 값을 다시 로드한 뒤 설정을 다시 실행하세요. 설정 스크립트는 .env를 자체적으로 읽지 않으며, 현재 셸과 기본값을 기준으로 .env를 다시 작성합니다. 생성된 .env의 경우 다음을 실행하세요.

set -a. ./.envset +aexport OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"./scripts/docker/setup.sh

.env에 셸이 source할 수 없는 값이 포함되어 있다면, 먼저 OPENCLAW_IMAGE, 포트, 바인드 모드, 사용자 지정 경로, OPENCLAW_EXTRA_MOUNTS, 샌드박스, 온보딩 건너뛰기 설정처럼 의존하는 기존 값을 수동으로 다시 export하세요. 생성된 오버레이는 openclaw-gateway와 openclaw-cli 모두에 홈 볼륨을 마운트합니다.

두 서비스가 영구화된 홈을 마운트하도록 생성된 Compose 오버레이와 함께 나머지 명령을 실행하세요. 설정에서 docker-compose.override.yml도 사용하는 경우 docker-compose.extra.yml보다 먼저 포함하세요.

해당 영구화된 홈에 Claude Code를 설치하세요.

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint sh openclaw-cli -lc \  'curl -fsSL https://claude.ai/install.sh | bash'

네이티브 설치 프로그램은 claude 바이너리를 /home/node/.local/bin/claude 아래에 씁니다. OpenClaw에 해당 컨테이너 경로를 사용하도록 지정하세요.

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli config set \  agents.defaults.cliBackends.claude-cli.command \  /home/node/.local/bin/claude

동일한 영구화된 컨테이너 홈 내부에서 로그인하고 확인하세요.

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth logindocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth status --textdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models auth login \  --provider anthropic --method cli --set-defaultdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models list --provider anthropic

그 후 번들 claude-cli 백엔드를 사용할 수 있습니다.

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli agent \  --agent main \  --model claude-cli/claude-sonnet-4-6 \  --message "Say hello from Docker Claude CLI"

OPENCLAW_HOME_VOLUME은 네이티브 Claude Code 설치를 /home/node/.local/bin 및 /home/node/.local/share/claude 아래에, Claude Code 설정과 인증 상태를 /home/node/.claude 및 /home/node/.claude.json 아래에 영구화합니다. /home/node/.openclaw만 영구화하는 것으로는 Claude CLI 재사용에 충분하지 않습니다. 홈 볼륨 대신 OPENCLAW_EXTRA_MOUNTS를 사용하는 경우, 해당 Claude 경로를 모두 두 Docker 서비스에 마운트하세요.

Bonjour / mDNS

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

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

주의 사항과 문제 해결은 Bonjour 검색을 참조하세요.

스토리지와 영속성

Docker Compose는 OPENCLAW_CONFIG_DIR을 /home/node/.openclaw에, OPENCLAW_WORKSPACE_DIR을 /home/node/.openclaw/workspace에, OPENCLAW_AUTH_PROFILE_SECRET_DIR을 /home/node/.config/openclaw에 바인드 마운트하므로 해당 경로는 컨테이너 교체 후에도 유지됩니다. 변수가 설정되지 않은 경우 번들 docker-compose.yml은 ${HOME} 아래로 폴백하고, HOME 자체도 없으면 /tmp로 폴백합니다. 이렇게 하면 기본 환경에서 docker compose up이 빈 source 볼륨 사양을 내보내지 않습니다.

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

• 동작 설정용 openclaw.json
• 저장된 제공자 OAuth/API 키 인증용 agents/<agentId>/agent/auth-profiles.json
• OPENCLAW_GATEWAY_TOKEN 같은 env 기반 런타임 시크릿용 .env

인증 프로필 시크릿 키 디렉터리는 OAuth 기반 인증 프로필 토큰 자료에 사용되는 로컬 암호화 키를 저장합니다. Docker 호스트 상태와 함께 보관하되, OPENCLAW_CONFIG_DIR과는 분리하세요.

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

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

디스크 증가 핫스팟: /tmp/openclaw/ 아래의 media/, 세션 JSONL 파일, 공유 SQLite 상태 데이터베이스, 설치된 Plugin 패키지 루트, 순환 파일 로그를 확인하세요.

셸 헬퍼(선택 사항)

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

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

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

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

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

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

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

printf '%s\n' \  'services:' \  '  openclaw-cli:' \  '    cap_drop: !reset []' \  > docker-compose.cli-no-dropped-caps.local.yml docker compose -f docker-compose.yml -f docker-compose.cli-no-dropped-caps.local.yml run --rm openclaw-cli plugins install <package>

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

FROM node:24-bookwormRUN curl -fsSL https://bun.sh/install | bashENV PATH="/root/.bun/bin:${PATH}"RUN corepack enableWORKDIR /appCOPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./COPY ui/package.json ./ui/package.jsonCOPY scripts ./scriptsRUN pnpm install --frozen-lockfileCOPY . .RUN pnpm buildRUN pnpm ui:installRUN pnpm ui:buildENV NODE_ENV=productionCMD ["node","dist/index.js"]

VPS에서 실행하시나요?

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

에이전트 샌드박스

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

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

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

• 샌드박싱 -- 전체 샌드박스 참조
• OpenShell -- 샌드박스 컨테이너에 대한 대화형 셸 접근
• 다중 에이전트 샌드박스 및 도구 -- 에이전트별 재정의

빠른 활성화

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

기본 샌드박스 이미지를 빌드합니다(소스 체크아웃에서):

scripts/sandbox-setup.sh

소스 체크아웃 없이 npm 설치를 사용하는 경우, 인라인 docker build 명령은 샌드박싱 § 이미지 및 설정을 참조하세요.

문제 해결

docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker 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 구성