You wake up to find your OpenClaw agent hasn’t responded to messages in hours. You check the dashboard at localhost:18789, and everything looks fine—all green lights, status “connected.” You send a test message. Nothing. Your agent is awake, but the messaging bridges are asleep, and nobody told you.
This is the silent failure mode that haunts every OpenClaw deployment: platforms disconnect without throwing errors, without alerting, without any visible sign that something broke. One moment your agent is responsive across WhatsApp, Telegram, Discord, and Slack. The next moment, you’re getting no replies, and the user experience goes from seamless to frustrating.
Here’s the truth that the documentation glosses over: messaging platform disconnections aren’t random glitches. They follow predictable patterns. Token expiry, session invalidation, rate limiting, network interruptions, gateway heartbeat failures—each platform has its own disconnection signatures, and each one requires a different fix. More importantly, you can anticipate them, monitor for them, and recover from them automatically.
In this article, I’m going to walk you through exactly what causes disconnections on each major platform, why the OpenClaw Gateway sometimes fails to detect them, and the monitoring and auto-recovery patterns that actually work. By the end, you’ll have a bulletproof monitoring setup that alerts you before your agent goes silent.
Why Messaging Platforms Disconnect: The Underlying Mechanisms
Let’s start with the hidden layer—the stuff that experienced practitioners know but the docs don’t explain.
Every messaging platform connection is a contract: your bridge sends a token or authentication credential to the platform’s server, and the server grants you a session that expires at a fixed time. Some platforms (like WhatsApp Web) renew this session implicitly by maintaining the WebSocket connection. Others (like Slack) require explicit token refresh on a schedule. And some (like Discord) monitor the connection with a heartbeat—a periodic “are you still there?” handshake that, if missed, terminates the session immediately.
The problem: OpenClaw’s Gateway monitors these connections passively. It waits to hear about a disconnection from the platform. But platforms don’t always announce disconnection clearly. WhatsApp Web might just go quiet. Telegram webhooks might start returning 401s without the bot noticing. Discord might close the gateway connection with a non-resumable opcode. Slack might silently stop delivering events after the token expires.
In these scenarios, the Gateway sees a connection that looks healthy—no errors logged, socket still open—but is actually dead. Messages come in, get routed to the bridge, and vanish into the void.
Token Expiry: The Most Common Culprit
Slack tokens expire. WhatsApp sessions expire. Telegram bot sessions can be invalidated by the platform without warning. When a token expires, the next API call fails with a 401 Unauthorized. But here’s the gotcha: the first failure often doesn’t propagate back to the Gateway. The bridge might retry silently, or queue the message, or just log an error that nobody reads.
The fix: proactive token refresh on a schedule, not reactive refresh on failure.
Session Invalidation: The Silent Killer
WhatsApp Web maintains a session file on disk. If that file gets corrupted, or if WhatsApp detects suspicious activity and invalidates all sessions (this happens), the connection dies without any error. The bridge still has a socket open. It still thinks it’s connected. But when you try to send a message, WhatsApp rejects it.
The fix: periodic session validation and forced re-authentication.
Rate Limiting: The Forgotten Constraint
Telegram rate-limits bot API calls. Discord rate-limits gateway connections. If you hit the limit, the platform doesn’t disconnect you—it just starts rejecting requests. The bridge might queue these, retry them later, and eventually succeed. Or it might drop them. Either way, messages disappear silently.
The fix: track rate limit headers and implement exponential backoff before you hit the ceiling.
Network Interruptions: The Obvious One You Still Need to Handle
WiFi drops. ISP hiccups. Cloud provider network maintenance. The connection dies, and the bridge needs to detect this and reconnect. Most bridges have some reconnection logic, but it’s often incomplete. The WebSocket might be “open” but the underlying network connection is dead. The Gateway doesn’t notice because it’s not pinging the bridge.
The fix: health checks and forced reconnection on timeout.
Platform-by-Platform Disconnection Patterns
Different platforms fail in different ways. Understanding these patterns is crucial because they determine what you monitor, what thresholds trigger alarms, and how you recover. You can’t use the same recovery strategy for all platforms—Discord’s heartbeat mechanism is nothing like WhatsApp’s webhook verification. If you try to apply the same fix to both, you’ll either miss failures on one platform or unnecessarily restart the other.
Here’s the key insight: most messaging platforms don’t care if you miss a single message or a single check-in. They care if you miss a pattern of them. One missed webhook? That’s okay. Three missed webhooks in a row? The platform assumes you’re dead and stops trying. This is why monitoring is about catching patterns, not individual events.
And here’s the subtle part: most platforms fail silently when they think you’re dead. They don’t send you an error message. They just stop delivering messages. Your OpenClaw agent continues running, continues accepting messages from your internal systems, continues trying to send outbound messages that never reach the platform. From your perspective, everything looks normal until you actually test it or a user complains.
Let’s go through each platform and understand exactly how this plays out:
Now let’s get specific. Each platform disconnects differently, and knowing the pattern is half the battle.
WhatsApp Web Bridge: The Session Stability Problem
WhatsApp Web is a reverse-engineered bridge that emulates the browser session. It’s powerful but brittle.
How it disconnects:
- Session file corruption (browser state invalid)
- QR code expiry (re-authentication required)
- WhatsApp server invalidates the session (security measure)
- Network timeout during message send
Why it stays disconnected:
The bridge maintains a local session file (~/.openclaw/whatsapp-session.json or similar). If this file becomes corrupted or out-of-sync with WhatsApp’s servers, the bridge can’t recover without QR code re-authentication. The bridge might not detect this until you try to send a message.
The monitoring pattern:
// Monitor WhatsApp Bridge Health
const whatsappHealthCheck = async (bridgeUrl = "https://automateanddeploy.com:3001") => {
try {
const response = await fetch(`${bridgeUrl}/api/status`, {
timeout: 5000,
});
const data = await response.json();
// Check three signals: socket connected, session valid, recent activity
const isConnected = data.socket?.connected === true;
const isSessionValid = data.session?.authenticated === true;
const lastActivity = new Date() - new Date(data.lastMessageTime || 0);
const isResponsive = lastActivity < 300000; // 5 minutes
return {
platform: "whatsapp",
healthy: isConnected && isSessionValid && isResponsive,
details: {
connected: isConnected,
authenticated: isSessionValid,
lastActivityMs: lastActivity,
requiresReauth: !isSessionValid,
},
};
} catch (error) {
return {
platform: "whatsapp",
healthy: false,
error: error.message,
details: { requiresReauth: true },
};
}
};
The key insight: don’t just check if the socket is open. Check if the session is authenticated. Check if messages are actually flowing. If you see a socket open but no recent activity, the bridge is dead.
The recovery pattern:
If WhatsApp fails health checks three times in a row, force re-authentication:
const whatsappRecovery = async (bridgeUrl = "https://automateanddeploy.com:3001") => {
console.log("[WhatsApp] Recovery triggered: requesting QR code");
try {
// POST to trigger logout and QR code regeneration
await fetch(`${bridgeUrl}/api/logout`, { method: "POST" });
// Wait for QR code generation (user must scan within 60 seconds)
const qrCheck = setInterval(async () => {
const qrResponse = await fetch(`${bridgeUrl}/api/qr-code`);
const { qrCode, authenticated } = await qrResponse.json();
if (authenticated) {
console.log("[WhatsApp] Session re-established");
clearInterval(qrCheck);
}
}, 2000);
// Timeout after 120 seconds
setTimeout(() => {
clearInterval(qrCheck);
console.error("[WhatsApp] Recovery failed: QR code not scanned");
}, 120000);
} catch (error) {
console.error("[WhatsApp] Recovery error:", error.message);
}
};
The gotcha: WhatsApp recovery requires human intervention (scanning a QR code). You can’t fully automate this. What you can do is detect the failure fast and alert the user to re-authenticate immediately, rather than silently losing messages for hours.
Telegram Bot Bridge: The Webhook vs Polling Dilemma
Telegram is more reliable than WhatsApp because it doesn’t require session state. But it has its own patterns.
How it disconnects:
- Bot token revoked (user changed password or revoked the token)
- Webhook URL becomes unreachable (DNS failure, firewall, IP change)
- Webhook IP changed and Telegram’s allowlist wasn’t updated
- Long-polling times out (network issue or platform timeout)
Why it stays disconnected:
Telegram uses one of two patterns: webhooks (Telegram pushes updates to you) or long-polling (you ask Telegram for updates). If you use webhooks and your URL becomes unreachable, Telegram stops trying after a few hours and you miss all messages. If you use long-polling and the connection times out, the bridge needs to detect this and reconnect.
The monitoring pattern:
// Monitor Telegram Bridge Health
const telegramHealthCheck = async (
botToken,
bridgeUrl = "https://automateanddeploy.com:3002",
) => {
try {
// Query Telegram API directly to test the token
const telegramResponse = await fetch(
`https://api.telegram.org/bot${botToken}/getMe`,
{ timeout: 10000 },
);
if (!telegramResponse.ok) {
return {
platform: "telegram",
healthy: false,
error: `Telegram API error: ${telegramResponse.status}`,
details: { requiresReauth: telegramResponse.status === 401 },
};
}
// Also check bridge's polling status
const bridgeResponse = await fetch(`${bridgeUrl}/api/status`, {
timeout: 5000,
});
const data = await bridgeResponse.json();
const isPolling = data.pollingActive === true;
const lastUpdate = new Date() - new Date(data.lastUpdateTime || 0);
const isUpdatingRecently = lastUpdate < 60000; // 1 minute
return {
platform: "telegram",
healthy: isPolling && isUpdatingRecently,
details: {
tokenValid: true,
polling: isPolling,
lastUpdateMs: lastUpdate,
},
};
} catch (error) {
return {
platform: "telegram",
healthy: false,
error: error.message,
};
}
};
The hidden layer: validate the token directly with Telegram, not just the bridge. If the bridge says it’s fine but Telegram says the token is invalid, you need to re-create the bot. Don’t wait for the bridge to figure it out.
The recovery pattern:
const telegramRecovery = async (
botToken,
bridgeUrl = "https://automateanddeploy.com:3002",
) => {
console.log("[Telegram] Recovery triggered: restarting polling");
try {
// Stop current polling
await fetch(`${bridgeUrl}/api/polling/stop`, { method: "POST" });
// Wait 5 seconds
await new Promise((resolve) => setTimeout(resolve, 5000));
// Restart polling
const response = await fetch(`${bridgeUrl}/api/polling/start`, {
method: "POST",
});
const data = await response.json();
if (data.success) {
console.log("[Telegram] Polling restarted");
} else {
console.error("[Telegram] Polling restart failed:", data.error);
}
} catch (error) {
console.error("[Telegram] Recovery error:", error.message);
}
};
Telegram is simpler to recover because you don’t need session state. Just restart the polling connection, and you’re back online within seconds.
Discord Bot: The Heartbeat and Gateway Opcode Problem
Discord uses a WebSocket gateway with a heartbeat mechanism. This is more complex but also more predictable.
How it disconnects:
- Gateway opcode 1000 (normal closure) – intentional disconnect
- Gateway opcode 1001 (going away) – server shutdown
- Gateway opcode 1002 (protocol error) – invalid data sent
- Gateway opcode 4000+ (Discord errors) – bot token invalid, intents wrong, etc.
- Heartbeat ACK timeout – the bridge sent a heartbeat but didn’t receive ACK
- Invalid session – token was revoked, permissions changed
Why it stays disconnected:
If the gateway closes with opcode 1006 (abnormal closure), the bridge should reconnect automatically. But if it closes with 1000 or 1001, it depends on the bridge implementation. Some bridges treat these as intentional and don’t reconnect. Some do reconnect but without exponential backoff, hammering the gateway and getting rate-limited.
The monitoring pattern:
// Monitor Discord Bot Gateway Health
const discordHealthCheck = async (
botToken,
bridgeUrl = "https://automateanddeploy.com:3003",
) => {
try {
// Check gateway status
const response = await fetch(`${bridgeUrl}/api/status`, { timeout: 5000 });
const data = await response.json();
const isConnected = data.gateway?.connected === true;
const sessionId = data.gateway?.sessionId;
const lastHeartbeatAck =
new Date() - new Date(data.gateway?.lastHeartbeatAck || 0);
// If heartbeat ACK is stale (>60 seconds), the connection is dead
const heartbeatHealthy = lastHeartbeatAck < 60000;
// Verify the bot can authenticate with Discord
let tokenValid = true;
try {
const discordResponse = await fetch(
"https://discord.com/api/v10/users/@me",
{
headers: { Authorization: `Bot ${botToken}` },
timeout: 5000,
},
);
tokenValid = discordResponse.ok;
} catch (e) {
tokenValid = false;
}
return {
platform: "discord",
healthy: isConnected && heartbeatHealthy && tokenValid,
details: {
connected: isConnected,
heartbeatHealthy,
lastHeartbeatAckMs: lastHeartbeatAck,
sessionId,
tokenValid,
},
};
} catch (error) {
return {
platform: "discord",
healthy: false,
error: error.message,
};
}
};
The key insight: heartbeat health is the real indicator. If the heartbeat ACK is stale, the connection is broken even if the socket is technically open.
The recovery pattern:
const discordRecovery = async (bridgeUrl = "https://automateanddeploy.com:3003") => {
console.log("[Discord] Recovery triggered: resuming gateway connection");
try {
// POST to resume gateway connection (uses existing session ID)
const response = await fetch(`${bridgeUrl}/api/gateway/resume`, {
method: "POST",
});
const data = await response.json();
if (data.resumed) {
console.log("[Discord] Gateway resumed with existing session");
} else if (data.reconnecting) {
console.log("[Discord] Creating new gateway connection");
} else {
console.error("[Discord] Resume failed:", data.error);
}
} catch (error) {
console.error("[Discord] Recovery error:", error.message);
// If resume fails, force a full reconnection
console.log("[Discord] Forcing full gateway reconnection");
await fetch(`${bridgeUrl}/api/gateway/disconnect`, { method: "POST" });
await new Promise((resolve) => setTimeout(resolve, 3000));
await fetch(`${bridgeUrl}/api/gateway/connect`, { method: "POST" });
}
};
Discord has built-in session resume, which is more elegant than reconnecting from scratch. Use this to recover from network hiccups. Only do a full reconnection if resume fails.
Slack: The OAuth Token Refresh Tango
Slack uses OAuth tokens that expire. This is a known pattern, but many deployments don’t implement the refresh correctly.
How it disconnects:
- Access token expired (Slack invalidated it after the expiration window)
- Refresh token expired (both tokens are dead, need to re-authenticate)
- Socket Mode connection dropped (disconnected from Slack’s WebSocket)
- App uninstalled or reinstalled (tokens invalidated)
Why it stays disconnected:
If you’re using Socket Mode (real-time event delivery), you maintain a WebSocket connection to Slack. If this connection drops, the bridge needs to reconnect. But here’s the gotcha: Slack sends you a disconnect event after closing the connection, so if your network is flaky, you might not receive it.
The monitoring pattern:
// Monitor Slack App Health
const slackHealthCheck = async (bridgeUrl = "https://automateanddeploy.com:3004") => {
try {
const response = await fetch(`${bridgeUrl}/api/status`, { timeout: 5000 });
const data = await response.json();
const isConnected = data.socket?.connected === true;
const tokenValid = data.oauth?.tokenValid === true;
const tokenExpiresAt = new Date(data.oauth?.expiresAt || 0);
const timeUntilExpiry = tokenExpiresAt - new Date();
// If token expires in less than 5 minutes, it's effectively stale
const tokenFresh = timeUntilExpiry > 300000;
const lastEventTime = new Date() - new Date(data.lastEventTime || 0);
const isReceivingEvents = lastEventTime < 120000; // 2 minutes
return {
platform: "slack",
healthy: isConnected && tokenFresh && isReceivingEvents,
details: {
connected: isConnected,
tokenValid,
tokenExpiresInMs: Math.max(0, timeUntilExpiry),
lastEventMs: lastEventTime,
},
};
} catch (error) {
return {
platform: "slack",
healthy: false,
error: error.message,
};
}
};
The hidden layer: watch the token expiration time, not just whether the token is currently valid. Proactively refresh before expiry, not after.
The recovery pattern:
const slackRecovery = async (bridgeUrl = "https://automateanddeploy.com:3004") => {
console.log("[Slack] Recovery triggered: reconnecting Socket Mode");
try {
// Disconnect current socket
await fetch(`${bridgeUrl}/api/socket/disconnect`, { method: "POST" });
// Wait for clean disconnect
await new Promise((resolve) => setTimeout(resolve, 2000));
// Reconnect socket
const response = await fetch(`${bridgeUrl}/api/socket/connect`, {
method: "POST",
});
const data = await response.json();
if (data.connected) {
console.log("[Slack] Socket Mode reconnected");
} else {
console.error("[Slack] Socket Mode reconnection failed:", data.error);
// If socket reconnection fails, try token refresh
console.log("[Slack] Attempting token refresh");
await slackTokenRefresh(bridgeUrl);
}
} catch (error) {
console.error("[Slack] Recovery error:", error.message);
}
};
const slackTokenRefresh = async (bridgeUrl) => {
try {
const response = await fetch(`${bridgeUrl}/api/oauth/refresh`, {
method: "POST",
});
const data = await response.json();
if (data.refreshed) {
console.log("[Slack] OAuth token refreshed");
// Reconnect socket after token refresh
await fetch(`${bridgeUrl}/api/socket/connect`, { method: "POST" });
} else {
console.error("[Slack] Token refresh failed:", data.error);
}
} catch (error) {
console.error("[Slack] Token refresh error:", error.message);
}
};
Slack recovery is a two-step dance: reconnect the socket first (fast), then refresh the token if socket reconnection fails (slower but more reliable).
Signal: The Simple Messenger Problem
Signal is simpler than the others because it doesn’t have complex session management or OAuth. But it has its own quirks.
How it disconnects:
- Registration invalidated (phone number deregistered from Signal)
- Sync service becomes unreachable (network or service outage)
- Session key expires (requires re-registration)
- Bridge loses contact with local Signal daemon (if using a local daemon)
Why it stays disconnected:
Signal doesn’t have built-in reconnection logic like Discord or Slack. If the sync service is unreachable, the bridge just waits. It won’t know to try again until someone initiates a new action.
The monitoring pattern:
// Monitor Signal Bridge Health
const signalHealthCheck = async (bridgeUrl = "https://automateanddeploy.com:3005") => {
try {
const response = await fetch(`${bridgeUrl}/api/status`, { timeout: 5000 });
const data = await response.json();
const isConnected = data.connected === true;
const isRegistered = data.registered === true;
const lastSync = new Date() - new Date(data.lastSyncTime || 0);
// If last sync is > 10 minutes, consider it unhealthy
const isSyncHealthy = lastSync < 600000;
return {
platform: "signal",
healthy: isConnected && isRegistered && isSyncHealthy,
details: {
connected: isConnected,
registered: isRegistered,
lastSyncMs: lastSync,
requiresReregistration: !isRegistered,
},
};
} catch (error) {
return {
platform: "signal",
healthy: false,
error: error.message,
};
}
};
The key insight: check registration status. If the bridge is connected but not registered, you need to re-register (requires a phone number confirmation).
The recovery pattern:
const signalRecovery = async (bridgeUrl = "https://automateanddeploy.com:3005") => {
console.log("[Signal] Recovery triggered: restarting sync");
try {
// Try a sync restart first (faster)
const response = await fetch(`${bridgeUrl}/api/sync/restart`, {
method: "POST",
});
const data = await response.json();
if (data.synced) {
console.log("[Signal] Sync restarted");
} else if (data.registered) {
console.log("[Signal] Still registered, attempting reconnect");
// Try reconnecting to the Signal service
await fetch(`${bridgeUrl}/api/reconnect`, { method: "POST" });
} else {
console.log("[Signal] Not registered, manual re-registration required");
console.log("[Signal] Phone number needed for re-registration");
}
} catch (error) {
console.error("[Signal] Recovery error:", error.message);
}
};
Signal is the least automated because re-registration requires a phone number confirmation code. For production, document this as a known limitation: if Signal loses registration, an operator needs to re-register it manually.
Here’s what this means in practice: if your WhatsApp token expires and you don’t notice, your agent will keep trying to send messages for days. The API will reject each attempt (silently), and you won’t see an error unless you’re specifically monitoring for 401 responses. Meanwhile, users are messaging your agent on WhatsApp expecting responses that never come.
If your Discord bot’s heartbeat fails, the WebSocket closes. Your code catches the disconnection and should attempt to reconnect. But if your reconnection code has a bug, or if you’re not restarting the connection attempt properly, the bot stays offline indefinitely. The OpenClaw process is running. The Discord token is valid. But nobody can reach you.
These scenarios aren’t theoretical. They happen every week in production systems around the world. The fix isn’t complex—it’s just visibility and automation. You need to see disconnections the moment they happen, and you need the system to recover without waiting for a human.
Why Passive Monitoring Fails (And What Works Instead)
The biggest mistake people make is relying on passive monitoring. You set up a log aggregation system and wait for errors to appear. When no errors appear, you assume everything’s working. This is backwards.
Passive monitoring means you’re checking logs after the fact. “Did we see a 401 error in the Telegram bridge?” “Did the Discord WebSocket close unexpectedly?” This approach finds problems hours or days after they start. By then, your agent has been silent for hours, and users have stopped trying to message you.
Active monitoring means you check directly that each platform is working. You don’t wait for errors. You ask the bridge “are you connected?” and “are you receiving messages?” If the answer is no, you act immediately.
The difference: with passive monitoring, a platform can be dead for six hours before you know. With active monitoring, you know within sixty seconds.
Active monitoring works because:
-
You control the check frequency. Every minute, every 30 seconds, whatever you decide. You’re not waiting for an error to occur.
-
You test multiple signals. It’s not just “is the connection open?” It’s “is the connection open AND are we receiving messages AND is the session valid?” Multiple signals give you a complete picture.
-
You can alert immediately. When the check fails, you alert the operator and attempt recovery. Not three hours later.
-
You build a historical record. After a month of active monitoring, you know exactly which platforms fail most often, which times of day they fail, and how long recovery takes.
The key to active monitoring is defining what “healthy” means for each platform. For WhatsApp, it’s “socket connected AND session authenticated AND received a message in the last 5 minutes.” For Discord, it’s “gateway connected AND heartbeat acknowledged in the last 60 seconds.” For Telegram, it’s “bot token valid AND polling is active AND received an update in the last 60 seconds.”
Once you define health checks, you can build a monitor that runs every 60 seconds, checks each platform, and automatically attempts recovery when something fails. This is what separates systems that have 99.9% uptime from systems that have 95% uptime with frequent mysterious downtimes.
Building a Unified Monitoring Script
Now let’s put this all together. Here’s a monitoring script that checks all platforms and automatically attempts recovery:
// openclaw-connection-monitor.js
// Save this as ~/openclaw-monitor/monitor.js
const fs = require("fs");
const path = require("path");
const fetch = require("node-fetch");
// Configuration
const CONFIG = {
bridgeUrls: {
whatsapp: "https://automateanddeploy.com:3001",
telegram: "https://automateanddeploy.com:3002",
discord: "https://automateanddeploy.com:3003",
slack: "https://automateanddeploy.com:3004",
signal: "https://automateanddeploy.com:3005",
},
checkInterval: 60000, // Check every 60 seconds
failureThreshold: 3, // Alert after 3 consecutive failures
tokens: {
telegram: process.env.TELEGRAM_BOT_TOKEN,
discord: process.env.DISCORD_BOT_TOKEN,
},
alertWebhook: process.env.ALERT_WEBHOOK_URL, // Slack or Discord webhook
logFile: path.join(process.env.HOME, ".openclaw/monitor.log"),
};
// State tracking
const platformState = {
whatsapp: { failures: 0, lastAlert: null, healthy: true },
telegram: { failures: 0, lastAlert: null, healthy: true },
discord: { failures: 0, lastAlert: null, healthy: true },
slack: { failures: 0, lastAlert: null, healthy: true },
signal: { failures: 0, lastAlert: null, healthy: true },
};
// Health check implementations for each platform
const healthChecks = {
whatsapp: async () => {
try {
const response = await fetch(`${CONFIG.bridgeUrls.whatsapp}/api/status`, {
timeout: 5000,
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
const isConnected = data.socket?.connected === true;
const isAuthenticated = data.session?.authenticated === true;
const lastActivity = new Date() - new Date(data.lastMessageTime || 0);
return {
platform: "whatsapp",
healthy: isConnected && isAuthenticated && lastActivity < 300000,
details: {
connected: isConnected,
authenticated: isAuthenticated,
lastActivityMs: lastActivity,
},
};
} catch (error) {
return {
platform: "whatsapp",
healthy: false,
error: error.message,
};
}
},
telegram: async () => {
try {
// Check bot token validity
const telegramResponse = await fetch(
`https://api.telegram.org/bot${CONFIG.tokens.telegram}/getMe`,
{ timeout: 10000 },
);
if (!telegramResponse.ok) {
return {
platform: "telegram",
healthy: false,
error: `Telegram API error: ${telegramResponse.status}`,
};
}
// Check bridge polling
const bridgeResponse = await fetch(
`${CONFIG.bridgeUrls.telegram}/api/status`,
{ timeout: 5000 },
);
const data = await bridgeResponse.json();
const isPolling = data.pollingActive === true;
const lastUpdate = new Date() - new Date(data.lastUpdateTime || 0);
return {
platform: "telegram",
healthy: isPolling && lastUpdate < 60000,
details: {
tokenValid: true,
polling: isPolling,
lastUpdateMs: lastUpdate,
},
};
} catch (error) {
return {
platform: "telegram",
healthy: false,
error: error.message,
};
}
},
discord: async () => {
try {
const response = await fetch(`${CONFIG.bridgeUrls.discord}/api/status`, {
timeout: 5000,
});
const data = await response.json();
const isConnected = data.gateway?.connected === true;
const lastHeartbeatAck =
new Date() - new Date(data.gateway?.lastHeartbeatAck || 0);
const heartbeatHealthy = lastHeartbeatAck < 60000;
return {
platform: "discord",
healthy: isConnected && heartbeatHealthy,
details: {
connected: isConnected,
lastHeartbeatAckMs: lastHeartbeatAck,
},
};
} catch (error) {
return {
platform: "discord",
healthy: false,
error: error.message,
};
}
},
slack: async () => {
try {
const response = await fetch(`${CONFIG.bridgeUrls.slack}/api/status`, {
timeout: 5000,
});
const data = await response.json();
const isConnected = data.socket?.connected === true;
const tokenExpiresAt = new Date(data.oauth?.expiresAt || 0);
const timeUntilExpiry = tokenExpiresAt - new Date();
const tokenFresh = timeUntilExpiry > 300000;
const lastEventTime = new Date() - new Date(data.lastEventTime || 0);
const isReceivingEvents = lastEventTime < 120000;
return {
platform: "slack",
healthy: isConnected && tokenFresh && isReceivingEvents,
details: {
connected: isConnected,
tokenExpiresInMs: Math.max(0, timeUntilExpiry),
},
};
} catch (error) {
return {
platform: "slack",
healthy: false,
error: error.message,
};
}
},
signal: async () => {
try {
const response = await fetch(`${CONFIG.bridgeUrls.signal}/api/status`, {
timeout: 5000,
});
const data = await response.json();
const isConnected = data.connected === true;
const lastSync = new Date() - new Date(data.lastSyncTime || 0);
return {
platform: "signal",
healthy: isConnected && lastSync < 300000,
details: {
connected: isConnected,
lastSyncMs: lastSync,
},
};
} catch (error) {
return {
platform: "signal",
healthy: false,
error: error.message,
};
}
},
};
// Recovery implementations
const recoveryActions = {
whatsapp: async () => {
log("INFO", "Attempting WhatsApp recovery: requesting QR code");
try {
await fetch(`${CONFIG.bridgeUrls.whatsapp}/api/logout`, {
method: "POST",
});
return true;
} catch (error) {
log("ERROR", `WhatsApp recovery failed: ${error.message}`);
return false;
}
},
telegram: async () => {
log("INFO", "Attempting Telegram recovery: restarting polling");
try {
await fetch(`${CONFIG.bridgeUrls.telegram}/api/polling/stop`, {
method: "POST",
});
await new Promise((resolve) => setTimeout(resolve, 5000));
await fetch(`${CONFIG.bridgeUrls.telegram}/api/polling/start`, {
method: "POST",
});
return true;
} catch (error) {
log("ERROR", `Telegram recovery failed: ${error.message}`);
return false;
}
},
discord: async () => {
log("INFO", "Attempting Discord recovery: resuming gateway");
try {
const response = await fetch(
`${CONFIG.bridgeUrls.discord}/api/gateway/resume`,
{
method: "POST",
},
);
const data = await response.json();
if (data.resumed || data.reconnecting) {
return true;
}
// If resume fails, force full reconnection
await fetch(`${CONFIG.bridgeUrls.discord}/api/gateway/disconnect`, {
method: "POST",
});
await new Promise((resolve) => setTimeout(resolve, 3000));
await fetch(`${CONFIG.bridgeUrls.discord}/api/gateway/connect`, {
method: "POST",
});
return true;
} catch (error) {
log("ERROR", `Discord recovery failed: ${error.message}`);
return false;
}
},
slack: async () => {
log("INFO", "Attempting Slack recovery: reconnecting Socket Mode");
try {
await fetch(`${CONFIG.bridgeUrls.slack}/api/socket/disconnect`, {
method: "POST",
});
await new Promise((resolve) => setTimeout(resolve, 2000));
const response = await fetch(
`${CONFIG.bridgeUrls.slack}/api/socket/connect`,
{
method: "POST",
},
);
const data = await response.json();
return data.connected === true;
} catch (error) {
log("ERROR", `Slack recovery failed: ${error.message}`);
return false;
}
},
signal: async () => {
log("INFO", "Attempting Signal recovery: restarting sync");
try {
await fetch(`${CONFIG.bridgeUrls.signal}/api/sync/restart`, {
method: "POST",
});
return true;
} catch (error) {
log("ERROR", `Signal recovery failed: ${error.message}`);
return false;
}
},
};
// Logging function
const log = (level, message) => {
const timestamp = new Date().toISOString();
const logEntry = `[${timestamp}] [${level}] ${message}\n`;
console.log(logEntry);
try {
fs.appendFileSync(CONFIG.logFile, logEntry);
} catch (error) {
console.error(`Failed to write log: ${error.message}`);
}
};
// Alert function
const sendAlert = async (platform, message, severity = "warning") => {
if (!CONFIG.alertWebhook) return;
const payload = {
text: `⚠️ OpenClaw Alert: ${platform}`,
attachments: [
{
color: severity === "error" ? "danger" : "warning",
fields: [
{ title: "Platform", value: platform, short: true },
{ title: "Time", value: new Date().toISOString(), short: true },
{ title: "Message", value: message, short: false },
],
},
],
};
try {
await fetch(CONFIG.alertWebhook, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(payload),
});
} catch (error) {
log("ERROR", `Failed to send alert: ${error.message}`);
}
};
// Main monitoring loop
const monitorLoop = async () => {
log("INFO", "Starting health check cycle");
for (const platform of Object.keys(healthChecks)) {
try {
const result = await healthChecks[platform]();
if (result.healthy) {
// Platform is healthy
if (!platformState[platform].healthy) {
log("INFO", `${platform} recovered`);
platformState[platform].healthy = true;
platformState[platform].failures = 0;
}
} else {
// Platform is unhealthy
platformState[platform].failures++;
log(
"WARN",
`${platform} health check failed (${platformState[platform].failures}/${CONFIG.failureThreshold}): ${result.error}`,
);
// If threshold is reached, alert and attempt recovery
if (platformState[platform].failures >= CONFIG.failureThreshold) {
const timeSinceLastAlert =
new Date() - (platformState[platform].lastAlert || 0);
// Only send alert if we haven't alerted in the last 10 minutes
if (timeSinceLastAlert > 600000) {
const message = `${platform} has failed ${CONFIG.failureThreshold} consecutive health checks. Attempting automatic recovery.`;
log("ERROR", message);
await sendAlert(platform, message, "error");
platformState[platform].lastAlert = new Date();
}
// Attempt recovery
const recovered = await recoveryActions[platform]();
if (recovered) {
log("INFO", `${platform} recovery action completed`);
platformState[platform].failures = 0; // Reset counter if recovery succeeded
}
}
}
} catch (error) {
log("ERROR", `Unexpected error checking ${platform}: ${error.message}`);
}
}
log("INFO", "Health check cycle complete");
};
// Start the monitor
log("INFO", "OpenClaw Connection Monitor started");
log("INFO", `Check interval: ${CONFIG.checkInterval}ms`);
log("INFO", `Failure threshold: ${CONFIG.failureThreshold}`);
setInterval(monitorLoop, CONFIG.checkInterval);
// Run first check immediately
monitorLoop();
To use this script:
# Install dependencies
npm install node-fetch
# Set environment variables
export TELEGRAM_BOT_TOKEN="your-token-here"
export DISCORD_BOT_TOKEN="your-token-here"
export ALERT_WEBHOOK_URL="https://hooks.slack.com/services/..." # Slack or Discord webhook
# Run the monitor
node ~/openclaw-monitor/monitor.js
The script runs forever, checking all platforms every 60 seconds. If a platform fails three times in a row, it logs an error, sends an alert, and attempts automatic recovery. The log file is written to ~/.openclaw/monitor.log.
Why This Matters: The Hidden Layer of System Design
You need to understand something fundamental about distributed systems like messaging platforms: they don’t care about you. They don’t know you exist. They have rules (rate limits, token expiry times, heartbeat intervals), and they enforce those rules mechanically. If you break a rule, the platform will disconnect you. It won’t warn you. It won’t give you a grace period. It will just disconnect.
Your job is to:
- Know the rules
- Never break them (or recover instantly when you do)
- Detect when you’re about to break a rule and proactively fix it
- Detect when you’ve already broken a rule and recover
- Tell the difference between “temporarily disconnected” and “fundamentally broken”
Most people skip steps 3 and 4 and wonder why their systems fail.
The reason most lead generation and customer service automation fails isn’t because the logic is bad. It’s because the operational model is broken. You can have perfect message handling code, but if your WhatsApp token expires and you don’t notice, all that perfect code is useless. The messages never reach WhatsApp.
This is why we’re not just showing you how to fix disconnections—we’re showing you how to make sure they never become visible to your users. The fix is monitoring + automation. Monitoring detects the problem. Automation fixes it. Together, they’re invisible.
Using systemd to Keep the Monitor Running
On Linux servers, use systemd to run the monitor as a service:
# /etc/systemd/system/openclaw-monitor.service
[Unit]
Description=OpenClaw Connection Monitor
After=network.target
[Service]
Type=simple
User=openclaw
WorkingDirectory=/home/openclaw/openclaw-monitor
ExecStart=/usr/bin/node /home/openclaw/openclaw-monitor/monitor.js
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
Then:
sudo systemctl enable openclaw-monitor
sudo systemctl start openclaw-monitor
sudo systemctl status openclaw-monitor
# View logs
sudo journalctl -u openclaw-monitor -f
The Dashboard Check: Why You Still Need Manual Verification
The OpenClaw Dashboard at localhost:18789 shows real-time connection status. But here’s the hidden layer: the dashboard is reactive, not proactive. It shows you the current state, but it won’t alert you when something breaks. The monitoring script fills this gap.
However, the dashboard is still valuable for:
- Quick manual verification during troubleshooting
- Viewing detailed gateway logs
- Checking individual bridge status in real-time
- Testing message send/receive manually
Visit the dashboard regularly during development. But for production use, you need automated monitoring.
Here’s the practical decision tree: if a platform reconnects within 30 seconds, it’s a blip. It happens. The system recovered automatically. Don’t worry about it.
If a platform stays disconnected for more than a minute, something is wrong. Check the logs. Is it a rate limit error? Is the token expired? Is there a network issue? Depending on the answer, you either:
- Back off and retry later (rate limit)
- Refresh the token (token expired)
- Check your network configuration (network issue)
- Restart the whole bridge (something fundamentally broken)
If a platform has been disconnected for more than an hour, it’s time for human intervention. Your automated recovery has failed. This is the point where you page an engineer and start investigating. But the key: you’ve bought an hour of time. You’ve probably already logged useful information. Your automated systems have attempted recovery multiple times. When the engineer gets paged, they have context.
When to Restart the Gateway vs When to Re-authenticate the Bridge
This is the decision point that catches people. The wrong choice costs you hours of downtime. Here’s the rule:
The Decision Tree
Ask yourself three questions:
-
How many platforms are affected?
-
One platform: targeted fix (re-auth or restart single bridge)
- Multiple platforms: consider full Gateway restart
-
All platforms: definitely full Gateway restart
-
Is the Gateway process healthy?
-
Check memory usage:
ps aux | grep openclaw - Check CPU: same command, look for high CPU% in column 3
- Check file handles:
lsof | grep openclaw | wc -l(should be < 1000) -
If any of these are bad, restart the Gateway
-
What’s the error pattern?
- “401 Unauthorized” or “token invalid”: re-authenticate
- “Connection refused” or “timeout”: restart bridge or Gateway
- “Heartbeat ACK timeout”: restart single bridge
- “Message send failed but API call succeeded”: session validation issue, re-auth
Restart Scenarios in Detail
Scenario 1: WhatsApp disconnected, everything else working
The session file is likely corrupted or the session expired. You can’t fix this without human intervention (QR code scan). So:
# Don't restart the Gateway—just trigger WhatsApp recovery
curl -X POST https://automateanddeploy.com:3001/api/logout
# Then wait for someone to scan the QR code, or
# restart just the WhatsApp bridge
docker restart openclaw-whatsapp-bridge
Decision: Single bridge restart or re-auth, not Gateway restart.
Scenario 2: Slack disconnected, but tokens are fresh and socket reconnects successfully
The socket Mode connection dropped (network hiccup), but the bridge detected it and reconnected. You might not need to restart anything:
# Check if socket reconnected automatically
curl https://automateanddeploy.com:3004/api/status | jq '.socket'
# If it's connected, you're done. If not, restart the bridge
docker restart openclaw-slack-bridge
Decision: Single bridge restart if needed, not Gateway restart.
Scenario 3: Multiple platforms disconnected simultaneously, but separately
WhatsApp disconnected 2 hours ago. Discord disconnected 1 hour ago. Telegram is fine. This is suspicious—something systemic is happening.
Check the Gateway logs:
# Docker logs
docker logs openclaw-gateway | tail -100
# Or systemd
journalctl -u openclaw -n 100
Look for patterns: are there repeated errors? Is the Gateway hitting connection limits? Is it running out of memory?
If the logs look healthy and it’s just isolated bridge failures, handle them individually. If you see errors about file descriptors, memory pressure, or repeated timeout errors, restart the Gateway:
# Full Gateway restart
docker restart openclaw-gateway
# Or with systemd
sudo systemctl restart openclaw
Decision: Check logs first. If logs look healthy: targeted fixes. If logs show systemic issues: full restart.
Scenario 4: All platforms disconnected simultaneously
This is the red alert. The Gateway itself is down or the network is broken. First, verify Gateway is actually running:
# Docker
docker ps | grep openclaw
# Systemd
systemctl status openclaw
# Process check
ps aux | grep openclaw | grep -v grep
If the process isn’t running, start it. If it is running but nothing can connect, restart it:
docker restart openclaw-gateway
# or
sudo systemctl restart openclaw
Decision: Full restart. This is a system-wide failure.
Supervisor Configuration: The Automation Layer
Instead of manually handling these decisions, use a supervisor (systemd, PM2, Kubernetes) to handle automatic restart policies. Here’s how:
Using systemd (Linux)
# /etc/systemd/system/openclaw.service
[Unit]
Description=OpenClaw Gateway
After=network.target
[Service]
Type=simple
User=openclaw
WorkingDirectory=/opt/openclaw
# Restart policy: always restart on failure
Restart=always
RestartSec=10
# But don't restart too fast if it's crashing immediately
StartLimitInterval=60s
StartLimitBurst=3
# If it crashes 3 times in 60 seconds, enter failure state (don't restart)
# This prevents thundering herd: if there's a critical bug, keep restarting doesn't help
StandardOutput=journal
StandardError=journal
ExecStart=/usr/bin/openclaw start
ExecStop=/usr/bin/openclaw stop
[Install]
WantedBy=multi-user.target
Key insights:
Restart=always: Restarts on any exitRestartSec=10: Waits 10 seconds before restarting (prevents rapid restart loop)StartLimitBurst=3: If it crashes 3 times within StartLimitInterval, consider it failedStartLimitInterval=60s: The time window for counting crashes
Using PM2 (Node/any application)
# pm2.config.js
module.exports = {
apps: [{
name: "openclaw-gateway",
script: "/usr/bin/openclaw",
args: "start",
instances: 1,
exec_mode: "fork",
// Restart settings
restart_delay: 4000, // Wait 4s before restarting
max_restarts: 3, // Max 3 restarts
min_uptime: 60000, // If it stays up 60s, reset restart count
// Monitoring
error_file: "/var/log/openclaw/pm2-error.log",
out_file: "/var/log/openclaw/pm2-out.log",
// Environment
env: {
NODE_ENV: "production"
}
}]
};
Then run it:
pm2 start pm2.config.js
pm2 save
pm2 startup # Enable PM2 to start on boot
This gives you:
- Automatic restart on failure
- Controlled restart rate (prevents crash loops)
- Persistent restart count reset (if process stays up for 60s, we trust it again)
- Logging for debugging
Using Kubernetes (for distributed deployments)
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: openclaw-gateway
spec:
replicas: 1
selector:
matchLabels:
app: openclaw-gateway
template:
metadata:
labels:
app: openclaw-gateway
spec:
containers:
- name: openclaw-gateway
image: openclaw:latest
ports:
- containerPort: 8080
# Restart policy: Kubernetes restarts containers on failure
# (this is always on, can't disable)
# Health check: tells Kubernetes if the container is healthy
livenessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 30
periodSeconds: 10
timeoutSeconds: 5
failureThreshold: 3
# Readiness check: tells Kubernetes if the container can accept traffic
readinessProbe:
httpGet:
path: /ready
port: 8080
initialDelaySeconds: 10
periodSeconds: 5
failureThreshold: 2
resources:
requests:
memory: "256Mi"
cpu: "250m"
limits:
memory: "512Mi"
cpu: "500m"
Kubernetes handles restart automatically, but the health checks tell it when to restart. If the liveness probe fails 3 times, Kubernetes kills the container and restarts it.
Monitoring Script Integration with Supervisor
The monitoring script you wrote earlier pairs perfectly with systemd/PM2. Instead of just alerting, it can trigger restarts:
// Modified openclaw-connection-monitor.js with restart capabilities
const recoveryActions = {
whatsapp: async () => {
log("INFO", "Attempting WhatsApp recovery");
try {
await fetch(`${CONFIG.bridgeUrls.whatsapp}/api/logout`, {
method: "POST",
});
return true;
} catch (error) {
log("ERROR", `WhatsApp recovery failed, restarting bridge`);
// Trigger restart via systemd or PM2
await restartBridge("openclaw-whatsapp-bridge");
return false;
}
},
// Similar for other platforms...
};
const restartBridge = async (bridgeName) => {
// For systemd
const { exec } = require("child_process");
return new Promise((resolve) => {
exec(`sudo systemctl restart ${bridgeName}`, (error) => {
if (error) {
log("ERROR", `Failed to restart ${bridgeName}: ${error.message}`);
resolve(false);
} else {
log("INFO", `${bridgeName} restarted`);
resolve(true);
}
});
});
};
This creates a chain: monitoring script detects issue → attempts automatic recovery → if that fails, restarts the bridge → if that fails, alerts the ops team.
The Full Recovery Escalation Path
Think of it as levels of escalation:
Level 1: Automatic (no human required)
- Token refresh (Slack OAuth)
- Session resume (Discord)
- Polling restart (Telegram)
- Socket reconnect (Slack, Discord)
Level 2: Automated restart (minimal human required)
- Single bridge restart (monitored script issues restart command)
- Then monitor for success
Level 3: Manual intervention (human required)
- Gateway restart (might affect all users)
- Re-authentication with manual steps (WhatsApp QR code)
- Configuration changes
Your monitoring script should be smart about escalation: start at Level 1, move to Level 2 if Level 1 fails, and alert for Level 3.
Common Pitfalls and How to Avoid Them
Pitfall 1: Assuming “Connected” Means “Working”
A socket can be open but the session dead. Always validate the session state, not just the socket connection. The monitoring script does this.
Pitfall 2: Not Tracking Token Expiration
Tokens expire on a schedule. WhatsApp sessions expire. Discord tokens are valid indefinitely but sessions can be invalidated. Watch the expiration time and refresh proactively, not reactively.
Pitfall 3: Forgetting about Rate Limits
Telegram and Discord rate-limit you. If you hit the limit, requests fail silently. Implement exponential backoff and watch rate-limit headers.
Pitfall 4: Ignoring Network Instability
WiFi drops. ISP hiccups. If your bridge runs on an unstable network, reconnection will be frequent. Use exponential backoff and increase timeouts for unstable networks.
Pitfall 5: Not Logging Everything
Without detailed logging, you can’t diagnose issues. The monitoring script logs to both stdout and a file. Keep these logs for at least a week so you can analyze failure patterns.
Conclusion: The Permanent Fix
Messaging platform disconnections are predictable. They follow patterns. And they can be detected and recovered from automatically.
The permanent fix is three-part:
- Understand why each platform disconnects (token expiry, session invalidation, network issues)
- Monitor proactively (don’t wait for the user to tell you something broke)
- Recover automatically when possible (and alert when you can’t)
The monitoring script I provided handles all three. Deploy it alongside OpenClaw, configure your alert webhook, and you’ll never again have silent failures where your agent is awake but the bridges are asleep.
The users will appreciate it. They’ll keep getting responses, and you’ll sleep better knowing you caught the problem before it became a problem.
Related Articles:
- OpenClaw Setup and Configuration: The Complete Guide
- Building Custom Message Bridges for OpenClaw
- Deploying OpenClaw to Production: Docker, systemd, and Monitoring
- Debugging OpenClaw: Reading Logs and Understanding the Gateway
Building Confidence in Your System: Testing and Validation
You’ve set up monitoring. You’ve configured automated recovery. Now comes the critical part: proving that it actually works.
Too many teams deploy recovery automation and then never test it. Weeks or months later, something fails, the recovery fails to kick in, and they find out their system doesn’t actually recover. That’s when you learn the hard way that your automation was broken, or your monitoring was misconfigured, or there was an edge case you didn’t anticipate.
Here’s what proper testing looks like:
Test each platform independently: Kill the connection for WhatsApp and verify that your monitoring detects it within 30 seconds and that recovery restores the connection. Then do the same for Telegram, Discord, Slack. Test each one separately because failures often compound in weird ways.
Test partial failures: What happens if WhatsApp is disconnected but Discord is fine? Does your system still function? Can agents still respond on Discord? Or does a failure in one platform take down the entire agent?
Test the monitoring itself: Generate a false positive. Manually trigger a disconnection alert and verify that your team gets notified. Then verify that they can act on it. If your alerting is broken, none of the other recovery matters.
Test recovery speed: Time how long it takes from disconnection to recovery. Is it under a minute? Under five minutes? The acceptable threshold depends on your use case, but you should know what it is and verify you’re meeting it.
Test failure cascades: What happens if a platform gets stuck in a disconnection-recovery-disconnection loop? Does your system back off and stop hammering the API? Or does it keep retrying forever and get rate-limited? If it gets rate-limited, does it handle the 429 errors gracefully?
Document what works: After you test successfully, document it. What was the scenario? What did you check? How long did recovery take? This becomes your playbook for future reference.
Testing takes time, but it’s the difference between “I hope this works” and “I know this works.” Choose the latter.