> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw

> Envie traces do framework OpenClaw para o Toqan Router via OpenTelemetry. Monitore interações de agentes, chamadas de ferramentas e o desempenho de LLMs em tempo real.

## Primeiros passos

O OpenClaw é um assistente pessoal de IA de código aberto que roda localmente na sua máquina, conectando LLMs a plataformas de mensagens e ferramentas do sistema. O OpenClaw tem um plugin `diagnostics-otel` integrado que exporta traces, métricas e logs via OTLP/HTTP — basta ativar o plugin e apontá-lo para o Toqan Router.

> [!WARNING]
>
> No momento, o suporte do OpenClaw ao OpenTelemetry exige alguma configuração manual para funcionar de ponta a ponta. Estamos trabalhando ativamente com a equipe do OpenClaw para melhorar isso — há um [PR em andamento](https://github.com/openclaw/openclaw/pull/11100) para simplificar a integração. Se um suporte melhor ao OTEL é importante para você, deixe um comentário no PR para ajudar a priorizá-lo.

### Pré-requisitos

Antes de começar, verifique se você tem:

* Uma conta no Toqan Router e uma chave de API
* O OpenClaw instalado e em execução localmente
* Node.js 20+

### Instale o OpenClaw

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Quick install
curl -fsSL https://openclaw.ai/install.sh | bash

# Or via npm
npm install -g openclaw
```

## Configure o OpenClaw

A exportação OTEL do OpenClaw é configurada pelo arquivo `~/.openclaw/openclaw.json`. Você precisa ativar o plugin `diagnostics-otel` e configurar a seção `diagnostics.otel`.

### Etapa 1: ative o plugin

Você pode ativar o plugin pela CLI:

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
openclaw plugins enable diagnostics-otel
```

Ou adicioná-lo diretamente ao `~/.openclaw/openclaw.json`:

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  }
}
```

### Etapa 2: configure o exportador OTEL

Adicione a seção `diagnostics` ao `~/.openclaw/openclaw.json`, apontando o endpoint para o Toqan Router:

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "https://router.toqan.ai/eu/v2/otel",
      "protocol": "http/protobuf",
      "headers": {
        "Authorization": "Bearer <TOQAN_API_KEY>"
      },
      "serviceName": "openclaw",
      "traces": true,
      "metrics": true,
      "logs": false,
      "sampleRate": 1,
      "flushIntervalMs": 5000
    }
  }
}
```

**Alternativa: variáveis de ambiente**

Você também pode configurar o exportador por variáveis de ambiente como alternativa. Elas são lidas caso os valores correspondentes não estejam definidos no arquivo de configuração.

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export OTEL_EXPORTER_OTLP_ENDPOINT="https://router.toqan.ai/eu/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <TOQAN_API_KEY>"
export OTEL_SERVICE_NAME="openclaw"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
```

> [!NOTE]
>
> O plugin `diagnostics-otel` e `diagnostics.enabled: true` continuam sendo obrigatórios no arquivo de configuração — as variáveis de ambiente apenas substituem o endpoint, os headers e o nome do serviço.

### Etapa 3: execute o OpenClaw

Inicie o gateway do OpenClaw:

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
openclaw gateway run
```

## O que é rastreado

O plugin `diagnostics-otel` do OpenClaw emite spans para uso de modelos, processamento de mensagens, tratamento de webhooks e execução de ferramentas. O Toqan Router detecta e processa esses spans automaticamente, extraindo:

| Atributo | Descrição |
| - | - |
| `openclaw.model` | O modelo de LLM utilizado |
| `openclaw.provider` | O provedor de LLM (por exemplo, anthropic, openai) |
| `openclaw.sessionId` | Identificador da sessão de conversa |
| `openclaw.sessionKey` | Chave de sessão para agrupar conversas |
| `openclaw.tokens.input` | Contagem de tokens de entrada |
| `openclaw.tokens.output` | Contagem de tokens de saída |
| `openclaw.tokens.total` | Contagem total de tokens |
| `openclaw.tokens.cache_read` | Contagem de tokens em cache |
| `openclaw.channel` | Canal de mensagens (por exemplo, webchat, telegram) |
| `openclaw.outcome` | Resultado do processamento |

### Spans exportados

* **`openclaw.model.usage`** — Chamadas de inferência de LLM com uso de tokens, custo e detalhes do modelo
* **`openclaw.message.processed`** — Processamento de mensagens de ponta a ponta, com resultado e duração
* **`openclaw.webhook.processed`** — Tratamento de webhooks para integrações com plataformas de mensagens
* **`openclaw.session.stuck`** — Alertas de estado da sessão

### Opções de configuração

| Opção | Padrão | Descrição |
| - | - | - |
| `diagnostics.otel.enabled` | `false` | Ativa a exportação OTEL |
| `diagnostics.otel.endpoint` | — | URL do endpoint OTLP/HTTP |
| `diagnostics.otel.protocol` | `http/protobuf` | Protocolo de exportação (apenas `http/protobuf` é compatível) |
| `diagnostics.otel.headers` | `{}` | Headers de autenticação |
| `diagnostics.otel.serviceName` | — | Nome do serviço para o recurso |
| `diagnostics.otel.traces` | `true` | Exporta traces |
| `diagnostics.otel.metrics` | `true` | Exporta métricas |
| `diagnostics.otel.logs` | `false` | Exporta logs (pode gerar alto volume) |
| `diagnostics.otel.captureContent` | `false` | Captura o conteúdo das mensagens nos spans (dados sensíveis) |
| `diagnostics.otel.sampleRate` | `1.0` | Taxa de amostragem de traces (0.0–1.0) |
| `diagnostics.otel.flushIntervalMs` | `60000` | Intervalo de exportação de métricas em ms (mín. 1000) |

## Próximos passos

[**Verifique os traces**](/docs/pt-BR/ai-studio/observability/traces.md) no Studio.

> [!NOTE]
>
> Nenhuma biblioteca de instrumentação adicional é necessária — o OpenClaw inclui suporte ao OpenTelemetry por meio do plugin integrado `diagnostics-otel`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.