---
read_when:
    - 로컬 설치 대신 컨테이너화된 Gateway를 사용하려는 경우
    - Docker 흐름을 검증하는 경우
summary: OpenClaw용 선택적 Docker 기반 설정 및 온보딩
title: Docker
x-i18n:
    generated_at: "2026-04-26T11:31:59Z"
    model: gpt-5.4
    provider: openai
    source_hash: 3483dafa6c8baa0d4ad12df1a457e07e3c8b4182a2c5e1649bc8db66ff4c676c
    source_path: install/docker.md
    workflow: 15
---

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

## Docker가 나에게 맞을까요?

- **예**: 격리되고 일회성인 Gateway 환경이 필요하거나, 로컬 설치 없이 호스트에서 OpenClaw를 실행하려는 경우
- **아니오**: 자신의 머신에서 실행 중이고 가장 빠른 개발 루프만 원할 경우. 대신 일반 설치 흐름을 사용하세요.
- **Sandboxing 참고**: sandboxing이 활성화되면 기본 sandbox backend는 Docker를 사용하지만, sandboxing은 기본적으로 꺼져 있으며 전체 Gateway를 Docker에서 실행할 필요는 **없습니다**. SSH 및 OpenShell sandbox backend도 사용할 수 있습니다. [Sandboxing](/ko/gateway/sandboxing)을 참고하세요.

## 사전 요구 사항

- Docker Desktop(또는 Docker Engine) + Docker Compose v2
- 이미지 빌드를 위한 최소 2 GB RAM (`pnpm install`은 1 GB 호스트에서 종료 코드 137로 OOM 종료될 수 있음)
- 이미지와 로그를 위한 충분한 디스크 공간
- VPS/공개 호스트에서 실행하는 경우 [Security hardening for network exposure](/ko/gateway/security), 특히 Docker `DOCKER-USER` 방화벽 정책을 검토하세요

## 컨테이너화된 Gateway

