Como Monitorar o Desempenho do Agente OpenClaw

Um agente OpenClaw em execução não é um sistema do tipo "configure e esqueça". Skills quebram, chaves de API expiram, conversas falham silenciosamente e os custos de tokens aumentam aos poucos. O monitoramento adequado detecta esses problemas antes que afetem sua experiência. Este guia cobre todos os aspectos do monitoramento do OpenClaw.

Monitoramento Integrado

openclaw status

A verificação de saúde mais rápida:

openclaw status

# Output:
# OpenClaw v0.9.6
# Status:        running
# Uptime:        14d 3h 22m
# Model:         claude-sonnet-4-20250514
# Memory DB:     82 MB (1,234 entries)
# Active channels: telegram (connected), email (connected)
# Skills:        12 installed, 12 healthy
# Cron jobs:     5 active, 0 paused
# Last message:  2 minutes ago
# CPU:           3.2%
# Memory:        312 MB

openclaw logs

Streaming de logs em tempo real:

# Follow all logs
openclaw logs -f

# Filter by component
openclaw logs --filter "channel" --since 1h
openclaw logs --filter "skill" --since 1h
openclaw logs --filter "error" --since 24h
openclaw logs --filter "llm" --since 1h

# Show only errors and warnings
openclaw logs --level warn --since 24h

openclaw doctor

Uma verificação diagnóstica abrangente:

openclaw doctor

# Output:
# [PASS] Node.js version: 20.11.0
# [PASS] OpenClaw version: 0.9.6 (latest)
# [PASS] Database: healthy, 82 MB
# [PASS] Anthropic API: connected, key valid
# [PASS] Telegram channel: connected
# [WARN] Email channel: webhook URL returns 404
# [PASS] Skills: 12/12 healthy
# [PASS] Cron: service running, 5 jobs active
# [PASS] Disk space: 12 GB free (60% available)
# [WARN] Memory usage: 312 MB (approaching 512 MB limit)
#
# 2 warnings found. Run `openclaw doctor --fix` to attempt auto-repair.

Métricas Principais para Acompanhar

1. Tempo de Resposta

Quanto tempo leva desde o recebimento de uma mensagem até o envio de uma resposta?

openclaw metrics response-time --period 24h

# Output:
# Average:  4.2s
# P50:      3.1s
# P90:      8.4s
# P99:      15.2s
# Min:      1.8s
# Max:      22.1s

O que observar:

• Média > 10s: Considere um modelo mais rápido ou verifique a latência de rede
• P99 > 30s: Algo está intermitentemente errado (rate limiting, timeout)
• Tendência crescente: Janela de contexto crescendo, inchaço de memória

2. Taxa de Sucesso

Qual porcentagem de mensagens recebe uma resposta bem-sucedida?

openclaw metrics success-rate --period 7d

# Output:
# Total messages:  342
# Successful:      331 (96.8%)
# Failed:          11 (3.2%)
#
# Failure breakdown:
#   API rate limit:    5
#   Skill error:       3
#   Timeout:           2
#   Parse error:       1

Meta: taxa de sucesso de 95%+. Abaixo de 90% indica um problema sistêmico.

3. Uso de Tokens

Acompanhe o consumo diário de tokens para gerenciar custos:

openclaw metrics tokens --period 30d --daily

# Output:
# Date        Input Tokens  Output Tokens  Total     Cost
# 2026-04-05  45,230        12,340         57,570    $0.22
# 2026-04-04  52,100        15,890         67,990    $0.26
# 2026-04-03  38,900        10,200         49,100    $0.19
# ...
# Monthly:    1,234,567     345,678        1,580,245 $6.04

4. Saúde das Skills

Monitore quais skills estão tendo sucesso e quais estão falhando:

openclaw metrics skills --period 7d

# Output:
# Skill              Calls  Success  Failed  Avg Time
# web-search         45     44       1       2.1s
# file-manager       32     32       0       0.3s
# email-send         18     17       1       1.5s
# image-gen          8      6        2       8.4s
# shell-exec         156    154      2       0.8s

5. Disponibilidade dos Canais

Acompanhe a conectividade de cada canal de mensagens:

openclaw metrics channels --period 7d

