Zum Hauptinhalt springen
OpenClaw kann Diagnosemetriken über das offizielle diagnostics-prometheus-Plugin bereitstellen. Es lauscht auf vertrauenswürdige Diagnosen sowie vom Core ausgegebene Gateway-Stabilitätsereignisse und stellt dann einen Prometheus-Textendpunkt unter folgender Adresse bereit: 
GET /api/diagnostics/prometheus
Der Inhaltstyp ist text/plain; version=0.0.4; charset=utf-8, das standardmäßige Prometheus-Expositionsformat.
Die Route verwendet Gateway-Authentifizierung (Operator-Scope). Stellen Sie sie nicht als öffentlichen, nicht authentifizierten /metrics-Endpunkt bereit. Scrapen Sie sie über denselben Authentifizierungspfad, den Sie auch für andere Operator-APIs verwenden.
Für Traces, Logs, OTLP-Push und semantische OpenTelemetry-GenAI-Attribute siehe OpenTelemetry-Export.

​
Schnellstart

1

Plugin installieren

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

Plugin aktivieren

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

Gateway neu starten

Die HTTP-Route wird beim Start des Plugins registriert; laden Sie daher nach der Aktivierung neu.
4

Geschützte Route scrapen

Senden Sie dieselbe Gateway-Authentifizierung, die Ihre Operator-Clients verwenden:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

Wire 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 ist erforderlich. Ohne diese Einstellung registriert das Plugin weiterhin die HTTP-Route, aber es fließen keine Diagnoseereignisse in den Exporter, sodass die Antwort leer ist.

​
Exportierte Metriken

MetrikTypLabels
openclaw_run_completed_totalCounterchannel, model, outcome, provider, trigger
openclaw_run_duration_secondsHistogrammchannel, model, outcome, provider, trigger
openclaw_model_call_totalCounterapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondsHistogrammapi, 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_usageHistogrammmodel, 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_secondsHistogrammerror_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_secondsHistogrammchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_webhook_received_totalCounterchannel, webhook
openclaw_webhook_error_totalCounterchannel, webhook
openclaw_webhook_duration_secondsHistogrammchannel, webhook
openclaw_message_received_totalCounterchannel, source
openclaw_message_dispatch_started_totalCounterchannel, source
openclaw_message_dispatch_completed_totalCounterchannel, outcome, reason, source
openclaw_message_dispatch_duration_secondsHistogrammchannel, outcome, reason, source
openclaw_message_processed_totalCounterchannel, outcome, reason
openclaw_message_processed_duration_secondsHistogrammchannel, outcome, reason
openclaw_message_delivery_started_totalCounterchannel, delivery_kind
openclaw_message_delivery_totalCounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondsHistogrammchannel, delivery_kind, error_category, outcome
openclaw_talk_event_totalCounterbrain, event_type, mode, provider, transport
openclaw_talk_event_duration_secondsHistogrammbrain, event_type, mode, provider, transport
openclaw_talk_audio_bytesHistogrammbrain, event_type, mode, provider, transport
openclaw_queue_lane_sizeGaugelane
openclaw_queue_lane_wait_secondsHistogrammlane
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_secondsHistogrammreason, state
openclaw_session_recovery_totalCounteraction, active_work_kind, state, status
openclaw_session_recovery_age_secondsHistogrammaction, active_work_kind, state, status
openclaw_liveness_warning_totalCounterreason
openclaw_liveness_sessionsGaugestate
openclaw_liveness_event_loop_delay_p99_secondsHistogrammreason
openclaw_liveness_event_loop_delay_max_secondsHistogrammreason
openclaw_liveness_event_loop_utilization_ratioHistogrammreason
openclaw_liveness_cpu_core_ratioHistogrammreason
openclaw_payload_large_totalCounteraction, channel, plugin, reason, surface
openclaw_payload_large_bytesHistogrammaction, channel, plugin, reason, surface
openclaw_memory_bytesGaugekind
openclaw_memory_rss_bytesHistogrammkeine
openclaw_memory_pressure_totalCounterlevel, reason
openclaw_telemetry_exporter_totalCounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalCounterkeine

