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

# OpenClaw

> Send OpenClaw framework traces to Orq.ai 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 Orq.ai.

<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.
</Warning>

### Prerequisites

Before you begin, ensure you have:

* An Orq.ai account and [API Key](/docs/administer/api-keys)
* OpenClaw installed and running locally
* Node.js 20+

### Install OpenClaw

<CodeGroup>
  ```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
  ```
</CodeGroup>

## 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:

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

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

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

### Step 2: Configure the OTEL exporter

Add the `diagnostics` section to `~/.openclaw/openclaw.json`, pointing the endpoint at Orq.ai:

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

<Expandable title="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://api.orq.ai/v2/otel"
  export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <ORQ_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.</Note>
</Expandable>

### Step 3: Run OpenClaw

Start the OpenClaw gateway:

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

## What Gets Traced

OpenClaw's `diagnostics-otel` plugin emits spans for model usage, message processing, webhook handling, and tool execution. Orq.ai 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/observability/traces) in the Studio.

<Info>
  No additional instrumentation libraries are needed — OpenClaw includes OpenTelemetry support via the built-in `diagnostics-otel` plugin.
</Info>