Installing OpenClaw with Docker: step-by-step setup and deployment jour

#Install OpenClaw: official script or Docker?

The project documents two ways to install OpenClaw. The first uses a script that places the openclaw command directly on the system. The second runs the gateway (the central process that connects your messaging services to the model) in a Docker container. Both result in the same software and the same setup assistant, called onboarding.

Official script

The shortest path on a personal machine running macOS, Linux, or WSL2. The script installs the openclaw command and Node.js if needed, then onboarding registers the gateway as a service for your session.

Docker Compose

The gateway runs in a container, and nothing except Docker is installed on the host. This is the practical approach on a VPS, or when you want to delete everything in one move. The documentation presents it as optional.

What Docker does not change

The container retains full access to the configuration directory and workspace mounted from the host, as well as the network. It's a useful barrier, not a safe.

# Télécharger et exécuter l'installateur officiel
curl -fsSL https://openclaw.ai/install.sh | bash

# Lancer l'onboarding et installer le service
openclaw onboard --install-daemon

The rest of this guide follows the Docker path, with a reminder of the equivalent command for the script method in the update and uninstall steps. If you are still unsure about the tool itself, our “OpenClaw: What is it?” page addresses that question; here, we install it.

#Prerequisites

The gateway itself uses little power: it relays messages and calls a model. The requirements below mainly concern Docker and image building.

Docker and Compose v2

Docker Desktop on macOS and Windows (with WSL2), or Docker Engine with the Compose plugin on Linux. The command is written docker compose, with a space: the old docker-compose version 1 binary is not suitable.

Git

To clone the official repository, which contains the Dockerfile, the docker-compose.yml file, and the installation script.

Memory

The documentation requires at least 2 GB of RAM to build the image. On a 1 GB host, compilation may be terminated by the system for lack of memory (exit code 137). The prebuilt image, shown below, avoids this step.

Disk

Room for Docker images and logs. The documentation gives no figure: monitor space with docker system df.

A model

An API key from an online provider, with a spending limit, or a local model. Connecting a local model is a separate topic that this guide does not cover.

On a VPS

Key-based SSH access and the provider’s firewall configured to allow only SSH in. No other port needs to be open, as we’ll see.

docker --version
docker compose version
git --version

On Windows, work from a WSL2 terminal: the installation script is a shell script, and the documentation directs Windows users to WSL2 anyway. Whatever the machine, avoid one that contains your personal documents and passwords: an agent capable of executing commands should run on a dedicated machine, virtual machine, or rented server.

#Install OpenClaw with Docker Compose, step by step

The Docker installation relies on a script provided in the repository. It handles image preparation, onboarding, and gateway startup in sequence. The four steps below follow that order.

#1. Clone the official repository

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Check the address character by character: it's the openclaw organization on GitHub, not a repository with a similar name. The Docker installation script is called docker-setup.sh at the repository root in the documentation we know. The project often reorganizes its files, and recent versions may place it under scripts/docker/: the following command shows which one exists on your system.

ls docker-setup.sh scripts/docker/setup.sh 2>/dev/null

#2. Choose between a prebuilt image and a local build

By default, the script builds the image on your machine from the Dockerfile and names it openclaw:local. This is the most transparent approach, since you compile the code you just cloned, but it requires memory and compute time. The alternative is to download the image published by the project from the GitHub registry by setting the OPENCLAW_IMAGE variable before launching the script.

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"

The latest tag tracks the most recently released version. On a server, it’s better to replace it with a specific version number taken from the repository’s releases page: you then decide when to update, and you know which version to roll back to if something goes wrong.

#3. Run the installation script

./docker-setup.sh

According to the documentation, this script does five things in sequence:

Image

It builds the image locally, or downloads it if OPENCLAW_IMAGE is defined.

Onboarding

It launches the setup assistant in a temporary container.

Token

It generates the gateway access token and writes it to a .env file at the repository root.

Startup

It starts the gateway with Docker Compose under the openclaw-gateway service name.

Data

It places the configuration and workspace on the host, in ~/.openclaw and ~/.openclaw/workspace. These folders survive container deletion.

#4. Respond to onboarding

The assistant asks questions about the model, messaging, and the gateway. For this last part, the script displays the expected answers in a container. They differ from those in a standard installation, and the first one warrants an explanation.

Gateway bind: lan

Inside the container, the gateway must listen on the Docker network interface; otherwise, the port published to the host can't reach it. This setting doesn't determine what is visible from outside: that is handled on the host; see the VPS section.

Gateway auth: token

Access to the gateway's interface and API requires a token.

Gateway token

Use the one the script just displayed so that it matches the .env file.

Tailscale exposure: Off

