发现和传输端口
节点的发现和传输端口（Bonjour、Tailscale、SSH）：Gateway 的見次可方。
OpenClaw 有两个表面上看起来相似但截然不同的问题：
1. 操作员远程控制：macOS 菜单栏应用控制运行在其他地方的网关。
2. 节点配对：iOS/Android（以及未来的节点）找到网关并安全配对。
设计目标是将所有网络发现/广告保留在''节点网关''（''openclaw gateway''）中，并保持客户端（mac app、iOS）仅作为消费者。
用語
- Gateway: a single long-running gateway process that owns state (sessions, pairing, node registry) and runs channels. Most setups use one per host; isolated multi-gateway setups are possible.
- ''Gateway WS (control plane)'': the WebSocket endpoint on ''127.0.0.1:18789'' by default; can be bound to LAN/tailnet via ''gateway.bind''.
- Direct WS transport: a LAN/tailnet-facing Gateway WS endpoint (no SSH).
- ''SSH transport (fallback)'': remote control by forwarding ''127.0.0.1:18789'' over SSH.
- ''Legacy TCP bridge (deprecated/removed)'': older node transport (see ''Bridge protocol''); no longer advertised for discovery.
协议的详情：
「直接」和 SSH 的两方維持执行理由
- Direct WS is the best UX on the same network and within a tailnet:
- LAN 内在 Bonjour 通过在自动的在发现可能
- 配对令牌和 ACL 是 gateway 由一元管理
- No shell access required; protocol surface can stay tight and auditable
- SSH remains the universal fallback:
- Works anywhere you have SSH access (even across unrelated networks)
- Survives multicast/mDNS issues
- Requires no new inbound ports besides SSH
Discovery inputs (how clients learn where the gateway is)
#
1）Bonjour / mDNS（LAN 仅）
Bonjour is best-effort and does not cross networks. It is only used for "same LAN" convenience.
目标的方向：
- The gateway advertises its WS endpoint via Bonjour.
- Clients browse and show a "pick a gateway" list, then store the chosen endpoint.
故障排除和信标详情：''Bonjour''。
##
服务信标的详情
- 服务类型：
- ''_openclaw-gw._tcp''（gateway 传输端口信标）
- TXT 密钥（非秘密）：
- ''role=gateway''
- ''lanHost=<hostname>.local''
- ''sshPort=22'' (or advertised port)
- ''gatewayPort=18789''（Gateway WS + HTTP）
- ''gatewayTls=1''（TLS 但启用那場合仅）
- ''gatewayTlsSha256=<sha256>'' (only when TLS is enabled and fingerprint is available)
- ''canvasPort=18793''（默认的 canvas 主机端口。''/__openclaw__/canvas/'' 提供）
- ''cliPath=<path>'' (optional; absolute path to a runnable ''openclaw'' entrypoint or binary)
- ''tailnetDns=<magicdns>'' (optional hint; auto-detected when Tailscale is available)
禁用/覆盖：
- ''OPENCLAW_DISABLE_BONJOUR=1'' disables advertising.
- ''gateway.bind'' in ''~/.openclaw/openclaw.json'' controls the Gateway bind mode.
- ''OPENCLAW_SSH_PORT'' overrides the SSH port advertised in TXT (defaults to 22).
- ''OPENCLAW_TAILNET_DNS'' 在 ''tailnetDns'' 提示公开（MagicDNS）。
- ''OPENCLAW_CLI_PATH'' overrides the advertised CLI path.
#
2) Tailnet (cross-network)
For London/Vienna style setups, Bonjour won't help. The recommended "direct" target is:
- Tailscale MagicDNS 名（優先）或安定已执行 tailnet IP。
如果网关可以检测到它在 Tailscale 下运行，它会发布 ''tailnetDns'' 作为客户端的可选提示（包括广域信标）。
#
3）手动 / SSH 目标
当没有直接路由（或直接路由被禁用）时，客户端始终可以通过转发本地回环网关端口通过 SSH 连接。
参照：''Remote access''。
传输端口选择（客户端策略）
Recommended client behavior:
1. If a paired direct endpoint is configured and reachable, use it.
2. Else, if Bonjour finds a gateway on LAN, offer a one-tap "Use this gateway" choice and save it as the direct endpoint.
3. Else, if a tailnet DNS/IP is configured, try direct.
4. Else, fall back to SSH.
配对 + 认证（直接传输端口）
网关是节点/客户端准入的真实来源。
- 配对请求是 gateway 由创建/批准/拒绝被（''Gateway pairing'' 参照）。
- gateway 是以下強制执行：
- auth (token / keypair)
- scopes/ACLs (the gateway is not a raw proxy to every method)
- rate limits
组件的責任分钟担
- Gateway: advertises discovery beacons, owns pairing decisions, and hosts the WS endpoint.
- macOS app: helps you pick a gateway, shows pairing prompts, and uses SSH only as a fallback.
- iOS/Android nodes: browse Bonjour as a convenience and connect to the paired Gateway WS.