# Node Connect

Diagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS...

- Repository: https://github.com/SafeAI-Lab-X/ClawKeeper (1020 stars)
- Category: Mobile
- License: see repository
- Last updated: 2026-08-17
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add SafeAI-Lab-X/ClawKeeper --skill node-connect -g -a claude-code -y`
Codex: `npx skills add SafeAI-Lab-X/ClawKeeper --skill node-connect -g -a codex -y`
Cursor: `npx skills add SafeAI-Lab-X/ClawKeeper --skill node-connect -g -a cursor -y`
Gemini CLI: `npx skills add SafeAI-Lab-X/ClawKeeper --skill node-connect -g -a gemini-cli -y`

## 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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

The rest: https://github.com/SafeAI-Lab-X/ClawKeeper/blob/HEAD/legacy/clawkeeper-watcher/skills/node-connect/SKILL.md