openclaw/docs/install/docker.md

summary, read_when, title

summary	read_when	title
Optional Docker-based setup and onboarding for OpenClaw	You want a containerized gateway instead of local installs You are validating the Docker flow	Docker

Docker is optional. Use it only if you want a containerized gateway or to validate the Docker flow.

Is Docker right for me?

• Yes: you want an isolated, throwaway gateway environment or to run OpenClaw on a host without local installs.
• No: you are running on your own machine and just want the fastest dev loop. Use the normal install flow instead.
• Sandboxing note: the default sandbox backend uses Docker when sandboxing is enabled, but sandboxing is off by default and does not require the full gateway to run in Docker. SSH and OpenShell sandbox backends are also available. See Sandboxing.

Prerequisites

• Docker Desktop (or Docker Engine) + Docker Compose v2
• At least 2 GB RAM for image build (pnpm install may be OOM-killed on 1 GB hosts with exit 137)
• Enough disk for images and logs
• If running on a VPS/public host, review Security hardening for network exposure, especially Docker DOCKER-USER firewall policy.

Containerized gateway

From the repo root, run the setup script:

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

This builds the gateway image locally. To use a pre-built image instead:

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

Pre-built images are published at the
[GitHub Container Registry](https://github.com/openclaw/openclaw/pkgs/container/openclaw).
Common tags: `main`, `latest`, `<version>` (e.g. `2026.2.26`).

The setup script runs onboarding automatically. It will:

- prompt for provider API keys
- generate a gateway token and write it to `.env`
- start the gateway via Docker Compose

During setup, pre-start onboarding and config writes run through
`openclaw-gateway` directly. `openclaw-cli` is for commands you run after
the gateway container already exists.

Open `http://127.0.0.1:18789/` in your browser and paste the configured shared secret into Settings. The setup script writes a token to `.env` by default; if you switch the container config to password auth, use that password instead.

Need the URL again?

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

Use the CLI container to add messaging channels:

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

Docs: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord)

Manual flow

If you prefer to run each step yourself instead of using the setup script:

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

Run `docker compose` from the repo root. If you enabled `OPENCLAW_EXTRA_MOUNTS` or `OPENCLAW_HOME_VOLUME`, the setup script writes `docker-compose.extra.yml`; include it with `-f docker-compose.yml -f docker-compose.extra.yml`. Because `openclaw-cli` shares `openclaw-gateway`'s network namespace, it is a post-start tool. Before `docker compose up -d openclaw-gateway`, run onboarding and setup-time config writes through `openclaw-gateway` with `--no-deps --entrypoint node`.

Environment variables

The setup script accepts these optional environment variables:

Variable	Purpose
OPENCLAW_IMAGE	Use a remote image instead of building locally
OPENCLAW_DOCKER_APT_PACKAGES	Install extra apt packages during build (space-separated)
OPENCLAW_EXTENSIONS	Pre-install plugin deps at build time (space-separated names)
OPENCLAW_EXTRA_MOUNTS	Extra host bind mounts (comma-separated source:target[:opts])
OPENCLAW_HOME_VOLUME	Persist /home/node in a named Docker volume
OPENCLAW_SANDBOX	Opt in to sandbox bootstrap (1, true, yes, on)
OPENCLAW_DOCKER_SOCKET	Override Docker socket path
OPENCLAW_DISABLE_BONJOUR	Disable Bonjour/mDNS advertising (defaults to 1 for Docker)
OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS	Disable bundled plugin source bind-mount overlays
OTEL_EXPORTER_OTLP_ENDPOINT	Shared OTLP/HTTP collector endpoint for OpenTelemetry export
OTEL_EXPORTER_OTLP_*_ENDPOINT	Signal-specific OTLP endpoints for traces, metrics, or logs
OTEL_EXPORTER_OTLP_PROTOCOL	OTLP protocol override. Only http/protobuf is supported today
OTEL_SERVICE_NAME	Service name used for OpenTelemetry resources
OTEL_SEMCONV_STABILITY_OPT_IN	Opt in to latest experimental GenAI semantic attributes
OPENCLAW_OTEL_PRELOADED	Skip starting a second OpenTelemetry SDK when one is preloaded

