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

# OpenClaw

> Using Moda with OpenClaw via OTLP diagnostics

## Overview

OpenClaw can export telemetry through its `diagnostics-otel` plugin. Moda accepts that OTLP traffic at `/v1/traces` and maps OpenClaw session spans into `conversation_logging`.

## 1. Enable OpenClaw diagnostics

OpenClaw does not export OTLP by default. Enable the plugin and diagnostics keys once in your OpenClaw profile:

```bash theme={"dark"}
openclaw plugins enable diagnostics-otel
openclaw config set diagnostics.enabled true --json
openclaw config set diagnostics.otel.enabled true --json
```

## 2. Point OpenClaw to Moda

Set the OTLP endpoint and auth headers to Moda ingest:

```bash theme={"dark"}
openclaw config set diagnostics.otel.endpoint '"https://moda-ingest.modas.workers.dev"' --json
openclaw config set diagnostics.otel.protocol '"http/protobuf"' --json
openclaw config set diagnostics.otel.serviceName '"openclaw-gateway"' --json
openclaw config set diagnostics.otel.traces true --json
```

<Note>
  You can also use Moda SDK helpers to generate equivalent OTEL environment variables for OpenClaw subprocesses.
</Note>

## Node.js helper usage

```ts theme={"dark"}
import { Moda } from 'moda-ai';

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

const env = Moda.getOpenClawEnvironment({
  serviceName: 'openclaw-gateway',
});

// Pass `env` when spawning OpenClaw
```

## Python helper usage

```python theme={"dark"}
import moda
from moda.openclaw import get_openclaw_env, run_openclaw_cli

moda.init("YOUR_MODA_API_KEY")

env = get_openclaw_env(service_name="openclaw-gateway")

result = run_openclaw_cli(
    ["agent", "--local", "--session-id", "session_123", "--message", "Hello", "--json"],
    command_prefix=["npx", "-y", "openclaw@latest"],
    env={"ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_KEY", **env},
)
print(result.stdout)
```

## What gets ingested

For OpenClaw spans, Moda ingestion supports:

* `openclaw.model.usage`
* `openclaw.message.processed`

Conversation grouping uses:

* `openclaw.sessionId` (preferred)
* `openclaw.sessionKey` (fallback)

## Troubleshooting

**No rows in `conversation_logging`?**

* Verify `openclaw plugins list` shows `diagnostics-otel` as enabled.
* Verify `diagnostics.enabled=true` and `diagnostics.otel.enabled=true`.
* Verify endpoint is `https://moda-ingest.modas.workers.dev` (without extra path suffixes).
* Verify OTLP headers include `Authorization: Bearer <MODA_API_KEY>`.

**Still seeing `count: 0` from `/v1/traces` responses?**

* Your ingest worker may be running an older build that does not parse `openclaw.*` spans yet.
* Deploy the ingest worker version that includes OpenClaw span extraction.