发现与传输

OpenClaw 要解决两个看起来相似但实际不同的问题：

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

设计目标是把所有网络发现/广播功能集中在 Node Gateway（openclaw gateway）中，客户端（Mac 应用、iOS）只做消费者。

术语

  • Gateway：一个长期运行的进程，拥有状态（会话、配对、节点注册表）并运行频道。大多数场景每台主机一个就够了；也支持隔离的多 Gateway 部署。
  • Gateway WS（控制面）：默认在 127.0.0.1:18789 的 WebSocket 端点；可通过 gateway.bind 绑定到局域网/tailnet。
  • 直连 WS 传输：面向局域网/tailnet 的 Gateway WS 端点（不经过 SSH）。
  • SSH 传输（回退）：通过 SSH 转发 127.0.0.1:18789 实现远程控制。
  • 旧版 TCP bridge（已废弃/移除）：早期节点传输方式（见 Bridge 协议）；不再用于发现。

协议详情：

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

  • 直连 WS 在同一网络和 tailnet 内体验最好：
    • 通过 Bonjour 在局域网自动发现
    • 配对 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=<port>（canvas 主机端口；canvas 启用时与 gatewayPort 相同）
    • cliPath=<path>（可选；openclaw 入口或二进制文件的绝对路径）
    • tailnetDns=<magicdns>（可选提示；Tailscale 可用时自动检测）

安全说明：

  • Bonjour/mDNS TXT 记录是未经认证的。客户端只能将 TXT 值作为 UX 提示。
  • 路由（主机/端口）应优先使用解析后的服务端点（SRV + A/AAAA），而非 TXT 中的 lanHost、tailnetDns 或 gatewayPort。
  • TLS 钉扎绝不能允许广播的 gatewayTlsSha256 覆盖之前存储的指纹。
  • iOS/Android 节点应将基于发现的直连视为仅限 TLS，并在存储首次指纹前要求显式的”信任此指纹”确认（带外验证）。

禁用/覆盖：

  • 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。

配对与认证（直连传输）

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

  • 配对请求在 Gateway 中创建/审批/拒绝（见 Gateway pairing）。
  • Gateway 负责执行：
    • 认证（token / 密钥对）
    • 范围/ACL（Gateway 不是对所有方法的原始代理）
    • 速率限制

各组件的职责

  • Gateway：广播发现信标，掌控配对决策，托管 WS 端点。
  • macOS 应用：帮你选择 Gateway，显示配对提示，仅在回退时使用 SSH。
  • iOS/Android 节点：通过 Bonjour 浏览作为便捷手段，连接到已配对的 Gateway WS。
arrow_back
上一页
Pairing
下一页
Bonjour
arrow_forward