Node Connect

目标：找出从 node 到 gateway 的唯一真实路由，验证 OpenClaw 是否正在广播该路由，然后修复配对/认证问题。

先确认拓扑结构

在提出修复方案前，请先明确你处于以下哪种场景：

• 同一台机器 / 模拟器 / USB 隧道
• 同一局域网（LAN）/ 本地 Wi-Fi
• 同一 Tailscale tailnet
• 公网 URL / 反向代理

请勿混用多种模式。

• 本地 Wi-Fi 问题：除非确实需要远程访问，否则不要切换到 Tailscale。
• VPS / 远程 gateway 问题：不要继续调试 localhost 或 LAN IP。

若存在歧义，请先提问

如果部署环境不清晰，或故障报告描述模糊，请在开始诊断前先提出简短、明确的问题。

请询问以下信息：

• 用户意图使用的路由类型：同一台机器、同一局域网、Tailscale tailnet，还是公网 URL
• 是否使用了二维码/设置码，还是手动输入 host/port
• App 中显示的确切文本/状态/错误信息（尽可能完整引用原文）
• openclaw devices list 是否显示有待处理的配对请求

切勿仅凭 can't connect 等模糊提示进行猜测。

标准检查命令

优先使用 openclaw qr --json。它生成的 setup-code 载荷与 Android 扫描的完全一致。

openclaw config get gateway.mode
openclaw config get gateway.bind
openclaw config get gateway.tailscale.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.allowTailscale
openclaw config get plugins.entries.device-pair.config.publicUrl
openclaw qr --json
openclaw devices list
openclaw nodes status

如果当前 OpenClaw 实例指向的是远程 gateway，请额外运行：

openclaw qr --remote --json

若涉及 Tailscale，请同时运行：

tailscale status --json

依据结果判断，而非猜测

openclaw qr --json 执行成功时，关键字段含义如下：

• gatewayUrl：即 App 实际应连接的 endpoint 地址。
• urlSource：表明最终生效的配置路径来源。

常见合法的配置来源包括：

• gateway.bind=lan：仅限同一 Wi-Fi / 局域网内访问
• gateway.bind=tailnet：直连 tailnet 访问
• gateway.tailscale.mode=serve 或 gateway.tailscale.mode=funnel：通过 Tailscale 路由
• plugins.entries.device-pair.config.publicUrl：显式指定的公网地址 / 反向代理路由
• gateway.remote.url：指向远程 gateway 的路由

根因映射表

若 openclaw qr --json 返回 Gateway is only bound to loopback：

• 远程 node 尚无法连接
• 需先修复路由配置，再生成新的 setup code
• 即使配置了 gateway.bind=auto，只要实际生效的 QR 路由仍是 loopback，则仍不满足要求
• 同局域网场景：应设为 gateway.bind=lan
• 同 tailnet 场景：推荐使用 gateway.tailscale.mode=serve，或设为 gateway.bind=tailnet
• 公网互联网场景：必须设置真实的 plugins.entries.device-pair.config.publicUrl 或 gateway.remote.url

若提示 gateway.bind=tailnet set, but no tailnet IP was found：

• gateway 主机实际上并未接入 Tailscale

若提示 qr --remote requires gateway.remote.url：

• 远程模式配置不完整

若 App 显示 pairing required：

• 网络路由与认证已成功
• 只需批准待处理的设备请求即可

openclaw devices list
openclaw devices approve --latest

若 App 显示 bootstrap token invalid or expired：

• setup code 已过期或无效
• 需生成新的 setup code 并重新扫码
• 每次完成 URL 或认证相关修复后，也应执行此操作

若 App 显示 unauthorized：

• 可能为 token/密码错误，或对 Tailscale 访问方式的理解有误
• 对于 Tailscale Serve 模式，gateway.auth.allowTailscale 必须与预期流程匹配
• 否则请使用显式的 token/password 认证方式

快速启发式判断

• 同一 Wi-Fi 下部署 + gateway 广播 127.0.0.1、localhost 或仅 loopback 配置 → 错误
• 远程部署 + setup/手动输入使用私有 LAN IP → 错误
• Tailscale 部署 + gateway 广播 LAN IP 而非 MagicDNS / tailnet 路由 → 错误
• 已设置公网 URL，但 QR 仍广播其他地址 → 查看 urlSource；当前配置与预期不符
• openclaw devices list 显示有待处理请求 → 停止修改网络配置，先完成批准

修复建议风格

回复应包含一个具体、明确的诊断结论，以及一条可执行的修复路径。

若当前信息不足以支撑判断，请索要部署详情和 App 中的精确报错文本，而非盲目猜测。

良好示例：

• 当前 gateway 仍仅绑定 loopback，因此其他网络中的 node 无法访问。请启用 Tailscale Serve，重启 gateway，再次运行 openclaw qr，重新扫码，并批准待处理的设备配对请求。

不良示例：

• 可能是 LAN，可能是 Tailscale，可能是端口转发，也可能是公网 URL。