​
Label-Richtlinie

Prometheus-Labels bleiben begrenzt und haben eine niedrige Kardinalität. Der Exporter gibt keine rohen Diagnosekennungen wie runId, sessionKey, sessionId, callId, toolCallId, Nachrichten-IDs, Chat-IDs oder Provider-Anfrage-IDs aus.Labelwerte werden redigiert und müssen der OpenClaw-Zeichenrichtlinie für niedrige Kardinalität entsprechen. Werte, die die Richtlinie nicht erfüllen, werden je nach Metrik durch unknown, other oder none ersetzt. Labels, die wie bereichsbezogene Agent-Sitzungsschlüssel aussehen, werden ebenfalls durch unknown ersetzt.
Der Exporter begrenzt die im Arbeitsspeicher vorgehaltenen Zeitreihen auf insgesamt 2048 Reihen über Counter, Gauges und Histogramme hinweg. Neue Reihen oberhalb dieser Grenze werden verworfen, und openclaw_prometheus_series_dropped_total wird jedes Mal um eins erhöht.Beobachten Sie diesen Counter als eindeutiges Signal dafür, dass ein vorgelagertes Attribut Werte mit hoher Kardinalität weitergibt. Der Exporter hebt die Grenze nie automatisch an; wenn sie erreicht wird, beheben Sie die Quelle, statt die Begrenzung zu deaktivieren.
  • Prompt-Text, Antworttext, Tool-Eingaben, Tool-Ausgaben, System-Prompts
  • Talk-Transkripte, Audio-Payloads, Call-IDs, Raum-IDs, Handoff-Tokens, Turn-IDs und rohe Session-IDs
  • rohe Provider-Request-IDs (nur begrenzte Hashes, sofern zutreffend, auf Spans — niemals auf Metriken)
  • Session-Schlüssel und Session-IDs
  • Hostnamen, Dateipfade, geheime Werte

​
PromQL-Rezepte

# 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
Bevorzugen Sie gen_ai_client_token_usage für Provider-übergreifende Dashboards: Es folgt den semantischen OpenTelemetry-GenAI-Konventionen und ist konsistent mit Metriken von GenAI-Diensten außerhalb von OpenClaw.

​
Auswahl zwischen Prometheus- und OpenTelemetry-Export

OpenClaw unterstützt beide Oberflächen unabhängig voneinander. Sie können eine davon, beide oder keine ausführen.
  • Pull-Modell: Prometheus ruft /api/diagnostics/prometheus ab.
  • Kein externer Collector erforderlich.
  • Authentifiziert über die normale Gateway-Authentifizierung.
  • Die Oberfläche umfasst nur Metriken (keine Traces oder Logs).
  • Am besten für Stacks geeignet, die bereits auf Prometheus + Grafana standardisiert sind.

​
Fehlerbehebung

  • Prüfen Sie diagnostics.enabled: true in der Konfiguration.
  • Bestätigen Sie mit openclaw plugins list --enabled, dass das Plugin aktiviert und geladen ist.
  • Erzeugen Sie etwas Traffic; Counter und Histogramme geben erst nach mindestens einem Ereignis Zeilen aus.
Der Endpunkt erfordert den Gateway-Operator-Scope (auth: "gateway" mit gatewayRuntimeScopeSurface: "trusted-operator"). Verwenden Sie dasselbe Token oder Passwort, das Prometheus für jede andere Gateway-Operator-Route verwendet. Es gibt keinen öffentlichen nicht authentifizierten Modus.
Ein neues Attribut überschreitet die Obergrenze von 2048 Serien. Prüfen Sie aktuelle Metriken auf ein Label mit unerwartet hoher Kardinalität und beheben Sie es an der Quelle. Der Exporter verwirft neue Serien absichtlich, statt Labels stillschweigend umzuschreiben.
Das Plugin hält den Zustand nur im Arbeitsspeicher. Nach einem Gateway-Neustart werden Counter auf null zurückgesetzt, und Gauges starten wieder mit ihrem nächsten gemeldeten Wert. Verwenden Sie PromQL rate() und increase(), um Zurücksetzungen sauber zu behandeln.

​
Verwandte Themen