远程控制的应用场景
当你在 VPS 或家用服务器上长期运行 OpenClaw Gateway 时，macOS 应用可以切换到「远程模式」，直接管理和操控远端 Gateway——无需在本地再起一个 Gateway 进程。你的 Mac 成为远端 Gateway 的「控制台」，同时也作为节点向其贡献摄像头、屏幕、Canvas 等本地能力。
三种工作模式
| 模式 | 说明 |
|---|---|
| 本地（this Mac） | 所有操作在本机执行，无 SSH |
| 远程（SSH 默认） | 通过 SSH 端口转发连接远端 Gateway |
| 直连（ws/wss） | 直接 WebSocket 连接，无 SSH 隧道 |
传输方式对比
SSH 隧道模式（推荐）：
使用 ssh -N -L 建立端口转发，Gateway 看到的客户端 IP 为 loopback（127.0.0.1），安全性最高，适合 Gateway 保持 loopback 绑定的部署方式。
直连（ws/wss）模式：
直接连接 Gateway WebSocket 地址（如 wss://gateway.example.ts.net），Gateway 能看到真实客户端 IP。适合通过 Tailscale 接入且 Gateway 已绑定 tailnet 的场景。
配置步骤
在 macOS 应用中进入「设置 → General」：
- 模式选择「Remote over SSH」
- 传输类型选「SSH tunnel」或「Direct (ws/wss)」
- 填写「SSH target」，格式为
user@host或user@host:port - 直连模式下填写 Gateway URL，如
wss://gateway.example.ts.net - 可选填写 identity file、project root、CLI 路径
- 点击「Test remote」验证连通性
测试成功意味着远端能正常执行 openclaw status --json 命令。
远端主机准备
远端主机需要满足以下条件：
- 安装 Node.js 和 pnpm，并编译好 OpenClaw CLI
- CLI 可在非交互式 Shell 的 PATH 中被找到，建议创建软链接：
ln -s $(which openclaw) /usr/local/bin/openclaw
# 或
ln -s $(which openclaw) /opt/homebrew/bin/openclaw
- 开启 SSH 密钥认证（推荐使用 Tailscale IP 作为主机地址，稳定可靠）
WebChat 集成
- SSH 隧道模式： WebSocket 通过转发的控制端口（默认 18789）连接，无需额外 HTTP 服务器
- 直连模式： WebSocket 直接连接配置的 Gateway URL
远端节点权限
远端 macOS 主机需要与本地相同的 TCC 授权（辅助功能、屏幕录制、麦克风、语音识别等），这些权限决定了节点通过 node.list 和 node.describe 对外声明的可用能力。
远程 WhatsApp 登录
在远端主机上执行以下命令，扫描二维码完成 WhatsApp 认证：
openclaw channels login --verbose
故障排查
| 问题 | 解决方案 |
|---|---|
exit 127 / not found |
将 openclaw 添加到 PATH，或通过 /etc/paths 全局生效 |
| 健康探测失败 | 检查 SSH 连通性、PATH 配置和 Gateway 登录状态 |
| WebChat 无响应 | 确认 Gateway 正在运行，端口转发配置正确 |
| 节点 IP 显示 127.0.0.1 | SSH 隧道模式的正常现象，切换到直连模式可看到真实 IP |
跨节点通知推送
通过 CLI 向远端节点推送系统通知：
openclaw nodes notify --node <id> \
--title "Ping" \
--body "Remote gateway ready" \
--sound Glass