What You Will Achieve

By following this guide, you will run OpenClaw inside a Docker container. This is a clean way to use OpenClaw without installing lots of software directly on your computer. The process takes about 20-30 minutes.

Why Use Docker?

Docker is a good choice if you:

• Want to keep your computer's main system clean
• Plan to run OpenClaw on a server
• Want an easy way to completely remove OpenClaw later
• Already use Docker for other projects

Docker is NOT the best choice if you:

• Have never used a terminal before
• Have a very old or slow computer (Docker uses extra resources)
• Just want to try OpenClaw quickly

Before You Start

You need Docker installed on your computer. If you do not have Docker yet, follow these steps first.

Check If Docker Is Already Installed

Open a terminal and type:

docker --version

If you see a version number, Docker is installed and you can skip to the "Clone the OpenClaw Repository" section.

If you see "command not found", you need to install Docker first.

Install Docker on Ubuntu/Debian Linux

sudo apt update

sudo apt install -y docker.io docker-compose

sudo systemctl start docker
sudo systemctl enable docker

sudo usermod -aG docker $USER

docker run hello-world

Install Docker on Windows

For Windows, we recommend using Docker Desktop:

1. Go to docker.com
2. Download Docker Desktop for Windows
3. Run the installer and follow the prompts
4. Restart your computer when asked
5. Open Docker Desktop and wait for it to start

Install Docker on macOS

For macOS, we also recommend Docker Desktop:

1. Go to docker.com
2. Download Docker Desktop for Mac
3. Open the downloaded file and drag Docker to Applications
4. Open Docker from Applications and wait for it to start

Clone the OpenClaw Repository

OpenClaw Docker images are built locally from source code. First, you need to download the source code.

sudo apt install -y git

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

Build and Start OpenClaw

OpenClaw provides a setup script that handles everything automatically.

./docker-setup.sh

docker compose ps

Manual Setup (Alternative)

If the setup script does not work, you can run each step manually:

docker build -t openclaw:local -f Dockerfile .

docker compose run --rm openclaw-cli onboard

docker compose up -d openclaw-gateway

Access the Dashboard

Open your web browser and go to:

http://127.0.0.1:18789/

You should see the OpenClaw dashboard. From here you can:

• See the status of your connections
• View message logs
• Change settings

Docker Image Reference

OpenClaw uses several Docker images:

• openclaw:local - The main Gateway image (built locally)
• openclaw-sandbox:bookworm-slim - Default sandbox for code execution
• openclaw-sandbox-common:bookworm-slim - Sandbox with common development tools
• openclaw-sandbox-browser:bookworm-slim - Sandbox with browser automation support

Build Sandbox Images (Optional)

If you need sandbox functionality, build the sandbox images:

Default sandbox
scripts/sandbox-setup.sh
Common tools sandbox
scripts/sandbox-common-setup.sh
Browser sandbox
scripts/sandbox-browser-setup.sh

Useful Docker Commands

Here are commands you will use often:

Start OpenClaw

cd ~/openclaw
docker compose up -d openclaw-gateway

Stop OpenClaw

cd ~/openclaw
docker compose down

Restart OpenClaw

cd ~/openclaw
docker compose restart

View logs

cd ~/openclaw
docker compose logs -f

Press Ctrl + C to stop watching logs.

Update to the latest version

cd ~/openclaw
git pull
docker build -t openclaw:local -f Dockerfile .
docker compose up -d openclaw-gateway

Run OpenClaw commands

To run any openclaw command inside the container:

docker compose run --rm openclaw-cli status

Health check

docker compose exec openclaw-gateway node dist/index.js health

Environment Variables

You can customize the Docker setup with environment variables:

• OPENCLAW_DOCKER_APT_PACKAGES - Additional apt packages to install during build (space-separated)
• OPENCLAW_EXTRA_MOUNTS - Additional host directories to mount (comma-separated)
• OPENCLAW_HOME_VOLUME - Named volume for persisting home directory

Example: Extra Mounts

OPENCLAW_EXTRA_MOUNTS="$HOME/.config:/home/node/.config:ro" ./docker-setup.sh

Example: Persistent Home Volume

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

Common Problems and Solutions

"Cannot connect to the Docker daemon"

This means Docker is not running.

Solution for Linux:

sudo systemctl start docker

Solution for Windows/Mac:

Open Docker Desktop and wait for it to start.

"Permission denied" when running docker commands

Solution:

Either use sudo before docker commands, or add your user to the docker group:

sudo usermod -aG docker $USER

Then log out and log back in.

Port 18789 is already in use

Another program is using port 18789.

Solution:

Edit the docker-compose.yml file to use a different port. For example, to use port 18790:

Find the ports section and change it to:

ports:

"18790:18789"

Then restart: docker compose down && docker compose up -d

Access the dashboard at http://127.0.0.1:18790/ instead.

Build fails with "out of memory"

Docker needs enough memory to build the image.

Solution:

• On Docker Desktop: Go to Settings, then Resources, and increase Memory to at least 4GB
• On Linux: Make sure you have at least 4GB of available RAM

Container keeps restarting

Check the logs to see what is wrong:

docker compose logs

Common causes:

• Missing or invalid API key
• Configuration file errors

How do I completely remove OpenClaw?

cd ~/openclaw
docker compose down
docker rmi openclaw:local
cd ~
rm -rf ~/openclaw

Keeping OpenClaw Safe

• Local-only by default: The default configuration only allows access from your computer (127.0.0.1). Other devices on your network cannot access it.

• Do not expose to the internet: Never change the port binding to 0.0.0.0:18789:18789 unless you know what you are doing. This would make OpenClaw accessible from anywhere.

• Keep Docker updated: Regularly update Docker to get security patches.

• Update OpenClaw regularly: Pull the latest code and rebuild:

cd ~/openclaw
git pull
docker build -t openclaw:local -f Dockerfile .
docker compose up -d

What To Do Next

Now that OpenClaw is running, you are ready to connect it to your chat apps:

1. Connect to Telegram - Send AI messages through Telegram
2. Connect to WhatsApp - Use AI through WhatsApp
3. Connect to Discord - Add AI to your Discord server
4. Your First Agent - Learn how to configure agents

Last updated: February 3, 2026 | Found an error? Contact us