Channel troubleshooting
Use this page when a channel connects but behavior is wrong.
ClawCentral
In ClawCentral, use the platform dashboard to diagnose channel issues: check channel status and webhook delivery logs via Admin UI → Settings → Channels → [channel]. The CLI commands described on this page apply to self-hosted OpenClaw deployments.
Diagnostic steps
ClawCentral (managed platform)
- Open Admin UI → Settings → Channels → [channel] and check the channel status indicator.
- Review webhook delivery logs in the platform dashboard for recent inbound events and any delivery errors.
- Verify the channel's credentials are correctly configured under Admin UI → Settings → Tenant Settings → Secrets.
Self-hosted OpenClaw
Run these in order first:
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
Healthy baseline:
Runtime: runningRPC probe: ok- Channel probe shows connected/ready
WhatsApp
WhatsApp failure signatures
| Symptom | Fastest check | Fix |
|---|---|---|
| Connected but no DM replies | ClawCentral: Admin UI → Settings → Channels → WhatsApp → Pairing. Self-hosted: openclaw pairing list whatsapp | Approve sender or switch DM policy/allowlist. |
| Group messages ignored | Check requireMention + mention patterns in channel settings | Mention the bot or relax mention policy for that group. |
| Random disconnect/relogin loops | ClawCentral: check channel status in platform dashboard. Self-hosted: openclaw channels status --probe + logs | Re-login and verify credentials are healthy. |
Full troubleshooting: /channels/whatsapp#troubleshooting-quick
Telegram
Telegram failure signatures
| Symptom | Fastest check | Fix |
|---|---|---|
/start but no usable reply flow | ClawCentral: Admin UI → Settings → Channels → Telegram → Pairing. Self-hosted: openclaw pairing list telegram | Approve pairing or change DM policy. |
| Bot online but group stays silent | Verify mention requirement and bot privacy mode in channel settings | Disable privacy mode for group visibility or mention bot. |
| Send failures with network errors | Check platform dashboard logs for Telegram API call failures | Fix DNS/IPv6/proxy routing to api.telegram.org. |
setMyCommands rejected at startup | Check platform dashboard logs for BOT_COMMANDS_TOO_MUCH | Reduce plugin/skill/custom Telegram commands or disable native menus. |
| Upgraded and allowlist blocks you | Review allowlist settings in Admin UI → Settings → Channels → Telegram. Self-hosted: openclaw security audit | Replace @username with numeric sender IDs in allowlist config. |
Full troubleshooting: /channels/telegram#troubleshooting
Discord
Discord failure signatures
| Symptom | Fastest check | Fix |
|---|---|---|
| Bot online but no guild replies | ClawCentral: check channel status in Admin UI → Settings → Channels → Discord. Self-hosted: openclaw channels status --probe | Allow guild/channel and verify message content intent. |
| Group messages ignored | Check platform dashboard logs for mention gating drops | Mention bot or set guild/channel requireMention: false. |
| DM replies missing | ClawCentral: Admin UI → Settings → Channels → Discord → Pairing. Self-hosted: openclaw pairing list discord | Approve DM pairing or adjust DM policy. |
Full troubleshooting: /channels/discord#troubleshooting
Slack
Slack failure signatures
| Symptom | Fastest check | Fix |
|---|---|---|
| Socket mode connected but no responses | ClawCentral: check channel status in Admin UI → Settings → Channels → Slack. Self-hosted: openclaw channels status --probe | Verify app token + bot token and required scopes. |
| DMs blocked | ClawCentral: Admin UI → Settings → Channels → Slack → Pairing. Self-hosted: openclaw pairing list slack | Approve pairing or relax DM policy. |
| Channel message ignored | Check groupPolicy and channel allowlist in channel settings | Allow the channel or switch policy to open. |
Full troubleshooting: /channels/slack#troubleshooting
iMessage and BlueBubbles
iMessage and BlueBubbles failure signatures
| Symptom | Fastest check | Fix |
|---|---|---|
| No inbound events | Verify webhook/server reachability and app permissions; check delivery logs in platform dashboard | Fix webhook URL or BlueBubbles server state. |
| Can send but no receive on macOS | Check macOS privacy permissions for Messages automation | Re-grant TCC permissions and restart channel process. |
| DM sender blocked | ClawCentral: Admin UI → Settings → Channels → [iMessage or BlueBubbles] → Pairing. Self-hosted: openclaw pairing list imessage / openclaw pairing list bluebubbles | Approve pairing or update allowlist. |
Full troubleshooting:
- /channels/imessage#troubleshooting-macos-privacy-and-security-tcc
- /channels/bluebubbles#troubleshooting
Signal
Signal failure signatures
| Symptom | Fastest check | Fix |
|---|---|---|
| Daemon reachable but bot silent | ClawCentral: check channel status in Admin UI → Settings → Channels → Signal. Self-hosted: openclaw channels status --probe | Verify signal-cli daemon URL/account and receive mode. |
| DM blocked | ClawCentral: Admin UI → Settings → Channels → Signal → Pairing. Self-hosted: openclaw pairing list signal | Approve sender or adjust DM policy. |
| Group replies do not trigger | Check group allowlist and mention patterns in channel settings | Add sender/group or loosen gating. |
Full troubleshooting: /channels/signal#troubleshooting
Matrix
Matrix failure signatures
| Symptom | Fastest check | Fix |
|---|---|---|
| Logged in but ignores room messages | ClawCentral: check channel status in Admin UI → Settings → Channels → Matrix. Self-hosted: openclaw channels status --probe | Check groupPolicy and room allowlist. |
| DMs do not process | ClawCentral: Admin UI → Settings → Channels → Matrix → Pairing. Self-hosted: openclaw pairing list matrix | Approve sender or adjust DM policy. |
| Encrypted rooms fail | Verify crypto module and encryption settings in channel config | Enable encryption support and rejoin/sync room. |
Full troubleshooting: /channels/matrix#troubleshooting