How to run OpenClaw with Docker

Short answer. Clone the OpenClaw repository and run ./scripts/docker/setup.sh with OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" set, so it uses the official pre-built image instead of building one (a source build needs at least 6 GB of RAM). The script runs onboarding, writes a Gateway token to .env and starts the Gateway with Docker Compose. Mount the state folder ~/.openclaw so nothing is lost when the container is replaced, and keep port 18789 closed to the internet: Docker's published ports go around UFW. Give the container at least 2 GB of memory; capped at 1 GB without swap, the official image was killed for lack of memory in our test.

Checked on 6 November 2026, accurate for OpenClaw 2026.11.1.

This guide uses OpenClaw's Docker documentation, the docker-compose.yml in its repository, and a test of the official image we ran on our own server (numbers below).

Do you need Docker at all?

OpenClaw's docs call Docker optional: useful for an isolated, throwaway Gateway or a host where you do not want Node.js installed. On a VPS that only runs OpenClaw, the plain npm install with a systemd service is the main route (see how to host OpenClaw 24/7). Docker is a good fit when you already run other things in containers.

What the official image is

• Where: ghcr.io/openclaw/openclaw (primary) and the Docker Hub mirror openclaw/openclaw. OpenClaw advises against unofficial mirrors.
• Tags: latest, exact releases such as 2026.11.1, -slim variants, and -browser variants that include Chromium for browser automation.
• Inside: it runs as the node user under tini, and its entrypoint runs openclaw doctor --fix on your mounted state before the Gateway starts, so image upgrades migrate the state for you. A built-in health check calls /healthz.

What we measured

We pulled ghcr.io/openclaw/openclaw:2026.11.1 on one of our Linux servers and started the Gateway twice with docker run (not Compose), no model, no chat app, no published port, limited to 1 CPU and with no swap: once with a 2 GB memory cap, once with 1 GB. Memory figures are in MiB, as Linux reports them.

OpenClaw's FAQ gives 1 GB as the absolute minimum for a VPS. With this release in a container capped at 1 GB, that was not enough. Plan on 2 GB or more, and more again for real conversations, several chat apps or a -browser image. More in how much memory OpenClaw needs.

Step by step with Docker Compose

1. Install Docker Engine and Docker Compose v2, then get the repository:

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

2. Run the setup script with the pre-built image:

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

   Without OPENCLAW_IMAGE, the script builds openclaw:local from source, which needs at least 6 GB of RAM; a build that ends in Killed or exit code 137 ran out of memory. The script asks for your provider API key, generates the Gateway token and writes it to .env, then starts the Gateway.
3. Open the dashboard at http://127.0.0.1:18789/ on the same machine and paste the token from .env into Settings. Need the link again: docker compose run --rm openclaw-cli dashboard --no-open.
4. Add a chat app:

   docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"
   docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

   New DMs start in pairing mode: message your bot, then run docker compose run --rm openclaw-cli pairing approve telegram <CODE>. More in connect OpenClaw to Telegram.
5. Check it:

   docker compose ps
   docker compose logs --tail=100 openclaw-gateway
   curl -fsS http://127.0.0.1:18789/healthz

For a host with no terminal prompts, OpenClaw documents a headless bootstrap: put the provider key, OPENCLAW_GATEWAY_TOKEN and TELEGRAM_BOT_TOKEN in .env, then run onboard --non-interactive and channels add --channel telegram --use-env through the Gateway container before docker compose up -d openclaw-gateway.

Persistence: what to mount and back up

• Mount the folder, never the single file. OpenClaw saves openclaw.json by replacing it, so a single-file bind mount can leave the container reading an old copy.
• Keep the state on a local disk. NFS, SMB and CIFS shares do not give SQLite the shared-memory coordination it needs and can corrupt it.
• One Gateway per state folder. Stop the old container before starting its replacement.
• Treat backups as secrets. OpenClaw's docs say OAuth tokens sit as plain text in those SQLite files.
• Anything you install inside a running container is lost when it is recreated. Extra tools go into the image at build time.

Keep the port private

The repository's docker-compose.yml publishes 18789 (and 18790 and 3978) on the host and starts the Gateway with --bind lan, so the published port reaches it. On a VPS that means the dashboard port is on the public address unless you block it. Two traps:

• UFW does not cover it. Published container ports go through Docker's own forwarding chains, not only the host's INPUT rules. OpenClaw's docs give rules for the DOCKER-USER chain; a cloud firewall that admits only SSH also works.
• Use a tunnel to reach the dashboard: ssh -N -L 18789:127.0.0.1:18789 root@<vps-ip>, then open http://127.0.0.1:18789/ on your own computer.

Compose also sets restart: unless-stopped, so the Gateway comes back after a crash or a reboot, and drops the NET_RAW and NET_ADMIN capabilities.

Updating

docker compose pull openclaw-gateway openclaw-cli
docker compose stop openclaw-gateway
docker compose up -d openclaw-gateway

The image's entrypoint repairs and migrates the mounted state on start. Back up ~/.openclaw first. With latest you move with each stable release; pin a tag such as 2026.11.1 to stay put.

Skip Docker: run OpenClaw on PlayNHost

A PlayNHost server is already an isolated container with its own memory limit, so there is nothing to compose. We do not use the official image: the server runs Node.js 26 and installs the openclaw npm package at the first start, then checks for a newer release at every start.

• Setup: paste an AI provider key and a Telegram or Discord bot token on the Agent page, then press Start. In our test of the same setup, the agent was running 67 seconds after the first Start, install included.
• Persistence: .openclaw lives on the server's disk and in its backups (about 4 MB in our test); the program and its caches are reinstalled, not backed up.
• Port: the Gateway listens only on the server's own loopback address, port 18789, with a token the panel generates. Nothing is published, so there is no firewall to get wrong.
• Memory: plans of 2 GB, 4 GB and 8 GB. The start refuses to run OpenClaw below 2 GB.
• Not included yet: the web dashboard, chat apps other than Telegram and Discord, and browser automation (no Chromium).

Create an OpenClaw server.

PlayNHost is not affiliated with the OpenClaw Foundation. OpenClaw is open-source software under the MIT licence.