<Steps>
  <Step title="이미지 빌드">
    저장소 루트에서 setup 스크립트를 실행하세요.

    ```bash
    ./scripts/docker/setup.sh
    ```

    이 명령은 Gateway 이미지를 로컬에서 빌드합니다. 대신 사전 빌드된 이미지를 사용하려면:

    ```bash
    export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
    ./scripts/docker/setup.sh
    ```

    사전 빌드된 이미지는 [GitHub Container Registry](https://github.com/openclaw/openclaw/pkgs/container/openclaw)에 게시됩니다.
    일반 태그: `main`, `latest`, `<version>` (예: `2026.2.26`)

  </Step>

  <Step title="온보딩 완료">
    setup 스크립트는 자동으로 온보딩을 실행합니다. 이 과정에서 다음을 수행합니다.

    - provider API 키 입력 요청
    - gateway token 생성 후 `.env`에 기록
    - Docker Compose를 통해 Gateway 시작

    설정 중에는 시작 전 온보딩과 config 쓰기가 `openclaw-gateway`를 통해 직접 실행됩니다. `openclaw-cli`는 Gateway 컨테이너가 이미 존재한 뒤 실행하는 명령용입니다.

  </Step>

  <Step title="Control UI 열기">
    브라우저에서 `http://127.0.0.1:18789/`를 열고 Settings에 구성된 shared secret을 붙여넣으세요. setup 스크립트는 기본적으로 token을 `.env`에 기록합니다. 컨테이너 config를 password 인증으로 바꿨다면 대신 그 password를 사용하세요.

    URL이 다시 필요하신가요?

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

  </Step>

  <Step title="채널 구성(선택 사항)">
    메시징 채널을 추가하려면 CLI 컨테이너를 사용하세요.

    ```bash
    # 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](/ko/channels/whatsapp), [Telegram](/ko/channels/telegram), [Discord](/ko/channels/discord)

  </Step>
</Steps>

### 수동 흐름

setup 스크립트 대신 각 단계를 직접 실행하려면:

```bash
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
```

<Note>
`docker compose`는 저장소 루트에서 실행하세요. `OPENCLAW_EXTRA_MOUNTS` 또는 `OPENCLAW_HOME_VOLUME`을 활성화했다면 setup 스크립트가 `docker-compose.extra.yml`을 작성합니다. 이 경우 `-f docker-compose.yml -f docker-compose.extra.yml`을 함께 포함하세요.
</Note>

<Note>
`openclaw-cli`는 `openclaw-gateway`의 네트워크 네임스페이스를 공유하므로 시작 후 도구입니다. `docker compose up -d openclaw-gateway` 이전에는 온보딩과 설정 시점 config 쓰기를 `--no-deps --entrypoint node`와 함께 `openclaw-gateway`를 통해 실행하세요.
</Note>

### 환경 변수

setup 스크립트는 다음 선택적 환경 변수를 지원합니다.

| 변수                                       | 목적                                                            |
| ------------------------------------------ | --------------------------------------------------------------- |
| `OPENCLAW_IMAGE`                           | 로컬 빌드 대신 원격 이미지 사용                                 |
| `OPENCLAW_DOCKER_APT_PACKAGES`             | 빌드 중 추가 apt 패키지 설치(공백 구분)                         |
| `OPENCLAW_EXTENSIONS`                      | 빌드 시 Plugin 의존성 사전 설치(공백 구분 이름)                 |
| `OPENCLAW_EXTRA_MOUNTS`                    | 추가 호스트 bind mount(쉼표 구분 `source:target[:opts]`)        |
| `OPENCLAW_HOME_VOLUME`                     | `/home/node`를 이름 있는 Docker volume에 유지                   |
| `OPENCLAW_SANDBOX`                         | sandbox bootstrap 옵트인(`1`, `true`, `yes`, `on`)             |
| `OPENCLAW_DOCKER_SOCKET`                   | Docker 소켓 경로 재정의                                         |
| `OPENCLAW_DISABLE_BONJOUR`                 | Bonjour/mDNS 광고 비활성화(Docker에서는 기본값 `1`)             |
| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | 번들된 Plugin source bind-mount overlay 비활성화                |
| `OTEL_EXPORTER_OTLP_ENDPOINT`              | OpenTelemetry export용 공용 OTLP/HTTP collector 엔드포인트      |
| `OTEL_EXPORTER_OTLP_*_ENDPOINT`            | trace, metric, log용 신호별 OTLP 엔드포인트                     |
| `OTEL_EXPORTER_OTLP_PROTOCOL`              | OTLP 프로토콜 재정의. 현재는 `http/protobuf`만 지원             |
| `OTEL_SERVICE_NAME`                        | OpenTelemetry 리소스에 사용되는 서비스 이름                     |
| `OTEL_SEMCONV_STABILITY_OPT_IN`            | 최신 실험적 GenAI semantic attribute 옵트인                     |
| `OPENCLAW_OTEL_PRELOADED`                  | 이미 preload된 경우 두 번째 OpenTelemetry SDK 시작 건너뛰기     |

유지보수자는 패키지된 이미지에 대해 번들 Plugin source를 테스트하기 위해, 하나의 Plugin source 디렉터리를 해당 패키지된 source 경로 위에 mount할 수 있습니다. 예:
`OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro`.
이렇게 mount된 source 디렉터리는 같은 Plugin ID에 대해 일치하는 컴파일된 `/app/dist/extensions/synology-chat` 번들을 재정의합니다.

### 관찰 가능성

OpenTelemetry export는 Gateway 컨테이너에서 OTLP collector로 outbound 방식으로 동작합니다. 별도의 Docker 포트를 공개할 필요는 없습니다. 이미지를 로컬에서 빌드하고 번들된 OpenTelemetry exporter를 이미지 내부에서 사용할 수 있게 하려면 해당 런타임 의존성을 포함하세요.

```bash
export OPENCLAW_EXTENSIONS="diagnostics-otel"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"
export OTEL_SERVICE_NAME="openclaw-gateway"
./scripts/docker/setup.sh
```

공식 OpenClaw Docker 릴리스 이미지에는 번들된 `diagnostics-otel` Plugin source가 포함되어 있습니다. 이미지와 캐시 상태에 따라, Gateway가 Plugin을 처음 활성화할 때 Plugin 로컬 OpenTelemetry 런타임 의존성을 다시 준비할 수 있으므로, 첫 부팅 시 package registry에 접근할 수 있게 하거나 릴리스 레인에서 이미지를 미리 준비하세요. export를 활성화하려면 config에서 `diagnostics-otel` Plugin을 허용하고 활성화한 다음, `diagnostics.otel.enabled=true`를 설정하거나 [OpenTelemetry export](/ko/gateway/opentelemetry)의 config 예시를 사용하세요. Collector 인증 헤더는 Docker 환경 변수가 아니라 `diagnostics.otel.headers`를 통해 구성합니다.

Prometheus 메트릭은 이미 공개된 Gateway 포트를 사용합니다. `diagnostics-prometheus` Plugin을 활성화한 뒤 다음을 스크레이프하세요.

```text
http://<gateway-host>:18789/api/diagnostics/prometheus
```

이 경로는 Gateway 인증으로 보호됩니다. 별도의 공개 `/metrics` 포트나 인증 없는 reverse-proxy 경로를 노출하지 마세요. [Prometheus metrics](/ko/gateway/prometheus)를 참고하세요.

### 상태 확인

컨테이너 probe 엔드포인트(인증 불필요):

```bash
curl -fsS http://127.0.0.1:18789/healthz   # liveness
curl -fsS http://127.0.0.1:18789/readyz     # readiness
```

Docker 이미지에는 `/healthz`를 확인하는 내장 `HEALTHCHECK`가 포함되어 있습니다.
검사가 계속 실패하면 Docker는 컨테이너를 `unhealthy`로 표시하고,
오케스트레이션 시스템은 이를 재시작하거나 교체할 수 있습니다.

인증된 심층 상태 스냅샷:

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

### LAN vs loopback

`scripts/docker/setup.sh`는 기본적으로 `OPENCLAW_GATEWAY_BIND=lan`을 사용하므로 Docker 포트 게시와 함께 호스트에서 `http://127.0.0.1:18789`로 접근할 수 있습니다.

- `lan` (기본값): 호스트 브라우저와 호스트 CLI가 게시된 Gateway 포트에 접근할 수 있습니다.
- `loopback`: 컨테이너 네트워크 네임스페이스 내부 프로세스만 Gateway에 직접 접근할 수 있습니다.

<Note>
`0.0.0.0` 또는 `127.0.0.1` 같은 호스트 별칭이 아니라 `gateway.bind`의 bind 모드 값(`lan` / `loopback` / `custom` / `tailnet` / `auto`)을 사용하세요.
</Note>

### Bonjour / mDNS

Docker bridge 네트워킹은 일반적으로 Bonjour/mDNS 멀티캐스트(`224.0.0.251:5353`)를 안정적으로 전달하지 못합니다. 따라서 번들된 Compose 설정은 기본적으로 `OPENCLAW_DISABLE_BONJOUR=1`을 사용하여, bridge가 멀티캐스트 트래픽을 버릴 때 Gateway가 crash-loop에 빠지거나 광고를 반복 재시작하지 않도록 합니다.

Docker 호스트에서는 게시된 Gateway URL, Tailscale 또는 광역 DNS-SD를 사용하세요.
호스트 네트워킹, macvlan 또는 mDNS 멀티캐스트가 확실히 동작하는 다른 네트워크에서만 `OPENCLAW_DISABLE_BONJOUR=0`을 설정하세요.

주의 사항과 문제 해결은 [Bonjour discovery](/ko/gateway/bonjour)를 참고하세요.

### 저장소 및 영속성

Docker Compose는 `OPENCLAW_CONFIG_DIR`을 `/home/node/.openclaw`에, `OPENCLAW_WORKSPACE_DIR`을 `/home/node/.openclaw/workspace`에 bind-mount하므로 컨테이너를 교체해도 이 경로는 유지됩니다.

이 mount된 config 디렉터리는 OpenClaw가 다음을 저장하는 위치입니다.

- 동작 config용 `openclaw.json`
- 저장된 provider OAuth/API 키 인증용 `agents/<agentId>/agent/auth-profiles.json`
- `OPENCLAW_GATEWAY_TOKEN` 같은 env 기반 런타임 비밀 정보를 위한 `.env`

VM 배포에서의 전체 영속성 세부 정보는 [Docker VM Runtime - What persists where](/ko/install/docker-vm-runtime#what-persists-where)를 참고하세요.

**디스크 증가 hotspot:** `media/`, 세션 JSONL 파일, `cron/runs/*.jsonl`, `/tmp/openclaw/` 아래의 롤링 파일 로그를 주의해서 보세요.

### 셸 도우미(선택 사항)

일상적인 Docker 관리를 더 쉽게 하려면 `ClawDock`을 설치하세요.

```bash
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` raw 경로에서 ClawDock을 설치했다면, 위 설치 명령을 다시 실행해서 로컬 도우미 파일이 새 위치를 따라가도록 하세요.

그런 다음 `clawdock-start`, `clawdock-stop`, `clawdock-dashboard` 등을 사용하세요.
전체 명령은 `clawdock-help`를 실행해 확인하세요.
전체 도우미 가이드는 [ClawDock](/ko/install/clawdock)를 참고하세요.

<AccordionGroup>
  <Accordion title="Docker Gateway용 에이전트 sandbox 활성화">
    ```bash
    export OPENCLAW_SANDBOX=1
    ./scripts/docker/setup.sh
    ```

    사용자 정의 소켓 경로(예: rootless Docker):

    ```bash
    export OPENCLAW_SANDBOX=1
    export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
    ./scripts/docker/setup.sh
    ```

    이 스크립트는 sandbox 사전 요구 사항을 통과한 뒤에만 `docker.sock`을 mount합니다. sandbox 설정을 완료할 수 없으면 스크립트는 `agents.defaults.sandbox.mode`를 `off`로 재설정합니다.

  </Accordion>

  <Accordion title="자동화 / CI (비대화형)">
    Compose의 pseudo-TTY 할당을 `-T`로 비활성화하세요.

    ```bash
    docker compose run -T --rm openclaw-cli gateway probe
    docker compose run -T --rm openclaw-cli devices list --json
    ```

  </Accordion>

  <Accordion title="공유 네트워크 보안 참고">
    `openclaw-cli`는 `network_mode: "service:openclaw-gateway"`를 사용하므로 CLI 명령이 `127.0.0.1`을 통해 gateway에 접근할 수 있습니다. 이를 공유 신뢰 경계로 취급하세요. compose config는 `openclaw-cli`에서 `NET_RAW`/`NET_ADMIN`을 제거하고 `no-new-privileges`를 활성화합니다.
  </Accordion>

  <Accordion title="권한 및 EACCES">
    이 이미지는 `node`(uid 1000) 사용자로 실행됩니다. `/home/node/.openclaw`에서 권한 오류가 발생하면, 호스트 bind mount의 소유자가 uid 1000인지 확인하세요.

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

  </Accordion>

  <Accordion title="더 빠른 재빌드">
    의존성 레이어가 캐시되도록 Dockerfile 순서를 구성하세요. 이렇게 하면 lockfile이 바뀌지 않는 한 `pnpm install`을 다시 실행하지 않아도 됩니다.

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

  </Accordion>

  <Accordion title="고급 사용자용 컨테이너 옵션">
    기본 이미지는 보안 우선이며 비루트 `node` 사용자로 실행됩니다. 더 기능이 많은 컨테이너를 원한다면:

    1. **`/home/node` 유지**: `export OPENCLAW_HOME_VOLUME="openclaw_home"`
    2. **시스템 의존성 내장**: `export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"`
    3. **Playwright 브라우저 설치**:
       ```bash
       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`를 사용하세요.

  </Accordion>

  <Accordion title="OpenAI Codex OAuth (헤드리스 Docker)">
    마법사에서 OpenAI Codex OAuth를 선택하면 브라우저 URL이 열립니다. Docker 또는 헤드리스 환경에서는 최종적으로 이동한 전체 redirect URL을 복사해 마법사에 다시 붙여넣어 인증을 완료하세요.
  </Accordion>

  <Accordion title="기본 이미지 메타데이터">
    메인 Docker 이미지는 `node:24-bookworm`을 사용하며 `org.opencontainers.image.base.name`, `org.opencontainers.image.source` 등을 포함한 OCI 기본 이미지 annotation을 게시합니다. 자세한 내용은 [OCI image annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md)를 참고하세요.
  </Accordion>
</AccordionGroup>

### VPS에서 실행 중인가요?

바이너리 내장, 영속성, 업데이트를 포함한 공유 VM 배포 단계는 [Hetzner (Docker VPS)](/ko/install/hetzner) 및 [Docker VM Runtime](/ko/install/docker-vm-runtime)을 참고하세요.

## 에이전트 Sandbox

Docker backend와 함께 `agents.defaults.sandbox`가 활성화되면, gateway 자체는 호스트에 남아 있는 상태에서 에이전트 도구 실행(셸, 파일 읽기/쓰기 등)을 격리된 Docker 컨테이너 내부에서 실행합니다. 이를 통해 전체 gateway를 컨테이너화하지 않고도 신뢰할 수 없거나 다중 테넌트인 에이전트 세션 주위에 강한 격리 경계를 둘 수 있습니다.

Sandbox 범위는 에이전트별(기본값), 세션별 또는 공유 범위가 될 수 있습니다. 각 범위는 `/workspace`에 mount된 자체 워크스페이스를 가집니다. allow/deny 도구 정책, 네트워크 격리, 리소스 제한, 브라우저 컨테이너도 구성할 수 있습니다.

전체 구성, 이미지, 보안 참고 사항, 멀티 에이전트 프로필은 다음 문서를 참고하세요.

- [Sandboxing](/ko/gateway/sandboxing) -- 전체 sandbox 참조
- [OpenShell](/ko/gateway/openshell) -- sandbox 컨테이너에 대한 대화형 셸 접근
- [Multi-Agent Sandbox and Tools](/ko/tools/multi-agent-sandbox-tools) -- 에이전트별 재정의

### 빠른 활성화

```json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
      },
    },
  },
}
```

기본 sandbox 이미지를 빌드합니다.

```bash
scripts/sandbox-setup.sh
```

## 문제 해결

<AccordionGroup>
  <Accordion title="이미지가 없거나 sandbox 컨테이너가 시작되지 않음">
    [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh)로 sandbox 이미지를 빌드하거나 `agents.defaults.sandbox.docker.image`를 사용자 정의 이미지로 설정하세요.
    컨테이너는 필요 시 세션별로 자동 생성됩니다.
  </Accordion>

  <Accordion title="sandbox에서 권한 오류">
    mount된 워크스페이스 소유권과 일치하는 UID:GID로 `docker.user`를 설정하거나 워크스페이스 폴더의 소유권을 변경하세요.
  </Accordion>

  <Accordion title="sandbox에서 사용자 정의 도구를 찾을 수 없음">
    OpenClaw는 `sh -lc`(로그인 셸)로 명령을 실행하므로 `/etc/profile`을 읽고 PATH를 재설정할 수 있습니다. 사용자 정의 도구 경로를 앞에 추가하려면 `docker.env.PATH`를 설정하거나 Dockerfile의 `/etc/profile.d/` 아래에 스크립트를 추가하세요.
  </Accordion>

  <Accordion title="이미지 빌드 중 OOM 종료됨(종료 코드 137)">
    VM에는 최소 2 GB RAM이 필요합니다. 더 큰 머신 클래스를 사용하고 다시 시도하세요.
  </Accordion>

  <Accordion title="Control UI에서 unauthorized 또는 pairing required 표시">
    새 dashboard 링크를 가져오고 브라우저 device를 승인하세요.

    ```bash
    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](/ko/web/dashboard), [Devices](/ko/cli/devices).

  </Accordion>

  <Accordion title="Gateway 대상이 ws://172.x.x.x로 표시되거나 Docker CLI에서 pairing 오류 발생">
    gateway 모드와 bind를 재설정하세요.

    ```bash
    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
    ```

  </Accordion>
</AccordionGroup>

## 관련 항목

- [Install Overview](/ko/install) — 모든 설치 방법
- [Podman](/ko/install/podman) — Docker의 Podman 대안
- [ClawDock](/ko/install/clawdock) — Docker Compose 커뮤니티 설정
- [Updating](/ko/install/updating) — OpenClaw를 최신 상태로 유지하기
- [Configuration](/ko/gateway/configuration) — 설치 후 gateway 구성
