# Openclaw Diagnose

> Diagnose and fix OpenClaw gateway and node host issues. Use when openclaw services have warnings, connection failures, pairing errors, or port conflicts.

- **Type:** Skill
- **Install:** `agentstack add skill-soulmachine-skills-openclaw-diagnose`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [soulmachine](https://agentstack.voostack.com/s/soulmachine)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [soulmachine](https://github.com/soulmachine)
- **Source:** https://github.com/soulmachine/skills/tree/main/openclaw-diagnose

## Install

```sh
agentstack add skill-soulmachine-skills-openclaw-diagnose
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# OpenClaw Diagnose

When the user asks you to diagnose or fix OpenClaw gateway/node issues, follow this structured investigation.

## Step 1: Gather status

Run these in parallel:

```bash
openclaw gateway status
openclaw node status
openclaw nodes status
openclaw nodes pending
```

## Step 2: Analyze warnings

Look for these common issues:

### Multiple gateway-like services detected
- Check if both `ai.openclaw.gateway` and `ai.openclaw.node` are registered as LaunchAgents
- Use `launchctl print gui/$(id -u)/` to inspect each service
- Use `lsof -iTCP: -sTCP:LISTEN -P` to confirm which process owns the port
- The gateway **listens** on the port; the node host **connects to** the gateway on that port — they do NOT conflict

### Pairing required errors
- Check `~/.openclaw/logs/node.err.log` for `pairing required` or `ECONNREFUSED`
- If the node shows "pairing required", run `openclaw nodes pending` to find the pending request
- Approve with: `openclaw nodes approve `
- **Pairing requests expire quickly** — if approval fails with "unknown requestId", restart the node (`openclaw node restart`) and immediately re-check pending + approve

### ECONNREFUSED errors
- The gateway may not be running yet when the node starts
- Check if gateway is listening: `lsof -iTCP: -sTCP:LISTEN -P`
- If gateway is down: `openclaw gateway restart`
- The node has `KeepAlive: true` so it will automatically reconnect once the gateway is up

## Step 3: Verify fix

After taking corrective action, confirm health:

```bash
openclaw nodes status    # Should show: paired · connected
openclaw nodes pending   # Should show: No pending pairing requests
tail -5 ~/.openclaw/logs/node.err.log  # Check for new errors
```

## Key architecture notes

- **Gateway** (`ai.openclaw.gateway`): WebSocket server that listens on a port (default 18789)
- **Node host** (`ai.openclaw.node`): Client that connects to the gateway via WebSocket to register capabilities (browser, system commands)
- The `--host` and `--port` flags on `openclaw node run` specify the **gateway address to connect to**, not a port to bind
- One gateway supports multiple nodes — running both on the same machine is the normal setup
- Node plist is at `~/Library/LaunchAgents/ai.openclaw.node.plist`
- Gateway plist is at `~/Library/LaunchAgents/ai.openclaw.gateway.plist`
- Node logs: `~/.openclaw/logs/node.log` and `~/.openclaw/logs/node.err.log`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [soulmachine](https://github.com/soulmachine)
- **Source:** [soulmachine/skills](https://github.com/soulmachine/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-soulmachine-skills-openclaw-diagnose
- Seller: https://agentstack.voostack.com/s/soulmachine
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.