메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

1

이미지 빌드

repo 루트에서 설정 스크립트를 실행합니다.
./scripts/docker/setup.sh
이렇게 하면 Gateway 이미지가 로컬에 빌드됩니다. 대신 미리 빌드된 이미지를 사용하려면:
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh
미리 빌드된 이미지는 GitHub Container Registry에 게시됩니다. 일반 태그: main, latest, <version>(예: 2026.2.26).
2

온보딩 완료

설정 스크립트는 온보딩을 자동으로 실행합니다. 이 스크립트는 다음을 수행합니다.
  • provider API 키 입력 요청
  • Gateway 토큰 생성 및 .env에 기록
  • auth-profile 비밀 키 디렉터리 생성
  • Docker Compose를 통해 Gateway 시작
설정 중에는 시작 전 온보딩과 구성 쓰기가 openclaw-gateway를 통해 직접 실행됩니다. openclaw-cli는 Gateway 컨테이너가 이미 존재한 뒤 실행하는 명령에 사용됩니다.
3

Control UI 열기

브라우저에서 http://127.0.0.1:18789/를 열고 구성된 공유 비밀을 Settings에 붙여넣습니다. 설정 스크립트는 기본적으로 토큰을 .env에 씁니다. 컨테이너 구성을 비밀번호 인증으로 전환한 경우 대신 해당 비밀번호를 사용하세요.URL이 다시 필요하신가요?
docker compose run --rm openclaw-cli dashboard --no-open
4

채널 구성(선택 사항)

CLI 컨테이너를 사용해 메시징 채널을 추가합니다.
# 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>"
문서: WhatsApp, Telegram, Discord

수동 흐름

설정 스크립트를 사용하는 대신 각 단계를 직접 실행하려면:
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
repo 루트에서 docker compose를 실행하세요. OPENCLAW_EXTRA_MOUNTS 또는 OPENCLAW_HOME_VOLUME을 활성화한 경우 설정 스크립트가 docker-compose.extra.yml을 씁니다. -f docker-compose.yml -f docker-compose.extra.yml로 포함하세요.
openclaw-cliopenclaw-gateway의 네트워크 네임스페이스를 공유하므로 시작 후 도구입니다. docker compose up -d openclaw-gateway 전에 --no-deps --entrypoint node와 함께 openclaw-gateway를 통해 온보딩과 설정 시점 구성 쓰기를 실행하세요.

환경 변수

설정 스크립트는 다음 선택적 환경 변수를 허용합니다.
변수목적
OPENCLAW_IMAGE로컬 빌드 대신 원격 이미지 사용
OPENCLAW_DOCKER_APT_PACKAGES빌드 중 추가 apt 패키지 설치(공백으로 구분)
OPENCLAW_EXTENSIONS빌드 시 선택한 번들 Plugin 헬퍼 포함
OPENCLAW_EXTRA_MOUNTS추가 호스트 바인드 마운트(쉼표로 구분된 source:target[:opts])
OPENCLAW_HOME_VOLUME/home/node를 명명된 Docker 볼륨에 유지
OPENCLAW_SANDBOX샌드박스 부트스트랩 사용 선택(1, true, yes, on)
OPENCLAW_SKIP_ONBOARDING대화형 온보딩 단계 건너뛰기(1, true, yes, on)
OPENCLAW_DOCKER_SOCKETDocker 소켓 경로 재정의
OPENCLAW_DISABLE_BONJOURBonjour/mDNS 광고 비활성화(Docker에서는 기본값 1)
OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS번들 Plugin 소스 바인드 마운트 오버레이 비활성화
OTEL_EXPORTER_OTLP_ENDPOINTOpenTelemetry 내보내기를 위한 공유 OTLP/HTTP 수집기 엔드포인트
OTEL_EXPORTER_OTLP_*_ENDPOINTtraces, metrics 또는 logs를 위한 신호별 OTLP 엔드포인트
OTEL_EXPORTER_OTLP_PROTOCOLOTLP 프로토콜 재정의. 현재는 http/protobuf만 지원됨
OTEL_SERVICE_NAMEOpenTelemetry 리소스에 사용되는 서비스 이름
OTEL_SEMCONV_STABILITY_OPT_IN최신 실험적 GenAI 의미론 속성 사용 선택
OPENCLAW_OTEL_PRELOADED하나가 미리 로드된 경우 두 번째 OpenTelemetry SDK 시작 건너뛰기
maintainer는 예를 들어 OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro처럼 하나의 Plugin 소스 디렉터리를 패키징된 소스 경로 위에 마운트하여 패키징된 이미지에 대해 번들 Plugin 소스를 테스트할 수 있습니다. 해당 마운트된 소스 디렉터리는 같은 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 설치에서 공식 @openclaw/diagnostics-otel Plugin을 ClawHub에서 설치하세요. 커스텀 소스 빌드 이미지는 여전히 OPENCLAW_EXTENSIONS=diagnostics-otel로 로컬 Plugin 소스를 포함할 수 있습니다. 내보내기를 활성화하려면 구성에서 diagnostics-otel Plugin을 허용하고 활성화한 다음 diagnostics.otel.enabled=true를 설정하거나 OpenTelemetry 내보내기의 구성 예시를 사용하세요. 수집기 인증 헤더는 Docker 환경 변수가 아니라 diagnostics.otel.headers를 통해 구성됩니다. Prometheus metrics는 이미 게시된 Gateway 포트를 사용합니다. clawhub:@openclaw/diagnostics-prometheus를 설치하고 diagnostics-prometheus Plugin을 활성화한 다음 scrape하세요.
http://<gateway-host>:18789/api/diagnostics/prometheus
이 경로는 Gateway 인증으로 보호됩니다. 별도의 공개 /metrics 포트나 인증되지 않은 reverse-proxy 경로를 노출하지 마세요. Prometheus metrics를 참조하세요.

