30.1 健康检查

生成模型：Claude Opus 4.6 (anthropic/claude-opus-4-6) Token 消耗：输入 ~250k tokens，输出 ~5k tokens（本节）

---

健康检查是生产环境中不可或缺的基础设施——它让运维人员和自动化系统能够判断 Gateway 是否正常运行。OpenClaw 提供了多层次的健康检查机制：Gateway 探针（WebSocket 级别）、健康 RPC 方法（应用级别）和状态快照（系统级别）。

30.1.1 Gateway 探针（Probe）

probeGateway()（src/gateway/probe.ts，126 行）是 OpenClaw 最全面的健康检查工具。它不是简单的 TCP 端口检测，而是通过 WebSocket 建立一个完整的客户端连接，然后请求多项数据：

// src/gateway/probe.ts（简化）
export async function probeGateway(opts: {
  url: string;
  auth?: { token?: string; password?: string };
  timeoutMs: number;
}): Promise<GatewayProbeResult> {
  const client = new GatewayClient({
    url: opts.url,
    mode: "probe",           // 特殊的探针模式
    onHelloOk: async () => {
      // 握手成功后，并行请求四项数据
      const [health, status, presence, configSnapshot] = await Promise.all([
        client.request("health"),
        client.request("status"),
        client.request("system-presence"),
        client.request("config.get", {}),
      ]);
      // 返回结构化结果
    },
  });
  client.start();
}

返回的 GatewayProbeResult 包含：

字段	类型	含义
ok	boolean	整体是否健康
url	string	探测的 Gateway URL
connectLatencyMs	number	WebSocket 连接延迟（毫秒）
error	string | null	错误信息
close	{code, reason}	WebSocket 关闭码和原因
health	HealthSummary	频道和代理的健康摘要
status	object	Gateway 运行状态
presence	SystemPresence[]	在线设备列表
configSnapshot	object	当前配置快照

探针模式（mode: "probe"）是 Gateway 客户端的特殊连接模式——它只进行只读查询，不会被计入活跃客户端计数，也不会触发聊天或命令执行。

30.1.2 健康 RPC 方法

Gateway 暴露了 health 和 status 两个 RPC 方法，可以通过 WebSocket 调用：

// src/gateway/server-methods/health.ts
export const healthHandlers: GatewayRequestHandlers = {
  health: async ({ respond, context, params }) => {
    const wantsProbe = params?.probe === true;
    const cached = context.getHealthCache();
    
    // 如果缓存有效且不要求主动探测，返回缓存
    if (!wantsProbe && cached && now - cached.ts < HEALTH_REFRESH_INTERVAL_MS) {
      respond(true, cached, undefined, { cached: true });
      // 后台异步刷新缓存
      void context.refreshHealthSnapshot({ probe: false });
      return;
    }
    
    // 否则同步刷新并返回
    const snap = await context.refreshHealthSnapshot({ probe: wantsProbe });
    respond(true, snap, undefined);
  },
  
  status: async ({ respond }) => {
    const status = await getStatusSummary();
    respond(true, status, undefined);
  },
};

健康缓存策略

健康检查涉及对多个频道（如 Telegram、Discord）的探测，可能耗时数秒。为了避免频繁查询影响性能，Gateway 实现了两层缓存：

1. 内存缓存：healthCache 变量保存最新的 HealthSummary，带有时间戳和版本号

2. 后台刷新：当返回缓存结果时，同时在后台触发异步刷新——用户看到的是即时响应，同时缓存在后台静默更新

refreshGatewayHealthSnapshot() 使用 Promise 去重——如果已有刷新正在进行，新的刷新请求会等待同一个 Promise 完成，避免并发重复探测：

// src/gateway/server/health-state.ts
export async function refreshGatewayHealthSnapshot(opts?: { probe?: boolean }) {
  if (!healthRefresh) {
    healthRefresh = (async () => {
      const snap = await getHealthSnapshot({ probe: opts?.probe });
      healthCache = snap;
      healthVersion += 1;
      broadcastHealthUpdate?.(snap);    // 通知所有连接的客户端
      return snap;
    })().finally(() => { healthRefresh = null; });
  }
  return healthRefresh;  // 多个请求共享同一个 Promise
}

30.1.3 健康摘要结构

getHealthSnapshot()（src/commands/health.ts，788 行）生成全面的 HealthSummary，包含：

频道健康

对每个已配置的频道（Telegram、Discord、WhatsApp 等），检查：

• 是否已配置：API 密钥/凭证是否存在

• 是否已链接：OAuth 令牌是否有效

• 探测结果：主动调用频道 API 验证连通性

• Bot 信息：bot 用户名、webhook URL

代理健康

对每个配置的 Agent：

• 心跳状态：HeartbeatSummary（间隔时间、上次运行时间）

• 会话统计：会话数量、最近活跃的会话列表

会话健康

• 会话存储路径

• 会话总数

• 最近 5 个活跃会话（键名、更新时间、活跃时长）

30.1.4 状态快照

buildGatewaySnapshot()（src/gateway/server/health-state.ts）在 Gateway 启动时和客户端首次连接时生成初始状态快照：

export function buildGatewaySnapshot(): Snapshot {
  const cfg = loadConfig();
  return {
    presence: listSystemPresence(),          // 在线设备
    health: {},                               // 占位，异步填充
    stateVersion: {
      presence: presenceVersion,              // Presence 变更计数器
      health: healthVersion,                  // 健康数据变更计数器
    },
    uptimeMs: Math.round(process.uptime() * 1000),  // Gateway 运行时间
    configPath: CONFIG_PATH,                  // 实际配置文件路径
    stateDir: STATE_DIR,                      // 状态目录路径
    sessionDefaults: {
      defaultAgentId,                         // 默认代理 ID
      mainKey,                                // 主会话键
      mainSessionKey,                         // 主会话标识
      scope,                                  // 会话作用域模式
    },
  };
}

状态版本号（presenceVersion 和 healthVersion）是单调递增的计数器，客户端可以通过比较版本号判断是否需要刷新本地缓存——这比轮询完整数据更高效。

30.1.5 心跳广播

Gateway 定期向所有已连接的客户端广播心跳事件，包含最新的健康和 Presence 数据。当健康状态发生变化时，broadcastHealthUpdate() 也会触发实时推送：

Gateway ──heartbeat─→ [所有客户端]
         {health, presence, stateVersion}

Gateway ──health.update─→ [所有客户端]  （健康变更时）
         {HealthSummary}

这种推送模式确保了 Web 控制台和原生应用能实时反映 Gateway 的健康状态，无需客户端主动轮询。

---

本节小结

1. Gateway 探针是最全面的健康检查——它建立完整 WebSocket 连接，并行请求健康、状态、Presence 和配置四项数据，适用于外部监控和 CLI 诊断。

2. 健康 RPC 方法支持缓存 + 后台刷新的双层策略——缓存有效时立即返回，同时异步更新；Promise 去重避免并发探测。

3. 健康摘要覆盖频道（探测 + 配置）、代理（心跳 + 会话）和系统（运行时间 + 版本）三个维度。

4. 状态版本号是高效的缓存失效机制——单调递增计数器让客户端只需比较数字即可判断是否需要刷新。

5. 心跳广播将健康数据主动推送到所有客户端，实现实时状态同步。