Channel Errors

When OpenClaw’s connection to a messaging platform fails-Telegram, WhatsApp, Discord, Slack, Signal, or others-the problem is usually credentials, permissions, config, or the gateway. This page covers channel connection errors and how to fix them.

Not sure where to start? Run openclaw doctor first. It checks configuration, gateway, and common issues. See Quick diagnostics and the main Troubleshooting Guide.

Quick diagnostic for channels

Use these commands to see if the gateway and channels are healthy:

# Overall health and config
openclaw doctor

# Optional: try auto-fix for common config issues
openclaw doctor --fix

# Gateway and process status
openclaw status

# Watch logs while you reproduce the issue
openclaw logs --follow

# Validate config (including channel blocks)
openclaw config validate

If the gateway is down or unreachable, channel connections will fail. Fix that first: Gateway Issues.

Telegram: bot not responding

Your Telegram bot is online but does not reply, or messages never reach the agent.

  • Wrong or expired token: Get a new token from BotFather and update your config. Prefer an environment variable (e.g. TELEGRAM_BOT_TOKEN) instead of pasting the token in the config file-see Credential management.
  • Gateway not running: Run openclaw status. If the gateway is stopped, start it; then check Gateway Issues if it won’t stay up.
  • Channel not enabled or misconfigured: In your OpenClaw config, ensure the Telegram channel block is present and the adapter name/schema match your OpenClaw version. Run openclaw config validate and openclaw doctor.
  • Network/firewall: The machine running OpenClaw must be able to reach Telegram’s API. Proxies or corporate firewalls can block outbound HTTPS.

Full setup steps: Telegram setup guide.

WhatsApp: connection failed

WhatsApp integration typically uses the Business API or a compatible bridge. Failures are often due to credentials or configuration.

  • Invalid or expired credentials: Verify API keys, phone number ID, and business account linking. Rotate secrets if they may have been exposed.
  • Webhook/URL not reachable: OpenClaw must be reachable at the URL you registered with WhatsApp (often via a tunnel like ngrok or a reverse proxy). Ensure the gateway is bound correctly and the URL in the WhatsApp developer console matches. See Network isolation for safe exposure (e.g. reverse proxy, no direct port to internet).
  • Channel config mismatch: Check the channel block in your config against the official OpenClaw documentation for WhatsApp. Run openclaw doctor and openclaw config validate.

Step-by-step: WhatsApp integration guide.

Discord: permission and connection errors

Discord bots need the right intents and permissions, and a valid token.

  • Permission errors in channel: The bot must have “Read Messages/View Channels”, “Send Messages”, “Read Message History”, and “Use Slash Commands” (or equivalent) in the Discord server. Re-invite the bot with the correct OAuth2 scopes and bot permissions-see Discord setup guide.
  • Bot doesn’t read messages: In the Discord Developer Portal, enable Message Content Intent (Privileged Gateway Intents). Without it, the bot receives events but not message text.
  • Invalid token / bot offline: Regenerate the bot token in the Developer Portal and update your config (prefer env var). Restart the gateway after changing the token.
  • Rate limits / disconnects: Reduce message volume or check for duplicate instances. Check openclaw logs for Discord API errors.

Full walkthrough: Discord bot configuration.

Slack: workspace and app issues

Slack connections depend on the Slack app configuration and OAuth.

  • App not in workspace or revoked: Reinstall the app to the workspace and re-authorize. Ensure the app has the required OAuth scopes (e.g. chat:write, channels:history, im:history as needed).
  • Wrong credentials: Use the correct Bot User OAuth Token (starts with xoxb-) in config, preferably via environment variable. Rotate if compromised.
  • Socket mode vs webhook: Depending on how the OpenClaw Slack adapter works, you may need Socket Mode or a public webhook URL. Check the official channel docs for Slack and your OpenClaw version.

Setup: Slack integration guide.

Channel schema unavailable or unsupported

Errors like “channel schema unavailable” or “schema node unsupported” usually mean the config does not match what your OpenClaw version expects.

  • Upgrade or downgrade: Channel adapter names and schema can change between versions. Read the release notes and official documentation for your version.
  • Typos in channel id or adapter: Validate config with openclaw config validate and openclaw doctor. Fix any reported path or schema errors.
  • Config file location: OpenClaw may be reading a different config file than the one you edited. Run openclaw doctor to see which config file is in use (see Configuration file guide).

If the gateway reports “agent config moved” or similar, see Configuration problems.

Message routing problems

Messages reach the gateway but are not handled correctly-wrong agent, duplicate replies, or no reply.

  • Multiple gateways or instances: Ensure only one OpenClaw gateway is running for a given config. Multiple processes can cause duplicate responses or routing confusion. Use openclaw status and check for duplicate PIDs.
  • Session or user mapping: Routing is often keyed by channel and user/conversation ID. If the channel adapter or config changed, sessions may not match. Check logs for routing or session errors.
  • Model or API errors: If the agent never gets a model response, you may see rate limits or billing errors in logs. See Model & API errors.

Summary: channel errors at a glance

Symptom Likely cause What to do
Telegram bot not responding Invalid token; gateway down; wrong config Check token (BotFather); openclaw status and Gateway Issues; openclaw doctor
WhatsApp connection failed Credentials; webhook URL unreachable Verify API/phone ID; ensure webhook URL is reachable; WhatsApp guide
Discord permission errors Missing intents or bot permissions Enable Message Content Intent; re-invite bot with correct scopes; Discord guide
Slack workspace issues App not installed; wrong token; OAuth scopes Reinstall app; use Bot token (xoxb-); check official Slack channel docs
Channel schema unavailable Config schema mismatch for OpenClaw version Update config to match docs; openclaw config validate; Config problems
Message routing / no reply Multiple gateways; model/API errors Single gateway instance; check Model & API errors and logs

Related troubleshooting

Channel setup guides

If you haven’t set up a channel yet, follow the step-by-step guides:

Getting help

If you’re still stuck: