2026 年云 Mac 上 Setup Wizard 一直 Retry：Gateway did not become ready 的四类根因
macOS Setup Wizard 会在短周期内轮询 Gateway 健康状态。当界面只给出 Gateway did not become ready 并让你继续 Retry 时，失败几乎总在基础设施就绪，而不是频道配对或 API Key。在 KVMNODE 主机上，很多人先通过 SSH 完成安装：交互 shell 里 openclaw 可用，而向导子进程继承的 PATH 更窄，于是你在终端里刚跑通的命令，在 GUI 里仍无限 Retry。
第二类根因是 launchd 已失败退出，向导仍在倒计时：SSH 里执行 openclaw gateway start 可能只碰到残留 socket 而显示成功，但 launchctl print 显示 LaunchAgent 因缺少 OPENCLAW_* 或 WorkingDirectory 错误而崩溃。第三类是 18789 端口争用：旧的手动 gateway、二次 onboard 或遗留 Node 进程先占回环，plist 所属的 Gateway 无法附着。第四类是 绑定地址不一致：Gateway 监听 127.0.0.1，向导或健康探针却按局域网或其它接口探测，改配置后尤易出现。
GUI 上下文无 CLI：向导里 which openclaw 为空，安装只在 SSH 完成。
launchd 已失败仍超时：作业非零退出，Retry 不展示 stderr。
18789 被占：lsof 显示其它 PID，健康永远不到 ready。
plist 环境漂移：SSH 用 nvm 的 Node 22，plist 仍指向系统 Node 18。
升级后 split brain：应用包比 CLI 新，应先做 版本对齐 再开向导。
再次点 Retry 前，请把四类根因贴进变更单。若已按 官方 install-daemon 部署，验收应冻结 openclaw 版本、launchd 标签、监听端口、doctor 退出码、向导截图或跳过理由。向导通过后若出现鉴权错误，请对照 诊断梯子 L2 与 launchd token 文，不要先换硬件。
平台负责人应把 Retry 循环视为 P1 仅当生产 Gateway 已宕机；首次向导场景下，应在 PATH 与端口非交互检查通过前，限制连续 Retry，否则日志交错会丢失第一次失败时间戳。
2026 年社区 issue 已明确：若 Gateway 启动阶段已标记 failed，向导仍空等到超时才显示 Gateway did not become ready，会把「CLI 未找到」掩盖成泛化超时。云 Mac 上先用 SSH 跑通 openclaw doctor --non-interactive 再开向导，可把失败原因前置到变更单。若你同时参考 安装排错清单，请把「向导 Retry」单独记为一栏，不要与 channels 401 或 split brain 混在同一工单，否则 L2 梯子会走错分支。
决策表：跳过 Setup Wizard 还是屏幕共享走完向导
无头团队希望从 SSH 关掉向导；macOS 应用对部分频道流程仍期待 GUI 完成。下表是分叉：CLI 列全绿时，在工单注明「向导跳过」并按 无头 SSH 跟做 继续 onboard；任一行标红则开一次屏幕共享，修好 launchd 与 PATH 后再让向导结束，使配对状态与应用存储一致。
| 检查项 | 纯 CLI（可跳过向导） | 必须走 Setup Wizard |
|---|---|---|
| which openclaw | SSH 与 plist EnvironmentVariables 路径一致 | GUI 会话中为空 |
| openclaw doctor | 退出 0，无阻塞迁移 | 需 GUI 完成后才通过 |
| gateway status --deep | Ready，绑定与 token 正确 | RPC 超时或 401 循环 |
| 端口 18789 | 单一监听且归 plist 所有 | 未知 PID 或双 onboard |
| Channels | 已在 CLI 完成配对 | 仅 macOS 应用首次配对 |
变更单上没有冻结的 PATH 行就点 Retry，不算排障，只是制造噪声。
资产清单应记录该主机是 向导优先 还是 CLI 优先。同一 openclaw 版本下，一台跳过向导、另一台必须向导，会让审计困惑。分叉后，切勿在向导打开时再从 SSH 执行第二次 onboard --install-daemon，否则会重复 LaunchAgent 标签并再现 install-daemon 文中描述的 18789 争夺。
屏幕共享仅用于「GUI PATH 与 plist 对齐」：登录图形会话后在终端执行与 SSH 相同的 which openclaw，若路径不同，把 Homebrew 或 npm 全局前缀写入 LaunchAgent 的 EnvironmentVariables，而不是在向导里反复 Retry。无头团队若长期不打开 GUI，应在验收记录中写明 CLI-only 跳过向导并附第三节命令块完整输出。六区节点不改变 Retry 机理，但会影响查看 ~/Library/Logs/openclaw/gateway.log 时与协作者的时区对齐。
命令块：再次 Retry 前先查 PATH、doctor、launchd 日志与 18789
在独占云 Mac 上通过 SSH 执行下列块，再动向导里的 Retry。LaunchAgent 标签请用 launchctl list | grep -i openclaw 核对后替换。完整 stdout 附在变更单；失败映射到 诊断梯子 L1。
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
提示：若 doctor 报告 CLI 比运行中 Gateway 新，先按 客户端与 CLI 对齐 处理，再让向导探测健康。
lsof 显示的监听若不是 plist 作业，先 openclaw gateway stop，仅在变更单点名 PID 后再结束进程，然后 gateway start 或按 官方安装 重装守护进程，勿留双启动器。端口清理后若仍是 token 或鉴权错误，请走 launchd token 手册，不要在向导 Retry 里打转。
七步跟做：从 Retry 循环到 Gateway ready 与首条消息
冻结版本：变更单记录 openclaw --version、node -v 与 KVMNODE 节点区域。
对齐 launchd PATH：LaunchAgent EnvironmentVariables 与 SSH 使用同一 openclaw 与 Node 路径。
先跑一次 doctor：向导 Retry 前完成迁移修复并保存 stdout。
清空 18789：保证单一监听，停止重复 onboard 或手动 start。
经 plist 重启 Gateway：对标签作业 launchctl kickstart -k，确认 gateway status --deep 为 ready。
向导或记录跳过：屏幕共享完成 Setup Wizard，或附第二节 CLI 跳过证据。
首条消息验收：一条入站频道或 RPC ping、健康 JSON 行与时间戳；仍抖动则升 L2 梯子。
七步全通过后，工单应写明清除 Retry 的杠杆：PATH、launchd、端口、版本对齐或档型。验收周建议每日快照 gateway status --deep 并与 SLO 对比 P95。若第 05 步在 SSH 通过而向导仍 Retry，优先假设 GUI PATH 漂移，仅通过屏幕共享确认应用看到的二进制与终端一致，在 doctor 与端口行全绿前勿重装整套栈。
批量上架云 Mac 的团队，应在堡垒机手册中与 SSH 密钥并列一行健康探针：curl -sf http://127.0.0.1:18789/health（或 openclaw.json 文档路径），在 kickstart 之后、通知向导负责人之前执行，以区分「界面慢」与「Gateway 从未监听」。
验收完成后，建议把「清除 Retry 的杠杆」写入节点资产表：PATH、launchd、18789、版本对齐、区域或档型。若计划与 iOS CI 同池，请先阅读站内同池隔离文，再决定是否在向导通过当日开启并行 xcodebuild；否则 Retry 刚结束又遇到内存压力，会再次被误判为 Gateway 故障。对需要 7×24 常驻且向导只应出现一次的生产节点，优先选 M4 Pro 并固定远区，比在低配 M4 上每周重跑向导更省营运成本。
云 Mac 特有问题、三条硬数据与 Retry 掩盖压力时的 M4 对比 M4 Pro
独占云 Mac 与笔记本不同：无合盖睡眠，但SSH 不继承 GUI PATH，屏幕共享可能断断续续，六区节点只影响日志时区标签而非 Gateway 逻辑。勿把 ~/.openclaw 放在团队同步盘；向导 Retry 重写配置时若同机还有 CI，可能交错写入半成品。
默认 Gateway 端口：18789 回环，除非 openclaw.json 覆盖，探针须对准同一绑定。
2026 构建 Node 主版本：doctor 前在 SSH 与 plist 冻结 Node 22（或 install.sh 钉死的版本）。
向导轮询窗口：连续三次 Retry 仍无日志采集视为流程失败，必须先跑第三节命令块。
| 落点 | 近区 M4 试跑 | 远区 M4 Pro 常驻 |
|---|---|---|
| 云上首次 OpenClaw 验证 | 利于 Git RTT 与向导 UI | 首日即要统一内存余量时选用 |
| Retry 已清但协作者 P95 > 800ms | 先重选区域再升档 | RTT 已修且内存仍顶满时再上 |
| 同机 iOS CI 与 Gateway | 16GB 在 archive 尖峰有风险 | xcodebuild 与 18789 同抖时优先 |
注意：在 undersize 节点上多点 Retry 修不了 launchd PATH；doctor、端口与梯子 L1 连续 48 小时全绿后再考虑升档。
仅用个人 Mac 跑 OpenClaw 时，合盖睡眠会在配对中途打断向导，终端与 GUI 的 PATH 也不一致。共享办公室虚拟机还有邻居噪声，难以合同化 7×24 launchd 验收。临时借用同事 Mac 做向导，还会把设备 token 与 keychain 视图留在他人机器上，迁移到云节点时又要重做配对。对需要可审计、可换区独占 Apple Silicon、且 Setup Wizard、Gateway 与可选 CI 同机的团队，KVMNODE Mac Mini 云端租赁通常是更优解：独占主机、六区节点、按天至月租，与 PATH、18789、M4 Pro 升级共用同一套选区语言。下单见 订购入口，操作见 帮助中心，档位见 定价页。