Diagnose XClaw 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 XClaw 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:
xclaw devices list shows a pending pairing requestDo not guess from .
can't connectPrefer xclaw qr --json. It uses the same setup-code payload Android scans.
xclaw config get gateway.mode
xclaw config get gateway.bind
xclaw config get gateway.tailscale.mode
xclaw config get gateway.remote.url
xclaw config get gateway.auth.mode
xclaw config get gateway.auth.allowTailscale
xclaw config get plugins.entries.device-pair.config.publicUrl
xclaw qr --json
xclaw devices list
xclaw nodes status
If this XClaw instance is pointed at a remote gateway, also run:
xclaw qr --remote --json
If Tailscale is part of the story:
tailscale status --json
xclaw 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 xclaw 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:
xclaw devices list
xclaw 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.xclaw 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 xclaw qr again, rescan, then approve the pending device pairing.Bad:
Maybe LAN, maybe Tailscale, maybe port forwarding, maybe public URL.