Skip to main content
OpenClaw 可以通过官方 diagnostics-prometheus 插件暴露诊断指标。它监听可信诊断，以及由调度器拥有并在内部标记的诊断事件（队列、内存和会话恢复信号），并在以下位置渲染 Prometheus 文本端点： 
GET /api/diagnostics/prometheus
内容类型为 text/plain; version=0.0.4; charset=utf-8，即标准 Prometheus 暴露格式。
该路由使用 Gateway 网关身份验证（操作员权限范围，可信操作员接口）。不要将它暴露为公开且未认证的 /metrics 端点。请通过你用于其他操作员 API 的相同认证路径抓取它。
有关追踪、日志、OTLP 推送和 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

抓取受保护路由

发送操作员客户端所用的相同 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；只有在严格受限的环境中才将它设为 false。如果它为 false，插件仍会注册 HTTP 路由，但不会有诊断事件流入导出器，因此响应为空。

​
导出的指标

指标类型标签
openclaw_run_completed_total计数器channel, model, outcome, provider, trigger
openclaw_run_duration_seconds直方图channel, model, outcome, provider, trigger
openclaw_model_call_total计数器api, error_category, model, outcome, provider, transport
openclaw_model_call_duration_seconds直方图api, error_category, model, outcome, provider, transport
openclaw_model_failover_total计数器from_model, from_provider, lane, reason, suspended, to_model, to_provider
openclaw_model_tokens_total计数器agent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usage直方图model, provider, token_type
openclaw_model_cost_usd_total计数器agent, channel, model, provider
openclaw_model_usage_duration_seconds直方图agent, channel, model, provider
openclaw_skill_used_total计数器activation, agent, skill, source
openclaw_tool_execution_total计数器error_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_duration_seconds直方图error_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_blocked_total计数器denied_reason, params_kind, tool, tool_owner, tool_source
openclaw_harness_run_total计数器channel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_seconds直方图channel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_webhook_received_total计数器channel, webhook
openclaw_webhook_error_total计数器channel, webhook
openclaw_webhook_duration_seconds直方图channel, webhook
openclaw_message_received_total计数器channel, source
openclaw_message_dispatch_started_total计数器channel, source
openclaw_message_dispatch_completed_total计数器channel, outcome, reason, source
openclaw_message_dispatch_duration_seconds直方图channel, outcome, reason, source
openclaw_message_processed_total计数器channel, outcome, reason
openclaw_message_processed_duration_seconds直方图channel, outcome, reason
openclaw_message_delivery_started_total计数器channel, delivery_kind
openclaw_message_delivery_total计数器channel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_seconds直方图channel, delivery_kind, error_category, outcome
openclaw_talk_event_total计数器brain, event_type, mode, provider, transport
openclaw_talk_event_duration_seconds直方图brain, event_type, mode, provider, transport
openclaw_talk_audio_bytes直方图brain, event_type, mode, provider, transport
openclaw_queue_lane_size仪表盘lane
openclaw_queue_lane_wait_seconds直方图lane
openclaw_session_state_total计数器reason, state
openclaw_session_queue_depth仪表盘state
openclaw_session_turn_created_total计数器agent, channel, trigger
openclaw_session_stuck_total计数器reason, state
openclaw_session_stuck_age_seconds直方图reason, state
openclaw_session_recovery_total计数器action, active_work_kind, state, status
openclaw_session_recovery_age_seconds直方图action, active_work_kind, state, status
openclaw_liveness_warning_total计数器reason
openclaw_liveness_sessions仪表盘state
openclaw_liveness_event_loop_delay_p99_seconds直方图reason
openclaw_liveness_event_loop_delay_max_seconds直方图reason
openclaw_liveness_event_loop_utilization_ratio直方图reason
openclaw_liveness_cpu_core_ratio直方图reason
openclaw_payload_large_total计数器action, channel, plugin, reason, surface
openclaw_payload_large_bytes直方图action, channel, plugin, reason, surface
openclaw_memory_bytes仪表盘kind
openclaw_memory_rss_bytes直方图无
openclaw_memory_pressure_total计数器level, reason
openclaw_telemetry_exporter_total计数器exporter, reason, signal, status
openclaw_prometheus_series_dropped_total计数器无
openclaw_diagnostic_async_queue_dropped_total计数器drop_class
openclaw_diagnostic_async_queue_length仪表盘无

​
标签策略

Prometheus 标签保持有界且低基数。导出器不会发出原始诊断标识符，例如 runId、sessionKey、sessionId、callId、toolCallId、消息 ID、聊天 ID 或提供商请求 ID。标签值会被脱敏，并且必须匹配 OpenClaw 的低基数字符策略。不符合该策略的值会根据指标替换为 unknown、other 或 none。看起来像限定范围的智能体会话键的标签也会被替换为 unknown。
导出器会将内存中保留的时间序列总数限制在 2048 个，涵盖计数器、仪表和直方图。超过该上限的新序列会被丢弃，并且 openclaw_prometheus_series_dropped_total 每次递增一。将此计数器视为上游某个属性正在泄漏高基数值的明确信号。导出器绝不会自动提高上限；如果它持续增长，请修复源头，而不是禁用上限。
  • 提示文本、响应文本、工具输入、工具输出、系统提示
  • Talk 转录、音频载荷、调用 ID、房间 ID、移交令牌、轮次 ID 和原始会话 ID
  • 原始提供商请求 ID（仅在适用时以有界哈希出现在 span 上，绝不会出现在指标上）
  • 会话键和会话 ID
  • 主机名、文件路径、密钥值

​
PromQL 配方

# Tokens per minute, split by provider
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# Spend (USD) over the last hour, by model
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# 95th percentile model run duration
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# Queue wait time SLO (95p under 2s)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Skill usage, split by bounded source
sum by (skill, source) (increase(openclaw_skill_used_total[24h]))

# Dropped Prometheus series (cardinality alarm)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
对于跨提供商仪表板，请优先使用 gen_ai_client_token_usage：它遵循 OpenTelemetry GenAI 语义约定，并且与非 OpenClaw GenAI 服务的指标保持一致。

​
在 Prometheus 和 OpenTelemetry 导出之间选择

OpenClaw 独立支持这两个接口。你可以运行其中任一者、两者都运行，或都不运行。
  • 拉取模型：Prometheus 抓取 /api/diagnostics/prometheus。
  • 不需要外部收集器。
  • 通过常规 Gateway 网关身份验证完成认证。
  • 接口仅包含指标（没有追踪或日志）。
  • 最适合已经标准化为 Prometheus + Grafana 的技术栈。

​
故障排查

  • 检查配置中的 diagnostics.enabled 未设置为 false（默认值为 true）。
  • 使用 openclaw plugins list --enabled 确认插件已启用并已加载。
  • 生成一些流量；计数器和直方图只有在至少一个事件之后才会发出行。
该端点需要 Gateway 网关操作员权限范围（auth: "gateway"，且 gatewayRuntimeScopeSurface: "trusted-operator"）。使用 Prometheus 用于其他任何 Gateway 网关操作员路由的同一令牌或密码。不存在公开的未认证模式。
某个新属性超过了 2048 个序列的上限。检查近期指标，查找意外的高基数标签，并在源头修复。导出器会有意丢弃新序列，而不是静默重写标签。
该插件仅在内存中保留状态。Gateway 网关重启后，计数器会重置为零，仪表会在下一次报告值时重新开始。使用 PromQL rate() 和 increase() 来干净地处理重置。

​
相关