OpenClaw Gateway blue-green rollout with a second port, health-gated cutover, and launchd on leased cloud Mac (2026-05-08)

OpenClaw’s macOS gateway story in 2026 is split: the desktop app orchestrates lifecycle, while the long-running daemon stays under launchd with external CLI installs. That split is good news for blue-green: you can boot a candidate gateway on 127.0.0.1:18765 while production stays on 127.0.0.1:18764, prove readiness with synthetic probes, then repoint loopback consumers or upstream proxies—without inventing a second physical MacLogin mini. This May 2026 runbook encodes the matrix MacLogin tenants in Hong Kong, Japan, Korea, Singapore, and the United States use to keep webhook workers, Canvas hooks, and CLI automations stable during upgrades.

Cross-read app + CLI handoff, health curl monitoring, graceful shutdown & drain, and the hub OpenClaw topic index. Also anchor help and pricing.

Why blue-green beats in-place restarts for busy gateways

In-place launchctl kickstart -k wins on tiny patches, but risky upgrades (Node major bumps, model allowlist changes, webhook URL migrations) benefit from side-by-side processes. Blue-green gives you a full warm container: TLS contexts compiled, model caches primed, and worker queues validated before any customer traffic touches the build.

Port plan and launchd label matrix

Color	Listen address	launchd label (example)	Purpose
Blue (stable)	127.0.0.1:18764	ai.openclaw.gateway.blue	Production traffic
Green (candidate)	127.0.0.1:18765	ai.openclaw.gateway.green	Staging validation
Observability	Either	N/A	Bind health to loopback; expose publicly only via controlled proxies per localhost hardening

Health probe contract before you flip traffic

Define non-negotiable signals: HTTP 200 on /healthz (or project-specific), JSON version field matching CLI, successful model ping under budgeted latency, and webhook self-test echo when applicable. Run probes for at least two scrape intervals to catch slow leaks.

Secondary LaunchAgent plist pattern (per-user)

Duplicate the working plist, change Label, StandardOutPath, StandardErrorPath, and environment exports that pin port + config root. Keep ThrottleInterval sane so crash loops do not DOS syslog. Align with environment variable guidance so both colors inherit the right secrets vault.

Nine-step cutover runbook

1. Snapshot current plist, binary hash, and Node version.
2. Deploy candidate bits to a versioned directory; do not overwrite stable paths.
3. Install green plist; launchctl bootstrap as tenant user.
4. Verify health endpoints locally with curl + mTLS if enabled.
5. Replay synthetic webhook payloads against green only.
6. Drain blue using the April 2026 drain article sequence.
7. Promote by repointing localhost forwarders or upstream proxy upstream blocks.
8. Observe error budgets for 30–60 minutes before declaring victory.
9. Demote blue binaries or keep warm as instant rollback.

Rollback drills that finish under five minutes

Practice reversing the promotion: restore upstream pointer to blue, launchctl bootout green only after draining queues, and keep logs tailing until webhook providers stop retrying 5xx bursts. Document who owns DNS vs loopback vs reverse-proxy layers—confusion there is how incidents stretch past SLAs.

Observability: diff JSONL streams between colors

When both daemons emit JSON lines, tag each record with color=blue|green at the logger configuration level. SIEM teams across HK, JP, KR, SG, and US time zones can then overlay error rates without guessing which process emitted noise.

FAQ

Does this replace Kubernetes? No—single-host leases use simpler patterns; K8s tenants should use pod blue-green instead.

What about TLS public webhooks? Pair this pattern with TLS reverse proxy guidance so the edge flips upstream to the healthy loopback port.

Where do I rent more isolated gateways? Start at pricing to add JP or US capacity for noisy workloads.

OpenClaw hub, help, and why regions matter

Keep the OpenClaw hub updated with your internal run labels so new engineers inherit the same port matrix. When latency-sensitive automations run closer to Tokyo brokers than US west coast, pinning leases per region reduces cutover risk because webhook RTTs stay predictable.