TL;DR
- Minimum requirements: 1 vCPU, 1 GB RAM, 10 GB disk, Docker 20.10+, Docker Compose V2.
- Pull the official image: `docker pull openclaw/openclaw:1.4.2`.
- Create a `docker-compose.yml` with your environment variables and a persistent volume.
- Run `docker compose up -d` and open your server on port 3000.
- Not a fan of terminal windows? OneClaw managed hosting gets you live in one click — no Docker required.
Why Run OpenClaw in Docker?
OpenClaw is a powerful, self-hostable AI assistant framework. Docker is the cleanest way to run it on your own server: dependencies are bundled inside the image, the host stays clean, and upgrades are a single command.
This guide walks through every step — from checking system requirements to monitoring a running container — so you can go from zero to a production-ready OpenClaw instance without surprises.
If at any point the terminal feels like the wrong tool for the job, remember that OneClaw managed hosting handles all of this automatically, including backups, SSL, and automatic updates.
OpenClaw Server Requirements
Before pulling any image, make sure your host meets these specs.
Minimum (development / low-traffic)
| Resource | Minimum |
|---|---|
| CPU | 1 vCPU |
| RAM | 1 GB |
| Disk | 10 GB |
| Docker | 20.10+ |
| Docker Compose | V2 (compose v2 plugin) |
Recommended (production)
| Resource | Recommended |
|---|---|
| CPU | 2 vCPU |
| RAM | 2 – 4 GB |
| Disk | 20 GB SSD |
| Docker | Latest stable |
| Docker Compose | V2 (compose v2 plugin) |
Note: If you plan to run OpenClaw alongside a database container and a reverse proxy on the same host, lean toward the recommended figures. Low RAM is the most common cause of container crashes.
Step 1 — Install Docker and Docker Compose V2
Skip this section if Docker is already installed. You can verify with:
```bash docker --version # Should be 20.10 or newer docker compose version # Should show Compose version v2.x ```
Ubuntu / Debian
```bash sudo apt-get update sudo apt-get install -y 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-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ```
Add your user to the docker group so you can run commands without sudo:
```bash sudo usermod -aG docker $USER newgrp docker ```
macOS and Windows
Install Docker Desktop. Docker Compose V2 is bundled automatically.
Step 2 — Pull the OpenClaw Docker Image
```bash docker pull openclaw/openclaw:1.4.2 ```
Always pin to a specific version tag in production. The `latest` tag changes with each release and can introduce unexpected breaking changes if you run `docker compose pull` without reviewing the changelog first.
Step 3 — Create a Project Directory
Keep your Compose file, environment config, and any custom assets in one place:
```bash mkdir -p /opt/openclaw cd /opt/openclaw ```
Step 4 — Write Your docker-compose.yml
Create `/opt/openclaw/docker-compose.yml` with the following content. Read through it before running — each section is explained below.
```yaml version: "3.9"
services: openclaw: image: openclaw/openclaw:1.4.2 container_name: openclaw restart: unless-stopped ports: - "127.0.0.1:3000:3000" environment: APP_URL: "https://openclaw.example.com" APP_SECRET: "change-me-to-a-random-64-char-string" DATABASE_URL: "postgres://openclaw:securepassword@db:5432/openclaw" REDIS_URL: "redis://redis:6379" TELEGRAM_BOT_TOKEN: "your-telegram-bot-token" AI_PROVIDER: "anthropic" AI_API_KEY: "your-anthropic-api-key" volumes: - openclaw_data:/app/data depends_on: db: condition: service_healthy redis: condition: service_started
db: image: postgres:16-alpine container_name: openclaw_db restart: unless-stopped environment: POSTGRES_USER: openclaw POSTGRES_PASSWORD: securepassword POSTGRES_DB: openclaw volumes: - openclaw_db:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U openclaw"] interval: 10s timeout: 5s retries: 5
redis: image: redis:7-alpine container_name: openclaw_redis restart: unless-stopped volumes: - openclaw_redis:/data
volumes: openclaw_data: openclaw_db: openclaw_redis: ```
What each service does
| Service | Purpose |
|---|---|
| `openclaw` | The main application server (Node.js, port 3000) |
| `db` | PostgreSQL 16 — stores all operational data |
| `redis` | Redis 7 — queues, sessions, and real-time events |
Step 5 — Configure Environment Variables
The most important variables to change before first launch:
| Variable | Description |
|---|---|
| `APP_URL` | Your public-facing URL, including the protocol. Must match your SSL domain. |
| `APP_SECRET` | A cryptographically random string (64+ chars). Generate with `openssl rand -hex 32`. |
| `DATABASE_URL` | PostgreSQL connection string. Update credentials to match the db service. |
| `TELEGRAM_BOT_TOKEN` | Your Telegram bot token from BotFather. |
| `AI_PROVIDER` | The AI model provider: anthropic, openai, google, or deepseek. |
| `AI_API_KEY` | Your API key for the selected AI provider. |
For a cleaner setup, move secrets into a `.env` file and reference it from Compose:
```bash
/opt/openclaw/.env
APP_SECRET=your-real-secret-here POSTGRES_PASSWORD=your-real-db-password TELEGRAM_BOT_TOKEN=your-real-token AI_API_KEY=your-real-api-key ```
Then update `docker-compose.yml` to use `env_file: .env` under the openclaw service. Keep the `.env` file out of version control by adding it to `.gitignore`.
Step 6 — Persistent Storage
The Compose file defines three named volumes:
- openclaw_data — uploaded files, exports, and local configuration written by the app.
- openclaw_db — PostgreSQL data directory.
- openclaw_redis — Redis snapshot for session persistence.
Named volumes live under `/var/lib/docker/volumes/` on Linux and survive container removal. If you prefer host-bind mounts (useful for easier direct access to files), replace the volume references with a host path.
Step 7 — Start OpenClaw
```bash cd /opt/openclaw docker compose up -d ```
Docker will pull any missing images, create the volumes and network, and start the three containers. OpenClaw runs database migrations automatically on first boot.
Check that all containers are running:
```bash docker compose ps ```
Expected output:
``` NAME IMAGE STATUS openclaw openclaw/openclaw:1.4.2 Up 30 seconds openclaw_db postgres:16-alpine Up 31 seconds (healthy) openclaw_redis redis:7-alpine Up 31 seconds ```
Open `http://your-server-ip:3000\` in a browser (or your configured domain if DNS and a reverse proxy are already set up).
Step 8 — Set Up a Reverse Proxy (Recommended)
Binding only to `127.0.0.1:3000` means OpenClaw is not directly accessible from the internet. Route public traffic through Nginx or Caddy, which also handles TLS.
A minimal Nginx config:
```nginx server { listen 80; server_name openclaw.example.com; return 301 https://$host$request_uri; }
server { listen 443 ssl http2; server_name openclaw.example.com;
ssl_certificate /etc/letsencrypt/live/openclaw.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/openclaw.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 120s;
}
} ```
Obtain a free certificate with Certbot: `sudo certbot --nginx -d openclaw.example.com`.
Monitoring the Running Container
Stream live logs:
```bash docker compose logs -f openclaw ```
Check resource usage:
```bash docker stats openclaw ```
Updating OpenClaw
- Back up your data volumes before any upgrade.
- Pull the new image:
```bash cd /opt/openclaw
Edit docker-compose.yml to update the image tag, then:
docker compose pull docker compose up -d ```
OpenClaw applies any pending database migrations on startup. Monitor logs for the first minute to confirm a clean boot.
Troubleshooting
Container exits immediately
Run `docker compose logs openclaw` and look for the first error line. Common causes:
- Missing or incorrect APP_SECRET — must be set to a non-empty string.
- Database not reachable — the depends_on health check should prevent this, but verify DATABASE_URL credentials match the db service.
- Port already in use — change `127.0.0.1:3000:3000` to a free port.
Out of memory
Upgrade your host to meet the recommended 2 GB RAM, or add a swap file as a temporary measure:
```bash sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile ```
The Easier Alternative: OneClaw Managed Hosting
Self-hosting with Docker gives you full control, but it also means you own the maintenance: OS patches, certificate renewals, backups, and version upgrades.
If that sounds like more overhead than you want, OneClaw managed hosting is the alternative. Deployments are one-click, SSL is automatic, and the team handles every update. You focus on building your AI assistant, not managing your infrastructure. Check out our guides for more ways to get started, or jump straight to the cloud one-click deploy if you want to be live in under two minutes.