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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Restart the gateway">
    ```bash theme={"dark"}
    openclaw gateway restart
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={"dark"}
    tracectrl doctor
    ```

    The doctor command checks both that the plugin is installed and that it is enabled in `openclaw.json`.
  </Step>
</Steps>

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.

<Steps>
  <Step title="Enable the diagnostics-otel plugin">
    ```bash theme={"dark"}
    openclaw plugins enable diagnostics-otel
    ```
  </Step>

  <Step title="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).
    </Note>
  </Step>

  <Step title="Restart and verify">
    ```bash theme={"dark"}
    openclaw gateway restart
    tracectrl doctor
    ```
  </Step>
</Steps>

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