Environment:Openclaw Openclaw Docker Deployment Environment
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Deployment |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Docker container environment based on `node:22-bookworm` for running the OpenClaw Gateway in containerized deployments (Docker Compose, Fly.io, Render).
Description
The Docker environment provides a self-contained deployment context for the OpenClaw Gateway. The base image is node:22-bookworm (Debian Bookworm with Node.js 22). Bun is installed at build time for build scripts. The container runs as a non-root user (`node`, uid 1000) for security hardening. By default, the gateway binds to loopback (127.0.0.1); for cloud deployments, `--bind lan` must be used to accept external connections. Memory is configured at 1536 MB heap (NODE_OPTIONS) within a 2048 MB container (Fly.io default).
Usage
Use this environment for Docker-based deployments including Docker Compose, Fly.io, Render, and similar container platforms. Required by the Docker Deployment workflow and any containerized OpenClaw installation.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| Base Image | `node:22-bookworm` | Debian Bookworm with Node.js 22 |
| Memory | 2048 MB container / 1536 MB heap | Fly.io defaults; Render uses starter plan |
| Disk | 1 GB+ persistent volume | Fly.io: `openclaw_data` at `/data`; Render: 1 GB at `/data` |
| Ports | 18789 (gateway), 18790 (bridge) | Fly.io remaps to internal port 3000 |
Dependencies
System Packages
- node:22-bookworm base image (includes Node.js 22, npm, Corepack)
- Bun (installed via `curl -fsSL https://bun.sh/install | bash`)
- Corepack (enabled for pnpm management)
- Optional: Custom APT packages via `OPENCLAW_DOCKER_APT_PACKAGES` build arg
Build-Time Environment Variables
- `OPENCLAW_DOCKER_APT_PACKAGES` — inject custom APT packages (e.g., for ARM/Synology)
- `OPENCLAW_A2UI_SKIP_MISSING=1` — skip missing canvas bundle during build
- `OPENCLAW_PREFER_PNPM=1` — force pnpm for UI build on ARM/Synology architectures
Credentials
The following environment variables should be set at runtime:
- `OPENCLAW_GATEWAY_TOKEN` or `OPENCLAW_GATEWAY_PASSWORD`: Authentication for gateway access (required for LAN-bound deployments)
- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`: Model provider credentials (at least one required)
- `OPENCLAW_STATE_DIR`: Override state directory (default: `/home/node/.openclaw` in container)
Quick Install
# Build and run with Docker Compose
docker compose up -d openclaw-gateway
# Or build manually
docker build -t openclaw .
docker run -d \
-p 18789:18789 \
-v openclaw_data:/home/node/.openclaw \
-e OPENCLAW_GATEWAY_TOKEN=your-token \
openclaw node dist/index.js gateway --allow-unconfigured --bind lan
Code Evidence
Dockerfile base image and security hardening from `Dockerfile:1,37-40`:
FROM node:22-bookworm
# Security hardening: Run as non-root user
# The node:22-bookworm image includes a 'node' user (uid 1000)
USER node
ARM/Synology compatibility from `Dockerfile:28-29`:
# Force pnpm for UI build (Bun may fail on ARM/Synology architectures)
ENV OPENCLAW_PREFER_PNPM=1
Fly.io memory configuration from `fly.toml:15,29`:
NODE_OPTIONS = "--max-old-space-size=1536"
memory = "2048mb"
Docker Compose port mapping from `docker-compose.yml:15-16`:
ports:
- "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
- "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `EACCES: permission denied` | Container running as root writing to node-owned dirs | Ensure `chown -R node:node /app` runs before `USER node` |
| Gateway not reachable from outside container | Default loopback bind | Use `--bind lan` in CMD or docker-compose override |
| `OOMKilled` | Insufficient container memory | Increase memory to 2048 MB; set `NODE_OPTIONS=--max-old-space-size=1536` |
| Bun build fails on ARM | Architecture incompatibility | Set `OPENCLAW_PREFER_PNPM=1` for UI build step |
Compatibility Notes
- ARM/Synology: Bun may fail on non-x86 architectures. Set `OPENCLAW_PREFER_PNPM=1` to force pnpm for UI builds.
- Fly.io: Internal port is remapped to 3000 for Fly's HTTPS proxy. Primary region defaults to `iad`.
- Render: Uses port 8080 by default. Disk limited to 1 GB on starter plan.
- Docker Compose: Provides two services: `openclaw-gateway` (WebSocket server) and `openclaw-cli` (utility with TTY).