OpenClaw on Docker

Learn how to run OpenClaw on Docker in a separate environment, manage your AI agent more safely, and avoid common setup problems.

Deploy OpenClaw Now

What Is OpenClaw on Docker?

OpenClaw is an open-source AI agent framework that helps you build an AI assistant that can actually perform tasks, not just reply with text. It can connect with tools, apps, messaging channels, workflows, and automations for tasks like customer support, reminders, research, developer work, and business operations.

Docker is a platform that runs software inside containers. A container packages the app with the files and dependencies it needs, so the setup is cleaner and more consistent across different machines, servers, or cloud platforms.

OpenClaw on Docker means running OpenClaw inside a Docker container instead of installing everything directly on your system. This helps keep the OpenClaw setup separate, easier to manage, and easier to move from local testing to a VPS or cloud server.

Docker Requirements to Run OpenClaw

Before running OpenClaw on Docker, make sure your system has the basic requirements. Otherwise, Docker will fail and pretend the problem is “technical,” when really the machine is.

Docker Desktop or Docker Engine

You need Docker installed on your system. Docker Desktop is common for Windows and macOS. Docker Engine is common for Linux servers.

Docker Compose v2

OpenClaw’s Docker setup uses Docker Compose, so you need Compose v2 installed.

At least 2 GB RAM

OpenClaw needs at least 2 GB RAM for the image build. On a 1 GB server, the build can fail with an out-of-memory error, often shown as exit 137. For smoother setup, 4 GB RAM or more is better.

Enough disk space

Docker needs storage for images, containers, logs, OpenClaw config, workspace files, and plugin data.

Terminal access

You need a terminal to run Docker commands, start the setup script, check containers, and manage the OpenClaw gateway.

Model provider access

During setup, OpenClaw may ask for API keys or login details for providers like OpenAI, Anthropic, Gemini, Ollama, or LM Studio.

Docker Setup : Run OpenClaw on Docker

Follow this process to run OpenClaw on Docker using the official Docker setup flow.

Install Docker

First, install Docker on your system.

For macOS

Use Docker Desktop for Mac.

Go to the official Docker Desktop for Mac page :-

Download the correct version:

Apple Silicon if your Mac uses M1, M2, M3, or M4
Intel chip if your Mac is older Intel-based

Open the downloaded .dmg file.
Drag Docker.app into the Applications folder.
Open Docker from Applications.
Open Docker and wait until it starts.

For Windows

Open Docker’s official Windows install page :-

Download Docker Desktop for Windows.
Run the installer.
Keep WSL 2 backend enabled if the installer asks.
Restart your computer if needed.
Open Docker Desktop and wait until it starts.

For Ubuntu or Linux VPS

Use Docker Engine.

Open Docker’s official Ubuntu install guide :-

For Ubuntu/Debian, after Docker’s repository is set up, install Docker Compose plugin with:

sudo apt-get update
sudo apt-get install docker-compose-plugin

Check Docker and Compose

Open terminal and run:

docker --version
docker compose version

You should see version numbers.

Then run a small Docker test:

docker run hello-world

If this works, Docker is ready.

Clone the OpenClaw Repo

Run:

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

Run the Docker Setup Script

From the OpenClaw repo folder, run:

./scripts/docker/setup.sh

This is the official Docker setup command. It builds the gateway image locally and starts the setup flow.

Use Pre-Built Image Optional

To avoid building the image locally, use the pre-built image from GitHub Container Registry:

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

Complete OpenClaw Onboarding

The setup script runs onboarding automatically.

During onboarding, OpenClaw may ask for:

Model provider API keys
Gateway setup details
Basic configuration
Optional channel setup

The setup script also creates a gateway token and writes it to .env. You need this token to access the Control UI.

Open the Control UI

After setup, open:

http://127.0.0.1:18789/

Paste the gateway token or shared secret when asked.

If you need the dashboard URL again, run:

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

Connect Messaging Channels Optional

You can connect OpenClaw to messaging apps.

# WhatsApp QR login
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>"

OpenClaw’s Docker docs list WhatsApp, Telegram, and Discord channel setup examples.

Check OpenClaw Is Running

Check containers:

docker ps

Check gateway health:

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

OpenClaw Docker includes health endpoints for liveness and readiness checks.

Know Where Data Is Stored

OpenClaw Docker stores important data in mounted folders.

Main paths:

OPENCLAW_CONFIG_DIR → /home/node/.openclaw
OPENCLAW_WORKSPACE_DIR → /home/node/.openclaw/workspace

The config folder stores openclaw.json, auth profiles, and .env secrets such as OPENCLAW_GATEWAY_TOKEN. Plugin data also stays under the mounted OpenClaw home folder.

Where OpenClaw Docker Stores Your Data

When you run OpenClaw on Docker, important data is stored in mounted folders on your host machine. This helps your setup survive container restarts or replacement.

