DEV Community

zac
zac

Posted on • Originally published at remoteopenclaw.com

Run OpenClaw in Docker: Complete Setup Guide

#claude #ai #productivity #tutorial

Originally published on Remote OpenClaw.

How to Run OpenClaw in Docker: Complete Setup Guide (2026)

Marketplace

Free skills and AI personas for OpenClaw — browse the marketplace.

Browse the Marketplace →

Join the Community

Join 1k+ OpenClaw operators sharing deployment guides, security configs, and workflow automations.

Join the Community →

Why Should You Run OpenClaw in Docker?

Running OpenClaw in Docker gives you dependency isolation, consistent environments across operating systems, persistent storage, security boundaries with non-root execution, easy updates, and production-ready health checks and logging.

  • Dependency isolation — all 70+ dependencies managed automatically
  • Consistent environment — same setup on Ubuntu, macOS, or Windows
  • Persistent storage — configuration and workspace survive container restarts
  • Security boundaries — the agent runs as a non-root user with limited host access
  • Easy updates — pull new images without reinstalling anything
  • Production-ready — health checks, logging, and monitoring built in

What Do You Need Before Starting?

You need Docker Desktop or Engine (latest stable), Docker Compose v2+, at least 2 GB RAM (4 GB recommended), 10 GB disk space, Git, Bash v4+, and at least one AI provider API key.

Requirement

Minimum

Recommended

Docker Desktop or Engine

Latest stable

Latest stable

Docker Compose

v2+

v2+

RAM

2 GB

4 GB

Disk space

10 GB

20 GB+

Git

Any version

Latest

Bash

v4+ (upgrade on macOS: brew install bash)

v4+

API key

At least one AI provider

Anthropic recommended

Verify your setup:

docker --version
docker compose version
git --version
Enter fullscreen mode Exit fullscreen mode

VPS Sizing by Use Case

Use Case

vCores

RAM

Disk

Digital assistant

4

4 GB

120 GB

Workflow automation

6

8 GB

240 GB

Developer productivity

8

16 GB

480 GB

How Do You Clone the OpenClaw Repository?

Clone the official OpenClaw GitHub repository and navigate into the project directory — this gives you the Docker Compose configuration, setup scripts, and all required files.

git clone https://github.com/openclaw/openclaw.git
cd openclaw
Enter fullscreen mode Exit fullscreen mode

How Do You Run the OpenClaw Docker Setup Script?

The setup script builds the Docker image, runs an interactive onboarding wizard, prompts for your API key, generates authentication tokens, creates configuration directories, and starts the gateway via Docker Compose.

chmod +x docker-setup.sh
./docker-setup.sh
Enter fullscreen mode Exit fullscreen mode

Using a Pre-Built Image (Faster)

Skip the local build by specifying a remote image:

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh
Enter fullscreen mode Exit fullscreen mode

Pre-built images are available from GitHub Container Registry with tags: latest (most recent stable release), main (latest from main branch), and version-specific (e.g., 2026.2.26).

How Do You Verify OpenClaw Docker Is Running?

Run docker compose ps to confirm the gateway container is running, then check health endpoints at localhost:18789 for liveness and readiness without authentication.

docker compose ps
Enter fullscreen mode Exit fullscreen mode

You should see openclaw-openclaw-gateway-1 running. Check the logs:

docker compose logs -f openclaw-gateway
Enter fullscreen mode Exit fullscreen mode

Health Checks 

# Liveness check
curl -fsS http://127.0.0.1:18789/healthz

# Readiness check
curl -fsS http://127.0.0.1:18789/readyz
Enter fullscreen mode Exit fullscreen mode

How Do You Access the OpenClaw Web Dashboard?

Navigate to http://127.0.0.1:18789 in your browser to access OpenClaw's web-based control panel for chatting with your agent, configuring channels, and managing skills.

If you see a pairing or authentication prompt, retrieve your dashboard link:

docker compose run --rm openclaw-cli dashboard --no-open
Enter fullscreen mode Exit fullscreen mode

If device approval is needed:

docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>
Enter fullscreen mode Exit fullscreen mode

Marketplace

Free skills and AI personas for OpenClaw — browse the marketplace.

Browse the Marketplace →

How Do You Connect WhatsApp, Telegram, Discord, and Slack?

Each messaging channel connects through CLI commands after the gateway is running — WhatsApp via QR code scan, Telegram via BotFather token, and Discord and Slack via bot tokens with pairing approval.

WhatsApp (QR Code) 

docker compose run --rm openclaw-cli channels login
Enter fullscreen mode Exit fullscreen mode

Scan the QR code with your WhatsApp app to connect.

