​

Docker (선택 사항)

​

Docker 가 나에게 맞을까요?

• 예: 격리된 일회용 게이트웨이 환경이 필요하거나 로컬 설치 없이 호스트에서 OpenClaw 를 실행하고 싶을 때.
• 아니오: 개인 머신에서 실행하며 가장 빠른 개발 루프만 원할 때. 대신 일반 설치 플로우를 사용하십시오.
• 샌드박스 참고: 에이전트 샌드박스화도 Docker 를 사용하지만, 전체 Gateway(게이트웨이)를 Docker 에서 실행할 필요는 없습니다. Sandboxing을 참고하십시오.

• 컨테이너화된 Gateway(게이트웨이) (Docker 에서 전체 OpenClaw 실행)
• 세션별 에이전트 샌드박스 (호스트 게이트웨이 + Docker 로 격리된 에이전트 도구)

​

요구 사항

• Docker Desktop (또는 Docker Engine) + Docker Compose v2
• 이미지 + 로그를 위한 충분한 디스크 공간

​

컨테이너화된 Gateway(게이트웨이) (Docker Compose)

​

빠른 시작 (권장)

./docker-setup.sh

• 게이트웨이 이미지 빌드
• 온보딩 마법사 실행
• 선택적 공급자 설정 힌트를 출력합니다
• Docker Compose 를 통해 게이트웨이 시작
• 게이트웨이 토큰을 생성하고 .env 에 기록

• OPENCLAW_DOCKER_APT_PACKAGES — 빌드 중 추가 apt 패키지 설치
• OPENCLAW_EXTRA_MOUNTS — 추가 호스트 바인드 마운트 추가
• OPENCLAW_HOME_VOLUME — /home/node 를 이름 있는 볼륨에 영구 저장

• 브라우저에서 http://127.0.0.1:18789/ 을 여십시오.
• Control UI (Settings → token)에 토큰을 붙여넣으십시오.
• URL 이 다시 필요하신가요? docker compose run --rm openclaw-cli dashboard --no-open 를 실행하십시오.

• ~/.openclaw/
• ~/.openclaw/workspace

​

Shell 도우미 (선택 사항)

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

​

수동 플로우 (compose)

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

docker compose -f docker-compose.yml -f docker-compose.extra.yml <command>

​

Control UI 토큰 + 페어링 (Docker)

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>

​

추가 마운트 (선택 사항)

export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

• macOS/Windows 에서는 경로가 Docker Desktop 과 공유되어야 합니다.
• OPENCLAW_EXTRA_MOUNTS 을 수정한 경우, docker-setup.sh 을 다시 실행하여 추가 compose 파일을 재생성하십시오.
• docker-compose.extra.yml 은 자동 생성됩니다. 수동으로 편집하지 마십시오.

​

전체 컨테이너 홈 영구화 (선택 사항)

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

export OPENCLAW_HOME_VOLUME="openclaw_home"
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

• OPENCLAW_HOME_VOLUME 을 변경한 경우, docker-setup.sh 를 다시 실행하여 추가 compose 파일을 재생성하십시오.
• 이름 있는 볼륨은 docker volume rm <name> 로 제거할 때까지 유지됩니다.

​

추가 apt 패키지 설치 (선택 사항)

export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

• 공백으로 구분된 apt 패키지 이름 목록을 허용합니다.
• OPENCLAW_DOCKER_APT_PACKAGES 을 변경한 경우, docker-setup.sh 를 다시 실행하여 이미지를 재빌드하십시오.

​

파워 유저 / 풀 기능 컨테이너 (옵트인)

• 런타임 중 시스템 패키지 설치 불가
• 기본적으로 Homebrew 없음
• Chromium/Playwright 브라우저 번들 없음

1. /home/node 영구화 — 브라우저 다운로드 및 도구 캐시 유지:

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

2. 시스템 의존성을 이미지에 포함 (재현 가능 + 영구):

export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
./docker-setup.sh

3. npx 없이 Playwright 브라우저 설치 (npm override 충돌 방지):

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

4. Playwright 브라우저 다운로드 영구화:

• docker-compose.yml 에서 PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright 설정.
• OPENCLAW_HOME_VOLUME 를 통해 /home/node 이 유지되도록 하거나, OPENCLAW_EXTRA_MOUNTS 를 통해 /home/node/.cache/ms-playwright 을 마운트하십시오.

​

권한 + EACCES

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

​

더 빠른 재빌드 (권장)

FROM node:22-bookworm

# Install Bun (required for build scripts)
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# Cache dependencies unless package metadata changes
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"]

​

채널 설정 (선택 사항)

docker compose run --rm openclaw-cli channels login

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

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

​

OpenAI Codex OAuth (헤드리스 Docker)

​

헬스 체크

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

​

E2E 스모크 테스트 (Docker)

scripts/e2e/onboard-docker.sh

​

QR 가져오기 스모크 테스트 (Docker)

pnpm test:docker:qr

​

참고 사항

• 게이트웨이 바인드는 컨테이너 사용을 위해 기본적으로 lan 에 바인드됩니다.
• Dockerfile CMD 는 --allow-unconfigured 을 사용합니다. gateway.mode 이 아닌 local 로 마운트된 설정도 여전히 시작됩니다. Override CMD to enforce the guard.
• 게이트웨이 컨테이너는 세션에 대한 단일 소스 오브 트루스입니다 (~/.openclaw/agents/<agentId>/sessions/).

​

에이전트 샌드박스 (호스트 게이트웨이 + Docker 도구)

​

What it does

