Implementation:Openclaw Openclaw ChannelsAddCommand

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

Overview

Concrete command handler and configuration mutator for registering a messaging channel account in the OpenClaw gateway configuration, provided by the OpenClaw CLI.

Description

The channelsAddCommand function orchestrates the full channel registration flow. It reads the current config, resolves the target channel plugin, validates input, delegates to the plugin's applyAccountConfig hook via the applyChannelAccountConfig mutator, and writes the updated config to disk. It supports both an interactive wizard mode (when no CLI flags are provided) and a direct flag-based mode.

The applyChannelAccountConfig function in src/commands/channels/add-mutators.ts (lines 20-96) is the core mutation helper. It normalizes the account ID, looks up the channel plugin, constructs a ChannelSetupInput record from the raw parameters, and delegates to the plugin's applyAccountConfig setup hook. This function is pure in the sense that it takes a config and returns a new config without side effects.

Usage

Import and call channelsAddCommand to register a channel from the CLI layer. Use applyChannelAccountConfig directly when you need to produce a mutated config without writing it to disk (e.g., in tests or batch operations).

Code Reference

Source Location

• Repository: openclaw
• File (command): src/commands/channels/add.ts
• Lines (command): 79-277
• File (mutator): src/commands/channels/add-mutators.ts
• Lines (mutator): 20-96

Signature (channelsAddCommand)

export async function channelsAddCommand(
  opts: ChannelsAddOptions,
  runtime: RuntimeEnv = defaultRuntime,
  params?: { hasFlags?: boolean },
): Promise<void>

Signature (applyChannelAccountConfig)

export function applyChannelAccountConfig(params: {
  cfg: OpenClawConfig;
  channel: ChannelId;
  accountId: string;
  name?: string;
  token?: string;
  tokenFile?: string;
  botToken?: string;
  appToken?: string;
  signalNumber?: string;
  cliPath?: string;
  dbPath?: string;
  service?: "imessage" | "sms" | "auto";
  region?: string;
  authDir?: string;
  httpUrl?: string;
  httpHost?: string;
  httpPort?: string;
  webhookPath?: string;
  webhookUrl?: string;
  audienceType?: string;
  audience?: string;
  useEnv?: boolean;
  homeserver?: string;
  userId?: string;
  accessToken?: string;
  password?: string;
  deviceName?: string;
  initialSyncLimit?: number;
  ship?: string;
  url?: string;
  code?: string;
  groupChannels?: string[];
  dmAllowlist?: string[];
  autoDiscoverChannels?: boolean;
}): OpenClawConfig

Import

import { channelsAddCommand, type ChannelsAddOptions } from "./commands/channels/add.js";
import { applyChannelAccountConfig } from "./commands/channels/add-mutators.js";

I/O Contract

Inputs (channelsAddCommand)

Name	Type	Required	Description
opts	ChannelsAddOptions	Yes	CLI flags: channel name, account ID, credential values, policy overrides
runtime	RuntimeEnv	No	Runtime environment for logging/exit; defaults to defaultRuntime
params	{ hasFlags?: boolean }	No	Controls wizard vs. direct mode; wizard is used when hasFlags is falsy

Inputs (applyChannelAccountConfig)

Name	Type	Required	Description
cfg	OpenClawConfig	Yes	Current OpenClaw configuration object
channel	ChannelId	Yes	Normalized channel identifier (e.g., "telegram")
accountId	string	Yes	Account identifier, normalized via normalizeAccountId
(credentials)	various	No	Platform-specific fields: token, botToken, appToken, signalNumber, etc.

Outputs

Name	Type	Description
channelsAddCommand return	Promise<void>	Writes config and logs success; exits with code 1 on error
applyChannelAccountConfig return	OpenClawConfig	New config object with the channel account added or updated

Usage Examples

Registering a Slack Channel

await channelsAddCommand({
  channel: "slack",
  botToken: "xoxb-1234567890-abcdef",
  appToken: "xapp-1-A0123456789-1234567890123-abcdef",
  account: "workspace-bot",
  name: "Engineering Bot",
}, runtime, { hasFlags: true });

Mutating Config Directly

const updatedConfig = applyChannelAccountConfig({
  cfg: existingConfig,
  channel: "telegram",
  accountId: "default",
  botToken: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
  name: "My Bot",
});

Related Pages

Implements Principle

• Principle:Openclaw_Openclaw_Channel_Registration