Orq.ai Documentation - AI Gateway & LLM Collaboration Platform

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.

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

An Orq.ai account and API Key
OpenClaw installed and running locally
Node.js 20+

Install OpenClaw

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

openclaw plugins enable diagnostics-otel

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

{
  "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 Orq.ai:

{
  "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
    }
  }
}

Show 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

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"

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:

openclaw gateway run

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 in the Studio.

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

Documentation Index

​Getting Started

​Prerequisites

​Install OpenClaw

​Configure OpenClaw

​Step 1: Enable the plugin

​Step 2: Configure the OTEL exporter

​Step 3: Run OpenClaw

​What Gets Traced

​Exported Spans

​Configuration Options

​Next Steps

Getting Started

Prerequisites

Install OpenClaw

Configure OpenClaw

Step 1: Enable the plugin

Step 2: Configure the OTEL exporter

Step 3: Run OpenClaw

What Gets Traced

Exported Spans

Configuration Options

Next Steps