远程 Clawdbot（macOS ⇄ 远程主机）

适用范围

在以下情况使用此页面：

此流程让 macOS 应用可以作为远程 Clawdbot 网关的完整远程控制，该网关运行在另一台主机（桌面/服务器）上。这是应用的通过 SSH 远程运行功能。所有功能——健康检查、语音唤醒转发和 Web 聊天——都重用来自设置 → 通用的相同远程 SSH 配置。

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

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

SSH 隧道（默认）：使用 ssh -N -L ... 将网关端口转发到 localhost。网关将节点的 IP 视为 127.0.0.1，因为隧道是回环的。
直连（ws/wss）：直接连接到网关 URL。网关看到真实的客户端 IP。

安装 Node + pnpm 并构建/安装 Clawdbot CLI（pnpm install && pnpm build && pnpm link --global）。
确保 clawdbot 在非交互式 shell 的 PATH 上（如需要，符号链接到 /usr/local/bin 或 /opt/homebrew/bin）。
使用密钥认证打开 SSH。我们推荐 Tailscale IP 以实现稳定的局域网外可达性。

打开设置 → 通用。
在 Clawdbot 运行下，选择通过 SSH 远程并设置：
- 传输方式：SSH 隧道或直连（ws/wss）。
- SSH 目标：user@host（可选 :port）。
  - 如果网关在同一局域网上并宣传 Bonjour，从发现的列表中选择它以自动填充此字段。
- 网关 URL（仅直连）：wss://gateway.example.ts.net（或本地/LAN 使用 ws://...）。
- 身份文件（高级）：你的密钥路径。
- 项目根目录（高级）：用于命令的远程检出路径。
- CLI 路径（高级）：可选的可运行 clawdbot 入口点/二进制文件路径（宣传时自动填充）。
点击测试远程。成功表示远程 clawdbot status --json 正确运行。失败通常意味着 PATH/CLI 问题；退出 127 表示远程未找到 CLI。
健康检查和 Web 聊天现在将自动通过此 SSH 隧道运行。

exit 127 / not found：clawdbot 不在非登录 shell 的 PATH 上。将其添加到 /etc/paths、shell rc 或符号链接到 /usr/local/bin//opt/homebrew/bin。
Health probe failed：检查 SSH 可达性、PATH 以及 Baileys 是否已登录（clawdbot status --json）。
Web Chat 卡住：确认网关在远程主机上运行且转发的端口与网关 WS 端口匹配；UI 需要健康的 WS 连接。
节点 IP 显示 127.0.0.1：SSH 隧道的预期行为。如果希望网关看到真实的客户端 IP，请将传输方式切换到直连（ws/wss）。
语音唤醒：触发短语在远程模式下自动转发；不需要单独的转发器。

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

clawdbot nodes notify --node <id> --title "Ping" --body "远程网关就绪" --sound Glass

应用中不再有全局"默认声音"切换；调用者根据请求选择声音（或无）。