OpenClaw SSH 隧道 2026.05.19

OpenClaw 2026 远程 Gateway 配对与 SSH 隧道： macOS 客户端 Health Check 排障与 LaunchAgent 常驻清单

JEX
JEXCLOUD 工程团队
· 2026年5月19日 · 约 11 分钟阅读

已在 JEXCLOUD 云端 Mac 上跑通 OpenClaw Gateway，却在本机 macOS 应用里卡在 「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 隧道 vs Direct WSS 远程 Gateway 对照（2026 生产视角）
维度 SSH 隧道 + LocalForward Direct WSS
安全边界 Gateway 仅监听 127.0.0.1；出网走 SSH 加密 需 TLS 终止与 Token；常配合 Tailscale / 内网 DNS
防火墙友好度 仅需 SSH 22（或自定义端口）可达 需放行 wss 端口与证书链；企业代理下易失败
延迟与稳定性 多一跳 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 的用户一致。

~/.ssh/config（本机笔记本） 
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
~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist（节选） 
<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 验活

  1. 远端安装 CLI 并启动 Gateway：在 JEXCLOUD 实例上执行 openclaw gateway install（或按应用引导安装 LaunchAgent），确认 lsof -i :18789 仅监听 127.0.0.1。
  2. 写入并校验 Token：生成 Gateway Token，chmod 600 保存；launchctl setenv OPENCLAW_GATEWAY_TOKEN '…' 后重启 Gateway Agent。
  3. 本机配置 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。
  4. 安装隧道 LaunchAgent：launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist，确认登录后隧道自动拉起。
  5. macOS 客户端配对：设置 → OpenClaw runs → 选 Remote + SSH tunnel，填写 user@host（若走 config 别名可仅填 Host），点击 Test remote 直至通过。
  6. 登记巡检与告警：将 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 可能静默拒绝加载。
health-patrol.sh 
#!/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 1

06 常见 FAQ、Health pending 对照与 JEXCLOUD 选型收束

CLI 健康 vs macOS UI pending 对照排障
现象 优先检查 处理动作
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 页面 说明开通远程桌面。

返回博客列表
标签： OpenClaw SSH 隧道 Health Check LaunchAgent