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 重跑次數」「首次健康檢查耗時」「埠類工單佔比」——與第五節資料互為補充，便於季度總結向管理層展示趨勢。