Verified skill
Real-time security audit skill scanning for OWASP Top 10 vulnerabilities and infrastructure misconfigurations.
Openclaw Node Connect Diagnoser
This skill is designed to methodically troubleshoot OpenClaw node connection issues. It guides users through identifying the correct network topology (same machine, LAN, Tailscale, or public URL) and avoids common pitfalls like mixing network types. The primary goal is to pinpoint the single, real route from the node to the gateway, verify OpenClaw's advertisement of that route, and then resolve any pairing or authentication problems.
The skill emphasizes asking clarifying questions when initial reports are vague, ensuring an accurate understanding of the setup before proposing solutions. It leverages canonical `openclaw` and `tailscale` commands to gather precise configuration and status information, interpreting their output to identify root causes rather than relying on guesses.
It provides a structured approach to diagnosing issues like loopback-only gateways, missing Tailscale IPs, incomplete remote configurations, pairing requirements, invalid bootstrap tokens, and unauthorized access, offering concrete, actionable fixes.
What It Does
This skill provides a methodical approach to diagnosing OpenClaw node connectivity problems. It helps users determine the correct network route, verify OpenClaw's advertising of that route, and then fix any pairing or authentication issues. It leverages specific `openclaw` and `tailscale` commands to gather crucial configuration and status information, leading to precise root-cause identification and resolution.
Inputs
The skill primarily expects a clear description of the OpenClaw connection problem, including any exact error messages or status indications from the OpenClaw app. It will then prompt the user for outputs from specific `openclaw` and `tailscale` CLI commands to gather necessary diagnostic data.
Outputs
The skill produces a concrete diagnosis of the OpenClaw connectivity issue, a single recommended fix, or a set of clarifying questions if the initial problem description is ambiguous. It aims to guide the user directly to the solution, avoiding vague or multi-pronged suggestions.
Step By Step
-
Determine Intended Network Topology
Ask the user to explicitly state their intended connection method: same machine, same LAN, same Tailscale tailnet, or public URL.
Done when: The user has clearly stated one of the four intended network topologies.
If it cannot finish: If the user cannot state a clear topology, proceed to ask clarifying questions.
-
Clarify Ambiguous Setup Details
If the initial report is vague, ask for the intended route, whether QR/setup code or manual host/port was used, the exact app text/status/error, and if 'openclaw devices list' shows a pending pairing request.
Done when: All requested setup details and error messages are explicitly provided by the user.
If it cannot finish: If details remain vague, inform the user that diagnosis cannot proceed without clear information.
-
Collect Gateway Configuration
Run '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', and 'openclaw config get plugins.entries.device-pair.config.publicUrl'.
Done when: Outputs for all specified 'openclaw config get' commands are collected.
If it cannot finish: If a command fails, note the error and attempt to proceed with available information, or request troubleshooting for the failed command.
-
Generate and Analyze QR Code Payload
Run 'openclaw qr --json'. If this OpenClaw instance is pointed at a remote gateway, also run 'openclaw qr --remote --json'.
Done when: The 'openclaw qr --json' output, including 'gatewayUrl' and 'urlSource', is collected and understood.
If it cannot finish: If 'openclaw qr --json' fails or provides malformed output, request re-execution or manual inspection of configuration.
-
Gather Device and Node Status
Run 'openclaw devices list' and 'openclaw nodes status'. If Tailscale is part of the story, also run 'tailscale status --json'.
Done when: Outputs for 'openclaw devices list', 'openclaw nodes status', and 'tailscale status --json' (if applicable) are collected.
If it cannot finish: If a command fails, note the error and attempt to proceed with available information.
-
Diagnose Root Cause
Compare all collected configuration, QR output, and status information against the 'Root-cause map' and 'Fast heuristics' sections to pinpoint the single, real route issue, pairing, or authentication problem.
Done when: A specific root cause (e.g., 'Gateway is only bound to loopback', 'pairing required', 'bootstrap token invalid') is identified.
If it cannot finish: If no clear root cause is found, re-evaluate all collected data and clarify any remaining ambiguities with the user.
-
Propose Concrete Solution
Based on the identified root cause, provide one concrete diagnosis and one clear, actionable route to resolve the issue, adhering to the 'Fix style'.
Done when: A single, specific, and actionable solution is communicated to the user.
If it cannot finish: If a solution cannot be formulated, indicate that more information or deeper investigation is required.
Mistakes It Prevents
| The mistake | What it costs | How the skill prevents it |
|---|---|---|
| Mixing network types during diagnosis, for example, debugging LAN issues when remote access is actually needed. | Wasted time, incorrect fixes, and continued connection issues because the fundamental network path is misunderstood. | Explicitly determine the intended network topology first (same machine, LAN, Tailscale, or public URL) and do not switch between them unless the intended access method changes. |
| Guessing the root cause from vague user reports like 'can't connect' without asking for specific details. | Pursuing incorrect diagnostic paths, leading to frustration, delayed resolution, and potentially unnecessary configuration changes. | Always ask clarifying questions for the intended route, setup method (QR/manual), and the exact app text/status/error before proposing solutions. |
| Not generating a fresh setup code after making changes to the gateway's URL or authentication configuration. | The node continues to fail connection or pairing due to an outdated bootstrap token or incorrect gateway URL, even if the underlying network issue is resolved. | Always generate a fresh setup code using 'openclaw qr --json' and rescan it with the node after any URL or authentication configuration fix. |
| Ignoring a 'pairing required' message from the app and continuing to troubleshoot network connectivity. | The node remains unpaired and unable to connect, despite the network route and authentication having successfully completed, leading to misdiagnosis. | When the app reports 'pairing required', check 'openclaw devices list' for pending requests and approve the device using 'openclaw devices approve <requestId>'. |
| Assuming 'gateway.bind=auto' is sufficient for a node on a different machine or network to connect. | The gateway advertises a loopback-only address (e.g., 127.0.0.1), preventing any remote node from establishing a connection. | Verify the 'gatewayUrl' from 'openclaw qr --json' matches the intended network access. For non-loopback access, explicitly set 'gateway.bind=lan', 'gateway.bind=tailnet', or 'gateway.tailscale.mode=serve'. |
| Not verifying the Tailscale status on the gateway host when 'gateway.bind=tailnet' is configured. | The gateway attempts to bind to a non-existent Tailscale IP, resulting in connection failures and misattribution of the problem. | If Tailscale is part of the story, always run 'tailscale status --json' on the gateway host to confirm it is active on the tailnet and has an assigned IP address. |
Edge Cases It Handles
- Gateway is only bound to loopback
- Fix the route by setting 'gateway.bind=lan', 'gateway.tailscale.mode=serve', or 'gateway.bind=tailnet' for same LAN/tailnet, or a real 'plugins.entries.device-pair.config.publicUrl' or 'gateway.remote.url' for public internet. Then generate a fresh setup code.
- 'gateway.bind=tailnet' is set, but no Tailscale IP was found for the gateway host.
- Verify that the gateway host is actually connected to Tailscale and has an active Tailscale IP.
- 'openclaw qr --remote' requires 'gateway.remote.url' but it is not set.
- The remote-mode configuration is incomplete. Set a valid 'gateway.remote.url'.
- The app displays 'pairing required'.
- The network route and authentication worked. Approve the pending device using 'openclaw devices approve <requestId>' after checking 'openclaw devices list'.
- The app displays 'bootstrap token invalid or expired'.
- The setup code is old. Generate a fresh one and rescan it with the device. This should be done after any URL or authentication fix.
- The app displays 'unauthorized'.
- The wrong token/password was used, or there is a wrong Tailscale expectation. For Tailscale Serve, ensure 'gateway.auth.allowTailscale' matches the intended flow. Otherwise, use explicit token/password.
- A remote setup is attempted, but the setup code or manual configuration uses a private LAN IP.
- The configuration is incorrect for a remote setup. Correct the setup to use a public URL, reverse proxy, or a Tailscale route.
- 'openclaw devices list' shows pending pairing requests.
- Stop changing network configuration and approve the pending device first using 'openclaw devices approve <requestId>'.
A Worked Example
A user is trying to connect an Android OpenClaw node to an OpenClaw gateway running on a separate Linux machine on the same local area network (LAN). They initially configured 'gateway.bind=auto' and are reporting that their Android app cannot connect.
Input
User reports: 'My Android phone can't connect to OpenClaw. It just says 'pairing required' but then fails.'
Intended topology: Same LAN.
'openclaw config get gateway.mode': 'standard'
'openclaw config get gateway.bind': 'auto'
'openclaw qr --json': '{"gatewayUrl": "http://127.0.0.1:8080", "urlSource": "gateway.bind=auto"}'
'openclaw devices list': 'No pending pairing requests.' (This was the state before any fixes or successful connection attempts.)Expected output
The gateway is still advertising a loopback-only address (127.0.0.1) due to 'gateway.bind=auto'. For same LAN access, set 'gateway.bind=lan', restart the gateway, generate a fresh QR code with 'openclaw qr --json', rescan it with your Android device, and then approve the pending pairing request using 'openclaw devices approve <requestId>' (after checking 'openclaw devices list' for the new request).Why this output: The 'openclaw qr --json' output clearly shows the gateway is advertising '127.0.0.1', which is a loopback address and unreachable from another machine on the LAN. The 'urlSource' confirms this is due to 'gateway.bind=auto'. For LAN access, 'gateway.bind=lan' is required. The 'pairing required' message was likely a transient or misleading error because the node could not even reach the gateway. Once the route is fixed and the QR code updated, the node will be able to reach the gateway and then a pairing request will genuinely appear, which needs to be approved.
Limitations
Installation
Add to Copilot workspace settingsAdd to .vscode/skills/Add to Cline skills directoryConfigure in .aider.conf.ymlWhat people say, and where to get help
No ratings yet. If you have used this skill, yours would be the first.
Sign in to leave a rating
An account keeps your review with your name on it, and lets you edit it later. Sign in or create one free.
No reviews yet
This skill has not been rated. If you have run it, a short note about what you used it for helps the next person more than any description can.
Related Skills You May Like
Discover more AI agent skills in the same category to enhance your workflow automation.
Leverages AI-assisted debugging and multi-agent orchestration to systematically diagnose, resolve, and prevent production issues, reducing Mean Time To Recovery (MTTR).
A fully functional, temporary preview environment is deployed from a feature branch, verified for correctness, and ready for review.
Automatically detects and safely remediates configuration drift in Salesforce orgs, ensuring alignment with desired state and preventing deployment failures.
Premium skill
$120.00 , one time purchase
Automatically generates and optimizes Salesforce reports and dashboards based on natural language requests, ensuring data accuracy and performance.
Interact directly with MCP servers using the mcporter CLI for listing, configuring, authenticating, and calling tools via HTTP or stdio.
Have a Skill to Share?
Join the community and help AI agents learn new capabilities. Submit your skill and reach thousands of developers.