OpenClaw Docker Setup: From Zero to Running AI Assistant in 30 Minutes

OpenClaw is the fastest-growing open-source AI agent framework on GitHub, and the Docker installation is the recommended path for most users. This guide covers exactly what works in 2026 — the tested commands, the real gotchas, and the complete path from a blank server to a running AI assistant with Telegram connected.

Why Docker for OpenClaw?

Docker isolates OpenClaw from your system environment. No dependency conflicts, no version conflicts with Node.js or npm packages already on your server, and consistent behavior across different host systems. When something goes wrong, you can tear down and rebuild in minutes.

The alternative (native npm install) works, but Docker is the path with fewer surprises — especially on VPS environments with non-standard OS configurations.

Prerequisites

A Linux VPS with root SSH access

Ubuntu 22.04 LTS recommended (but most distros work)

At least 2 GB RAM (4 GB recommended)

A domain name pointed at your server (optional but recommended)

An API key from Anthropic, OpenAI, or any OpenAI-compatible provider

Step 1: Install Docker

`bash
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
`

Log out and back in for group changes to take effect. Verify:

`bash
docker –version
docker compose version
`

Step 2: Create the Docker Compose File

`bash
mkdir openclaw && cd openclaw
nano docker-compose.yml
`

Paste this:

`yaml
version: “3.9”

services:
openclaw:
image: openclaw/openclaw:latest
container_name: openclaw
restart: unless-stopped
ports:
– “127.0.0.1:18789:18789”
volumes:
– ./config:/root/.openclaw
– ./workspace:/root/.openclaw/workspace
environment:
– ANTHROPIC_API_KEY=sk-ant-your-key-here
– NODE_ENV=production
healthcheck:
test: [“CMD”, “curl”, “-f”, “http://localhost:18789/health”]
interval: 30s
timeout: 5s
retries: 3
start_period: 60s
`

Key detail: 127.0.0.1:18789 — this binds the gateway to localhost only. Nginx will proxy to it from outside. Never bind 0.0.0.0:18789 — that’s exposing your gateway without authentication to the public internet.

Step 3: Configure SSL (With Nginx)

Install Nginx:

`bash
sudo apt install -y nginx certbot python3-certbot-nginx
`

Create the Nginx site config:

`bash
sudo nano /etc/nginx/sites-available/openclaw
`

`nginx
server {
listen 80;
server_name your-domain.com;

location / {
proxy_pass http://127.0.0.1:18789;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection “upgrade”;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
`

Enable and get SSL:

`bash
sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t
sudo certbot –nginx -d your-domain.com
`

The Upgrade and Connection: upgrade headers are not optional. OpenClaw uses WebSockets — without these headers, you’ll get 502 errors or silent failures.

Step 4: Start OpenClaw

`bash
docker compose up -d
`

Wait 60 seconds — the first startup includes container initialization. Check logs:

`bash
docker compose logs -f openclaw
`

You should see OpenClaw gateway running on :18789. Hit Ctrl+C.

Verify:

`bash
curl -f http://localhost:18789/health
`

200 OK means the gateway is healthy.

Step 5: Connect Telegram

1. Message @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Copy the bot token
4. Open https://your-domain.com in your browser
5. Go to Channels → Telegram → paste your token → Save
6. Send a message to your bot

If it responds within seconds, you’re done.

Common Issues

Container won’t start:
`bash
docker compose logs openclaw
`
Most often: invalid API key or port already in use.

Telegram not responding:

Double-check the bot token

Check docker compose logs | grep telegram

Make sure the bot hasn’t been blocked

502 errors:

The Upgrade and Connection: upgrade headers must be present in the Nginx config

Restart Nginx: sudo systemctl reload nginx

Gateway unhealthy:

Wait 60+ seconds after startup

Check docker compose logs | grep health

Updating OpenClaw

`bash
cd ~/openclaw
docker compose pull
docker compose up -d
docker image prune -f
`

Your config and workspace persist in the Docker volumes. The update takes 2 minutes.

The 30-Minute Checklist

[ ] SSH into your server

[ ] Install Docker

[ ] Create docker-compose.yml

[ ] Start the container

[ ] Verify health endpoint

[ ] Install Nginx

[ ] Configure SSL

[ ] Connect Telegram

[ ] Send first message

That’s it. If you hit a specific error, the OpenClaw docs at docs.openclaw.ai have troubleshooting sections for every common issue.

One email per week when I publish a new article or update an existing one. New AI tool reviews, deployment updates, behind-the-scenes notes. No marketing, no spam, unsubscribe in one click.

Subscribe to AimActok Weekly

Or learn more · RSS feed

One email per week when I publish a new article or update an existing one. No marketing, no spam.

→ Subscribe to the newsletter · RSS