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

此流程让 macOS 应用充当运行在另一台主机（桌面/服务器）上的 OpenClaw gateway 的完整远程控制。这是应用的 Remote over SSH（远程运行）功能。所有功能——健康检查、Voice Wake 转发和 Web Chat——复用来自"设置 → 通用"的相同远程 SSH 配置。

模式

• 本地（此 Mac）：所有内容在笔记本上运行。不涉及 SSH。
• Remote over SSH（默认）：OpenClaw 命令在远程主机上执行。Mac 应用使用 -o BatchMode 加上你选择的身份/密钥以及本地端口转发打开 SSH 连接。
• Remote direct（ws/wss）：无 SSH 隧道。Mac 应用直接连接到 gateway URL（例如通过 Tailscale Serve 或公共 HTTPS 反向代理）。

远程传输方式

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

• SSH 隧道（默认）：使用 ssh -N -L ... 将 gateway 端口转发到 localhost。由于隧道是回环的，gateway 会看到节点 IP 为 127.0.0.1。
• 直连（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. 打开设置 → 通用。
2. 在 OpenClaw runs 下，选择 Remote over SSH 并设置：
   • Transport：SSH tunnel 或 Direct (ws/wss)。
   • SSH target：user@host（可选 :端口）。
     • 如果 gateway 在同一 LAN 上且通告了 Bonjour，从发现列表中选择以自动填充此字段。
   • Gateway URL（仅 Direct）：wss://gateway.example.ts.net（或 ws://... 用于本地/LAN）。
   • Identity file（高级）：密钥路径。
   • Project root（高级）：用于命令的远程 checkout 路径。
   • 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。
• 直连（ws/wss）：Web Chat 直接连接到配置的 gateway URL。
• 不再有单独的 WebChat HTTP 服务器。

权限

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

安全须知

• 优先在远程主机上使用回环绑定，通过 SSH 或 Tailscale 连接。
• SSH 隧道使用严格的主机密钥检查；先信任主机密钥使其存在于 ~/.ssh/known_hosts 中。
• 如果你将 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 卡住：确认 gateway 正在远程主机上运行，且转发端口与 gateway WS 端口匹配；UI 需要健康的 WS 连接。
• 节点 IP 显示 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

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