guide2026-03-17

OpenClaw Docker Setup Guide: Step-by-Step (2026)

OpenClaw Docker Setup: What You're Getting Into

Self-hosting OpenClaw with Docker is the most popular approach for developers who want full control. This guide covers the complete setup process step-by-step, including common errors and how to fix them. It also covers when you should skip Docker entirely and use a managed service instead.

Prerequisites before you start:

  • A Linux server (Ubuntu 22.04 or 24.04 recommended) with at least 2 GB RAM
  • SSH access to the server
  • A domain name or public IP for webhook configuration
  • A Telegram Bot Token (from @BotFather) or WhatsApp pairing access
  • An AI API key: OpenAI, Anthropic Claude, or Google Gemini

If you don't have a server, DigitalOcean's 2 GB Droplet at $14/month is a reliable choice. Hetzner offers similar specs for less in Europe.

Step 1: Install Docker

Connect to your server via SSH and install Docker using the official repository (the apt package is outdated):

# Remove any old Docker versions
sudo apt remove docker docker-engine docker.io containerd runc

# Install Docker's official repository
sudo apt update
sudo apt install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to the docker group (avoid using sudo for every docker command)
sudo usermod -aG docker $USER
newgrp docker

Verify Docker is working:

docker --version
docker compose version

Step 2: Clone the OpenClaw Repository

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

Check the latest stable release tag and checkout it:

git fetch --tags
git checkout $(git describe --tags $(git rev-list --tags --max-count=1))

Step 3: Configure Environment Variables

OpenClaw uses a .env file for all configuration. Copy the example:

cp .env.example .env
nano .env

Key variables to configure:

# AI Provider (choose one)
OPENAI_API_KEY=sk-your-openai-key-here
# OR
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here
# OR
GOOGLE_AI_API_KEY=your-gemini-key-here

# Default AI model
DEFAULT_MODEL=claude-3-5-sonnet-20241022
# OR: gpt-4o, gemini-2.0-flash-exp

# Telegram (if using Telegram)
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

# WhatsApp (if using WhatsApp)
WHATSAPP_ENABLED=true

# Security
JWT_SECRET=generate-a-random-string-here
ADMIN_PASSWORD=your-admin-password

# Domain (for webhooks and SSL)
DOMAIN=yourdomain.com

Generate a random JWT secret:

openssl rand -base64 32

Step 4: Configure SSL with Nginx

OpenClaw needs HTTPS for Telegram webhooks. The easiest approach is to use the built-in Nginx + Certbot configuration:

# Install Certbot
sudo apt install certbot python3-certbot-nginx

# Get a certificate (replace with your domain)
sudo certbot --nginx -d yourdomain.com

# Verify auto-renewal
sudo certbot renew --dry-run

Update your .env with the SSL certificate paths if needed, or use the docker-compose configuration that mounts the Let's Encrypt certificates automatically.

Step 5: Start OpenClaw

docker compose up -d

This starts all containers in the background. Watch the logs to see if everything starts correctly:

docker compose logs -f

Wait for output like:

openclaw-core  | [OpenClaw] Telegram connector initialized
openclaw-core  | [OpenClaw] Listening on port 3000
openclaw-core  | [OpenClaw] Bot @your_bot_username is ready

Common Errors and Fixes

Error: "Cannot find module" or npm install failures

This usually means the Docker build failed. Try rebuilding:

docker compose build --no-cache
docker compose up -d

Error: "ECONNREFUSED" to AI API

Your API key is wrong or not being read. Double-check your .env file has no trailing spaces and the key format is correct. Run docker compose config to see the resolved configuration.

Error: Telegram webhook failed to set

Your domain is not publicly accessible or SSL is not configured. Verify your domain resolves to your server's IP and SSL is working:

curl -v https://yourdomain.com/health

Error: WhatsApp QR code not appearing

WhatsApp needs a persistent session storage. Check that the ./data volume is properly mounted in your docker-compose.yml and the container has write permissions.

Error: Container exits with OOM (Out of Memory)

Your server has insufficient RAM. OpenClaw needs at least 512 MB for the core process, plus the AI provider workers. Upgrade to a 2 GB server minimum.

Step 6: Test Your Bot

For Telegram: open your bot in the Telegram app and send "Hello". You should get a response within 5 seconds.

For WhatsApp: look for the QR code in the OpenClaw web dashboard (usually at http://localhost:3000 or your domain). Scan it with your phone.

Step 7: Set Up Automatic Restarts and Monitoring

Ensure your containers restart on server reboot:

# Already configured in docker-compose.yml with restart: unless-stopped
# But verify your Docker service starts on boot:
sudo systemctl enable docker
sudo systemctl start docker

Set up basic monitoring with a simple uptime check:

# Add to crontab (check every 5 minutes, restart if down)
crontab -e

# Add this line:
*/5 * * * * docker inspect openclaw-core --format='{{.State.Status}}' | grep -v running && docker compose -f /path/to/openclaw/docker-compose.yml up -d

Keeping OpenClaw Updated

OpenClaw releases updates frequently. To update:

cd openclaw
git fetch --tags
git checkout $(git describe --tags $(git rev-list --tags --max-count=1))
docker compose down
docker compose build --no-cache
docker compose up -d

Test your bot after each update to ensure nothing broke.

Estimated Total Time

If you've followed this guide step by step on a fresh server:

  • Docker install: 10 minutes
  • Repository setup: 5 minutes
  • Configuration: 20-45 minutes (first time)
  • SSL setup: 15-30 minutes
  • Troubleshooting: 30 minutes to 3 hours (varies)
  • Total: 1.5 to 5 hours

For experienced Linux admins, closer to 1.5-2 hours. For first-timers, budget 4-5 hours and expect to Google several errors.

The No-Docker Alternative: ClawMates

If you got through this guide and thought "I just want my AI assistant to work without all this" — that's completely valid. ClawMates is the managed alternative that handles everything in this guide automatically.

What ClawMates replaces:

  • All of the Docker configuration above
  • SSL certificate management
  • Nginx reverse proxy setup
  • Monitoring and automatic restarts
  • OpenClaw version updates
  • Server security hardening

What you do instead:

  1. Go to clawmates.net/setup
  2. Paste your bot token
  3. Choose AI model
  4. Click deploy

Your bot is live in 30 seconds. No server, no Docker, no SSL, no 3 AM debugging sessions.

Plans start at $9.99/month with AI API access included. For users who tried self-hosting and found the maintenance burden too high, ClawMates is the natural next step. Read the self-hosted vs managed comparison for a full cost analysis.

Ready to try it?

Try ClawMates free for 7 days. Set up your AI assistant in 5 minutes.

Start Free Trial