Docker Guide

OpenClaw Docker setup

This page is for running OpenClaw in Docker: image pull, container run, volume config, and post-setup verification.

For non-Docker install, go to install OpenClaw. If container fails to start, see troubleshooting.

Quick answer

Pull the official image, run it with your config mounted, then verify with openclaw gateway status inside the container or via the dashboard.

Prerequisites

  • Docker 20.10+ installed and running.
  • Node 22+ on host (for CLI access if needed).
  • LLM provider credentials (OpenAI/Anthropic/Gemini).
  • Optional: Telegram bot token or Slack tokens.

Step 1: Pull the OpenClaw image

docker pull openclaw/openclaw:latest

Use a specific tag for reproducibility:

docker pull openclaw/openclaw:v1.2.0

Step 2: Run the container

Basic run with ports exposed:

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v openclaw-config:/app/config \
  openclaw/openclaw:latest

With environment variables for initial setup:

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -e OPENCLAW_MODEL_PROVIDER=openai \
  -e OPENCLAW_MODEL_API_KEY=sk-... \
  -v openclaw-config:/app/config \
  openclaw/openclaw:latest

Step 3: Verify gateway is running

docker exec openclaw openclaw gateway status

Expected: running status with no fatal errors.

Or access the dashboard:

openclaw dashboard

This opens the Control UI at http://127.0.0.1:18789/.

Step 4: Configure providers and channels

Run the onboarding wizard inside the container:

docker exec openclaw openclaw onboard --install-daemon

Or configure manually:

docker exec openclaw openclaw configure

Step 5: Persist data with volumes

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v openclaw-config:/app/config \
  -v openclaw-workspace:/app/workspace \
  openclaw/openclaw:latest
  • /app/config — gateway config, credentials, allowlists.
  • /app/workspace — files, memory, conversation history.

Common errors and quick fixes

Port 18789 already in use

Stop the conflicting service or change the port:

docker run -d --name openclaw -p 18790:18789 openclaw/openclaw:latest

Container exits immediately

Check logs for the error:

docker logs openclaw

Common causes: missing API key, invalid credentials, port conflict.

Gateway unreachable from host

Verify the container is listening:

docker exec openclaw openclaw gateway status
docker port openclaw

"command not found" inside container

Ensure you're using the correct image tag. Try:

docker exec openclaw which openclaw

Next steps

OpenClaw setup guide

Full setup from install to first message.

 Gateway setup

Operations, auth, and debugging.

 Troubleshooting

Common issues and solutions.
Cookie preferences