Appearance
远程 OpenClaw（macOS ⇄ 远程主机）
这套流程让 macOS 应用充当运行在另一台主机（桌面/服务器）上的 OpenClaw 网关的完整远程控制端。这是应用的Remote over SSH（远程运行）功能。所有功能——健康检查、Voice Wake 转发和 Web Chat——均复用 Settings → General 中的同一套远程 SSH 配置。
模式说明
- 本地（this Mac）：所有内容在本机运行，不涉及 SSH。
- Remote over SSH（默认）：OpenClaw 命令在远程主机上执行。Mac 应用使用
-o BatchMode加上所选身份/密钥以及本地端口转发打开 SSH 连接。 - Remote direct（ws/wss）：无 SSH 隧道，Mac 应用直接连接到网关 URL（例如通过 Tailscale Serve 或公共 HTTPS 反向代理）。
远程传输协议
远程模式支持两种传输协议：
- SSH 隧道（默认）：使用
ssh -N -L ...将网关端口转发到 localhost。网关会看到节点 IP 为127.0.0.1，因为隧道走回环地址。 - 直连（ws/wss）：直接连接到网关 URL。网关看到真实客户端 IP。
远程主机前置条件
- 安装 Node + pnpm，构建并安装 OpenClaw CLI（
pnpm install && pnpm build && pnpm link --global）。 - 确保
openclaw在非交互式 shell 的 PATH 中（如需要，将其符号链接到/usr/local/bin或/opt/homebrew/bin）。 - 开启 SSH 密钥认证。推荐使用 Tailscale IP，确保离开局域网后仍可稳定访问。
macOS 应用设置
- 打开 Settings → General。
- 在 OpenClaw runs 下选择 Remote over SSH 并设置：
- Transport：SSH tunnel 或 Direct (ws/wss)。
- SSH target：
user@host（可选:port）。- 如果网关在同一局域网并通过 Bonjour 广播，可从发现列表中选择以自动填充此字段。
- Gateway URL（仅直连）：
wss://gateway.example.ts.net（局域网/本地可用ws://...）。 - Identity file（高级）：密钥路径。
- Project root（高级）：用于命令的远程检出路径。
- CLI path（高级）：可运行的
openclaw入口点/二进制文件的可选路径（广播时自动填充）。
- 点击 Test remote。成功表示远程
openclaw status --json可正常运行。失败通常意味着 PATH/CLI 问题；exit 127 表示远程找不到 CLI。 - 健康检查和 Web Chat 现在会自动通过这条 SSH 隧道运行。
Web Chat
- SSH 隧道：Web Chat 通过转发的 WebSocket 控制端口（默认 18789）连接到网关。
- 直连（ws/wss）：Web Chat 直接连接到配置的网关 URL。
- 不再有独立的 WebChat HTTP 服务器。
权限要求
- 远程主机需要与本地相同的 TCC 授权（自动化、辅助功能、屏幕录制、麦克风、语音识别、通知）。在该机器上运行 onboarding 一次性授权即可。
- 节点通过
node.list/node.describe广播其权限状态，以便 Agent 了解可用功能。
安全说明
- 优先在远程主机上绑定回环地址，通过 SSH 或 Tailscale 连接。
- SSH 隧道使用严格的主机密钥检查；请先信任主机密钥，确保其存在于
~/.ssh/known_hosts。 - 如果将 Gateway 绑定到非回环接口，请要求 token/密码认证。
- 参见 Security 和 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 卡住：确认网关在远程主机上运行，且转发端口与网关 WS 端口匹配；UI 需要健康的 WS 连接。
- Node IP 显示 127.0.0.1：SSH 隧道模式下的预期行为。如果希望网关看到真实客户端 IP，请将 Transport 切换为 Direct (ws/wss)。
- Voice Wake：触发短语在远程模式下自动转发，无需额外配置转发器。
通知声音
通过脚本使用 openclaw 和 node.invoke 为每条通知选择声音，例如：
bash
openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass应用中不再有全局"默认声音"开关；调用方按需为每次请求选择声音（或不选）。