OpenClaw Docker Setup

Pull the OpenClaw Docker Image

The official OpenClaw image is published on GitHub Container Registry.

docker pull ghcr.io/openclaw/openclaw:latest

Official tags include latest, main, and version tags. Use latest for a quick test. Pin a tested version tag for a long-lived deployment so a rebuild does not silently change the runtime.

For the supported setup flow, clone the OpenClaw repository and run the Docker setup script:

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

Confirm Docker can see the image after the pull:

docker image ls ghcr.io/openclaw/openclaw

If the pull fails, check three items first: Docker is running, the host can reach ghcr.io, and your environment does not require a proxy or registry allowlist. Prefer the GitHub Container Registry image unless your organization has mirrored and verified the image in a private registry.

Run OpenClaw With docker run (Minimal Example)

The official OpenClaw setup uses Docker Compose. Use docker run only for manual tests or quick validation.

For manual tests, build from the repository first:

docker build -t openclaw:local -f Dockerfile .

Then follow the repository's current container command. OpenClaw needs persistent configuration, a Gateway token, and port 18789 exposed to the host.

Before running a manual container, verify these inputs:

• The image exists locally or can be pulled from the registry.
• The Gateway token is set through the supported environment variable or generated by the setup script.
• Port 18789 is not already used by another process.
• Configuration, workspace, session, and log paths are mounted outside the container if you need data to survive container replacement.
• Any local model endpoint uses a container-reachable host address, not container-local 127.0.0.1.

Check whether the Control UI port is already in use:

lsof -i :18789

On systems without lsof, use the platform equivalent such as ss, netstat, or Docker Desktop's port view.

Avoid copying an old docker run command without checking the current release. Container flags, environment variables, image names, and required mounts can change between OpenClaw versions.

docker-compose Setup for Persistent Sessions

Use the bundled Compose file for normal Docker deployments.

./scripts/docker/setup.sh
docker compose up -d openclaw-gateway

The setup script creates credentials and starts onboarding. Docker Compose then keeps the gateway service, ports, volumes, and environment configuration in one repeatable file.

Persist these locations:

• OpenClaw configuration.
• Agent workspaces.
• Session data.
• Logs required by your retention policy.

Open the Control UI at http://127.0.0.1:18789/.

After starting the service, verify the container state:

docker compose ps
docker compose logs -f openclaw-gateway

Treat the Compose file as the source of truth for ports, volumes, environment variables, and Gateway configuration. Before upgrading or rebuilding, confirm that the directories holding OpenClaw config, workspaces, credentials, and session data are mounted outside the container.

A safe operating flow is:

1. Run docker compose ps and confirm the gateway is healthy.
2. Back up mounted configuration and session directories.
3. Pull or build the intended image version.
4. Restart with docker compose up -d openclaw-gateway.
5. Reopen http://127.0.0.1:18789/ and confirm the expected sessions and workspaces are still available.

If sessions disappear after a container rebuild, the most likely cause is missing or incorrect volume mapping.

Windows-Specific: WSL2 and Docker Desktop Prerequisites

Install Docker Desktop and enable WSL2 integration for the Linux distribution where you run OpenClaw.

Run the OpenClaw repository and Compose commands inside a WSL2 distribution. Keep the project on the Linux filesystem for better file performance. A path such as ~/projects/openclaw is usually better than working under /mnt/c/....

Confirm these commands work inside WSL2:

docker version
docker compose version

Also confirm the Docker context points to Docker Desktop:

docker context ls

If docker is not available inside WSL2, open Docker Desktop settings, enable integration for the selected distribution, then restart the WSL2 shell.

If file changes feel slow or container startup takes longer than expected, move the repository and mounted workspace directories into the WSL2 Linux filesystem. Cross-filesystem mounts between Windows and WSL2 can add avoidable latency.

For model services running on the Windows host or through Docker Desktop, do not assume that localhost inside the OpenClaw container reaches the host service. Use the container networking checks in the Docker Model Runner and Linux networking sections.

