OpenClaw's official Docker setup runs the Gateway with Docker Compose and provides a companion CLI service. Start with the repository's setup script and supported images so configuration, state mounts, and service networking stay aligned.

Independent guide. Docker workflow checked on October 2, 2026 against the official Docker documentation. Commands are documentation-reviewed, not a claim of a fresh deployment test.

Docker Gateway and tool sandboxing are separate

A containerized Gateway changes how you package and supervise OpenClaw. Tool sandboxing controls where agent tool execution runs. Installing the Gateway in Docker does not by itself create the tool policy or sandbox you want.

OpenClaw is not a Python core engine installed with pip install openclaw. The previous Python Dockerfile and generic YAML configuration on this page have been removed. Use the official images and current setup flow below.

1. Check prerequisites

docker --version
docker compose version

Use Docker Engine or Docker Desktop with Compose v2. The official docs currently call for at least 6 GB RAM for a local source-image build; choosing a pre-built image avoids that build requirement. Runtime needs depend on tools, browser usage, and whether model inference is local.

Have Git and working model-provider access available.

On a VPS, secure inbound access before running setup. The official Compose configuration can publish Gateway ports on all host interfaces, and its container listener defaults to lan. An SSH tunnel does not remove those public listeners. Before startup, configure the cloud security group or provider firewall to allow SSH only from your trusted administration source and deny public inbound access to 18789, 18790, and 3978, plus any custom host ports you select. Check IPv4 and IPv6 rules. Preserve and verify your current SSH access before tightening rules.

Docker-published ports can bypass assumptions about ordinary host firewall rules. Use the provider's network firewall/security group as the initial boundary, then review the documented Docker firewall chain and actual port bindings. For a local computer, review what networks can reach its published ports too.

2. Get the official setup files

git clone https://github.com/openclaw/openclaw.git
cd openclaw

This checkout supplies the Compose files and scripts even when you use a pre-built image. For a production deployment, choose a release and use the matching setup files and image rather than mixing arbitrary revisions.

For a new installation using the official image:

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

The current script is scripts/docker/setup.sh. If following an older release checkout, inspect that release's documentation instead of assuming the script location is unchanged.

GHCR is the primary registry. The official docs also document a Docker Hub mirror at openclaw/openclaw; use a verified release tag when pinning production. latest is convenient for an initial setup but is a moving tag.

3. Complete onboarding

The setup script guides provider setup, prepares the Gateway credential and environment, and starts the Compose Gateway. Keep the generated .env and state private. Do not publish the generated token in a screenshot or Git repository.

Inspect the resulting deployment from the repository directory:

docker compose ps
docker compose logs --tail=100 openclaw-gateway

Look for startup or validation errors. A running container is one check; provider access and a useful agent reply are separate checks.

4. Open the Control UI

For a local installation, use the configured host port, normally http://127.0.0.1:18789/. Authenticate with the credential generated during setup. To obtain the dashboard address again:

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

The official docs explain the distinction between the internal listener port and a custom OPENCLAW_GATEWAY_PORT on the host. If this is a VPS, establish SSH or Tailscale access rather than assuming a local browser can reach the container.

Send one plain text message before adding channels. If the UI loads but the model fails, check provider credentials and usage limits before rebuilding the image.

5. Review ports and persistent state

Read Docker networking and storage alongside your generated Compose configuration. Confirm the host listener, mount paths, and account that owns the files.

Inspect the resulting host-port publication instead of assuming it is private:

docker compose port openclaw-gateway 18789
docker compose port openclaw-gateway 18790
docker compose port openclaw-gateway 3978
docker compose ps -q openclaw-gateway

Some optional ports may not be published by your selected release. Use the container ID from the final command to inspect all actual bindings, replacing CONTAINER_ID:

docker inspect CONTAINER_ID --format '{{json .HostConfig.PortBindings}}'

A host IP of 0.0.0.0 or :: means a port is published on all corresponding host interfaces; it is not loopback-only. Confirm that the provider firewall blocks public access. If you want loopback-only publication, follow the Compose version's replacement semantics and inspect the resulting bindings again. Adding a second 127.0.0.1 port entry in an override file can merge with, rather than replace, the original public entry.

A loopback-only listener inside the Gateway container can prevent other containers or the host-published port from reaching it. Private host access is typically enforced by the host's published-port configuration and access path; do not transplant a native-host bind example into Docker without checking the official networking guide.

Keep state and workspace mounts across container recreation. Back them up outside the host. Deleting volumes to clear a startup error can also delete configuration or conversation state.

6. Health and troubleshooting

curl -fsS http://127.0.0.1:18789/healthz

Use your configured host port. The health endpoint checks liveness; it does not prove the selected provider will answer your next message.

Symptom Inspect first
Container exits at startup Gateway logs and config validation
Dashboard unreachable Published port, host route, and container listener
Permission denied on state Mount ownership for the image's runtime user
Image build killed Build memory and disk; consider an official pre-built image
Dashboard works, no reply Provider setup and quota

The official Compose operations guide covers commands and image maintenance. For installation failures, see our troubleshooting guide.

7. Update without discarding state

Back up first and keep the existing Compose files, overlays, mounts, and environment. After selecting the appropriate official image tag in your deployment, the documented image refresh is:

docker compose pull openclaw-gateway openclaw-cli
docker compose up -d openclaw-gateway

Review release notes and confirm health and a small task afterward. Do not rerun setup with an empty shell environment merely to switch an existing deployment's image; the official docs warn that setup can rewrite .env from current defaults.

FAQ

Is Redis or PostgreSQL required?

Neither is a prerequisite for the basic official Compose installation described here. Add a database only for an integration whose own documentation requires it.

Is my Docker Gateway automatically sandboxed?

Gateway containerization and tool sandboxing are different. Follow the official sandbox guide for tool isolation and review the permissions needed by your task.

How do I use it on a remote server?

Choose a private remote-access route and keep persistent state on the server. Start with our Linux server guide and the Docker networking reference above.