OpenClaw Docker Deployment: A Reproducible Gateway Setup You Can Recover

What this guide helps you finish

By the end of this guide, you should have:

• one reproducible Docker-based OpenClaw gateway,
• state persisted on the host instead of trapped in disposable containers,
• a repeatable way to verify the gateway, token flow, and basic CLI operations,
• a cleaner mental model for what to back up before changes.

Who this is for (and not for)

This guide is for operators who want:

• a contained install,
• easier rebuilds and rollback preparation,
• one gateway host they can reason about without global Node/npm drift.

This is not the best starting point if:

• you mainly want the fastest local developer install,
• you are still deciding between Docker and another deployment model,
• you need a remote access design more than a local deployment path.

Before you run docker-setup.sh: collect these four facts

Before you start, know these four things:

1. Where state should live on the host and how you will back it up.
2. How you will reopen the dashboard token if you need to reconnect after restart.
3. Whether this host will stay local-only or later be reached remotely.
4. Which mounted paths or extra packages are actually required so you do not overcomplicate the first boot.

What this guide gives you

This is a containerized Gateway setup. You get:

• A reproducible install (everything runs in Docker containers)
• A persistent state directory on the host (config, credentials, sessions)
• An easy way to onboard and manage channels using the bundled CLI container

Docker is optional in OpenClaw. Use it if you want isolation or if you are deploying on a host where you do not want global Node/npm installs.

Further reading (official):

• Docker install: https://docs.openclaw.ai/install/docker
• Dashboard access/auth: https://docs.openclaw.ai/web/dashboard

If you want a deeper mental model for openclaw.json (paths, env vars, $include, providers/models), see:

• /guides/openclaw-configuration

Prerequisites

• Docker Desktop (macOS/Windows) or Docker Engine (Linux)
• Docker Compose v2 (docker compose version works)
• A machine with enough disk for images + logs (plan for a few GB)

Recommended: quick start with docker-setup.sh

1. Clone the repo:

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

2. Run the setup script:

./docker-setup.sh

What it does (high level):

• Builds the image
• Runs the onboarding wizard in a CLI container
• Starts the Gateway via Docker Compose
• Generates a Gateway token and writes it to .env

3. Open the Control UI:

• Open: http://127.0.0.1:18789/
• If the UI asks for a token, paste the token printed by the script (or stored in .env)

Persistence and where your data lives

By default, the Docker flow keeps OpenClaw state on the host, not inside the container:

• State dir: ~/.openclaw/
• Workspace dir: ~/.openclaw/workspace

Treat the state dir like production secrets. It contains credentials (OAuth tokens, WhatsApp creds, etc.).

Basic backup:

tar -czf openclaw-backup.tgz ~/.openclaw

Optional: extra mounts, packages, and home volume

These environment variables are the “power user” knobs for Docker installs.

Extra bind mounts (example: mount your Codex home + a work repo):

export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

Install extra apt packages into the image (example: ffmpeg):

export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg"
./docker-setup.sh

Persist the entire container home as a named volume (optional):

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

Channel setup from Docker (examples)

Most channel workflows can be run via the CLI container:

docker compose run --rm openclaw-cli --help

WhatsApp login (QR):

docker compose run --rm openclaw-cli channels login

After changing channel config or creds, restart the gateway container:

docker compose restart openclaw-gateway

Day-2 operations: logs, restart, stop

Check status:

docker compose ps

Follow logs:

docker compose logs -f openclaw-gateway

Stop everything (keeps host state):

docker compose down

Verification: prove the deployment is actually stable

Do not stop at “the dashboard loaded once.”

Verify these before you call the deployment good:

1. docker compose ps shows the expected container state.
2. docker compose logs -f openclaw-gateway does not show immediate restart loops or auth churn.
3. The Control UI opens and accepts the expected token flow.
4. A simple CLI operation works from the CLI container:

docker compose run --rm openclaw-cli openclaw doctor

5. After one restart, the gateway comes back with the same persisted state:

docker compose restart openclaw-gateway

If any of those fail, you do not have a boring Docker baseline yet.

Security notes (important)

• The Control UI is an admin surface. Avoid exposing it directly on the public internet.
• If you must access remotely, prefer Tailscale or SSH tunneling (see the official dashboard doc).
• Keep your Gateway token secret; rotate it if it leaks.

Common issues

• “Unauthorized” in the browser: open the Control UI, then paste the gateway token (Settings -> token).
• Port conflict: something else is using 18789. Stop the conflicting process, or change the port in the Docker env/config and redeploy.
• Permission issues on mounted folders: ensure the mounted paths are shared with Docker Desktop (macOS/Windows) and accessible by the container user.

What to keep stable after it works

Once Docker deployment is healthy, resist the urge to change too many variables at once.

Keep these stable:

• the host state path,
• the auth/bootstrap path you actually use,
• the container restart flow,
• the list of extra mounts and packages,
• the backup habit before upgrades or config surgery.

That is what turns a Docker install from “it boots” into “it is recoverable.”