Prometheus 指标

OpenClaw 可以通过官方的 OpenClawdiagnostics-prometheus 插件暴露诊断指标。它会监听受信任的内部诊断信息，并在以下位置渲染 Prometheus 文本端点：

GET /api/diagnostics/prometheus

内容类型为 text/plain; version=0.0.4; charset=utf-8，这是标准的 Prometheus 暴露格式。

有关跟踪、日志、OTLP 推送和 OpenTelemetry GenAI 语义属性，请参阅 OpenTelemetry 导出。

快速开始

安装插件

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus

启用插件

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

openclaw plugins enable diagnostics-prometheus

Gateway(网关)重启 Gateway（网关）
HTTP 路由在插件启动时注册，因此在启用后请重新加载。
抓取受保护的路由
发送与您的操作员客户端使用的相同的 Gateway（网关）身份验证：
Terminal window
```
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
```

连接 Prometheus

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"]

导出的指标

指标	类型	标签
`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_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_tool_execution_total`	计数器	`error_category`，`outcome`，`params_kind`，`tool`
`openclaw_tool_execution_duration_seconds`	直方图	`error_category`，`outcome`，`params_kind`，`tool`
`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_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`	counter	`channel`， `delivery_kind`， `error_category`， `outcome`
`openclaw_message_delivery_duration_seconds`	histogram	`channel`， `delivery_kind`， `error_category`， `outcome`
`openclaw_talk_event_total`	counter	`brain`， `event_type`， `mode`， `provider`， `transport`
`openclaw_talk_event_duration_seconds`	histogram	`brain`， `event_type`， `mode`， `provider`， `transport`
`openclaw_talk_audio_bytes`	histogram	`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`	gauge	`state`
`openclaw_session_recovery_total`	计数器	`action`， `active_work_kind`， `state`， `status`
`openclaw_session_recovery_age_seconds`	histogram	`action`， `active_work_kind`， `state`， `status`
`openclaw_memory_bytes`	gauge	`kind`
`openclaw_memory_rss_bytes`	直方图	无
`openclaw_memory_pressure_total`	计数器	`level`， `reason`
`openclaw_telemetry_exporter_total`	计数器	`exporter`， `reason`， `signal`， `status`
`openclaw_prometheus_series_dropped_total`	计数器	无

标签策略

有界的、低基数的标签

Prometheus 标签保持有界且低基数。导出器不会发出原始诊断标识符，如 runId、sessionKey、sessionId、callId、toolCallId、消息 ID、聊天 ID 或提供商请求 ID。

标签值会被编辑，且必须符合 OpenClaw 的低基数字符策略。不符合策略的值将被替换为 unknown、other 或 none，具体取决于指标。

序列上限与溢出统计

导出器将在内存中保留的时间序列上限设为 2048 个，涵盖计数器、仪表和直方图。超出此上限的新序列将被丢弃，并且 openclaw_prometheus_series_dropped_total 每次都会加一。

请密切关注此计数器，将其视为上游属性正在泄露高基数值的强烈信号。导出器永远不会自动取消上限；如果该计数器上升，请修复源头而不是禁用上限。

Prometheus 输出中绝不会出现的内容

提示文本、响应文本、工具输入、工具输出、系统提示
对话记录、音频负载、呼叫 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

# Dropped Prometheus series (cardinality alarm)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0

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

OpenClaw 独立支持这两种接口。您可以运行其中一种、两者都运行，或都不运行。

Pull 模型：Prometheus 抓取 /api/diagnostics/prometheus。
不需要外部收集器。
通过常规 Gateway(网关) 身份验证进行认证。
接口仅包含指标（不包含跟踪或日志）。
最适合已标准化使用 Prometheus + Grafana 的技术栈。

Push 模型：OpenClaw 将 OTLP/HTTP 发送到收集器或兼容 OTLP 的后端。
接口包括指标、跟踪和日志。
当您同时需要两者时，可通过 OpenTelemetry Collector（prometheus 或 prometheusremotewrite 导出器）桥接到 Prometheus。
有关完整目录，请参阅 OpenTelemetry 导出。

故障排除

Empty response body

检查配置中的 diagnostics.enabled: true。
确认插件已启用并使用 openclaw plugins list --enabled 加载。
生成一些流量；计数器和直方图仅在至少发生一次事件后才输出行。

401 / unauthorized

该端点需要 Gateway(网关) 操作员范围（auth: "gateway" 配合 gatewayRuntimeScopeSurface: "trusted-operator"）。使用 Prometheus 用于任何其他 Gateway(网关) 操作员路由的相同令牌或密码。没有公共的未经身份验证的模式。

`openclaw_prometheus_series_dropped_total` 正在攀升

一个新属性超过了 2048 序列的限制。检查最近的指标，查找基数意外过高的标签，并在源头进行修复。导出器会有意丢弃新序列，而不是静默地重写标签。

Prometheus 在重启后显示过时序列

该插件仅在内存中保留状态。在 Gateway(网关) 重启后，计数器将重置为零，仪表（gauge）将在下一次报告的值处重新开始。使用 PromQL rate() 和 increase() 来干净地处理重置。