远程 OpenClaw（macOS ⇄ 远程主机）

这个流程让 macOS 应用充当远程 OpenClaw Gateway 的完整控制端。它就是应用中的 Remote over SSH（远程运行）功能。所有功能——健康检查、语音唤醒转发、Web Chat——都复用 Settings → General 中的同一份远程 SSH 配置。

模式

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

远程传输方式

Remote 模式支持两种传输：

• 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. 确保非交互式 shell 的 PATH 中有 openclaw（需要的话把它软链接到 /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 问题；exit 127 表示远程找不到 CLI。
4. 健康检查和 Web Chat 会自动走 SSH 隧道。

Web Chat

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

权限

• 远程主机需要和本地一样的 TCC 授权（Automation、Accessibility、Screen Recording、Microphone、Speech Recognition、Notifications）。在该机器上运行一次 onboarding 来授权。
• 节点通过 node.list / node.describe 广播其权限状态，agent 据此判断可用能力。

安全建议

• 远程主机优先 loopback 绑定，通过 SSH 或 Tailscale 连接。
• SSH 隧道使用严格主机密钥检查；先信任主机密钥以便 ~/.ssh/known_hosts 中存在记录。
• 如果把 Gateway 绑定到非 loopback 接口，要求 token/密码认证。
• 参见 安全 和 Tailscale。

WhatsApp 登录流程（远程）

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

故障排查

• exit 127 / not found：非登录 shell 的 PATH 中没有 openclaw。添加到 /etc/paths、shell rc，或软链接到 /usr/local/bin//opt/homebrew/bin。
• 健康探测失败：检查 SSH 可达性、PATH，以及 Baileys 是否已登录（openclaw status --json）。
• Web Chat 卡住：确认远程主机上 Gateway 正在运行，且转发端口与 Gateway WS 端口一致；UI 需要健康的 WS 连接。
• Node IP 显示 127.0.0.1：SSH 隧道的正常现象。如果需要 Gateway 看到真实客户端 IP，把 Transport 切换到 Direct (ws/wss)。
• 语音唤醒：触发短语在 Remote 模式下自动转发，不需要单独的转发器。

通知声音

通过脚本中的 openclaw 和 node.invoke 为每条通知选择声音，例如：

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

应用中不再有全局 “默认声音” 开关；调用方按请求选择声音（或不选）。