Docker 사용 가이드 (선택 사항)

개발을 하다 보면 로컬 환경의 설정이 복잡하게 꼬여서 고생하는 경우가 종종 있어요. “내 컴퓨터에서는 잘 되는데?”라는 상황을 마주하면 참 답답하죠.

이런 상황에서 환경을 독립적으로 분리해 관리하고 싶다면 Docker가 좋은 선택지가 될 수 있습니다.

필요한 것

Docker (선택 사항)

빠른 시작

Docker 사용은 필수가 아닌 선택 사항이에요. 아래 두 가지 경우에 해당할 때만 Docker를 사용하세요.

Gateway를 컨테이너화하여 관리하고 싶을 때
Docker flow를 직접 검증하고 싶을 때

Docker를 사용하면 로컬 환경에 직접 의존하지 않고 Gateway를 실행할 수 있습니다.

문제 해결

Docker flow를 검증하는 과정에서 문제가 발생한다면, 먼저 Docker 엔진이 정상적으로 실행 중인지 확인해 보세요. 이 설정은 선택 사항이므로, Docker 환경 구축이 필수는 아닙니다.

궁금한 점이 더 있다면 AI Setup Assistant에서 바로 물어보세요.

다음 단계

```mdx
---
title: "OpenClaw와 Docker: 나에게 맞는 선택은?"
description: "Docker를 사용한 Gateway 실행과 에이전트 샌드박싱 중 본인의 환경에 맞는 최적의 방법을 결정하는 가이드입니다."
---

새로운 기술을 로컬 환경에 세팅하다 보면 금방 컴퓨터가 지저분해지는 것 같아 걱정될 때가 있죠. 설치해야 할 의존성도 많고, 나중에 깔끔하게 지워질지 확신이 서지 않아 망설여졌던 경험이 다들 있으실 거예요.

OpenClaw를 시작할 때 Docker를 사용하는 것이 좋을지, 아니면 로컬에 직접 설치하는 것이 좋을지 고민 중이라면 아래 내용을 확인해 보세요.

## 필요한 것

시작하기 전에 다음 항목이 준비되어 있는지 확인해 주세요.

- Docker Desktop (또는 Docker Engine) + Docker Compose v2
- 이미지와 로그를 저장하기 위한 충분한 디스크 공간

## 빠른 시작

본인의 작업 스타일과 목적에 따라 가장 적합한 경로를 선택해 보세요. 5분이면 충분합니다.

**Docker 사용을 추천하는 경우 (Yes):**
- 격리된 일회용 Gateway 환경을 만들고 싶을 때
- 로컬에 직접 도구를 설치하지 않고 호스트에서 OpenClaw를 실행하고 싶을 때

**로컬 설치를 추천하는 경우 (No):**
- 본인의 머신에서 직접 실행하며 가장 빠른 개발 루프(dev loop)를 원할 때 (이 경우 일반 설치 플로우를 따라주세요.)

**샌드박싱(Sandboxing) 참고 사항:**
에이전트 샌드박싱 기능도 Docker를 사용합니다. 하지만 에이전트 샌드박싱을 쓴다고 해서 Gateway 전체를 반드시 Docker에서 실행해야 하는 것은 아니에요. 자세한 내용은 [Sandboxing](/docs/gateway/sandboxing) 문서를 참고해 주세요.

이 가이드는 다음 내용을 다룹니다:
- 컨테이너화된 Gateway (Docker에서 실행되는 전체 OpenClaw)
- 세션별 에이전트 샌드박스 (호스트 Gateway + Docker로 격리된 에이전트 도구)

## 문제 해결

문제가 발생할 경우 다음 사항을 먼저 확인해 보세요.

- **Docker 버전 확인**: Docker Compose v2가 정상적으로 설치되어 있는지 확인이 필요해요.
- **디스크 공간**: 로그나 이미지 파일이 차지하는 공간이 부족하지 않은지 체크해 보세요.

설치와 관련된 더 자세한 샌드박싱 정보는 [Sandboxing](/docs/gateway/sandboxing) 링크에서 확인할 수 있습니다.

궁금한 점이 더 있다면 [AI Setup Assistant](/docs/)에게 언제든 물어보세요!

## 다음 단계

- [Sandboxing](/docs/gateway/sandboxing)

---
title: "Docker Compose로 Containerized Gateway 시작하기"
description: "Docker Compose를 사용하여 OpenClaw Gateway를 빠르고 안정적으로 배포하고 관리하는 방법을 알아봅니다."
---

로컬 개발 환경을 설정하다 보면 의존성 충돌이나 환경 차이 때문에 "내 컴퓨터에서는 되는데?" 같은 상황을 자주 겪게 돼요. 특히 Gateway처럼 여러 설정이 필요한 서비스를 다룰 때는 환경을 일관되게 유지하는 게 정말 중요하죠. Docker Compose를 사용하면 이런 복잡한 과정을 줄이고 어디서나 동일한 환경에서 Gateway를 실행할 수 있어요.

## 필요한 것

시작하기 전에 다음 항목들이 준비되었는지 확인해 주세요.

- Docker 및 Docker Compose
- OpenClaw 저장소 로컬 복사본 (저장소 루트에서 작업 필요)

## 빠른 시작

가장 권장하는 방법은 제공되는 셋업 스크립트를 사용하는 거예요. 저장소 루트에서 다음 명령어를 실행하면 5분 안에 설정을 끝낼 수 있어요.

```bash
./docker-setup.sh

