Implementation:Openclaw Openclaw HealthCommand

Knowledge Sources	OpenClaw
Domains	Deployment, Docker
Last Updated	2026-02-06 12:00 GMT

Overview

Concrete tool for verifying deployment health provided by the healthCommand and getHealthSnapshot functions in the OpenClaw health module.

Description

The health module provides two primary functions. The getHealthSnapshot function runs inside the gateway process, collecting comprehensive health data: it loads the current configuration, resolves the agent order, builds session summaries for each agent, iterates over all channel plugins to probe their connectivity, and assembles a HealthSummary object with timing information.

The healthCommand function is the CLI entry point. It calls the running gateway via RPC (using callGateway with the "health" method), receives the HealthSummary, and renders it as either JSON output or formatted terminal lines. The terminal output includes color-coded channel status lines (ok, linked, configured, not configured, failed), agent information, heartbeat intervals, and session store details. In verbose mode, it also displays gateway connection details and per-account probe timings.

Usage

Use healthCommand via the CLI (openclaw health) to check deployment status. Use getHealthSnapshot programmatically when building health endpoints or monitoring integrations within the gateway process.

Code Reference

Source Location

Repository: openclaw
File: src/commands/health.ts
- getHealthSnapshot: lines 385-560
- healthCommand: lines 562-787

Signature

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

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

Types

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;
    }>;
  };
};

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

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

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

Import

import { healthCommand, getHealthSnapshot } from "../commands/health.js";
import type { HealthSummary, ChannelHealthSummary } from "../commands/health.js";

I/O Contract

Inputs

getHealthSnapshot:

Name	Type	Required	Description
params.timeoutMs	`number`	No	Maximum time in milliseconds for channel probes. Defaults to 10000. Capped at minimum 1000.
params.probe	`boolean`	No	Whether to execute channel probes. Defaults to `true`. Set to `false` to skip external API calls.

healthCommand:

Name	Type	Required	Description
opts.json	`boolean`	No	When `true`, outputs the full `HealthSummary` as JSON.
opts.timeoutMs	`number`	No	Timeout passed to the gateway RPC call.
opts.verbose	`boolean`	No	When `true`, displays detailed connection info, all agent summaries, and per-account probe timings.
opts.config	`OpenClawConfig`	No	Override config object. Defaults to `loadConfig()`.
runtime	`RuntimeEnv`	Yes	Runtime environment for logging output and process control.

Outputs

getHealthSnapshot:

Name	Type	Description
(return value)	`Promise<HealthSummary>`	Comprehensive health snapshot with channel probes, agent summaries, session data, and timing.

healthCommand:

Name	Type	Description
(return value)	`Promise<void>`	Resolves after rendering output. Calls `runtime.exit(1)` if a fatal error occurs.
(side effect)	Terminal output	Formatted health status lines or JSON written via `runtime.log`.

Usage Examples

Basic Usage

import { healthCommand, getHealthSnapshot } from "../commands/health.js";
import { defaultRuntime } from "../runtime.js";

// CLI health check (formatted terminal output)
await healthCommand({}, defaultRuntime);

// CLI health check with verbose probes
await healthCommand({ verbose: true }, defaultRuntime);

// JSON output for monitoring
await healthCommand({ json: true }, defaultRuntime);

// Programmatic health snapshot inside the gateway
const snapshot = await getHealthSnapshot({ probe: true, timeoutMs: 5000 });
console.log(`Gateway ok: ${snapshot.ok}, channels: ${snapshot.channelOrder.length}`);

Docker Health Check

# From Docker Compose
docker compose -f docker-compose.yml exec openclaw-gateway \
  node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

# JSON output for scripting
docker compose -f docker-compose.yml exec openclaw-gateway \
  node dist/index.js health --json --token "$OPENCLAW_GATEWAY_TOKEN"

# Render health check endpoint (configured in render.yaml)
# healthCheckPath: /health
curl https://openclaw.onrender.com/health

Related Pages

Implements Principle

Principle:Openclaw_Openclaw_Deployment_Health_Verification

Requires Environment

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment