Node Connect

Goal: find the one real route from node -> gateway, verify OpenClaw is advertising that route, then fix pairing/auth.

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.

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.

Canonical checks

Prefer openclaw qr --json. It uses the same setup-code payload Android scans.

CODEBLOCK0

If this OpenClaw instance is pointed at a remote gateway, also run:

CODEBLOCK1

If Tailscale is part of the story:

CODEBLOCK2

Read the result, not guesses

INLINECODE4 success means:

• - gatewayUrl: this is the actual endpoint the app should use.
• INLINECODE6: this tells you which config path won.

Common good sources:

• - gateway.bind=lan: same Wi-Fi / LAN only
• INLINECODE8: direct tailnet access
• INLINECODE9 or gateway.tailscale.mode=funnel: Tailscale route
• INLINECODE11: explicit public/reverse-proxy route
• INLINECODE12: remote gateway route

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
• INLINECODE15 is not enough if the effective QR route is still loopback
• same LAN: use INLINECODE16
• same tailnet: prefer gateway.tailscale.mode=serve or use INLINECODE18
• public internet: set a real plugins.entries.device-pair.config.publicUrl or INLINECODE20

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

CODEBLOCK3

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

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.
• INLINECODE30 shows pending requests: stop changing network config and approve first.

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:

• - INLINECODE31

Bad:

• - INLINECODE32