channels

Channels

OpenClaw supports 50+ messaging platforms through a unified channel abstraction in the Gateway. Each channel is a bridge that converts platform-specific message formats into internal Gateway events and streams replies back. All channel configuration lives in the channels object of ~/.openclaw/openclaw.json.

Supported Platforms at a Glance

Platform	Library / Method	Auth Mechanism	Difficulty
WhatsApp	Baileys (unofficial Web API)	QR code pairing	Easy
Telegram	grammY	@BotFather token	Easy
Discord	discord.js	Developer Portal app + bot token	Medium
Slack	Bolt framework	OAuth app + Socket Mode	Medium
Signal	signal-cli	Phone number + registration	Hard
iMessage	BlueBubbles	macOS server + API key	Hard
Google Chat	Google Workspace API	Chat app via Admin console	Medium
Teams	@openclaw/msteams plugin	Azure AD app registration	Medium
Matrix	@openclaw/matrix plugin	Homeserver + access token	Medium

For full step-by-step setup instructions on each platform, consult the dedicated reference files:

• WhatsApp: ${CLAUDE_PLUGIN_ROOT}/skills/channels/references/whatsapp.md
• Telegram: ${CLAUDE_PLUGIN_ROOT}/skills/channels/references/telegram.md
• Discord: ${CLAUDE_PLUGIN_ROOT}/skills/channels/references/discord.md
• Slack: ${CLAUDE_PLUGIN_ROOT}/skills/channels/references/slack.md
• Signal: ${CLAUDE_PLUGIN_ROOT}/skills/channels/references/signal.md
• iMessage: ${CLAUDE_PLUGIN_ROOT}/skills/channels/references/imessage.md
• Google Chat: ${CLAUDE_PLUGIN_ROOT}/skills/channels/references/google-chat.md
• Teams: ${CLAUDE_PLUGIN_ROOT}/skills/channels/references/teams.md
• Matrix: ${CLAUDE_PLUGIN_ROOT}/skills/channels/references/matrix.md

Configuration Pattern

Every channel follows the same structure inside openclaw.json. Enable a channel by adding its key to the channels object with enabled: true and any platform-specific options. Always reference secrets through environment variable substitution ("${VAR_NAME}") rather than hardcoding tokens.

{
  channels: {
    whatsapp: {
      enabled: true,
      // WhatsApp uses QR-code pairing; no token needed in config
    },
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
    },
    discord: {
      enabled: true,
      botToken: "${DISCORD_BOT_TOKEN}",
    },
    slack: {
      enabled: true,
      botToken: "${SLACK_BOT_TOKEN}",
      appToken: "${SLACK_APP_TOKEN}",
    },
    signal: {
      enabled: true,
      phoneNumber: "+1234567890",
    },
    imessage: {
      enabled: true,
      blueBubblesUrl: "http://localhost:1234",
      apiKey: "${BLUEBUBBLES_API_KEY}",
    },
    "google-chat": {
      enabled: true,
    },
    teams: {
      enabled: true,
    },
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.com",
      accessToken: "${MATRIX_ACCESS_TOKEN}",
    },
  }
}

After editing the config, verify the channel with:

openclaw channels status --probe

The Gateway watches openclaw.json for changes and hot-reloads safe modifications (including channel toggles). Critical changes such as switching the Gateway bind address require a full restart.

Quick-Start Recommendations

For a first channel, start with one of the easy-difficulty platforms:

1. Telegram -- Create a bot via @BotFather in Telegram, copy the token, set TELEGRAM_BOT_TOKEN in the environment or ~/.openclaw/.env, and enable the channel. The bot is reachable within seconds.
2. WhatsApp -- Enable the WhatsApp channel and run openclaw onboard or visit the dashboard. Scan the QR code with the WhatsApp mobile app to link the session. Baileys maintains the session locally so the QR scan is a one-time step (unless the session expires).

Once comfortable, add a second platform to experience multi-channel operation.

DM and Group Policies

Access control determines who can message OpenClaw and how group interactions work. Configure policies globally or per-channel. See ${CLAUDE_PLUGIN_ROOT}/skills/channels/references/dm-and-group-policies.md for full details.

DM Policy (dmPolicy)

Controls how OpenClaw handles incoming direct messages from unknown senders.

Value	Behavior
"pairing" (default)	Unknown senders receive a one-time pairing code that expires after 1 hour. The owner approves or denies the pairing request from the dashboard or a paired device. This is the recommended policy for production.
"allowlist"	Only peer IDs listed in allowFrom may initiate conversations. All other messages are silently dropped. Also recommended for production.
"open"	Any sender can message OpenClaw without approval. Suitable for public-facing bots or demos, but carries significant security risk.
"disabled"	DMs are entirely disabled on this channel.

Group Policy (groupPolicy)

Controls whether OpenClaw responds in group chats.

Value	Behavior
"open"	Responds in any group it is added to.
"allowlist"	Responds only in groups whose IDs appear in allowFrom.

Peer Allowlists

The allowFrom array accepts platform-specific peer identifiers:

• WhatsApp: phone numbers in E.164 format (e.g., "+14155551234")
• Telegram: numeric user IDs (e.g., "123456789")
• Discord: Discord user snowflake IDs (e.g., "981234567890123456")
• Slack: Slack member IDs (e.g., "U04ABCDEF")