이 스크립트는 다음과 같은 작업을 자동으로 처리해요.

Gateway 이미지 빌드
온보딩 마법사 실행
선택 사항인 provider 설정 힌트 출력
Docker Compose를 통한 Gateway 시작
Gateway 토큰 생성 및 .env 파일 기록

사용 가능한 선택적 환경 변수는 다음과 같아요.

OPENCLAW_DOCKER_APT_PACKAGES — 빌드 중 추가 apt 패키지 설치
OPENCLAW_EXTRA_MOUNTS — 추가 호스트 bind mounts 추가
OPENCLAW_HOME_VOLUME — /home/node를 named volume에 유지

설치가 끝나면 브라우저에서 http://127.0.0.1:18789/를 여세요. 그리고 생성된 토큰을 Control UI(Settings → token)에 붙여넣으면 돼요. URL이 다시 필요하다면 다음 명령어를 실행하세요.

docker compose run --rm openclaw-cli dashboard --no-open

설정 및 워크스페이스는 호스트의 다음 경로에 저장돼요.

~/.openclaw/
~/.openclaw/workspace

VPS에서 실행 중이라면 Hetzner (Docker VPS) 가이드를 참고하세요.

Shell Helpers (선택 사항)

Docker 관리를 더 편하게 하고 싶다면 ClawDock을 설치해 보세요.

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

zsh 설정에 추가하기:

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

이제 clawdock-start, clawdock-stop, clawdock-dashboard 같은 명령어를 바로 쓸 수 있어요. 전체 명령어는 clawdock-help로 확인 가능해요. 자세한 내용은 ClawDock Helper README를 보세요.

Manual flow (Compose)

스크립트를 쓰지 않고 직접 설정하고 싶다면 이 순서대로 진행하세요.

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

참고로 모든 docker compose 명령어는 저장소 루트에서 실행해야 해요. 만약 OPENCLAW_EXTRA_MOUNTS나 OPENCLAW_HOME_VOLUME을 사용 중이라면 docker-compose.extra.yml 파일이 생성되는데, 이때는 다음과 같이 실행해야 합니다.

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

문제 해결

Control UI token + pairing

만약 “unauthorized” 또는 “disconnected (1008): pairing required” 에러가 발생하면, 새로운 대시보드 링크를 가져와서 브라우저 기기를 승인해 주세요.

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 문서를 확인하세요.

