文档
网关（Gateway）
远程访问（SSH、隧道和 tailnet）

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

适用范围

在以下情况使用此页面：

  • 运行或故障排除远程网关设置

此存储库通过在专用主机（桌面/服务器）上运行单个网关（主控）并将客户端连接到它来支持"通过 SSH 远程"。

  • 对于 操作员（您/macOS 应用）：SSH 隧道是通用回退。
  • 对于 节点（iOS/Android 和未来设备）：连接到 网关 WebSocket（LAN/tailnet 或 SSH 隧道（如需要））。

核心思想

  • 网关 WebSocket 在您配置的端口上绑定到 回环（默认为 18789）。
  • 对于远程使用，您通过 SSH 转发该回环端口（或使用 tailnet/VPN 并减少隧道）。

常见的 VPN/tailnet 设置（代理所在位置）

将 网关主机 视为"代理所在位置"。它拥有会话、身份验证配置文件、通道和状态。 您的笔记本电脑/桌面（和节点）连接到该主机。

1) tailnet 中的始终开启网关（VPS 或家庭服务器）

在持久主机上运行网关并通过 Tailscale 或 SSH 访问它。

  • 最佳 UX：保持 gateway.bind: "loopback" 并为控制 UI 使用 Tailscale Serve。
  • 回退：保持回环 + 从任何需要访问的机器进行 SSH 隧道。
  • 示例：exe.dev（简单 VM）或 Hetzner（生产 VPS）。

当您的笔记本电脑经常休眠但您希望代理始终开启时，这是理想的。

2) 家庭桌面运行网关，笔记本电脑是远程控制

笔记本电脑 不运行代理。它远程连接：

  • 使用 macOS 应用的 SSH 远程模式（设置 → 常规 → “Moltbot 运行”）。
  • 应用程序打开并管理隧道，因此 WebChat + 健康检查"正常工作"。

运行手册：macOS 远程访问。

3) 笔记本电脑运行网关，从其他机器远程访问

保持网关本地但安全地公开它：

  • 从其他机器 SSH 隧道到笔记本电脑，或
  • Tailscale Serve 控制 UI 并保持网关仅限回环。

指南：Tailscale和 Web 概述。

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

一个网关服务拥有状态 + 通道。节点是外设。

流示例（Telegram → 节点）：

  • Telegram 消息到达 网关。
  • 网关运行 代理 并决定是否调用节点工具。
  • 网关通过网关 WebSocket（node.* RPC）调用 节点。
  • 节点返回结果；网关回复回 Telegram。

注意：

  • **节点不运行网关服务。**每主机应只运行一个网关，除非您有意运行隔离的配置文件（参见多个网关）。
  • macOS 应用"节点模式"只是网关 WebSocket 上的节点客户端。

SSH 隧道（CLI + 工具）

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

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

隧道启动后：

  • moltbot health 和 moltbot status --deep 现在通过 ws://127.0.0.1:18789 到达远程网关。
  • moltbot gateway {status,health,send,agent,call} 也可以在需要时通过 --url 定向转发的 URL。

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

CLI 远程默认值

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

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

当网关仅限回环时，将 URL 保持在 ws://127.0.0.1:18789 并首先打开 SSH 隧道。

通过 SSH 的聊天 UI

WebChat 不再使用单独的 HTTP 端口。SwiftUI 聊天 UI 直接连接到网关 WebSocket。

  • 通过 SSH 转发 18789（见上文），然后将客户端连接到 ws://127.0.0.1:18789。
  • 在 macOS 上，更喜欢应用程序的"SSH 远程"模式，它自动管理隧道。

macOS 应用"SSH 远程"

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

运行手册：macOS 远程访问。

安全规则（远程/VPN）

简短版本：保持网关仅限回环，除非您确定需要绑定。

  • 回环 + SSH/Tailscale Serve 是最安全的默认值（无公开暴露）。
  • 非回环绑定（lan/tailnet/custom，或当回环不可用时的 auto）必须使用身份验证令牌/密码。
  • gateway.remote.token 仅用于远程 CLI 调用 — 它 不启用本地身份验证。
  • gateway.remote.tlsFingerprint 在使用 wss:// 时固定远程 TLS 证书。
  • Tailscale Serve 可以在 gateway.auth.allowTailscale: true 时通过身份验证标头进行身份验证。 如果您想要令牌/密码，请将其设置为 false。
  • 将 browser.controlUrl 视为管理员 API：仅限 tailnet + 令牌身份验证。

深入探讨：安全性。

心跳（网关）诊断工具