OpenClaw Docker Setup Guide

Run OpenClaw in containers with Docker Compose. You get a clean, repeatable setup that's easy to update, move to another server or throw away and rebuild. This guide covers choosing an image, the official setup script, daily commands, sandboxing and keeping a Docker install secure.

Quick answer

Clone github.com/openclaw/openclaw, set OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest", run ./scripts/docker/setup.sh, then open http://127.0.0.1:18789/.

Is Docker right for you?

Why run OpenClaw in Docker

Good for
  • Servers and VPS hosting
  • Keeping OpenClaw separate from your system
  • One-command updates and easy rollbacks
  • Moving your setup between machines
  • People who already use Docker
Less ideal for
  • Beginners on a personal laptop (use the native installer)
  • iMessage, which needs macOS directly
  • Machines with little RAM if you build images yourself
Before you start

Docker requirements for OpenClaw

Docker
Docker Engine (Linux) or Docker Desktop (Mac, Windows)
Compose
Docker Compose v2 (the docker compose command)
Memory
At least 6 GB RAM to build the image yourself. Smaller machines can use pre-built images.
Other
git, plus an AI model API key
Choose an image

Official OpenClaw Docker images

Defaultghcr.io/openclaw/openclaw:latest

The primary registry, used by OpenClaw's release automation. Start here.

With browserghcr.io/openclaw/openclaw:latest-browser

Bundles Chromium so the browser tool works in the container. The standard image doesn't include it.

Mirroropenclaw/openclaw:latest

Docker Hub mirror of the same image, if GHCR is blocked on your network.

Avoid unofficial mirrors and look-alike image names. Copies using the old Clawdbot and Moltbot names have been used to spread malware.

Make it yours

Build your setup command

Pick your options and copy the result into step 3.

Your setup command
1
Step 1

Install Docker and Compose

On Debian or Ubuntu, the official OpenClaw server guides use Docker's convenience script:

Terminal
sudo apt-get update
sudo apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sh

Check both are ready:

Terminal
docker --version
docker compose version
2
Step 2

Get the OpenClaw setup files

The Compose file and setup script live in the official repository.

Terminal
git clone https://github.com/openclaw/openclaw.git
cd openclaw
3
Step 3

Run the setup script

Choose a pre-built image and run the script. Or paste the command from the builder above.

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

What the script does

  1. Pulls or builds the gateway image you chose
  2. Syncs .env, fixes file permissions and runs onboarding
  3. Asks for your AI provider API keys
  4. Generates a gateway token and writes it to .env
  5. Starts the gateway with Docker Compose

Without OPENCLAW_IMAGE, the script builds the image locally. That's the step that needs 6 GB of RAM.

4
Step 4

Open the Control UI

Get the dashboard link, then open it in your browser:

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

The Control UI runs at http://127.0.0.1:18789/. Your gateway token is saved in the .env file in the openclaw folder. On a remote server, connect through an SSH tunnel first. See the VPS guide.

5
Step 5

Connect a chat app

Run OpenClaw commands through the openclaw-cli container. For example, add a Telegram bot:

Terminal
docker compose run --rm openclaw-cli channels add --channel telegram --token "<bot-token>"

For channels that log in with a QR code or account, such as WhatsApp:

Terminal
docker compose run --rm openclaw-cli channels login

Message your bot, then approve yourself the same way you would outside Docker, prefixed with docker compose run --rm openclaw-cli. Next: build your first workflow.

Architecture

How the OpenClaw containers fit together

openclaw-gateway

The always-running service: chat channels, agents, memory, tools and the Control UI on port 18789.

openclaw-cli

A short-lived container for commands such as pairing, channels and the dashboard link. It's removed after each run with --rm.

Config volume

OPENCLAW_CONFIG_DIR on your host, mounted at /home/node/.openclaw. Holds settings, memory and tokens.

Workspace volume

OPENCLAW_WORKSPACE_DIR on your host, mounted at /home/node/workspace. The agent's working files.