Permissions + EACCES

이미지는 node 사용자(uid 1000)로 실행돼요. 만약 /home/node/.openclaw 경로에서 권한 에러가 발생한다면, 호스트의 bind mount 경로 소유권이 uid 1000으로 되어 있는지 확인하세요.

Linux 호스트 예시:

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

Extra mounts (선택 사항)

호스트의 추가 디렉토리를 컨테이너에 마운트하고 싶다면 docker-setup.sh를 실행하기 전에 OPENCLAW_EXTRA_MOUNTS를 설정하세요.

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

macOS/Windows에서는 해당 경로가 Docker Desktop에 공유되어 있어야 해요.
이 값을 수정했다면 docker-setup.sh를 다시 실행해서 설정 파일을 갱신해야 합니다.
docker-compose.extra.yml은 자동 생성되므로 직접 수정하지 마세요.

컨테이너 홈 디렉토리 유지 (선택 사항)

컨테이너를 다시 생성해도 /home/node의 데이터를 유지하고 싶다면 OPENCLAW_HOME_VOLUME으로 named volume을 설정하세요.

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

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

이미지 내부에 build tools나 media libraries 같은 시스템 패키지가 필요하다면 OPENCLAW_DOCKER_APT_PACKAGES를 사용하세요.

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

Power-user / Full-featured 컨테이너

기본 Docker 이미지는 보안을 위해 root가 아닌 node 사용자로 실행돼요. 그래서 몇 가지 제약이 있습니다.

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

모든 기능이 포함된 컨테이너가 필요하다면 다음 설정을 조합해 보세요.

/home/node 유지: 브라우저 다운로드 및 캐시 보존
Terminal window
```
export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh
```
시스템 의존성 포함: 빌드 시 패키지 추가
Terminal window
```
export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
./docker-setup.sh
```

Playwright 브라우저 설치:

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

Faster rebuilds

빌드 속도를 높이려면 Dockerfile에서 의존성 레이어가 캐시되도록 순서를 조정하는 것이 좋아요. pnpm-lock.yaml이 바뀌지 않으면 pnpm install을 다시 실행하지 않게 됩니다.

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

Channel setup

CLI 컨테이너를 사용해 채널을 구성하고 Gateway를 재시작하세요.

WhatsApp (QR):

docker compose run --rm openclaw-cli channels login

Telegram (bot token):

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

Discord (bot token):

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

관련 문서: WhatsApp, Telegram, Discord

OpenAI Codex OAuth (headless Docker)

