发现与传输

OpenClaw 有两个表面上相似但本质不同的问题：

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

设计目标是将所有网络发现/广播保持在 Node Gateway（openclaw gateway）中，让客户端（Mac 应用、iOS）作为消费者。

术语

• Gateway：单个长时间运行的 Gateway 进程，负责状态（会话、配对、节点注册表）和渠道运行。大多数设置每台主机使用一个；隔离的多 Gateway 设置也是可能的。
• Gateway WS（控制平面）：WebSocket 端点，默认在 127.0.0.1:18789；可通过 gateway.bind 绑定到 LAN/tailnet。
• 直连 WS 传输：面向 LAN/tailnet 的 Gateway WS 端点（无 SSH）。
• SSH 传输（降级）：通过 SSH 转发 127.0.0.1:18789 进行远程控制。
• 旧版 TCP bridge（已废弃/移除）：旧版节点传输（见 Bridge 协议）；不再用于发现广播。

协议详情：

• Gateway 协议
• 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=<端口>（canvas host 端口；canvas host 启用时与 gatewayPort 相同）
  • cliPath=<路径>（可选；可运行的 openclaw 入口点的绝对路径）
  • tailnetDns=<magicdns>（可选提示；Tailscale 可用时自动检测）

安全说明：

• Bonjour/mDNS TXT 记录未经认证。客户端必须将 TXT 值仅视为 UX 提示。
• 路由（主机/端口）应优先使用已解析的服务端点（SRV + A/AAAA），而不是 TXT 提供的 lanHost、tailnetDns 或 gatewayPort。
• TLS 固定绝不允许广播的 gatewayTlsSha256 覆盖之前存储的固定值。

禁用/覆盖：

• 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 转发 loopback Gateway 端口来连接。

见远程访问。

传输选择（客户端策略）

推荐的客户端行为：

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

配对 + 认证（直连传输）

Gateway 是节点/客户端准入的唯一真实来源。

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

各组件职责

• Gateway：广播发现信标，拥有配对决策，托管 WS 端点。
• macOS 应用：帮助你选择 Gateway，显示配对提示，仅将 SSH 作为降级方案。
• iOS/Android 节点：将 Bonjour 作为便利工具浏览，并连接到已配对的 Gateway WS。

---

小龙虾在局域网藏得住，但跨网络就得靠 Tailscale 或 SSH 了——发现协议的设计就是这个逻辑。