Docker is optional

Docker is not required and not the recommended path for most users. For the simplest and fastest setup, we recommend installing OpenClaw directly on a VPS using our standard installation guide.

View Recommended VPS Providers

Security Warning: Local Installation Risks

Running OpenClaw locally on your personal computer can pose significant security risks. The AI agent has access to execute commands, read/write files, and interact with your system. A misconfigured setup could expose sensitive data or allow unintended actions.

Data exposure: The agent can read files on your system, including sensitive documents and credentials
System access: Commands executed by the agent run with your user permissions
Network risks: Improperly secured installations could be accessed by others on your network
No isolation: Unlike a VPS, your personal files and data share the same environment

Recommended: Use a VPS Instead

For a safer and more reliable setup, we strongly recommend running OpenClaw on a dedicated VPS. This provides:

Isolation from your personal computer
24/7 uptime without keeping your computer on
Better security with a controlled environment
Easy setup with our step-by-step guide

View VPS Setup Guide

Why Docker?

Isolated Environment

OpenClaw runs in a container separate from your system, reducing security risks

Easy Cleanup

Remove everything cleanly with docker compose down. No leftover files.

Portable

Same setup works across different systems. Share your config easily.

Agent Sandboxing

Run agent tools in isolated Docker containers for extra security

Requirements

Docker Desktop or Docker Engine
Docker Compose v2
Enough disk space for images and logs

Quick Start (Recommended)

Clone the repository

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

Run the setup script

cd openclaw

./docker-setup.sh

This builds the image, runs onboarding, and starts the gateway via Docker Compose.

Access the dashboard

Open http://127.0.0.1:18789/ in your browser and paste the token from the setup output.

Manual Docker Compose Flow

If you prefer manual control:

docker build -t openclaw:local -f Dockerfile .

docker compose run --rm openclaw-cli onboard

docker compose up -d openclaw-gateway

Useful Docker Commands

Get dashboard URL with token:

docker compose run --rm openclaw-cli dashboard --no-open

View logs:

docker compose logs -f openclaw-gateway

Health check:

docker compose exec openclaw-gateway node dist/index.js health

Stop and remove containers:

docker compose down

Environment Variables

Configure OpenClaw via environment variables in your docker-compose.yml:

services:
  openclaw-gateway:
    environment:
      - OPENCLAW_HOME=/data
      - ANTHROPIC_API_KEY=sk-ant-...
      - OPENAI_API_KEY=sk-...
      - TELEGRAM_BOT_TOKEN=123456:ABC...
      # Agent sandboxing (optional)
      - OPENCLAW_SANDBOX=docker
      - SHARP_IGNORE_GLOBAL_LIBVIPS=1

Common Variables:

• OPENCLAW_HOME — Data directory (default: ~/.openclaw)
• ANTHROPIC_API_KEY — Anthropic API key for Claude models
• OPENAI_API_KEY — OpenAI API key
• OPENCLAW_SANDBOX — Enable agent sandboxing ("docker" or "none")
• SHARP_IGNORE_GLOBAL_LIBVIPS — Set to 1 to fix sharp image processing issues

Agent Tool Sandboxing

When OPENCLAW_SANDBOX=docker is set, the agent executes shell commands inside ephemeral Docker containers. This adds an extra layer of isolation.

Sandbox Volumes:

You may need to grant the sandbox containers access to certain directories:

# In docker-compose.yml
services:
  openclaw-gateway:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - openclaw-data:/data
      - ./workspace:/workspace  # Shared working dir

Caution: Mounting the Docker socket (/var/run/docker.sock) grants the container access to control Docker. Only do this if you understand the security implications.

Volume Mounts & Data Persistence

OpenClaw stores configuration, databases, and logs in the data directory. Use volumes to persist this data across container restarts.

services:
  openclaw-gateway:
    volumes:
      - openclaw-data:/data
    environment:
      - OPENCLAW_HOME=/data

volumes:
  openclaw-data:

Important Paths:

• /data/config.yaml — Main configuration
• /data/db/ — SQLite databases
• /data/logs/ — Log files
• /data/channels/ — Channel session data

Channel Setup in Docker

WhatsApp (QR)

docker compose run --rm openclaw-cli channels login

docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

Discord

docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

Docker Troubleshooting

Permission Denied on Volume Mounts (Linux)

On Linux, the container user may not have permission to write to mounted directories. Fix by matching the container UID or using Docker's user namespace remapping:

docker compose run --user $(id -u):$(id -g) openclaw-cli onboard

Sharp Image Processing Errors

If you see errors related to "sharp" or "libvips", set this environment variable:

SHARP_IGNORE_GLOBAL_LIBVIPS=1

Container Won't Start / Crashes

Check logs for errors:

docker compose logs openclaw-gateway --tail 100