For OpenClaw production, Docker or local npm?

Choose Docker Compose when you need reproducible runtimes and isolation across the team; choose local npm or installers for rapid source-level debugging. Many teams develop locally and run the Gateway in containers in production.

Gateway won't start—what to check first?

Port conflicts, health-check paths, outbound HTTPS from the container to model vendors, and volume permissions for state directories. Align defaults with the docs for the exact image tag you pinned.

How do I roll back after a bad upgrade?

Record the running image digest and compose revision; stop the Gateway; restore volume snapshots; bring the stack back with the previous tag. Avoid anonymous latest pulls in production.

2026 OpenClaw Production: Docker, Always-On Gateway, Troubleshooting & Rollback

About 16 min read · MACCOME

You installed OpenClaw per platform, but production needs a 24/7 Gateway, sane Docker volumes, and upgrades that do not erase state. This runbook targets teams who want Agents as contractable services: a preflight checklist, Docker vs npm trade-offs, Compose patterns for always-on processes, a symptom triage table, and a token, logging, backup, and rollback sequence. Pair it with the Windows/macOS/Linux install guide and, when you need a stable egress host, with the remote Mac execution layer below.

Six traps when moving from “it runs” to “it’s on-call”

Using a dev laptop as the only Gateway: sleep, updates, and GUI prompts break sessions; incident time often exceeds a dedicated node.
Tracking latest anonymously: upstream can change ports or config schemas overnight—CI pulls become silent releases.
Volume UID fights: state directories owned by root vs the container user surface as vague SQLite or I/O errors.
Egress not aligned with model vendors: corporate proxies or regional blocks show up as timeouts, not crisp 403s.
Gateway tokens in git plaintext: mixing CI and laptop secrets magnifies offboarding and fork risk.
No rollback script besides “reinstall”: you cannot report RTO or repeat recovery reliably.

If Windows vs macOS vs Linux paths are still fuzzy, read OpenClaw install & platform choice first, then return here for containerization.

Preflight: Node, memory, keys, and egress (15-minute checklist)

Community installers and Docker images evolve; use these as order-of-magnitude planning numbers and verify against the release you pin.

Runtime: many 2026 docs anchor on Node 20 LTS or 22; images usually bundle a tested runtime while the host only needs a current Docker Engine and Compose plugin.
Memory: plan 2–4 GB container limit for a light Gateway; add headroom for concurrent channels or local models.
Secrets: separate least-privilege keys for vendors vs gateway auth; rotate both the orchestration secret and mounted files together.
Egress: probe vendor APIs from the same network path as the Gateway; validate corporate MITM roots and proxies.

Dimension	Docker Compose (production-leaning)	Local npm / installer (iteration-leaning)
Reproducibility	High: image pins dependencies	Medium: global Node/OS drift
Isolation / multi-instance	Easy: networks, volumes, limits	Harder: port and config clashes
Upgrade cadence	Controlled: tag or digest roll	Fast: track upstream main
Debugging	`exec` or bind-mount sources	Direct debuggers and breakpoints
Operational cost	Pulls, volume backups, compose hygiene	Host pollution, daemon consistency

bash

# Illustrative flow—service names follow the pinned release docs
git clone https://github.com/openclaw/openclaw.git && cd openclaw
# if provided: bash docker-setup.sh
# docker compose pull
# docker compose run --rm <cli-service> onboard
# docker compose up -d <gateway-service>
# docker compose ps
# curl -fsS http://127.0.0.1:<health-port>/health || echo "see docs for path"

warning

Warning: service names, env vars, and health paths change across releases—treat snippets as patterns, not gospel, and verify against the tag you froze.

Six steps to keep the Gateway resident on Compose

Pin versions: set image tags or digests in compose; ban anonymous drift in production.
Split volumes: separate config, state, and logs; tune backup RPO per volume class.
Dependencies & restart: restart: unless-stopped handles crashes, not bad configs—still add health checks.
Health checks: use vendor HTTP/TCP probes; align semantics with your LB or watchdog.
Observability: keep at least one searchable log path (stdout or file) for alert wiring.
Change control: every port/volume/env change gets a diff plus rollback tag—no “verbal infra.”

Symptom	Likely cause	Ordered actions
Gateway exits immediately	Missing env, entrypoint change	Read compose logs; diff required keys vs release notes
Port in use	Stale process or host conflict	`ss -lntp`; remap or stop the owner
Model timeouts	Egress, proxy, DNS, region	curl from inside container; inspect certs/proxy
SQLite / lock errors	Dual writers, UID mismatch	Ensure one primary writer; fix volume ownership

Production hardening: tokens, exposure, backups, rollback order

Inject gateway tokens via secrets—not image layers. If HTTP must be public, terminate TLS and rate-limit in front; even internal listeners should assume lateral movement.

Rollback order: ① record running digest + compose revision; ② stop Gateway; ③ restore volume snapshot; ④ docker compose up -d with the previous tag; ⑤ run health checks plus one end-to-end probe.

Three measurable ops review criteria

Cold start to healthy: track P95 from compose up to probe success—if it spikes, inspect pulls and volume I/O before buying CPU.
Error mix vs latency: split 4xx/5xx from TCP timeouts so throttling is not misread as a dead Gateway.
Restore drills: quarterly restore volumes to an isolated host and boot Gateway—publish RTO numbers, not vibes.

When to host the Gateway on an always-on remote Mac

Teams that co-locate Apple toolchain work—Xcode builds, Simulator, signing—with Agents benefit from moving Gateway off personal laptops onto dedicated, billable 24/7 Mac metal. Default to SSH for daemons and logs, VNC only when GUI triage is required—see SSH vs VNC guide.

Why laptops alone rarely become production Gateways

Laptop pilots struggle with sleep policies, uncoordinated OS updates, and leaked ports when multiple humans debug. Containers without pinned digests only hide host drift behind a false sense of reproducibility.

The maintainable pattern is Compose-pinned runtimes on dedicated remote Macs (or equivalent bare metal) as the execution plane. MACCOME cloud Macs provide multi-region Apple Silicon with clear rental terms—useful when OpenClaw shares the same host as iOS/macOS automation. Compare regions with the multi-region guide and public rental rates, then order Singapore, Tokyo, Seoul, Hong Kong, US East, or US West.

Session help: Help Center.

FAQ

Docker or npm for production?

Compose for reproducibility; local npm for deep debugging. Start with install & platform choice to stage the path.

Gateway down—first checks?

Ports, health paths, container egress, volume permissions. Browse Help Center for SSH/VNC and connectivity topics.

How does this pair with remote Mac access?

SSH-first automation, VNC on demand—remote Mac SSH/VNC guide.

Where to compare regions and pricing?

Multi-region decision table plus rental rates.