Pular para o conteúdo principal
O OpenClaw pode expor métricas de diagnóstico por meio do plugin oficial diagnostics-prometheus. Ele escuta diagnósticos confiáveis e eventos de estabilidade do Gateway emitidos pelo núcleo, depois renderiza um endpoint de texto do Prometheus em: 
GET /api/diagnostics/prometheus
O tipo de conteúdo é text/plain; version=0.0.4; charset=utf-8, o formato de exposição padrão do Prometheus.
A rota usa autenticação do Gateway (escopo de operador). Não a exponha como um endpoint público /metrics sem autenticação. Colete-a pelo mesmo caminho de autenticação que você usa para outras APIs de operador.
Para traces, logs, envio por OTLP e atributos semânticos GenAI do OpenTelemetry, consulte Exportação do OpenTelemetry.

​
Início rápido

1

Instale o plugin

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

Habilite o plugin

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

Reinicie o Gateway

A rota HTTP é registrada na inicialização do plugin, então recarregue após habilitá-lo.
4

Colete a rota protegida

Envie a mesma autenticação do Gateway que seus clientes operadores usam:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

Conectar o 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 é obrigatório. Sem isso, o plugin ainda registra a rota HTTP, mas nenhum evento de diagnóstico flui para o exportador, então a resposta fica vazia.

​
Métricas exportadas

MétricaTipoRótulos
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_byteshistogramnenhum
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounternenhum

​
Política de rótulos

Os rótulos do Prometheus permanecem delimitados e com baixa cardinalidade. O exportador não emite identificadores brutos de diagnóstico, como runId, sessionKey, sessionId, callId, toolCallId, IDs de mensagens, IDs de chats ou IDs de solicitação de provedores.Os valores dos rótulos são redigidos e devem corresponder à política de caracteres de baixa cardinalidade do OpenClaw. Valores que não passam na política são substituídos por unknown, other ou none, dependendo da métrica. Rótulos que parecem chaves de sessão de agente com escopo também são substituídos por unknown.
O exportador limita as séries temporais mantidas na memória a 2048 séries no total entre contadores, medidores e histogramas. Novas séries além desse limite são descartadas, e openclaw_prometheus_series_dropped_total é incrementado em um a cada vez.Monitore esse contador como um sinal forte de que um atributo upstream está vazando valores de alta cardinalidade. O exportador nunca aumenta o limite automaticamente; se ele subir, corrija a origem em vez de desabilitar o limite.
  • texto de prompt, texto de resposta, entradas de ferramentas, saídas de ferramentas, prompts de sistema
  • transcrições de conversa, payloads de áudio, IDs de chamadas, IDs de sala, tokens de transferência, IDs de turno e IDs de sessão brutos
  • IDs de solicitação brutos do provedor (apenas hashes limitados, quando aplicável, em spans — nunca em métricas)
  • chaves de sessão e IDs de sessão
  • nomes de host, caminhos de arquivos, valores secretos

​
Receitas de 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
Prefira gen_ai_client_token_usage para painéis entre provedores: ela segue as convenções semânticas GenAI do OpenTelemetry e é consistente com métricas de serviços GenAI que não são do OpenClaw.

​
Como escolher entre exportação Prometheus e OpenTelemetry

O OpenClaw oferece suporte às duas superfícies de forma independente. Você pode executar uma delas, as duas ou nenhuma.
  • Modelo pull: o Prometheus faz scrape de /api/diagnostics/prometheus.
  • Nenhum coletor externo é necessário.
  • Autenticado pela autenticação normal do Gateway.
  • A superfície é apenas de métricas (sem traces nem logs).
  • Melhor para stacks já padronizadas em Prometheus + Grafana.

​
Solução de problemas

  • Verifique diagnostics.enabled: true na configuração.
  • Confirme que o Plugin está habilitado e carregado com openclaw plugins list --enabled.
  • Gere algum tráfego; contadores e histogramas só emitem linhas após pelo menos um evento.
O endpoint exige o escopo de operador do Gateway (auth: "gateway" com gatewayRuntimeScopeSurface: "trusted-operator"). Use o mesmo token ou senha que o Prometheus usa para qualquer outra rota de operador do Gateway. Não há modo público não autenticado.
Um novo atributo está excedendo o limite de 2048 séries. Inspecione as métricas recentes em busca de um rótulo com cardinalidade inesperadamente alta e corrija-o na origem. O exportador descarta intencionalmente novas séries em vez de reescrever rótulos silenciosamente.
O Plugin mantém estado apenas em memória. Após uma reinicialização do Gateway, os contadores voltam a zero e os gauges reiniciam no próximo valor relatado. Use rate() e increase() do PromQL para lidar com resets de forma limpa.

​
Relacionado