> ## 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](/ai-studio/organization/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://my.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://my.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**](/ai-studio/observability/traces) in the Studio.

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


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