Implementation:Openclaw Openclaw ChannelsStatusCommand

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

Overview

Concrete command handler and snapshot builder for verifying channel connectivity and reporting health status, provided by the OpenClaw CLI.

Description

The channelsStatusCommand function in src/commands/channels/status.ts (lines 243-289) implements the openclaw channels status CLI command. It first attempts to reach the running gateway via the channels.status RPC call. If the gateway is reachable, it formats and displays the live status payload including connection states, probe results, and health warnings. If the gateway is unreachable, it falls back to config-only status by reading the config file and building account snapshots locally.

The buildChannelAccountSnapshot function in src/channels/plugins/status.ts (lines 5-36) constructs a ChannelAccountSnapshot for a single channel account. It resolves the account configuration from the plugin, then either delegates to the plugin's custom buildAccountSnapshot hook (if available) or falls back to a generic snapshot that reports enabled/disabled and configured/unconfigured status. This function is used both in the config-only fallback path and as the foundation for gateway-side status reporting.

Usage

The channelsStatusCommand is invoked by the CLI layer when the operator runs openclaw channels status. The buildChannelAccountSnapshot function is used internally by the status command and by the gateway's status endpoint to produce per-account status records.

Code Reference

Source Location

• Repository: openclaw
• File (command): src/commands/channels/status.ts
• Lines (channelsStatusCommand): 243-289
• File (snapshot builder): src/channels/plugins/status.ts
• Lines (buildChannelAccountSnapshot): 5-36

Signature (channelsStatusCommand)

export async function channelsStatusCommand(
  opts: ChannelsStatusOptions,
  runtime: RuntimeEnv = defaultRuntime,
): Promise<void>

Signature (buildChannelAccountSnapshot)

export async function buildChannelAccountSnapshot<ResolvedAccount>(params: {
  plugin: ChannelPlugin<ResolvedAccount>;
  cfg: OpenClawConfig;
  accountId: string;
  runtime?: ChannelAccountSnapshot;
  probe?: unknown;
  audit?: unknown;
}): Promise<ChannelAccountSnapshot>

Supporting Types

export type ChannelsStatusOptions = {
  json?: boolean;
  probe?: boolean;
  timeout?: string;
};

export type ChannelAccountSnapshot = {
  accountId: string;
  name?: string;
  enabled?: boolean;
  configured?: boolean;
  linked?: boolean;
  running?: boolean;
  connected?: boolean;
  reconnectAttempts?: number;
  lastConnectedAt?: number | null;
  lastInboundAt?: number | null;
  lastOutboundAt?: number | null;
  lastError?: string | null;
  // ... additional runtime fields
};

Import

import { channelsStatusCommand, type ChannelsStatusOptions } from "./commands/channels/status.js";
import { buildChannelAccountSnapshot } from "./channels/plugins/status.js";

I/O Contract

Inputs (channelsStatusCommand)

Name	Type	Required	Description
opts	ChannelsStatusOptions	Yes	CLI flags: json for machine output, probe for live probing, timeout for RPC timeout
runtime	RuntimeEnv	No	Runtime environment for logging/exit; defaults to defaultRuntime

Inputs (buildChannelAccountSnapshot)

Name	Type	Required	Description
plugin	ChannelPlugin<ResolvedAccount>	Yes	Channel plugin instance with config and status adapters
cfg	OpenClawConfig	Yes	Current gateway configuration
accountId	string	Yes	Account identifier to build the snapshot for
runtime	ChannelAccountSnapshot	No	Runtime overlay data from the gateway (connection state, timestamps)
probe	unknown	No	Probe result data from active health checks
audit	unknown	No	Audit result data from configuration audits

Outputs

Name	Type	Description
channelsStatusCommand	Promise<void>	Logs formatted status lines to stdout; falls back to config-only on gateway error
buildChannelAccountSnapshot	Promise<ChannelAccountSnapshot>	Snapshot record with enabled, configured, connected, and runtime fields

Usage Examples

Basic Status Check

await channelsStatusCommand({}, runtime);
// Output:
// Gateway reachable.
// - telegram (default): enabled, configured, connected, in:2m, out:5m, bot:@my_bot
// - discord (default): enabled, configured, connected, in:1m, out:3m

JSON Output for Monitoring

await channelsStatusCommand({ json: true }, runtime);
// Outputs full JSON payload to stdout

Probe Mode

await channelsStatusCommand({ probe: true }, runtime);
// Output includes "works" or "probe failed" per account

Building a Snapshot Directly

import { getChannelPlugin } from "./channels/plugins/index.js";

const plugin = getChannelPlugin("telegram");
const snapshot = await buildChannelAccountSnapshot({
  plugin,
  cfg,
  accountId: "default",
});
// snapshot.enabled === true
// snapshot.configured === true

Related Pages

Implements Principle

• Principle:Openclaw_Openclaw_Channel_Health_Verification

Uses Heuristic

• Heuristic:Openclaw_Openclaw_Cache_TTL_Asymmetric_Strategy