# Run OpenClaw in Docker: Complete Setup Guide > Originally published on [Remote OpenClaw](https://remoteopenclaw.com/blog/how-to-run-openclaw-in-docker/). ![How to Run OpenClaw in Docker: Complete Setup Guide (2026)](/api/og?type=hero&title=How%20to%20Run%20OpenClaw%20in%20Docker%3A%20Complete%20Setup%20Guide%20%282026%29&subtitle=Get%20OpenClaw%20running%20inside%20Docker%20containers%20in%20minutes.%20Covers%20image%20pull%2C...) Marketplace Free skills and AI personas for OpenClaw — browse the marketplace. [Browse the Marketplace →](https://remoteopenclaw.com/marketplace) Join the Community Join 1k+ OpenClaw operators sharing deployment guides, security configs, and workflow automations. [Join the Community →](https://shorturl.at/3bwc0) ## Why Should You Run OpenClaw in Docker? Running OpenClaw in Docker gives you dependency isolation, consistent environments across operating systems, persistent storage, security boundaries with non-root execution, easy updates, and production-ready health checks and logging. - **Dependency isolation** — all 70+ dependencies managed automatically - **Consistent environment** — same setup on Ubuntu, macOS, or Windows - **Persistent storage** — configuration and workspace survive container restarts - **Security boundaries** — the agent runs as a non-root user with limited host access - **Easy updates** — pull new images without reinstalling anything - **Production-ready** — health checks, logging, and monitoring built in * * * ## What Do You Need Before Starting? You need Docker Desktop or Engine (latest stable), Docker Compose v2+, at least 2 GB RAM (4 GB recommended), 10 GB disk space, Git, Bash v4+, and at least one AI provider API key. Requirement Minimum Recommended **Docker Desktop or Engine** Latest stable Latest stable **Docker Compose** v2+ v2+ **RAM** 2 GB 4 GB **Disk space** 10 GB 20 GB+ **Git** Any version Latest **Bash** v4+ (upgrade on macOS: `brew install bash`) v4+ **API key** At least one AI provider Anthropic recommended Verify your setup: ```bash docker --version docker compose version git --version ``` ### VPS Sizing by Use Case Use Case vCores RAM Disk Digital assistant 4 4 GB 120 GB Workflow automation 6 8 GB 240 GB Developer productivity 8 16 GB 480 GB * * * ## How Do You Clone the OpenClaw Repository? Clone the official OpenClaw GitHub repository and navigate into the project directory — this gives you the Docker Compose configuration, setup scripts, and all required files. ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw ``` * * * ## How Do You Run the OpenClaw Docker Setup Script? The setup script builds the Docker image, runs an interactive onboarding wizard, prompts for your API key, generates authentication tokens, creates configuration directories, and starts the gateway via Docker Compose. ```bash chmod +x docker-setup.sh ./docker-setup.sh ``` ### Using a Pre-Built Image (Faster) Skip the local build by specifying a remote image: ```bash export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" ./docker-setup.sh ``` Pre-built images are available from GitHub Container Registry with tags: `latest` (most recent stable release), `main` (latest from main branch), and version-specific (e.g., `2026.2.26`). * * * ## How Do You Verify OpenClaw Docker Is Running? Run docker compose ps to confirm the gateway container is running, then check health endpoints at localhost:18789 for liveness and readiness without authentication. ```bash docker compose ps ``` You should see `openclaw-openclaw-gateway-1` running. Check the logs: ```bash docker compose logs -f openclaw-gateway ``` ### Health Checks ```bash # Liveness check curl -fsS http://127.0.0.1:18789/healthz # Readiness check curl -fsS http://127.0.0.1:18789/readyz ``` * * * ## How Do You Access the OpenClaw Web Dashboard? Navigate to http://127.0.0.1:18789 in your browser to access OpenClaw's web-based control panel for chatting with your agent, configuring channels, and managing skills. If you see a pairing or authentication prompt, retrieve your dashboard link: ```bash docker compose run --rm openclaw-cli dashboard --no-open ``` If device approval is needed: ```bash docker compose run --rm openclaw-cli devices list docker compose run --rm openclaw-cli devices approve ``` * * * Marketplace Free skills and AI personas for OpenClaw — browse the marketplace. [Browse the Marketplace →](https://remoteopenclaw.com/marketplace) ## How Do You Connect WhatsApp, Telegram, Discord, and Slack? Each messaging channel connects through CLI commands after the gateway is running — WhatsApp via QR code scan, Telegram via BotFather token, and Discord and Slack via bot tokens with pairing approval. ### WhatsApp (QR Code) ```bash docker compose run --rm openclaw-cli channels login ``` Scan the QR code with your WhatsApp app to connect. ### Telegram 1. Create a bot with [@BotFather](https://t.me/BotFather) on Telegram 2. Copy the bot token 3. Add the channel: ```bash docker compose run --rm openclaw-cli channels add \ --channel telegram \ --token ``` 4. Send a message to your bot, then approve the pairing: ```bash docker compose run --rm openclaw-cli pairing approve telegram ``` ### Discord ```bash docker compose run --rm openclaw-cli channels add \ --channel discord \ --token ``` ### Slack ```bash docker compose run --rm openclaw-cli channels add \ --channel slack \ --token ``` * * * ## What Environment Variables Does OpenClaw Docker Support? OpenClaw Docker supports environment variables for image selection, API keys (Anthropic, OpenAI, Google, Groq), gateway tokens, extra apt packages, bind mounts, sandbox mode, and network binding configuration. Variable Purpose Example `OPENCLAW_IMAGE` Use a remote image instead of building locally `ghcr.io/openclaw/openclaw:latest` `ANTHROPIC_API_KEY` Anthropic API key for Claude models `sk-ant-...` `OPENAI_API_KEY` OpenAI API key `sk-...` `GOOGLE_API_KEY` Google API key for Gemini `AIza...` `GROQ_API_KEY` Groq API key `gsk_...` `GATEWAY_TOKEN` Authentication token for dashboard access Auto-generated `OPENCLAW_DOCKER_APT_PACKAGES` Extra apt packages to install in the image `ffmpeg imagemagick` `OPENCLAW_SANDBOX` Enable agent sandbox mode `1`, `true`, `yes`, `on` `OPENCLAW_GATEWAY_BIND` Network binding mode `lan`, `loopback`, `tailnet` * * * ## How Does OpenClaw Docker Handle Storage and Persistence? Docker Compose bind-mounts two critical directories — ~/.openclaw/ for configuration and agent state, and ~/.openclaw/workspace/ for agent-accessible files — both persisting across container restarts and rebuilds. Container Path Host Path Contents `/home/node/.openclaw` `~/.openclaw/` Configuration, API keys, agent state, sessions `/home/node/.openclaw/workspace` `~/.openclaw/workspace/` Agent-accessible files, generated outputs * * * ## How Do You Update OpenClaw Docker? Update by pulling the latest code and images, then restarting — your configuration and workspace persist in the mounted volumes. ```bash cd ~/openclaw git pull docker compose pull docker compose up -d ``` * * * ## How Do You Troubleshoot Common OpenClaw Docker Issues? The most common Docker issues are out-of-memory crashes (exit code 137), permission errors from UID mismatch, gateway binding misconfigurations, and stale pairing tokens — each with straightforward fixes. ### Container Won't Start (Exit Code 137) **Cause:** Out of memory. The image build requires at least 2 GB RAM. **Fix:** Increase Docker memory allocation in Docker Desktop > Settings > Resources > Memory. ### Permission Errors **Cause:** OpenClaw runs as `node` user (UID 1000), not root. Host-mounted directories may have wrong ownership. ```bash sudo chown -R 1000:1000 ~/.openclaw ``` ### Gateway Not Accessible ```bash docker compose run --rm openclaw-cli config set gateway.mode local docker compose run --rm openclaw-cli config set gateway.bind lan docker compose up -d ``` ### Dashboard Pairing Errors ```bash docker compose run --rm openclaw-cli dashboard --no-open docker compose run --rm openclaw-cli devices approve ``` ### Missing Sandbox Image ```bash ./scripts/sandbox-setup.sh ``` * * * ## Frequently Asked Questions ### Can I run OpenClaw Docker on a Raspberry Pi? OpenClaw requires at least 2 GB RAM and the Docker image is built for amd64 and arm64. A Raspberry Pi 4 with 4 GB RAM can run it, though performance will be limited. ### Do I need Docker Desktop or can I use Docker Engine? Either works. Docker Desktop provides a GUI and is easier on macOS/Windows. Docker Engine (CLI-only) is sufficient for Linux servers. ### Can I use multiple AI providers simultaneously? Yes. Set multiple API key environment variables and configure which model each agent uses in your `openclaw.json`. ### How do I back up my OpenClaw data? Back up the `~/.openclaw/` directory. This contains all configuration, API keys, agent state, session history, and workspace files. ### Is the Docker image updated automatically? No. You need to manually pull updates with `docker compose pull && docker compose up -d`. Consider setting up a cron job or Watchtower for automatic updates. ### Can I run multiple OpenClaw instances on one server? Yes, but each instance needs unique port mappings and separate configuration directories. Adjust the `docker-compose.yml` ports and volume mounts accordingly.