OpenClaw Docker Setup Deep Dive

Docker is the recommended way to run OpenClaw. It provides isolation, simplifies dependency management, and makes updating or rolling back versions straightforward. This guide covers everything from the automated setup script to manual deployment and security hardening.

Prerequisites

Before you begin, ensure your system meets these requirements:

• Docker Desktop (or Docker Engine) and Docker Compose v2
• Operating System: Ubuntu Server is recommended for VPS deployments. For Windows, WSL2 provides a more stable experience.
• Memory: At least 2GB RAM for the image build process. Without this, the pnpm install step may fail due to out-of-memory errors.
• Disk Space: Enough for Docker images, logs, and your workspace.
• Git: For cloning the OpenClaw repository.
• SSH: For VPS deployments, use SSH with keys for a secure connection.

Automated Setup (Recommended)

The fastest way to get OpenClaw running with Docker is to use the official docker-setup.sh script:

Step 1: Clone the Repository

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

Step 2: Run the Setup Script

./docker-setup.sh

This script performs these actions:

• Builds the Docker image locally (or pulls a pre-built image if OPENCLAW_IMAGE is set)
• Runs an interactive onboarding wizard inside a container
• Prompts for your provider API keys
• Generates a gateway token and saves it to a .env file
• Creates necessary volume directories (~/.openclaw for config and ~/openclaw/workspace for files)
• Starts the OpenClaw gateway via Docker Compose

Onboarding Decisions

During the onboarding process, you will make several key decisions:

• Onboarding mode: Select 'manual'
• What to set up: Choose 'Local gateway (this machine)'
• Model provider: Select your desired AI model (OpenAI, Anthropic, Google). If choosing OpenAI Codex with ChatGPT OAuth, you may need to copy a redirect URL from your browser back into the wizard.

Fixing Memory Issues

If the build fails on a low-memory VPS, create a swap file first:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Accessing the Web Interface

Once the setup script completes, the OpenClaw gateway should be running. The web Control UI is accessible at:

http://127.0.0.1:18789/

You will need to paste the generated gateway token into the settings to access the interface.

Using the CLI Container

OpenClaw provides a separate CLI container (openclaw-cli) for administrative commands. Run commands through docker compose from the repository root:

# Check gateway status
docker compose run --rm openclaw-cli status

# Configure messaging channels
docker compose run --rm openclaw-cli channels add telegram

Manual Docker Deployment

If you prefer to run each step manually instead of using the docker-setup.sh script:

Step 1: Build the Docker Image

docker build -t openclaw:local -f Dockerfile .

Step 2: Run Onboarding and Start Gateway

Execute the onboarding and configuration writes directly through the openclaw-gateway container before bringing up the full Docker Compose stack.

Step 3: Start Docker Compose

docker compose up -d

Common Troubleshooting

Installation Stuck or Unauthorized Dashboard

If the installation appears to freeze after onboarding, or the dashboard shows an Unauthorized error:

• Ensure Docker Desktop is running
• If stuck, press Ctrl C in the terminal
• Manually run: docker compose up -d openclaw-gateway
• Wait a few minutes and refresh the browser
• For the stuck state, navigate to ~/.openclaw/pending.json and change "silent": false to "silent": true

Gateway Service Not Starting

If the gateway does not start or you see "connection refused":

• Check Docker Desktop to confirm the container is running
• Review logs: docker logs openclaw --tail 50
• Check for port conflicts: sudo lsof -i :3000

Configuration Issues

If OpenClaw fails to start due to missing environment variables or corrupted config:

• Check required env vars: docker exec openclaw env | grep -E "API_KEY|DATABASE|PORT"
• Validate config syntax: docker exec openclaw cat /app/config.yml | python3 -c "import sys,yaml; yaml.safe_load(sys.stdin)"
• Ensure you are mounting a writable host directory for /app/data
• Verify UID/GID of the mounted directory matches the container user

Bot Connected but Not Responding

If the dashboard shows the bot connected but messages receive no response:

• Check if messages are being received: docker logs openclaw --tail 100 | grep -i "incoming\|received\|message"
• Verify AI API connectivity and check for expired or rate-limited API keys
• Run: docker exec openclaw openclaw doctor --fix
• Restart: docker compose -p openclaw restart

Security Hardening for Public Deployments

The default Docker setup is intended for testing and development. For VPS or public deployments, security hardening is crucial:

• Bind to localhost: Configure the web interface to bind to 127.0.0.1:18789 instead of 0.0.0.0
• Use a reverse proxy: Set up Nginx with authentication and HTTPS for external access
• Restrict .env permissions: chmod 600 .env
• Never commit secrets: Add .env to .gitignore

Docker Sandboxing (Optional)

For stronger isolation, especially when running agents that execute code, consider Docker Sandboxes. This runs OpenClaw in isolated micro-VMs with a configurable network proxy.

With Docker Sandboxes, agents cannot connect to arbitrary internet hosts, and API keys can be securely injected without exposure.