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
Connectivity probe: ok
Capability: read-only, write-capable, or admin-capable
Channel probe shows transport connected and, where supported, works or audit ok

After an update

Use this when Telegram, iMessage, BlueBubbles-era configs, or another plugin channel disappears after updating.

openclaw status --all
openclaw doctor --fix
openclaw gateway restart
openclaw status --all

Look for plugin load failed: dependency tree corrupted; run openclaw doctor --fix in openclaw status --all. That means the channel is configured, but plugin setup/load hit a corrupted dependency tree instead of registering the channel. openclaw doctor --fix clears stale plugin-runtime dependency symlinks and stale auth shadows, then openclaw gateway restart reloads clean state.

WhatsApp failure signatures

Symptom	Fastest check	Fix
Connected but no DM replies	`openclaw pairing list whatsapp`	Approve sender or switch DM policy/allowlist.
Group messages ignored	Check `requireMention` + mention patterns in config	Mention the bot or relax mention policy for that group.
QR login times out with 408	Check gateway `HTTPS_PROXY` / `HTTP_PROXY` env	Set a reachable proxy; use `NO_PROXY` only for bypasses.
Random disconnect/relogin loops	`openclaw channels status --probe` + logs	Recent reconnects are flagged even when currently connected; watch logs, restart the gateway, then relink if flapping continues.
`status=408 Request Time-out` loop	Probe, logs, doctor, then gateway status	Fix host connectivity/timing first; back up auth and re-link the account if the loop persists.
Replies arrive seconds/minutes late	`openclaw doctor --fix`	Doctor stops verified stale local TUI clients when they are degrading the Gateway event loop.

Full troubleshooting: WhatsApp troubleshooting

Telegram failure signatures

Symptom	Fastest check	Fix
`/start` but no usable reply flow	`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 `api.telegram.org`.
Startup reports `getMe returned 401`	Check configured token source	Re-copy or regenerate the BotFather token and update `botToken`, `tokenFile`, or default-account `TELEGRAM_BOT_TOKEN`.
Polling stalls or reconnects slowly	`openclaw logs --follow` for polling diagnostics	Upgrade; persistent stalls usually point to proxy/DNS/IPv6.
`setMyCommands` rejected at startup	Inspect logs for `BOT_COMMANDS_TOO_MUCH`	Reduce plugin/skill/custom Telegram commands or disable native menus.
Upgraded and allowlist blocks you	`openclaw security audit` and config allowlists	Run `openclaw doctor --fix` or replace `@username` with numeric sender IDs.

Full troubleshooting: Telegram troubleshooting

Discord

Discord failure signatures

Symptom	Fastest check	Fix
Bot online but no guild replies	`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 `requireMention: false`.
Typing/token usage but no Discord message	Check whether this is an ambient room event or an opted-in `message_tool` room where the model missed `message(action=send)`	Inspect the gateway verbose log for suppressed final payload metadata, verify `messages.groupChat.unmentionedInbound`, read Ambient room events, or keep `messages.groupChat.visibleReplies: "automatic"` for normal group requests.
DM replies missing	`openclaw pairing list discord`	Approve DM pairing or adjust DM policy.
Bot silent in channels that used to work	Check whether the guild entry gained a `channels` map	A channel map is an allowlist: unlisted channels are denied. Add a `"*"` wildcard entry. See Guild channel maps are allowlists.
Agent cannot see room history or attachments from other bots	Check the room’s `requireMention` and the account’s `allowBots`	`requireMention: true` drops unmentioned messages before they become room events, so there is no backlog. Bot-authored messages and their attachments need `allowBots` (`"mentions"` is the safer setting). See Ambient room events.
Agent watches an ambient room but never posts	Check the agent’s tool profile for the `message` tool	Room events require `message(action=send)`, which the `minimal` and `coding` profiles omit. Grant `tools.alsoAllow: ["message"]` for that agent.

Full troubleshooting: Discord troubleshooting

Slack

Slack failure signatures

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

Full troubleshooting: Slack troubleshooting

iMessage

iMessage failure signatures

Symptom	Fastest check	Fix
`imsg` missing or fails on non-macOS	`openclaw channels status --probe --channel imessage`	Run OpenClaw on the Messages Mac or use an SSH wrapper for `cliPath`.
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	`openclaw pairing list imessage`	Approve pairing or update allowlist.

Full troubleshooting: iMessage troubleshooting

Signal

Signal failure signatures

Symptom	Fastest check	Fix
Daemon reachable but bot silent	`openclaw channels status --probe`	Verify `signal-cli` daemon URL/account and receive mode.
DM blocked	`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 `appId` and `clientSecret` in config	Set credentials or restart the gateway.
No inbound messages	`openclaw channels status --probe`	Verify credentials on the QQ Open Platform.
Voice not transcribed	Check STT provider config	Configure `channels.qqbot.stt` or `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	`openclaw channels status --probe`	Check `groupPolicy`, room allowlist, and mention gating.
DMs do not process	`openclaw pairing list matrix`	Approve sender or adjust DM policy.
Encrypted rooms fail	`openclaw matrix verify status`	Re-verify the device, then check `openclaw matrix verify backup status`.
Backup restore is pending/broken	`openclaw matrix verify backup status`	Run `openclaw matrix verify backup restore` or rerun with a recovery key.
Cross-signing/bootstrap looks wrong	`openclaw matrix verify bootstrap`	Repair secret storage, cross-signing, and backup state in one pass.

Full setup and config: Matrix

Gateway up but channel never connects

If the gateway process is healthy but a channel stays stopped after repeated unclean boots, the crash-loop breaker may be suppressing channel auto-start. Use openclaw gateway call channels.start --params '{"channel":"<id>"}' to override, or wait for the unclean-boot window to drain and then restart the gateway.

Overview

Mainstream messaging

Developer and self-hosted

Regional platforms

Configuration

Channel troubleshooting

Command ladder

After an update

WhatsApp

WhatsApp failure signatures

Telegram

Telegram failure signatures

Discord

Discord failure signatures

Slack

Slack failure signatures

iMessage

iMessage failure signatures

Signal

Signal failure signatures

QQ Bot

QQ Bot failure signatures

Matrix

Matrix failure signatures

Gateway up but channel never connects

​Command ladder

​After an update

​WhatsApp

​WhatsApp failure signatures

​Telegram

​Telegram failure signatures

​Discord

​Discord failure signatures

​Slack

​Slack failure signatures

​iMessage

​iMessage failure signatures

​Signal

​Signal failure signatures

​QQ Bot

​QQ Bot failure signatures

​Matrix

​Matrix failure signatures

​Gateway up but channel never connects

​Related

Command ladder

After an update

WhatsApp

WhatsApp failure signatures

Telegram

Telegram failure signatures

Discord

Discord failure signatures

Slack

Slack failure signatures

iMessage

iMessage failure signatures

Signal

Signal failure signatures

QQ Bot

QQ Bot failure signatures

Matrix

Matrix failure signatures

Gateway up but channel never connects

Related