openclaw 文档

简体中文

English

简体中文

English

Appearance

远程访问（SSH、隧道与 tailnets） ​

本仓库支持“通过 SSH 远程使用”：在一台专用主机（桌面机/服务器）上运行一个长期存活的 Gateway（master），然后让各类客户端连接过去。

  • 对 operators（你 / macOS app）：SSH 隧道是通用 fallback。
  • 对 nodes（iOS/Android 与未来设备）：连接到 Gateway WebSocket（同 LAN/tailnet，或必要时通过 SSH 隧道）。

核心思路 ​

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

常见 VPN/tailnet 形态（agent 在哪里跑） ​

把 Gateway host 理解为“agent 所在的位置”。它拥有 sessions、auth profiles、channels 与 state。 你的 laptop/desktop（以及 nodes）连接到该主机。

1）tailnet 里常开 Gateway（VPS 或家用服务器） ​

在一台常驻主机上运行 Gateway，通过 Tailscale 或 SSH 访问。

  • 最佳体验： 保持 gateway.bind: "loopback"，并用 Tailscale Serve 暴露 Control UI。
  • Fallback： 保持 loopback + 从需要访问的机器建立 SSH 隧道。
  • 示例： exe.dev（易用 VM）或 Hetzner（生产 VPS）。

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

2）家用台式机跑 Gateway，笔记本做远程控制 ​

笔记本 不运行 agent，只做远程连接：

  • 使用 macOS app 的 Remote over SSH 模式（Settings → General → “OpenClaw runs”）。
  • app 会自动打开并管理隧道，因此 WebChat + health checks 基本“开箱即用”。

Runbook：/platforms/mac/remote。

3）笔记本跑 Gateway，从其它机器远程访问 ​

保持 Gateway 在本地运行，但以安全方式暴露：

  • 其它机器通过 SSH 隧道连到笔记本，或
  • 用 Tailscale Serve 暴露 Control UI，同时保持 Gateway 只绑定 loopback。

指南：Tailscale 与 Web overview。

命令流（哪里跑什么） ​

一个 gateway service 拥有 state + channels；nodes 是外设。

示例流程（Telegram → node）：

  • Telegram 消息到达 Gateway。
  • Gateway 运行 agent，并决定是否要调用某个 node tool。
  • Gateway 通过 Gateway WebSocket 调用 node（node.* RPC）。
  • node 返回结果；Gateway 再回复 Telegram。

备注：

  • Nodes 不运行 gateway service。 除非你有意运行隔离 profiles，否则每台主机通常只运行一个 gateway（见 Multiple gateways）。
  • macOS app 的 “node mode” 本质上就是一个通过 Gateway WebSocket 连接的 node 客户端。

SSH 隧道（CLI + tools） ​

把远端 Gateway WS 转发到本地：

bash
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 remote 默认值 ​

你可以持久化一个 remote target，让 CLI 命令默认使用它：

json5
{
  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 使用 Chat UI ​

WebChat 不再使用单独的 HTTP 端口。SwiftUI chat UI 直接连接到 Gateway WebSocket。

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

macOS app “Remote over SSH” ​

macOS 菜单栏 app 可以端到端地驱动同一套方案（远程 status checks、WebChat、Voice Wake 转发）。

Runbook：/platforms/mac/remote。

安全规则（remote/VPN） ​

简版：除非确定需要，否则保持 Gateway 只绑定 loopback。

  • Loopback + SSH/Tailscale Serve 是最安全的默认值（不暴露公网端口）。
  • 非 loopback 的 bind（lan/tailnet/custom，或 loopback 不可用时的 auto）必须启用 auth tokens/passwords。
  • gateway.remote.token 仅 用于 remote CLI calls —— 它 不会 启用本地鉴权。
  • 当使用 wss:// 时，gateway.remote.tlsFingerprint 用于 pin 远端 TLS 证书。
  • 当 gateway.auth.allowTailscale: true 时，Tailscale Serve 可以通过 identity headers 鉴权。 如果你更希望使用 tokens/passwords，请把它设为 false。
  • 把 browser control 当作 operator access：tailnet-only + 谨慎的 node pairing。

深入说明：Security。