远程 OpenClaw（macOS ⇄ 远程主机）

这个功能让 macOS 应用可以完全远程控制运行在另一台主机（桌面电脑或服务器）上的 OpenClaw Gateway。这就是应用的 Remote over SSH（远程运行）功能。所有功能——健康检查、Voice Wake 转发和 Web Chat——都会复用 Settings → General 中的同一套远程 SSH 配置。

运行模式

  • Local (this Mac)：所有东西都在本地笔记本上运行，不涉及 SSH。
  • Remote over SSH（默认）：OpenClaw 命令在远程主机上执行。Mac 应用会用 -o BatchMode 加上你选择的身份文件/密钥打开一个 SSH 连接，并建立本地端口转发。
  • Remote direct (ws/wss)：不用 SSH 隧道。Mac 应用直接连接到 Gateway URL（比如通过 Tailscale Serve 或公网 HTTPS 反向代理）。

远程传输方式

远程模式支持两种传输方式：

  • SSH tunnel（默认）：用 ssh -N -L ... 把 Gateway 端口转发到 localhost。Gateway 会看到节点的 IP 是 127.0.0.1，因为隧道是回环的。
  • Direct (ws/wss)：直接连接到 Gateway URL。Gateway 能看到真实的客户端 IP。

远程主机的前置要求

  1. 安装 Node + pnpm，然后构建并安装 OpenClaw CLI（pnpm install && pnpm build && pnpm link --global）。
  2. 确保 openclaw 在非交互式 shell 的 PATH 中（如果需要的话，可以软链接到 /usr/local/bin 或 /opt/homebrew/bin）。
  3. 开启 SSH 密钥认证。我们推荐用 Tailscale IP 来保证在局域网外也能稳定访问。

macOS 应用设置

  1. 打开 Settings → General。
  2. 在 OpenClaw runs 下，选择 Remote over SSH 并设置：
    • Transport：SSH tunnel 或 Direct (ws/wss)。
    • SSH target：user@host（可选 :port）。
      • 如果 Gateway 在同一局域网并广播了 Bonjour，可以从发现列表中选择它来自动填充这个字段。
    • Gateway URL（仅 Direct 模式）：wss://gateway.example.ts.net（或本地/局域网用 ws://...）。
    • Identity file（高级）：你的密钥文件路径。
    • Project root（高级）：远程代码库路径，用于执行命令。
    • CLI path（高级）：可选的 openclaw 可执行文件路径（广播时会自动填充）。
  3. 点击 Test remote。成功表示远程的 openclaw status --json 运行正常。失败通常意味着 PATH 或 CLI 问题；退出码 127 表示远程找不到 CLI。
  4. 健康检查和 Web Chat 现在会自动通过这个 SSH 隧道运行。

Web Chat

  • SSH tunnel：Web Chat 通过转发的 WebSocket 控制端口（默认 18789）连接到 Gateway。
  • Direct (ws/wss)：Web Chat 直接连接到配置的 Gateway URL。
  • 不再有单独的 WebChat HTTP 服务器了。

权限

  • 远程主机需要和本地一样的 TCC 授权（自动化、辅助功能、屏幕录制、麦克风、语音识别、通知）。在那台机器上运行一次引导流程来授予这些权限。
  • 节点会通过 node.list / node.describe 广播它们的权限状态，这样 Agent 就知道有哪些功能可用。

安全提示

  • 优先在远程主机上绑定回环地址，然后通过 SSH 或 Tailscale 连接。
  • 如果你把 Gateway 绑定到非回环接口，务必启用 token/密码认证。
  • 参见安全和 Tailscale。

WhatsApp 登录流程（远程）

  • 在远程主机上运行 openclaw channels login --verbose。用手机上的 WhatsApp 扫描二维码。
  • 如果认证过期，在那台主机上重新运行登录。健康检查会显示连接问题。

故障排除

  • exit 127 / not found：openclaw 不在非登录 shell 的 PATH 中。把它加到 /etc/paths、你的 shell rc 文件，或者软链接到 /usr/local/bin//opt/homebrew/bin。
  • Health probe failed：检查 SSH 可达性、PATH，以及 Baileys 是否已登录（openclaw status --json）。
  • Web Chat stuck：确认 Gateway 在远程主机上运行，并且转发的端口和 Gateway WS 端口匹配；UI 需要健康的 WS 连接。
  • Node IP shows 127.0.0.1：用 SSH 隧道时这是正常的。如果你想让 Gateway 看到真实的客户端 IP，把 Transport 切换到 Direct (ws/wss)。
  • Voice Wake：触发短语在远程模式下会自动转发；不需要单独的转发器。

通知声音

用 openclaw 和 node.invoke 从脚本中为每个通知选择声音，例如：

openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass

应用里不再有全局的”默认声音”开关了；调用者为每个请求选择声音（或不用声音）。