Ampere
Ampere.sh

OpenClaw on Docker

Run OpenClaw on Docker to set up your AI agent in a clean, portable environment. This guide covers requirements, setup steps, storage, health checks, and common Docker fixes.

Deploy OpenClaw Now

What Is OpenClaw on Docker?

OpenClaw is an open-source AI agent framework that helps you build an AI assistant that can actually perform tasks, not just reply with text. It can connect with tools, apps, messaging channels, workflows, and automations for tasks like customer support, reminders, research, developer work, and business operations.

Docker is a platform that runs software inside containers. A container packages the app with the files and dependencies it needs, so the setup is cleaner and more consistent across different machines, servers, or cloud platforms.

OpenClaw on Docker means running OpenClaw inside a Docker container instead of installing everything directly on your system. This helps keep the OpenClaw setup separate, easier to manage, and easier to move from local testing to a VPS or cloud server.

Why Run OpenClaw With Docker?

  • Keeps OpenClaw separate from your main system
  • Makes setup easier to repeat on another machine
  • Helps test plugins, updates, and workflows safely
  • Works well for VPS and cloud deployments
  • Reduces dependency conflicts
  • Makes cleanup easier if something breaks, because apparently software enjoys breaking at the worst possible time

OpenClaw Docker Requirements

Before running OpenClaw on Docker, make sure your system has the basic requirements. Otherwise, Docker will fail and pretend the problem is “technical,” when really the machine is.

Docker Desktop or Docker Engine
  • Docker Desktop for Windows and macOS
  • Docker Engine for Linux servers
Terminal Access

Required for Docker commands, setup script, logs, and health checks.

Minimum RAM
  • At least 2 GB RAM
  • 4 GB or more recommended
  • Low RAM can cause build failure or exit 137
Docker Compose v2

OpenClaw Docker setup uses Docker Compose v2. User should check with:

docker compose version
Disk Space
  • Docker images
  • Containers
  • Logs
  • OpenClaw config
  • Workspace files
  • Plugin data
Model Provider Access
  • OpenAI
  • Anthropic
  • Gemini
  • Ollama
  • LM Studio

Docker Setup : Run OpenClaw on Docker

Follow this process to run OpenClaw on Docker using the official Docker setup flow.

1
Install Docker

First, install Docker on your system.

For macOS

Use Docker Desktop for Mac.

Go to the official Docker Desktop for Mac page :-

Download the correct version:

  • Apple Silicon if your Mac uses M1, M2, M3, or M4
  • Intel chip if your Mac is older Intel-based
  • Open the downloaded .dmg file.
  • Drag Docker.app into the Applications folder.
  • Open Docker from Applications.
  • Open Docker and wait until it starts.

For Windows

Open Docker’s official Windows install page :-

  • Download Docker Desktop for Windows.
  • Run the installer.
  • Keep WSL 2 backend enabled if the installer asks.
  • Restart your computer if needed.
  • Open Docker Desktop and wait until it starts.

For Ubuntu or Linux VPS

Use Docker Engine.

Open Docker’s official Ubuntu install guide :-

For Ubuntu/Debian, after Docker’s repository is set up, install Docker Compose plugin with:

sudo apt-get update
sudo apt-get install docker-compose-plugin
2
Check Docker and Compose

Open terminal and run:

docker --version
docker compose version

You should see version numbers.

Then run a small Docker test:

docker run hello-world

If this works, Docker is ready.

3
Clone the OpenClaw Repo

Run:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
4
Run the Docker Setup Script

From the OpenClaw repo folder, run:

./scripts/docker/setup.sh

This is the official Docker setup command. It builds the gateway image locally and starts the setup flow.

5
Use Pre-Built Image Optional

To avoid building the image locally, use the pre-built image from GitHub Container Registry:

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh
6
Complete OpenClaw Onboarding

The setup script runs onboarding automatically.

During onboarding, OpenClaw may ask for:

  • Model provider API keys
  • Gateway setup details
  • Basic configuration
  • Optional channel setup

