Channels#

OpenClaw connects your AI agents to external messaging surfaces through channel adapters. These adapters handle inbound events from apps such as Discord, Google Chat, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo, and others, plus outbound delivery back to those surfaces.

Each channel is implemented as a plugin. The Gateway loads channel plugins at startup and wires them into central routing, session management, and delivery.

How channels work#

Inbound messages arrive from provider SDKs (for example Baileys for WhatsApp or grammY for Telegram). The channel normalizes them into ChannelEnvelope and ChannelMessage shapes and passes them through channel-ingress into session binding and the agent runtime.

Outbound content from agents, tools, heartbeats, or cron jobs flows through a durable delivery queue. The channel's ChannelOutboundAdapter executes the actual send, supporting text, media, reply-to, thread IDs, and presentation blocks.

A shared message tool dispatches channel-specific actions (send, edit, react, poll, typing). Each channel plugin declares its supported actions through ChannelMessageActionAdapter.

Channel plugins#

Plugins declare their identity and ownership in an openclaw.plugin.json manifest:

{
  "id": "whatsapp",
  "kind": ["channel"],
  "channels": ["whatsapp"],
  "providers": ["baileys"]
}

Bundled plugins ship with OpenClaw. External plugins are installed from the catalog or npm. Use the CLI to manage them:

openclaw plugins install <spec>
openclaw plugins inspect <id>

See Plugin manifests and contracts and Plugin SDK for the full registration surface.

Configuration#

Channel settings live under the top-level channels key in ~/.openclaw/openclaw.json (or the path set by OPENCLAW_CONFIG_PATH). Common fields include:

enabled
Provider-specific credentials (bot tokens, session stores, etc.)
dmPolicy — pairing (default), allowlist, open, or disabled
allowFrom — explicit allowlist of sender identifiers
groupPolicy and groupAllowFrom
healthMonitor

Example:

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Validation uses bundled channel metadata schemas. Unknown keys or violations are rejected at startup. See Configuration for the complete schema and openclaw config schema for runtime introspection.

Pairing and access control#

DM policy defaults to pairing. Unknown senders receive a short code and the message is not processed until approved:

openclaw pairing approve <channel> <code>

Run openclaw doctor after changes or upgrades to surface risky DM policies (pairing/allowlist/open) or other misconfigurations.

Device and node pairing use separate flows and are covered in the nodes documentation.

Delivery and actions#

Outbound delivery is queued for durability and retried. Delivery is mirrored into session transcripts so that sent messages appear in history and agent context.

The shared message tool surfaces channel-specific actions based on the current account, thread, and sender trust level. Media parameters are declared via mediaSourceParams so the runtime can apply sandbox normalization.

Security considerations#

Treat all inbound DMs as untrusted input. Default policy requires explicit pairing or allowlisting. Group messages are mention-gated in many channels by default.

Use agents.defaults.sandbox for non-main sessions when processing untrusted group content. Before exposing the Gateway beyond loopback, review the full security model in Configuration and Secrets and auth.