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

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

根因映射

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

gateway.remote.url

gateway.bind=tailnet set, but no tailnet IP was found

gateway host is not actually on Tailscale

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问题。