OpenClaw Docker Deployment Guide

📘 Quick path: For a one-line native install on macOS or Linux, see the Quick Start Guide. Use Docker when you want portability, isolation, or to run OpenClaw on any host (VPS, NAS, cloud) without installing Node.js.

Why Run OpenClaw in Docker?

Running OpenClaw in Docker gives you a consistent environment across machines, easy updates by pulling a new image, and isolation from the host. It is ideal for VPS deployments, homelabs, and teams that already use containers. OpenClaw requires Node.js 22+ and channel-specific dependencies-Docker bundles everything so you avoid version conflicts.

This guide covers:

  • Prerequisites: Docker and Docker Compose
  • Step-by-step deployment with docker run and docker-compose
  • Environment variables and configuration persistence
  • Common issues and troubleshooting
  • Security best practices (bind address, no docker.sock, hardening)
  • Next steps: first channel, skills, and post-install checklist

Prerequisites

  • Docker Engine 20.10 or later. Install from Docker’s official install guide for your OS (Linux, macOS, or Windows with WSL2).
  • Docker Compose v2 (e.g. docker compose). Usually included with Docker Desktop; on Linux you may need to install the plugin or standalone binary.
  • API keys for at least one LLM provider (e.g. Anthropic Claude or OpenAI). Have them ready for environment variables-see Anthropic or OpenAI setup.
  • Optional: a messaging app account (e.g. Telegram, Discord) for your first channel.

Step-by-Step Instructions

Step 1: Create a project directory

Create a folder for your OpenClaw Docker setup and configuration:

mkdir -p openclaw-docker && cd openclaw-docker

Step 2: Create a docker-compose.yml

Use the official OpenClaw image and mount a volume for config and data so settings persist across restarts. Bind the gateway to localhost only-do not expose the gateway port to the internet. Example:

# docker-compose.yml
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    environment:
      - NODE_ENV=production
    env_file:
      - .env
    volumes:
      - openclaw-data:/root/.openclaw
    ports:
      - "127.0.0.1:1618:1618"
    # Optional: resource limits
    deploy:
      resources:
        limits:
          memory: 1G

volumes:
  openclaw-data:

Security note: Never mount /var/run/docker.sock into the OpenClaw container. For detailed Docker hardening (user namespaces, minimal mounts, network isolation), see Docker Security Hardening and Security Best Practices.

Step 3: Create a .env file

Store API keys and secrets in .env (do not commit this file). Example:

# .env - keep this file secret, add to .gitignore
ANTHROPIC_API_KEY=sk-ant-...
# Or for OpenAI:
# OPENAI_API_KEY=sk-...

Channel tokens (e.g. Telegram, Discord) can also be set here and referenced in your config. See Configuration File Guide and Credential Management.

Step 4: Pull the image and start the stack

From the same directory as docker-compose.yml:

docker compose pull
docker compose up -d

Check that the container is running:

docker compose ps
docker compose logs -f openclaw

Step 5: Verify and configure

The gateway listens on port 1618 inside the container, mapped to 127.0.0.1:1618 on the host. If you have the OpenClaw CLI installed on the host, you can point it at the gateway; otherwise use the container to run commands:

docker compose exec openclaw openclaw status

To edit config or run the onboarding wizard, exec into the container or mount a pre-built config into /root/.openclaw. After changing config, restart:

docker compose restart openclaw

For full post-setup (first channel, model provider, skills), follow the Post-Installation Setup guide.

Alternative: Single docker run command

For a quick test without Compose, you can run the image once (replace YOUR_ANTHROPIC_KEY and adjust the volume path):

docker run -d \
  --name openclaw \
  -e ANTHROPIC_API_KEY=YOUR_ANTHROPIC_KEY \
  -v openclaw-data:/root/.openclaw \
  -p 127.0.0.1:1618:1618 \
  openclaw/openclaw:latest

For production, prefer docker-compose with an .env file and resource limits.

Common Issues

Issue Solution
Container exits immediately Check docker compose logs openclaw. Often caused by missing or invalid API keys in .env or invalid config in the mounted volume. Ensure ANTHROPIC_API_KEY or OPENAI_API_KEY is set.
Port 1618 already in use Change the host port in ports (e.g. 127.0.0.1:1619:1618) or stop the process using 1618. See Installation Errors.
Permission denied on volume Named volumes are owned by root inside the container. If you need to edit files from the host, ensure the user in the container matches, or use a bind mount with correct permissions.
Gateway not reachable from host Keep the gateway bound to 127.0.0.1 only. For remote access, use SSH tunneling or a VPN (e.g. Tailscale)-do not expose the gateway port publicly. See Network Isolation.
Image not found or pull fails Confirm the image name openclaw/openclaw:latest from the official repository. Check Docker Hub or the project’s install docs for the current image location.

For more fixes, see the Troubleshooting Guide and Gateway Issues.

Best Practices

  • Bind gateway to localhost only: Use 127.0.0.1:1618:1618 in ports. Never expose the gateway directly to the internet.
  • Never mount docker.sock: Do not give the OpenClaw container access to the Docker socket. See Docker Security Hardening.
  • Secrets in environment: Keep API keys and tokens in .env or a secrets manager; do not hardcode in docker-compose.yml.
  • Minimal volumes: Mount only what you need (e.g. ~/.openclaw). Avoid broad host mounts.
  • Updates: Regularly docker compose pull and docker compose up -d to get security and feature updates.
  • Resource limits: Set memory (and optionally CPU) limits to avoid one container affecting the host.

Next Steps

Related Resources