1. Config Folder

The config folder stores OpenClaw setup and account-related files.

It includes:

OpenClaw settings
Gateway settings
Agent settings
Provider login or API key details
.env runtime secrets
Gateway token

Official container path:

/home/node/.openclaw

Host path example:

~/.openclaw

2. Workspace Folder

The workspace folder stores files your OpenClaw agent can use or create.

It may include:

Uploaded files
Generated files
Task files
Agent working files
Files created during automation

Official container path:

/home/node/.openclaw/workspace

Host path example:

~/.openclaw/workspace

3. .env File

The .env file stores runtime values used by OpenClaw.

Example:

OPENCLAW_GATEWAY_TOKEN=your_gateway_token

Treat this file like a password file. Do not upload it to GitHub, share it in screenshots, or paste it into public chats.

4. Auth Profiles

OpenClaw stores saved provider login or API key details in agent auth profiles.

Example path:

agents/<agentId>/agent/auth-profiles.json

This helps OpenClaw remember model provider access after restart.

5. Plugin Data

Installed plugins store their package data inside the mounted OpenClaw home folder. This means plugins should stay available after container replacement if the mount is configured correctly.

6. Logs and Growing Files

OpenClaw can create logs and runtime files over time.

Watch these areas:

media/
Session .jsonl files
cron/runs/*.jsonl
installed plugin folders
/tmp/openclaw/

These files can grow over time, so check disk space regularly.

7. Permission Note

The OpenClaw Docker image runs as the node user with UID 1000. If you get permission errors, make sure your mounted folders are owned by UID 1000.

Example:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

When People Use Docker for OpenClaw

1. Test OpenClaw Safely

Use Docker when you want to test OpenClaw without installing everything directly on your main computer.

2. Run Multiple OpenClaw Setups

Use Docker when you need separate setups, such as one for daily use and one for testing plugins, updates, or client work.

3. Deploy OpenClaw on a VPS

Use Docker when you want to run OpenClaw on a cloud server with a cleaner and easier-to-manage setup.

4. VPS or Cloud Hosting

Use Docker when you want to run OpenClaw on a VPS or cloud server as a persistent remote assistant.

5. Plugin and Version Testing

Use Docker when you want to test new OpenClaw versions, plugins, or workflows without breaking your main setup.

6. Test New OpenClaw Versions

Use Docker when you want to try a new OpenClaw version without changing your main install.

Common OpenClaw Docker Problems and Fixes

Problem	Simple Fix
Docker Compose command not working	Install or update Docker Compose v2. Check with docker compose version.
Build fails or shows exit 137	Use at least 2 GB RAM. For better performance, use 4 GB RAM or more.
Control UI asks for token	Use the gateway token created during setup. Check the .env file.
Lost Control UI link	Run docker compose run --rm openclaw-cli dashboard --no-open.
Pairing required error	List devices and approve the pending request with the OpenClaw CLI.
Port already in use	Check if another app is using port 18789. Stop it or change the port.
Permission denied / EACCES	Fix folder permissions. Mounted folders may need ownership for user ID 1000.
Container shows unhealthy	Check /healthz, /readyz, and container logs.
Ollama not reachable	Use host.docker.internal:11434 instead of 127.0.0.1:11434.
LM Studio not reachable	Use host.docker.internal:1234 instead of 127.0.0.1:1234.

Frequently Asked Questions

1. Does OpenClaw need Docker?

No. OpenClaw does not need Docker. Docker is optional. Use it if you want a cleaner, separate setup for testing, VPS hosting, or multiple OpenClaw setups.

2. Should I run OpenClaw in Docker?

Run OpenClaw in Docker if you want better separation from your main system, easier VPS deployment, or a setup you can repeat on another machine.

3. Can I run OpenClaw without Docker?

Yes. You can run OpenClaw without Docker using the normal install flow. Docker is mainly useful when you want a containerized setup.

4. How do I run OpenClaw on Docker?

Install Docker and Docker Compose v2, then run the OpenClaw Docker setup script from the OpenClaw repo. The setup will start the gateway and create the needed token.

5. Why is OpenClaw Docker not working?

Common reasons include old Docker Compose, low RAM, port 18789 already in use, wrong gateway token, permission issues, or missing mounted folders.

6. Can I run multiple OpenClaw setups with Docker?

Yes. Docker is useful if you want separate OpenClaw setups, such as one for daily use and another for testing plugins, updates, or client workflows.

7. Can I run OpenClaw Docker on a VPS?

Yes. Docker is a common way to run OpenClaw on a VPS or cloud server. Just make sure you set up storage, firewall rules, gateway access, and security properly.

Want to Run OpenClaw Without Docker Setup?

Run OpenClaw without Docker setup or server maintenance. Use Ampere.sh for an easier way to launch your OpenClaw agent in 60 seconds.

Deploy OpenClaw Now