文档
网关（Gateway）
发现与传输

发现与传输

适用范围

在以下情况使用此页面：

  • 实现或更改 Bonjour 发现/广告
  • 调整远程连接模式（直接 vs SSH）
  • 为远程节点设计节点发现 + 配对

Moltbot 有两个表面看起来相似的独特问题：

  1. 操作员远程控制：macOS 菜单栏应用控制其他地方运行的网关。
  2. 节点配对：iOS/Android（及未来节点）查找网关并安全配对。

设计目标是将所有网络发现/广告保留在 节点网关（clawd / moltbot gateway）中， 并保持客户端（mac 应用、iOS）作为消费者。

术语

  • 网关：拥有状态（会话、配对、节点注册表）并运行通道的单个长时间运行的网关进程。大多数设置每主机使用一个；隔离的多网关设置是可能的。
  • 网关 WS（控制平面）：默认为 127.0.0.1:18789 上的 WebSocket 端点；可以通过 gateway.bind 绑定到 LAN/tailnet。
  • 直接 WS 传输：面向 LAN/tailnet 的网关 WS 端点（无 SSH）。
  • SSH 传输（回退）：通过 SSH 转发 127.0.0.1:18789 进行远程控制。
  • 传统 TCP 桥接（已弃用/已删除）：较旧的节点传输（参见桥接协议；不再用于发现广告。

协议详细信息：

为什么我们保留"直接"和 SSH

  • 直接 WS 在同一网络和 tailnet 内提供最佳 UX：
    • 通过 Bonjour 在 LAN 上自动发现
    • 由网关拥有的配对令牌 + ACL
    • 无需 shell 访问；协议表面可以保持紧密和可审计
  • SSH 仍然是通用回退：
    • 在任何您有 SSH 访问权限的地方都可以工作（即使在不相关的网络之间）
    • 在多播/mDNS 问题中幸存
    • 除了 SSH 之外不需要新的入站端口

发现输入（客户端如何了解网关的位置）

1) Bonjour / mDNS（仅限 LAN）

Bonjour 是尽力而为的，不跨网络。它仅用于"同一 LAN"的便利。

目标方向：

  • 网关通过 Bonjour 广告其 WS 端点。
  • 客户端浏览并显示"选择网关"列表，然后存储所选端点。

故障排除和信标详细信息：Bonjour。

服务信标详细信息

  • 服务类型：
    • _moltbot-gw._tcp（网关传输信标）
  • TXT 键（非秘密）：
    • role=gateway
    • lanHost=<hostname>.local
    • sshPort=22（或任何广告的）
    • gatewayPort=18789（网关 WS + HTTP）
    • gatewayTls=1（仅在启用 TLS 时）
    • gatewayTlsSha256=<sha256>（仅在启用 TLS 且指纹可用时）
    • canvasPort=18793（默认 canvas 主机端口；提供 /__moltbot__/canvas/）
    • cliPath=<path>（可选；可运行的 moltbot 入口点或二进制文件的绝对路径）
    • tailnetDns=<magicdns>（可选提示；当 Tailscale 可用时自动检测）

禁用/覆盖：

  • MOLTBOT_DISABLE_BONJOUR=1 禁用广告。
  • ~/.moltbot/moltbot.json 中的 gateway.bind 控制网关绑定模式。
  • MOLTBOT_SSH_PORT 覆盖 TXT 中广告的 SSH 端口（默认为 22）。
  • MOLTBOT_TAILNET_DNS 发布 tailnetDns 提示（MagicDNS）。
  • MOLTBOT_CLI_PATH 覆盖广告的 CLI 路径。

2) Tailnet（跨网络）

对于伦敦/维也纳风格的设置，Bonjour 无济于事。推荐的"直接"目标是：

  • Tailscale MagicDNS 名称（首选）或稳定的 tailnet IP。

如果网关可以检测到它在 Tailscale 下运行，它会将 tailnetDns 作为可选提示发布给客户端（包括广域信标）。

3) 手动 / SSH 目标

当没有直接路由（或直接被禁用）时，客户端可以通过转发回环网关端口随时通过 SSH 连接。

请参阅远程访问。

传输选择（客户端策略）

推荐的客户端行为：

  1. 如果配置了已配对的直接端点且可达，请使用它。
  2. 否则，如果 Bonjour 在 LAN 上找到网关，提供一键"使用此网关"选择并将其保存为直接端点。
  3. 否则，如果配置了 tailnet DNS/IP，请尝试直接连接。
  4. 否则，回退到 SSH。

配对 + 身份验证（直接传输）

网关是节点/客户端准入的真相来源。

  • 配对请求在网关中创建/批准/拒绝（参见网关配对）。
  • 网关强制执行：
    • 身份验证（令牌 / 密钥对）
    • 作用域/ACL（网关不是每个方法的原始代理）
    • 速率限制

按组件的职责

  • 网关：广告发现信标，拥有配对决策，并托管 WS 端点。
  • macOS 应用：帮助您选择网关，显示配对提示，并仅将 SSH 作为回退使用。
  • iOS/Android 节点：浏览 Bonjour 作为便利，并连接到已配对的网关 WS。
多个网关（同一主机）工具调用（HTTP）