2026 OpenClaw Gateway Built-in Health Probes (/health, /ready) and Load Balancing: Remote Physical Mac, Docker Compose, and Kubernetes Alignment—Path Shadowing and False-NotReady Runbook

1. Pain points: shadowing, drift, and load-balancer lies

1. Path shadowing. A static location /, SPA fallback, or aggressive try_files can return 200 OK HTML for /ready without ever hitting OpenClaw. Your LB thinks the pool is warm; the gateway never received the probe.
2. Semantic drift between platforms. Compose marks a service healthy when the engine-level check passes; Kubernetes can still route to a different revision behind a Service if selectors overlap, or if an Ingress sends probes to a canary backend you did not intend to test.
3. Hidden audit and stability cost. Reusing /ready for liveness couples dependency outages to Pod restarts. On a remote Mac fleet, that shows up as flapping Screen Sharing sessions, half-written agent state, and noisy on-call—not “just Kubernetes.”

2. Decision matrix: where each probe should run

Use this table during design review before you paste YAML into production. “Who must observe what?” is the whole game.

3. Seven-step alignment runbook

1. Enumerate callers. Export every health URL from the cloud LB, nginx server_name block, Compose file, Helm values, and ad-hoc monitoring. If any row is blank, that is your blind spot.
2. Prove shadowing. From the proxy host, curl -svH 'Host: your.api' https://127.0.0.1/ready and diff the body against curl straight to the gateway port on loopback.
3. Pin locations ahead of catch-alls. Dedicated location = /health and location = /ready with proxy_pass to the gateway upstream, proxy_buffering off; and add_header Cache-Control no-store;.
4. Compose: match LB timeouts. Set interval, timeout, and retries within 80% of what the external LB uses so you do not optimistically mark healthy first.
5. Kubernetes: split probes. Wire liveness to /health, readiness to /ready, and add startupProbe with longer failureThreshold for model-router warm-up.
6. Rollout rehearsal. Blue/green or rolling: watch kubectl get endpoints while tailing gateway logs; confirm traffic shifts only after /ready flips for the new revision.
7. Archive diffs. Store redacted nginx -T, Compose YAML, and kubectl describe pod snippets with timestamps—your future self thanks you during the next false NotReady.

4. Configuration snippets

4.1 nginx: explicit probe locations (no shadowing)

location = /health { proxy_pass http://openclaw_gateway; proxy_http_version 1.1;
  proxy_set_header Host $host; proxy_buffering off; add_header Cache-Control "no-store"; }
location = /ready  { proxy_pass http://openclaw_gateway; proxy_http_version 1.1;
  proxy_set_header Host $host; proxy_buffering off; add_header Cache-Control "no-store"; }

4.2 Docker Compose: healthcheck + dependency gate

services:
  openclaw-gateway:
    image: your.registry/openclaw-gateway@sha256:…
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:18789/health"]
      interval: 15s
      timeout: 3s
      retries: 5
      start_period: 120s
  edge-proxy:
    depends_on:
      openclaw-gateway:
        condition: service_healthy

4.3 Kubernetes: startup + readiness + liveness

startupProbe:
  httpGet: { path: /ready, port: http }
  periodSeconds: 5
  failureThreshold: 30
readinessProbe:
  httpGet: { path: /ready, port: http }
  periodSeconds: 10
  timeoutSeconds: 3
livenessProbe:
  httpGet: { path: /health, port: http }
  periodSeconds: 20
  timeoutSeconds: 2

Adjust port: http to match your containerPort name. If you terminate TLS at the Ingress, keep probes on the plain container port unless your mesh injects sidecar TLS.

5. Cite-ready parameters

• 18789 — common OpenClaw gateway HTTP surface on Mac nodes; always confirm with your openclaw.json or release notes before baking into LB templates.
• 120s start_period — practical first guess for cold model cache and Secret mount latency on remote Mac hosts; trim with measured P95 after two weeks of metrics.
• 3s readiness timeout — balances slow upstreams against kubelet aggressiveness; pair with failureThreshold instead of unbounded timeouts that hide real stalls.

6. FAQ: reproducible false positives

7. Why Mac mini is the right place to terminate this complexity

Gateway health semantics only matter when the host stays up: Apple Silicon Mac mini nodes combine low idle power (often on the order of a few watts at rest), silent operation suitable for racks and desks, and a Unix-first toolchain—curl, launchctl, Docker Desktop or Colima, and SSH—without the driver friction common on Windows fleets.

macOS Gatekeeper, SIP, and FileVault also reduce tampering risk for long-lived agent tokens sitting beside your gateway. That security posture matters when /ready is the signal your load balancer uses to expose automation to the internet.

If you want this probe and load-balancer story on hardware you can leave unattended, Mac mini M4 is a strong 2026 baseline—then use the CTA below to compare ZoneMac gateway-ready nodes and roll out with the same acceptance curls you just documented.