Troubleshooting OpenClaw Channel Disconnections and Reconnection Issues

Introduction

Channel disconnection is one of the most frustrating issues when using OpenClaw. Users send messages through a chat app but never receive a reply, often because the channel connection has dropped. This article systematically covers the causes, troubleshooting methods, and preventive measures for disconnections across various platforms.

1. General Diagnostic Steps

Regardless of which channel is disconnected, you can start with these general diagnostics:

# 1. Check OpenClaw service status
curl -s http://localhost:18789/health/detail | jq '.channels'

# 2. View channel-related logs
openclaw logs | grep -i "channel\|connect\|disconnect\|reconnect"

# 3. Run comprehensive diagnostics
openclaw doctor

# 4. Check network connectivity
ping api.telegram.org
ping web.whatsapp.com
ping discord.com

Channel Status Meanings

2. WhatsApp Disconnection Troubleshooting

WhatsApp is the most frequently disconnecting channel due to its relatively complex connection mechanism.

2.1 Common Disconnection Causes

2.2 Handling Session Expiry

# Check WhatsApp connection status
openclaw logs | grep -i "whatsapp"

# If it reports session expired, re-authentication is needed
openclaw restart

# After restart, check logs for the new QR code
openclaw logs | grep -A 20 "QR Code"

2.3 Session Persistence Configuration

// ~/.config/openclaw/openclaw.json5
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      // Session storage path (defaults to ~/.openclaw/sessions/)
      "sessionPath": "/home/user/.openclaw/sessions/whatsapp",
      // Keep-alive heartbeat interval (seconds)
      "keepAliveInterval": 30,
      // Auto-reconnect after disconnection
      "autoReconnect": true,
      // Maximum reconnection attempts
      "maxReconnectAttempts": 10,
      // Reconnection interval (seconds)
      "reconnectInterval": 15
    }
  }
}

2.4 WhatsApp Stability Optimization

# Ensure session files have correct permissions
ls -la ~/.openclaw/sessions/whatsapp/
chmod 700 ~/.openclaw/sessions/whatsapp/

# Back up session files (avoid frequent QR code re-scanning)
cp -r ~/.openclaw/sessions/whatsapp/ ~/whatsapp-session-backup/

3. Telegram Disconnection Troubleshooting

Telegram uses the Bot API or MTProto protocol, providing relatively stable connections, though Webhook mode may encounter issues.

3.1 Webhook Mode Troubleshooting

# Check if the Webhook is set up correctly
curl -s "https://api.telegram.org/bot<TOKEN>/getWebhookInfo" | jq .

# A normal response should include:
# {
#   "url": "https://your-domain.com/webhook/telegram",
#   "has_custom_certificate": false,
#   "pending_update_count": 0,
#   "last_error_date": null,
#   "last_error_message": null
# }

Common Webhook issues and solutions:

# Issue 1: Invalid SSL certificate
# Solution: Telegram Webhooks require a valid HTTPS certificate
sudo certbot renew

# Issue 2: Webhook URL unreachable
# Solution: Verify that the firewall allows the port and DNS resolves correctly
curl -sf https://your-domain.com/webhook/telegram

# Issue 3: Too many pending messages
# Solution: Clear the backlog and reset the Webhook
curl "https://api.telegram.org/bot<TOKEN>/deleteWebhook?drop_pending_updates=true"
# Then restart OpenClaw, which will automatically re-register the Webhook
openclaw restart

3.2 Long Polling Mode

If Webhook issues persist, you can switch to long polling mode:

// ~/.config/openclaw/openclaw.json5
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "mode": "polling",  // Switch to polling
      "pollingInterval": 1000
    }
  }
}

3.3 Telegram Reconnection Configuration

{
  "channels": {
    "telegram": {
      "autoReconnect": true,
      "maxReconnectAttempts": 20,
      "reconnectInterval": 10,
      "keepAliveInterval": 25
    }
  }
}

4. Discord Disconnection Troubleshooting

Discord uses WebSocket Gateway connections, and disconnections are usually related to Gateway events.

4.1 Gateway Disconnect Codes

4.2 Discord Intents Configuration

Many disconnection issues stem from missing required Gateway Intents:

# 1. Go to the Discord Developer Portal
# https://discord.com/developers/applications

