Docker

기준일: 2026-07-26
공식 기준: Docker

Docker 문서는 OpenClaw 공식 문서(install/docker)를 한국어로 정리한 가이드입니다. Optional Docker-based setup and onboarding for OpenClaw 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Optional Docker-based setup and onboarding for OpenClaw

한국어 가이드 범위: install/docker 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• 사전 요구사항
• Containerized gateway
• Manual flow
• Upgrading container images
• 환경 변수
• Source-built images with selected plugins
• Deploy: registry.example.com/fakeco/openclaw-clickclack@sha256:
• Observability
• Health checks
• LAN vs loopback
• Host local providers
• Claude CLI backend in Docker
• Bonjour / mDNS
• Storage and persistence
• Shell helpers (optional)
• Running on a VPS?
• Agent sandbox
• Quick enable
• 트러블슈팅
• 관련 문서

상세 내용

본문

Docker is optional. Use it for an isolated, throwaway gateway environment or a host without local installs. If you already develop on your own machine, use the normal install flow instead.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

사전 요구사항

주요 항목:

• Docker Desktop (or Docker Engine) + Docker Compose v2
• At least 2 GB RAM for image build (pnpm install may be OOM-killed on 1 GB hosts with exit 137)
• Enough disk for images and logs
• On a VPS/public host, review Security hardening for network exposure, especially the Docker DOCKER-USER firewall chain

Containerized gateway

This builds the gateway image locally as openclaw:local. To use a pre-built image instead:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• prompts for provider API keys
• generates a gateway token and writes it to .env
• creates the auth-profile secret key directory
• starts the gateway via Docker Compose

./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.tar
    export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
    ./scripts/docker/setup.sh --offline

Manual flow

The Docker context excludes .git. Pass the source identity as build arguments as shown above so the image's About screen reports the checked-out commit and one build timestamp. scripts/docker/setup.sh resolves and passes both values automatically.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

BUILD_GIT_COMMIT="$(git rev-parse HEAD)"
BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
docker build \
  --build-arg "GIT_COMMIT=${BUILD_GIT_COMMIT}" \
  --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \
  -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

Upgrading container images

When you replace the OpenClaw image but keep the same mounted state/config, the new gateway runs startup-safe upgrade migrations and plugin convergence before readiness. Routine image upgrades should not require a separate openclaw doctor --fix pass.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

docker run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fix
podman run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fix

환경 변수

Optional variables accepted by scripts/docker/setup.sh (and, for the gateway container, by docker-compose.yml directly):

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Variable	Purpose
OPENCLAW_IMAGE	Use a remote image instead of building locally
OPENCLAW_IMAGE_APT_PACKAGES	Install extra apt packages during build (space-separated). Legacy alias: OPENCLAW_DOCKER_APT_PACKAGES
OPENCLAW_IMAGE_PIP_PACKAGES	Install extra Python packages during build (space-separated)
OPENCLAW_EXTENSIONS	Compile/package supported selected plugins and install their runtime dependencies (comma- or space-separated ids)
OPENCLAW_DOCKER_BUILD_NODE_OPTIONS	Override the local source-build Node options (default --max-old-space-size=8192)
OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB	Override the local source-build tsdown heap in MB
OPENCLAW_DOCKER_BUILD_SKIP_DTS	Skip declaration output during runtime-only local image builds (default 1)
OPENCLAW_INSTALL_BROWSER	Bake Chromium + Xvfb into the image at build time
OPENCLAW_EXTRA_MOUNTS	Extra host bind mounts (comma-separated source:target[:opts])
OPENCLAW_HOME_VOLUME	Persist /home/node in a named Docker volume
OPENCLAW_SANDBOX	Opt in to sandbox bootstrap (1, true, yes, on)
OPENCLAW_SKIP_ONBOARDING	Skip the interactive onboarding step (1, true, yes, on)
OPENCLAW_DOCKER_SOCKET	Override the Docker socket path
OPENCLAW_DISABLE_BONJOUR	Force Bonjour/mDNS advertising on (0) or off (1); see Bonjour / mDNS
OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS	Disable bundled plugin source bind-mount overlays
OTEL_EXPORTER_OTLP_ENDPOINT	Shared OTLP/HTTP collector endpoint for OpenTelemetry export
OTEL_EXPORTER_OTLP_*_ENDPOINT	Signal-specific OTLP endpoints for traces, metrics, or logs
OTEL_EXPORTER_OTLP_PROTOCOL	OTLP protocol override. Only http/protobuf is supported today
OTEL_SERVICE_NAME	Service name used for OpenTelemetry resources
OTEL_SEMCONV_STABILITY_OPT_IN	Opt in to latest experimental GenAI semantic attributes
OPENCLAW_OTEL_PRELOADED	Skip starting a second OpenTelemetry SDK when one is preloaded

OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096

Source-built images with selected plugins

OPENCLAW_EXTENSIONS selects plugin manifest ids from the source checkout; existing source-directory names are also accepted when they differ. The Docker build resolves the selection to source directories once, installs production dependencies, and, when a selected plugin is published separately with openclaw.build.bundledDist: false, compiles its runtime into the root bundled dist. This Docker-only packaging does not change the plugin's npm or ClawHub artifact contract. Unknown, invalid, or ambiguous ids fail the image build. Known dependency/source-only ids keep their existing source and dependency staging without gaining a compiled root dist entry. A selected plugin with unified build entries must compile successfully; unselected external plugin source and runtime output are pruned.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