No automatic exposure. Remote access is decided later, with full awareness of the implications.

Install Gateway daemon: No

In this setup, Docker Compose restarts the container—not a system service.

For the model, provide a budget-limited API key instead of your primary key. For messaging services, you can skip this step and return to it once the gateway has been verified. Remember the conversion rule: any documentation command that starts with openclaw is run here by prefixing it with docker compose run --rm openclaw-cli.

# WhatsApp : affiche un QR code à scanner depuis le téléphone
docker compose run --rm openclaw-cli channels login

# Telegram : avec le jeton du bot créé auprès de BotFather
docker compose run --rm openclaw-cli channels add --channel telegram --token "<jeton-du-bot>"

#Verify that the gateway is running

Before connecting anything else, make sure the container is running and its logs show no errors.

docker compose ps
docker compose logs -f openclaw-gateway

Then open the control interface in a browser on the same machine and paste the token into its settings. If you lost the link, the dashboard command displays it again without trying to open a browser.

http://127.0.0.1:18789/

docker compose run --rm openclaw-cli dashboard --no-open

Two built-in checks complete the verification. The first diagnoses the installation and configuration; the second reviews dangerous settings. Run them again after every configuration change.

docker compose run --rm openclaw-cli doctor
docker compose run --rm openclaw-cli security audit --deep

One last step: protect the .env file. It contains the gateway token, and anyone who has that token controls the agent—and therefore everything the agent can access. chmod 600 .env limits read access to your account. Do not copy it into a Git repository or a screenshot.

#OpenClaw on a VPS: do not expose the gateway

On a PC behind a router, a port published by Docker remains on the local network. On a VPS, the machine has a public address: a published port without a specified address is reachable from the entire Internet. In early 2026, researchers identified thousands of OpenClaw gateways accessible this way. The token protects access, but a single vulnerability is enough to bypass it: the CVE-2026-25253 vulnerability, fixed in late January 2026, could specifically be used to steal it. The proper posture is to expose nothing at all.

docker compose port openclaw-gateway 18789
ss -tlnp | grep 18789

If the response starts with 0.0.0.0, the port is exposed on all interfaces. Three layers of protection stack up, from the outermost to the one closest to the container.

Provider firewall

The filtering proposed in the hosting provider's console acts before the machine, and therefore before Docker. Allow only SSH through it.

Published on 127.0.0.1

Tell Docker to publish the port only on the host's local address, using the file below.

Tunnel access

Access the control interface through an SSH tunnel or VPN, never through a public address.

services:
  openclaw-gateway:
    ports: !override
      - "127.0.0.1:18789:18789"
      - "127.0.0.1:18790:18790"

This file is an example from us, not an excerpt from the OpenClaw documentation: compare the service name and port list with your version's docker-compose.yml before using it. The !override label replaces the port list rather than adding to it; it requires Docker Compose 2.24.4 or later. Place the file next to docker-compose.yml, recreate the container with docker compose up -d openclaw-gateway, then run the check again: it should now respond 127.0.0.1:18789.

ssh -N -L 18789:127.0.0.1:18789 utilisateur@adresse-du-vps

As long as this tunnel is open, the http://127.0.0.1:18789/ address of your computer leads to the server's gateway. Messaging apps don't need any inbound port in their normal operating mode: for WhatsApp, Telegram, or Discord, the gateway opens outbound connections. So there is no reason to expose the control interface behind a domain name. The reasoning is the same as for a model server, detailed in our guide to securing a Ollama server.

#Update OpenClaw

The project releases versions at a rapid pace, and some fix vulnerabilities. Leaving an installation untouched for months is a risk, not a time saver. With Docker, updating means replacing the image and recreating the container; your data in ~/.openclaw remains unchanged.

1. 01
   Back up the data folder

   Archive ~/.openclaw before any update. A new version may migrate the configuration, and rolling back is reliable only with a copy of the previous state.
2. 02
   Get the new version

   Update the repository with git pull to get the current Dockerfile and Compose file, then rebuild the local image or download the published image, depending on the choice made during installation.
3. 03
   Recreate the container

   Restart the openclaw-gateway service. Docker Compose replaces the container as soon as it detects a different image.
4. 04
   Control

   Run doctor, read the last lines of the logs, and send a test message from your email client.

tar czf openclaw-sauvegarde-$(date +%F).tar.gz -C ~ .openclaw

cd openclaw
git pull
docker build -t openclaw:local -f Dockerfile .
docker compose up -d openclaw-gateway

cd openclaw
git pull
docker compose pull openclaw-gateway
docker compose up -d openclaw-gateway

docker compose run --rm openclaw-cli doctor
docker compose logs --tail 50 openclaw-gateway