# 2. Select your Bot -> Bot Settings
# 3. Enable the following Privileged Gateway Intents:
#    - Presence Intent
#    - Server Members Intent
#    - Message Content Intent

4.3 Discord Reconnection Configuration

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "autoReconnect": true,
      "maxReconnectAttempts": 15,
      "reconnectInterval": 10,
      // Heartbeat interval (specified by Discord server, typically 41250ms)
      "heartbeatInterval": 41250
    }
  }
}

5. Global Reconnection and Keep-Alive Configuration

5.1 Global Reconnection Strategy

// ~/.config/openclaw/openclaw.json5
{
  "connection": {
    // Global auto-reconnect
    "autoReconnect": true,
    // Exponential backoff reconnection strategy
    "backoff": {
      "initialDelay": 5000,      // First reconnection wait: 5 seconds
      "maxDelay": 300000,        // Maximum wait: 5 minutes
      "multiplier": 2            // Double each time
    },
    // Connection health check
    "healthCheck": {
      "enabled": true,
      "interval": 60000          // Check every 60 seconds
    }
  }
}

5.2 Keep-Alive Configuration

{
  "connection": {
    "keepAlive": {
      "enabled": true,
      "interval": 30000,    // Send heartbeat every 30 seconds
      "timeout": 10000      // Heartbeat timeout
    }
  }
}

5.3 Network Layer Optimization

# Increase system-level TCP keepalive settings
echo "net.ipv4.tcp_keepalive_time = 60" | sudo tee -a /etc/sysctl.conf
echo "net.ipv4.tcp_keepalive_intvl = 10" | sudo tee -a /etc/sysctl.conf
echo "net.ipv4.tcp_keepalive_probes = 6" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

6. Diagnostic Command Reference

6.1 Checking All Channel Statuses

# View all channel statuses at a glance
curl -s http://localhost:18789/health/detail | jq '{
  channels: .channels,
  uptime: .uptime,
  status: .status
}'

6.2 Real-Time Disconnection Event Monitoring

# Display connection status changes in real time
openclaw logs | grep --line-buffered -E "connect|disconnect|reconnect|session|auth"

6.3 Connection History Query

# View recent disconnection records
openclaw logs | grep -i "disconnect" | tail -20

# Count disconnections by channel
openclaw logs | grep -i "disconnect" | awk '{print $NF}' | sort | uniq -c | sort -rn

7. Automated Disconnection Recovery

7.1 External Monitoring Script

#!/bin/bash
# /usr/local/bin/openclaw-channel-watchdog.sh

HEALTH_URL="http://localhost:18789/health/detail"
EXPECTED_CHANNELS=("whatsapp" "telegram" "discord")

check_channels() {
    local health=$(curl -sf "$HEALTH_URL" 2>/dev/null)
    if [ -z "$health" ]; then
        echo "[$(date)] OpenClaw service unavailable" >> /var/log/openclaw-watchdog.log
        openclaw restart
        return
    fi

    for channel in "${EXPECTED_CHANNELS[@]}"; do
        local status=$(echo "$health" | jq -r ".channels.$channel" 2>/dev/null)
        if [ "$status" != "connected" ]; then
            echo "[$(date)] $channel status abnormal: $status" >> /var/log/openclaw-watchdog.log
            # Attempt restart to recover
            openclaw restart
            break
        fi
    done
}

check_channels

# Run every 5 minutes
chmod +x /usr/local/bin/openclaw-channel-watchdog.sh
echo "*/5 * * * * /usr/local/bin/openclaw-channel-watchdog.sh" | crontab -

8. Best Practices for Preventing Disconnections

1. Maintain network stability: Use a wired connection instead of Wi-Fi for your server
2. Use a process manager: PM2 or Systemd for automatic crash recovery
3. Regularly back up sessions: Especially WhatsApp session files
4. Monitor channel status: Use Uptime Kuma or Prometheus for monitoring
5. Log-based alerting: Send notifications when the keyword "disconnect" is detected
6. Keep software up to date: npm update -g openclaw@latest to get the latest connection fixes
7. Configure reconnection strategies properly: Use exponential backoff to avoid overly frequent reconnection attempts

By following the troubleshooting methods and configurations above, your OpenClaw channel connections will be much more stable and reliable.