The setup script also creates a gateway token and writes it to .env. You need this token to access the Control UI.

7
Open the Control UI

After setup, open:

http://127.0.0.1:18789/

Paste the gateway token or shared secret when asked.

If you need the dashboard URL again, run:

docker compose run --rm openclaw-cli dashboard --no-open
8
Connect Messaging Channels Optional

You can connect OpenClaw to messaging apps.

# WhatsApp QR login
docker compose run --rm openclaw-cli channels login
# Telegram
docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"
# Discord
docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

OpenClaw’s Docker docs list WhatsApp, Telegram, and Discord channel setup examples.

9
Check OpenClaw Is Running

Check containers:

docker ps

Check gateway health:

curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz

OpenClaw Docker includes health endpoints for liveness and readiness checks.

10
Know Where Data Is Stored

OpenClaw Docker stores important data in mounted folders.

Main paths:

OPENCLAW_CONFIG_DIR → /home/node/.openclaw
OPENCLAW_WORKSPACE_DIR → /home/node/.openclaw/workspace


The config folder stores openclaw.json, auth profiles, and .env secrets such as OPENCLAW_GATEWAY_TOKEN. Plugin data also stays under the mounted OpenClaw home folder.

Where OpenClaw Docker Stores Your Data

When you run OpenClaw on Docker, important data is stored in mounted folders on your host machine. This helps your setup survive container restarts or replacement.

1. Config Folder

The config folder stores OpenClaw setup and account-related files.

It includes:

  • OpenClaw settings
  • Gateway settings
  • Agent settings
  • Provider login or API key details
  • .env runtime secrets
  • Gateway token

Official container path:

/home/node/.openclaw

Host path example:

~/.openclaw


2. Workspace Folder

The workspace folder stores files your OpenClaw agent can use or create.

It may include:

  • Uploaded files
  • Generated files
  • Task files
  • Agent working files
  • Files created during automation

Official container path:

/home/node/.openclaw/workspace

Host path example:

~/.openclaw/workspace


3. .env File

The .env file stores runtime values used by OpenClaw.

Example:

OPENCLAW_GATEWAY_TOKEN=your_gateway_token

Treat this file like a password file. Do not upload it to GitHub, share it in screenshots, or paste it into public chats.


4. Auth Profiles

OpenClaw stores saved provider login or API key details in agent auth profiles.

Example path:

agents/<agentId>/agent/auth-profiles.json

This helps OpenClaw remember model provider access after restart.


5. Plugin Data

Installed plugins store their package data inside the mounted OpenClaw home folder. This means plugins should stay available after container replacement if the mount is configured correctly.


6. Logs and Growing Files

OpenClaw can create logs and runtime files over time.