The published image variant assumes that the OPENCLAW_IMAGE line is present in the .env file, which the script adds when the variable was defined during installation. If you pinned a version number, edit this line first. To roll back, restore the old number, recreate the container, and, if the configuration was migrated in the meantime, restore the backup.

With the script method, the update runs through the built-in command, followed by the same diagnostic.

openclaw update
openclaw doctor

#Uninstall OpenClaw cleanly

A complete uninstall removes three things: the containers and images, the data on disk, and the access you had entrusted to the assistant. The third is the one people forget.

cd openclaw
docker compose down

# Supprimer l'image utilisée (l'une ou l'autre selon votre cas)
docker image rm openclaw:local
docker image rm ghcr.io/openclaw/openclaw:latest

# Vérifier qu'il ne reste ni conteneur ni volume
docker ps -a --filter name=openclaw
docker volume ls --filter name=openclaw

The ~/.openclaw directory contains the configuration, API keys, messaging sessions, and the assistant’s memory. Its deletion is irreversible: keep an archive if you think you may return someday, or if you want to reread what the assistant had recorded. The cloned repository, for its part, contains the .env file and its token.

rm -rf ~/.openclaw

# Le dépôt cloné, avec son fichier .env
cd ..
rm -rf openclaw

API keys

Revoke the key entrusted to OpenClaw with the model provider. Deleting the local file does not invalidate it.

Telegram or Discord bot

Revoke the bot's token or delete the bot from the service's tool (BotFather for Telegram, developer portal for Discord).

WhatsApp

In the app, open the list of connected devices and disconnect the one corresponding to the gateway.

Network access

Remove the firewall rule, tunnel, or VPN machine created for the occasion. If you rented a VPS solely for this purpose, terminate the server.

With the script method, the built-in uninstall command removes the service and offers to delete the data; you then still need to remove the command itself.

openclaw uninstall
npm rm -g openclaw

#Troubleshooting: the most common blockers

“unauthorized” or “pairing required (1008)”

The browser has not yet been approved by the gateway. Display the access link again, then list and approve the device using the commands below. This is common in Docker and behind a tunnel because the connection does not come from the container's local address.

Build interrupted, code 137

The system killed the compilation due to insufficient memory. Switch to the image published with OPENCLAW_IMAGE, or use a machine with at least 2 GB of RAM.

Permission denied on /home/node/.openclaw

The image runs as the node user, with ID 1000. Directories mounted from the host must belong to that user: sudo chown -R 1000:1000 ~/.openclaw.

Port 18789 already in use

Another service, or an older OpenClaw installation, is occupying the port. Stop it, or change OPENCLAW_GATEWAY_PORT in the .env file before recreating the container.

docker compose introuvable

You have the old docker-compose binary or no Compose plugin. Install your distribution's Compose v2 plugin.

Local model unreachable

In a container, localhost refers to the container, not the host. So a Ollama listening on http://localhost:11434 on the host is not directly visible from the gateway. This setting concerns model integration and is outside the scope of this guide.

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

When none of this fits, the service logs remain the best starting point, followed by the doctor command. Before looking elsewhere for a solution, check the date of the answers you find: those mentioning Clawdbot or Moltbot describe older commands.

#Official sources to keep handy

This guide is not based on any in-house testing: it contains no duration, measurements, or numerical comparisons. The commands are taken from the project's documentation, which changes from one version to the next: script names, variables, and onboarding steps. If this page and the documentation differ, the documentation takes precedence.

https://docs.openclaw.ai/install/docker

https://docs.openclaw.ai/install/updating

https://docs.openclaw.ai/install/uninstall

https://docs.openclaw.ai/gateway/security

https://github.com/openclaw/openclaw/releases

#Go further

Installation is only half the work: an agent must be configured, monitored, and benchmarked. These site guides build on the concepts used here.

OpenClaw: what is it, and should you install it?

How the gateway works, its uses, and its risks, so you can decide before installing. https://quelllm.fr/guide/openclaw-c-est-quoi

Secure a Ollama server

Firewall, local listening, and remote access: the same minimal-exposure logic applied to the model server. https://quelllm.fr/guide/securiser-serveur-ollama

Deploy an LLM with Docker Compose in production

Compose files, restarts, logs, and backups for a stack that runs continuously. https://quelllm.fr/guide/deployer-llm-docker-compose-production

Install Ollama with Docker

To run the model server in a container, on the same machine or another one. https://quelllm.fr/guide/ollama-docker-installation-guide

Agent Zero with Ollama in Docker

Another self-hosted agent delivered in a container, for comparing approaches. https://quelllm.fr/guide/agent-zero-ollama-docker