Channel Troubleshooting Guide

Use this page when a channel establishes a connection but behaves incorrectly.

Command ladder

Start by running these in sequence:

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

Expected healthy state:

Runtime: running
Connectivity probe: ok
Capability: read-only, write-capable, or admin-capable
Channel probe reports transport connected and, when the feature exists, works or audit ok

After an update

Refer to this when Telegram, iMessage, BlueBubbles-era configs, or another plugin channel vanishes after an upgrade.

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

Search for plugin load failed: dependency tree corrupted; run openclaw doctor --fix inside openclaw status --all. That indicates the channel is set up, but plugin setup/load encountered a corrupted dependency tree rather than registering the channel. openclaw doctor --fix removes stale plugin-runtime dependency symlinks and outdated auth shadows, then openclaw gateway restart reloads a clean state.

WhatsApp failure signatures

Symptom	Fastest check	Fix
Connected but no DM replies	`openclaw pairing list whatsapp`	Approve the sender or adjust the DM policy/allowlist.
Group messages ignored	Check `requireMention` + mention patterns in config	Mention the bot or relax the mention policy for that group.
QR login times out with 408	Check gateway `HTTPS_PROXY` / `HTTP_PROXY` env	Configure 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; monitor logs, restart the gateway, then relink if flapping persists.
`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`	Enable guild/channel access and confirm the message content intent is turned on.
Group messages ignored	Look through logs for drops caused by mention gating	Have the bot mentioned, or configure guild/channel `requireMention: false`.
Typing/token usage but no Discord message	Determine whether this is an ambient room event or an opted-in `message_tool` room where the model skipped `message(action=send)`	Review the gateway verbose log for suppressed final payload metadata, confirm `messages.groupChat.unmentionedInbound`, consult Ambient room events, or retain `messages.groupChat.visibleReplies: "automatic"` for standard group requests.
DM replies missing	`openclaw pairing list discord`	Accept the DM pairing or modify the DM policy.
Bot silent in channels that used to work	See if the guild entry picked up a `channels` map	A channel map functions as an allowlist: any channel not listed is refused. Insert a `"*"` wildcard entry. Refer to Guild channel maps are allowlists.
Agent cannot see room history or attachments from other bots	Examine the room's `requireMention` and the account's `allowBots`	`requireMention: true` discards unmentioned messages before they turn into room events, so no backlog exists. Messages written by bots along with their attachments call for `allowBots` (`"mentions"` is the more secure choice). See Ambient room events.
Agent watches an ambient room but never posts	Inspect the agent's tool profile for the `message` tool	Room events depend on `message(action=send)`, which the `minimal` and `coding` profiles leave out. Assign `tools.alsoAllow: ["message"]` to that agent.

Full troubleshooting: Discord troubleshooting

Slack

Slack failure signatures

Symptom	Fastest check	Fix
Socket mode connected but no responses	`openclaw channels status --probe`	Confirm app token plus bot token and the necessary scopes; keep an eye out for `botTokenStatus` / `appTokenStatus = configured_unavailable` on SecretRef-backed setups.
DMs blocked	`openclaw pairing list slack`	Accept the pairing or ease the DM policy.
Channel message ignored	Check `groupPolicy` and channel allowlist	Permit the channel or change the 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`	Execute OpenClaw on the Messages Mac, or employ 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 the channel process.
DM sender blocked	`openclaw pairing list imessage`	Accept the pairing or refresh the allowlist.

Full troubleshooting: iMessage troubleshooting

Signal

Signal failure signatures

Symptom	Fastest check	Fix
Daemon reachable but bot silent	`openclaw channels status --probe`	Confirm the `signal-cli` daemon URL/account and receive mode.
DM blocked	`openclaw pairing list signal`	Approve the sender or tweak the DM policy.
Group replies do not trigger	Check group allowlist and mention patterns	Add the sender/group or relax 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`	Confirm credentials on the QQ Open Platform.
Voice not transcribed	Check STT provider config	Set up `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

When the gateway process runs fine yet a channel stays stopped after several unclean boots, the crash-loop breaker might be holding back channel auto-start. To override right away, use openclaw gateway call channels.start --params '{"channel":"<id>"}', or keep the healthy gateway active. Once the full unclean-boot window has passed, the same process re-evaluates the breaker and resumes auto-start for any deferred channels.