OpenTelemetry export：总控室这一层在盯什么

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：OpenClaw exports diagnostics through the official diagnostics-otel 新本领插件 using **OTLP/HTTP (protobuf)**. Any collector…。

OpenClaw exports diagnostics through the official diagnostics-otel plugin using **OTLP/HTTP (protobuf)**. Any collector or backend that accepts OTLP/HTTP works without code changes. For local file logs and how to read them, see Logging.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：门口的小门卫 and bundled 新本领插件s for 聪明脑袋模型 runs, 小纸条消息 flow, sessions, queues, and exec. OpenTelemetry **metrics**, **traces*…。

Gateway and bundled plugins for model runs, message flow, sessions, queues, and exec.

OpenTelemetry **metrics**, **traces**, and **logs** over OTLP/HTTP.

trusted model-call span context when the provider transport accepts custom headers. Plugin-emitted trace context is not propagated.

enabled, so the in-process cost stays near zero by default.

• **Diagnostics events** are structured, in-process records emitted by the
• **diagnostics-otel plugin** subscribes to those events and exports them as
• **Provider calls** receive a W3C traceparent header from OpenClaw's
• Exporters only attach when both the diagnostics surface and the plugin are

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：For packaged installs, install the 新本领插件 first: You can also enable the 新本领插件 from the CLI: Note protocol currently sup…。

For packaged installs, install the plugin first:

openclaw plugins install clawhub:@openclaw/diagnostics-otel

{
  plugins: {
    allow: ["diagnostics-otel"],
    entries: {
      "diagnostics-otel": { enabled: true },
    },
  },
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      protocol: "http/protobuf",
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: true,
      sampleRate: 0.2,
      flushIntervalMs: 60000,
    },
  },
}

You can also enable the plugin from the CLI:

openclaw plugins enable diagnostics-otel

Note

protocol currently supports http/protobuf only. grpc is ignored.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Toggle traces, metrics, and logs independently. All three default to on when diagnostics.otel.enabled is true.

Toggle traces, metrics, and logs independently. All three default to on when diagnostics.otel.enabled is true.

这一小段像旁白，在提醒我们镜头已经切到下一站。

{
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      tracesEndpoint: "http://otel-collector:4318/v1/traces",
      metricsEndpoint: "http://otel-collector:4318/v1/metrics",
      logsEndpoint: "http://otel-collector:4318/v1/logs",
      protocol: "http/protobuf", // grpc is ignored
      serviceName: "openclaw-gateway",
      headers: { "x-collector-token": "..." },
      traces: true,
      metrics: true,
      logs: true,
      sampleRate: 0.2, // root-span sampler, 0.0..1.0
      flushIntervalMs: 60000, // metric export interval (min 1000ms)
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
      },
    },
  },
}

这一小段像旁白，在提醒我们镜头已经切到下一站。

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Raw 聪明脑袋模型/工具小帮手 content is **not** exported by default. Spans carry bounded identifiers (消息通道, provider, 聪明脑袋模型, error…。

Raw model/tool content is **not** exported by default. Spans carry bounded identifiers (channel, provider, model, error category, hash-only request ids, tool source, tool owner, and skill name/source) and never include prompt text, response text, tool inputs, tool outputs, skill file paths, or session keys. OTLP log records keep severity, logger, code location, trusted trace context, and sanitized attributes by default, but the raw log message body is exported only when diagnostics.otel.captureContent is set to boolean true. Granular captureContent.* subkeys do not enable log bodies. Labels that look like scoped agent session keys are replaced with unknown. Talk metrics export only bounded event metadata such as mode, transport, provider, and event type. They do not include transcripts, audio payloads, session ids, turn ids, call ids, room ids, or handoff tokens.

Outbound model requests may include a W3C traceparent header. That header is generated only from OpenClaw-owned diagnostic trace context for the active model call. Existing caller-supplied traceparent headers are replaced, so plugins or custom provider options cannot spoof cross-service trace ancestry.

Set diagnostics.otel.captureContent.* to true only when your collector and retention policy are approved for prompt, response, tool, or system-prompt text. Each subkey is opt-in independently:

• inputMessages - user prompt content.
• outputMessages - model response content.
• toolInputs - tool argument payloads.
• toolOutputs - tool result payloads.
• systemPrompt - assembled system/developer prompt.

When any subkey is enabled, model and tool spans get bounded, redacted openclaw.content.* attributes for that class only. Use boolean captureContent: true only for broad diagnostics captures where OTLP log message bodies are also approved for export.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：1.0 keeps all). diagnostic log-record redaction path, not console formatting. High-volume installs should prefer OTLP c…。

