OpenClaw Docker Hub: Pull and Run the Official Image in Minutes

Two docker pull commands give you everything you need to run OpenClaw locally. The gateway image handles all request routing and authentication. The agent image runs your actual AI workloads. Both are under 250MB compressed and boot in under 5 seconds on any modern machine. What trips people up: using unofficial images from the wrong namespace, or blindly running latest and hitting a breaking change mid-sprint.

Prerequisites

You need Docker Engine 24+ or Docker Desktop 4.20+. Run docker --version to confirm. No other dependencies are required to pull and run the official images — that's the point of using Docker Hub images rather than building from source.

You will need your OpenClaw API key and an LLM provider API key. Have these ready before running any containers; the gateway exits immediately if OPENCLAW_API_KEY is not set.

Finding the Official OpenClaw Images

The OpenClaw project publishes two images under the openclaw namespace on Docker Hub. There are no other official images. Community forks and third-party builds exist but are not maintained by the OpenClaw team and may lag behind on security patches.

• openclaw/gateway — The API gateway. Receives external requests, authenticates them, routes tasks to agent workers. This is the only container that needs an external port published.
• openclaw/agent — The agent worker. Pulls tasks from the gateway's queue, executes them against your configured LLM, returns results. Run one or many of these.

Search Docker Hub from the CLI to see all available tags:

# List available tags for the gateway image
docker search openclaw

# Pull image digest info without downloading
docker manifest inspect openclaw/gateway:latest

Pulling and Running the Images

Start with a pull to cache images locally before the first run:

# Pull both images
docker pull openclaw/gateway:latest
docker pull openclaw/agent:latest

# Verify images are present
docker images | grep openclaw

Now run the gateway. It needs your API key and a port binding:

docker run -d \
  --name openclaw-gateway \
  -p 8080:8080 \
  -e OPENCLAW_API_KEY=your-key-here \
  -e LOG_FORMAT=json \
  --restart unless-stopped \
  openclaw/gateway:latest

With the gateway running, start an agent worker. Note it connects to the gateway by container name using Docker's default bridge network:

docker run -d \
  --name openclaw-agent-1 \
  -e GATEWAY_URL=http://openclaw-gateway:8080 \
  -e OPENCLAW_API_KEY=your-key-here \
  -e OPENAI_API_KEY=your-openai-key \
  --link openclaw-gateway:openclaw-gateway \
  -v openclaw-agent-data:/app/data \
  --restart unless-stopped \
  openclaw/agent:latest

Verify both are running:

docker ps --filter name=openclaw
curl http://localhost:8080/health

Choosing the Right Image Tag

OpenClaw Docker Hub follows semantic versioning. Understanding the tag structure saves you from both stale images and unexpected breaking changes.

The rule is simple: pin to Major.Minor.Patch in production. This means updates only happen when you explicitly change the tag and redeploy. Patch releases contain only bug fixes and security patches — upgrading between patch versions of the same minor release is always safe.

Gateway vs. Agent Image: What's Inside

Both images use python:3.11-slim as their base. The gateway image adds the FastAPI server, authentication middleware, Redis client, and request routing logic. The agent image adds the task executor, LLM client libraries, and tool integration modules.

Inspect the full layer breakdown and labels with:

# Check image size breakdown
docker history openclaw/gateway:latest

# View embedded labels including exact version
docker inspect openclaw/gateway:latest \
  --format '{{json .Config.Labels}}' | python3 -m json.tool

Common Mistakes

Pulling from an unofficial namespace. Images named openclaw-agent, openclaw-latest, or similar without the openclaw/ prefix are not official. Check the Docker Hub namespace carefully before trusting any image.

Running latest in production. Every docker pull fetches the newest build. A breaking change in a minor release will silently update your production container on the next pull. Pin to a full version tag.

Not mapping a volume for agent data. Without -v openclaw-agent-data:/app/data, all conversation history and agent memory is lost when the container stops. Always mount a named volume.

Publishing the agent port. The agent container has no listener that needs external access. Only publish ports for the gateway. Exposing unnecessary ports increases attack surface without providing any benefit.

Forgetting to pull before restarting. docker restart container-name does not pull a new image — it just restarts the container on the existing image. Run docker pull first, then remove and recreate the container, or use Docker Compose's pull + up -d workflow.

Frequently Asked Questions

What is the official OpenClaw Docker Hub image name?

The official images are openclaw/gateway and openclaw/agent on Docker Hub. Always pull from the openclaw namespace — third-party images with similar names are not maintained by the OpenClaw team and may be outdated or unverified.

Should I use the latest tag for OpenClaw Docker images?

Avoid latest in production. Pin to a specific version tag like openclaw/gateway:0.9.2 so updates happen deliberately on your schedule, not automatically on the next docker pull. Use latest only in development where you always want the newest build and a breaking change won't cause an incident.

How big is the OpenClaw Docker image?

The gateway image is approximately 180MB compressed and the agent image around 220MB. Both use slim Python base images. Initial pulls take 30–90 seconds on typical broadband. Subsequent pulls for point releases are much faster since most base layers are already cached locally.

How do I check which version of OpenClaw is in a Docker image?

Run docker inspect openclaw/gateway:latest and look for the org.opencontainers.image.version label. Alternatively run docker run --rm openclaw/gateway:latest --version for a quick version string output without starting a full daemon.

Can I run the OpenClaw Docker image on ARM architecture?

Yes — official OpenClaw images are multi-arch and support linux/amd64 and linux/arm64. Docker automatically pulls the correct variant for your host platform. The same image tag works on AMD64 cloud VMs and ARM64 machines like Apple Silicon Macs and Raspberry Pi 4 or 5.

How do I update the OpenClaw Docker image?

Run docker pull openclaw/gateway:latest (or your pinned tag) to fetch the updated layers, then remove and recreate the container with the same docker run command. For Compose-managed stacks, use docker compose pull followed by docker compose up -d to recreate containers cleanly on the new image.

You now know exactly which images to pull, how to choose the right tag for each environment, and how to run both the gateway and agent containers correctly. The next step is verifying connectivity between them by sending a test task through the gateway endpoint. If you're running more than a single agent, move to Docker Compose — it handles the startup ordering, networking, and scaling that manual docker run commands can't manage cleanly at scale.