OpenClaw

Moda ingests OpenClaw telemetry natively: spans exported by OpenClaw’s diagnostics-otel plugin are accepted on the ingestion API’s /v1/traces endpoint and grouped into conversations by OpenClaw session. The Moda SDK for Node.js ships helpers that generate the plugin configuration and the OTLP environment variables. The OpenClaw helpers are Node.js only — the Python SDK does not include them.

Prerequisites

Node.js 18 or later with moda-ai installed (npm install moda-ai)
An OpenClaw installation with the diagnostics-otel plugin available
A Moda API key, created at Settings → Ingestion keys (see Authentication)

Set up

Generate the telemetry configuration

Moda.getOpenClawTelemetryConfig() returns the configuration object OpenClaw’s diagnostics-otel plugin expects, pre-filled with Moda’s OTLP endpoint and your API key:

generate-config.ts

import { Moda } from 'moda-ai';

// Reads MODA_API_KEY from the environment; alternatively pass an
// `apiKey` option or call `await Moda.init(...)` first.
const config = Moda.getOpenClawTelemetryConfig({
  serviceName: 'openclaw-gateway',
  enableMetrics: false,
  enableLogs: false,
});
console.log(JSON.stringify(config, null, 2));

Output

{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": { "diagnostics-otel": { "enabled": true } }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "https://moda-ingest.modas.workers.dev",
      "protocol": "http/protobuf",
      "serviceName": "openclaw-gateway",
      "traces": true,
      "metrics": false,
      "logs": false,
      "headers": { "Authorization": "Bearer moda_sk_..." }
    }
  }
}

Merge this object into your OpenClaw configuration.

Or generate environment variables for spawned processes

If you launch OpenClaw as a subprocess, Moda.getOpenClawEnvironment() returns the equivalent OTEL_* environment variables:

launch.ts

import { spawn } from 'node:child_process';
import { Moda } from 'moda-ai';

const env = Moda.getOpenClawEnvironment({
  serviceName: 'openclaw-gateway',
  enableMetrics: false,
  enableLogs: false,
  extraEnv: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
});

// Launch OpenClaw with the generated variables
const child = spawn('openclaw', process.argv.slice(2), {
  env: { ...process.env, ...env },
  stdio: 'inherit',
});

The returned map contains:

Variable	Value
`OTEL_EXPORTER_OTLP_ENDPOINT`	`https://moda-ingest.modas.workers.dev` (or your `baseUrl`)
`OTEL_EXPORTER_OTLP_PROTOCOL`	`http/protobuf`
`OTEL_EXPORTER_OTLP_HEADERS`	`Authorization=Bearer%20moda_sk_...` (URL-encoded)
`OTEL_SERVICE_NAME`	Your `serviceName` (default `openclaw`)
`OTEL_TRACES_EXPORTER`	`otlp`, or `none` when `enableTraces: false`
`OTEL_METRICS_EXPORTER`	`otlp`, or `none` when `enableMetrics: false`
`OTEL_LOGS_EXPORTER`	`otlp`, or `none` when `enableLogs: false`

Verify

Run an OpenClaw session, then open Conversations in the dashboard. Within minutes you should see a conversation per OpenClaw session containing model usage and processed-message entries.

The ingestion API stores traces only — there are no /v1/metrics or /v1/logs endpoints. Set enableMetrics: false and enableLogs: false unless another OTLP backend consumes those signals.

Helper options

Both helpers accept the same options; getOpenClawEnvironment additionally accepts extraEnv.

Option	Default	Description
`apiKey`	Key passed to `Moda.init()`, then the `MODA_API_KEY` env var	Moda API key placed in the `Authorization` header
`baseUrl`	`baseUrl` from `Moda.init()`, then `MODA_BASE_URL`, then `https://moda-ingest.modas.workers.dev/v1/traces`	OTLP endpoint base. A trailing `/v1/traces`, `/v1/metrics`, or `/v1/logs` is stripped because OTLP exporters append the signal path themselves
`serviceName`	`openclaw`	OpenTelemetry service name
`enableTraces`	`true`	Export traces
`enableMetrics`	`true`	Export metrics (set to `false` — see the note above)
`enableLogs`	`true`	Export logs (set to `false` — see the note above)
`additionalHeaders`	—	Extra OTLP headers to attach
`extraEnv` (`getOpenClawEnvironment` only)	—	Extra environment variables merged into the returned map

