Diagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps. Use when QR/setup code/manual connect fails, local Wi-Fi works but VPS/tailnet does not, or errors mention pairing required, unauthorized, bootstrap token invalid or expired, gateway.bind, gateway.remote.url, Tailscale, or plugins.entries.device-pair.config.publicUrl.
Goal: find the one real route from node -> gateway, verify OpenClaw is advertising that route, then fix pairing/auth.
Decide which case you are in before proposing fixes:
Do not mix them.
localhost or LAN IPs.If the setup is unclear or the failure report is vague, ask short clarifying questions before diagnosing.
Ask for:
openclaw devices list shows a pending pairing requestDo not guess from .
can't connectPrefer openclaw qr --json. It uses the same setup-code payload Android scans.
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:
openclaw qr --remote --json
If Tailscale is part of the story:
tailscale status --json
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 onlygateway.bind=tailnet: direct tailnet accessgateway.tailscale.mode=serve or gateway.tailscale.mode=funnel: Tailscale routeplugins.entries.device-pair.config.publicUrl: explicit public/reverse-proxy routegateway.remote.url: remote gateway routeIf openclaw qr --json says Gateway is only bound to loopback:
gateway.bind=auto is not enough if the effective QR route is still loopbackgateway.bind=langateway.tailscale.mode=serve or use gateway.bind=tailnetplugins.entries.device-pair.config.publicUrl or gateway.remote.urlIf gateway.bind=tailnet set, but no tailnet IP was found:
If qr --remote requires gateway.remote.url:
If the app says pairing required:
openclaw devices list
openclaw devices approve --latest
If the app says bootstrap token invalid or expired:
If the app says unauthorized:
gateway.auth.allowTailscale must match the intended flow127.0.0.1, localhost, or loopback-only config: wrong.urlSource; config is not what you think.openclaw devices list shows pending requests: stop changing network config and approve first.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.