Diagnostics Commands

Contents

Overview

Core Types

The health subsystem is built around a hierarchy of summary types. HealthSummary is the top-level envelope returned by the gateway, containing per-channel, per-agent, and session data. Each nested type carries its own probe and heartbeat metadata.

// src/commands/health.ts — ChannelAccountHealthSummary
export type ChannelAccountHealthSummary = {
  accountId: string;
  configured?: boolean;
  linked?: boolean;
  authAgeMs?: number | null;
  probe?: unknown;
  lastProbeAt?: number | null;
  [key: string]: unknown;
};

// src/commands/health.ts — ChannelHealthSummary
export type ChannelHealthSummary = ChannelAccountHealthSummary & {
  accounts?: Record<string, ChannelAccountHealthSummary>;
};

// src/commands/health.ts — AgentHealthSummary & top-level HealthSummary
export type AgentHealthSummary = {
  agentId: string;
  name?: string;
  isDefault: boolean;
  heartbeat: AgentHeartbeatSummary;
  sessions: HealthSummary["sessions"];
};

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

Decision Points

How It Works

The diagnostics subsystem has three independent but composable command paths: the health command for gateway-level probes, the status command for local runtime scanning, and the doctor flow for interactive repair. Each is designed to be invoked independently or chained in automated pipelines.

Health Command — Gateway Probing

The healthCommand function issues a single RPC call to the gateway's health method. When the --verbose flag is set, it passes { probe: true } to trigger live channel probes rather than returning cached status. The result is a complete HealthSummary snapshot.

// src/commands/health.ts — healthCommand
export async function healthCommand(
  opts: { json?: boolean; timeoutMs?: number; verbose?: boolean; config?: OpenClawConfig },
  runtime: RuntimeEnv,
) {
  const cfg = opts.config ?? runtime.config;
  const summary = await callGateway<HealthSummary>({
    method: "health",
    params: opts.verbose ? { probe: true } : undefined,
    timeoutMs: opts.timeoutMs,
    config: cfg,
  });

  if (opts.json) {
    runtime.stdout.write(JSON.stringify(summary, null, 2));
    return;
  }

  // Render human-readable channel table
  renderChannelTable(summary.channels, summary.channelOrder, summary.channelLabels, runtime);
  renderAgentTable(summary.agents, summary.defaultAgentId, runtime);
  renderSessionSummary(summary.sessions, runtime);
}

The companion getHealthSnapshot function provides a programmatic API for other subsystems (e.g. the doctor flow) that need a HealthSummary without CLI rendering:

// src/commands/health.ts — getHealthSnapshot
export async function getHealthSnapshot(
  params?: { timeoutMs?: number; probe?: boolean },
): Promise<HealthSummary> {
  return callGateway<HealthSummary>({
    method: "health",
    params: params?.probe ? { probe: true } : undefined,
    timeoutMs: params?.timeoutMs,
  });
}

Status Command — Runtime Scanning

The statusCommand extends health data with local runtime introspection. It scans session directories, checks process states, and optionally gathers usage statistics. The --deep flag activates the full scan pipeline including status.scan.runtime.ts and status.scan.fast-json.ts.

// src/commands/status.command.ts — statusCommand
export async function statusCommand(
  opts: {
    json?: boolean;
    deep?: boolean;
    usage?: boolean;
    timeoutMs?: number;
    verbose?: boolean;
    all?: boolean;
  },
  runtime: RuntimeEnv,
) {
  const health = await getHealthSnapshot({
    timeoutMs: opts.timeoutMs,
    probe: opts.verbose,
  });

  const scanResult = opts.deep
    ? await deepScan(runtime)
    : await fastScan(runtime);

  const summary = buildStatusSummary(health, scanResult, {
    includeUsage: opts.usage,
    includeAll: opts.all,
  });

  if (opts.json) {
    runtime.stdout.write(JSON.stringify(summary, null, 2));
    return;
  }

  renderStatusReport(summary, runtime);
}

Doctor Flow — Interactive Repair

The doctor flow is the most complex diagnostic path. It combines health probing, config validation, and interactive repair into a single guided workflow. The flow is orchestrated by createDoctorPrompter which presents issues and repair options through a terminal UI.