# Output:
# Channel     Uptime    Disconnects  Avg Reconnect
# telegram    99.8%     1            3.2s
# email       99.9%     0            N/A
# whatsapp    97.2%     4            12.4s

Configurando Dashboards do Grafana

Para monitoramento visual, exporte as métricas do OpenClaw para o Grafana via Prometheus.

Passo 1: Habilitar a Exportação de Métricas

# config.yaml
metrics:
  enabled: true
  exporter: "prometheus"
  port: 9090
  path: "/metrics"

Passo 2: Configurar o Prometheus

# prometheus.yml
scrape_configs:
  - job_name: 'openclaw'
    scrape_interval: 15s
    static_configs:
      - targets: ['localhost:9090']

Passo 3: Criar o Dashboard do Grafana

Importe o dashboard comunitário do OpenClaw ou crie o seu próprio com estes painéis:

Tempo de Resposta (Série Temporal)

histogram_quantile(0.95, rate(openclaw_response_duration_seconds_bucket[5m]))

Taxa de Sucesso (Gauge)

rate(openclaw_messages_success_total[1h]) / rate(openclaw_messages_total[1h]) * 100

Uso de Tokens (Gráfico de Barras)

increase(openclaw_tokens_total[1d])

Canais Ativos (Painel de Status)

openclaw_channel_connected

Docker Compose com Stack de Monitoramento

version: "3.8"
services:
  openclaw:
    image: openclaw/openclaw:latest
    ports:
      - "127.0.0.1:3080:3080"
      - "127.0.0.1:9090:9090"
    volumes:
      - ./config:/app/config
      - ./data:/app/data

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "127.0.0.1:9091:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana:latest
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - grafana-data:/var/lib/grafana

volumes:
  grafana-data:

Verificações de Saúde

Endpoint HTTP de Saúde

O OpenClaw expõe um endpoint de verificação de saúde:

curl http://localhost:3080/health

# Response:
# {
#   "status": "healthy",
#   "uptime": 1234567,
#   "version": "0.9.6",
#   "components": {
#     "database": "healthy",
#     "llm_api": "healthy",
#     "channels": {
#       "telegram": "connected",
#       "email": "connected"
#     }
#   }
# }

Monitoramento Automatizado de Saúde

Use um script simples para verificar a saúde e alertar sobre falhas:

#!/bin/bash
# health-check.sh

HEALTH_URL="http://localhost:3080/health"
RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" "$HEALTH_URL")

if [ "$RESPONSE" != "200" ]; then
    # Alert via Inbounter email
    curl -X POST https://api.inbounter.com/v1/email/send \
      -H "Authorization: Bearer ${INBOUNTER_API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "to": "admin@company.com",
        "subject": "OpenClaw Health Check Failed",
        "body": "Health check returned HTTP '"$RESPONSE"' at '"$(date)"'"
      }'
fi

Agende isso com o cron do sistema:

# Check every 5 minutes
*/5 * * * * /home/user/scripts/health-check.sh

Monitoramento por Heartbeat

Para uma abordagem mais robusta, configure um heartbeat que alerta você quando ele para:

openclaw cron add --name "heartbeat" "*/5 * * * *" \
  "Send a heartbeat ping. This confirms I am running. 
   If this message does not arrive within 10 minutes, 
   something is wrong."

Configure o Inbounter para esperar o heartbeat e alertar você se ele perder uma janela.

Alertas

Alertas Integrados

alerts:
  - name: "high-error-rate"
    condition: "error_rate > 0.10"
    period: "1h"
    channels: ["telegram"]
    message: "Error rate above 10% in the last hour"
  
  - name: "high-latency"
    condition: "p95_latency > 15"
    period: "15m"
    channels: ["telegram", "email"]
    message: "P95 response time above 15 seconds"
  
  - name: "budget-warning"
    condition: "daily_cost > 5.00"
    period: "1d"
    channels: ["email"]
    message: "Daily API cost exceeded $5.00"
  
  - name: "channel-disconnect"
    condition: "channel_disconnected"
    channels: ["email"]
    message: "Channel {{channel}} disconnected"

Alertas por E-mail e SMS via Inbounter

Para alertas críticos, e-mail ou SMS é mais confiável do que o Telegram (que pode ser o próprio canal que está falhando):