Maintainers can test bundled plugin source against a packaged image by mounting one plugin source directory over its packaged source path, for example OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. That mounted source directory overrides the matching compiled /app/dist/extensions/synology-chat bundle for the same plugin id.

Observability

OpenTelemetry export is outbound from the Gateway container to your OTLP collector. It does not require a published Docker port. If you build the image locally and want the bundled OpenTelemetry exporter available inside the image, include its runtime dependencies:

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

The official OpenClaw Docker release image includes the bundled diagnostics-otel plugin source. Depending on the image and cache state, the Gateway may still stage plugin-local OpenTelemetry runtime dependencies the first time the plugin is enabled, so allow that first boot to reach the package registry or prewarm the image in your release lane. To enable export, allow and enable the diagnostics-otel plugin in config, then set diagnostics.otel.enabled=true or use the config example in OpenTelemetry export. Collector auth headers are configured through diagnostics.otel.headers, not through Docker environment variables.

Prometheus metrics use the already-published Gateway port. Enable the diagnostics-prometheus plugin, then scrape:

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

The route is protected by Gateway authentication. Do not expose a separate public /metrics port or unauthenticated reverse-proxy path. See Prometheus metrics.

Health checks

Container probe endpoints (no auth required):

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

The Docker image includes a built-in HEALTHCHECK that pings /healthz. If checks keep failing, Docker marks the container as unhealthy and orchestration systems can restart or replace it.

Authenticated deep health snapshot:

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

LAN vs loopback

scripts/docker/setup.sh defaults OPENCLAW_GATEWAY_BIND=lan so host access to http://127.0.0.1:18789 works with Docker port publishing.

• lan (default): host browser and host CLI can reach the published gateway port.
• loopback: only processes inside the container network namespace can reach the gateway directly.

Use bind mode values in `gateway.bind` (`lan` / `loopback` / `custom` / `tailnet` / `auto`), not host aliases like `0.0.0.0` or `127.0.0.1`.

Bonjour / mDNS

Docker bridge networking usually does not forward Bonjour/mDNS multicast (224.0.0.251:5353) reliably. The bundled Compose setup therefore defaults OPENCLAW_DISABLE_BONJOUR=1 so the Gateway does not crash-loop or repeatedly restart advertising when the bridge drops multicast traffic.

Use the published Gateway URL, Tailscale, or wide-area DNS-SD for Docker hosts. Set OPENCLAW_DISABLE_BONJOUR=0 only when running with host networking, macvlan, or another network where mDNS multicast is known to work.

For gotchas and troubleshooting, see Bonjour discovery.

Storage and persistence

Docker Compose bind-mounts OPENCLAW_CONFIG_DIR to /home/node/.openclaw and OPENCLAW_WORKSPACE_DIR to /home/node/.openclaw/workspace, so those paths survive container replacement.

That mounted config directory is where OpenClaw keeps:

• openclaw.json for behavior config
• agents/<agentId>/agent/auth-profiles.json for stored provider OAuth/API-key auth
• .env for env-backed runtime secrets such as OPENCLAW_GATEWAY_TOKEN

For full persistence details on VM deployments, see Docker VM Runtime - What persists where.