flowchart TD
  START["doctor command invoked"]
  UPDATE{"maybeOfferUpdateBeforeDoctor()"}
  MIGRATE["loadAndMaybeMigrateDoctorConfig()"]
  HEALTH["getHealthSnapshot(probe: true)"]
  INSTALL["noteSourceInstallIssues()"]
  STARTUP["noteStartupOptimizationHints()"]
  ALLOWLIST["Check allowlist policies"]
  ISSUES{"Issues found?"}
  PROMPT["createDoctorPrompter — display issues"]
  REPAIR["Apply selected repairs"]
  VERIFY["Re-run health check"]
  DONE["Report summary"]

  START --> UPDATE
  UPDATE -->|"Outdated"| DONE
  UPDATE -->|"Current"| MIGRATE
  MIGRATE --> HEALTH
  HEALTH --> INSTALL
  INSTALL --> STARTUP
  STARTUP --> ALLOWLIST
  ALLOWLIST --> ISSUES
  ISSUES -->|"No"| DONE
  ISSUES -->|"Yes"| PROMPT
  PROMPT --> REPAIR
  REPAIR --> VERIFY
  VERIFY --> DONE

The doctor flow runs six sequential diagnostic stages. First, it checks whether the binary itself is outdated. Then it migrates any legacy config schemas. The health snapshot is taken with full probing enabled. Installation issues (missing binaries, incorrect permissions) and startup optimization hints (unnecessary env vars, slow plugin loads) are noted. Finally, allowlist policies are validated against the current channel configuration.

Code Walkthrough

Doctor Command Repair Sequence

The following diagram shows the interaction between the doctor command, the health gateway, and the local repair subsystem during a typical repair session:

sequenceDiagram
    participant Operator
    participant Doctor as doctor flow
    participant Config as config loader
    participant Gateway as health gateway
    participant Repair as repair subsystem
    participant FS as file system

    Operator->>Doctor: openclaw doctor
    Doctor->>Config: loadAndMaybeMigrateDoctorConfig()
    Config->>FS: read config files
    FS-->>Config: raw config
    Config-->>Doctor: migrated config

    Doctor->>Gateway: getHealthSnapshot(probe: true)
    Gateway-->>Doctor: HealthSummary

    Doctor->>Doctor: noteSourceInstallIssues()
    Doctor->>Doctor: noteStartupOptimizationHints()
    Doctor->>Doctor: check allowlist policies

    Doctor-->>Operator: display issues list

    Operator->>Doctor: select repairs
    Doctor->>Repair: apply selected repairs
    Repair->>FS: atomic config writes
    FS-->>Repair: write confirmation
    Repair-->>Doctor: repair results

    Doctor->>Gateway: getHealthSnapshot(probe: true)
    Gateway-->>Doctor: updated HealthSummary
    Doctor-->>Operator: final report

Edge Cases

Configuration

Doctor Shared Modules

The src/commands/doctor/shared/ directory contains 25+ utility modules that the doctor flow delegates to for specific repair tasks. These are intentionally decoupled so they can be unit-tested in isolation.

Related Topics

Source Files

src/
├── commands/
│   ├── health.ts                        ← healthCommand(), getHealthSnapshot(), HealthSummary types
│   ├── status.command.ts                ← statusCommand() entry point
│   ├── status.scan.ts                   ← Core scan orchestration
│   ├── status.scan.fast-json.ts         ← Streaming JSON session parser
│   ├── status.scan.runtime.ts           ← Local runtime file scanner
│   ├── status.summary.ts               ← buildStatusSummary() aggregation
│   ├── doctor/
│   │   └── shared/
│   │       ├── allowlist-policy-repair.ts
│   │       ├── exec-safe-bins.ts
│   │       ├── mutable-allowlist.ts
│   │       └── empty-allowlist-policy.ts  (25 files total)
│   └── gateway-status/
│       ├── discovery.ts                 ← Gateway endpoint resolution
│       ├── helpers.ts                   ← Response normalization
│       ├── output.ts                    ← Status rendering
│       └── probe-run.ts                ← Individual probe execution
└── flows/
    └── doctor-health.ts                 ← Doctor flow orchestration