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:
- Go to clawmates.net/setup
- Paste your bot token
- Choose AI model
- 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.