Skip to main content

Connection Problems

This guide helps diagnose and fix various connectivity issues with your ClawBook VPS.

Cannot SSH into Server​

Symptoms​

  • "Connection refused"
  • "Connection timed out"
  • "Permission denied"

Diagnosis​

1. Check if server is online

Ping the server:

ping YOUR_VPS_IP

If no response:

  • Check VPS provider dashboard for status
  • Server may be powered off or crashed
  • Network issue at provider level

2. Check if SSH port is open

nmap -p 22 YOUR_VPS_IP

# Or telnet
telnet YOUR_VPS_IP 22

3. Check SSH service status

If you have console access (via VPS provider):

sudo systemctl status sshd
sudo systemctl start sshd

Solutions​

Firewall Blocking

# Via VPS console
sudo ufw status
sudo ufw allow 22/tcp

SSH Not Running

sudo systemctl start sshd
sudo systemctl enable sshd

Wrong SSH Key

# Specify key explicitly
ssh -i ~/.ssh/correct_key root@YOUR_VPS_IP

# Verbose output for debugging
ssh -vvv root@YOUR_VPS_IP

IP Changed

Check current IP in VPS provider dashboard. Update your connection.

Dashboard Not Loading​

Symptoms​

  • Browser shows "Connection refused"
  • ERR_CONNECTION_TIMED_OUT
  • SSL errors

Diagnosis​

1. Test from server

# SSH in first, then:
curl -k https://localhost:8443

If works locally but not remotely: firewall issue.

2. Check service status

sudo systemctl status openclaw caddy

3. Check ports

sudo ss -tulpn | grep -E '8443|443|80'

Solutions​

Services Not Running

sudo systemctl restart openclaw caddy

Firewall Blocking

sudo ufw allow 8443/tcp
sudo ufw allow 443/tcp
sudo ufw allow 80/tcp
sudo ufw reload

Wrong URL

  • Use https:// not http://
  • Include port if using IP: https://IP:8443
  • If custom domain, ensure DNS is correct

SSL Certificate Issues

# Check certificate
clawbook-ssl status

# Renew if needed
clawbook-ssl renew yourdomain.com

Messaging Platform Disconnections​

WhatsApp Keeps Disconnecting​

Causes:

  • Phone went offline
  • Battery optimization killed WhatsApp
  • Linked device limit reached

Solutions:

  1. Ensure phone has stable WiFi

  2. Disable battery optimization for WhatsApp:

    • Android: Settings → Battery → WhatsApp → Don't optimize
    • iOS: Background App Refresh → WhatsApp → On

  3. Check linked devices (max 4):

    • WhatsApp → Linked Devices → Remove unused

  4. Re-scan QR code after disconnection

Telegram Bot Disconnected​

Check webhook:

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

Reset connection:

clawbook-telegram reconnect

Discord Bot Offline​

Check gateway status:

tail -100 /var/log/openclaw/discord.log | grep -i gateway

Reconnect:

clawbook-discord reconnect

API Connection Failures​

Symptoms​

  • "Failed to connect to API"
  • "Request timeout"
  • "SSL handshake failed"

Diagnosis​

Test API connectivity:

# Anthropic
curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

# OpenAI
curl -s https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hi"}],"max_tokens":10}'

Solutions​

DNS Issues

# Check DNS resolution
nslookup api.anthropic.com

# Try Google DNS
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

Firewall Blocking Outbound

sudo ufw allow out 443/tcp

SSL Issues

# Update CA certificates
sudo apt update && sudo apt install -y ca-certificates
sudo update-ca-certificates

Network Diagnostics​

Basic Connectivity​

# Check internet access
ping -c 3 google.com

# Check DNS
nslookup google.com

# Check specific service
ping -c 3 api.anthropic.com

Port Testing​

# Test outbound port
nc -zv api.anthropic.com 443

# Test from local to VPS
nc -zv YOUR_VPS_IP 8443

Traceroute​

# Find where connection fails
traceroute api.anthropic.com

Bandwidth Test​

# Install speedtest
sudo apt install speedtest-cli -y

# Run test
speedtest

VPS Provider Issues​

Check Provider Status​

Common Provider Issues​

Network Maintenance

  • Usually scheduled
  • Check provider notifications
  • May cause brief outages

DDoS Attacks

  • Provider may null-route your IP
  • Contact support if prolonged

Resource Throttling

  • If you exceed fair use
  • Check provider terms

Slow Network Performance​

Diagnosis​

# Check bandwidth
iperf3 -c iperf.he.net -p 5201

# Check latency
ping -c 10 api.anthropic.com

# Check packet loss
mtr -rw api.anthropic.com

Solutions​

High Latency

  • Choose VPS location closer to API servers
  • Most AI APIs are US-based
  • Consider US-East datacenter

Packet Loss

  • Usually provider/network issue
  • Contact support if persistent
  • May need different datacenter

Recovery Procedures​

Emergency Access​

If SSH is broken:

  1. VPS Provider Console

    • Most providers offer web console
    • Access via provider dashboard
    • Use to fix firewall/SSH issues

  2. Recovery Mode

    • Boot into recovery mode
    • Mount disk and fix configurations
    • Provider-specific process

Service Recovery​

# Stop all services
sudo systemctl stop openclaw caddy postgresql

# Start in order
sudo systemctl start postgresql
sudo systemctl start openclaw
sudo systemctl start caddy

# Check status
sudo systemctl status openclaw caddy postgresql

Factory Reset​

Last resort - reinstall everything:

# Backup first!
clawbook-backup create --output ~/emergency-backup.tar.gz

# Then reinstall via provider
# Restore from backup after reinstall

Monitoring Connections​

Real-time Connection Status​

# Watch all connections
watch -n 1 'ss -tulpn'

# Watch specific port
watch -n 1 'ss -tulpn | grep 8443'

Connection Logs​

# All connection attempts
sudo tail -f /var/log/auth.log

# Web server access
sudo tail -f /var/log/caddy/access.log

Set Up Alerts​

Configure notifications for connectivity issues:

  1. Settings → Notifications
  2. Enable "Service Down" alerts
  3. Configure email/Slack notification

Need More Help?​

If connection problems persist:

  1. Document the issue

    • Error messages
    • When it started
    • What changed

  2. Gather diagnostics

    clawbook-diagnostics network > ~/network-diag.txt

  3. Contact support