SOURCE_SHA="$(git rev-parse HEAD)"
BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
REGISTRY="registry.example.com/fakeco"

build_gateway_image() {
  gateway="$1"
  selected_plugin="$2"
  docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --build-arg "GIT_COMMIT=${SOURCE_SHA}" \
    --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \
    --build-arg "OPENCLAW_EXTENSIONS=${selected_plugin}" \
    --build-arg OPENCLAW_INSTALL_BROWSER= \
    --provenance=mode=max \
    --sbom=true \
    --tag "${REGISTRY}/openclaw-${gateway}:${SOURCE_SHA}" \
    --push \
    .
}

build_gateway_image clickclack clickclack
build_gateway_image slack slack
build_gateway_image teams msteams

Deploy: registry.example.com/fakeco/openclaw-clickclack@sha256:

These images are for standalone OCI-based gateways and generic Docker users. Crabhelm-managed gateways do not consume them: that delivery path builds a separate x86_64 appliance archive containing an OpenClaw npm tarball and pins the Node, archive, and manifest digests. Build that appliance independently from the same landed OpenClaw source.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Observability

OpenTelemetry export is outbound from the Gateway container to your OTLP collector; it needs no published Docker port. To include the bundled exporter in a locally built image:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

./scripts/docker/setup.sh

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

Health checks

Container probe endpoints (no auth required):

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

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

LAN vs loopback

scripts/docker/setup.sh defaults OPENCLAW_GATEWAY_BIND=lan so http://127.0.0.1:18789 on the host works with Docker port publishing.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• lan (default): host browser and host CLI can reach the published gateway port.
• loopback: only processes inside the container network namespace can reach the gateway directly.

Host local providers

Inside the container, 127.0.0.1 is the container itself, not the host. Use host.docker.internal for providers running on the host:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Provider	Host default URL	Docker setup URL
LM Studio	http://127.0.0.1:1234	http://host.docker.internal:1234
Ollama	http://127.0.0.1:11434	http://host.docker.internal:11434

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

Claude CLI backend in Docker

The official image does not pre-install Claude Code. Install and log in inside the container's node user, then persist that container home so image upgrades don't erase the binary or auth state.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

./scripts/docker/setup.sh

set -a
. ./.env
set +a

./scripts/docker/setup.sh

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'

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

Bonjour / mDNS

Docker bridge networking usually doesn't forward Bonjour/mDNS multicast (224.0.0.251:5353) reliably. When OPENCLAW_DISABLE_BONJOUR is unset, the bundled Bonjour plugin auto-disables LAN advertising once it detects it's running in a container, so it won't crash-loop retrying multicast the bridge drops. Set OPENCLAW_DISABLE_BONJOUR=1 to force it off regardless of detection, or 0 to force it on (only on host networking, macvlan, or another network where mDNS multicast is known to work).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Storage and persistence

Docker Compose bind-mounts OPENCLAW_CONFIG_DIR to /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR to /home/node/.openclaw/workspace, and OPENCLAW_AUTH_PROFILE_SECRET_DIR to /home/node/.config/openclaw, so those paths survive container replacement. When a variable is unset, docker-compose.yml falls back under ${HOME}, or /tmp if HOME itself is missing, so docker compose up never emits an empty-source volume spec on bare environments.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• openclaw.json for behavior config
• agents/<agentId>/agent/auth-profiles.json for stored provider OAuth/API-key auth
• .env for env-backed runtime secrets such as OPENCLAW_GATEWAY_TOKEN

Shell helpers (optional)

For shorter day-to-day commands, install ClawDock:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

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

Running on a VPS?

See Hetzner (Docker VPS) and Docker VM Runtime for shared VM deployment steps including binary baking, persistence, and updates.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Agent sandbox

When agents.defaults.sandbox is enabled with the Docker backend, the gateway runs agent tool execution (shell, file read/write, etc.) inside isolated Docker containers while the gateway itself stays on the host — a hard wall around untrusted or multi-tenant agent sessions without containerizing the whole gateway.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Sandboxing -- complete sandbox reference
• OpenShell -- interactive shell access to sandbox containers
• Multi-Agent Sandbox and Tools -- per-agent overrides

Quick enable

Build the default sandbox image (from a source checkout):

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

scripts/sandbox-setup.sh

트러블슈팅

Build the sandbox image with scripts/sandbox-setup.sh (source checkout) or the inline docker build command from Sandboxing § Images and setup (npm install), or set agents.defaults.sandbox.docker.image to your custom image. Containers are auto-created per session on demand.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

관련 문서

주요 항목:

• Install Overview — all installation methods
• Podman — Podman alternative to Docker
• ClawDock — Docker Compose community setup
• Updating — keeping OpenClaw up to date
• Configuration — gateway configuration after install

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/install/docker
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 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.tar
    export 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

    # 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>"

관련 링크

• 공식 원문: install/docker
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.