OpenClaw Docker Compose setup

Why Docker Compose for OpenClaw

Docker Compose packages the OpenClaw runtime, relay service, and all required dependencies into a single reproducible environment. On any machine that runs Docker, the compose file produces identical behavior regardless of host OS version, installed tooling, or prior configuration. This eliminates the most common class of setup failures: missing or version-mismatched dependencies on the host system.

Compose environments are disposable by design. If an OpenClaw configuration becomes corrupted or you need a clean slate for a new project, run docker compose down -v to remove all containers, networks, and volumes, then docker compose up to start fresh. No uninstall scripts, no leftover registry entries, no permission drift.

Teams benefit most from Docker Compose because every developer on the project runs the exact same runtime environment. Version mismatches between local setups are a frequent source of bugs that appear on some machines but not others. With compose, if it works in your compose environment, it works on every teammate's machine.

• Environment reproducibility across Mac, Windows, and Linux
• No dependency conflicts with host-level tooling
• Easy teardown and reset between projects
• Team onboarding in minutes instead of hours

Prerequisites

Verify Docker is installed and the daemon is running with docker version. Both the client and server versions should be displayed. On macOS, Docker Desktop includes the Compose plugin automatically. On Linux, you may need to install it separately with sudo apt install docker-compose-plugin or your distribution's equivalent.

Allocate sufficient memory to Docker in Docker Desktop Settings > Resources. The default 2 GB is not enough for the OpenClaw runtime plus skill execution plus the relay browser context. Set it to at least 4 GB, and 8 GB if you plan to run more than one agent concurrently.

• Docker Desktop 4.25 or later, or Docker Engine 24 on Linux
• Docker Compose v2 plugin (docker compose command, not docker-compose standalone)
• 4 GB RAM allocated to Docker (8 GB recommended)
• 20 GB disk space for the OpenClaw image and volume data

Compose file setup

The official compose template is available in the ClawMesh GitHub repository under deploy/docker. Clone it or copy the compose.yaml file into your project directory. The template includes the OpenClaw runtime service, a named volume for persistence, and a health check that verifies the agent is responsive before marking the container as healthy.

Always pin the image tag to a specific version rather than using latest. Using latest causes unpredictable updates when the image is republished. Check the ClawMesh releases page for the current stable version and set the image tag accordingly: image: clawmesh/runtime:2.4.1.

Create a .env file in the same directory as compose.yaml with the required environment variables: CLAWMESH_WORKSPACE_ID, CLAWMESH_TOKEN, and CLAWMESH_RELAY_SECRET. These are your workspace credentials and should never be committed to version control. Add .env to your .gitignore file immediately.

• Create a clawmesh directory and clone or create the compose template
• Pin image tags to specific versions in the compose file
• Set required environment variables in a .env file
• Never commit .env files to version control

Running and validating

Start the environment with docker compose up -d. The runtime container will download if it is not already present, which may take a few minutes on a fresh install. After startup, the container runs a health check every 30 seconds. When the health check passes, the service is ready to accept tasks.

Attach a shell to the running container with docker compose exec runtime bash to run diagnostic commands. Run clawmesh doctor inside the container to verify that the relay, credentials, and network connectivity are all functional. Address any errors reported by the doctor command before submitting tasks.

The OpenClaw dashboard is accessible at localhost:8080 when the compose environment is running. The relay WebSocket endpoint is available at localhost:8081. These ports are exposed via the compose.yaml ports mapping and are independent of the host firewall configuration.

• Run docker compose up -d to start in detached mode
• Run docker compose logs -f to monitor startup
• Run clawmesh doctor in a compose exec shell to validate
• Submit one test task via the dashboard or CLI

Skill management in containers

Skill scripts can be mounted into the container via bind volumes during development, allowing you to edit skills on your host machine and test them inside the container without rebuilding. Add a volumes entry to the compose.yaml runtime service: - ./skills:/home/clawmesh/skills:ro.

For production deployments, bake skill sets into a custom image using the official image as a base. Create a Dockerfile that copies your skill scripts into the correct location and rebuild with docker build. This ensures skills are immutable and versioned alongside the runtime.

Never run skill activation on the host machine when using Docker Compose. Skills activated outside the container create local state that the container cannot see, causing confusion about which skill versions are actually active. Activate all skills inside the container environment.

• Mount skill directories as bind volumes for development
• Use named volumes for production skill caches
• Rebuild images when adding new built-in skills
• Run skill activation inside the container, not on the host

Teardown and reset

To pause the environment without losing state, use docker compose stop. This preserves the named volumes and container state. Resume with docker compose start. This is useful when you want to free up RAM without losing your agent configuration or task history.

For a complete teardown including all state, use docker compose down -v. This removes the containers, networks, and named volumes. On the next docker compose up, OpenClaw will start from a clean state as if it were the first run. Use this when migrating between major versions or when you need a guaranteed clean environment.

• docker compose down stops containers without removing data
• docker compose down -v also removes named volumes and resets state
• docker compose down --rmi local removes only locally-built images