Use this file to discover all available pages before exploring further.

Channel troubleshooting

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

Command ladder

Run these in order first:


bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Healthy baseline:

text
Runtime: running
text
Connectivity probe: ok
text
Capability: read-only
,
text
write-capable
, or
text
admin-capable
Channel probe shows transport connected and, where supported,
text
works
or
text
audit ok

WhatsApp failure signatures

Symptom	Fastest check	Fix
Connected but no DM replies	text `openclaw pairing list whatsapp`	Approve sender or switch DM policy/allowlist.
Group messages ignored	Check text `requireMention` + mention patterns in config	Mention the bot or relax mention policy for that group.
QR login times out with 408	Check gateway text `HTTPS_PROXY` / text `HTTP_PROXY` env	Set a reachable proxy; use text `NO_PROXY` only for bypasses.
Random disconnect/relogin loops	text `openclaw channels status --probe` + logs	Recent reconnects are flagged even when currently connected; watch logs, restart the gateway, then relink if flapping continues.

Full troubleshooting: WhatsApp troubleshooting

Telegram failure signatures

Symptom	Fastest check	Fix
text `/start` but no usable reply flow	text `openclaw pairing list telegram`	Approve pairing or change DM policy.
Bot online but group stays silent	Verify mention requirement and bot privacy mode	Disable privacy mode for group visibility or mention bot.
Send failures with network errors	Inspect logs for Telegram API call failures	Fix DNS/IPv6/proxy routing to text `api.telegram.org` .
Startup reports text `getMe returned 401`	Check configured token source	Re-copy or regenerate the BotFather token and update text `botToken` , text `tokenFile` , or default-account text `TELEGRAM_BOT_TOKEN` .
Polling stalls or reconnects slowly	text `openclaw logs --follow` for polling diagnostics	Upgrade; if restarts are false positives, tune text `pollingStallThresholdMs` . Persistent stalls still point to proxy/DNS/IPv6.
text `setMyCommands` rejected at startup	Inspect logs for text `BOT_COMMANDS_TOO_MUCH`	Reduce plugin/skill/custom Telegram commands or disable native menus.
Upgraded and allowlist blocks you	text `openclaw security audit` and config allowlists	Run text `openclaw doctor --fix` or replace text `@username` with numeric sender IDs.

Full troubleshooting: Telegram troubleshooting

Discord

Discord failure signatures

Symptom	Fastest check	Fix
Bot online but no guild replies	text `openclaw channels status --probe`	Allow guild/channel and verify message content intent.
Group messages ignored	Check logs for mention gating drops	Mention bot or set guild/channel text `requireMention: false` .
DM replies missing	text `openclaw pairing list discord`	Approve DM pairing or adjust DM policy.

Full troubleshooting: Discord troubleshooting

Slack

Slack failure signatures

Symptom	Fastest check	Fix
Socket mode connected but no responses	text `openclaw channels status --probe`	Verify app token + bot token and required scopes; watch for text `botTokenStatus` / text `appTokenStatus = configured_unavailable` on SecretRef-backed setups.
DMs blocked	text `openclaw pairing list slack`	Approve pairing or relax DM policy.
Channel message ignored	Check text `groupPolicy` and channel allowlist	Allow the channel or switch policy to text `open` .

Full troubleshooting: Slack troubleshooting

iMessage and BlueBubbles

iMessage and BlueBubbles failure signatures

Symptom	Fastest check	Fix
No inbound events	Verify webhook/server reachability and app permissions	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	text `openclaw pairing list imessage` or text `openclaw pairing list bluebubbles`	Approve pairing or update allowlist.

Full troubleshooting:

Signal

Signal failure signatures

Symptom	Fastest check	Fix
Daemon reachable but bot silent	text `openclaw channels status --probe`	Verify text `signal-cli` daemon URL/account and receive mode.
DM blocked	text `openclaw pairing list signal`	Approve sender or adjust DM policy.
Group replies do not trigger	Check group allowlist and mention patterns	Add sender/group or loosen gating.

Full troubleshooting: Signal troubleshooting

QQ Bot

QQ Bot failure signatures

Symptom	Fastest check	Fix
Bot replies "gone to Mars"	Verify text `appId` and text `clientSecret` in config	Set credentials or restart the gateway.
No inbound messages	text `openclaw channels status --probe`	Verify credentials on the QQ Open Platform.
Voice not transcribed	Check STT provider config	Configure text `channels.qqbot.stt` or text `tools.media.audio` .
Proactive messages not arriving	Check QQ platform interaction requirements	QQ may block bot-initiated messages without recent interaction.

Full troubleshooting: QQ Bot troubleshooting

Matrix

Matrix failure signatures

Symptom	Fastest check	Fix
Logged in but ignores room messages	text `openclaw channels status --probe`	Check text `groupPolicy` , room allowlist, and mention gating.
DMs do not process	text `openclaw pairing list matrix`	Approve sender or adjust DM policy.
Encrypted rooms fail	text `openclaw matrix verify status`	Re-verify the device, then check text `openclaw matrix verify backup status` .
Backup restore is pending/broken	text `openclaw matrix verify backup status`	Run text `openclaw matrix verify backup restore` or rerun with a recovery key.
Cross-signing/bootstrap looks wrong	text `openclaw matrix verify bootstrap`	Repair secret storage, cross-signing, and backup state in one pass.

Full setup and config: Matrix

OpenClaw Docs