The helpers do not require Moda.init() to have run: they are the only part of the Node.js SDK that falls back to the MODA_API_KEY and MODA_BASE_URL environment variables. If no key can be resolved, they throw [Moda] MODA_API_KEY is required for OpenClaw telemetry helpers.

What Moda extracts from OpenClaw spans

Two OpenClaw span names are mapped into conversation data; other openclaw.* spans are ignored.

Span name	Meaning
`openclaw.model.usage`	A model call, with provider, model, and token usage
`openclaw.message.processed`	A processed message, with its outcome

Attributes read from those spans:

Attribute	Used for
`openclaw.sessionId`	Conversation grouping (preferred)
`openclaw.sessionKey`	Conversation grouping (fallback)
`openclaw.provider`	Provider
`openclaw.model`	Model
`openclaw.tokens.input`, `openclaw.tokens.output`	Token usage
`openclaw.messageId`	External message ID for the resulting message
`openclaw.outcome`, `openclaw.reason`	Outcome of `openclaw.message.processed` spans

When neither openclaw.sessionId nor openclaw.sessionKey is present, grouping falls back to the OTLP trace ID.

Trace your own OpenClaw operations

Moda.withOpenClawOperation() wraps gateway or CLI lifecycle work in a span named openclaw.<operation> with llm.vendor: openclaw. Conversation and user IDs come from the options, or from the ambient Moda context when omitted. Errors are recorded on the span and re-thrown.

operations.ts

import { Moda } from 'moda-ai';

await Moda.init(process.env.MODA_API_KEY!);

const result = await Moda.withOpenClawOperation(
  {
    operation: 'session.start',
    conversationId: 'oc-sess-1',
    userId: 'user_1042',
    attributes: { 'gateway.region': 'us-east-1' },
  },
  async ({ span }) => {
    // run the OpenClaw work you want traced, then return its result
    span.setAttribute('session.channel', 'gateway');
    return 'session-started';
  },
);
console.log(result);

await Moda.flush();

Operation spans record timing and errors but do not create conversation messages. Message content comes from OpenClaw’s own openclaw.model.usage and openclaw.message.processed spans.

Troubleshooting

Symptom	Fix
`401` from `/v1/traces`	The key is missing, invalid, or revoked. The helpers set the `Authorization: Bearer moda_sk_...` header from your API key — check the key in the dashboard at Settings → Ingestion keys.
Exports succeed but nothing appears in Conversations	The spans reaching Moda are not named `openclaw.model.usage` / `openclaw.message.processed` and carry no GenAI attributes. Confirm the `diagnostics-otel` plugin is enabled and exporting traces (not only metrics or logs).
Every message lands in its own conversation	Spans are missing `openclaw.sessionId` / `openclaw.sessionKey`, so grouping falls back to the trace ID.
Exporter errors for metrics or logs	The ingestion API has no metrics or logs endpoints. Set `enableMetrics: false` and `enableLogs: false`.

Next steps

OpenTelemetry — the full OTLP attribute contract on /v1/traces.
Moda SDK for Node.js — init, context APIs, and flush semantics.
Conversations — how ingested sessions appear in the dashboard.
Reliability — retry behavior and error envelopes.

Send data

SDKs

Providers

Frameworks and agents

OpenTelemetry

API reference

Prerequisites

Set up

Helper options

What Moda extracts from OpenClaw spans

Trace your own OpenClaw operations

Troubleshooting

Next steps

​Prerequisites

​Set up

​Helper options

​What Moda extracts from OpenClaw spans

​Trace your own OpenClaw operations

​Troubleshooting

​Next steps

Prerequisites

Set up

Helper options

What Moda extracts from OpenClaw spans

Trace your own OpenClaw operations

Troubleshooting

Next steps