Implementation:Openclaw Openclaw SetupChannels

Knowledge Sources	OpenClaw
Domains	Configuration, Channels, Onboarding
Last Updated	2026-02-06 12:00 GMT

Overview

Concrete interactive channel configuration flow for the OpenClaw gateway, provided by the setupChannels function in src/commands/onboard-channels.ts.

Description

setupChannels is the main entry point for configuring messaging channels during onboarding or reconfiguration. It enumerates all available channels (core built-in channels, installed plugin channels, and catalog entries for installable plugins), collects their current configuration status, presents an interactive selection UI, and delegates to per-channel onboarding adapters to collect credentials and settings. The function supports both QuickStart mode (single channel, sensible defaults) and Advanced mode (multi-channel loop with modify/disable/delete options). It returns the updated OpenClawConfig with all channel changes applied.

Usage

Called by runOnboardingWizard during the onboarding flow, or directly by the openclaw channels add command for post-setup channel configuration. Requires a WizardPrompter for interactive input and a RuntimeEnv for output.

Code Reference

Source Location

• Repository: openclaw
• File: src/commands/onboard-channels.ts
• Lines: 287-675

Signature

export async function setupChannels(
  cfg: OpenClawConfig,
  runtime: RuntimeEnv,
  prompter: WizardPrompter,
  options?: SetupChannelsOptions,
): Promise<OpenClawConfig>

Import

import { setupChannels } from "../commands/onboard-channels.js";

I/O Contract

Inputs

Name	Type	Required	Description
cfg	OpenClawConfig	Yes	The current gateway configuration object. Channel settings will be merged into this.
runtime	RuntimeEnv	Yes	Provides log, error, and exit for output and process control.
prompter	WizardPrompter	Yes	Abstraction over terminal prompts (select, confirm, text, note).
options	SetupChannelsOptions	No	Controls behavior: skipConfirm (skip "Configure channels now?" prompt), quickstartDefaults (single-select mode), forceAllowFromChannels (auto-enable allowFrom for specified channels), skipDmPolicyPrompt, skipStatusNote, allowDisable (show disable/delete options), initialSelection (pre-select a channel), promptAccountIds (ask for account IDs), accountIds (preset account IDs), onSelection / onAccountId (callbacks).

Outputs

Name	Type	Description
(return)	Promise<OpenClawConfig>	The updated configuration object with all channel changes applied. The caller is responsible for writing this to disk.

Internal Flow

1. Status collection -- collectChannelStatus builds a Map<ChannelChoice, ChannelOnboardingStatus> by querying every onboarding adapter, plus fallback statuses for channels without adapters and catalog statuses for installable plugins.
2. Confirmation gate -- unless skipConfirm is set, prompts "Configure chat channels now?"
3. Channel primer -- displays a note explaining how channels work, DM security model (pairing by default), and a summary of each available channel.
4. Selection loop -- In quickstartDefaults mode, a single select prompt is shown. In advanced mode, a while(true) loop presents the channel list repeatedly until the user picks "Finished".
5. Channel handling -- For each selected channel:
   • If it is a catalog plugin: install it via ensureOnboardingPluginInstalled, reload the plugin registry.
   • If it is a bundled plugin not yet enabled: enable it via enablePluginInConfig.
   • If already configured: prompt modify / disable / delete / skip.
   • If not configured: delegate to adapter.configure() which collects channel-specific credentials.
6. Selection summary -- displays which channels were configured.
7. DM policy prompts -- unless skipDmPolicyPrompt, offers to configure DM access policies (pairing, allowlist, open, disabled) for each selected channel that has a dmPolicy adapter.

Usage Examples

Basic Usage

import { setupChannels } from "../commands/onboard-channels.js";

const updatedConfig = await setupChannels(
  currentConfig,
  defaultRuntime,
  clackPrompter,
);
await writeConfigFile(updatedConfig);

QuickStart Mode

import { setupChannels } from "../commands/onboard-channels.js";

const updatedConfig = await setupChannels(
  currentConfig,
  defaultRuntime,
  clackPrompter,
  {
    quickstartDefaults: true,
    skipConfirm: true,
    skipDmPolicyPrompt: true,
    forceAllowFromChannels: ["telegram", "discord"],
  },
);

Key Dependencies

Dependency	Purpose
@clack/prompts	Terminal UI for interactive prompts (via WizardPrompter)
src/channels/plugins/index.js	listChannelPlugins, getChannelPlugin for discovering installed channel plugins
src/channels/plugins/catalog.js	listChannelPluginCatalogEntries for discovering installable extension plugins
src/channels/registry.js	listChatChannels for enumerating core built-in channels
src/commands/onboarding/registry.js	getChannelOnboardingAdapter, listChannelOnboardingAdapters for per-channel setup logic
src/commands/onboarding/plugin-install.js	ensureOnboardingPluginInstalled for inline plugin installation
src/plugins/enable.js	enablePluginInConfig for enabling bundled plugins in the config

Related Pages

Implements Principle

• Principle:Openclaw_Openclaw_Channel_Setup