alerts:
  providers:
    inbounter:
      api_key: "${INBOUNTER_API_KEY}"
      email: "admin@company.com"
      sms: "+1234567890"  # For critical alerts only
  
  routing:
    warning: ["telegram"]
    error: ["telegram", "inbounter_email"]
    critical: ["telegram", "inbounter_email", "inbounter_sms"]

Gestão de Logs

Rotação de Logs

Evite que os logs encham seu disco:

logging:
  file: "/var/log/openclaw/openclaw.log"
  max_size: "50MB"
  max_files: 10
  compress: true

Ou use o logrotate no Linux:

# /etc/logrotate.d/openclaw
/home/openclaw/.openclaw/logs/*.log {
    daily
    rotate 14
    compress
    missingok
    notifempty
    copytruncate
}

Logging Estruturado

Habilite logs no formato JSON para facilitar o parsing:

logging:
  format: "json"
  fields:
    - timestamp
    - level
    - component
    - user
    - message
    - duration

Isso permite a integração com ferramentas de agregação de logs (Loki, ELK stack, Datadog).

Análise de Logs

Comandos rápidos para análise comum de logs:

# Most common errors today
openclaw logs --level error --since 24h --format json | \
  jq -r '.message' | sort | uniq -c | sort -rn | head -10

# Slowest responses
openclaw logs --filter "response_time" --since 24h --format json | \
  jq -r '. | select(.duration > 10) | "\(.timestamp) \(.duration)s \(.message)"'

# Failed skills
openclaw logs --filter "skill_error" --since 7d --format json | \
  jq -r '.skill_name' | sort | uniq -c | sort -rn

Otimização de Desempenho

Se o monitoramento revelar problemas de desempenho, aqui estão as correções mais comuns:

Tempo de Resposta Alto

# Check if it's the API or your server
openclaw metrics response-time --breakdown

# If API is slow: switch to a faster model or provider
# If server is slow: check CPU and memory
openclaw status --resources

Vazamentos de Memória

# Track memory over time
watch -n 60 'openclaw status --resources | grep Memory'

# If memory keeps growing, restart periodically
openclaw cron add --name "weekly-restart" "0 3 * * 0" \
  "Notify admin that a scheduled restart is about to happen, 
   then restart the agent."

Otimização do Banco de Dados

# Check database size and health
openclaw db stats

# Compact the database
openclaw db vacuum

# Clear old data
openclaw memory prune --older-than 90d

Checklist de Monitoramento

Use este checklist para garantir que seu monitoramento está completo:

• openclaw doctor roda sem erros
• O endpoint de verificação de saúde é monitorado externamente
• Alertas configurados para taxa de erro, latência e orçamento
• Rotação de logs está configurada
• Uso de tokens é acompanhado diariamente
• Conectividade dos canais é monitorada
• Verificação de backup é automatizada
• Alertas de espaço em disco estão definidos
• Revisão semanal de desempenho está agendada

Perguntas Frequentes

Como monitoro o OpenClaw se eu estiver longe do meu computador?

Configure alertas por Telegram ou e-mail via Inbounter. Você receberá notificações no seu celular quando algo precisar de atenção.

Qual é uma boa referência para o tempo de resposta?

Com o Claude Sonnet, espere de 3 a 8 segundos para consultas típicas. Qualquer coisa consistentemente acima de 15 segundos justifica uma investigação.

Quanto o monitoramento adiciona aos custos do meu servidor?

Prometheus + Grafana adicionam cerca de 200-300 MB de RAM. Em um VPS de $5+, isso é gerenciável. Se você estiver em hardware mínimo, fique com o openclaw status e alertas baseados em cron.

Posso monitorar múltiplas instâncias do OpenClaw em um único dashboard?

Sim. Aponte o Prometheus para múltiplas instâncias do OpenClaw e o Grafana mostrará todas elas. Use labels para distinguir entre instâncias.

Devo monitorar os custos de tokens em tempo real?

O monitoramento diário costuma ser suficiente. Defina alertas para quando os gastos diários excederem seu limite, para que você detecte anomalias rapidamente.

Como sei se meu agente está tendo um bom desempenho?

Acompanhe estes três números: taxa de sucesso (meta: 95%+), tempo médio de resposta (meta: abaixo de 8s) e custo diário de tokens (meta: dentro do orçamento). Se os três estiverem no verde, seu agente está saudável.