OpenClaw 2026 遠端 Gateway 配對與 SSH 隧道： macOS 用戶端 Health Check 排障與 LaunchAgent 常駐清單
已在 JEXCLOUD 雲端 Mac 上跑通 OpenClaw Gateway，卻在本機 macOS App 裡卡在 「Health check pending」 或 gateway.remote 配對失敗？2026 年最常見的原因不是「Gateway 沒起來」，而是本機 App ↔ SSH 隧道 ↔ 遠端 127.0.0.1:18789 這條鏈路某一環斷了。本文面向需要用本機 OpenClaw 用戶端遙控遠端 Gateway 的開發者與 SRE，給出 SSH 隧道與 Direct WSS 選型矩陣、LaunchAgent 常駐清單、Health Check 巡檢腳本 與對照排障表（設定細節可參考 OpenClaw 官方 onboarding 文件）。
讀完你應能回答三件事：① 你的網路環境該選 SSH LocalForward 還是 Direct wss://；② OPENCLAW_GATEWAY_TOKEN 與 ai.openclaw.ssh-tunnel / ai.openclaw.gateway 兩套 LaunchAgent 如何分工；③ 當 CLI openclaw health 已通過而 UI 仍 pending 時，該查連接埠、Token 還是隧道行程。
01 OpenClaw 遠端 Gateway 架構：本機 macOS 用戶端遙控雲端 Mac
2026 年 OpenClaw 在 macOS 上提供兩種 Gateway 連線模式：Local（Gateway 與 App 同機）與 Remote（Gateway 在另一台 Mac，本機 App 透過 SSH 隧道或 Direct WebSocket 接入）。生產環境裡更常見的是：Gateway 跑在 JEXCLOUD 裸金屬 Mac 的 127.0.0.1:18789，開發者筆電上的 OpenClaw.app 只做「遙控台」——這與節點選型與 launchd Token 排障那篇互補：彼文解決「遠端機器怎麼裝、怎麼選型」，本文解決「本機怎麼連上去、怎麼保活、怎麼驗活」。
在評審會上，這五類痛點最容易被低估：
- 隧道未常駐：SSH 連線一斷，本機 App 仍顯示舊狀態，直到 Health Check 逾時才發現 Gateway 不可達。
- Token 雙軌不一致：遠端
launchctl環境變數、~/.openclaw設定與本機 App 填寫的 Token 不一致，會觸發 pairing / device token 類錯誤。 - 連接埠與轉發錯位：預設 Gateway 連接埠 18789 被佔用或 LocalForward 指錯目標，CLI 直連遠端成功、本機 localhost 失敗。
- Health Check UI 滯後：已知情境下 CLI 健康檢查已通過，macOS 應用 UI 仍停在 pending（社群 Issue 討論見 openclaw#66306）。
- 安全暴露面：為圖省事把 Gateway 綁到
0.0.0.0且無 mTLS，在公網 IP 上等同裸奔；推薦 127.0.0.1 + SSH/Tailscale。
記憶口訣：「Gateway 只監聽回環，隧道負責出網，Token 只走一條真相源」。任何一環繞過這條口訣，排障時間都會以小時計。
02 SSH 隧道還是 Direct WSS：OpenClaw 遠端接入選型矩陣
在 OpenClaw 設定裡的 OpenClaw runs 區域，Transport 通常在 SSH tunnel 與 Direct (ws/wss) 之間二選一。沒有「永遠正確」的選項，只有與你的防火牆、Tailscale 覆蓋、維運習慣匹配的選項。
| 維度 | SSH 隧道 + LocalForward | Direct WSS |
|---|---|---|
| 安全邊界 | Gateway 僅監聽 127.0.0.1；出網走 SSH 加密 | 需 TLS 終止與 Token；常配合 Tailscale / 內網 DNS |
| 防火牆友善度 | 僅需 SSH 22（或自訂連接埠）可達 | 需放行 wss 連接埠與憑證鏈；企業 Proxy下易失敗 |
| 延遲與穩定性 | 多一跳 SSH，RTT 15–40 ms 仍可接受；KeepAlive plist 可自愈 | 少一跳，適合已部署穩定 WSS 反代的環境 |
| 維運複雜度 | 維護 ~/.ssh/config + 隧道 LaunchAgent |
維護憑證、反代與 Token 輪換流程 |
| 推薦場景 | 個人開發者筆電遙控 JEXCLOUD 單節點；小團隊無專職 SRE | 已有 Tailscale Serve / 統一 API 閘道器的多人團隊 |
若你已在 說明中心 開通 SSH 金鑰登入，且遠端 Gateway 僅綁定回環位址，優先 SSH 隧道；僅當公司已提供穩定的 wss://gateway.example.ts.net 且 macOS 用戶端「Test remote」持續通過時，再切 Direct。
03 雲端 Mac 前置準備：PATH、Token 權限與 SSH 設定片段
遠端主機須滿足 OpenClaw CLI 在非互動 Shell 下可呼叫（pnpm link --global 後建議 symlink 到 /opt/homebrew/bin 或 /usr/local/bin）。Token 檔案權限應為 600，擁有者與執行 Gateway 的使用者一致。
Host jex-openclaw-sg
HostName your-instance.jexcloud.com
User macuser
IdentityFile ~/.ssh/jexcloud_ed25519
LocalForward 18789 127.0.0.1:18789
ServerAliveInterval 30
ServerAliveCountMax 3<key>Label</key>
<string>ai.openclaw.ssh-tunnel</string>
<key>ProgramArguments</key>
<array>
<string>/usr/bin/ssh</string>
<string>-N</string>
<string>jex-openclaw-sg</string>
</array>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>Gateway 本體由 macOS 應用或 CLI 安裝 LaunchAgent ai.openclaw.gateway；環境變數 OPENCLAW_GATEWAY_TOKEN 建議透過 launchctl setenv 或 plist 內 EnvironmentVariables 注入，避免在 shell profile 與 plist 各寫一份導致漂移。
04 OpenClaw 遠端 Gateway 配對六步：從 Test remote 到 LaunchAgent 驗活
- 遠端安裝 CLI 並啟動 Gateway：在 JEXCLOUD 實例上執行
openclaw gateway install（或依應用引導安裝 LaunchAgent），確認lsof -i :18789僅監聽127.0.0.1。 - 寫入並校驗 Token：產生 Gateway Token，
chmod 600儲存；launchctl setenv OPENCLAW_GATEWAY_TOKEN '…'後重啟 Gateway Agent。 - 本機設定 SSH：將上節
LocalForward 18789寫入~/.ssh/config，手動執行ssh -N jex-openclaw-sg，另開終端機curl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer $TOKEN" http://127.0.0.1:18789/health應得 200。 - 安裝隧道 LaunchAgent：
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist，確認登入後隧道自動拉起。 - macOS 用戶端配對：設定 → OpenClaw runs → 選 Remote + SSH tunnel，填寫
user@host（若走 config 別名可僅填 Host），點擊 Test remote 直至通過。 - 登記巡檢與告警：將 Health 腳本加入
StartInterval（建議 300s）或 CI SSH job；失敗時launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel並記錄結束碼供 on-call。
配對成功後，可在應用內進入 onboarding 工作階段驗證 Agent 通道；若僅 CLI 可用而 UI pending，按下一節對照表排查，勿重複重裝 Gateway。
05 Health Check 巡檢腳本與可引用技術資料
生產環境建議用腳本斷言 HTTP 200，而非依賴 UI 狀態燈。下列條目可在評審檔案引用（區間為 2026 年社群實踐與 JEXCLOUD 節點觀測，非 SLA 承諾）：
- 預設 Gateway 連接埠：
18789（LocalForward 須與此一致；多實例時依文件規劃額外連接埠）。 - Health 端點：常見為
/health，需 Bearer Token；非 200 應令監控結束碼非零。 - SSH 隧道自愈：LaunchAgent
KeepAlive+ServerAliveInterval 30可將斷線恢復時間壓到 30–90 秒 量級（視網路抖動而定）。 - 亞太 RTT：東亞開發者經 SSH 存取 SG/JP/HK 節點，命令列往返常見 15–35 ms；隧道額外開銷通常 < 5 ms，可忽略。
- Token 檔案權限：必須 600；擁有者與 Gateway 行程使用者不一致時，launchd 可能靜默拒絕載入。
#!/bin/bash
TOKEN="${OPENCLAW_GATEWAY_TOKEN:?}"
CODE=$(curl -sf -o /dev/null -w '%{http_code}' \
-H "Authorization: Bearer $TOKEN" http://127.0.0.1:18789/health)
[[ "$CODE" == "200" ]] || exit 106 常見 FAQ、Health pending 對照與 JEXCLOUD 選型收束
| 現象 | 優先檢查 | 處理動作 |
|---|---|---|
| CLI 200，UI pending | App 快取、Transport 模式、本機 localhost 轉發 | 重啟 App；確認 Remote+SSH；重跑 Test remote |
| pairing / token mismatch | 雙軌 Token、device token 檔案 | 統一 plist 與 App 內 Token；參考官方 remote gateway 文件重設配對 |
| Connection refused | 隧道行程、連接埠佔用 | launchctl list | grep openclaw；檢查 18789 |
| 隧道頻繁斷線 | 筆電睡眠、NAT 逾時 | ServerAlive；隧道 KeepAlive plist；避免僅依賴手動 ssh -N |
用家用寬頻或不穩定 Wi‑Fi做 7×24 隧道入口，常因 NAT 逾時與睡眠策略導致「早上還能用、下午全紅」；把 Gateway 放在分時 VPS 或超賣虛擬化上，則可能在鄰居爭搶時出現 Health 間歇失敗；純本機 Mac 還受自動更新重啟、Keychain 彈窗無人值守影響。對需要本機 App 穩定遙控、Token 可稽核、隧道可自愈的團隊，把 Gateway 落在 JEXCLOUD 多區域裸金屬 Mac 上，再用 SSH 回環 + LaunchAgent 常駐，通常是更省心的組合：獨占 Apple Silicon、約 120 秒交付，可按專案並聯或升級 M4 Pro。方案與節點見 JEXCLOUD 定價頁；若需圖形排障可配合 VNC 頁面 說明開通遠端桌面。