<!-- source: https://deepwiki.com/openclaw/openclaw/4.1-channel-architecture -->

# Channel Architecture

- extensions/discord/src/mentions.test.ts
- extensions/discord/src/mentions.ts
- extensions/discord/src/monitor/message-handler.draft-preview.ts
- extensions/discord/src/monitor/message-handler.process.test.ts
- extensions/discord/src/monitor/message-handler.process.ts
- extensions/mattermost/src/channel.test.ts
- extensions/mattermost/src/channel.ts
- extensions/mattermost/src/mattermost/send.test.ts
- extensions/mattermost/src/mattermost/send.ts
- extensions/msteams/src/reply-stream-controller.ts
- src/agents/runtime-plan/types.ts
- src/agents/tools/message-tool.test.ts
- src/agents/tools/message-tool.ts
- src/auto-reply/reply-payload.ts
- src/auto-reply/reply/agent-runner-usage-line.test.ts
- src/auto-reply/reply/agent-runner-usage-line.ts
- src/auto-reply/reply/block-reply-coalescer.ts
- src/auto-reply/reply/block-reply-pipeline.test.ts
- src/auto-reply/reply/block-reply-pipeline.ts
- src/auto-reply/reply/reply-threading.ts
- src/channels/streaming.ts
- src/infra/outbound/message-action-param-keys.ts
- src/infra/outbound/message-action-params.test.ts
- src/infra/outbound/message-action-params.ts
- src/infra/outbound/message-action-runner.media.test.ts
- src/infra/outbound/message-action-runner.send-validation.test.ts
- src/infra/outbound/message-action-runner.ts
- src/infra/outbound/outbound-send-service.test.ts
- src/infra/outbound/outbound-send-service.ts
- src/plugin-sdk/channel-streaming.test.ts
- src/plugin-sdk/channel-streaming.ts
- src/plugin-sdk/reply-payload.test.ts
- src/plugin-sdk/reply-payload.ts

This page documents the unified channel architecture that enables OpenClaw to connect to multiple messaging platforms (Telegram, Discord, Slack, WhatsApp, Signal, iMessage, and others). It explains the multi-platform channel system, provider monitors, message normalization, and event processing patterns involved in handling inbound and outbound messaging.

OpenClaw treats messaging platforms as **Channels**, which are implemented as extensible plugins. Each channel is responsible for maintaining a live connection to its respective platform, normalizing its inbound events into a standard intermediate representation, managing multi-account configurations, enforcing security policies, and delivering outbound messages with proper session routing.

## Channel Plugin Architecture

OpenClaw channels follow a shared plugin architecture standard defined in the Plugin SDK. Each messaging platform implements the `ChannelPlugin` interface, furnishing hooks for setup, configuration, security policies, event routing, outbound delivery, and status monitoring.

### Channel Plugin Structure

The core abstraction is the `ChannelPlugin` interface. It is subdivided into several key components encapsulating domain-specific logic for each platform.

Title: Channel Plugin Component Model

```

```

- ChannelMeta : Metadata including channel id and label.
- Messaging : Provides target normalization, chat type inference, and session routing src/infra/outbound/message-action-runner.ts 88-90
- Outbound : Defines message chunking, media sending, and payload delivery respecting platform limits src/plugin-sdk/reply-payload.ts 187-195
- Actions : Exposes platform-specific capabilities (like polls or message pinning) as tools for the AI agent src/agents/tools/message-tool.ts 11-21

**Sources:**

- src/infra/outbound/message-action-runner.ts 88-90
- src/plugin-sdk/reply-payload.ts 187-195
- src/agents/tools/message-tool.ts 11-21

## Message Normalization and Tooling

Inbound messages from various platforms are normalized into a common format for processing by the agent runtime. Conversely, agents interact with channels through the `message` tool, which abstracts platform-specific APIs.

### The Message Tool ( message-tool.ts )

The `message` tool is the primary interface for agents to send messages, create polls, or interact with threads across any configured channel.

