Use this file to discover all available pages before exploring further.

Prometheus metrics

OpenClaw can expose diagnostics metrics through the bundled

text

diagnostics-prometheus

plugin. It listens to trusted internal diagnostics and renders a Prometheus text endpoint at:


text
GET /api/diagnostics/prometheus

Content type is

text

text/plain; version=0.0.4; charset=utf-8

, the standard Prometheus exposition format.

warning

The route uses Gateway authentication (operator scope). Do not expose it as a public unauthenticated `/metrics` endpoint. Scrape it through the same auth path you use for other operator APIs.

For traces, logs, OTLP push, and OpenTelemetry GenAI semantic attributes, see OpenTelemetry export.

Quick start

Enable the plugin

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


text
  <Tab title="CLI">
    ```bash}
    openclaw plugins enable diagnostics-prometheus
    ```
  </Tab>
</Tabs>

Restart the Gateway

The HTTP route is registered at plugin startup, so reload after enabling.

Scrape the protected route

Send the same gateway auth your operator clients use:


text
```bash}
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
```

Wire Prometheus

```yaml} # 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"] ```

note

`diagnostics.enabled: true` is required. Without it, the plugin still registers the HTTP route but no diagnostic events flow into the exporter, so the response is empty.

Metrics exported

Metric	Type	Labels
text `openclaw_run_completed_total`	counter	text `channel` , text `model` , text `outcome` , text `provider` , text `trigger`
text `openclaw_run_duration_seconds`	histogram	text `channel` , text `model` , text `outcome` , text `provider` , text `trigger`
text `openclaw_model_call_total`	counter	text `api` , text `error_category` , text `model` , text `outcome` , text `provider` , text `transport`
text `openclaw_model_call_duration_seconds`	histogram	text `api` , text `error_category` , text `model` , text `outcome` , text `provider` , text `transport`
text `openclaw_model_tokens_total`	counter	text `agent` , text `channel` , text `model` , text `provider` , text `token_type`
text `openclaw_gen_ai_client_token_usage`	histogram	text `model` , text `provider` , text `token_type`
text `openclaw_model_cost_usd_total`	counter	text `agent` , text `channel` , text `model` , text `provider`
text `openclaw_tool_execution_total`	counter	text `error_category` , text `outcome` , text `params_kind` , text `tool`
text `openclaw_tool_execution_duration_seconds`	histogram	text `error_category` , text `outcome` , text `params_kind` , text `tool`
text `openclaw_harness_run_total`	counter	text `channel` , text `error_category` , text `harness` , text `model` , text `outcome` , text `phase` , text `plugin` , text `provider`
text `openclaw_harness_run_duration_seconds`	histogram	text `channel` , text `error_category` , text `harness` , text `model` , text `outcome` , text `phase` , text `plugin` , text `provider`
text `openclaw_message_processed_total`	counter	text `channel` , text `outcome` , text `reason`
text `openclaw_message_processed_duration_seconds`	histogram	text `channel` , text `outcome` , text `reason`
text `openclaw_message_delivery_total`	counter	text `channel` , text `delivery_kind` , text `error_category` , text `outcome`
text `openclaw_message_delivery_duration_seconds`	histogram	text `channel` , text `delivery_kind` , text `error_category` , text `outcome`
text `openclaw_queue_lane_size`	gauge	text `lane`
text `openclaw_queue_lane_wait_seconds`	histogram	text `lane`
text `openclaw_session_state_total`	counter	text `reason` , text `state`
text `openclaw_session_queue_depth`	gauge	text `state`
text `openclaw_memory_bytes`	gauge	text `kind`
text `openclaw_memory_rss_bytes`	histogram	none
text `openclaw_memory_pressure_total`	counter	text `level` , text `reason`
text `openclaw_telemetry_exporter_total`	counter	text `exporter` , text `reason` , text `signal` , text `status`
text `openclaw_prometheus_series_dropped_total`	counter	none

Label policy

PromQL recipes


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

tip

Prefer `gen_ai_client_token_usage` for cross-provider dashboards: it follows the OpenTelemetry GenAI semantic conventions and is consistent with metrics from non-OpenClaw GenAI services.

Choosing between Prometheus and OpenTelemetry export

OpenClaw supports both surfaces independently. You can run either, both, or neither.

* **Pull** model: Prometheus scrapes `/api/diagnostics/prometheus`. * No external collector required. * Authenticated through normal Gateway auth. * Surface is metrics only (no traces or logs). * Best for stacks already standardized on Prometheus + Grafana. * **Push** model: OpenClaw sends OTLP/HTTP to a collector or OTLP-compatible backend. * Surface includes metrics, traces, and logs. * Bridges to Prometheus through an OpenTelemetry Collector (`prometheus` or `prometheusremotewrite` exporter) when you need both. * See [OpenTelemetry export](/gateway/opentelemetry) for the full catalog.

Troubleshooting

Diagnostics export — local diagnostics zip for support bundles
Health and readiness —
text
/healthz
and
text
/readyz
probes
Logging — file-based logging
OpenTelemetry export — OTLP push for traces, metrics, and logs

OpenClaw Docs