发现与传输

Moltbot 有两类表面相似的问题：

操作员远程控制：macOS 菜单栏应用控制运行在他处的网关。
节点配对：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 内体验最好：
- 通过 Bonjour 在 LAN 上自动发现
- 配对 token 与 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 host 端口；提供 /__moltbot__/canvas/）、cliPath=<path>（可选；可执行 moltbot 入口或二进制的绝对路径）、tailnetDns=<magicdns>（可选提示；Tailscale 可用时自动检测）

禁用/覆盖：CLAWDBOT_DISABLE_BONJOUR=1 关闭发布；~/.clawdbot/moltbot.json 中的 gateway.bind 控制网关绑定模式；CLAWDBOT_SSH_PORT 覆盖 TXT 中发布的 SSH 端口（默认 22）；CLAWDBOT_TAILNET_DNS 发布 tailnetDns 提示（MagicDNS）；CLAWDBOT_CLI_PATH 覆盖发布的 CLI 路径。

2) Tailnet（跨网络）

在 London/Vienna 式部署中，Bonjour 无法帮忙。推荐的「直接」目标是：Tailscale MagicDNS 名称（优先）或稳定 tailnet IP。若网关检测到自己在 Tailscale 下运行，会发布 tailnetDns 作为可选提示供客户端（含广域信标）使用。

3) 手动 / SSH 目标

当没有直接路由（或直接已禁用）时，客户端始终可通过 SSH 转发回环网关端口连接。见远程访问。

传输选择（客户端策略）

推荐客户端行为：

若已配置且可达的直连端存在，使用它。
否则，若 Bonjour 在 LAN 上发现网关，提供一键「使用此网关」并保存为直连端点。
否则，若已配置 tailnet DNS/IP，尝试直连。
否则，回退到 SSH。

配对与认证（直接传输）

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

配对请求在网关中创建/批准/拒绝（见网关配对）。
网关强制：认证（token / 密钥对）、scope/ACL（网关并非对所有方法的裸代理）、限速。

各组件的职责

网关：发布发现信标、负责配对决策、托管 WS 端点。
macOS 应用：协助选择网关、显示配对提示，仅将 SSH 作为回退。
iOS/Android 节点：通过 Bonjour 浏览并连接已配对的网关 WS。