1.0 keeps all).

diagnostic log-record redaction path, not console formatting. High-volume installs should prefer OTLP collector sampling/filtering over local sampling.

spanId, parentSpanId, and traceFlags when the log call carries a valid diagnostic trace context, which lets log processors join local log lines with exported spans.

internal request trace scope. Logs and diagnostic events inside that scope inherit the request trace by default, while agent run and model-call spans are created as children so provider traceparent headers stay on the same trace.

• **Traces:** diagnostics.otel.sampleRate (root-span only, 0.0 drops all,
• **Metrics:** diagnostics.otel.flushIntervalMs (minimum 1000).
• **Logs:** OTLP logs respect logging.level (file log level). They use the
• **File-log correlation:** JSONL file logs include top-level traceId,
• **Request correlation:** Gateway HTTP requests and WebSocket frames create an

这一小段像旁白，在提醒我们镜头已经切到下一站。

• openclaw.tokens (counter, attrs: openclaw.token, openclaw.channel, openclaw.provider, openclaw.model, openclaw.agent)
• openclaw.cost.usd (counter, attrs: openclaw.channel, openclaw.provider, openclaw.model)
• openclaw.run.duration_ms (histogram, attrs: openclaw.channel, openclaw.provider, openclaw.model)
• openclaw.context.tokens (histogram, attrs: openclaw.context, openclaw.channel, openclaw.provider, openclaw.model)
• gen_ai.client.token.usage (histogram, GenAI semantic-conventions metric, attrs: gen_ai.token.type = input/output, gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model)
• gen_ai.client.operation.duration (histogram, seconds, GenAI semantic-conventions metric, attrs: gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model, optional error.type)
• openclaw.model_call.duration_ms (histogram, attrs: openclaw.provider, openclaw.model, openclaw.api, openclaw.transport, plus openclaw.errorCategory and openclaw.failureKind on classified errors)
• openclaw.model_call.request_bytes (histogram, UTF-8 byte size of the final model request payload; no raw payload content)
• openclaw.model_call.response_bytes (histogram, UTF-8 byte size of streamed model response events; no raw response content)
• openclaw.model_call.time_to_first_byte_ms (histogram, elapsed time before the first streamed response event)
• openclaw.skill.used (counter, attrs: openclaw.skill.name, openclaw.skill.source, openclaw.skill.activation, optional openclaw.agent, optional openclaw.toolName)

这一小段像旁白，在提醒我们镜头已经切到下一站。

• openclaw.webhook.received (counter, attrs: openclaw.channel, openclaw.webhook)
• openclaw.webhook.error (counter, attrs: openclaw.channel, openclaw.webhook)
• openclaw.webhook.duration_ms (histogram, attrs: openclaw.channel, openclaw.webhook)
• openclaw.message.queued (counter, attrs: openclaw.channel, openclaw.source)
• openclaw.message.received (counter, attrs: openclaw.channel, openclaw.source)
• openclaw.message.dispatch.started (counter, attrs: openclaw.channel, openclaw.source)
• openclaw.message.dispatch.completed (counter, attrs: openclaw.channel, openclaw.outcome, openclaw.reason, openclaw.source)
• openclaw.message.dispatch.duration_ms (histogram, attrs: openclaw.channel, openclaw.outcome, openclaw.reason, openclaw.source)
• openclaw.message.processed (counter, attrs: openclaw.channel, openclaw.outcome)
• openclaw.message.duration_ms (histogram, attrs: openclaw.channel, openclaw.outcome)
• openclaw.message.delivery.started (counter, attrs: openclaw.channel, openclaw.delivery.kind)
• openclaw.message.delivery.duration_ms (histogram, attrs: openclaw.channel, openclaw.delivery.kind, openclaw.outcome, openclaw.errorCategory)

这一小段像旁白，在提醒我们镜头已经切到下一站。

• openclaw.talk.event (counter, attrs: openclaw.talk.event_type, openclaw.talk.mode, openclaw.talk.transport, openclaw.talk.brain, openclaw.talk.provider)
• openclaw.talk.event.duration_ms (histogram, attrs: same as openclaw.talk.event; emitted when a Talk event reports duration)
• openclaw.talk.audio.bytes (histogram, attrs: same as openclaw.talk.event; emitted for Talk audio frame events that report byte length)

这一小段像旁白，在提醒我们镜头已经切到下一站。

• openclaw.queue.lane.enqueue (counter, attrs: openclaw.lane)
• openclaw.queue.lane.dequeue (counter, attrs: openclaw.lane)
• openclaw.queue.depth (histogram, attrs: openclaw.lane or openclaw.channel=heartbeat)
• openclaw.queue.wait_ms (histogram, attrs: openclaw.lane)
• openclaw.session.state (counter, attrs: openclaw.state, openclaw.reason)
• openclaw.session.stuck (counter, attrs: openclaw.state; emitted only for stale session bookkeeping with no active work)
• openclaw.session.stuck_age_ms (histogram, attrs: openclaw.state; emitted only for stale session bookkeeping with no active work)
• openclaw.session.turn.created (counter, attrs: openclaw.agent, openclaw.channel, openclaw.trigger)
• openclaw.session.recovery.requested (counter, attrs: openclaw.state, openclaw.action, openclaw.active_work_kind, openclaw.reason)
• openclaw.session.recovery.completed (counter, attrs: openclaw.state, openclaw.action, openclaw.status, openclaw.active_work_kind, openclaw.reason)
• openclaw.session.recovery.age_ms (histogram, attrs: same as the matching recovery counter)
• openclaw.run.attempt (counter, attrs: openclaw.attempt)

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：diagnostics.stuckSessionWarnMs is the no-progress age threshold for session liveness diagnostics. A processing session…。

diagnostics.stuckSessionWarnMs is the no-progress age threshold for session liveness diagnostics. A processing session does not age toward this threshold while OpenClaw observes reply, tool, status, block, or ACP runtime progress. Typing keepalives are not counted as progress, so a silent model or harness can still be detected.

OpenClaw classifies sessions by the work it can still observe:

still making progress.

recent progress. Stalled embedded runs stay observe-only at first, then abort-drain after diagnostics.stuckSessionAbortMs with no progress so queued turns behind the lane can resume. When unset, the abort threshold defaults to the safer extended window of at least 5 minutes and 3x diagnostics.stuckSessionWarnMs.

the affected session lane immediately.

• session.long_running: active embedded work, model calls, or tool calls are
• session.stalled: active work exists, but the active run has not reported
• session.stuck: stale session bookkeeping with no active work. This releases

Recovery emits structured session.recovery.requested and session.recovery.completed events. Diagnostic session state is marked idle only after a mutating recovery outcome (aborted or released) and only if the same processing generation is still current.

Only session.stuck emits the openclaw.session.stuck counter, the openclaw.session.stuck_age_ms histogram, and the openclaw.session.stuck span. Repeated session.stuck diagnostics back off while the session remains unchanged, so dashboards should alert on sustained increases rather than every heartbeat tick. For the config knob and defaults, see Configuration reference.

这一小段像旁白，在提醒我们镜头已经切到下一站。

• openclaw.harness.duration_ms (histogram, attrs: openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.harness.phase on errors)

这一小段像旁白，在提醒我们镜头已经切到下一站。

• openclaw.exec.duration_ms (histogram, attrs: openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind)

这一小段像旁白，在提醒我们镜头已经切到下一站。

• openclaw.memory.heap_used_bytes (histogram, attrs: openclaw.memory.kind)
• openclaw.memory.rss_bytes (histogram)
• openclaw.memory.pressure (counter, attrs: openclaw.memory.level)
• openclaw.tool.loop.iterations (counter, attrs: openclaw.toolName, openclaw.outcome)
• openclaw.tool.loop.duration_ms (histogram, attrs: openclaw.toolName, openclaw.outcome)

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：When content capture is explicitly enabled, 聪明脑袋模型 and 工具小帮手 spans can also include bounded, redacted openclaw.content.…。

• openclaw.model.usage
• openclaw.channel, openclaw.provider, openclaw.model
• openclaw.tokens.* (input/output/cache_read/cache_write/total)
• gen_ai.system by default, or gen_ai.provider.name when the latest GenAI semantic conventions are opted in
• gen_ai.request.model, gen_ai.operation.name, gen_ai.usage.*
• openclaw.run
• openclaw.outcome, openclaw.channel, openclaw.provider, openclaw.model, openclaw.errorCategory
• openclaw.model.call
• gen_ai.system by default, or gen_ai.provider.name when the latest GenAI semantic conventions are opted in
• gen_ai.request.model, gen_ai.operation.name, openclaw.provider, openclaw.model, openclaw.api, openclaw.transport
• openclaw.errorCategory and optional openclaw.failureKind on errors
• openclaw.model_call.request_bytes, openclaw.model_call.response_bytes, openclaw.model_call.time_to_first_byte_ms
• openclaw.provider.request_id_hash (bounded SHA-based hash of the upstream provider request id; raw ids are not exported)
• openclaw.harness.run
• openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.provider, openclaw.model, openclaw.channel
• On completion: openclaw.harness.result_classification, openclaw.harness.yield_detected, openclaw.harness.items.started, openclaw.harness.items.completed, openclaw.harness.items.active
• On error: openclaw.harness.phase, openclaw.errorCategory, optional openclaw.harness.cleanup_failed
• openclaw.tool.execution
• gen_ai.tool.name, openclaw.toolName, openclaw.errorCategory, openclaw.tool.params.*
• openclaw.exec
• openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind, openclaw.exec.command_length, openclaw.exec.exit_code, openclaw.exec.timed_out
• openclaw.webhook.processed
• openclaw.channel, openclaw.webhook
• openclaw.webhook.error
• openclaw.channel, openclaw.webhook, openclaw.error
• openclaw.message.processed
• openclaw.channel, openclaw.outcome, openclaw.reason
• openclaw.message.delivery
• openclaw.channel, openclaw.delivery.kind, openclaw.outcome, openclaw.errorCategory, openclaw.delivery.result_count
• openclaw.session.stuck
• openclaw.state, openclaw.ageMs, openclaw.queueDepth
• openclaw.context.assembled
• openclaw.prompt.size, openclaw.history.size, openclaw.context.tokens, openclaw.errorCategory (no prompt, history, response, or session-key content)
• openclaw.tool.loop
• openclaw.toolName, openclaw.outcome, openclaw.iterations, openclaw.errorCategory (no loop messages, params, or tool output)
• openclaw.memory.pressure
• openclaw.memory.level, openclaw.memory.heap_used_bytes, openclaw.memory.rss_bytes

When content capture is explicitly enabled, model and tool spans can also include bounded, redacted openclaw.content.* attributes for the specific content classes you opted into.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The events below back the metrics and spans above. 新本领插件s can also subscribe to them directly without OTLP export. **聪明…。

The events below back the metrics and spans above. Plugins can also subscribe to them directly without OTLP export.

**Model usage**

session ids. usage is provider/turn accounting for cost and telemetry; context.used is the current prompt/context snapshot and can be lower than provider usage.total when cached input or tool-loop calls are involved.

• model.usage - tokens, cost, duration, context, provider/model/channel,

**Message flow**

• webhook.received / webhook.processed / webhook.error
• message.queued / message.processed
• message.delivery.started / message.delivery.completed / message.delivery.error

**Queue and session**

• queue.lane.enqueue / queue.lane.dequeue
• session.state / session.long_running / session.stalled / session.stuck
• run.attempt / run.progress
• diagnostic.heartbeat (aggregate counters: webhooks/queue/session)

**Harness lifecycle**

per-run lifecycle for the agent harness. Includes harnessId, optional pluginId, provider/model/channel, and run id. Completion adds durationMs, outcome, optional resultClassification, yieldDetected, and itemLifecycle counts. Errors add phase (prepare/start/send/resolve/cleanup), errorCategory, and optional cleanupFailed.

• harness.run.started / harness.run.completed / harness.run.error -

**Exec**

code, and failure kind. Command text and working directories are not included.

• exec.process.completed - terminal outcome, duration, target, mode, exit

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：You can keep diagnostics events available to 新本领插件s or custom sinks without running diagnostics-otel: For targeted debu…。

You can keep diagnostics events available to plugins or custom sinks without running diagnostics-otel:

{
  diagnostics: { enabled: true },
}

For targeted debug output without raising logging.level, use diagnostics flags. Flags are case-insensitive and support wildcards (e.g. telegram.* or *):

{
  diagnostics: { flags: ["telegram.http"] },
}

Or as a one-off env override:

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

Flag output goes to the standard log file (logging.file) and is still redacted by logging.redactSensitive. Full guide: Diagnostics flags.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：You can also leave diagnostics-otel out of 新本领插件s.allow, or run openclaw 新本领插件s disable diagnostics-otel.

{
  diagnostics: { otel: { enabled: false } },
}

You can also leave diagnostics-otel out of plugins.allow, or run openclaw plugins disable diagnostics-otel.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：---。

• Logging - file logs, console output, CLI tailing, and the Control UI Logs tab
• Gateway logging internals - WS log styles, subsystem prefixes, and console capture
• Diagnostics flags - targeted debug-log flags
• Diagnostics export - operator support-bundle tool (separate from OTEL export)
• Configuration reference - full diagnostics.* field reference

---