Principle:Openclaw Openclaw Channel Setup
| Knowledge Sources | |
|---|---|
| Domains | Configuration, Channels, Onboarding |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Channel setup is the process of discovering available messaging platforms, collecting per-channel credentials and preferences through interactive prompts, and persisting the resulting channel configuration into the gateway config file.
Description
A multi-channel AI gateway must connect to diverse messaging platforms -- WhatsApp, Telegram, Discord, Slack, Signal, iMessage, and extensible plugin channels like Microsoft Teams, Matrix, and Zalo. Each platform has its own authentication model (bot tokens, API keys, phone numbers, OAuth flows), its own set of optional features (DM policies, allowlists, multi-account support), and its own onboarding adapter that knows how to collect and validate the required credentials.
The channel setup concept addresses the challenge of presenting this heterogeneous landscape to the user in a unified, approachable way. Rather than requiring the user to manually edit a config file with platform-specific keys, the setup flow enumerates all available channels (both built-in and extension plugins), displays their current status (configured, disabled, not configured, plugin not installed), and lets the user interactively select which channels to configure. For each selected channel, the appropriate onboarding adapter takes over, prompting for the specific credentials and settings that channel requires.
The design supports multiple operational modes. In QuickStart mode, the user selects a single channel and the setup applies sensible defaults (such as automatically enabling allowFrom for channels that support it). In Advanced mode, the user can configure multiple channels in a loop, modify already-configured channels, disable or delete channel accounts, and fine-tune DM access policies. The setup also handles plugin channels: if the user selects a channel provided by an extension that is not yet installed, the setup offers to install the plugin on-the-fly before proceeding with configuration.
Usage
Apply this pattern when:
- A gateway or bot framework supports multiple messaging backends that share a common config structure.
- Each backend has unique credential requirements that cannot be expressed in a single generic form.
- The user needs to see which channels are already configured and which are available.
- Plugin-based extensibility means the set of available channels is not fixed at compile time.
Theoretical Basis
The channel setup uses an adapter pattern layered on an iterative selection loop:
1. Collect status for all channels:
- For each installed channel plugin, query its onboarding adapter
- For each catalog entry (not installed), mark as "install plugin to enable"
- Build a Map<ChannelId, ChannelOnboardingStatus>
2. Display channel status summary
3. Selection loop (Advanced mode) or single select (QuickStart mode):
a. Present channel list with status hints
b. User selects a channel (or "Finished"/"Skip")
c. If channel is a catalog plugin -> install plugin, reload registry
d. If channel is a bundled plugin not enabled -> enable in config
e. If channel is already configured -> prompt: modify / disable / delete / skip
f. If channel is not configured -> delegate to adapter.configure()
g. Record account ID, refresh status, loop back to (a)
4. Post-selection:
- Display selected channel summary
- Optionally prompt DM access policies (pairing, allowlist, open, disabled)
- Return updated config
Key design decisions:
- Adapter pattern: Each channel provides a ChannelOnboardingAdapter with getStatus and configure methods. This keeps channel-specific logic encapsulated and allows plugins to contribute their own onboarding flows.
- Status-first display: Before asking the user to choose, the setup shows the current state of every channel. This reduces confusion and helps users understand what needs attention.
- Plugin-on-demand installation: Extension channels listed in the catalog but not installed can be installed inline without leaving the wizard. After installation, the plugin registry is reloaded so the new adapter is immediately available.
- DM policy as a cross-cutting concern: DM access policies (pairing, allowlist, open) are configured after channel selection rather than per-channel, because the concepts are shared across all channels even though the config keys differ.