Docker 환경에서 OpenAI Codex OAuth를 선택하면 브라우저 콜백(http://127.0.0.1:1455/auth/callback)에서 에러가 날 수 있어요. 이때는 브라우저 주소창의 전체 리다이렉트 URL을 복사해서 마법사에 직접 붙여넣으면 인증이 완료돼요.

Health check 및 테스트

상태 확인:

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

E2E 테스트 실행:

scripts/e2e/onboard-docker.sh

QR 임포트 테스트:

pnpm test:docker:qr

설정 중에 궁금한 점이 생기면 언제든 물어봐 주세요!

AI Setup Assistant

What’s Next:

에이전트에게 파일 수정이나 명령어 실행 권한을 줄 때마다 내 컴퓨터가 망가질까 봐 불안했던 적 없으신가요? 에이전트가 의도치 않게 중요한 파일을 삭제하거나, 검증되지 않은 네트워크 요청을 보낼까 봐 걱정되는 건 모든 개발자가 공통으로 느끼는 페인 포인트일 거예요.

이런 고민을 해결하기 위해 Gateway는 호스트 시스템에 그대로 두면서, 에이전트가 사용하는 도구들만 Docker 컨테이너 안에서 따로 돌아가게 만드는 샌드박스 기능을 제공해요.

## 필요한 것

시작하기 전에 다음 사항들이 준비되어 있는지 확인해 주세요.

- 시스템에 설치된 Docker 엔진
- OpenClaw 소스 코드 및 실행 스크립트 권한
- Gateway 설정 파일 (`config.json5`)
- `scripts/sandbox-setup.sh` 실행 권한

## 빠른 시작

딱 5분 만에 최소한의 샌드박스 환경을 구성하는 방법이에요.

1.  **기본 이미지 빌드**: 터미널에서 다음 스크립트를 실행해서 기본 샌드박스 이미지를 만드세요.
    ```bash
    scripts/sandbox-setup.sh

설정 활성화: config.json5 파일에서 샌드박스 모드를 non-main으로 설정하세요.
```
{
  agents: {
    defaults: {
      sandbox: { mode: "non-main" }
    }
  }
}
```
확인: 이제 메인 세션이 아닌 에이전트가 도구를 실행할 때 자동으로 Docker 컨테이너가 생성되고 그 안에서 작업이 수행돼요.

상세 동작 방식

agents.defaults.sandbox가 활성화되면 non-main sessions의 도구들은 Docker 컨테이너 내부에서 실행돼요. 도구 실행만 격리될 뿐 Gateway 자체는 호스트에 머물러 있죠.

Scope: 기본값은 "agent"예요. 에이전트당 하나의 컨테이너와 Workspace가 할당돼요. 격리를 더 강화하고 싶다면 "session" 단위를 쓸 수 있어요.
Workspace: 각 Scope에 맞는 폴더가 컨테이너의 /workspace에 마운트돼요.
미디어 파일: 인바운드 미디어는 활성화된 샌드박스 Workspace의 media/inbound/*로 복사되어 도구가 읽을 수 있게 돼요.
주의 사항: scope: "shared"를 쓰면 세션 간 격리가 해제되어 모든 세션이 하나의 컨테이너와 Workspace를 공유하게 되니 주의가 필요해요.

더 자세한 내용은 Sandboxing 문서를 참고해 보세요.

에이전트별 샌드박스 프로필

멀티 에이전트 라우팅을 사용한다면, 에이전트마다 샌드박스와 도구 설정을 다르게 줄 수 있어요. agents.list[].sandbox와 agents.list[].tools 설정을 통해 하나의 Gateway에서 다양한 권한 수준을 운영할 수 있죠.

개인용 에이전트: 모든 권한 허용 (Full access)
업무/가족용 에이전트: 읽기 전용 도구 및 Workspace (ro)
공용 에이전트: 파일 시스템이나 Shell 도구 접근 차단
기타: 특정 도구만 허용하는 화이트리스트 정책

상세 예시와 우선순위는 Multi-Agent Sandbox & Tools에서 확인할 수 있어요.

기본 설정 및 보안 옵션

샌드박스의 기본 동작 방식과 보안 관련 하드닝 옵션들이에요.

기본 이미지: openclaw-sandbox:bookworm-slim
네트워크: 기본값은 none이에요. 외부 연결이 필요하면 명시적으로 설정해야 해요.
자동 정리 (Auto-prune): 24시간 동안 사용되지 않거나(idle), 생성된 지 7일이 지난 컨테이너는 자동으로 삭제돼요.
권한 관리: deny 설정이 allow보다 항상 우선해요. allow가 비어 있으면 deny 항목을 제외한 모든 도구를 사용할 수 있어요.

전체 설정 예시는 다음과 같아요.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
        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,
          maxAgeDays: 7,
        },
      },
    },
  },
  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-browser-setup.sh

이 스크립트는 openclaw-sandbox-browser:bookworm-slim 이미지를 생성해요. 이 컨테이너는 CDP가 활성화된 Chromium을 실행하며, Xvfb를 통해 GUI 환경을 제공해요. Headless 모드보다 봇 차단에 더 강하다는 장점이 있어요.

설정에서 브라우저를 활성화하려면 다음과 같이 작성하세요.

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

문제 해결

샌드박스 이용 중 자주 발생하는 문제와 해결 방법이에요.

패키지 설치 실패: setupCommand를 사용 중인데 패키지 설치가 안 된다면, docker.network가 "none"이거나 readOnlyRoot가 true인지 확인해 보세요. 또한 apt-get을 쓰려면 user가 root여야 해요.
설정이 반영 안 됨: OpenClaw는 컨테이너가 최근(약 5분 이내)에 사용되었다면 다시 만들지 않아요. 즉시 반영하고 싶다면 로그에 찍히는 openclaw sandbox recreate ... 명령어를 직접 실행해 보세요.
브라우저 도구 차단: 샌드박스 내에서 browser 도구를 허용하면 호스트 격리가 일부 약화될 수 있어요. 도구 정책의 allow 리스트에 browser가 있는지, deny 리스트에 들어있지는 않은지 확인해 보세요.
Workspace 쓰기 권한: workspaceAccess가 "ro"로 되어 있으면 write, edit, apply_patch 같은 도구들은 사용할 수 없게 돼요.

설정이 막막하다면 AI Setup Assistant의 도움을 받아보세요.

다음 단계

샌드박스 환경을 구축하다 보면 로컬에서는 잘 되던 기능이 컨테이너 안에서만 동작하지 않아 당황스러울 때가 있죠. 특히 권한 설정이나 환경 변수 문제는 원인을 찾는 데 의외로 많은 시간을 쓰게 됩니다.

설정 과정에서 겪을 수 있는 일반적인 문제들을 빠르게 해결하고 다시 개발에 집중할 수 있도록 돕겠습니다.

필요한 것

OpenClaw 프로젝트 소스 코드
Docker 설치 및 실행 환경
기본 CLI 사용 권한

빠른 시작

문제가 발생했을 때 가장 먼저 시도해 볼 수 있는 최소한의 단계입니다.

이미지 빌드: scripts/sandbox-setup.sh 파일을 실행해 필요한 이미지를 생성하세요.
설정 확인: agents.defaults.sandbox.docker.image 값이 올바른 이미지를 가리키고 있는지 체크하세요.

문제 해결

Image missing (이미지를 찾을 수 없음)

샌드박스 실행에 필요한 Docker 이미지가 없는 경우입니다. scripts/sandbox-setup.sh 스크립트를 직접 실행하여 빌드하거나, agents.defaults.sandbox.docker.image 설정값에 사용하려는 이미지 이름을 정확히 입력하세요.

Container not running (컨테이너가 실행 중이 아님)

컨테이너가 미리 실행되어 있지 않아도 걱정하지 마세요. OpenClaw는 세션이 시작될 때 필요에 따라(on demand) 자동으로 컨테이너를 생성하고 실행합니다.

Permission errors in sandbox (샌드박스 권한 오류)

샌드박스 내부에서 파일 접근 권한 문제가 발생한다면, 마운트된 Workspace의 소유권과 Docker 실행 사용자가 일치하지 않기 때문일 수 있습니다. docker.user 설정을 현재 사용자의 UID:GID 형식으로 지정하거나, Workspace 폴더의 소유권을 chown 명령어로 변경하세요.

Custom tools not found (커스텀 도구를 찾을 수 없음)

OpenClaw는 명령어를 실행할 때 sh -lc(login shell) 방식을 사용합니다. 이 과정에서 /etc/profile이 로드되면서 기존 PATH가 초기화될 수 있습니다. 이 문제를 해결하려면 두 가지 방법이 있습니다.

docker.env.PATH 설정에 커스텀 도구 경로를 추가하세요. (예: /custom/bin:/usr/local/share/npm-global/bin)
Dockerfile을 작성할 때 /etc/profile.d/ 아래에 경로 설정 스크립트를 추가하세요.

설정 과정에서 막히는 부분이 있다면 AI Setup Assistant에게 물어보세요.

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.