OpenClaw Prometheus 监控接入

背景 链接到标题

OpenClaw 是日常使用的 AI 网关，接入飞书通道提供 AI 助手服务。之前监控体系只有节点级的 CPU/内存/磁盘告警，缺少网关本身的可观测性——不知道模型调用失败率、token 消耗趋势、会话是否异常恢复、任务队列是否堆积。

已有的监控基础设施：Prometheus + Alertmanager 部署在内网服务器，alert-transformer 负责将告警格式化后通过 OpenClaw 推送到飞书。这次要做的是把 OpenClaw 自身的指标接入同一套体系。

安装插件 链接到标题

OpenClaw 官方提供了 diagnostics-prometheus 插件，通过 ClawHub 安装：

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus

不过有版本兼容性问题：最新版插件要求的 pluginApi >= 2026.6.11，而部署的 OpenClaw 运行时是 2026.6.6，直接装最新版会报安装失败。查看 npm 历史版本后，锁定 2026.6.6 版本安装：

openclaw plugins install @openclaw/diagnostics-prometheus@2026.6.6

配置 链接到标题

openclaw.json 需要做三个改动：

• diagnostics.enabled: true — 启用诊断事件流，插件依赖此开关
• plugins.allow 加入 "diagnostics-prometheus" — 显式允许加载
• plugins.entries 加入 "diagnostics-prometheus": { "enabled": true }

{
  "diagnostics": {
    "enabled": true
  },
  "plugins": {
    "allow": ["diagnostics-prometheus"],
    "entries": {
      "diagnostics-prometheus": { "enabled": true }
    }
  }
}

插件注册的指标端点位于：

GET /api/diagnostics/prometheus

需要 Gateway auth token 认证（operator scope），不接受未认证访问。

Prometheus 采集配置 链接到标题

在 Prometheus 的 scrape_configs 中新增 job，指向 Gateway 的指标端点：

- job_name: openclaw-gateway
  metrics_path: /api/diagnostics/prometheus
  scrape_interval: 30s
  scrape_timeout: 10s
  scheme: http
  authorization:
    type: Bearer
    credentials_file: /etc/prometheus/openclaw_token
  static_configs:
    - targets:
        - '部署节点IP:18789'
      labels:
        hostname: openclaw-node

token 写入文件后重启 Prometheus 即可看到 target 上线。

指标概览 链接到标题

插件暴露以下几类指标，全部以 openclaw_ 为前缀：

模型与运行时

• openclaw_run_completed_total — run 完成计数（含 outcome 标签区分成功/失败）
• openclaw_model_call_total — 模型调用次数（含 error_category 用于诊断）
• openclaw_model_tokens_total — token 消耗，按 token_type 区分 input/output
• openclaw_model_cost_usd_total — 累计费用
• openclaw_model_failover_total — 模型 failover 事件

消息流转

• openclaw_message_received_total / openclaw_message_processed_total — 消息收/发/处理
• openclaw_message_dispatch_duration_seconds — 调度延迟分布

技能与工具

• openclaw_skill_used_total — 技能调用次数
• openclaw_tool_execution_total / openclaw_tool_execution_blocked_total — 工具执行/被拦截

队列与会话

• openclaw_queue_lane_size — 队列当前深度（gauge）
• openclaw_session_state_total — 会话状态变更事件
• openclaw_session_recovery_total — 会话恢复次数（不稳定信号）

系统资源

• openclaw_memory_bytes — 进程内存（按 kind 区分 rss/heap/external）
• openclaw_liveness_event_loop_delay_p99_seconds — 事件循环延迟 P99
• openclaw_liveness_cpu_core_ratio — CPU 使用率

Prometheus 专属

• openclaw_prometheus_series_dropped_total — 因基数超限被丢弃的时间序列数，用于监控标签是否泄露了高基数属性

对应的 PromQL 比 node-exporter 的通用指标更有业务针对性，比如：

# 每分钟 token 消耗
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# 近一小时费用
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# 队列等待 P95
histogram_quantile(0.95, sum by(le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m])))

告警规则 链接到标题

基于上述指标定义了 7 条告警规则，覆盖可用性、性能、资源、稳定性四个维度：

告警通知链路 链接到标题

告警流转路径：

Prometheus 规则评估 → Alertmanager → alert-transformer → OpenClaw → 飞书

alert-transformer 是一个自建的轻量服务，负责将 Alertmanager webhook 的 JSON 格式化为自然语言消息，再通过 OpenClaw hook API 发送到指定飞书会话。这样告警可以直接出现在日常使用的飞书中，不需要额外打开 Grafana 或 Alertmanager UI。

踩坑记录 链接到标题

1. 插件版本不匹配：diagnostics-prometheus 最新版要求 pluginApi >= 2026.6.11，运行时版本过旧则安装失败。回退到 @openclaw/diagnostics-prometheus@2026.6.6 解决。建议安装前先 openclaw --version 确认 API 版本。

2. 指标初始为空：刚配置完时 GET /api/diagnostics/prometheus 返回只有 2 行元数据，因为 counter/histogram 需要在有事件发生后才会注册。发几条消息触发 run 和 model call 后指标才开始出现。

3. Credentials 文件权限：Prometheus 容器内读取 credentials_file，需要确保容器内用户（nobody）可读该文件，并且路径在容器 volume 挂载范围内。

效果 链接到标题

配置完成后，Prometheus 可以正常采集 OpenClaw 指标，告警规则在模拟故障时正确触发并通过飞书送达。后续可以围绕模型 failover 频率、缓存命中率、消息端到端延迟等业务维度补充 Grafana 面板。