메인 콘텐츠로 건너뛰기

​
Docker (선택 사항)

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

​
Docker가 나에게 적합할까요?

  • 예: 격리되고 일회성인 gateway 환경이 필요하거나 로컬 설치 없이 호스트에서 OpenClaw를 실행하려는 경우
  • 아니요: 직접 사용하는 머신에서 실행 중이고 가장 빠른 개발 루프만 원한다면 일반 설치 흐름을 대신 사용하세요.
  • 샌드박싱 참고: 에이전트 샌드박싱도 Docker를 사용하지만, 전체 gateway를 Docker에서 실행할 필요는 없습니다. Sandboxing을 참고하세요.

​
사전 요구 사항

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

​
컨테이너화된 Gateway

1

이미지 빌드

리포지토리 루트에서 설정 스크립트를 실행하세요.
./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

온보딩 완료

설정 스크립트는 자동으로 온보딩을 실행합니다. 수행되는 작업은 다음과 같습니다.
  • 프로바이더 API 키 입력 요청
  • gateway 토큰 생성 후 .env에 기록
  • 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
docker compose는 리포지토리 루트에서 실행하세요. OPENCLAW_EXTRA_MOUNTS 또는 OPENCLAW_HOME_VOLUME을 활성화한 경우 설정 스크립트가 docker-compose.extra.yml을 작성합니다. 이 경우 -f docker-compose.yml -f docker-compose.extra.yml과 함께 포함하세요.
openclaw-cli는 openclaw-gateway의 네트워크 네임스페이스를 공유하므로 시작 후 도구입니다. docker compose up -d openclaw-gateway 전에 온보딩과 설정 시점 구성 쓰기는 --no-deps --entrypoint node와 함께 openclaw-gateway를 통해 실행하세요.

​
환경 변수

설정 스크립트는 다음 선택적 환경 변수를 지원합니다.
변수용도
OPENCLAW_IMAGE로컬 빌드 대신 원격 이미지 사용
OPENCLAW_DOCKER_APT_PACKAGES빌드 중 추가 apt 패키지 설치(공백으로 구분)
OPENCLAW_EXTENSIONS빌드 시점에 extension 의존성 사전 설치(이름을 공백으로 구분)
OPENCLAW_EXTRA_MOUNTS추가 호스트 bind mount(쉼표로 구분된 source:target[:opts])
OPENCLAW_HOME_VOLUME이름 있는 Docker 볼륨에 /home/node 영속화
OPENCLAW_SANDBOX샌드박스 부트스트랩 사용(1, true, yes, on)
OPENCLAW_DOCKER_SOCKETDocker 소켓 경로 재정의

​
상태 점검

컨테이너 프로브 엔드포인트(인증 필요 없음): 
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에 직접 접근할 수 있습니다.
0.0.0.0 또는 127.0.0.1 같은 호스트 별칭이 아니라 gateway.bind의 bind 모드 값(lan / loopback / custom / tailnet / auto)을 사용하세요.

​
저장소 및 영속성

Docker Compose는 OPENCLAW_CONFIG_DIR를 /home/node/.openclaw에, OPENCLAW_WORKSPACE_DIR를 /home/node/.openclaw/workspace에 bind mount하므로 이 경로들은 컨테이너가 교체되어도 유지됩니다. 마운트된 이 구성 디렉터리는 OpenClaw가 다음을 저장하는 위치입니다.
  • 동작 구성을 위한 openclaw.json
  • 저장된 프로바이더 OAuth/API 키 인증을 위한 agents/<agentId>/agent/auth-profiles.json
  • OPENCLAW_GATEWAY_TOKEN 같은 env 기반 런타임 비밀을 위한 .env
VM 배포의 전체 영속성 세부 정보는 Docker VM Runtime - What persists where를 참고하세요. 디스크 증가 주요 지점: media/, 세션 JSONL 파일, cron/runs/*.jsonl, /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
사용자 지정 소켓 경로(예: 루트리스 Docker):
export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh
스크립트는 샌드박스 사전 요구 사항이 충족된 후에만 docker.sock를 마운트합니다. 샌드박스 설정을 완료할 수 없으면 스크립트는 agents.defaults.sandbox.mode를 off로 재설정합니다.
Compose 가상 TTY 할당은 -T로 비활성화하세요.
docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json
openclaw-cli는 network_mode: "service:openclaw-gateway"를 사용하므로 CLI 명령이 127.0.0.1을 통해 gateway에 접근할 수 있습니다. 이를 공유된 신뢰 경계로 취급하세요. Compose 구성은 openclaw-cli에서 NET_RAW/NET_ADMIN을 제거하고 no-new-privileges를 활성화합니다.
이미지는 node(uid 1000) 사용자로 실행됩니다. /home/node/.openclaw에서 권한 오류가 발생하면 호스트 bind mount의 소유자가 uid 1000인지 확인하세요.
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
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"]
기본 이미지는 보안을 우선하며 비루트 node 사용자로 실행됩니다. 더 완전한 기능의 컨테이너를 원한다면 다음을 고려하세요.
  1. /home/node 영속화: export OPENCLAW_HOME_VOLUME="openclaw_home"
  2. 시스템 의존성 포함: export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
  3. Playwright 브라우저 설치: 
    docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium
  4. 브라우저 다운로드 영속화: 다음을 설정하세요. PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright 그리고 OPENCLAW_HOME_VOLUME 또는 OPENCLAW_EXTRA_MOUNTS를 사용하세요.
마법사에서 OpenAI Codex OAuth를 선택하면 브라우저 URL이 열립니다. Docker 또는 헤드리스 환경에서는 도착한 전체 리디렉션 URL을 복사해 다시 마법사에 붙여넣어 인증을 완료하세요.
기본 Docker 이미지는 node:24-bookworm을 사용하며 org.opencontainers.image.base.name, org.opencontainers.image.source 등을 포함한 OCI 기본 이미지 어노테이션을 게시합니다. 자세한 내용은 OCI image annotations를 참고하세요.

​
VPS에서 실행 중인가요?

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

​
에이전트 샌드박스

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

​
빠른 활성화

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
      },
    },
  },
}
기본 샌드박스 이미지를 빌드하세요. 
scripts/sandbox-setup.sh

​
문제 해결

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

​
관련 문서