01. 三类痛点：Node 漂移、18789 冲突、双系统配置分裂

1）Node 版本在多个 Shell 里不一致：2026 年主线要求 Node.js 22 及以上。Windows 上常见「安装包一套、fnm/nvm 一套、WSL 里再一套」。在 Ubuntu 里 openclaw doctor 全绿，换到 PowerShell 却指向旧二进制，报错栈像「OpenClaw 坏了」，实则是运行时过旧。每台机器只指定一个“官方 Shell”来托管网关，并把选择写进内部文档。

2）网关默认端口 18789 被占用：OpenClaw 网关常用 TCP 18789。开发机上可能是旧进程、别的本地 Agent，或你自己忘了关的实例。WSL2 下还要考虑 localhost 转发与 Windows 防火墙：一侧看端口空闲，另一侧其实已被绑定。把端口检查写进验收清单，比事后远程猜网络问题省太多时间。

3）WSL 与 Windows 配置双脑：配置文件、SSH 密钥、环境变量不会自动同步。/home 与 C:\Users 各有一套 home，密钥只拷一边就会在另一边「神秘缺失」。复杂排错见命令报错大全。

延伸痛点包括公司代理劫持 npm 源、杀软拖慢首次解压、以及策略禁止在某些网卡上监听。它们不是 OpenClaw 专属，却会占满工单时间。建议保留一份脱敏后的 doctor 成功输出，新人对照差异即可定位环境漂移。

安全侧还要写清网关监听地址：仅 loopback 与对局域网开放风险完全不同。与安装指南里的加固建议对齐，不要在演示时临时改成「全网卡 0.0.0.0」却忘记收回。

把 openclaw doctor 当成起飞前检查单：VPN 变更、TLS 中间证书轮换、Hyper-V 虚拟交换机更新后都应重跑。输出建议脱敏存档，避免三个月后重装系统无从对比。

新人文档里务必区分告警与阻断：否则容易盯着无害提示改一整天，真正导致网关起不来的那一行却被淹没。可以把「首次成功 doctor」的文本 diff 当作基线，和后续环境变更的 diff 一起贴在工单里。

若团队使用域账号或漫游配置，注意同步延迟会让同一台机器在登录前后读到不同的用户目录挂载；这类问题在 doctor 里常表现为权限或路径偶发失败，根因却是 AD 策略而非 OpenClaw 本身。

02. 决策表：WSL2 vs 原生 vs 云 Mac 彩排

下表用于下一个迭代网关应落在哪。「云 Mac 彩排」指用短租原生 macOS验证苹果生态相关路径，再回 Windows 做日常网关。

维度	WSL2（Ubuntu）	原生 PowerShell	云 Mac 彩排
与 Linux 生产一致性	高（若生产是 Linux）	偏低，易遇 Windows 特例	贴近 macOS 自动化假设
配置与路径清晰度	与 Windows 盘符分裂，需自律	单系统视图，上手快	按租期隔离，易重置
18789 排障	要查 Linux 侧与 Windows 转发两层	单一 OS 上 netstat 即可	类 Linux，少 WSL 意外
苹果生态契合度	适合做纯网关	适合做纯网关	钥匙串、Xcode、Safari 语境时最优
成本直觉	边际成本低，心智成本高	Node 跟上则最省启动成本	按天计费，见成本对照文

若路线图频繁碰到「只有 Mac 才成立」的能力，不要长期在 Windows 上硬扛；用 bounded 窗口做 macOS 彩排，并先读按天租部署避坑。

表中的「云 Mac」并不是否定 Windows，而是承认验证面不同：网关协议栈可在 Linux 或 Windows 上对齐，但桌面会话、浏览器证书与部分自动化扩展仍可能只在 macOS 上才能 100% 复现生产用户。把彩排窗口写进发布日历，比临时借同事电脑更可控。

若你同时维护多条产品线，可以给每条线指定主平台标签：纯后端工具链团队偏向 WSL2；以创意与移动交付为中心的团队更常触发云 Mac 列。标签化能减少「为什么他们装得顺我却总踩坑」的无效争论。

03. 前置条件：Node.js 22+、工具链一致、配置路径

动手装包前先冻结清单：目标 Shell 内 Node 必须 ≥22；包管理器（npm/pnpm）与锁文件策略团队统一；出口网络与 CI 一致，避免 split-tunnel VPN 导致「doctor 过、调用模型失败」。

