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

# OpenClaw

> Trace OpenClaw gateway sessions with TraceCtrl

## Overview

[OpenClaw](https://openclaw.ai) is a self-hosted AI messaging gateway that bridges chat platforms (WhatsApp, Telegram, Discord, Slack, iMessage, etc.) to AI agents.

There are two ways to get OpenClaw traces into TraceCtrl. Pick one:

| Path | What it gives you | When to use |
| - | - | - |
| **TraceCtrl plugin** (`@tracectrl/openclaw-plugin`) | Rich spans — message content, tool I/O, security findings, token metrics, session lifecycle | Recommended. Powers topology, trace explorer, and risk scoring. |
| **Built-in `diagnostics-otel`** | Shallow operational spans only (model usage, message processed, webhook events) | Use when you can't install the TraceCtrl plugin. |

## Recommended: TraceCtrl plugin

The `tracectrl` CLI installs and configures the plugin into your local OpenClaw install.

**1. Install the plugin**

```bash theme={"dark"}
tracectrl install-plugin --configure
```

This copies the plugin to `~/.openclaw/extensions/tracectrl`, runs `npm install` and `npm run build`, then enables it in `~/.openclaw/openclaw.json`. Pass `--path /custom/openclaw` if your OpenClaw root is elsewhere, and `--endpoint http://host:4318` to override the collector URL.

**2. Restart the gateway**

```bash theme={"dark"}
openclaw gateway restart
```

**3. Verify**

```bash theme={"dark"}
tracectrl doctor
```

The doctor command checks both that the plugin is installed and that it is enabled in `openclaw.json`.

The resulting `openclaw.json` block looks like this:

```json theme={"dark"}
{
  "plugins": {
    "allow": ["tracectrl"],
    "entries": {
      "tracectrl": {
        "enabled": true,
        "config": {
          "endpoint": "http://localhost:4318",
          "serviceName": "openclaw-gateway",
          "captureContent": true
        }
      }
    }
  }
}
```

### Plugin config options

| Option | Type | Default | Description |
| - | - | - | - |
| `endpoint` | string | `http://localhost:4318` | OTLP collector endpoint |
| `serviceName` | string | `openclaw-gateway` | Service name for traces |
| `captureContent` | boolean | `false` | Capture message text and tool I/O (privacy-sensitive) |
| `protocol` | `"http"` \| `"grpc"` | `"http"` | OTLP transport protocol |
| `traces` | boolean | `true` | Enable trace export |
| `metrics` | boolean | `true` | Enable metric export |
| `metricsIntervalMs` | number | `30000` | Metric export interval |
| `headers` | object | `{}` | Additional HTTP headers for the OTLP exporter |

### What the plugin captures

| Hook | Span | Key attributes |
| - | - | - |
| `message_received` | `tracectrl.request` (root) | channel, session key, direction, message text |
| `before_agent_start` | `tracectrl.agent.turn` | agent ID, model |
| `tool_result_persist` | `tracectrl.tool.{name}` | tool name, call ID, input preview, result size, errors |
| `agent_end` | (closes agent + root) | token usage (input/output/cache), duration, model |
| `command:new/reset/stop` | `tracectrl.session.{action}` | action, session key |
| `gateway:startup` | `tracectrl.gateway.startup` | version, PID |

The plugin also flags dangerous tools (bash/shell/exec), dangerous commands (`rm -rf`, `sudo`, reverse shells, piped curl), sensitive file access (`.env`, private keys, `/etc/passwd`), and prompt-injection patterns. Findings are recorded under `tracectrl.security.*` span attributes and counted by the `tracectrl.security.events` metric.

## Alternative: built-in `diagnostics-otel`

If you can't install the TraceCtrl plugin, OpenClaw ships its own OTLP exporter. Spans are shallower but the wiring is the same.

**1. Enable the diagnostics-otel plugin**

```bash theme={"dark"}
openclaw plugins enable diagnostics-otel
```

**2. Configure OTEL export**

Add to `~/.openclaw/openclaw.json`:

```json theme={"dark"}
{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": { "enabled": true }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://localhost:4318",
      "protocol": "http/protobuf",
      "serviceName": "openclaw-gateway",
      "traces": true,
      "metrics": false,
      "logs": false,
      "sampleRate": 1.0,
      "flushIntervalMs": 5000
    }
  }
}
```

> [!NOTE]
>
> OpenClaw exports via **OTLP/HTTP** (port 4318), not gRPC (4317).

**3. Restart and verify**

```bash theme={"dark"}
openclaw gateway restart
tracectrl doctor
```

### What `diagnostics-otel` captures

| Span | Type | What It Captures |
| - | - | - |
| `openclaw.model.usage` | LLM | Model, provider, token counts (input/output/cache), session ID |
| `openclaw.message.processed` | Agent | Channel, outcome, chat ID, message ID, session ID |
| `openclaw.webhook.processed` | Tool | Channel, webhook handler, chat ID |
| `openclaw.webhook.error` | Tool (Error) | Channel, webhook, error details |
| `openclaw.session.stuck` | Alert | Session state, age, queue depth |

### Recommended settings

| Setting | Dev | Production | Why |
| - | - | - | - |
| `sampleRate` | `1.0` | `0.2` | Full tracing during setup, sample at scale |
| `flushIntervalMs` | `5000` | `60000` | 5s for near-real-time debugging, 60s to reduce overhead |
| `traces` | `true` | `true` | Required for all TraceCtrl views |
| `metrics` | `false` | `false` | Not processed by TraceCtrl yet (silently dropped) |
| `logs` | `false` | `false` | Not processed by TraceCtrl yet (silently dropped) |

## Protocol notes

* OpenClaw's built-in exporter supports **OTLP/HTTP (protobuf) only** — gRPC is not supported.
* The TraceCtrl plugin supports both `http` and `grpc` via its `protocol` config option.
* The endpoint should be the HTTP port (`:4318`), not gRPC (`:4317`), unless you've explicitly enabled gRPC ingest.
* TraceCtrl's engine currently consumes traces only. Metrics and logs sent to the collector are accepted but not surfaced in the dashboard.

## Environment variables

Both paths honour the standard OTEL environment variables, which override the JSON config:

```bash theme={"dark"}
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_SERVICE_NAME=openclaw-gateway
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
```

## Reference

* [OpenClaw Logging & OTEL docs](https://docs.openclaw.ai/logging)


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