OpenClaw Node Not Pairing — Troubleshooting Guide

Node pairing failures are one of the most frustrating OpenClaw setup issues — everything looks right, but the connection won't complete. Here's a systematic fix guide covering the most common causes.

Problem

The companion app (iOS, Android, or macOS) won't pair with your OpenClaw node. You might see: QR code scan fails silently, "bootstrap token invalid or expired" error, "pairing required" when trying to connect, or the app connects briefly then drops.

Cause Overview

Node pairing issues almost always fall into one of these categories:

• Bootstrap token expired (they have a short TTL)
• Gateway URL not publicly accessible or wrong port
• Tailscale not connected or misconfigured
• Gateway not running when pairing attempted
• Firewall blocking the pairing endpoint

Step 1: Confirm Gateway Is Running

openclaw gateway status
# Must show: running

Pairing cannot complete if the gateway is down. Start it if needed:

openclaw gateway start

Step 2: Get a Fresh Bootstrap Token

Bootstrap tokens expire quickly — typically within 5-15 minutes. Generate a fresh one immediately before attempting to pair:

openclaw node pair
# Generates a new QR code and bootstrap token
# Use it within 5 minutes

If using a setup code instead of QR:

openclaw node pair --text
# Shows the text setup code

Step 3: Verify Gateway URL is Accessible

The companion app needs to reach your gateway from the outside. Check what URL your gateway is advertising:

openclaw gateway config show
# Look for: gateway.remote.url or gateway.bind

Test that the URL is reachable from outside your local network:

curl https://your-gateway-url/health
# Should return: {"status":"ok"}

If this fails, the pairing will fail. Your gateway URL must be publicly accessible or reachable via Tailscale from the companion device.

Step 4: Tailscale Troubleshooting

If you're using Tailscale for connectivity:

tailscale status
# Should show your node as connected

tailscale ping [your-gateway-node]
# Should succeed with low latency

If Tailscale shows disconnected:

tailscale up
# Re-authenticate if prompted

Make sure the companion device (phone/tablet) is also connected to the same Tailnet.

Step 5: Check Firewall Rules

# Check if OpenClaw's port is open
curl http://localhost:3000/health
# Replace 3000 with your configured gateway port

# On macOS, check firewall settings:
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps | grep openclaw

Step 6: Check Gateway Logs During Pairing Attempt

openclaw gateway logs --follow
# Keep this running, then attempt pairing
# Watch for errors when the companion app tries to connect

Look for: "pairing request received", "bootstrap token mismatch", "unauthorized", or connection errors.

Step 7: Reset and Re-Pair

If nothing else works, reset the node configuration:

openclaw node reset
openclaw gateway restart
openclaw node pair
# Immediately scan the new QR code

Ready to go deeper? The OpenClaw Playbook covers this in detail — grab your copy for $9.99.