发现与传输

OpenClaw 有两个相关但不同的发现（discovery）问题：

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

所有网络发现/广播都由 Gateway（openclaw gateway）负责；客户端（mac 应用、iOS）只是消费者。

术语¶

• Gateway：一个长期运行的单一进程，拥有状态（会话、配对、节点注册表）并运行通道。大多数部署在每个主机上使用一个；也支持隔离的多 Gateway 部署。
• Gateway WS（控制面）：默认位于 127.0.0.1:18789 的 WebSocket 端点；可通过 gateway.bind 将其绑定到 LAN/tailnet。
• 直接 WS 传输：面向 LAN/tailnet 的 Gateway WS 端点（无 SSH）。
• SSH 传输（后备）：通过 SSH 转发 127.0.0.1:18789 进行远程控制。

协议详情：Gateway 协议。

为什么直连和 SSH 都存在¶

• 直接 WS 在同一网络和 tailnet 内提供最佳体验：通过 Bonjour 进行 LAN 自动发现，配对令牌和 ACL 由 Gateway 持有，且无需 shell 访问。
• SSH 是通用后备方案：只要你能通过 SSH 访问，就能在任何地方使用，甚至跨不相关网络；它能应对组播/mDNS 问题，并且除 SSH 外无需新增入站端口。

发现输入¶

1) Bonjour / DNS-SD¶

组播 Bonjour 是尽力而为的，且不能跨越网络。OpenClaw 还支持通过配置的广域网 DNS-SD 域浏览相同的 Gateway 信标，因此发现既可以覆盖同一 LAN 上的 local.，也可以覆盖已配置的单播 DNS-SD 域，用于跨网络发现。

当内置的 bonjour 插件启用时，Gateway 会通过 Bonjour 广播其 WS 端点；客户端浏览并显示一个“选择 Gateway”列表，然后应用其连接信任策略。在 macOS 上，选择一个条目会打开连接编辑器；它不会保存广播的端点。参见 在应用中配置。

故障排查与信标详情：Bonjour。

服务信标详情¶

• 服务类型：_openclaw-gw._tcp（Gateway 传输信标）。
• TXT 键（非机密）：

安全说明：

• Bonjour/mDNS TXT 记录是未经身份验证的。客户端必须仅将 TXT 值视为 UX 提示。
• 路由（主机/端口）应优先使用已解析的服务端点（SRV + A/AAAA），而不是 TXT 提供的 lanHost、tailnetDns 或 gatewayPort。
• TLS 固定（pinning）绝不能允许广播的 gatewayTlsSha256 覆盖已存储的固定值。
• 只要所选路由是安全/TLS 的，iOS/Android 节点在存储首次固定值之前，应要求用户明确确认“信任此指纹”（带外验证）。

启用、禁用和覆盖：

• openclaw plugins enable bonjour 启用 LAN 组播广播。
• openclaw.json 中的 discovery.mdns.mode 控制 mDNS 广播："minimal"（默认）、"full"（将 cliPath/sshPort 同时添加到 LAN 信标和任何广域网 DNS-SD 区域）或 "off"（禁用 mDNS）。
• OPENCLAW_DISABLE_BONJOUR=1 强制禁用广播；discovery.mdns.mode="off" 可独立禁用它。OPENCLAW_DISABLE_BONJOUR=0 是显式选择启用，会覆盖插件在检测到的容器（Docker、containerd、Kubernetes、LXC）内的自动禁用；它不会覆盖 discovery.mdns.mode="off"。内置的 bonjour 插件会在 macOS 主机上自动启动（enabledByDefaultOnPlatforms: ["darwin"]），并在检测到容器时自动禁用；Linux、Windows 和其他容器化部署需要显式执行 plugins enable bonjour。
• ~/.openclaw/openclaw.json 中的 gateway.bind 控制 Gateway 的绑定模式。
• OPENCLAW_SSH_PORT 覆盖广播的 SSH 端口（仅当 discovery.mdns.mode="full" 时生效）。
• OPENCLAW_TAILNET_DNS 发布 tailnetDns 提示（MagicDNS）。
• OPENCLAW_CLI_PATH 覆盖广播的 CLI 路径。

2) Tailnet（跨网络）¶

对于位于不同物理网络上的 Gateway，Bonjour 无法提供帮助。推荐的直接目标是 Tailscale MagicDNS 名称（首选）或稳定的 tailnet IP。

如果 Gateway 检测到自身运行在 Tailscale 环境下，它会发布 tailnetDns 作为客户端的可选提示（包括广域信标）。对于已配置的 macOS 连接，应优先使用受信任的 MagicDNS 名称，而不是原始 Tailscale IP，以便该名称解析为当前地址。Discovery 不会替代已保存的地址。

对于移动节点配对，discovery 提示绝不会放宽 tailnet/公共路由上的传输安全性：

• iOS/Android 仍然需要安全的首次 tailnet/公共连接路径（wss:// 或 Tailscale Serve/Funnel）。
• 发现到的原始 tailnet IP 只是路由提示，并不代表允许使用明文远程 ws://。
• 私有局域网直接连接 ws:// 仍然受支持。
• 对于移动节点上最简单的 Tailscale 路径，请使用 Tailscale Serve，使 discovery 和设置都解析到同一个安全的 MagicDNS 端点。

3) 手动 / SSH 目标¶

当没有直接路由（或直接路由被禁用）时，客户端始终可以通过转发 loopback Gateway 端口，经由 SSH 连接。参见 远程访问。

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

macOS 应用使用其已配置的直接或 SSH 传输方式。Discovery 不会替代该路由，也不会选择备用路由。对于新连接，用户在连接编辑器中提供受信任的地址、SSH 目标或设置代码并保存。

基于 Discovery 的客户端选择遵循以下策略：

1. 如果已配置且可访问的配对直接端点存在，则使用该端点。
2. 否则，如果 discovery 在 local. 或配置的广域网域上发现 Gateway，则为该候选者提供设置。在保存直接端点之前，应用客户端的信任策略；仅凭 discovery 并不构成授权。
3. 否则，如果配置了 tailnet DNS/IP，则尝试直接连接。对于 tailnet/公共路由上的移动节点，直接连接意味着安全端点，而不是明文远程 ws://。
4. 否则，回退到 SSH。

配对与认证（直接传输）¶

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

• 配对请求在 Gateway 中创建/批准/拒绝（参见 Gateway 配对）。
• Gateway 强制执行认证（token/密钥对）、作用域/ACL（它不是对所有方法的原始代理）以及速率限制。

各组件职责¶

• Gateway：广播 discovery 信标，负责配对决策，托管 WS 端点。
• macOS 应用：编辑受信任的 Gateway 连接，显示配对提示，并使用已配置的直接或 SSH 传输方式。
• iOS/Android 节点：将浏览 Bonjour 作为便捷方式，连接到已配对的 Gateway WS。

相关文档¶

• 远程访问
• Tailscale
• Bonjour 发现