​

Docker (optional)

​

Docker가 나에게 적합한가요?

• 예: 분리되고 일회용 게이트웨이 환경을 원하거나 로컬 설치 없이 호스트에서 OpenClaw를 실행하려는 경우.
• 아니오: 개인 기기에서 실행 중이며, 가장 빠른 개발 루프를 원한다면. 대신 일반 설치 흐름을 사용하세요.
• 샌드박스 주의사항: 에이전트 샌드박스 격리 또한 Docker를 사용하지만, 전체 게이트웨이를 Docker에서 실행할 필요는 없습니다. 샌드박스 격리를 참조하세요.

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

​

요구사항

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

​

컨테이너화된 게이트웨이 (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/를 엽니다.
• 토큰을 컨트롤 UI (설정 → 토큰)에 붙여넣습니다.
• URL이 필요하신가요? docker compose run --rm openclaw-cli dashboard --no-open을 실행하세요.

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

​

쉘 헬퍼 (선택 사항)

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>

​

컨트롤 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과 공유해야 합니다.
• 각 항목은 공백, 탭, 줄 바꿈 없이 source:target[:options] 형식이어야 합니다.
• 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

• 명명된 볼륨 이름은 ^[A-Za-z0-9][A-Za-z0-9_.-]*$ 패턴과 일치해야 합니다.
• 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 오버라이드 충돌 회피):

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 설정.
• /home/node는 OPENCLAW_HOME_VOLUME을 통해 지속되거나, /home/node/.cache/ms-playwright는 OPENCLAW_EXTRA_MOUNTS를 통해 마운트됩니다.

​

권한 + EACCES

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

​

더 빠른 재구축 (권장)

FROM node:24-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 (headless 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이 아닌 설치 구성은 여전히 시작됩니다. CMD를 무시하여 보호를 강화합니다.
• 게이트웨이 컨테이너는 세션 (~/.openclaw/agents/<agentId>/sessions/)의 진실 소스입니다.

​

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

​

그 작동 방식

• 범위: 기본으로 "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 (출구가 필요한 경우 명시적 선택 필요)
  • host는 차단됩니다.
  • container:<id>는 기본적으로 차단됩니다 (네임스페이스 결합 위험).
• 기본 허용: exec, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
• 기본 거부: browser, canvas, nodes, cron, discord, gateway

​

샌드박스 격리 활성화

• 기본 docker.network는 "none" (출구 없음).
• docker.network: "host"는 차단됩니다.
• docker.network: "container:<id>"는 기본적으로 차단됩니다.
• Break-glass 오버라이드: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.
• readOnlyRoot: true는 패키지 설치를 차단합니다.
• user는 apt-get을 위해 루트여야 합니다 ( user를 생략하거나 user: "0:0"으로 설정). setupCommand (또는 docker 설정)가 변경되면 OpenClaw는 자동으로 컨테이너를 재생성합니다 컨테이너가 최근에 사용되지 않은 경우 (약 5분 이내). 뜨거운 컨테이너는 정확한 openclaw sandbox recreate ... 명령어를 로그로 경고합니다.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (기본은 agent)
        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은 대기 정리 비활성화
          maxAgeDays: 7, // 0은 최대 나이 정리 비활성화
        },
      },
    },
  },
  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 대비 봇 차단을 줄입니다.
• Headless도 agents.defaults.sandbox.browser.headless=true로 설정하여 여전히 사용할 수 있습니다.
• 전체 데스크탑 환경 (GNOME)은 필요하지 않으며; Xvfb가 디스플레이를 제공합니다.
• 브라우저 컨테이너는 글로벌 bridge 대신 기본적으로 전용 Docker 네트워크 (openclaw-sandbox-browser)를 사용합니다.
• 선택적 agents.defaults.sandbox.browser.cdpSourceRange는 CIDR로 컨테이너 엣지 CDP 수신을 제한합니다 (예: 172.21.0.1/32).
• noVNC 관찰자 접근은 기본적으로 비밀번호로 보호됩니다; OpenClaw는 URL에 원시 비밀번호를 공유하는 대신 단기 관찰자 토큰 URL을 제공합니다.

{
  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/camera/canvas).
• 샌드박스에서 browser를 허용하는 것은 격리를 파괴합니다 (브라우저는 호스트에서 실행).

​

문제 해결

• 이미지 없음: scripts/sandbox-setup.sh로 빌드하거나 agents.defaults.sandbox.docker.image를 설정하세요.
• 컨테이너가 실행되지 않음: 세션 수요에 따라 자동으로 생성됩니다.
• 샌드박스에서의 권한 오류: docker.user를 마운트된 작업 공간 소유권에 맞는 UID:GID로 설정하거나 작업 공간 폴더의 소유권을 변경하세요.
• 사용자 지정 도구를 찾을 수 없음: OpenClaw는 sh -lc (로그인 셸)로 명령을 실행하며, 이는 /etc/profile을 소스하며 PATH를 재설정할 수 있습니다. docker.env.PATH에 사용자 지정 도구 경로를 미리 설정하거나 Dockerfile 내 /etc/profile.d/ 아래에 스크립트를 추가하세요.