상태 확인

컨테이너 프로브 엔드포인트(인증 필요 없음):
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는 Docker 포트 게시에서 http://127.0.0.1:18789에 대한 호스트 접근이 작동하도록 기본값을 OPENCLAW_GATEWAY_BIND=lan으로 설정합니다.
  • lan(기본값): 호스트 브라우저와 호스트 CLI가 게시된 Gateway 포트에 접근할 수 있습니다.
  • loopback: 컨테이너 네트워크 네임스페이스 내부의 프로세스만 Gateway에 직접 접근할 수 있습니다.
0.0.0.0 또는 127.0.0.1 같은 호스트 별칭이 아니라 gateway.bind의 바인드 모드 값(lan / loopback / custom / tailnet / auto)을 사용하세요.

호스트 로컬 provider

OpenClaw가 Docker에서 실행될 때 컨테이너 내부의 127.0.0.1은 호스트 머신이 아니라 컨테이너 자체입니다. 호스트에서 실행되는 AI provider에는 host.docker.internal을 사용하세요.
Provider호스트 기본 URLDocker 설정 URL
LM Studiohttp://127.0.0.1:1234http://host.docker.internal:1234
Ollamahttp://127.0.0.1:11434http://host.docker.internal:11434
번들 Docker 설정은 이러한 호스트 URL을 LM Studio 및 Ollama 온보딩 기본값으로 사용하며, docker-compose.yml은 Linux Docker Engine용 Docker 호스트 Gateway에 host.docker.internal을 매핑합니다. 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 설정은 기본적으로 OPENCLAW_DISABLE_BONJOUR=1로 설정되어, 브리지가 멀티캐스트 트래픽을 드롭할 때 Gateway가 crash-loop에 빠지거나 광고를 반복적으로 다시 시작하지 않도록 합니다. 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} 아래로 fallback하며, HOME 자체도 없으면 /tmp로 fallback합니다. 이렇게 하면 기본 환경에서 docker compose up이 빈 소스 볼륨 명세를 내보내지 않습니다. 해당 마운트된 구성 디렉터리는 OpenClaw가 다음을 보관하는 위치입니다.
  • 동작 구성을 위한 openclaw.json
  • 저장된 provider OAuth/API 키 인증을 위한 agents/<agentId>/agent/auth-profiles.json
  • OPENCLAW_GATEWAY_TOKEN 같은 env 기반 런타임 비밀을 위한 .env
