When using OpenClaw to connect to multiple chat platforms, you will inevitably encounter various connection issues. This article compiles the most common fault scenarios and troubleshooting methods for each channel, helping you quickly identify and resolve problems.
General Troubleshooting Steps
Regardless of which channel is experiencing issues, it is recommended to first perform the following general checks:
Check channel status: Run the openclaw channels status command to see the connection status, last active time, and error information for each configured channel.
Check the logs: OpenClaw's log files contain detailed connection and message processing information. Use openclaw logs --channel <channel-name> to filter logs for a specific channel. The log level can be adjusted to debug in the configuration for more detail.
Validate the configuration file: Use openclaw config validate to check openclaw.json for syntax errors and missing required fields. Many problems come down to typos or omitted fields in the configuration.
Check network connectivity: Ensure the OpenClaw instance can reach the target platform's API servers. For channels that require webhooks, make sure your server is publicly accessible.
Common Telegram Issues
Bot not receiving messages: The most common cause is another program using the same Bot Token to call getUpdates. Telegram's Bot API does not allow two clients to use long polling simultaneously. Ensure only one OpenClaw instance is running with that bot.
Not responding in groups: Check the Privacy Mode setting. If Privacy Mode is enabled (the default), the bot can only receive commands and @mentions. You need to disable Privacy Mode in BotFather, then remove and re-add the bot to the group.
Message formatting issues: Telegram's MarkdownV2 has strict escaping requirements for special characters. If AI responses contain characters like _, *, or [, formatting errors may occur. Try changing parseMode to HTML or plaintext.
Common WhatsApp Issues
QR code expired: WhatsApp QR codes have a short validity period and must be scanned before they expire. If it expires, run openclaw channels login whatsapp to regenerate the QR code.
Frequent disconnections: WhatsApp uses long-lived WebSocket connections, which are prone to disconnection on unstable networks. OpenClaw has a built-in auto-reconnect mechanism that handles recovery in most cases. If disconnections persist, check your server's network quality and firewall settings.
Account ban risk: WhatsApp has strict restrictions on automated usage. If the bot sends messages too frequently or receives many reports, the account may be banned. Control sending frequency, avoid proactively sending bulk messages, and ensure the bot only responds to known users' requests.
Multi-device login conflict: Baileys uses the multi-device protocol, but if you log out of WhatsApp Web on your phone or switch phones, the bot's connection will be invalidated and you'll need to re-scan the QR code.
Common Discord Issues
Bot shows offline: Confirm that the Bot Token is valid and the bot has been invited to the target server. Check that the invitation link's permission scope includes bot and applications.commands.
Cannot read messages: Discord's Privileged Gateway Intents must be manually enabled in the Discord Developer Portal. Go to the Bot settings page and enable Message Content Intent, otherwise the bot cannot read message content.
Insufficient permissions: Check the bot's role permissions in the server to ensure it has "Read Messages" and "Send Messages" permissions. Channel-level permission overrides may also prevent the bot from operating in specific channels.
Common Slack Issues
Event subscription failure: Slack sends a challenge request for verification when configuring event subscriptions. Ensure OpenClaw's webhook endpoint is publicly accessible and correctly handles the challenge response.
Bot not responding: Check whether OAuth Scopes include the necessary permissions, such as chat:write, channels:history, im:history, etc. Socket Mode and Event API modes have different configuration requirements — confirm you are using the correct mode.
Token expired: If using a user token rather than a Bot Token, it may expire. It is recommended to always use a Bot Token, which does not expire.
Common Signal Issues
signal-cli connection problems: OpenClaw's Signal channel depends on the signal-cli tool. Ensure signal-cli is properly installed and has completed number registration/linking. Run signal-cli -u +number receive to test whether messages can be received normally.
Message delay: signal-cli uses polling to retrieve messages, which may result in a few seconds of delay. This is normal and can be optimized by adjusting the polling interval.
Common Plugin Channel Issues
For channels installed through the plugin system (such as Lark, Mattermost, Nostr, etc.), common issues include:
Plugin version incompatibility: Run openclaw plugin update <plugin-name> to update to the latest version. There may be compatibility requirements between plugin versions and the OpenClaw main program version.
Plugin loading failure: Check whether the plugin's status shows as active in the openclaw plugin list output. If it shows error, check the detailed logs for the specific error cause.
Webhook-Related Issues
Multiple channels (such as Lark, Zalo, Google Chat) rely on webhooks to receive messages. Common webhook issues include:
SSL certificate issues: Most platforms require webhooks to use HTTPS. Ensure your SSL certificate is valid and not expired. Self-signed certificates are typically not accepted.
Timeout issues: After sending a webhook request, platforms usually expect a response within a few seconds. If AI processing takes longer, OpenClaw will first return a 200 acknowledgment, then asynchronously process the message and proactively send the reply.
IP allowlisting: Some platforms (such as Lark) only send webhook requests from specific IP ranges. If your firewall has inbound rules, make sure these IPs are allowed through.
Auto-Reconnect Mechanism
OpenClaw includes a built-in auto-reconnect mechanism for all channels. When a disconnection is detected, the system retries using an exponential backoff strategy. It retries immediately after the first disconnection, then increases the interval progressively (1s, 2s, 4s, 8s...), with a default maximum interval of 60 seconds.
You can adjust the reconnection parameters in the configuration:
{
"reconnect": {
"maxRetries": 50,
"maxInterval": 60,
"resetAfter": 300
}
}
resetAfter indicates how many seconds the connection must run stably before the retry counter is reset.
Getting Help
If none of the above troubleshooting methods resolve the issue, you can submit an Issue on OpenClaw's GitHub repository with your sanitized configuration file and relevant logs. The community typically responds within one to two days. When submitting an Issue, please specify the OpenClaw version, operating system, and the name of the affected channel.