OpenClaw

Overview

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

Install the plugin

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.

Restart the gateway

openclaw gateway restart

Verify

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:

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

Enable the diagnostics-otel plugin

openclaw plugins enable diagnostics-otel

Configure OTEL export

Add to ~/.openclaw/openclaw.json:

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

OpenClaw exports via OTLP/HTTP (port 4318), not gRPC (4317).

Restart and verify

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:

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_SERVICE_NAME=openclaw-gateway
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

Reference

OpenClaw Logging & OTEL docs

Getting Started

SDK

Framework Instrumentors

Security

Platform

Overview

Recommended: TraceCtrl plugin

Plugin config options

What the plugin captures

Alternative: built-in `diagnostics-otel`

What `diagnostics-otel` captures

Recommended settings

Protocol notes

Environment variables

Reference

​Overview

​Recommended: TraceCtrl plugin

​Plugin config options

​What the plugin captures

​Alternative: built-in diagnostics-otel

​What diagnostics-otel captures

​Recommended settings

​Protocol notes

​Environment variables

​Reference

Overview

Recommended: TraceCtrl plugin

Plugin config options

What the plugin captures

Alternative: built-in `diagnostics-otel`

What `diagnostics-otel` captures

Recommended settings

Protocol notes

Environment variables

Reference