Telegram

  1. Create a bot with @BotFather on Telegram
  2. Copy the bot token
  3. Add the channel: 
docker compose run --rm openclaw-cli channels add \
 --channel telegram \
 --token <YOUR_BOT_TOKEN>
Enter fullscreen mode Exit fullscreen mode
  1. Send a message to your bot, then approve the pairing: 
docker compose run --rm openclaw-cli pairing approve telegram <CODE>
Enter fullscreen mode Exit fullscreen mode

Discord 

docker compose run --rm openclaw-cli channels add \
 --channel discord \
 --token <DISCORD_BOT_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Slack 

docker compose run --rm openclaw-cli channels add \
 --channel slack \
 --token <SLACK_BOT_TOKEN>
Enter fullscreen mode Exit fullscreen mode

What Environment Variables Does OpenClaw Docker Support?

OpenClaw Docker supports environment variables for image selection, API keys (Anthropic, OpenAI, Google, Groq), gateway tokens, extra apt packages, bind mounts, sandbox mode, and network binding configuration.

Variable

Purpose

Example

OPENCLAW_IMAGE

Use a remote image instead of building locally

ghcr.io/openclaw/openclaw:latest

ANTHROPIC_API_KEY

Anthropic API key for Claude models

sk-ant-...

OPENAI_API_KEY

OpenAI API key

sk-...

GOOGLE_API_KEY

Google API key for Gemini

AIza...

GROQ_API_KEY

Groq API key

gsk_...

GATEWAY_TOKEN

Authentication token for dashboard access

Auto-generated

OPENCLAW_DOCKER_APT_PACKAGES

Extra apt packages to install in the image

ffmpeg imagemagick

OPENCLAW_SANDBOX

Enable agent sandbox mode

1, true, yes, on

OPENCLAW_GATEWAY_BIND

Network binding mode

lan, loopback, tailnet

How Does OpenClaw Docker Handle Storage and Persistence?

Docker Compose bind-mounts two critical directories — ~/.openclaw/ for configuration and agent state, and ~/.openclaw/workspace/ for agent-accessible files — both persisting across container restarts and rebuilds.

Container Path

Host Path

Contents

/home/node/.openclaw

~/.openclaw/

Configuration, API keys, agent state, sessions

/home/node/.openclaw/workspace

~/.openclaw/workspace/

Agent-accessible files, generated outputs

How Do You Update OpenClaw Docker?

Update by pulling the latest code and images, then restarting — your configuration and workspace persist in the mounted volumes.

cd ~/openclaw
git pull
docker compose pull
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

How Do You Troubleshoot Common OpenClaw Docker Issues?

The most common Docker issues are out-of-memory crashes (exit code 137), permission errors from UID mismatch, gateway binding misconfigurations, and stale pairing tokens — each with straightforward fixes.

Container Won't Start (Exit Code 137)

Cause: Out of memory. The image build requires at least 2 GB RAM.

Fix: Increase Docker memory allocation in Docker Desktop > Settings > Resources > Memory.

Permission Errors

Cause: OpenClaw runs as node user (UID 1000), not root. Host-mounted directories may have wrong ownership.

sudo chown -R 1000:1000 ~/.openclaw
Enter fullscreen mode Exit fullscreen mode

Gateway Not Accessible 

docker compose run --rm openclaw-cli config set gateway.mode local
docker compose run --rm openclaw-cli config set gateway.bind lan
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Dashboard Pairing Errors 

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices approve <requestId>
Enter fullscreen mode Exit fullscreen mode

Missing Sandbox Image 

./scripts/sandbox-setup.sh
Enter fullscreen mode Exit fullscreen mode

Frequently Asked Questions

Can I run OpenClaw Docker on a Raspberry Pi?

OpenClaw requires at least 2 GB RAM and the Docker image is built for amd64 and arm64. A Raspberry Pi 4 with 4 GB RAM can run it, though performance will be limited.

Do I need Docker Desktop or can I use Docker Engine?

Either works. Docker Desktop provides a GUI and is easier on macOS/Windows. Docker Engine (CLI-only) is sufficient for Linux servers.

Can I use multiple AI providers simultaneously?

Yes. Set multiple API key environment variables and configure which model each agent uses in your openclaw.json.

How do I back up my OpenClaw data?

Back up the ~/.openclaw/ directory. This contains all configuration, API keys, agent state, session history, and workspace files.

Is the Docker image updated automatically?

No. You need to manually pull updates with docker compose pull && docker compose up -d. Consider setting up a cron job or Watchtower for automatic updates.

Can I run multiple OpenClaw instances on one server?

Yes, but each instance needs unique port mappings and separate configuration directories. Adjust the docker-compose.yml ports and volume mounts accordingly.

Top comments (0)