Because your data lives in host folders, you can delete and recreate the containers without losing anything. Back up those two folders, not the containers.

Daily use

OpenClaw Docker command cheat sheet

TaskCommand
Follow logsdocker compose logs -f openclaw-gateway
Restartdocker compose restart openclaw-gateway
Update to the newest imagedocker compose pull openclaw-gateway && docker compose up -d openclaw-gateway
Stop everythingdocker compose down
Start againdocker compose up -d openclaw-gateway
Dashboard linkdocker compose run --rm openclaw-cli dashboard --no-open
Any OpenClaw commanddocker compose run --rm openclaw-cli <command>
Container statusdocker compose ps
Configuration

Key environment variables

VariableWhat it does
OPENCLAW_IMAGEWhich image to use instead of building locally
OPENCLAW_GATEWAY_PORTHost port for the gateway (default 18789)
OPENCLAW_CONFIG_DIRHost folder for config and memory (default ~/.openclaw)
OPENCLAW_WORKSPACE_DIRHost folder for the workspace (default ~/.openclaw/workspace)
OPENCLAW_SANDBOXTurns on sandboxed tool execution
OPENCLAW_DOCKER_SOCKETPath to the Docker socket used by the sandbox
OPENCLAW_BROWSER_HEADLESSBrowser display mode for the browser tool
Advanced

Sandboxing agent tools with Docker

OpenClaw can run risky tools, like shell commands, inside separate throwaway containers. Turn it on with OPENCLAW_SANDBOX and point OPENCLAW_DOCKER_SOCKET at your Docker socket.

The Docker socket is powerful

Access to the Docker socket is effectively root access on the host. The official docs say it needs explicit configuration and a security review. Only enable it on a machine dedicated to OpenClaw.

Using Podman instead of Docker? Set the sandbox backend to "podman" in your OpenClaw config.

Security on servers

Don't expose port 18789

A valid gateway token gives full control of your assistant. On a VPS, keep the Control UI private.

Troubleshooting

Fix common Docker problems

permission denied … docker.sock

Your user can't talk to Docker. Run the commands with sudo, or add yourself to the docker group and log in again.

Build killed / out of memory

Building the image needs about 6 GB of RAM. Set OPENCLAW_IMAGE to a pre-built image instead.

docker-compose: command not found

OpenClaw uses Compose v2. The command is docker compose, with a space. Install the Compose plugin.

port is already allocated

Something else is using 18789. Set OPENCLAW_GATEWAY_PORT to another port and run setup again.

Browser tool not working

The standard image has no browser. Switch to the latest-browser image.

Lost settings after an update

Check OPENCLAW_CONFIG_DIR points at the same host folder as before. Your data lives there, not inside the container.

More fixes: troubleshooting guide.

FAQ

OpenClaw Docker questions

Is there an official OpenClaw Docker image?

Yes. The official image is ghcr.io/openclaw/openclaw, with a latest tag and a latest-browser tag that includes Chromium. Docker Hub has a mirror at openclaw/openclaw.

How much RAM does OpenClaw need in Docker?

Building the image yourself needs at least 6 GB of RAM. Using a pre-built image with OPENCLAW_IMAGE avoids the build and works on smaller machines.

How do I update OpenClaw in Docker?

Run docker compose pull openclaw-gateway, then docker compose up -d openclaw-gateway. Your settings and memory are kept because they live in host folders.

Where is my OpenClaw gateway token in Docker?

The setup script generates a gateway token and writes it to the .env file in your openclaw folder. Keep that file private.

How do I run OpenClaw commands in Docker?

Use the CLI container: docker compose run --rm openclaw-cli followed by the command, for example channels add or dashboard --no-open.

Can I use Podman instead of Docker?

Yes. Podman is supported as an alternative. If you use sandboxing, set the sandbox backend to podman in your OpenClaw config.

Keep reading

Host on a VPS24/7 in the cloud Install on LinuxWithout Docker Security guideLock it down Update & backupKeep your data safe