Mention Patterns

In group chats, OpenClaw responds only when mentioned. The mentionPatterns array holds regex patterns that trigger a response:

{
  channels: {
    discord: {
      enabled: true,
      botToken: "${DISCORD_BOT_TOKEN}",
      mentionPatterns: ["@OpenClaw", "hey claw"],
    }
  }
}

Patterns are case-insensitive by default. OpenClaw always responds to native platform mentions (e.g., Discord @-mentions, Telegram /commands directed at the bot username).

Multi-Channel Operation

A single OpenClaw instance can serve multiple channels simultaneously. Messages from different platforms flow into the same Gateway and share the same agent runtime, tools, memory, and skills.

Identity Linking

When the same person contacts OpenClaw from multiple platforms, use session.identityLinks to collapse those identities into a single canonical identity. This ensures conversation history, memory, and preferences follow the person rather than the channel.

{
  session: {
    identityLinks: [
      {
        canonical: "alice",
        peers: [
          { channel: "whatsapp", id: "+14155551234" },
          { channel: "telegram", id: "123456789" },
          { channel: "discord", id: "981234567890123456" },
        ]
      }
    ]
  }
}

All sessions from those peer IDs will resolve to the "alice" identity, sharing a unified conversation thread and memory store.

Session Scoping

Control how sessions are partitioned across channels using the session.scope setting:

Value	Behavior
"main" (default)	All DMs share a single session. Simple but means every conversation sees the same context.
"per-peer"	One session per unique sender, regardless of which channel they use. Combined with identity linking, this gives each person their own isolated context.
"per-channel-peer"	One session per channel-and-sender combination. Most isolated -- the same person on WhatsApp and Telegram gets two separate sessions.

For multi-channel setups serving multiple users, "per-peer" with identity linking is the recommended configuration.

Verifying Channel Health

After enabling channels, confirm connectivity:

# Quick status of all channels
openclaw channels status

# Deep probe that tests actual connectivity to each platform
openclaw channels status --probe

# Full system health check including channels
openclaw doctor

If a channel shows as disconnected, run openclaw doctor --fix to attempt automatic repair (re-authenticating expired sessions, restarting stalled bridges, etc.).

Platform-Specific Notes

WhatsApp -- Uses the unofficial Baileys library which reverse-engineers the WhatsApp Web protocol. Sessions can expire if the linked device is inactive for 14+ days. Re-scan the QR code if this happens. WhatsApp may rate-limit or ban accounts used for automation; use a dedicated phone number.

Telegram -- The most straightforward integration. The grammY library provides a stable, well-documented interface. Bot tokens never expire unless revoked. Supports inline keyboards, file uploads, and rich message formatting out of the box.

Discord -- Requires creating an application in the Discord Developer Portal, adding a bot user, and inviting it to servers with the appropriate permissions (Send Messages, Read Message History, and optionally Manage Messages). The bot token goes in DISCORD_BOT_TOKEN.

Slack -- Uses the Bolt framework with Socket Mode, which avoids the need for a public URL or ngrok tunnel. Create a Slack app at api.slack.com, enable Socket Mode, add bot scopes (chat:write, app_mentions:read, im:history, im:read, im:write), install to the workspace, and set both SLACK_BOT_TOKEN (xoxb-) and SLACK_APP_TOKEN (xapp-).

Signal -- Requires signal-cli installed separately and a phone number registered with Signal. Registration involves receiving an SMS or voice verification code. The most complex setup among the common platforms, but provides strong end-to-end encryption.

iMessage -- Requires a macOS machine running BlueBubbles server. BlueBubbles exposes the macOS Messages framework over a local HTTP API. The Mac must remain running and logged in. Not viable for headless Linux deployments.

Google Chat -- Requires a Google Workspace domain. Create a Chat app in the Google Admin console, configure the app URL to point at the Gateway (or use the OpenClaw Google Chat plugin), and authorize it for the workspace.

Teams -- Uses the @openclaw/msteams plugin. Requires registering an Azure AD application, configuring bot channels in the Azure Bot Service, and adding the app to Teams. The Azure app needs the TeamsActivity.Send and ChatMessage.Read permissions.

Matrix -- Uses the @openclaw/matrix plugin. Point it at any Matrix homeserver (Element, Synapse, Dendrite, Conduit) with an access token for a dedicated bot account. Supports end-to-end encrypted rooms when Pantalaimon or native crypto is enabled.

Troubleshooting Channels

Common issues across all channels:

Symptom	Likely Cause	Fix
Channel shows "disconnected"	Expired auth or network issue	Run openclaw doctor --fix or re-authenticate
Messages sent but no reply	Gateway not running	Check openclaw gateway status and restart if needed
Bot responds in DMs but not groups	Missing mention pattern or group policy	Add mentionPatterns and set groupPolicy: "open"
"Token invalid" errors	Stale or revoked token	Regenerate the token on the platform and update the env var
WhatsApp QR code not appearing	Port conflict or Baileys session corrupt	Delete ~/.openclaw/credentials/whatsapp/ and retry

For deeper platform-specific troubleshooting, consult the individual reference files linked above.