After the WSL2 and Docker Desktop checks are working, OpenClaw on Windows can help you align the same setup with native Windows workflow decisions.

For source-level validation, the official documentation is worth checking after you understand the OpenClaw Docker Setup workflow described here.

Fix 'tcp://127.0.0.1:12434 Fetch Failed' With Docker Model Runner

Inside a container, 127.0.0.1 points to that container.

It does not point to the Windows or macOS host. If OpenClaw is running in Docker and the model service is running on the host, a host-side URL using 127.0.0.1 can fail from inside the container.

Replace the host address with:

host.docker.internal

Also confirm the model service listens on a host-reachable address. Check the real port. Do not assume 12434 is correct for every runner.

Use this troubleshooting sequence:

1. Identify the model service host and port on the host machine.
2. Confirm the service responds from the host.
3. Replace 127.0.0.1 or localhost in the container configuration with host.docker.internal.
4. Restart the OpenClaw container after changing environment variables or configuration files.
5. Test connectivity from inside the OpenClaw container, not only from the host.

A host-side request only proves the host can reach the model endpoint. It does not prove the OpenClaw container can reach the same endpoint. Docker Desktop, WSL2, and Linux bridge networking each add a network boundary that can change how the address must be written.

If the error continues, check the configured port, firewall rules, model service bind address, Docker logs, and whether the model runner is listening on an interface reachable from Docker.

After fixing container connectivity, How to Install OpenClaw can help verify the base setup before you retest model access.

When details such as limits or setup steps matter, Hub can help confirm the latest implementation surface.

Linux host.docker.internal Networking Fix

Linux Docker Engine may need an explicit host mapping for host.docker.internal.

With docker run, add:

--add-host=host.docker.internal:host-gateway

With Compose, add:

extra_hosts:
  - "host.docker.internal:host-gateway"

Ollama then normally uses:

http://host.docker.internal:11434

Restart the container after adding the host mapping:

docker compose up -d openclaw-gateway

Then test the endpoint from the container. Use the shell and tools available in the image, or run a temporary diagnostic container on the same network.

docker compose exec openclaw-gateway sh

From there, test the model URL if the image includes a tool such as curl or wget. If the tool is not present, use container logs and a temporary network diagnostic image approved for your environment.

The important rule is simple: the model service must listen on a host-reachable interface, Docker must provide a route from the container to the host, and OpenClaw must use the host-facing URL.

> From model output to merged work > > Verdent reported 76.1% SWE-bench Verified. That is the Production-Ready Quality layer between generated code and code ready to merge. > > Plan-First Intelligence sets the direction. Parallel Power handles concurrency. Review closes the loop.

After the container can reach the host service, OpenClaw Ollama Integration covers the Ollama-side configuration that keeps model calls aligned with that URL.

Before you budget a real project around OpenClaw Docker Setup, compare the claims here with Til.

Production Docker Hardening Checklist

• Bind the Gateway to a private interface.
• Require a strong Gateway token.
• Use a private tunnel for remote access.
• Keep secrets outside the image.
• Pin a version tag.
• Run as a non-root user.
• Back up persistent data.
• Limit container resources.
• Review third-party skills.
• Update after testing.

Docker isolates processes. It does not replace access control.

For a production-style deployment, also define who can access the Gateway, where logs are stored, how credentials rotate, and how containers are updated. Do not publish the Gateway port directly to the public internet. Place it behind a private network, VPN, zero-trust access layer, or another controlled access path approved by your team.

Use image tags intentionally. latest is useful for evaluation, but a pinned version tag is safer for controlled deployments. Test updates in a staging environment before replacing a working container.

Keep secrets in environment management, secret storage, or deployment tooling rather than baking them into an image. Back up mounted configuration, session, and workspace directories before upgrades.

Set resource limits when OpenClaw shares a host with other services. CPU, memory, and disk limits reduce the chance that one container affects the rest of the system.

For software delivery, Verdent adds task planning, parallel agents, isolated workspaces, and code verification.