古法编程

Appearance

OpenClaw macOS 远程控制功能让你从本地 Mac 管理另一台主机上的网关。支持 SSH 隧道（默认，ssh -N -L 回环转发）和直连（ws/wss，见真实客户端 IP）。配置前需在远程主机上安装 Node/pnpm、将 openclaw 加入非交互 shell 的 PATH，并开启 SSH 密钥认证。设置完成后，点击 Test remote 验证 openclaw status --json 能否正常执行。

OpenClaw macOS 远程控制配置（SSH 隧道/直连） ​

这套流程让 macOS 应用充当运行在另一台主机（桌面/服务器）上的 OpenClaw 网关的完整远程控制端。所有功能——健康检查、Voice Wake 转发和 Web Chat——均复用 Settings → General 中的同一套远程配置。

三种运行模式 ​

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

传输协议选择 ​

远程模式支持两种传输协议：

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

SSH 隧道模式下，发现的局域网/Tailnet 主机名会保存为 gateway.remote.sshTarget，应用的 gateway.remote.url 保持为本地隧道端点（例如 ws://127.0.0.1:18789），这样 CLI、Web Chat 和本地节点主机服务都使用同一安全的回环传输。如果本地隧道端口与远程网关端口不同，需设置 gateway.remote.remotePort 为远程主机上的端口。

远程模式下的浏览器自动化由 CLI 节点主机负责，而非原生 macOS app 节点。应用会尽可能启动已安装的节点主机服务；如需从该 Mac 控制浏览器，可执行 openclaw node install ... 和 openclaw node start（或前台运行 openclaw node run ...），然后指定该具备浏览器能力的节点。

远程主机前置条件 ​

  1. 安装 Node + pnpm，构建并安装 OpenClaw CLI：
    bash
    pnpm install && pnpm build && pnpm link --global
  2. 确保 openclaw 在非交互式 shell 的 PATH 中（如需要，将其符号链接到 /usr/local/bin 或 /opt/homebrew/bin）。
  3. 开启 SSH 密钥认证。推荐使用 Tailscale IP，确保离开局域网后仍可稳定访问。

macOS 应用设置 ​

命令行预配置（无需欢迎流程） ​

bash
openclaw-mac configure-remote \
  --ssh-target user@gateway.local \
  --local-port 18789 \
  --remote-port 18789 \
  --token "$OPENCLAW_GATEWAY_TOKEN"

对于已在可信局域网或 Tailnet 上的网关，可跳过 SSH：

bash
openclaw-mac configure-remote \
  --direct-url ws://192.168.0.202:18789 \
  --token "$OPENCLAW_GATEWAY_TOKEN"

这会将远程配置写入、标记 onboarding 完成，并在应用启动时让应用拥有所选传输协议。

图形界面设置 ​

  1. 打开 Settings → General。
  2. 在 OpenClaw runs 下选择 Remote 并设置：
    • 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 入口点/二进制文件的可选路径（广播时自动填充）。
  3. 点击 Test remote。成功表示远程 openclaw status --json 可正常运行。失败通常意味着 PATH/CLI 问题；exit 127 表示远程找不到 CLI。
  4. 健康检查和 Web Chat 现在会自动通过所选传输协议运行。

Web Chat 连接 ​

  • SSH 隧道：Web Chat 通过转发的 WebSocket 控制端口（默认 18789）连接到网关。
  • 直连（ws/wss）：Web Chat 直接连接到配置的网关 URL。
  • 不再有独立的 WebChat HTTP 服务器。

权限要求 ​

  • 远程主机需要与本地相同的 TCC 授权（自动化、辅助功能、屏幕录制、麦克风、语音识别、通知）。在该机器上运行 onboarding 一次性授权即可。
  • 节点通过 node.list / node.describe 广播其权限状态，以便智能体了解可用功能。

安全说明 ​

  • 优先在远程主机上绑定回环地址，通过 SSH、Tailscale Serve 或可信 Tailnet/LAN 直连 URL 连接。
  • SSH 隧道使用严格的主机密钥检查；请先信任主机密钥，确保其存在于 ~/.ssh/known_hosts。
  • 如果将网关绑定到非回环接口，请要求有效的网关认证：token、密码，或配合 gateway.auth.mode: "trusted-proxy" 的认证感知反向代理。
  • 参见 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)。
  • Dashboard 正常但 Mac 能力离线：这意味着应用的 operator/control 连接健康，但 companion 节点连接未连接或缺少命令界面。打开菜单栏设备区，检查 Mac 是否显示 paired · disconnected。对于 wss://*.ts.net Tailscale Serve 端点，应用会在证书轮换后检测到过时的遗留 TLS 叶销钉，当 macOS 信任新证书时清除旧销钉并自动重试。如果证书未被系统信任或主机不是 Tailscale Serve 名称，可设置 gateway.remote.tlsFingerprint 为期望的证书指纹、审查证书，或切换为 Remote over SSH。
  • Voice Wake：触发短语在远程模式下自动转发，无需额外配置转发器。

通知声音 ​

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

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

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

常见问题 ​

为什么 Test remote 报 exit 127？ ​

openclaw 命令在远程主机的非交互 shell 中找不到。检查远程主机上 which openclaw 的输出，并确保其路径已加入 /etc/paths、shell 配置文件（如 .bashrc、.zshrc），或通过符号链接到 /usr/local/bin 或 /opt/homebrew/bin。重新启动 SSH 会话后再次测试。

远程 Web Chat 一直卡住不显示怎么解决？ ​

先确认远程主机上的 OpenClaw 网关正在运行（openclaw status）。然后检查 Settings → General 中 Transport 选择的模式对应的端口号是否正确。SSH 隧道模式下，本地转发端口（默认 18789）必须与远程网关的 WebSocket 端口一致。直连模式下，确保 Gateway URL 可访问且未配置认证拦截。

Mac 能力显示离线，但仪表板正常，如何恢复？ ​

仪表板正常表示 operator 连接健康，但 companion 节点未连接。打开菜单栏设备区，确认 Mac 状态是否为 paired · disconnected。如果使用 Tailscale Serve 且证书刚轮换，应用会自动检测并重试；若未自动恢复，可尝试将 Transport 切换为 Remote over SSH 绕过证书问题，或手动设置 gateway.remote.tlsFingerprint 为当前证书指纹。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策