Disk growth hotspots: watch media/, session JSONL files, cron/runs/*.jsonl, and rolling file logs under /tmp/openclaw/.

Shell helpers (optional)

For easier day-to-day Docker management, install 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

If you installed ClawDock from the older scripts/shell-helpers/clawdock-helpers.sh raw path, rerun the install command above so your local helper file tracks the new location.

Then use clawdock-start, clawdock-stop, clawdock-dashboard, etc. Run clawdock-help for all commands. See ClawDock for the full helper guide.

```bash export OPENCLAW_SANDBOX=1 ./scripts/docker/setup.sh ```

Custom socket path (e.g. rootless Docker):

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

The script mounts `docker.sock` only after sandbox prerequisites pass. If
sandbox setup cannot complete, the script resets `agents.defaults.sandbox.mode`
to `off`.

Disable Compose pseudo-TTY allocation with `-T`:

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

`openclaw-cli` uses `network_mode: "service:openclaw-gateway"` so CLI commands can reach the gateway over `127.0.0.1`. Treat this as a shared trust boundary. The compose config drops `NET_RAW`/`NET_ADMIN` and enables `no-new-privileges` on `openclaw-cli`. The image runs as `node` (uid 1000). If you see permission errors on `/home/node/.openclaw`, make sure your host bind mounts are owned by uid 1000:

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

Order your Dockerfile so dependency layers are cached. This avoids re-running `pnpm install` unless lockfiles change:

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

The default image is security-first and runs as non-root `node`. For a more full-featured container:

1. **Persist `/home/node`**: `export OPENCLAW_HOME_VOLUME="openclaw_home"`
2. **Bake system deps**: `export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"`
3. **Install Playwright browsers**:
   ```bash
   docker compose run --rm openclaw-cli \
     node /app/node_modules/playwright-core/cli.js install chromium
   ```
4. **Persist browser downloads**: set
   `PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright` and use
   `OPENCLAW_HOME_VOLUME` or `OPENCLAW_EXTRA_MOUNTS`.

If you pick OpenAI Codex OAuth in the wizard, it opens a browser URL. In Docker or headless setups, copy the full redirect URL you land on and paste it back into the wizard to finish auth. The main Docker runtime image uses `node:24-bookworm-slim` and publishes OCI base-image annotations including `org.opencontainers.image.base.name`, `org.opencontainers.image.source`, and others. The Node base digest is refreshed through Dependabot Docker base-image PRs; release builds do not run a distro upgrade layer. See [OCI image annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md).

Running on a VPS?

See Hetzner (Docker VPS) and Docker VM Runtime for shared VM deployment steps including binary baking, persistence, and updates.

Agent sandbox

When agents.defaults.sandbox is enabled with the Docker backend, the gateway runs agent tool execution (shell, file read/write, etc.) inside isolated Docker containers while the gateway itself stays on the host. This gives you a hard wall around untrusted or multi-tenant agent sessions without containerizing the entire gateway.

Sandbox scope can be per-agent (default), per-session, or shared. Each scope gets its own workspace mounted at /workspace. You can also configure allow/deny tool policies, network isolation, resource limits, and browser containers.

For full configuration, images, security notes, and multi-agent profiles, see:

• Sandboxing -- complete sandbox reference
• OpenShell -- interactive shell access to sandbox containers
• Multi-Agent Sandbox and Tools -- per-agent overrides

Quick enable

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

Build the default sandbox image:

scripts/sandbox-setup.sh

Troubleshooting

Build the sandbox image with [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) or set `agents.defaults.sandbox.docker.image` to your custom image. Containers are auto-created per session on demand. Set `docker.user` to a UID:GID that matches your mounted workspace ownership, or chown the workspace folder. OpenClaw runs commands with `sh -lc` (login shell), which sources `/etc/profile` and may reset PATH. Set `docker.env.PATH` to prepend your custom tool paths, or add a script under `/etc/profile.d/` in your Dockerfile. The VM needs at least 2 GB RAM. Use a larger machine class and retry. Fetch a fresh dashboard link and approve the browser 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>
```

More detail: [Dashboard](/web/dashboard), [Devices](/cli/devices).

Reset gateway mode and 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
```

Related

• Install Overview — all installation methods
• Podman — Podman alternative to Docker
• ClawDock — Docker Compose community setup
• Updating — keeping OpenClaw up to date
• Configuration — gateway configuration after install