远程 OpenClaw（macOS 控制远程主机）

此流程允许 macOS 应用作为在另一台主机（桌面/服务器）上运行的 OpenClaw gateway 的完整遥控器。它是应用的通过 SSH 远程（远程运行）功能。所有功能—健康检查、语音唤醒转发和 Web Chat —重用 Settings → General 中的相同远程 SSH 配置。

模式

  • 本地（此 Mac）：一切在笔记本电脑上运行。无 SSH 涉及。
  • 通过 SSH 远程（默认）：OpenClaw 命令在远程主机上执行。mac 应用打开 SSH 连接，带有 -o BatchMode 以及您选择的身*份密钥和本地端口转发。
  • 远程直连（ws/wss）：无 SSH 隧道。mac 应用直接连接 gateway URL（例如，通过 Tailscale Serve 或公共 HTTPS 反向代理）。

远程传输

远程模式支持两种传输：

  • SSH 隧道（默认）：使用 ssh -N -L ... 将 gateway 端口转发到 localhost。gateway 会将节点 IP 视为 127.0.0.1，因为隧道是 loopback。
  • 直连（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 以便在 LAN 外稳定访问。

macOS 应用设置

  1. 打开 Settings → General。
  2. 在 OpenClaw runs 下，选择 Remote over SSH 并设置：
    • 传输：SSH 隧道 或 直连（ws/wss）。
    • SSH 目标：user@host（可加 :port）：
      • 如果 gateway 在同一 LAN 上并通告 Bonjour，从发现的列表中选择它以自动填充此字段。
    • Gateway URL（仅直连）：wss://gateway.example.ts.net（或 ws://... 用于本地/LAN）。
    • 身份文件（高级）：您的密钥路径。
    • 项目（高级）：用于命令的远程检出路径。
    • CLI 路径（高级）：可选的可运行 openclaw 入口点二进制（在被通告时自动填充）。
  3. 点击 Test remote。成功表示远程 openclaw status --json 正常运行。失败通常意味着 PATH/CLI 问题；退出码 127 表示远程找不到 CLI。
  4. 健康检查和 Web Chat 现在将自动通过 SSH 隧道运行。

Web Chat

  • SSH 隧道：Web Chat 通过转发 WebSocket 控制端口（默认 18789）连接到 gateway。
  • 直连（ws/wss）：Web Chat 直连到配置的 gateway URL。
  • 不再有独立的 WebChat HTTP 服务器。

权限

  • 远程主机需要与本地相同的 TCC 批准（自动化、辅助功能、屏幕录制、麦克风、语音识别、通知）。在该机器上运行 onboarding 以授予它们一次。
  • 节点通过 node.list / node.describe 通告其权限状态，以便代理知道可用的功能。

安全说明

  • 优先在远程主机上使用 loopback 绑定并通过 SSH 或 Tailscale 连接。
  • SSH 隧道使用严格的主机密钥检查；首先信任主机密钥，使其存在于 ~/.ssh/known_hosts 中。
  • 如果您将 Gateway 绑定到非 loopback 接口，则需要令牌密码认证。
  • 请参见 安全 和 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 卡住：确保 gateway 在远程主机上运行且转发的端口与 gateway WS 端口匹配；UI 需要健康的 WS 连接。
  • Node IP 显示 127.0.0.1：使用 SSH 隧道是预期的。如果您希望 gateway 看到真实客户机 IP，请将传输切换到直连（ws/wss）。
  • 语音唤醒：触发短语在远程模式下自动转发；不需要单独的转发器。

通知声音

通过脚本使用 openclaw 或 node.invoke 为每个通知选择声音，例如：

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

应用中不再有全局”默认声音”开关；调用者为每个请求选择声音（或无）?