Watch these areas:

  • media/
  • Session .jsonl files
  • cron/runs/*.jsonl
  • installed plugin folders
  • /tmp/openclaw/

These files can grow over time, so check disk space regularly.


7. Permission Note

The OpenClaw Docker image runs as the node user with UID 1000. If you get permission errors, make sure your mounted folders are owned by UID 1000.

Example:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

When Should You Use Docker for OpenClaw?

Use Docker when you want:

  • A clean local OpenClaw testing setup
  • A repeatable VPS or cloud deployment
  • Separate environments for testing and production
  • Safer plugin and workflow testing
  • Easier version testing
  • More control over configuration and storage

Who Should Avoid Docker Setup?

Docker may not be right if you:

  • Do not want to use terminal commands
  • Do not want to manage ports, volumes, and permissions
  • Need OpenClaw running quickly
  • Want less maintenance
  • Prefer managed hosting
  • Need a beginner-friendly setup for business workflows

OpenClaw Docker vs Managed Hosting

FeatureOpenClaw on DockerOpenClaw on Ampere.sh
Setup speedSlowerFaster
Terminal requiredYesNo or minimal
Server managementUser handles itManaged
Docker knowledge neededYesNo
ControlHighMedium
Best forTechnical usersBeginners, teams, operators
MaintenanceManualManaged
Channel setupManualEasier dashboard flow
Good for productionYes, if configured wellBetter for fast production use

Common OpenClaw Docker Problems and Fixes

ProblemSimple Fix
Docker Compose command not workingInstall or update Docker Compose v2. Check with docker compose version.
Build fails or shows exit 137Use at least 2 GB RAM. For better performance, use 4 GB RAM or more.
Control UI asks for tokenUse the gateway token created during setup. Check the .env file.
Lost Control UI linkRun docker compose run --rm openclaw-cli dashboard --no-open.
Pairing required errorList devices and approve the pending request with the OpenClaw CLI.
Port already in useCheck if another app is using port 18789. Stop it or change the port.
Permission denied / EACCESFix folder permissions. Mounted folders may need ownership for user ID 1000.
Container shows unhealthyCheck /healthz, /readyz, and container logs.
Ollama not reachableUse host.docker.internal:11434 instead of 127.0.0.1:11434.
LM Studio not reachableUse host.docker.internal:1234 instead of 127.0.0.1:1234.

Run OpenClaw Without Docker

You do not need Docker to start using OpenClaw. Docker gives you control, but it also adds setup work, port issues, storage handling, updates, logs, uptime checks, and security tasks.

With Ampere.sh, you can run OpenClaw without setting up Docker or managing the server manually. Ampere focuses on faster OpenClaw deployment, less setup friction, and letting users build workflows without server headaches.

How It Works on Ampere.sh

Instead of installing Docker and configuring everything manually, you can ask the Ampere bot what you want to connect.

1.Ask the bot: “I want to connect WeChat”
2.The bot starts processing and tells you what details it needs
3.You provide the required information, such as app details or connection settings
4.The bot applies the setup without extra manual server work
5.You test the connection and start using the workflow

Frequently Asked Questions

Does OpenClaw need Docker?
No. OpenClaw does not need Docker. Docker is optional. Use it if you want a cleaner, separate setup for testing, VPS hosting, or multiple OpenClaw setups.
Should I run OpenClaw in Docker?
Run OpenClaw in Docker if you want better separation from your main system, easier VPS deployment, or a setup you can repeat on another machine.
Can I run OpenClaw without Docker?
Yes. You can run OpenClaw without Docker using the normal install flow. Docker is mainly useful when you want a containerized setup.
How do I run OpenClaw on Docker?
Install Docker and Docker Compose v2, then run the OpenClaw Docker setup script from the OpenClaw repo. The setup will start the gateway and create the needed token.
Why is OpenClaw Docker not working?
Common reasons include old Docker Compose, low RAM, port 18789 already in use, wrong gateway token, permission issues, or missing mounted folders.
Can I run multiple OpenClaw setups with Docker?
Yes. Docker is useful if you want separate OpenClaw setups, such as one for daily use and another for testing plugins, updates, or client workflows.
Can I run OpenClaw Docker on a VPS?
Yes. Docker is a common way to run OpenClaw on a VPS or cloud server. Just make sure you set up storage, firewall rules, gateway access, and security properly.

Also Read

How to Run OpenClaw on Linux - Complete Guide
Installation

How to Run OpenClaw on Linux - Complete Guide

·
How to Install OpenClaw on a VPS (Step-by-Step Guide)
Installation

How to Install OpenClaw on a VPS (Step-by-Step Guide)

·
OpenClaw for Developers: AI Assistant for Developer Workflows
Use Case

OpenClaw for Developers: AI Assistant for Developer Workflows

·
Michael Park

Written by

Michael Park

Senior Technical Writer & DevRel

Michael creates comprehensive installation and setup guides for developers and system administrators. With experience across Linux, macOS, Windows, and embedded systems, he has written over 200 technical tutorials used by millions of developers. He focuses on clear, step-by-step instructions that work the first time, covering everything from Raspberry Pi to enterprise servers.

Run OpenClaw Without Managing Docker

Skip Docker setup, server maintenance, port errors, and manual configuration. Launch OpenClaw faster and start building useful AI workflows.

Deploy OpenClaw Now