which openclaw through first message, cloud Mac PATH and Screen Sharing notes, and an M4 versus M4 Pro node pick when retries mask memory pressure. Read it with the official install-daemon, launchd token fix, diagnostic ladder, CLI align, and headless SSH walkthrough so Retry stops being guesswork.
2026 Setup Wizard Retry on a cloud Mac: four roots behind Gateway did not become ready
The macOS Setup Wizard polls Gateway health on a short timer. When it shows Gateway did not become ready and only offers Retry, the failure is almost always infrastructure readiness, not channel pairing or API keys. On KVMNODE hosts you often installed over SSH first: the interactive shell sees a global openclaw while the wizard subprocess inherits a narrower PATH, so the UI retries forever even though you typed commands successfully minutes earlier.
The second root is launchd already exited failed while the wizard still counts down: openclaw gateway start from SSH may print success if it only talks to a partial socket, but launchctl print shows the LaunchAgent job crashed on missing OPENCLAW_* or wrong WorkingDirectory. The third is port 18789 contention: an old manual gateway start, a second onboard, or a leftover Node process binds loopback before the plist-owned Gateway can attach. The fourth is bind address mismatch: Gateway listens on 127.0.0.1 while the wizard or health probe expects LAN or the inverse after a config edit.
PATH without CLI: which openclaw empty in the GUI context; install finished in SSH only.
Failed launchd, wizard timeout: job exit code non-zero; Retry does not surface stderr.
18789 held: lsof shows another PID; health never reaches ready.
Plist env drift: Node 22 via nvm in SSH but plist uses system Node 18.
Split brain after upgrade: app bundle newer than CLI; align before wizard (see CLI align).
Paste the four roots into the change record before clicking Retry again. If you already ran official install-daemon, acceptance should freeze openclaw version, launchd label, listen port, doctor exit code, wizard screenshot or skip rationale. When auth errors appear after the wizard finally passes, map to L2 on the diagnostic ladder and the launchd token article before swapping hardware.
Platform owners should treat Retry loops as P1 only when production Gateway is down; for first-run wizard, block repeated Retry clicks until PATH and port checks pass once non-interactively—otherwise logs interleave and you lose the first failure timestamp.
Decision matrix: skip the wizard versus finish it on Screen Sharing
Headless teams want to close the wizard from SSH; the macOS app expects GUI completion for some channel flows. The matrix below is the fork: if every row in the CLI column is green, document wizard skip on the ticket and proceed with onboard from the headless SSH walkthrough. If any row is red, open Screen Sharing once, fix launchd and PATH, then let the wizard finish so pairing state matches what the app stores.
| Check | CLI-only path (skip wizard) | Must use Setup Wizard |
|---|---|---|
| which openclaw | Same path in SSH and plist EnvironmentVariables | Empty in GUI session |
| openclaw doctor | Exit 0, no blocking migrations | Doctor fails until GUI completes |
| gateway status --deep | Ready, correct bind and token | RPC timeout or 401 loop |
| Port 18789 | Single listener owned by plist | Unknown PID or dual onboard |
| Channels | Already paired via CLI | First macOS app pairing only |
Retry without a frozen PATH line on the ticket is not troubleshooting—it is noise.
Record whether the host is wizard-first or CLI-first in the asset inventory. Mixed templates confuse auditors when one machine skipped wizard and another required it for the same openclaw version. After the fork, never run a second onboard --install-daemon from SSH while the wizard is open; that duplicates LaunchAgent labels and recreates 18789 fights described in the install-daemon article.
Command block: PATH, doctor, launchd log, and port 18789 before another Retry
Run this block over SSH on the dedicated cloud Mac before touching Retry in the wizard. Replace the LaunchAgent label with your plist name from launchctl list | grep -i openclaw. Attach full stdout to the change record; map failures to L1 on the diagnostic ladder.
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH" which openclaw openclaw --version node -v openclaw doctor openclaw gateway status --deep lsof -nP -iTCP:18789 -sTCP:LISTEN log show --predicate 'process == "openclaw"' --last 5m 2>/dev/null | tail -n 40 launchctl print gui/$(id -u)/com.openclaw.gateway 2>/dev/null | head -n 30
Tip: If doctor reports CLI newer than the running Gateway, stop Retry and follow CLI align before the wizard probes health again.
When lsof shows a listener that is not your plist job, run openclaw gateway stop, kill the stray PID only if the record names it, then openclaw gateway start or reinstall daemon per the official install path—never leave two starters. Token or auth errors after port cleanup belong on the launchd token runbook, not in the wizard Retry loop.
Seven steps: from Retry loop to Gateway ready and first message
Freeze versions: capture openclaw --version, node -v, and KVMNODE region on the change record.
Align PATH for launchd: put the same openclaw and Node paths into the LaunchAgent EnvironmentVariables as SSH uses.
Run doctor once: fix migrations before any wizard Retry; save stdout.
Clear port 18789: single listener; stop duplicate onboard or manual starts.
Restart Gateway via plist: launchctl kickstart -k on the labeled job; confirm gateway status --deep ready.
Wizard or documented skip: finish Setup Wizard over Screen Sharing, or attach CLI-only skip evidence per section 02.
First-message acceptance: one inbound channel or RPC ping, health JSON line, and timestamp; escalate to L2 ladder if flaky.
When all seven steps pass, the ticket should state which lever cleared Retry: PATH, launchd, port, version align, or node tier. During acceptance week, snapshot gateway status --deep daily and compare P95 latency to your SLO. If step 05 passes in SSH but the wizard still Retries, assume GUI PATH drift and log in once via Screen Sharing only to confirm the app sees the same binary—do not reinstall from scratch until doctor and port rows are green.
Teams that onboard many cloud Macs should store a one-line health probe in the same bastion playbook as SSH keys: curl -sf http://127.0.0.1:18789/health or the path your openclaw.json documents, run after kickstart and before notifying the wizard owner. That separates “wizard UI slow” from “Gateway never listened,” which is the distinction stakeholders need when Retry screenshots land in chat without logs.
Cloud Mac specifics, three hard numbers, and M4 versus M4 Pro when Retry hides pressure
Dedicated cloud Macs differ from laptops: no lid-close sleep, but SSH sessions do not inherit GUI PATH, Screen Sharing may be intermittent, and six-region nodes shift log timezone labels—not Gateway logic, but incident timestamps. Keep ~/.openclaw off team sync folders; wizard retries that rewrite config while CI jobs run on the same host can interleave partial writes.
Default Gateway port: 18789 on loopback unless your openclaw.json overrides—health probes must target the same bind.
Node major for 2026 builds: freeze Node 22 (or your install.sh pin) on both SSH and plist before doctor.
Wizard poll window: treat three consecutive Retry clicks without log capture as a process failure—require the command block first.
| Placement | Near-region M4 trial | Far-region M4 Pro resident |
|---|---|---|
| First OpenClaw proof on cloud Mac | Preferred for RTT to Git and wizard UI | Use when unified memory headroom is mandatory day one |
| Retry cleared but Gateway P95 > 800ms to collaborators | Re-home region before tier jump | Only if RTT fixed and memory still pegged |
| Same host runs iOS CI and Gateway | Risk on 16GB during archive peaks | Preferred when 18789 flaps with xcodebuild |
Note: Buying more Retry clicks on an undersized node does not fix launchd PATH—resize only after doctor, port, and ladder L1 are green for 48 hours.
A personal Mac as the only OpenClaw host gives unpredictable wizard completion when the lid sleeps mid-pairing and PATH differs between Terminal and GUI. Shared office VMs add noisy neighbors and no contractible 7×24 launchd acceptance. For teams that need auditable, region-flexible dedicated Apple Silicon where Setup Wizard, Gateway, and optional CI share one machine, KVMNODE Mac Mini cloud rental is usually the better fit: dedicated hosts, six regions, day-through-month terms, and the same placement language for PATH, 18789, and M4 Pro upgrades. Order via order page, runbooks in the Help Center, SKUs on pricing.