This OpenClaw Docker guide runs the agent inside an Ubuntu VM. Install Docker Engine with the Compose plugin, and clone the OpenClaw repo. Then run the official setup script with a pinned pre-built image. The script asks for your model API key, creates a gateway token and starts the stack. Before you use it, bind the dashboard port to localhost and reach it over an SSH tunnel.
Who this is for: you want to try OpenClaw, the open-source personal AI agent (once called Clawdbot and Moltbot), in a setup you can throw away and rebuild.
Why a VM and Docker, not your main computer
OpenClaw connects a language model to your chat apps, your files and a shell. That power is the point, and it is also the risk. On 31 January 2026, Censys counted 21,639 OpenClaw instances reachable on the internet. In early February, security researchers reported hundreds of malicious skills on ClawHub, the public skill registry. As of 9 October 2026, the project's GitHub page lists more than 700 security advisories, most of them fixed.
None of that means "do not use it". It means "do not run it next to your personal data". Two layers help:
- The VM gives OpenClaw its own operating system, kernel and disk. Your laptop is out of reach, and snapshots let you undo anything.
- Docker inside the VM gives you a pinned image, a clear list of data folders and a one-command rebuild.
Docker alone shares the host kernel, so it isolates less than a VM. The guide to containers vs virtual machines explains the difference. Here you get both.
What you need
- A hypervisor. Proxmox VE on a spare PC, VMware Workstation or Fusion, or VirtualBox. See VMware vs VirtualBox vs Proxmox if you have not picked one. As of October 2026, OpenClaw publishes images for AMD64 and ARM64, so an ARM Ubuntu VM on an Apple Silicon Mac is a valid target.
- Ubuntu Server 24.04 LTS. The OpenClaw docs say Linux is fully supported and give Ubuntu setup steps. As of October 2026, they do not publish a tested list of distribution versions.
- A model. An API key from a provider such as Anthropic, OpenAI or OpenRouter, or a local model server such as Ollama.
VM size
OpenClaw publishes no general minimum for a Linux server. Its Raspberry Pi page states 1 GB of RAM, 1 core and 500 MB of disk as a floor. Building the Docker image from source needs at least 6 GB of RAM, but a pre-built image avoids that. The sizes below are my suggestion for a comfortable lab VM, not an official figure.
| Resource | Suggested | Note |
|---|---|---|
| vCPUs | 2 | One is enough to start |
| RAM | 4 GB | Use the pre-built image. A source build needs 6 GB or more. |
| Disk | 32 GB | OS, Docker images, workspace and snapshots |
| Network | NAT | OpenClaw needs outbound access only |
Step 1: Create the VM and install Docker
Create the VM, install Ubuntu Server with the OpenSSH server, and log in as your normal user. Update the system:
sudo apt update && sudo apt upgrade -y
sudo apt install -y gitInstall Docker Engine and the Compose plugin with the steps on the Docker Engine install page for Ubuntu. Use Docker's own repository, not the older docker.io package, so you get Compose v2. Check both tools:
docker --version
docker compose versionShut down the VM and take a snapshot called docker-ready. This is your clean return point.
Step 2: Get the OpenClaw Docker Compose files
The Docker setup runs from a checkout of the official repo:
git clone https://github.com/openclaw/openclaw.git
cd openclawPick a version and pin it. As of 8 October 2026, the latest stable release was 2026.9.9. Check the releases page for the current one, and use that tag in place of latest:
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:2026.9.9"A pinned tag means the agent does not change under you when you restart. Only download images from ghcr.io/openclaw/openclaw or the openclaw/openclaw Docker Hub mirror. The docs warn against unofficial mirrors.
Step 3: Close the ports before first start
This step is not in the quick start, and it matters. Open docker-compose.yml and find the ports: block of the openclaw-gateway service. As of October 2026, it publishes three ports on every network interface:
ports:
- "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
- "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
- "${OPENCLAW_MSTEAMS_PORT:-3978}:3978"Port 18789 serves the dashboard and the WebSocket API. Port 3978 is for Microsoft Teams. The old bridge on port 18790 is gone. Current builds use 18790 only if you turn on MCP Apps. If you do, add a second localhost line for it and tunnel it too. Change the block so the gateway listens on the VM's localhost only, and drop the ports you do not use:
ports:
- "127.0.0.1:${OPENCLAW_GATEWAY_PORT:-18789}:18789"Why edit the file? The container binds the gateway to the LAN by default, and the OpenClaw security docs say so plainly. Also, ports that Docker publishes skip the host's normal firewall rules, so UFW alone does not protect them. The gateway still requires a token, but a closed port is a stronger default. Keep a note of this change, because git pull may conflict with it later.
Step 4: Run the setup script
From the repo folder, run the official script:
./scripts/docker/setup.shWith OPENCLAW_IMAGE set, the script pulls the pre-built image instead of building one. It then asks for your model provider's API key, writes a gateway token to .env and starts the gateway with Docker Compose. The full flow is on the OpenClaw Docker page.
Check that the stack is up:
docker compose ps
docker compose logs -f openclaw-gatewayStep 5: Open the dashboard over an SSH tunnel
From your own computer, open a tunnel to the VM:
ssh -N -L 18789:127.0.0.1:18789 you@vm-addressKeep local port 18789. The setup script allows only that origin for the dashboard.
Then, in the VM, print the dashboard link:
docker compose run --rm openclaw-cli dashboard --no-openOpen the link in your browser. If the page says pairing required or unauthorized, approve your browser as a device:
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>Add a chat channel (optional)
The docs suggest Telegram first, because it needs only a bot token. Run the CLI through Compose:
docker compose run --rm openclaw-cli channels add --channel telegram --token <bot-token>Start the line with a space, or clear it from your shell history afterwards, so the token is not saved. Unknown senders get a pairing code by default. Leave that on.
Step 6: Harden the install
- Run the audit.
docker compose run --rm openclaw-cli security auditchecks your config against the safe defaults. - Treat skills as untrusted code. The docs say to read a skill before you enable it. A clean ClawHub scan does not prove a skill is safe.
- Tighten tools with the hardened baseline. The OpenClaw security docs list it. It denies shell commands, limits file access to the workspace and turns off elevated tools. In Docker, copy only its
toolsandchannelssettings. Leavegateway.bindaslanand keep the token that setup created. A loopback bind inside the container makes the dashboard unreachable. - Keep secrets out of the VM. Do not sign the agent into accounts it does not need.
- Leave the Docker socket mount off. It is commented out in the compose file. Mounting it gives the container control of Docker on the VM.
Snapshots, backups and rollback
OpenClaw keeps its state in three folders on the VM, mounted into the container:
~/.openclaw: config, the.envfile and the SQLite databases~/.openclaw/workspace: the agent's working files~/.openclaw-auth-profile-secrets: auth profile secrets
The docs warn that OAuth tokens sit in plain text in SQLite under the config folder. Treat every copy of these folders as a password vault.
Also, never copy live .sqlite, -wal or -shm files. Stop the stack first:
docker compose down
sudo tar czf ~/openclaw-backup-$(date +%F).tar.gz ~/.openclaw ~/.openclaw-auth-profile-secrets ~/openclaw/.env ~/openclaw/docker-compose.yml
docker compose up -d openclaw-gatewayThe repo's .env holds the image pin and the gateway token, so the archive is a secret. Encrypt it before it leaves the VM.
A safe upgrade routine
- Take a VM snapshot.
- In the repo folder, edit
.envand setOPENCLAW_IMAGEto the new version tag. - Run
docker compose pull openclaw-gateway openclaw-cli. - Run
docker compose up -d openclaw-gateway. - Test one simple task.
- If it fails, revert the snapshot. Do not just switch the tag back, because the new version may have migrated the database.
On start, the image runs openclaw doctor --fix and saves SQLite backups ending in .pre-startup-migration-<id>.bak. Still, the docs say a downgrade does not reverse config or database changes. That is why the VM snapshot is your real rollback.
Troubleshooting
| Symptom | Fix |
|---|---|
EACCES on /home/node/.openclaw | The image runs as user ID 1000. Run sudo chown -R 1000:1000 ~/.openclaw ~/.openclaw-auth-profile-secrets. |
| Build killed, exit code 137 | Out of memory. Use a pre-built image with OPENCLAW_IMAGE. |
pairing required or disconnected (1008) | Run devices list, then devices approve, as in step 5. |
origin not allowed | Add your dashboard URL to gateway.controlUi.allowedOrigins. |
EADDRINUSE | Another gateway uses the port. Stop it or change OPENCLAW_GATEWAY_PORT. |
| Config change has no effect | docker compose restart does not reload env changes. Run docker compose up -d openclaw-gateway. |
Skill fails with brew not installed | The image has no Homebrew. Build a local image with OPENCLAW_IMAGE_APT_PACKAGES set (a source build needs 6 GB of RAM), or build your own image on top of the official one. |
For anything else, run docker compose run --rm openclaw-cli doctor --json and read the findings. If that does not fix it, revert the snapshot and start again.
Docker or the native install?
OpenClaw also has a one-line native installer that sets up Node.js and a systemd service. On a host install, the gateway binds to loopback by default. The Docker route gives you a pinned image and easy rebuilds. The native route gives you openclaw update and fewer moving parts. In a VM, both are fine. If you also want to try Hermes Agent, read the Hermes Agent Ubuntu VM guide, then the Hermes vs OpenClaw comparison.
FAQ
What port does OpenClaw use?
The gateway uses port 18789 for the dashboard and the WebSocket API. As of October 2026, the compose file also publishes 18790 and 3978 (Microsoft Teams). Bind 18789 to localhost and reach it with an SSH tunnel or Tailscale.
How much RAM does OpenClaw need in Docker?
A pre-built image runs in far less than a source build. The docs say a source build needs at least 6 GB of RAM. For a lab VM, 4 GB with a pre-built image is a comfortable start.
Is OpenClaw safe to run?
It is as safe as your setup. Keep the gateway off the public internet, use token auth, read every skill before you enable it, and keep personal accounts out of it. A VM with snapshots limits the damage if something goes wrong.
Is a VPS better than a home VM for OpenClaw?
A VPS runs around the clock and needs no hardware at home. A home VM keeps your data on your own machine and costs nothing extra. On either, use an SSH-only firewall and never expose the gateway port directly.
Can I run OpenClaw on Proxmox?
Yes. Create an Ubuntu VM on Proxmox and follow this guide. As of October 2026, OpenClaw has no official Proxmox page, so treat the VM as any Linux Docker host. See what Proxmox VE is if you are new to it.
How do I update OpenClaw in Docker?
Take a snapshot, set the new tag in the repo's .env file, run docker compose pull, then docker compose up -d openclaw-gateway. Avoid latest, so you know which version you run.
No comments:
Post a Comment