• 범위: 기본값 "agent" (에이전트당 하나의 컨테이너 + 워크스페이스)
• 범위: 세션별 격리를 위한 "session"
• 범위별 워크스페이스 폴더는 /workspace 에 마운트
• 선택적 에이전트 워크스페이스 접근 (agents.defaults.sandbox.workspaceAccess)
• 허용/차단 도구 정책 (차단 우선)
• 인바운드 미디어는 활성 샌드박스 워크스페이스 (media/inbound/*) 로 복사되어 도구가 읽을 수 있음 (workspaceAccess: "rw" 사용 시 에이전트 워크스페이스에 위치)

​

에이전트별 샌드박스 프로파일 (멀티 에이전트)

• 전체 접근 (개인 에이전트)
• 읽기 전용 도구 + 읽기 전용 워크스페이스 (가족/업무 에이전트)
• 파일시스템/셸 도구 없음 (공개 에이전트)

​

기본 동작

• 이미지: openclaw-sandbox:bookworm-slim
• 에이전트당 하나의 컨테이너
• 에이전트 워크스페이스 접근: workspaceAccess: "none" (기본값) 은 ~/.openclaw/sandboxes 사용
  • "ro" 는 샌드박스 워크스페이스를 /workspace 에 유지하고, 에이전트 워크스페이스를 /agent 에 읽기 전용으로 마운트 (write/edit/apply_patch 비활성화)
  • "rw" 는 에이전트 워크스페이스를 /workspace 에 읽기/쓰기 마운트
• 자동 정리: 유휴 > 24시간 또는 수명 > 7일
• 네트워크: 기본값 none (이그레스가 필요하면 명시적으로 옵트인)
• 기본 허용: exec, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
• 기본 차단: browser, canvas, nodes, cron, discord, gateway

​

샌드박스 활성화

• 기본 docker.network 은 "none" (이그레스 없음)입니다.
• readOnlyRoot: true 는 패키지 설치를 차단합니다.
• apt-get 를 위해 user 는 root 여야 합니다 (user 를 생략하거나 user: "0:0" 로 설정). OpenClaw 는 setupCommand (또는 docker 설정)가 변경되면 컨테이너를 자동으로 재생성하지만, 컨테이너가 최근에 사용된 경우(약 5분 이내)에는 제외됩니다. 활성 컨테이너는 정확한 openclaw sandbox recreate ... 명령과 함께 경고를 로그로 남깁니다.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent is default)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
        },
        prune: {
          idleHours: 24, // 0 disables idle pruning
          maxAgeDays: 7, // 0 disables max-age pruning
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

​

기본 샌드박스 이미지 빌드

scripts/sandbox-setup.sh

​

샌드박스 공통 이미지 (선택 사항)

scripts/sandbox-common-setup.sh

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } },
    },
  },
}

​

샌드박스 브라우저 이미지

scripts/sandbox-browser-setup.sh

• Headful (Xvfb) 모드는 headless 대비 봇 차단을 줄입니다.
• agents.defaults.sandbox.browser.headless=true 을 설정하면 headless 도 사용 가능합니다.
• 전체 데스크톱 환경 (GNOME) 은 필요하지 않으며, Xvfb 가 디스플레이를 제공합니다.

{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true },
      },
    },
  },
}

{
  agents: {
    defaults: {
      sandbox: { browser: { image: "my-openclaw-browser" } },
    },
  },
}

• 샌드박스 브라우저 제어 URL (browser 도구용)
• noVNC URL (활성화되어 있고 headless=false 인 경우)

​

커스텀 샌드박스 이미지

docker build -t my-openclaw-sbx -f Dockerfile.sandbox .

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-openclaw-sbx" } },
    },
  },
}

​

도구 정책 (허용/차단)

• deny 이 allow 보다 우선합니다.
• allow 이 비어 있으면: (차단을 제외한) 모든 도구를 사용할 수 있습니다.
• allow 이 비어 있지 않으면: allow 에 있는 도구만 사용 가능하며 (차단 제외).

​

정리 전략

• prune.idleHours: X 시간 동안 사용되지 않은 컨테이너 제거 (0 = 비활성화)
• prune.maxAgeDays: X 일보다 오래된 컨테이너 제거 (0 = 비활성화)

• 활성 세션은 유지하되 수명 제한: idleHours: 24, maxAgeDays: 7
• 정리 안 함: idleHours: 0, maxAgeDays: 0

​

보안 참고 사항

• 강력한 격리는 도구에만 적용됩니다 (exec/read/write/edit/apply_patch).
• 브라우저/카메라/캔버스와 같은 호스트 전용 도구는 기본적으로 차단됩니다.
• 샌드박스에서 browser 을 허용하면 격리가 깨집니다 (브라우저가 호스트에서 실행).

​

문제 해결

• 이미지 누락: scripts/sandbox-setup.sh 로 빌드하거나 agents.defaults.sandbox.docker.image 을 설정하십시오.
• 컨테이너가 실행되지 않음: 세션 요청 시 자동으로 생성됩니다.
• 샌드박스 권한 오류: docker.user 를 마운트된 워크스페이스 소유권과 일치하는 UID:GID 로 설정하십시오 (또는 워크스페이스 폴더의 소유권을 변경).
• 커스텀 도구를 찾을 수 없음: OpenClaw 는 sh -lc (로그인 셸)로 명령을 실행하며, 이는 /etc/profile 을 소스하고 PATH 를 재설정할 수 있습니다. docker.env.PATH 를 설정하여 커스텀 도구 경로(예: /custom/bin:/usr/local/share/npm-global/bin)를 앞에 추가하거나, Dockerfile 에서 /etc/profile.d/ 아래에 스크립트를 추가하십시오.