OpenClaw Docker: How to Run OpenClaw in a Container (2026)

Running OpenClaw with Docker

OpenClaw supports Docker as an alternative to the standard npm installation. The Docker route is useful when you want strict process isolation, need to run additional services alongside OpenClaw, or prefer container-based infrastructure for your server environment.

The official Docker image is at hub.docker.com/r/alpine/openclaw and the official Docker documentation lives at docs.openclaw.ai/install/docker.

Docker vs npm: Which Should You Use?

On macOS, Docker runs through a Linux VM layer, which adds some overhead compared to a direct npm installation. For personal use on a Mac, the native npm install is usually the better choice. Docker becomes compelling on a VPS or when you specifically need to sandbox what the agent can access.

Requirements

• Docker Desktop (Mac, Windows) or Docker Engine with Compose v2 (Linux)
• Minimum 2 GB RAM available for the image build
• An API key for your chosen LLM provider

Step 1: Run docker-setup.sh

OpenClaw provides an automated setup script that builds the image, runs onboarding, and starts the gateway via Docker Compose:

./docker-setup.sh

The script creates two directories on your host machine:

• ~/.openclaw - the configuration directory (API keys, settings, memory, skills)
• ~/openclaw/workspace - the workspace directory the agent can read from and write to

Run through the onboarding prompts. When the script finishes, open http://127.0.0.1:18789/ in your browser and paste the authentication token into the Control UI to complete setup.

Step 2: Manage the Container

After initial setup, use Docker Compose to manage the service:

docker compose up -d # Start in the background docker compose down # Stop docker compose logs -f # Watch live logs docker compose restart # Restart after a config change

Step 3: Verify the Agent Is Running

Open http://127.0.0.1:18789/ in a browser. You should see the OpenClaw Control UI. If the page loads, the gateway is running. Send a test message via the built-in WebChat to confirm the agent responds.

Agent Sandboxing with Docker

One of the most powerful Docker-specific features in OpenClaw is agent sandboxing. Non-primary agent sessions can run their tool executions inside isolated Docker containers, separate from your main machine.

Sandboxing configuration options:

• Isolation scope: per-session or per-agent
• Workspace access: none, read-only, or read-write
• Tool access: explicit allow or deny lists
• Network access: disabled by default (agents cannot make outbound requests unless explicitly permitted)

This is especially useful if you run skills that execute arbitrary code or scripts, or if you are building multi-agent workflows where you want one agent to be unable to interfere with another.

Updating OpenClaw in Docker

To pull the latest image and restart:

docker compose pull docker compose up -d

If you built the image locally from source:

docker build --no-cache -t openclaw . docker compose up -d

Troubleshooting

Container exits immediately after starting Check the logs: docker compose logs. The most common cause is a missing or malformed API key in ~/.openclaw/openclaw.json.

Port 18789 is already in use Either stop the conflicting process or change the port mapping in docker-compose.yml:

ports: - "19000:18789"

Then access the Control UI at http://127.0.0.1:19000/ instead.

Slow performance on macOS This is expected due to Docker's Linux VM layer. If performance is a concern, switch to the native npm installation. See the OpenClaw install guide.

Workspace files not visible to the agent Verify that ~/openclaw/workspace is correctly mounted in your docker-compose.yml. The path must match exactly.

"Cannot connect to the Docker daemon" Docker Desktop is not running. Start it from your Applications folder (macOS) or run sudo systemctl start docker (Linux).

Frequently Asked Questions

Can I run OpenClaw on Docker with a local LLM?

Yes. Configure Ollama to run in a separate container or directly on your host, then point OpenClaw at it using the Ollama provider format in openclaw.json:

{ "agent": { "model": "ollama/llama3.3" } }

Make sure the OpenClaw container can reach the Ollama service. On macOS with Docker Desktop, use host.docker.internal as the hostname instead of localhost.

Is the Docker image official?

Yes. The alpine/openclaw image on Docker Hub is the official distribution. You can also build from source at github.com/openclaw/openclaw.

Does Docker sandboxing affect performance?

There is some overhead from spinning up containers per session. For typical conversational use, it is not noticeable. For high-frequency automation tasks, the native npm install will be faster.

Where is the official Docker documentation?

At docs.openclaw.ai/install/docker.

Can I expose the OpenClaw gateway to the internet?

You can, but it is not recommended without additional authentication in front of the gateway. For remote access, using a private tunnel tool like Tailscale is safer and simpler than opening a public port.