Workflow:Openclaw Openclaw Docker Deployment
| Knowledge Sources | |
|---|---|
| Domains | DevOps, Containers, Cloud_Deploy |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
End-to-end process for deploying an OpenClaw gateway inside a Docker container, either locally for isolation or on a cloud provider for persistent 24/7 operation.
Description
This workflow covers containerized deployment of OpenClaw using Docker and Docker Compose. It starts with building the Docker image, running the interactive setup within the container, configuring persistent storage volumes, and starting the gateway as a long-running service. The same approach extends to cloud providers like Fly.io, GCP, DigitalOcean, and Hetzner where the container runs on a remote VM with persistent volumes.
Key outputs:
- Running containerized gateway accessible via HTTP/WebSocket
- Persistent state directory mounted as a Docker volume
- Configuration and credentials preserved across container restarts
- Optional cloud deployment with public or tunnel-based access
Usage
Execute this workflow when deploying OpenClaw in an isolated container environment, either for local development or remote hosting. This is ideal for users who want process isolation, reproducible environments, or always-on operation on a cloud VM.
Execution Steps
Step 1: Build the Docker Image
Build the OpenClaw Docker image from the provided Dockerfile or use the automated setup script. The image includes Node.js, the OpenClaw CLI, and all runtime dependencies. The setup script handles image building, directory initialization, and token generation.
Key considerations:
- Base image uses Node.js 22 LTS
- Build includes all npm dependencies (production only)
- Optional packages can be added via OPENCLAW_DOCKER_APT_PACKAGES environment variable
- Gateway auth token auto-generated for secure access
Step 2: Configure Persistent Storage
Set up Docker volumes or bind mounts for the state directory (~/.openclaw) to ensure configuration, credentials, sessions, and workspace data persist across container restarts.
What happens:
- Volume or bind mount created for /data (or ~/.openclaw inside container)
- Configuration file location set via OPENCLAW_STATE_DIR environment variable
- Workspace directory mounted (separate or within state dir)
- Optional extra mounts configured via OPENCLAW_EXTRA_MOUNTS
Step 3: Run Container Onboarding
Execute the onboarding wizard inside the container to configure model providers, channels, and workspace. This can be done interactively or via non-interactive mode with pre-set environment variables.
Key considerations:
- Interactive mode: docker compose run --rm openclaw-cli onboard
- Non-interactive: pass --non-interactive with provider flags
- Channel login (QR scan for WhatsApp) requires interactive terminal
- API keys and tokens can be injected via Docker secrets or environment
Step 4: Start the Gateway Service
Launch the gateway as a long-running Docker Compose service. The gateway binds to the configured port and interface, with health checks ensuring automatic restart on failure.
What happens:
- Docker Compose starts the gateway container in detached mode
- Gateway binds to lan interface (required for Docker networking)
- Health check endpoint polled for automatic restart
- Logs accessible via docker compose logs --follow
Step 5: Configure Cloud Provider (Optional)
For remote deployment, configure the cloud provider (Fly.io, GCP, DigitalOcean, Hetzner) with the appropriate manifest, volume provisioning, and secret management. Each provider has its own deployment tooling and configuration format.
What happens:
- Fly.io: fly.toml manifest configured, volume created, secrets set, deployed via fly deploy
- GCP: Compute Engine instance created, Docker installed, compose file deployed
- VPS providers: server provisioned, Docker and Compose installed, gateway started via systemd
- Persistent volume attached and mounted at /data
Step 6: Verify Remote Access
Confirm the containerized gateway is accessible and functioning. For local Docker, access via localhost. For cloud deployments, set up SSH tunnels, Tailscale, or configure bind mode for direct access.
Key considerations:
- Local: http://127.0.0.1:18789/ for Control UI
- Remote: SSH tunnel (ssh -N -L 18789:127.0.0.1:18789 user@host) or Tailscale
- Cloud: verify via provider CLI (fly status, gcloud compute ssh)
- Health check: curl http://localhost:18789/health