Back to Details

node-connect

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Node Connect

节点连接

Goal: find the one real route from node -> gateway, verify OpenClaw is advertising that route, then fix pairing/auth.
目标：找到从节点到网关的真实路径，验证OpenClaw是否在广播该路径，然后修复配对/认证问题。

Topology first

先明确网络拓扑

Decide which case you are in before proposing fixes:
  • same machine / emulator / USB tunnel
  • same LAN / local Wi-Fi
  • same Tailscale tailnet
  • public URL / reverse proxy
Do not mix them.
  • Local Wi-Fi problem: do not switch to Tailscale unless remote access is actually needed.
  • VPS / remote gateway problem: do not keep debugging 
    localhost
    or LAN IPs.
在提出修复方案前，先确定你属于哪种场景：
  • 同一设备/模拟器/USB隧道
  • 同一局域网/本地Wi-Fi
  • 同一Tailscale tailnet
  • 公共URL/反向代理
不要混淆不同场景。
  • 本地Wi-Fi问题：除非确实需要远程访问，否则不要切换到Tailscale。
  • VPS/远程网关问题：不要再调试
    localhost
    或局域网IP。

If ambiguous, ask first

若情况不明，先询问

If the setup is unclear or the failure report is vague, ask short clarifying questions before diagnosing.
Ask for:
  • which route they intend: same machine, same LAN, Tailscale tailnet, or public URL
  • whether they used QR/setup code or manual host/port
  • the exact app text/status/error, quoted exactly if possible
  • whether 
    openclaw devices list
    shows a pending pairing request
Do not guess from 
can't connect
.
如果设置情况不清晰，或故障报告模糊，请先提出简短的澄清问题再进行诊断。
询问以下信息：
  • 他们打算使用哪种路径：同一设备、同一局域网、Tailscale tailnet还是公共URL
  • 是否使用了二维码/设置码，还是手动输入主机/端口
  • 应用显示的准确文本/状态/错误信息，尽可能精确引用
  • openclaw devices list
    是否显示待处理的配对请求
不要仅凭「无法连接」猜测。

Canonical checks

标准检查步骤

Prefer 
openclaw qr --json
. It uses the same setup-code payload Android scans.
bash
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
If this OpenClaw instance is pointed at a remote gateway, also run:
bash
openclaw qr --remote --json
If Tailscale is part of the story:
bash
tailscale status --json
优先使用
openclaw qr --json
，它使用的是Android扫描的同款设置码负载。
bash
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实例指向远程网关，还需运行：
bash
openclaw qr --remote --json
如果涉及Tailscale：
bash
tailscale status --json

Read the result, not guesses

依据结果判断，而非猜测

openclaw qr --json
success means:
  • gatewayUrl
    : this is the actual endpoint the app should use.
  • urlSource
    : this tells you which config path won.
Common good sources:
  • gateway.bind=lan
    : same Wi-Fi / LAN only
  • gateway.bind=tailnet
    : direct tailnet access
  • gateway.tailscale.mode=serve
    or 
    gateway.tailscale.mode=funnel
    : Tailscale route
  • plugins.entries.device-pair.config.publicUrl
    : explicit public/reverse-proxy route
  • gateway.remote.url
    : remote gateway route
openclaw qr --json
执行成功意味着：
  • gatewayUrl
    ：这是应用应使用的实际端点。
  • 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
    ：远程网关路径

Root-cause map

根因映射

If 
openclaw qr --json
says 
Gateway is only bound to loopback
:
  • remote node cannot connect yet
  • fix the route, then generate a fresh setup code
  • gateway.bind=auto
    is not enough if the effective QR route is still loopback
  • same LAN: use 
    gateway.bind=lan
  • same tailnet: prefer 
    gateway.tailscale.mode=serve
    or use 
    gateway.bind=tailnet
  • public internet: set a real 
    plugins.entries.device-pair.config.publicUrl
    or 
    gateway.remote.url
If 
gateway.bind=tailnet set, but no tailnet IP was found
:
  • gateway host is not actually on Tailscale
If 
qr --remote requires gateway.remote.url
:
  • remote-mode config is incomplete
If the app says 
pairing required
:
  • network route and auth worked
  • approve the pending device
bash
openclaw devices list
openclaw devices approve --latest
If the app says 
bootstrap token invalid or expired
:
  • old setup code
  • generate a fresh one and rescan
  • do this after any URL/auth fix too
If the app says 
unauthorized
:
  • wrong token/password, or wrong Tailscale expectation
  • for Tailscale Serve, 
    gateway.auth.allowTailscale
    must match the intended flow
  • otherwise use explicit token/password
如果
openclaw qr --json
显示「Gateway is only bound to loopback」：
  • 远程节点暂时无法连接
  • 修复路径后，生成新的设置码
  • 如果二维码的有效路径仍是回环地址，仅设置
    gateway.bind=auto
    不够
  • 同一局域网：使用
    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」：
  • 网关主机实际上并未接入Tailscale
如果显示「qr --remote requires gateway.remote.url」：
  • 远程模式配置不完整
如果应用显示「pairing required」：
  • 网络路径和认证已正常工作
  • 批准待处理的设备
bash
openclaw devices list
openclaw devices approve --latest
如果应用显示「bootstrap token invalid or expired」：
  • 设置码已过期
  • 生成新的设置码并重新扫描
  • 修复任何URL/认证问题后也需执行此操作
如果应用显示「unauthorized」：
  • 令牌/密码错误，或Tailscale预期不符
  • 对于Tailscale Serve，
    gateway.auth.allowTailscale
    必须与预期流程匹配
  • 否则使用显式令牌/密码

Fast heuristics

快速判断准则

  • Same Wi-Fi setup + gateway advertises 
    127.0.0.1
    , 
    localhost
    , or loopback-only config: wrong.
  • Remote setup + setup/manual uses private LAN IP: wrong.
  • Tailnet setup + gateway advertises LAN IP instead of MagicDNS / tailnet route: wrong.
  • Public URL set but QR still advertises something else: inspect 
    urlSource
    ; config is not what you think.
  • openclaw devices list
    shows pending requests: stop changing network config and approve first.
  • 同一Wi-Fi设置 + 网关广播
    127.0.0.1
    、
    localhost
    或仅回环配置：错误。
  • 远程设置 + 手动设置使用私有局域网IP：错误。
  • Tailnet设置 + 网关广播局域网IP而非MagicDNS/tailscale路径：错误。
  • 已设置公共URL但二维码仍广播其他地址：检查
    urlSource
    ；配置与预期不符。
  • openclaw devices list
    显示待处理请求：停止修改网络配置，先批准请求。

Fix style

修复回复风格

Reply with one concrete diagnosis and one route.
If there is not enough signal yet, ask for setup + exact app text instead of guessing.
Good:
  • The gateway is still loopback-only, so a node on another network can never reach it. Enable Tailscale Serve, restart the gateway, run openclaw qr again, rescan, then approve the pending device pairing.
Bad:
  • Maybe LAN, maybe Tailscale, maybe port forwarding, maybe public URL.
回复需包含一个明确的诊断结果和一个解决方案路径。
如果信息不足，请先询问设置详情和应用的准确文本，不要猜测。
示例：
  • 网关仍仅绑定回环地址，因此其他网络的节点永远无法连接它。启用Tailscale Serve，重启网关，重新运行openclaw qr，重新扫描二维码，然后批准待处理的设备配对。
反例：
  • 可能是局域网问题，可能是Tailscale问题，可能是端口转发问题，也可能是公共URL问题。