Skip to main content
OpenClaw 可通过官方 diagnostics-prometheus 插件公开诊断指标。它会监听受信任的诊断事件以及核心发出的 gateway 稳定性事件，然后在以下地址渲染 Prometheus 文本端点： 
GET /api/diagnostics/prometheus
内容类型为 text/plain; version=0.0.4; charset=utf-8，这是标准的 Prometheus exposition 格式。
该路由使用 Gateway 身份验证（operator scope）。不要将其作为公开的、无需认证的 /metrics 端点暴露出去。请通过你用于其他 operator API 的同一认证路径来抓取它。
关于 traces、logs、OTLP push 以及 OpenTelemetry GenAI 语义属性，请参见 OpenTelemetry 导出。

​
快速开始

1

安装插件

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus
2

启用插件

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

重启 Gateway

HTTP 路由会在插件启动时注册，因此启用后请重新加载。
4

抓取受保护的路由

发送与你的 operator 客户端相同的 gateway 认证：
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

接入 Prometheus

# prometheus.yml
scrape_configs:
  - job_name: openclaw
    scrape_interval: 30s
    metrics_path: /api/diagnostics/prometheus
    authorization:
      credentials_file: /etc/prometheus/openclaw-gateway-token
    static_configs:
      - targets: ["openclaw-gateway:18789"]
diagnostics.enabled: true 是必需的。否则，插件仍会注册 HTTP 路由，但不会有诊断事件流入导出器，因此响应会为空。

​
导出的指标

MetricTypeLabels
openclaw_run_completed_totalcounterchannel, model, outcome, provider, trigger
openclaw_run_duration_secondshistogramchannel, model, outcome, provider, trigger
openclaw_model_call_totalcounterapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondshistogramapi, error_category, model, outcome, provider, transport
openclaw_model_failover_totalcounterfrom_model, from_provider, lane, reason, suspended, to_model, to_provider
openclaw_model_tokens_totalcounteragent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usagehistogrammodel, provider, token_type
openclaw_model_cost_usd_totalcounteragent, channel, model, provider
openclaw_skill_used_totalcounteractivation, agent, skill, source
openclaw_tool_execution_totalcountererror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_duration_secondshistogramerror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_blocked_totalcounterdenied_reason, params_kind, tool, tool_owner, tool_source
openclaw_harness_run_totalcounterchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondshistogramchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_webhook_received_totalcounterchannel, webhook
openclaw_webhook_error_totalcounterchannel, webhook
openclaw_webhook_duration_secondshistogramchannel, webhook
openclaw_message_received_totalcounterchannel, source
openclaw_message_dispatch_started_totalcounterchannel, source
openclaw_message_dispatch_completed_totalcounterchannel, outcome, reason, source
openclaw_message_dispatch_duration_secondshistogramchannel, outcome, reason, source
openclaw_message_processed_totalcounterchannel, outcome, reason
openclaw_message_processed_duration_secondshistogramchannel, outcome, reason
openclaw_message_delivery_started_totalcounterchannel, delivery_kind
openclaw_message_delivery_totalcounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_talk_event_totalcounterbrain, event_type, mode, provider, transport
openclaw_talk_event_duration_secondshistogrambrain, event_type, mode, provider, transport
openclaw_talk_audio_byteshistogrambrain, event_type, mode, provider, transport
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalcounterreason, state
openclaw_session_queue_depthgaugestate
openclaw_session_turn_created_totalcounteragent, channel, trigger
openclaw_session_stuck_totalcounterreason, state
openclaw_session_stuck_age_secondshistogramreason, state
openclaw_session_recovery_totalcounteraction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaction, active_work_kind, state, status
openclaw_liveness_warning_totalcounterreason
openclaw_liveness_sessionsgaugestate
openclaw_liveness_event_loop_delay_p99_secondshistogramreason
openclaw_liveness_event_loop_delay_max_secondshistogramreason
openclaw_liveness_event_loop_utilization_ratiohistogramreason
openclaw_liveness_cpu_core_ratiohistogramreason
openclaw_payload_large_totalcounteraction, channel, plugin, reason, surface
openclaw_payload_large_byteshistogramaction, channel, plugin, reason, surface
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramnone
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounternone

​
标签策略

Prometheus 标签会保持受限且低基数。导出器不会输出原始诊断标识符，例如 runId、sessionKey、sessionId、callId、toolCallId、消息 ID、聊天 ID 或提供方请求 ID。标签值会被脱敏，并且必须符合 OpenClaw 的低基数字符策略。不符合该策略的值会根据指标不同被替换为 unknown、other 或 none。看起来像带作用域的 agent session key 的标签也会被替换为 unknown。
导出器将内存中保留的时间序列总数上限设为 2048，该上限适用于计数器、仪表和直方图的总和。超过该上限的新系列会被丢弃，并且每发生一次，openclaw_prometheus_series_dropped_total 就会加一。请将这个计数器视为上游属性泄露高基数值的硬性信号。导出器不会自动取消该上限；如果它持续上升，应修复数据源，而不是禁用上限。
  • prompt 文本、response 文本、工具输入、工具输出、系统 prompt
  • Talk 转录、音频负载、call id、room id、handoff token、turn id 以及原始 session id
  • 原始提供方请求 ID（仅在适用时，span 上使用有界哈希，指标中绝不会出现）
  • session key 和 session ID
  • 主机名、文件路径、密钥值

​
PromQL 示例

# 按提供方拆分的每分钟 token 数
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# 最近一小时的支出（USD），按 model 统计
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# model run 时长的 95 分位数
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# 队列等待时间 SLO（95 分位低于 2s）
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Skill 使用量，按受限 source 拆分
sum by (skill, source) (increase(openclaw_skill_used_total[24h]))

# 丢弃的 Prometheus 系列（基数告警）
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
对于跨提供方仪表盘，优先使用 gen_ai_client_token_usage：它遵循 OpenTelemetry GenAI 语义约定，并且与非 OpenClaw GenAI 服务的指标保持一致。

​
在 Prometheus 和 OpenTelemetry 导出之间进行选择

OpenClaw 独立支持这两种方式。你可以运行其中一种、两种都运行，或者都不运行。
  • 拉取 模式：Prometheus 抓取 /api/diagnostics/prometheus。
  • 不需要外部 collector。
  • 通过正常的 Gateway auth 进行认证。
  • 该方式仅提供指标（不包含 traces 或 logs）。
  • 适合已经标准化为 Prometheus + Grafana 的技术栈。

​
故障排查

  • 检查配置中的 diagnostics.enabled: true。
  • 确认插件已启用并通过 openclaw plugins list --enabled 加载。
  • 生成一些流量；计数器和直方图只有在至少发生一次事件后才会输出行。
该端点要求 Gateway operator 范围（auth: "gateway" 且 gatewayRuntimeScopeSurface: "trusted-operator"）。请使用 Prometheus 访问任何其他 Gateway operator 路由时所用的同一 token 或密码。没有公开的、无需认证的模式。
某个新属性正在超过 2048 个 series 的上限。请检查最近的指标中是否有意外的高基数标签，并在源头修复。导出器会有意丢弃新 series，而不是悄悄重写标签。
插件只在内存中保留状态。Gateway 重启后，计数器会重置为零，而 gauge 会从其下次报告的值重新开始。请使用 PromQL 的 rate() 和 increase() 以正确处理重置。

​
相关