OpenClaw channel troubleshooting

Most channel problems are not transport problems. The bot shows connected, the token is valid, and still nothing answers. The channel troubleshooting page exists for exactly that gap: a fixed command ladder, a healthy baseline to compare against, and per-channel tables of failure signatures with the fastest check for each. Here is the ladder and the signatures that come up most.

The ladder and the baseline

• Run in order: openclaw status, openclaw gateway status, openclaw logs --follow, openclaw doctor, then openclaw channels status --probe; the healthy baseline reads Runtime running, Connectivity probe ok, a Capability of read-only, write-capable or admin-capable, and a channel probe showing the transport connected and, where supported, works or audit ok.
• After an update, when Telegram, iMessage, a BlueBubbles-era config or another plugin channel disappears, run status --all, doctor --fix, gateway restart and status --all again; the line to look for is a plugin load failure with a corrupted dependency tree, which means the channel is configured but plugin setup hit corrupted symlinks instead of registering it.
• WhatsApp signatures: connected but no DM replies means pairing list whatsapp and approving the sender or switching the DM policy; group messages ignored means the mention requirement; a QR login that times out with 408 means the gateway proxy environment; relogin loops mean probe plus logs, then restart and relink if flapping continues; replies minutes late mean doctor --fix, which stops verified stale local TUI clients degrading the event loop.
• Telegram signatures: a start with no usable reply flow means pairing; a silent group means the mention requirement or bot privacy mode; network send failures mean DNS, IPv6 or proxy routing to the Telegram API; a getMe 401 at startup means the token source; polling stalls mean upgrade and then proxy or DNS; a rejected setMyCommands means too many commands; an allowlist that blocks you after an upgrade means doctor --fix or numeric sender IDs instead of usernames.

A channel map is an allowlist: unlisted channels are denied.

Discord and Slack

Discord has the longest table. A bot online with no guild replies is a probe check and then allowing the guild or channel and verifying the message content intent. Typing and token usage with no Discord message means the model treated the room as an ambient event or an opted-in message-tool room and missed the send action; the verbose gateway log shows the suppressed final payload. A bot that went silent in channels that used to work has usually gained a channels map on its guild entry, and the fix is a wildcard entry. An agent that cannot see room history from other bots needs the room mention requirement relaxed and the account allowBots setting, and an agent that watches an ambient room but never posts is missing the message tool that the minimal and coding profiles omit. Slack is shorter: socket mode connected with no responses means the app token, bot token and scopes, with a configured-but-unavailable token status on SecretRef-backed setups; blocked DMs mean pairing; an ignored channel message means the group policy and allowlist.

The other channels and the breaker

• iMessage: a missing or failing imsg on non-macOS means running OpenClaw on the Messages Mac or an SSH wrapper for the CLI path; send without receive means the macOS privacy permissions; a blocked DM sender means pairing. Signal: a reachable daemon with a silent bot means the signal-cli URL, account and receive mode.
• QQ Bot: a reply that says the bot has gone to Mars means the app ID and client secret; no inbound means the platform credentials; untranscribed voice means the STT provider config; missing proactive messages mean the platform blocks bot-initiated messages without recent interaction. Matrix: ignored room messages mean group policy, room allowlist and mention gating; failing encrypted rooms mean verify status, then backup status; a broken restore means backup restore with a recovery key; odd cross-signing means verify bootstrap.
• If the gateway is healthy but a channel stays stopped after repeated unclean boots, the crash-loop breaker may be suppressing channel auto-start: a gateway call to channels.start with the channel id overrides it immediately, or the same process rechecks the breaker once the unclean-boot window drains.

OpenClaw Telegram troubleshooting and OpenClaw Discord troubleshooting are the full per-channel troubleshooting posts this page points to first.

Why the order matters

The ladder is ordered from the widest view to the narrowest: status tells you whether the runtime is even running, gateway status whether the control plane answers, the log follow shows what is happening now, doctor finds and repairs the known misconfigurations, and the probe is the one command that asks each channel whether its transport really works. Skipping to the probe when the runtime is not running produces a misleading answer, and reading logs before doctor means reading symptoms that doctor would have named. OpenClaw Slack troubleshooting holds the Slack table in depth and OpenClaw pairing explains the pairing list that half the DM signatures point at.

On Diali

On Diali the channels are connected from the dashboard, the runtime configuration is generated from it and replaced at each release, and the same probe runs on the hosted runtime. Hosted OpenClaw on Diali is the assistant and WhatsApp on Diali the WhatsApp channel page, the channel with the longest signature table above.

• Status, gateway status, logs, doctor, probe: in that order.
• A channel gone after an update: doctor --fix then restart.
• Half the DM signatures resolve at the pairing list.