openclaw doctor passes on the host yet fails under a trimmed image, and port 18789 collides with sidecars. This guide compares dual paths honestly, explains how to persist state and secrets safely, documents publish maps for the default listener, and closes with a metro-level placement lens across Singapore, Tokyo, Seoul, Hong Kong, US East, and US West.
Why OpenClaw Docker installs feel haunted even when images build cleanly
OpenClaw’s Gateway is a long-lived control plane: WebSockets, CLI RPC, sessions, and adapters share one listener, default 18789. Docker excels at shipping immutable layers, yet the control plane is inherently stateful. When operators treat containers like cattle but omit explicit volume mounts for OPENCLAW_HOME, channel caches evaporate on recreate, remote clients observe phantom disconnects, and automation retries amplify until providers throttle you. Bind scopes add a second mirage: binding 127.0.0.1 inside a network namespace is not the same as publishing to the host LAN your teammates expect, so CLIs and reverse proxies appear “almost reachable” while the Gateway never actually exposes the interface you tested on bare metal.
The third mirage is diagnostic: openclaw doctor might pass on the hypervisor because libc and kernel capabilities differ from the slim runtime your compose file pulled. Fourth, tokens and refresh material stored only in the writable layer look fine until Kubernetes or Compose recreates the task; suddenly every channel needs re-authorization during a peak window. Fifth, multi-region teams accidentally park the Gateway in a cheap VPS while the human operators chat from Tokyo or Seoul, making occasional CLI interactions feel sluggish even though CPU charts look idle. Together these traps push teams toward either hardened bare-metal installs with install.sh or toward Docker, but only after they learn to pair volumes, publish maps, and explicit WebSocket URLs with their automation.
Bare-metal installs trade away layer immutability for closer-to-metal behavior: LaunchDaemon or systemd units restart like any other service, desktops can host Safari or Xcode-adjacent helpers without nested virtualization pain, and observability aligns with your existing host agents. The cost is discipline—OS upgrades, Xcode CLT drift, and fleet variance—where Docker wanted to keep everything uniform. The decision is therefore operational: do you optimize for identical images flowing through CI, or for interactive Apple workflows sitting beside the control plane? Most regulated fleets eventually operate both: Docker for disposable review apps, bare metal for production Gateways that must never lose tokens silently.
Ephemeral home directories: Anonymous volumes or missing bind mounts make OPENCLAW_HOME disappear between deploys, erasing channel proofing progress.
Loopback-only binds: Gateway WebSocket listeners stay unreachable from reverse proxies or remote CLIs unless publish and bind modes match the namespace boundary.
Doctor mismatch: Toolchains inside the image lack optional detectors that exist on a full macOS host, producing false confidence before production traffic.
Port 18789 collisions: Sidecars, legacy agents, or a second Gateway trial reuse the default listener triple and trigger EADDRINUSE with opaque logs.
Regionally distant control planes: A Gateway hosted far from the metro that owns interactive sessions adds RTT to every manual CLI invocation, exaggerating perceived slowness.
Heavy browser automation, manual TestFlight uploads, or desktop screen-sharing sessions still lean toward bare-metal macOS hosts because nested virtualization and GPU forwarding remain awkward inside containers on Apple hosts. If your agents must occasionally “drive” authenticated web consoles, hosting beside a full desktop session reduces friction more than squeezing X11-forwarding through extra hops. Conversely, if your OpenClaw footprint is purely API and WebSocket traffic with no GUI, Docker isolation can shrink blast radius—provided persistence, tokens, and published ports are intentional rather than accidental.
Treat every install path as a lifecycle story: provisioning, merge versus restart, token rotation, upgrade, and disaster recovery. Capture screenshots or structured notes for Singapore versus US East differences in latency and peering; operators debugging at 2 a.m. forget abstract guidance but remember concrete numbers tied to cities they recognize.
Finally, involve security early when Gateway exposure leaves loopback: any path that widens WebSocket reach should pair with network ACLs, reverse-proxy auth, and sealed secrets. The container versus bare-metal debate never removes those obligations; it only changes where you implement them—inside an overlay network or on the host firewall.
Decision matrix for Docker isolation versus install.sh daemons on cloud Mac
Use the matrix as a conversation accelerant with platform engineering and app owners, not as a law. Teams chasing reproducible CI artifacts frequently anchor on Docker, while teams pairing OpenClaw with native macOS utilities or frequent GUI adjacency favor install.sh plus a daemon supervised by launchd. Cost is not only dollars per month; it is incident hours when tokens vanish or when a container publish map disagrees with the documented wss endpoint. Always validate both paths in a staging metro before declaring a production default, because pre-1.0 velocity still shifts behavior month to month.
| Dimension | Docker isolated | install.sh bare metal |
|---|---|---|
| State persistence | Requires explicit volumes for OPENCLAW_HOME, logs, and secrets; easy to misconfigure | Writes to host paths by default; backup and snapshot tools already familiar to Mac admins |
| Upgrade velocity | Promotes immutable tags through registries; rollbacks swap images quickly | Depends on package pins and scripted downgrades; closer to classic fleet management |
| Process restarts | Orchestrator restart replaces the container; sessions drop unless designed for drain | Daemon bounce behaves like any service; LaunchDaemon or systemd policies you already runbooks |
| Gateway listener publish | Must map 18789 (or custom) through bridge or host network; bind flags interact with namespaces | Differentiated OPENCLAW_GATEWAY_PORT per instance with host networking semantics you can probe directly |
| Desktop-heavy workflows | Often awkward for GUI-adjacent agents; more moving parts | Native Metal, Safari, Xcode tooling without extra virtualization layers |
| Telemetry and forensics | Needs sidecars or log drivers; sometimes harder correlating host and container IDs | Host agents, unified logging, and crash reports align with existing Mac practices |
Containers change how you restart, not whether WebSockets, tokens, or bind scopes still matter.
Regional planning layers on top: placing a Gateway in Hong Kong when most channel operators sit in Los Angeles creates asymmetry—automations still work, but humans feel latency on every manual intervention. Collocating with the dominant interactive metro usually wins, with price traded only after you measure real CLI and dashboard round-trips rather than synthetic pings alone.
Where Docker genuinely shines is ephemeral environments: throwaway stacks for reproducing customer bugs without contaminating production homes. Pair that pattern with short TTL tokens so a discarded container never becomes a forgotten secret warehouse. Where bare metal shines is long-horizon stability with occasional GUI needs and predictable local tooling.
Document the matrix decisions in your internal wiki with owners and dates; future you should know whether Singapore was chosen for compliance proximity, operator proximity, or provider peering—not because someone liked the city name.
Skeleton compose for volumes, port publish, and Gateway WebSocket bind
The skeleton below is deliberately YAML-ish, not a vendor-specific contract: adapt labels, networks, and secret mounts to your orchestrator. The intent is to show parallel environment blocks you can diff during review—Docker versus bare metal—so teams notice when OPENCLAW_HOME lacks a host path or when 18789 never reaches the edge proxy. Mirror the same variables on a cloud Mac daemon install so staging and production diver only by metro and secrets, not by spelling mistakes in variable names.
service: openclaw-gateway image: your.registry/openclaw:pin-by-digest ports: - "18789:18789" environment: OPENCLAW_GATEWAY_PORT: "18789" OPENCLAW_HOME: /var/lib/openclaw GATEWAY_BIND_MODE: lan-or-loopback-review-me volumes: - /srv/openclaw-prod:/var/lib/openclaw - /srv/openclaw-logs:/var/log/openclaw secrets: - openclaw_tokens_readonly Bare-metal cloud Mac counterpart: export OPENCLAW_GATEWAY_PORT=18789 export OPENCLAW_HOME=/usr/local/var/openclaw launchctl bootstrap system /Library/LaunchDaemons/org.openclaw.gateway.plist
After editing skeleton values, rerun openclaw doctor inside the same execution context your orchestration uses, not only on an engineer laptop. discrepancies between developer shells and CI-built images routinely hide missing capabilities until the first on-call page. For WebSocket URLs, write three explicit strings into your runbook: internal upstream, public wss client URL, and health-check curl target; ambiguity there produces green dashboards with red user experiences.
When running multiple Gateways for blue-green trials, isolate ports and homes exactly as you would on bare metal: overlapping OPENCLAW_HOME trees corrupt caches just as quickly inside containers. Label logs per environment so support staff never guesses which stderr belongs to production.
Note: Treat token files mounted into containers as read-only; rotate after expanding bind scope or changing reverse-proxy auth, and avoid committing paths to public repositories.
Six-step rollout runbook for Docker or install.sh before you accept traffic
Choose the path explicitly: Record whether this metro uses Docker isolation or bare-metal install.sh, who owns upgrades, and where volumes or homes live on disk.
Map persistence: Bind-mount OPENCLAW_HOME, logs, and token material to durable host paths; verify permissions survive orchestrator restarts.
Publish 18789 intentionally: Align container port maps with firewalls and load balancers; on bare metal confirm only one listener owns the chosen triple.
Lock WebSocket bind policy: Decide loopback-only versus LAN exposure, pair with proxy auth, and document the public wss URL your CLIs must use.
Run openclaw doctor in situ: Execute inside the container or daemon context that production will use; capture warnings tied to release versions.
Probe channels off-peak: Send controlled test messages, validate remote CLI reads against the same URL operators will paste, and snapshot configs for rollback.
Annotate each step with the on-call roles responsible for reverting a bad publish map versus rotating tokens—confusion during minute twenty of an incident costs more than any single mis-typed port. Rehearse the runbook quarterly, especially after major macOS or image base upgrades, because capability gaps reappear subtly.
Keep rollback artifacts version-pinned: a working container digest or package tarball should sit beside the forward plan so you do not hunt artifacts while customers wait.
Citable guardrails plus metro placement on multi-region cloud Mac
Listener uniqueness: Only one healthy Gateway should own 18789 on a host unless you deliberately offset OPENCLAW_GATEWAY_PORT and separate OPENCLAW_HOME trees for staging.
Token durability class: Secrets must survive container recreate events; if they cannot, you are running a disposable lab, not production infrastructure.
Metro affinity heuristic: Park Gateways in the same region as the majority of interactive operators—Singapore, Tokyo, Seoul, Hong Kong, US East, or US West—not solely where compute was cheapest this week.
Warning: Do not widen WebSocket exposure to public interfaces until reverse-proxy authentication, ACLs, and rotation drills are complete.
Container glamour fades when incidents trace back to anonymous volumes or missing port publishes; bare-metal simplicity fades when fleets diverge silently without images to reconcile drift. The durable pattern is disciplined persistence, explicit networking, and metro-aware hosting that respects how humans and automations actually touch the Gateway daily. For teams needing Apple Silicon exclusivity, resilient power, and leases that flex across Singapore, Tokyo, Seoul, Hong Kong, US East, and US West, MESHLAUNCH Mac mini cloud rentals are usually the stronger operational fit because they keep native macOS beside your control plane while you still choose Docker or install.sh on your own terms.
Finance reviewers should challenge unnecessary spend tied to the wrong abstraction: if logs show persistence misses rather than CPU starvation, buying larger VMs will not help—fix mounts and publish maps first, then revisit sizing with evidence.
Operators spanning US West and Tokyo may run paired Gateways with synchronized policy but distinct secrets; document why redundancy exists so future cuts do not remove the one node that respected data residency expectations.
Yes. Apply merge-versus-restart discipline from the Gateway hot reload guide whether the process runs in a container or under a host LaunchDaemon, because socket, TLS, and bind moves still require a process bounce.
Track openclaw update semantics and pinned tracks using the update channels and rollback article, then compare capacity on the pricing page before you expand fleets.
Walk the Linux VPS versus cloud Mac troubleshooting ladder first, then open the help center with ports, publish maps, and token variable names.