Implementation:Openclaw Openclaw HealthCommand And ProbeGateway

HealthCommand And ProbeGateway

This page documents the implementation of Health Monitoring in the OpenClaw gateway. It covers three primary functions: healthCommand for CLI-facing health output, getHealthSnapshot for assembling the aggregate health data structure, and probeGateway for WebSocket-level gateway connectivity probing.

Source Locations

Function	File	Lines
healthCommand	src/commands/health.ts	L562-787
getHealthSnapshot	src/commands/health.ts	L385-560
probeGateway	src/gateway/probe.ts	L36-125

healthCommand

Signature

export async function healthCommand(
  opts: { json?: boolean; timeoutMs?: number; verbose?: boolean; config?: OpenClawConfig },
  runtime: RuntimeEnv,
): Promise<void>

Purpose

healthCommand is the CLI entry point for the openclaw health command. It queries the running gateway over RPC for a health snapshot and renders the result to the terminal.

Parameters

Parameter	Type	Description
opts.json	boolean (optional)	When true, output the raw health snapshot as formatted JSON instead of styled text.
opts.timeoutMs	number (optional)	Timeout in milliseconds for the gateway RPC call.
opts.verbose	boolean (optional)	When true, include gateway connection details and probe all accounts (not just the default).
opts.config	OpenClawConfig (optional)	Override configuration; defaults to loadConfig().
runtime	RuntimeEnv	Runtime environment providing log, error, and exit methods.

Behavior

1. Calls callGateway with method "health", wrapped in a progress spinner (suppressed in JSON mode).
2. If opts.json is true, serializes the entire HealthSummary to JSON and logs it.
3. Otherwise, formats styled text output:
   • In verbose mode, prints gateway connection details.
   • Resolves the ordered list of agents and their channel account bindings.
   • Calls formatHealthChannelLines to produce per-channel status lines (e.g., "Telegram: ok (@mybot) (142ms)").
   • Applies ANSI color styling via styleHealthChannelLine (green for "ok"/"linked", yellow for "not linked", red for "failed").
   • Prints agent list, heartbeat intervals, and session store information.
4. Gateway reachability defines success. Channel-level failures are reported but do not cause a non-zero exit code.

Return Value

Returns Promise<void>. Exits the process with code 1 only if a fatal error occurs (currently the fatal flag is always false).

getHealthSnapshot

Signature

export async function getHealthSnapshot(params?: {
  timeoutMs?: number;
  probe?: boolean;
}): Promise<HealthSummary>

Purpose

getHealthSnapshot assembles a complete HealthSummary by iterating over all registered channel plugins, probing their accounts, and collecting agent/session metadata. This function runs inside the gateway process itself (called via the "health" RPC handler).

Parameters

Parameter	Type	Description
params.timeoutMs	number (optional)	Maximum time for each channel probe. Capped to a minimum of 1000ms; defaults to 10000ms.
params.probe	boolean (optional)	When explicitly false, skips channel probing and only returns configuration/link status. Defaults to true.

Behavior

1. Loads configuration and resolves the ordered list of agents (with default agent first).
2. Iterates over all channel plugins from listChannelPlugins().
3. For each plugin, resolves account IDs (default, bound, and all configured accounts) and deduplicates them.
4. For each account:
   • Checks if the account is enabled and configured via the plugin's config.isEnabled and config.isConfigured methods.
   • If enabled, configured, and probing is active, calls plugin.status.probeAccount with the configured timeout.
   • On probe failure, captures the error as { ok: false, error: message }.
   • Delegates to plugin.status.buildChannelSummary if available for channel-specific summary fields (e.g., linked status, auth age).
5. Builds the top-level HealthSummary with ok: true, timestamp, duration, channel map, agent summaries, and session statistics.

Return Value: HealthSummary

export type HealthSummary = {
  ok: true;
  ts: number;
  durationMs: number;
  channels: Record<string, ChannelHealthSummary>;
  channelOrder: string[];
  channelLabels: Record<string, string>;
  heartbeatSeconds: number;
  defaultAgentId: string;
  agents: AgentHealthSummary[];
  sessions: {
    path: string;
    count: number;
    recent: Array<{ key: string; updatedAt: number | null; age: number | null }>;
  };
};

The ok field is always true because the snapshot's existence implies gateway reachability.

probeGateway

Signature

export async function probeGateway(opts: {
  url: string;
  auth?: GatewayProbeAuth;
  timeoutMs: number;
}): Promise<GatewayProbeResult>

Purpose

probeGateway performs a full WebSocket handshake with the gateway, authenticates, and issues RPC requests for health, status, system presence, and configuration. It is used by the deeper diagnostic tools (e.g., openclaw channels status --probe) to verify end-to-end connectivity.

Parameters

Parameter	Type	Description
opts.url	string	WebSocket URL of the gateway (e.g., ws://localhost:18789).
opts.auth	GatewayProbeAuth (optional)	Authentication credentials: either a token or a password.
opts.timeoutMs	number	Maximum time to wait for the entire probe sequence. Minimum enforced: 250ms.

Behavior

1. Creates a GatewayClient instance in PROBE mode with a random instance ID.
2. Starts the WebSocket connection and sets a timeout timer.
3. On successful handshake (onHelloOk), records connect latency and fires four parallel RPC requests:
   • health -- the gateway health snapshot.
   • status -- operational status.
   • system-presence -- active system presences.
   • config.get -- current running configuration.
4. Settles the promise with ok: true and all collected data, or ok: false with the error details.
5. On timeout, settles with ok: false and includes any connect error that occurred.
6. Always stops the client and clears the timer on settlement.

Return Value: GatewayProbeResult

export type GatewayProbeResult = {
  ok: boolean;
  url: string;
  connectLatencyMs: number | null;
  error: string | null;
  close: GatewayProbeClose | null;
  health: unknown;
  status: unknown;
  presence: SystemPresence[] | null;
  configSnapshot: unknown;
};

Supporting Types

export type ChannelAccountHealthSummary = {
  accountId: string;
  configured?: boolean;
  linked?: boolean;
  authAgeMs?: number | null;
  probe?: unknown;
  lastProbeAt?: number | null;
  [key: string]: unknown;
};

export type ChannelHealthSummary = ChannelAccountHealthSummary & {
  accounts?: Record<string, ChannelAccountHealthSummary>;
};

export type AgentHealthSummary = {
  agentId: string;
  name?: string;
  isDefault: boolean;
  heartbeat: AgentHeartbeatSummary;
  sessions: HealthSummary["sessions"];
};

export type GatewayProbeAuth = {
  token?: string;
  password?: string;
};

export type GatewayProbeClose = {
  code: number;
  reason: string;
  hint?: string;
};

Dependencies

Module	Purpose
src/gateway/call.ts	callGateway and buildGatewayConnectionDetails for RPC communication.
src/gateway/client.ts	GatewayClient WebSocket client used by probeGateway.
src/channels/plugins/index.ts	listChannelPlugins and getChannelPlugin for channel iteration.
src/routing/bindings.ts	buildChannelAccountBindings for resolving agent-to-account mappings.
src/config/sessions.ts	loadSessionStore and resolveStorePath for session statistics.
src/cli/progress.ts	withProgress for the spinner UI during health checks.

Principle:Openclaw_Openclaw_Health_Monitoring

Related Pages

Requires Environment

• Environment:Openclaw_Openclaw_Gateway_Network_Ports