Node Connect
Diagnose OpenClaw Control UI browser and native Android, iOS, or macOS node connection failures across route, auth, pairing, QR/setup-code, and reconnect states.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Node Connect when an AI agent needs a reusable SKILL.md workflow for this job: Diagnose OpenClaw Control UI browser and native Android, iOS, or macOS node connection failures across route, auth, pairing, QR/setup-code, and reconnect states.
When not to use it
Skip Node Connect when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/node-connect # Save SKILL.md to ~/.claude/skills/node-connect/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/node-connect/SKILL.md. For a shared project, commit the folder at .claude/skills/node-connect/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Node Connect skill for this task: Use Node Connect when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Node Connect
Goal: fix one exact client against one exact Gateway, then prove that client's fresh connection.
## 1. Lock the target
Record the target environment/profile, OpenClaw binary, config/state root, Gateway URL/port, and service before changing anything.
- Use the named deployment wrapper/profile for every config, log, service, device, and node command. - Never drift to a bare `openclaw`, proof environment, or similarly named deployment. - If the global executable is stale, invoke the target through its owner. - Verify status, config, logs, and process identity describe the same Gateway.
Identify the target Gateway before changing pairing or auth.
## 2. Classify the client
Classify from the request and Gateway log before choosing commands:
- **Control UI browser:** the user says browser, dashboard, Control UI, or webchat; logs show `client=openclaw-control-ui` or `mode=webchat`. - **Native mobile/node:** the official app shows Connect, Scan QR, or setup code; logs/request metadata show a native client or `role=node`.
A phone can be either client. Do not use `openclaw qr` or `openclaw nodes status` for a phone browser; those belong to native mobile/node pairing.
## 3. Observe the failing attempt
Run these through the locked target:
```bash openclaw gateway status --deep openclaw logs --follow --json openclaw devices list openclaw config get gateway.mode openclaw config get gateway.bind openclaw config get gateway.remote.url openclaw config get gateway.auth.mode openclaw config get gateway.auth.allowTailscale openclaw config get gateway.tailscale.mode ```
Have the client retry once while logs are live. Correlate its client ID, mode, platform, address, auth result, device ID, user, and close code. Ignore other paired devices.
Interpret the first failed transition:
- No matching Gateway attempt: route, DNS, TLS, origin, or proxy problem. - `token_missing`, `password_missing`, mismatch, or Tailscale identity failure: auth failed **before** pairing, so an empty pending list is expected. - `pairing required`: route and auth succeeded; approve the exact pending request. - `client connected`: match `conn`, `client`, `mode`, and `role` to the exact client. Admission precedes the hello response; if followed by `1006`, preserve auth/pairing and inspect hello delivery, lifecycle, transport, proxy, or reconnect. Older builds use overlapping `authenticated user connected` / `webchat connected` records that omit ephemeral clients. - `1006` without a matching application-level admission record does not prove auth/pairing; inspect the earlier handshake transition.
## 4. Prove the route
Choose one topology: same machine, LAN, tailnet, or public reverse proxy. Do not mix them.
- Browser Control UI needs HTTPS or localhost for browser device identity. A remote plain-HTTP Tailnet/LAN URL is not a valid substitute. - `gateway.tailscale.mode=off` means OpenClaw is not managing Serve/Funnel. It does not prove that Tailscale or an externally managed Serve route is absent. - When Tailscale is involved, inspect live state rather than inferring it from OpenClaw config:
```bash tailscale status --json tailscale serve status --json ```
Match the client's URL to the listener/proxy route reaching the locked Gateway.
## 5A. Control UI browser lane
Restore browser auth before looking for a pairing request:
- For token/password auth, enter the credential in Control UI settings. Never put permanent secrets in chat, logs, or URLs. - Prefer `openclaw dashboard` on the Gateway host for a one-time signed handoff. Use `--no-open` only when the operator can retrieve that host's clipboard, and keep the host browser/clipboard outside agent tooling. Never capture `dashboard --json`: it can expose the handoff and shared credentials. Never relay, rewrite, or send a loopback handoff URL to a remote phone. - For Tailscale Serve, verify the live route and forwarded identity. Enable `gateway.auth.allowTailscale` only for that intended trust boundary. Verified Tailscale Control UI auth with browser device identity can skip pairing.
After auth succeeds:
- Retry; never infer pairing from the pre-auth attempt. Token/password auth can reveal `pairing required`; verified Tailscale identity can skip it. - If logs say `pairing required`, re-list devices and approve the exact request ID. - A successful verified-Tailscale connection may correctly create no pending or paired-device row. - After a repeated `1006`, preserve auth/pairing and inspect reconnect evidence.
## 5B. Native mobile/node lane
Inspect the native route through the locked target without exposing the setup credential:
```bash openclaw qr --json | jq '{gatewayUrl, gatewayUrls, auth, access, accessDowngraded, urlSource}' ```
For a CLI controlling a remote Gateway, add `--remote` before `--json`; it selects `gateway.remote.url` and remote credentials. If the redaction filter is unavailable, do not run raw QR JSON in agent-visible output.
Verify `gatewayUrl` and `urlSource`. The setup code is password-equivalent: have the operator copy it from **Control UI → Devices → Pair device**, or run `openclaw qr --setup-code-only` in a terminal outside agent tooling and paste it directly into the official app. Never relay it through agent/chat/tool output. Generate a fresh code after a URL/auth fix or expiry.
If the app reports `pairing required`:
```bash openclaw devices list openclaw devices approve --latest # preview only; exits without approval openclaw devices approve <requestId> openclaw nodes status ```
`--latest` only previews the current request; never treat it as approval. Re-list immediately before the exact-ID command because retries can supersede the request. Never approve by position, age, or similarity.
## 6. Correlate and finish
Before approval, match available request, device/public-key, client, mode/role, platform, address, user, and retry-time facts.
Declare success only after a new attempt made after the final change proves all applicable checks:
- the exact client reaches the locked Gateway; - intended auth succeeds; - the browser completes initial requests, or the native node appears in `openclaw nodes status`; - approval used the exact request ID; and - no immediate auth, pairing, or reconnect failure follows.
A QR/setup code, launched browser, empty pending list, approval, paired-device count, or Tailscale ping proves only one transition.
Report the diagnosis, chosen route/auth lane, exact-client evidence, and any remaining failed transition.
Intended uses
- Use Node Connect when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.