openclaw 文档

简体中文

English

简体中文

English

Appearance

发现（Discovery）与传输（Transports） ​

OpenClaw 有两个在表面上很像、但本质不同的问题：

  1. Operator 远程控制：macOS 菜单栏 app 控制运行在另一台机器上的 gateway。
  2. Node 配对：iOS/Android（以及未来的 nodes）找到 gateway 并安全配对。

设计目标是：把所有网络发现/广播逻辑放在 Node Gateway（openclaw gateway）中；客户端（mac app、iOS）只作为消费者。

术语 ​

  • Gateway：一个长期运行的 gateway 进程，拥有状态（sessions、pairing、node registry）并运行 channels。多数场景每台主机一个；也支持隔离的多 gateway。
  • Gateway WS（control plane）：默认 127.0.0.1:18789 的 WebSocket 端点；可通过 gateway.bind 绑定到 LAN/tailnet。
  • Direct WS transport：面向 LAN/tailnet 的 Gateway WS 端点（不走 SSH）。
  • SSH transport（fallback）：通过 SSH 转发 127.0.0.1:18789 来做远程控制。
  • 旧版 TCP bridge（deprecated/removed）：旧的 node 传输（见 Bridge protocol）；已不再用于 discovery 广播。

协议细节：

为什么同时保留 “直连” 与 SSH ​

  • Direct WS 在同一网络与 tailnet 内是最佳体验：
    • LAN 内通过 Bonjour 自动发现
    • pairing tokens + ACLs 由 gateway 统一管理
    • 不需要 shell 权限；协议面更紧凑且更易审计
  • SSH 仍是通用 fallback：
    • 只要能 SSH 就能用（即使跨完全无关的网络）
    • 能绕开 multicast/mDNS 的问题
    • 除 SSH 外不需要额外开放入站端口

Discovery 输入（客户端如何得知 gateway 在哪） ​

1）Bonjour / mDNS（仅 LAN） ​

Bonjour 是 best-effort，且无法跨网络；只用于“同一 LAN”场景的便利。

目标方向：

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

排障与 beacon 细节：见 Bonjour。

Service beacon 细节 ​

  • Service types：
    • _openclaw-gw._tcp（gateway transport beacon）
  • TXT keys（非敏感）：
    • role=gateway
    • lanHost=<hostname>.local
    • sshPort=22（或广播的端口）
    • gatewayPort=18789（Gateway WS + HTTP）
    • gatewayTls=1（仅当启用 TLS）
    • gatewayTlsSha256=<sha256>（仅当启用 TLS 且有 fingerprint）
    • canvasPort=18793（默认 canvas host 端口；服务 /__openclaw__/canvas/）
    • cliPath=<path>（可选；可运行的 openclaw 入口或二进制的绝对路径）
    • tailnetDns=<magicdns>（可选提示；当检测到可用 Tailscale 时自动探测）

禁用/覆盖：

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

2）Tailnet（跨网络） ​

对于 London/Vienna 这类跨网络场景，Bonjour 不会有帮助。推荐的“直连”目标是：

  • Tailscale MagicDNS 名称（优先）或一个稳定的 tailnet IP。

如果 gateway 能检测到自己运行在 Tailscale 下，它会把 tailnetDns 作为可选提示发布给客户端（包括 wide-area beacons）。

3）手工 / SSH 目标 ​

当没有直连路径（或直连被禁用）时，客户端总能通过 SSH 转发 loopback gateway 端口连接。

参见 Remote access。

传输选择（客户端策略） ​

推荐的客户端行为：

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

配对 + 鉴权（直连传输） ​

gateway 是 node/client 准入的事实来源（source of truth）。

  • 配对请求在 gateway 中创建/批准/拒绝（见 Gateway pairing）。
  • gateway 负责强制：
    • auth（token / keypair）
    • scopes/ACLs（gateway 不是对每个方法的原始代理）
    • rate limits

组件职责划分 ​

  • Gateway：广播 discovery beacons，做配对决策，并托管 WS 端点。
  • macOS app：帮你选择 gateway，展示配对提示，并只在必要时使用 SSH fallback。
  • iOS/Android nodes：把 Bonjour 作为便利手段浏览，然后连接到已配对的 Gateway WS。