发现与传输

OpenClaw 有两个表面上看起来相似的问题：

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

设计目标是把所有网络发现和广播功能都放在 Node Gateway（openclaw gateway）中，让客户端（Mac 应用、iOS）作为消费者。

术语

  • Gateway：一个长期运行的 Gateway 进程，负责管理状态（Session、Pairing、节点注册表）并运行 Channel。大多数情况下每台主机运行一个；也可以配置隔离的多 Gateway 设置。
  • Gateway WS（控制平面）：WebSocket 端点，默认在 127.0.0.1:18789；可以通过 gateway.bind 绑定到局域网或 tailnet。
  • 直连 WS 传输：面向局域网/tailnet 的 Gateway WS 端点（不使用 SSH）。
  • SSH 传输（备用方案）：通过 SSH 转发 127.0.0.1:18789 来实现远程控制。
  • 旧版 TCP bridge（已弃用/移除）：旧的节点传输方式（参见 Bridge 协议）；不再用于发现广播。

协议详情：

为什么同时保留”直连”和 SSH

  • 直连 WS 在同一网络和 tailnet 内体验最好：
    • 通过 Bonjour 在局域网自动发现
    • Pairing token 和 ACL 由 Gateway 管理
    • 不需要 shell 访问权限；协议层面可以保持精简和可审计
  • SSH 作为通用备用方案：
    • 只要有 SSH 访问权限就能用（即使跨不相关的网络）
    • 不受组播/mDNS 问题影响
    • 除了 SSH 端口外不需要新的入站端口

发现方式（客户端如何找到 Gateway）

1) Bonjour / mDNS（仅限局域网）

Bonjour 是尽力而为的，不能跨网络。它只用于”同一局域网”的便利性。

目标方向：

  • Gateway 通过 Bonjour 广播其 WS 端点。
  • 客户端浏览并显示”选择一个 Gateway”列表，然后保存选中的端点。

故障排除和信标详情：Bonjour。

服务信标详情

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

禁用/覆盖：

  • OPENCLAW_DISABLE_BONJOUR=1 禁用广播。
  • ~/.openclaw/openclaw.json 中的 gateway.bind 控制 Gateway 绑定模式。
  • OPENCLAW_SSH_PORT 覆盖 TXT 中广播的 SSH 端口（默认为 22）。
  • OPENCLAW_TAILNET_DNS 发布 tailnetDns 提示（MagicDNS）。
  • OPENCLAW_CLI_PATH 覆盖广播的 CLI 路径。

2) Tailnet（跨网络）

对于伦敦/维也纳这种跨地域设置，Bonjour 帮不上忙。推荐的”直连”目标是：

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

如果 Gateway 检测到自己运行在 Tailscale 下，它会发布 tailnetDns 作为客户端的可选提示（包括广域信标）。

3) 手动 / SSH 目标

当没有直连路由（或直连被禁用）时，客户端始终可以通过 SSH 转发本地回环 Gateway 端口来连接。

参见远程访问。

传输选择（客户端策略）

推荐的客户端行为：

  1. 如果配置了已配对的直连端点且可达，使用它。
  2. 否则，如果 Bonjour 在局域网找到 Gateway，提供一键”使用此 Gateway”选项并保存为直连端点。
  3. 否则，如果配置了 tailnet DNS/IP，尝试直连。
  4. 否则，回退到 SSH。

Pairing 和认证（直连传输）

Gateway 是节点/客户端准入的权威来源。

  • Pairing 请求在 Gateway 中创建/批准/拒绝（参见 Gateway Pairing）。
  • Gateway 强制执行：
    • 认证（token / 密钥对）
    • 作用域/ACL（Gateway 不是每个方法的原始代理）
    • 速率限制

各组件职责

  • Gateway：广播发现信标，管理 Pairing 决策，托管 WS 端点。
  • macOS 应用：帮你选择 Gateway，显示 Pairing 提示，仅在备用时使用 SSH。
  • iOS/Android 节点：浏览 Bonjour 作为便利方式，连接到已配对的 Gateway WS。