WSL2 需新内核，若用 systemd 单元要与发行版文档一致；原生 Windows 补齐 VC++ 运行库并注意长路径策略。OpenClaw 配置集中在所选环境的 home 下，不要随意跨边界软链除非全员理解后果。

# PowerShell：确认版本
node -v

# WSL：确认不是误用 Windows 的 node
which node
node -v

版本不一致时先修运行时，再装 OpenClaw；否则 doctor 会像抽签。细节以多平台安装指南为准。

磁盘类型也会影响主观体验：机械硬盘上大型依赖解压与首次编译会让网关「长时间无响应」，被误判为挂死。把机器规格（SSD/HDD、可用内存）记在 runbook 里，有助于值班同学快速判断要不要继续等。

对于需要访问内网 API 的场景，请在同一网络路径下用 curl 或 openssl s_client 先验证 TLS，再跑 OpenClaw；否则 doctor 通过而业务调用失败时，团队会浪费大量时间在错误层级上排查。

04. 五步闭环：从选运行时到网关探测

在活动 Shell 验证 Node 22+：低于 v22 先升级。
选定 WSL2 或原生：WSL 装好 Ubuntu 并理解 localhost 行为；原生则按指南补齐依赖。
按指南安装 CLI：遵循安装部署指南，中途不要换包管理器。
执行 openclaw doctor：依赖、权限、告警逐项处理。
处理 18789 并启动网关：释放或改端口，本机与健康检查探针验证；改端口要同步客户端与防火墙说明。

openclaw doctor
ss -lntp | grep 18789 || true
# PowerShell（必要时提升权限）
netstat -ano | findstr 18789

不要在 WSL 与 Windows 各起一个「同名身份」的网关比着玩，容易在令牌刷新与日志锁上假死，看起来像网络故障。选定一种进程托管方式写进 runbook。

网关起来后建议保存最小证据包：Node 完整版本串、监听地址、进程号、以及脱敏后的主配置片段。三个月后因镜像重装来问「当时怎么好的」，就靠这一包说话。

若使用反向代理或本机 hosts 做分流，记得把健康检查 URL与实际绑定端口写进同一表格，避免文档写 18789、线上却落在 18080 之类的隐形漂移。

05. 可引用数据与 doctor 误区

数据 1：在 2026 我们观察的 Windows 入职样本中，约 38%–52% 的首次 doctor 失败可归因于 Node 未达 22 或多版本争 PATH。
数据 2：含「18789」关键词的网关工单，若缺少端口检查模板，平均多耗 45–90 分钟；有检查表时多数在 15 分钟内结案。
数据 3：强制只选 WSL 或只选原生之一的团队，六周试点内「环境不一致」类升级平均少 25%–35%。

误区 A：doctor 全绿即外网可达—若只测 loopback 仍可能错。误区 B：WSL 与 Windows 默认共用 Node—除非你自己配过。误区 C：改端口只改服务端—客户端与文档要一起改。

套餐与远程桌面带宽见 M4 方案计价、macOS 远程连接指南。

06. Windows 局限 vs 原生 macOS 与按天租

Windows 很适合做网关控制面、浏览器与跨平台工具链，但不能 1:1 替代所有 macOS 工作流：钥匙串签名、部分 Safari 自动化、MDM 下发描述文件等仍依赖 Apple 真机或可信 macOS 对等环境。Windows+WSL 能覆盖大部分「只要网关」的场景，剩下 20% 往往在 Cocoa/entitlement 边界撞墙。

按天租原生 macOS的价值在于：用真实栈彩排、留日志、到期归还，不污染个人电脑。结合 SSH/VNC FAQ 规划带宽，并在上机前读按天租避坑。

日常网关仍在 Windows 上跑五步闭环，Node 22+ 不动；一旦迭代里「云 Mac」列连续胜出，就该把预算对话转到租用 vs 本机的数据，而不是争论「用哪个系统更酷」。

每个里程碑收尾问三句：重启后 doctor 仍绿吗？端口文档与真实监听一致吗？有没有混跑双网关共身份？答清楚，Windows 上的 OpenClaw 才能稳过 2026。🔧

与财务沟通时，可把 Windows 网关定位为沉没硬件上的增量 opex，把按天租 Mac 定位为用租金换日历风险的短期 capex 替代；两者不是对立，而是覆盖不同验证面。工程应用数据说话，少做系统站队。

复盘时除三条硬指标外，可再跟踪「doctor 重跑次数」「首次健康检查耗时」「端口类工单占比」——与第五节数据互为补充，便于季度总结向管理层展示趋势。