OpenClaw macOS 应用可以作为远程主机上 OpenClaw 网关的完整远程控制器。这是应用的"通过 SSH 远程运行"功能。
运行模式
- 本地模式(此 Mac):所有功能都在本机运行,无需 SSH
- 通过 SSH 远程(默认):OpenClaw 命令在远程主机上执行。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,构建并安装 OpenClaw CLI(
pnpm install && pnpm build && pnpm link --global) - 确保
openclaw在非交互式 shell 的 PATH 中(如需要可创建符号链接到/usr/local/bin或/opt/homebrew/bin) - 开启 SSH 密钥认证。建议使用 Tailscale IP 以保证局域网外的稳定连接
macOS 应用设置
- 打开"设置 → 通用"
- 在"OpenClaw 运行于"下选择"通过 SSH 远程",并设置:
- 传输方式:SSH 隧道 或 直连(ws/wss)
- SSH 目标:
user@host(可选:port) - 如果网关在同一局域网上并广播 Bonjour,可以从发现列表中选择以自动填充此字段
- 网关 URL(仅直连模式):
wss://gateway.example.ts.net(或本地/局域网使用ws://...) - 身份文件(高级):密钥路径
- 项目根目录(高级):远程代码库路径,用于命令执行
- CLI 路径(高级):可选的可运行
openclaw入口点/二进制文件路径(在广播时自动填充)
- 点击"测试远程"。成功表示远程
openclaw status --json正确运行。失败通常意味着 PATH/CLI 问题;退出代码 127 表示远程找不到 CLI - 健康检查和 Web Chat 现在将自动通过此 SSH 隧道运行
Web Chat
- SSH 隧道:Web Chat 通过转发的 WebSocket 控制端口(默认 18789)连接到网关
- 直连(ws/wss):Web Chat 直接连接到配置的网关 URL
- 不再有单独的 WebChat HTTP 服务器
权限要求
远程主机需要与本地相同的 TCC 审批(自动化、辅助功能、屏幕录制、麦克风、语音识别、通知)。在该机器上运行入门向导以一次性授予这些权限。节点通过 node.list / node.describe 广播其权限状态,以便代理知道可用的功能。
安全注意事项
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 stuck":确认网关在远程主机上运行,且转发端口与网关 WS 端口匹配;UI 需要健康的 WS 连接
- "Node IP shows 127.0.0.1":SSH 隧道的预期行为。如果希望网关看到真实客户端 IP,将传输方式切换为直连(ws/wss)
- "Voice Wake":触发短语在远程模式下自动转发;无需单独的转发器
通知音效
通过 openclaw 和 node.invoke 从脚本为每个通知选择音效:
openclaw nodes notify --node --title "Ping" --body "Remote gateway ready" --sound Glass应用中不再有全局"默认音效"切换;调用者为每个请求选择音效(或不选)