auth-profile 비밀 키 디렉터리는 OAuth 기반 auth profile 토큰 자료에 사용되는 로컬 암호화 키를 저장합니다. 이를 Docker 호스트 상태와 함께 보관하되, OPENCLAW_CONFIG_DIR과는 분리하세요. 설치된 다운로드 가능 Plugin은 패키지 상태를 마운트된 OpenClaw 홈 아래에 저장하므로, Plugin 설치 기록과 패키지 루트는 컨테이너를 교체해도 유지됩니다. Gateway 시작 시 번들 Plugin 의존성 트리는 생성되지 않습니다. VM 배포의 전체 지속성 세부 정보는 Docker VM 런타임 - 무엇이 어디에 유지되는가를 참조하세요. 디스크 증가 주요 지점: media/, 세션 JSONL 파일, cron/runs/*.jsonl, 설치된 Plugin 패키지 루트, 그리고 /tmp/openclaw/ 아래의 순환 파일 로그를 주시하세요.

셸 헬퍼(선택 사항)

일상적인 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
사용자 지정 소켓 경로(예: rootless Docker):
export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh
스크립트는 샌드박스 사전 요구 사항이 통과한 뒤에만 docker.sock을 마운트합니다. 샌드박스 설정을 완료할 수 없으면 스크립트는 agents.defaults.sandbox.modeoff로 재설정합니다. OpenClaw 샌드박스가 활성 상태인 동안에도 Codex 코드 모드 턴은 Codex workspace-write로 제한됩니다. 호스트 Docker 소켓을 에이전트 샌드박스 컨테이너에 마운트하지 마세요.
-T로 Compose 의사 TTY 할당을 비활성화하세요.
docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json
openclaw-clinetwork_mode: "service:openclaw-gateway"를 사용하므로 CLI 명령이 127.0.0.1을 통해 Gateway에 도달할 수 있습니다. 이를 공유 신뢰 경계로 취급하세요. compose 설정은 openclaw-gatewayopenclaw-cli 모두에서 NET_RAW/NET_ADMIN을 제거하고 no-new-privileges를 활성화합니다.
일부 Docker Desktop 설정에서는 NET_RAW가 제거된 뒤 공유 네트워크 openclaw-cli 사이드카에서 DNS 조회가 실패하며, 이는 openclaw plugins install 같은 npm 기반 명령 중 EAI_AGAIN으로 나타납니다. 일반적인 Gateway 운영에는 기본 강화 compose 파일을 유지하세요. 아래 로컬 오버라이드는 Docker의 기본 capabilities를 복원하여 CLI 컨테이너의 보안 태세를 완화하므로, 기본 Compose 호출로 사용하지 말고 패키지 레지스트리 접근이 필요한 일회성 CLI 명령에만 사용하세요.
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>
이미 장기 실행 openclaw-cli 컨테이너를 만들었다면 동일한 오버라이드로 다시 생성하세요. docker compose execdocker exec는 이미 생성된 컨테이너의 Linux capabilities를 변경할 수 없습니다.
이미지는 node(uid 1000)로 실행됩니다. /home/node/.openclaw에서 권한 오류가 보이면 호스트 바인드 마운트의 소유자가 uid 1000인지 확인하세요.
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
같은 불일치는 blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) 뒤에 plugin present but blocked가 이어지는 Plugin 경고로 나타날 수도 있습니다. 이는 프로세스 uid와 마운트된 Plugin 디렉터리 소유자가 일치하지 않는다는 뜻입니다. 컨테이너는 기본 uid 1000으로 실행하고 바인드 마운트 소유권을 수정하는 것을 권장합니다. OpenClaw를 장기적으로 root로 실행하려는 경우에만 /path/to/openclaw-config/npmroot:root로 chown하세요.
의존성 레이어가 캐시되도록 Dockerfile 순서를 정하세요. 이렇게 하면 lockfile이 변경되지 않는 한 pnpm install을 다시 실행하지 않아도 됩니다.
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"]
기본 이미지는 보안을 우선하며 non-root node로 실행됩니다. 더 많은 기능을 갖춘 컨테이너를 원한다면:
  1. /home/node 유지: export OPENCLAW_HOME_VOLUME="openclaw_home"
  2. 시스템 의존성 포함: export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
  3. Playwright Chromium 포함: export OPENCLAW_INSTALL_BROWSER=1
  4. 또는 Playwright 브라우저를 지속 볼륨에 설치:
    docker compose run --rm openclaw-cli \
      node /app/node_modules/playwright-core/cli.js install chromium
    
  5. 브라우저 다운로드 유지: OPENCLAW_HOME_VOLUME 또는 OPENCLAW_EXTRA_MOUNTS를 사용하세요. OpenClaw는 Linux에서 Docker 이미지의 Playwright 관리 Chromium을 자동 감지합니다.
마법사에서 OpenAI Codex OAuth를 선택하면 브라우저 URL이 열립니다. Docker 또는 헤드리스 설정에서는 도착한 전체 리디렉션 URL을 복사한 뒤 마법사에 다시 붙여 넣어 인증을 완료하세요.
기본 Docker 런타임 이미지는 node:24-bookworm-slim을 사용하며, 장기 실행 컨테이너에서 좀비 프로세스가 회수되고 신호가 올바르게 처리되도록 엔트리포인트 init 프로세스(PID 1)로 tini를 포함합니다. org.opencontainers.image.base.name, org.opencontainers.image.source 등을 포함한 OCI 기본 이미지 주석을 게시합니다. Node 기본 다이제스트는 Dependabot Docker 기본 이미지 PR을 통해 갱신됩니다. 릴리스 빌드는 배포판 업그레이드 레이어를 실행하지 않습니다. OCI 이미지 주석을 참조하세요.

VPS에서 실행하나요?

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

에이전트 샌드박스

Docker 백엔드에서 agents.defaults.sandbox가 활성화되면 Gateway는 에이전트 도구 실행(셸, 파일 읽기/쓰기 등)을 격리된 Docker 컨테이너 안에서 실행하고 Gateway 자체는 호스트에 유지합니다. 이렇게 하면 전체 Gateway를 컨테이너화하지 않고도 신뢰할 수 없거나 멀티테넌트인 에이전트 세션 주위에 강한 경계를 둘 수 있습니다. 샌드박스 범위는 에이전트별(기본값), 세션별 또는 공유로 설정할 수 있습니다. 각 범위는 /workspace에 마운트된 자체 워크스페이스를 갖습니다. 허용/거부 도구 정책, 네트워크 격리, 리소스 제한, 브라우저 컨테이너도 설정할 수 있습니다. 전체 설정, 이미지, 보안 참고, 멀티 에이전트 프로필은 다음을 참조하세요.

빠른 활성화

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
      },
    },
  },
}
기본 샌드박스 이미지를 빌드합니다(소스 체크아웃에서):
scripts/sandbox-setup.sh
소스 체크아웃 없이 npm 설치를 사용하는 경우, 인라인 docker build 명령은 샌드박싱 § 이미지 및 설정을 참조하세요.

문제 해결

샌드박스 이미지를 scripts/sandbox-setup.sh (소스 체크아웃) 또는 샌드박싱 § 이미지 및 설정의 인라인 docker build 명령(npm 설치)으로 빌드하거나, agents.defaults.sandbox.docker.image를 사용자 지정 이미지로 설정하세요. 컨테이너는 필요할 때 세션별로 자동 생성됩니다.
docker.user를 마운트된 워크스페이스 소유권과 일치하는 UID:GID로 설정하거나, 워크스페이스 폴더를 chown하세요.
OpenClaw는 /etc/profile을 소싱하고 PATH를 재설정할 수 있는 sh -lc(로그인 셸)로 명령을 실행합니다. 사용자 지정 도구 경로가 앞에 오도록 docker.env.PATH를 설정하거나 Dockerfile에서 /etc/profile.d/ 아래에 스크립트를 추가하세요.
VM에는 최소 2GB RAM이 필요합니다. 더 큰 머신 클래스를 사용한 뒤 다시 시도하세요.
새 대시보드 링크를 가져와 브라우저 기기를 승인하세요.
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>
자세한 내용: 대시보드, 기기.
Gateway 모드와 바인드를 재설정하세요.
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

관련 항목