- Action Discovery : The tool determines what an agent can do on a specific platform by checking the plugin's action registry using listChannelSupportedActions src/agents/tools/message-tool.ts 51
- Target Normalization : Targets (phone numbers, user IDs, channel IDs) are normalized using resolveChannelTarget src/infra/outbound/message-action-runner.ts 90
- Multi-Channel Dispatch : Agents can broadcast messages across multiple channels simultaneously using the broadcast action src/infra/outbound/message-action-runner.ts 148-162

### Media and Attachments

Channel architecture handles complex media types by resolving local paths and remote URLs before delivery.

- SSRF Protection : Remote media fetching adheres to the ssrfPolicy configured in the gateway extensions/discord/src/monitor/message-handler.process.ts 201-208
- Sandbox Integration : When an agent generates a file in a sandbox, the system resolves the path using getAgentScopedMediaLocalRoots and normalizeSandboxMediaList before sending src/infra/outbound/message-action-runner.ts 35-63

**Sources:**

- src/agents/tools/message-tool.ts 51
- src/infra/outbound/message-action-runner.ts 35-162
- extensions/discord/src/monitor/message-handler.process.ts 201-208

## Message Flow and Delivery

The delivery pipeline handles the transformation of `ReplyPayload` objects into platform-specific API calls.

### Outbound Delivery Pipeline

1. Normalization : Payloads are normalized to handle text chunking and media attachment rules via normalizeOutboundReplyPayload src/plugin-sdk/reply-payload.ts 84-88
2. Chunking : Platforms have character limits. The sendPayloadWithChunkedTextAndMedia function splits long messages while preserving formatting src/plugin-sdk/reply-payload.ts 187-195
3. Action Execution : The executeSendAction service handles the final delivery to the resolved channel plugin src/infra/outbound/message-action-runner.ts 87

Title: Outbound Delivery Sequence

```

```

**Sources:**

- src/plugin-sdk/reply-payload.ts 84-195
- src/infra/outbound/message-action-runner.ts 87

## Progress Drafts and Streaming

To improve user experience during long-running tasks, OpenClaw supports **Progress Drafts** and **Live Previews**.

- Feedback Controllers : Channels use createStatusReactionController to manage "thinking" indicators or reactions extensions/discord/src/monitor/message-handler.process.ts 9-13
- Live Previews : The system can maintain a "live" message that updates as the agent progresses. Discord uses createDiscordDraftStream to manage this state extensions/discord/src/monitor/message-handler.draft-preview.ts 58-60
- Streaming Modes : Configuration allows switching between partial (streaming text), block (sending complete paragraphs), or progress (showing tool execution status) src/plugin-sdk/channel-streaming.test.ts 36-49
- Progress Rendering : formatChannelProgressDraftText generates the user-visible status text from internal tool events extensions/discord/src/monitor/message-handler.draft-preview.ts 103-107

**Sources:**

- extensions/discord/src/monitor/message-handler.process.ts 9-13
- extensions/discord/src/monitor/message-handler.draft-preview.ts 58-107
- src/plugin-sdk/channel-streaming.test.ts 36-49

## Channel Docking and Session Routing

Channel docking refers to how OpenClaw maintains a "reply route" for a session and switches between different delivery modes based on context.

### Session Interaction Mode

When an inbound message is received, the system determines how to route the reply.

- Bot Loop Protection : recordChannelBotPairLoopAndCheckSuppression prevents agents from endlessly replying to other bots extensions/discord/src/monitor/message-handler.process.ts 206-208
- Session Key Generation : Messages are associated with a session key (e.g., agent:main:discord:direct:123 ) used to load history and context src/infra/outbound/message-action-runner.ts 126
- Source Reply Routing : If sourceReplyDeliveryMode is set to message_tool_only , the agent must explicitly use the message tool to reply to the user, rather than the automatic reply pipeline src/infra/outbound/message-action-runner.ts 130
- Threading : resolveAndApplyOutboundThreadId ensures messages are grouped correctly in threads or replies src/infra/outbound/message-action-runner.ts 70-74

Title: Natural Language Space to Code Entity Space

```

```

**Sources:**

- extensions/discord/src/monitor/message-handler.process.ts 206-208
- src/infra/outbound/message-action-runner.ts 70-130
- extensions/discord/src/monitor/message-handler.draft-preview.ts 58-60
