远程访问（SSH、隧道和 tailnet）

这个项目支持”通过 SSH 远程访问”，方式是在专用主机（台式机/服务器）上运行单个 Gateway（主节点），然后让客户端连接到它。

  • 对于操作者（你/macOS 应用）：SSH 隧道是通用的备用方案。
  • 对于节点（iOS/Android 和未来的设备）：连接到 Gateway WebSocket（根据需要使用局域网/tailnet 或 SSH 隧道）。

核心思路

  • Gateway WebSocket 绑定到你配置的端口上的 loopback（默认是 18789）。
  • 远程使用时，你通过 SSH 转发那个 loopback 端口（或者使用 tailnet/VPN，减少隧道需求）。

常见的 VPN/tailnet 设置（Agent 运行的位置）

把 Gateway 主机想象成”Agent 运行的地方”。它拥有 Session、认证配置、Channel 和状态。 你的笔记本/台式机（以及节点）连接到那个主机。

1) 在 tailnet 中运行常驻 Gateway（VPS 或家庭服务器）

在持久运行的主机上运行 Gateway，通过 Tailscale 或 SSH 访问它。

  • 最佳体验： 保持 gateway.bind: "loopback" 并使用 Tailscale Serve 提供控制界面。
  • 备用方案： 保持 loopback + 从任何需要访问的机器建立 SSH 隧道。
  • 示例： exe.dev（简单的虚拟机）或 Hetzner（生产环境 VPS）。

当你的笔记本经常休眠，但你希望 Agent 始终在线时，这是理想的方案。

2) 家里的台式机运行 Gateway，笔记本作为远程控制

笔记本不运行 Agent。它远程连接：

  • 使用 macOS 应用的 Remote over SSH 模式（Settings → General → “OpenClaw runs”）。
  • 应用会打开并管理隧道，所以 WebChat + 健康检查”开箱即用”。

操作手册：macOS 远程访问。

3) 笔记本运行 Gateway，从其他机器远程访问

保持 Gateway 在本地，但安全地暴露它：

  • 从其他机器通过 SSH 隧道连接到笔记本，或
  • 用 Tailscale Serve 提供控制界面，并保持 Gateway 仅限 loopback。

指南：Tailscale 和 Web 概览。

命令流程（什么在哪里运行）

一个 Gateway 服务拥有状态 + Channel。节点是外围设备。

流程示例（Telegram → 节点）：

  • Telegram 消息到达 Gateway。
  • Gateway 运行 Agent 并决定是否调用节点工具。
  • Gateway 通过 Gateway WebSocket（node.* RPC）调用节点。
  • 节点返回结果；Gateway 将回复发送回 Telegram。

注意事项：

  • 节点不运行 Gateway 服务。 每个主机只应运行一个 Gateway，除非你有意运行隔离的配置文件（参见 多个 Gateway）。
  • macOS 应用的”节点模式”只是通过 Gateway WebSocket 连接的节点客户端。

SSH 隧道（CLI + 工具）

创建到远程 Gateway WS 的本地隧道：

ssh -N -L 18789:127.0.0.1:18789 user@host

隧道建立后：

  • openclaw health 和 openclaw status --deep 现在通过 ws://127.0.0.1:18789 访问远程 Gateway。
  • openclaw gateway {status,health,send,agent,call} 也可以在需要时通过 --url 指定转发的 URL。

注意：将 18789 替换为你配置的 gateway.port（或 --port/OPENCLAW_GATEWAY_PORT）。

CLI 远程默认设置

你可以持久化远程目标，让 CLI 命令默认使用它：

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token",
    },
  },
}

当 Gateway 仅限 loopback 时，保持 URL 为 ws://127.0.0.1:18789 并先打开 SSH 隧道。

通过 SSH 使用聊天界面

WebChat 不再使用单独的 HTTP 端口。SwiftUI 聊天界面直接连接到 Gateway WebSocket。

  • 通过 SSH 转发 18789（见上文），然后让客户端连接到 ws://127.0.0.1:18789。
  • 在 macOS 上，推荐使用应用的”Remote over SSH”模式，它会自动管理隧道。

macOS 应用的”Remote over SSH”

macOS 菜单栏应用可以端到端地驱动相同的设置（远程状态检查、WebChat 和 Voice Wake 转发）。

操作手册：macOS 远程访问。

安全规则（远程/VPN）

简短版本：保持 Gateway 仅限 loopback，除非你确定需要绑定。

  • Loopback + SSH/Tailscale Serve 是最安全的默认设置（无公开暴露）。
  • 非 loopback 绑定（lan/tailnet/custom，或当 loopback 不可用时的 auto）必须使用认证 token/密码。
  • gateway.remote.token 仅用于远程 CLI 调用——它不会启用本地认证。
  • gateway.remote.tlsFingerprint 在使用 wss:// 时固定远程 TLS 证书。
  • Tailscale Serve 可以在 gateway.auth.allowTailscale: true 时通过身份标头进行认证。 如果你想使用 token/密码，将其设置为 false。
  • 将浏览器控制视为操作者访问：仅限 tailnet + 有意的节点配对。

深入了解：安全。