OpenClaw Docker Setup

⚠️ Security Considerations

This skill involves elevated privileges and credential management. Review before running:

sudo operations — All Docker setup commands require elevated trust. Review references/docker-setup.sh before executing.
Tailscale remote access — Enables network access to your OpenClaw instance. Ensure your Tailscale network policy allows this and review your firewall rules.
Credential mounting — Mounting ~/.config/gh or other credential directories into containers exposes them to the container image. Only do this if you fully trust the image source.
Host file exposure — Volume mounts give containers access to host files. Be careful which directories you mount and which containers you run.
Port 18789 exposure — Do not expose port 18789 to the public internet. Bind to localhost (127.0.0.1) unless you have explicit firewall rules protecting it. For remote access, use Tailscale (see references/docker-config.md).
Token safety — The management script no longer prints full gateway tokens in terminal output. Tokens are masked to show only the first 4 characters.
Image pinning — Use specific version tags (e.g., ghcr.io/openclaw/openclaw:v1.2.3) instead of :latest for reproducible builds. The latest tag can change between container restarts.

Run OpenClaw inside Docker on Linux (Ubuntu 24.04+) with Tailscale for remote access.

Quick Start

Install Docker via APT (not Snap):
```
sudo apt install docker.io docker-compose && \
sudo usermod -aG docker $USER
```
Then log out and back in — sudo usermod doesn't take effect with newgrp.
Run onboard to configure gateway and get your token:
```
docker-compose run --rm openclaw-cli onboard
```
Create docker-compose.yml using the token from onboard. See references/docker-config.md for the full template and .env setup.
Start the container:
```
docker-compose up -d
```
Access at http://localhost:18789?token=YOUR_TOKEN

Key Concepts

bind: lan vs loopback — lan = accessible from the host via port mapping; loopback = locked inside container.
Tailscale on host, not container — Run Tailscale on the Ubuntu host for remote access.
One method only — Docker OR global install, never both (port + config conflicts).
Config path mapping — Host ~/.openclaw/ → Container /home/node/.openclaw/ (same files, different paths).
Docker group login — sudo usermod -aG docker requires full logout/login, not newgrp.

Common Usage

Generate a secure token:

openssl rand -hex 32

View container logs:

docker-compose logs -f openclaw

Run CLI commands inside container:

docker-compose run --rm openclaw-cli COMMAND_HERE

Fix volume permissions (Linux):

sudo chown -R 1000:1000 ~/.openclaw ~/openclaw

Approve Telegram pairing:

docker-compose run --rm openclaw-cli pairing approve telegram YOUR_CODE

Access via Tailscale (recommended — HTTPS):

sudo apt install tailscale
sudo tailscale up
./docker-setup.sh tailscale  # Starts tailscale serve on port 18789

Then visit https://YOUR_MACHINE_NAME.YOUR_TAILNET.ts.net?token=YOUR_TOKEN from any device on your tailnet. Use MagicDNS hostname over raw IP — it's HTTPS by default and more stable.

References

references/docker-config.md — docker-compose.yml, .env template, permissions, Tailscale, management script
references/quickstart.md — Simple 5-minute setup guide
references/docker-setup.sh — Management script (start/stop/logs/doctor/tailscale/approve_telegram)
references/gotchas.md — Critical mistakes and how to avoid them
references/troubleshooting.md — Common errors and fixes