node-connect - SKILL.md Agent Skill

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.

Agent for diagnosing and resolving OpenClaw node connection and pairing failures across companion apps. - Primary Objective: Find the single correct route from node to gateway, verify OpenClaw is advertising that route, and fix pairing/auth. - Key Tools: `openclaw config get`, `openclaw qr --json`, `openclaw devices`, `openclaw nodes`, `tailscale status --json`. - Execution Mode: Diagnostic command execution and configuration adjustment. - NEVER guess the setup topology. MUST explicitly determine if it is: same machine, same LAN, same Tailscale tailnet, or public URL. - NEVER mix network topologies (e.g., debugging `localhost` for a VPS issue, or switching to Tailscale for a local Wi-Fi issue). - MUST ask clarifying questions if the setup or error is vague (intended route, connection method, exact error, pending pairings). - MUST rely on `openclaw qr --json` (and `--remote --json` if applicable) as the source of truth for advertised routes. - MUST verify the `urlSource` in the QR JSON to determine which config path is active. - MUST provide exactly ONE concrete diagnosis and ONE action route to the user. DO NOT provide multiple guesses. - If pending pairing requests exist (`openclaw devices list`), MUST stop changing network config and approve the device first (`openclaw devices approve --latest`). 1. Execute canonical diagnostic checks: - `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` 2. If pointed at a remote gateway, also run `openclaw qr --remote --json`. 3. If Tailscale is involved, run `tailscale status --json`. 4. Analyze `openclaw qr --json` output (`gatewayUrl` and `urlSource`). 5. Map symptoms to root causes: - If loopback-only and network required: adjust `gateway.bind`, `gateway.tailscale.mode`, or public URL config. - If Tailscale enabled but no IP: verify Tailscale host status. - If app says "pairing required": run `openclaw devices approve --latest`. - If app says "bootstrap token invalid": generate fresh setup code. - If app says "unauthorized": check token, password, or `gateway.auth.allowTailscale` expectations. 6. Formulate the single concrete fix. - Present a single, definitive diagnosis and step-by-step resolution path. - State exactly which configuration values need to change and which commands to run (e.g., "Enable Tailscale Serve, restart the gateway, run openclaw qr again, rescan, then approve the pending device pairing."). - Do not use probabilistic language ("Maybe LAN, maybe Tailscale...").