OpenClaw Diagnose

Step 1: Gather status

openclaw gateway status
openclaw node status
openclaw nodes status
openclaw nodes pending

Step 2: Analyze warnings

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)/<label>

  to inspect each service
• Use

  lsof -iTCP:<port> -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 <requestId>

• 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:<port> -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

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