Skip to main content

​
Channel troubleshooting

Use this page when a channel connects but behavior is wrong.

​
Command ladder

Run these in order first: 
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
Healthy baseline:
  • Runtime: running
  • RPC probe: ok
  • Channel probe shows connected/ready

​
WhatsApp

​
WhatsApp failure signatures

SymptomFastest checkFix
Connected but no DM repliesopenclaw pairing list whatsappApprove sender or switch DM policy/allowlist.
Group messages ignoredCheck requireMention + mention patterns in configMention the bot or relax mention policy for that group.
Random disconnect/relogin loopsopenclaw channels status --probe + logsRe-login and verify credentials directory is healthy.
Full troubleshooting: /channels/whatsapp#troubleshooting-quick

​
Telegram

​
Telegram failure signatures

SymptomFastest checkFix
/start but no usable reply flowopenclaw pairing list telegramApprove pairing or change DM policy.
Bot online but group stays silentVerify mention requirement and bot privacy modeDisable privacy mode for group visibility or mention bot.
Send failures with network errorsInspect logs for Telegram API call failuresFix DNS/IPv6/proxy routing to api.telegram.org.
Full troubleshooting: /channels/telegram#troubleshooting

​
Discord

​
Discord failure signatures

SymptomFastest checkFix
Bot online but no guild repliesopenclaw channels status --probeAllow guild/channel and verify message content intent.
Group messages ignoredCheck logs for mention gating dropsMention bot or set guild/channel requireMention: false.
DM replies missingopenclaw pairing list discordApprove DM pairing or adjust DM policy.
Full troubleshooting: /channels/discord#troubleshooting

​
Slack

​
Slack failure signatures

SymptomFastest checkFix
Socket mode connected but no responsesopenclaw channels status --probeVerify app token + bot token and required scopes.
DMs blockedopenclaw pairing list slackApprove pairing or relax DM policy.
Channel message ignoredCheck groupPolicy and channel allowlistAllow the channel or switch policy to open.
Full troubleshooting: /channels/slack#troubleshooting

​
iMessage and BlueBubbles

​
iMessage and BlueBubbles failure signatures

SymptomFastest checkFix
No inbound eventsVerify webhook/server reachability and app permissionsFix webhook URL or BlueBubbles server state.
Can send but no receive on macOSCheck macOS privacy permissions for Messages automationRe-grant TCC permissions and restart channel process.
DM sender blockedopenclaw pairing list imessage or openclaw pairing list bluebubblesApprove pairing or update allowlist.
Full troubleshooting:

​
Signal

​
Signal failure signatures

SymptomFastest checkFix
Daemon reachable but bot silentopenclaw channels status --probeVerify signal-cli daemon URL/account and receive mode.
DM blockedopenclaw pairing list signalApprove sender or adjust DM policy.
Group replies do not triggerCheck group allowlist and mention patternsAdd sender/group or loosen gating.
Full troubleshooting: /channels/signal#troubleshooting

​
Matrix

​
Matrix failure signatures

SymptomFastest checkFix
Logged in but ignores room messagesopenclaw channels status --probeCheck groupPolicy and room allowlist.
DMs do not processopenclaw pairing list matrixApprove sender or adjust DM policy.
Encrypted rooms failVerify crypto module and encryption settingsEnable encryption support and rejoin/sync room.
Full troubleshooting: /channels/matrix#troubleshooting