OpenClaw Docker Starter

This repository provides an OpenClaw deployment flow built on a single Docker Compose stack:

• Build the latest OpenClaw image via the official OpenClaw setup script
• Access OpenClaw directly at http://localhost for local development
• Deploy to production with Traefik + Let's Encrypt HTTPS by setting DOMAIN_NAME, SSL_EMAIL, and the Traefik router env vars
• Keep the AI provider configuration generic — you choose the provider from the UI

Repository Structure

.
├── .env.example
├── docker-compose.yml
├── Makefile
└── scripts/
    ├── build-latest-image.sh
    ├── local-up.sh
    └── traefik-cmd.sh       # starts Traefik in local HTTP or production HTTPS mode

Prerequisites

• Docker Engine + Docker Compose plugin
• Git
• Bash

Check your setup:

docker --version
docker compose version
git --version

Quick Start

1. Copy the environment template:

cp .env.example .env

2. Build the image and start the stack:

make up

3. Open http://localhost.

4. If Control UI asks for auth, copy the token printed in the terminal and paste it manually into Control UI settings.

The first run will:

• Create local folders for config and workspace
• Clone OpenClaw and run the official ./scripts/docker/setup.sh
• Build the image and generate/sync OPENCLAW_GATEWAY_TOKEN
• Start Traefik + OpenClaw

Commands

make up          # build image + start stack
make down        # stop stack
make logs        # follow gateway logs
make rebuild     # rebuild image + restart
make build-image # build image only
make token       # show current gateway token

Local access: http://localhost

Configuration Details

Environment Variables

Main variables in .env:

• OPENCLAW_IMAGE: local tag for the built image
• OPENCLAW_UPSTREAM_REPO: upstream source repository
• OPENCLAW_BUILD_REF: latest-release, main, or a specific tag/branch
• OPENCLAW_GATEWAY_TOKEN: auth token (auto-generated on first make up)
• DOMAIN_NAME: your production domain (used by Traefik routing labels)
• SSL_EMAIL: Let's Encrypt email — leave empty for local dev; set to your email for production HTTPS
• TRAEFIK_ROUTER_ENTRYPOINTS: web for local, websecure for production
• TRAEFIK_ROUTER_TLS: false for local, true for production
• TRAEFIK_CERTRESOLVER: empty for local, letsencrypt for production

OpenClaw Config File

The bootstrap creates .openclaw/openclaw.json (if missing) with:

• Gateway token auth mode
• Local allowed origins (localhost and 127.0.0.1)
• No preconfigured model provider (you choose later)

You can configure your preferred provider later from OpenClaw onboarding/UI or by editing the file manually.

Troubleshooting

Build fails when resolving latest release

Set a fixed ref in .env:

OPENCLAW_BUILD_REF=main

or a specific tag:

OPENCLAW_BUILD_REF=vX.Y.Z

Gateway token errors

Delete OPENCLAW_GATEWAY_TOKEN value in .env (or set CHANGE_ME) and run:

make up

The build step syncs the token generated by the official OpenClaw setup script back into your local .env.

Production HTTPS

On your VPS:

1. Clone this repo and copy .env.example to .env.
2. Set DOMAIN_NAME=openclaw.your-domain.com and SSL_EMAIL=your@email.com.
3. Set TRAEFIK_ROUTER_ENTRYPOINTS=websecure, TRAEFIK_ROUTER_TLS=true, and TRAEFIK_CERTRESOLVER=letsencrypt.
4. Point your domain's DNS A record to the VPS IP.
5. Open ports 80 and 443 on the server firewall.
6. Run make up.

Traefik will automatically obtain a Let's Encrypt certificate for your domain on first start.

Security Notes (Before Making This Public)

• Never commit .env, .openclaw/, workspace/, or .tmp/ (already covered by .gitignore).
• Rotate OPENCLAW_GATEWAY_TOKEN if you ever shared terminal output/screenshots with the full token.
• Prefer HTTPS in production: set TRAEFIK_ROUTER_ENTRYPOINTS=websecure, TRAEFIK_ROUTER_TLS=true, and TRAEFIK_CERTRESOLVER=letsencrypt.
• Restrict network exposure at the VPS/firewall level to ports 80/443 only; do not publish internal service ports.
• Keep Docker, Traefik, and OpenClaw updated regularly to receive security fixes.
• Review gateway.trustedProxies and allowedOrigins in .openclaw/openclaw.json if deploying behind a reverse proxy in non-local environments.
• Container hardening is enabled in docker-compose.yml (read-only filesystem for Traefik, dropped Linux capabilities, no-new-privileges, and log rotation limits).

Personal Project Disclaimer

This repository is a personal project provided "as is", without warranties of any kind, express or implied.

By using, deploying, or modifying this project, you accept full responsibility for your own infrastructure, data, compliance, and security posture.

The author is not liable for any direct or indirect damages, data loss, service interruptions, security incidents, or other issues resulting from the use of this repository.

For legal terms, see LICENSE and DISCLAIMER.md.