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

# OpenClaw

> Send OpenClaw framework traces to Toqan Router via OpenTelemetry. Monitor agent interactions, tool calls, and LLM performance in real time.

## Getting Started

OpenClaw is an open-source personal AI assistant that runs locally on your machine, connecting LLMs to messaging platforms and system tools. OpenClaw has a built-in `diagnostics-otel` plugin that exports traces, metrics, and logs over OTLP/HTTP — just enable the plugin and point it at Toqan Router.

> [!WARNING]
>
> OpenClaw's OpenTelemetry support currently requires some manual configuration to get working end-to-end. We are actively working with the OpenClaw team to improve this — there is a [live PR](https://github.com/openclaw/openclaw/pull/11100) to streamline the integration. If better OTEL support matters to you, please leave a comment on the PR to help prioritize it.

### Prerequisites

Before you begin, ensure you have:

* A Toqan Router account and API Key
* OpenClaw installed and running locally
* Node.js 20+

### Install 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 OpenClaw

OpenClaw's OTEL export is configured through `~/.openclaw/openclaw.json`. You need to enable the `diagnostics-otel` plugin and configure the `diagnostics.otel` section.

### Step 1: Enable the plugin

You can enable the plugin via the CLI:

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

Or add it directly to `~/.openclaw/openclaw.json`:

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

### Step 2: Configure the OTEL exporter

Add the `diagnostics` section to `~/.openclaw/openclaw.json`, pointing the endpoint at 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
    }
  }
}
```

**Alternative: Environment Variables**

You can also configure the exporter via environment variables as a fallback. These are read if the corresponding config file values are not set.

```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]
>
> The `diagnostics-otel` plugin and `diagnostics.enabled: true` are still required in the config file — environment variables only override the endpoint, headers, and service name.

### Step 3: Run OpenClaw

Start the OpenClaw gateway:

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

## What Gets Traced

OpenClaw's `diagnostics-otel` plugin emits spans for model usage, message processing, webhook handling, and tool execution. Toqan Router automatically detects and processes these spans, extracting:

| Attribute | Description |
| - | - |
| `openclaw.model` | The LLM model used |
| `openclaw.provider` | The LLM provider (e.g., anthropic, openai) |
| `openclaw.sessionId` | Conversation session identifier |
| `openclaw.sessionKey` | Session key for conversation grouping |
| `openclaw.tokens.input` | Input token count |
| `openclaw.tokens.output` | Output token count |
| `openclaw.tokens.total` | Total token count |
| `openclaw.tokens.cache_read` | Cached token count |
| `openclaw.channel` | Messaging channel (e.g., webchat, telegram) |
| `openclaw.outcome` | Processing outcome |

### Exported Spans

* **`openclaw.model.usage`** — LLM inference calls with token usage, cost, and model details
* **`openclaw.message.processed`** — End-to-end message processing with outcome and duration
* **`openclaw.webhook.processed`** — Webhook handling for messaging platform integrations
* **`openclaw.session.stuck`** — Session state warnings

### Configuration Options

| Option | Default | Description |
| - | - | - |
| `diagnostics.otel.enabled` | `false` | Enable OTEL export |
| `diagnostics.otel.endpoint` | — | OTLP/HTTP endpoint URL |
| `diagnostics.otel.protocol` | `http/protobuf` | Export protocol (only `http/protobuf` is supported) |
| `diagnostics.otel.headers` | `{}` | Headers for authentication |
| `diagnostics.otel.serviceName` | — | Service name for the resource |
| `diagnostics.otel.traces` | `true` | Export traces |
| `diagnostics.otel.metrics` | `true` | Export metrics |
| `diagnostics.otel.logs` | `false` | Export logs (can be high volume) |
| `diagnostics.otel.captureContent` | `false` | Capture message content in spans (sensitive data) |
| `diagnostics.otel.sampleRate` | `1.0` | Trace sampling rate (0.0–1.0) |
| `diagnostics.otel.flushIntervalMs` | `60000` | Metric export interval in ms (min 1000) |

## Next Steps

[**Verify Traces**](/docs/ai-studio/observability/traces.md) in the Studio.

> [!NOTE]
>
> No additional instrumentation libraries are needed — OpenClaw includes OpenTelemetry support via the built-in `diagnostics-otel` plugin.


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