mirror of
https://github.com/openclaw/openclaw.git
synced 2026-03-17 04:50:51 +00:00
143 lines
4.5 KiB
Markdown
143 lines
4.5 KiB
Markdown
---
|
|
name: node-connect
|
|
description: 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.
|
|
---
|
|
|
|
# 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.
|
|
|
|
```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
|
|
```
|
|
|
|
## 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
|
|
|
|
## 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
|
|
|
|
## 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.
|
|
|
|
## 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.`
|