Gateway Pairing & Connection Troubleshooting

Having trouble pairing your Clawdbot Gateway? Follow this guide to resolve the most common "Gateway Pairing Failed" errors and get your system connected.

Common Error Message

Error: Gateway Pairing Failed. Please check your connection and try again.

Quick Fix Checklist

Follow these steps in order. Most pairing issues are resolved within the first 3 steps.

Check Internet Connection

Ensure your Mac mini has a stable internet connection. Gateway pairing requires an active connection to verify your API key.

# Test your connection

ping -c 4 api.clawdbot.com

✓ Expected: 4 packets transmitted, 4 packets received, 0.0% packet loss

Verify Your API Key

Invalid or expired API keys are the #1 cause of pairing failures. Make sure you're using the correct key from your Clawdbot dashboard.

# Check your API key configuration

clawdbot config get api-key

✓ Expected: A string starting with clk_ followed by 32+ characters

Tip: Generate a new API key from your dashboard if you suspect your current key is compromised or expired.

Check Firewall Settings

macOS firewall or third-party security software may block Clawdbot's connection to the gateway servers.

# Check if macOS firewall is enabled

/usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# Allow Clawdbot through firewall

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/local/bin/clawdbot

✓ If you see third-party antivirus software, temporarily disable it during pairing

Reset Gateway Configuration

If the above steps don't resolve the issue, reset your gateway configuration and try pairing again.

# Reset gateway and clear cached credentials

clawdbot gateway resetclawdbot gateway pair

⚠️ This will clear your saved pairing code. Have your code ready before running this command.

Check for Service Updates

Outdated Clawdbot services may have compatibility issues with the latest gateway protocol.

# Update Clawdbot to the latest version

clawdbot updateclawdbot restart

✓ Current version: 2.1.0 | Check for updates weekly

Advanced Troubleshooting

Enable Debug Logging

Get detailed logs to identify the exact point of failure.

clawdbot config set log-level debug

Logs are saved to: ~/.clawdbot/logs/gateway.log

Test Gateway Connectivity

Verify your Mac can reach the gateway servers.

clawdbot gateway test-connection

Returns: latency, packet loss, and DNS resolution status

Check DNS Resolution

DNS issues can prevent gateway discovery.

nslookup api.clawdbot.com

If this fails, try changing your DNS to 8.8.8.8 (Google DNS)

Verify TLS/SSL Certificates

Expired or invalid certificates can block secure connections.

curl -v https://api.clawdbot.com/health

Look for: "SSL certificate verify ok" in the output

Common Error Codes

Error Code	Meaning	Solution
E001	Invalid API key format	Regenerate API key from dashboard
E002	Network timeout	Check internet connection and firewall
E003	Gateway not responding	Service may be down - check status page
E004	Pairing code expired	Generate a new pairing code from dashboard
E005	TLS handshake failed	Update system certificates and Clawdbot