How to run OpenClaw with Docker

The official Docker guide treats Docker as optional, not the default install path. If you want a containerized gateway, the recommended flow is from the OpenClaw repo root with ./docker-setup.sh, then a dashboard check and container probe.

Who this is for

• You want a throwaway or isolated gateway environment.
• You prefer Docker Compose over a direct local install.
• You want the official scripted flow instead of writing your own compose stack.

What you need before you start

• Docker Desktop or Docker Engine with Compose v2.
• Enough disk space for image layers and logs.
• Git so you can clone the OpenClaw repo.

Step-by-step setup

Step 1: Clone the official repository

Expected result: you are in the repo root where docker-setup.sh exists.

Step 2: Run the official Docker setup script

The official Docker docs say this script builds the gateway image, runs onboarding, starts the gateway with Docker Compose, generates a gateway token, and writes it into .env.

Step 3: Open the dashboard

Open the local Control UI:

Then paste the token into the Control UI settings if prompted.

Step 4: Reprint a fresh dashboard link when needed

Expected result: the CLI prints the current dashboard URL again without needing to rerun the full setup.

Step 5: Check the running containers

Expected result: the gateway container shows as running.

Verify it worked

1. docker compose ps shows the gateway container as up.
2. The dashboard loads at http://127.0.0.1:18789/.
3. The generated config and workspace appear on the host under ~/.openclaw/ and ~/.openclaw/workspace.

Common problems and fixes

The dashboard says unauthorized or pairing required

Fetch a fresh dashboard link and approve the device from the CLI container:

I need extra host mounts

Set the extra mounts variable before you rerun the setup script:

I need a persistent /home/node

Use the official volume knob and rerun the setup:

FAQ

Do I need Docker for sandboxed tools?

Not necessarily. The Docker guide explicitly says agent sandboxing uses Docker too, but sandboxing does not require the entire gateway to run in Docker.

Can I do the setup manually without docker-setup.sh?

Yes. The docs include a manual compose flow, but the scripted path is the recommended quick start for a containerized gateway.

Where does Docker OpenClaw store config and workspace data?

On the host, under ~/.openclaw/ and ~/.openclaw/workspace, even when the gateway itself runs in containers.

Official sources

• Docker
• Dashboard
• devices CLI