Skip to main content

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.

​
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:
PathWhat it gives youWhen to use
TraceCtrl plugin (@tracectrl/openclaw-plugin)Rich spans — message content, tool I/O, security findings, token metrics, session lifecycleRecommended. Powers topology, trace explorer, and risk scoring.
Built-in diagnostics-otelShallow operational spans only (model usage, message processed, webhook events)Use when you can’t install the TraceCtrl plugin.
The tracectrl CLI installs and configures the plugin into your local OpenClaw install.
1

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

Restart the gateway

openclaw gateway restart
3

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

OptionTypeDefaultDescription
endpointstringhttp://localhost:4318OTLP collector endpoint
serviceNamestringopenclaw-gatewayService name for traces
captureContentbooleanfalseCapture message text and tool I/O (privacy-sensitive)
protocol"http" | "grpc""http"OTLP transport protocol
tracesbooleantrueEnable trace export
metricsbooleantrueEnable metric export
metricsIntervalMsnumber30000Metric export interval
headersobject{}Additional HTTP headers for the OTLP exporter

​
What the plugin captures

HookSpanKey attributes
message_receivedtracectrl.request (root)channel, session key, direction, message text
before_agent_starttracectrl.agent.turnagent ID, model
tool_result_persisttracectrl.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/stoptracectrl.session.{action}action, session key
gateway:startuptracectrl.gateway.startupversion, 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

openclaw plugins enable diagnostics-otel
2

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).
3

Restart and verify

openclaw gateway restart
tracectrl doctor

​
What diagnostics-otel captures

SpanTypeWhat It Captures
openclaw.model.usageLLMModel, provider, token counts (input/output/cache), session ID
openclaw.message.processedAgentChannel, outcome, chat ID, message ID, session ID
openclaw.webhook.processedToolChannel, webhook handler, chat ID
openclaw.webhook.errorTool (Error)Channel, webhook, error details
openclaw.session.stuckAlertSession state, age, queue depth
SettingDevProductionWhy
sampleRate1.00.2Full tracing during setup, sample at scale
flushIntervalMs5000600005s for near-real-time debugging, 60s to reduce overhead
tracestruetrueRequired for all TraceCtrl views
metricsfalsefalseNot processed by TraceCtrl yet (silently dropped)
logsfalsefalseNot 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