Use this file to discover all available pages before exploring further.

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 (
text
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
text
DOCKER-USER
firewall policy.

Containerized gateway

Build the image

From the repo root, run the setup script:


text
```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`).

Complete onboarding

The setup script runs onboarding automatically. It will:


text
* 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 the Control UI

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.


text
Need the URL again?

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

Configure channels (optional)

Use the CLI container to add messaging channels:


text
```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:


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

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

note

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

text

OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro

. That mounted source directory overrides the matching compiled

text

/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:


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

The official OpenClaw Docker release image includes the bundled

text

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

text

diagnostics-otel

plugin in config, then set

text

diagnostics.otel.enabled=true

or use the config example in OpenTelemetry export. Collector auth headers are configured through

text

diagnostics.otel.headers

, not through Docker environment variables.

Prometheus metrics use the already-published Gateway port. Enable the

text

diagnostics-prometheus

plugin, then scrape:


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

The route is protected by Gateway authentication. Do not expose a separate public

text

/metrics

port or unauthenticated reverse-proxy path. See Prometheus metrics.

Health checks

Container probe endpoints (no auth required):


bash
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

text

HEALTHCHECK

that pings

text

/healthz

. If checks keep failing, Docker marks the container as

text

unhealthy

and orchestration systems can restart or replace it.

Authenticated deep health snapshot:


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

LAN vs loopback

text

scripts/docker/setup.sh

defaults

text

OPENCLAW_GATEWAY_BIND=lan

so host access to

text

http://127.0.0.1:18789

works with Docker port publishing.

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

note

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

Host Local Providers

When OpenClaw runs in Docker,

text

127.0.0.1

inside the container is the container itself, not your host machine. Use

text

host.docker.internal

for AI providers that run on the host:

Provider	Host default URL	Docker setup URL
LM Studio	text `http://127.0.0.1:1234`	text `http://host.docker.internal:1234`
Ollama	text `http://127.0.0.1:11434`	text `http://host.docker.internal:11434`

The bundled Docker setup uses those host URLs as the LM Studio and Ollama onboarding defaults, and

text

docker-compose.yml

maps

text

host.docker.internal

to Docker's host gateway for Linux Docker Engine. Docker Desktop already provides the same hostname on macOS and Windows.

Host services must also listen on an address reachable from Docker:


bash
lms server start --port 1234 --bind 0.0.0.0
OLLAMA_HOST=0.0.0.0:11434 ollama serve

If you use your own Compose file or

text

docker run

command, add the same host mapping yourself, for example

text

--add-host=host.docker.internal:host-gateway

Bonjour / mDNS

Docker bridge networking usually does not forward Bonjour/mDNS multicast (

text

224.0.0.251:5353

) reliably. The bundled Compose setup therefore defaults

text

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

text

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

text

OPENCLAW_CONFIG_DIR

text

/home/node/.openclaw

and

text

OPENCLAW_WORKSPACE_DIR

text

/home/node/.openclaw/workspace

, so those paths survive container replacement. When either variable is unset, the bundled

text

docker-compose.yml

falls back to

text

${HOME}/.openclaw

(and

text

${HOME}/.openclaw/workspace

for the workspace mount), or

text

/tmp/.openclaw

when

text

HOME

itself is also missing. That keeps

text

docker compose up

from emitting an empty-source volume spec on bare environments.

That mounted config directory is where OpenClaw keeps:

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

Bundled plugin runtime dependencies and mirrored runtime files are generated state, not user config. Compose stores them in the named Docker volume

text

openclaw-plugin-runtime-deps

mounted at

text

/var/lib/openclaw/plugin-runtime-deps

. Keeping that high-churn tree out of the host config bind mount avoids slow Docker Desktop/WSL file operations and stale Windows handles during cold Gateway startup.

The default Compose file sets

text

OPENCLAW_PLUGIN_STAGE_DIR

to that path for both

text

openclaw-gateway

and

text

openclaw-cli

, so

text

openclaw doctor --fix

, channel login/setup commands, and Gateway startup all use the same generated runtime volume.

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

Disk growth hotspots: watch

text

media/

, session JSONL files,

text

cron/runs/*.jsonl

, the

text

openclaw-plugin-runtime-deps

Docker volume, and rolling file logs under

text

/tmp/openclaw/

Shell helpers (optional)

For easier day-to-day Docker management, install

text

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

If you installed ClawDock from the older

text

scripts/shell-helpers/clawdock-helpers.sh

raw path, rerun the install command above so your local helper file tracks the new location.

Then use

text

clawdock-start

text

clawdock-stop

text

clawdock-dashboard

, etc. Run

text

clawdock-help

for all commands. See ClawDock for the full helper guide.

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

text

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

text

/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


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

Build the default sandbox image:


bash
scripts/sandbox-setup.sh

Troubleshooting

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

OpenClaw Docs

Docker

Is Docker right for me?

Prerequisites

Containerized gateway

Build the image

Complete onboarding

Open the Control UI

Configure channels (optional)

Manual flow

note

note

Environment variables

Observability

Health checks

LAN vs loopback

note

Host Local Providers

Bonjour / mDNS

Storage and persistence

Shell helpers (optional)

Running on a VPS?

Agent sandbox

Quick enable

Troubleshooting

Related