OpenTelemetry 导出

OpenClaw 通过官方 OpenClawdiagnostics-otel 插件导出诊断信息，使用 OTLP/HTTP (protobuf)。任何接受 OTLP/HTTP 的收集器或后端都可以无需更改代码地工作。有关本地文件日志及其读取方法，请参阅日志记录。

如何协同工作

诊断事件 是由 Gateway(网关) 和捆绑插件为模型运行、消息流、会话、队列和 exec 发出的结构化进程内记录。
diagnostics-otel 插件 订阅这些事件，并通过 OTLP/HTTP 将其作为 OpenTelemetry 指标、追踪和日志导出。
当提供商传输接受自定义标头时，提供商调用 会从 OpenClaw 受信任的模型调用 span 上下文中接收 W3C traceparentOpenClaw 标头。插件发出的追踪上下文不会被传播。
只有当诊断表面和插件都启用时，导出器才会附加，因此默认情况下进程内成本接近于零。

快速开始

对于打包安装，请先安装插件：

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,
    },
  },
}

您也可以从 CLI 启用该插件：

openclaw plugins enable diagnostics-otel

导出的 Signal

Signal	包含内容
指标	用于 token 使用量、成本、运行持续时间、故障转移、技能使用、消息流、Talk 事件、队列通道、会话状态/恢复、工具执行、超大负载、exec 和内存压力的计数器和直方图。
追踪	用于模型使用情况、模型调用、harness 生命周期、技能使用、工具执行、exec、webhook/消息处理、上下文组装和工具循环的 Spans。
日志	当 `diagnostics.otel.logs` 启用时，通过 OTLP 导出的结构化 `logging.file` 记录；除非明确启用了内容捕获，否则保留日志正文。

独立切换 traces、metrics 和 logs。当 diagnostics.otel.enabled 为 true 时，Traces 和 metrics 默认开启。Logs 默认关闭，仅当 diagnostics.otel.logs 被显式设置为 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,
        toolDefinitions: false,
      },
    },
  },
}

环境变量

变量	用途
`OTEL_EXPORTER_OTLP_ENDPOINT`	覆盖 `diagnostics.otel.endpoint`。如果该值已包含 `/v1/traces`、`/v1/metrics` 或 `/v1/logs`，则将按原样使用。
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	当匹配的 Signal`diagnostics.otel.*Endpoint`Signal 配置键未设置时使用的特定 Signal 端点覆盖。特定 Signal 的配置优先于特定 Signal 的环境变量，后者又优先于共享端点。
`OTEL_SERVICE_NAME`	覆盖 `diagnostics.otel.serviceName`。
`OTEL_EXPORTER_OTLP_PROTOCOL`	覆盖线路协议（目前仅 `http/protobuf` 有效）。
`OTEL_SEMCONV_STABILITY_OPT_IN`	设置为 `gen_ai_latest_experimental` 以发出最新的实验性 GenAI 推理 span 形状，包括 `{gen_ai.operation.name} {gen_ai.request.model}` span 名称、`CLIENT` span 类型和 `gen_ai.provider.name`，而不是传统的 `gen_ai.system`。无论如何，GenAI 指标始终使用有界的低基数语义属性。
`OPENCLAW_OTEL_PRELOADED`	当另一个预加载或主机进程已注册全局 OpenTelemetry SDK 时，设置为 `1`。该插件随后将跳过其自身的 NodeSDK 生命周期，但仍会连接诊断侦听器并遵守 `traces`/`metrics`/`logs`。

隐私和内容捕获

默认情况下不导出原始模型/工具内容。Span 携带受限标识符（渠道、提供商、模型、错误类别、仅哈希的请求 ID、工具来源、工具所有者以及技能名称/来源），绝不包含提示文本、响应文本、工具输入、工具输出、技能文件路径或会话密钥。 OTLP 日志记录默认保留严重性、记录器、代码位置、可信跟踪上下文和已清理的属性，但仅当 diagnostics.otel.captureContent 设置为布尔值 true 时，才会导出原始日志消息正文。细粒度的 captureContent.* 子键不会启用日志正文。看起来像限定范围的代理会话密钥的标签将替换为 unknown。 Talk 指标仅导出受限的事件元数据（如模式、传输、提供商和事件类型）。它们不包括脚本、音频负载、会话 ID、轮次 ID、调用 ID、房间 ID 或移交令牌。

出站模型请求可能包含 W3C traceparent 标头。该标头仅根据当前模型调用的 OpenClaw 拥有的诊断跟踪上下文生成。现有的调用方提供的 traceparent 标头将被替换，因此插件或自定义提供商选项无法欺骗跨服务跟踪谱系。

仅当您的收集器和保留策略已获准处理提示、响应、工具或系统提示文本时，才将 diagnostics.otel.captureContent.* 设置为 true。每个子键都是独立选择加入的：

inputMessages - 用户提示内容。
outputMessages - 模型响应内容。
toolInputs - 工具参数负载。
toolOutputs - 工具结果负载。
systemPrompt - 已组装的系统/开发者提示。
toolDefinitions - 模型工具名称、描述和架构。

当启用任何子键时，模型和工具跨度将获得仅针对该类别的有界、已编辑的 openclaw.content.* 属性。仅当 OTLP 日志消息正文也被批准导出时，才将布尔 captureContent: true 用于广泛的诊断捕获。

采样和刷新

Traces: diagnostics.otel.sampleRate (仅限根跨度，0.0 丢弃全部， 1.0 保留全部)。
Metrics: diagnostics.otel.flushIntervalMs (最少 1000)。
Logs: OTLP 日志遵循 logging.level (文件日志级别)。它们使用诊断日志记录编辑路径，而不是控制台格式化。高容量安装应优先选择 OTLP 收集器采样/过滤而不是本地采样。
File-log correlation: 当日志调用携带有效的诊断追踪上下文时，JSONL 文件日志包含顶级 traceId、 spanId、parentSpanId 和 traceFlags，这使得日志处理器可以将本地日志行与导出的跨度连接起来。
Request correlation: Gateway(网关) HTTP 请求和 WebSocket 帧创建一个内部请求追踪范围。该范围内的日志和诊断事件默认继承请求追踪，而代理运行和模型调用跨度作为子项创建，因此提供商 traceparent 标头保持在同一追踪上。

导出的指标

模型使用情况

openclaw.tokens (计数器，属性： openclaw.token， openclaw.channel， openclaw.provider， openclaw.model， openclaw.agent)
openclaw.cost.usd (计数器，属性： openclaw.channel， openclaw.provider， openclaw.model)
openclaw.run.duration_ms (直方图，属性： openclaw.channel， openclaw.provider， openclaw.model)
openclaw.context.tokens (直方图，属性： openclaw.context， openclaw.channel， openclaw.provider， openclaw.model)
gen_ai.client.token.usage（直方图，GenAI 语义约定指标，属性：gen_ai.token.type = input/output、gen_ai.provider.name、gen_ai.operation.name、gen_ai.request.model）
gen_ai.client.operation.duration（直方图，秒，GenAI 语义约定指标，属性：gen_ai.provider.name、gen_ai.operation.name、gen_ai.request.model，可选 error.type）
openclaw.model_call.duration_ms（直方图，属性：openclaw.provider、openclaw.model、openclaw.api、openclaw.transport，此外在已分类错误上还有 openclaw.errorCategory 和 openclaw.failureKind）
openclaw.model_call.request_bytes（直方图，最终模型请求负载的 UTF-8 字节大小；不包含原始负载内容）
openclaw.model_call.response_bytes (直方图，流式模型响应事件的 UTF-8 字节大小，不包括增量事件上累积的 partial 快照；无原始响应内容)
openclaw.model_call.time_to_first_byte_ms (直方图，首次流式响应事件之前的经过时间)
openclaw.model.failover (计数器，属性：openclaw.provider, openclaw.model, openclaw.failover.to_provider, openclaw.failover.to_model, openclaw.failover.reason, openclaw.failover.suspended, openclaw.lane)
openclaw.skill.used (计数器，属性：openclaw.skill.name, openclaw.skill.source, openclaw.skill.activation, 可选 openclaw.agent, 可选 openclaw.toolName)

消息流

openclaw.webhook.received (计数器，属性：openclaw.channel, openclaw.webhook)
openclaw.webhook.error (计数器，属性：openclaw.channel, openclaw.webhook)
openclaw.webhook.duration_ms (直方图，属性：openclaw.channel, openclaw.webhook)
openclaw.message.queued (计数器，属性：openclaw.channel, openclaw.source)
openclaw.message.received (计数器，属性：openclaw.channel, openclaw.source)
openclaw.message.dispatch.started (计数器，属性：openclaw.channel, openclaw.source)
openclaw.message.dispatch.completed (计数器，属性：openclaw.channel, openclaw.outcome, openclaw.reason, openclaw.source)
openclaw.message.dispatch.duration_ms (直方图，属性：openclaw.channel、openclaw.outcome、openclaw.reason、openclaw.source)
openclaw.message.processed (计数器，属性：openclaw.channel、openclaw.outcome)
openclaw.message.duration_ms (直方图，属性：openclaw.channel、openclaw.outcome)
openclaw.message.delivery.started (计数器，属性：openclaw.channel、openclaw.delivery.kind)
openclaw.message.delivery.duration_ms (直方图，属性：openclaw.channel、openclaw.delivery.kind、openclaw.outcome、openclaw.errorCategory)

Talk

openclaw.talk.event (计数器，属性：openclaw.talk.event_type、openclaw.talk.mode、openclaw.talk.transport、openclaw.talk.brain、openclaw.talk.provider)
openclaw.talk.event.duration_ms (直方图，属性：与 openclaw.talk.event 相同；当 Talk 事件报告持续时间时发出)
openclaw.talk.audio.bytes (直方图，属性：与 openclaw.talk.event 相同；为报告字节长度的 Talk 音频帧事件发出)

Queues and sessions

openclaw.queue.lane.enqueue (计数器，属性：openclaw.lane)
openclaw.queue.lane.dequeue (计数器，属性：openclaw.lane)
openclaw.queue.depth (直方图，属性：openclaw.lane 或 openclaw.channel=heartbeat)
openclaw.queue.wait_ms (直方图，属性：openclaw.lane)
openclaw.session.state (计数器，属性：openclaw.state、openclaw.reason)
openclaw.session.stuck (计数器，属性：openclaw.state；为可恢复的陈旧会话簿记发出)
openclaw.session.stuck_age_ms (直方图，属性：openclaw.state；为可恢复的陈旧会话簿记发出)
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: 与匹配的恢复计数器相同)
openclaw.run.attempt (counter, attrs: openclaw.attempt)

会话活跃性遥测

diagnostics.stuckSessionWarnMs 是会话活动性诊断的无进展年龄阈值。当 OpenClaw 观察到回复、工具、状态、块或 ACP 运行时进展时，processing 会话不会向此阈值老化。输入保活信号不计为进展，因此仍可检测到静默模型或线束。

OpenClaw 根据其仍能观察到的工作对会话进行分类：

session.long_running：活动的嵌入式工作、模型调用或工具调用仍在取得进展。
session.stalled：存在活动工作，但活动运行未报告近期进展。停滞的嵌入式运行最初保持仅观察状态，然后在 diagnostics.stuckSessionAbortMs 无进展后中止排空，以便队列后的轮次可以恢复。如果未设置，中止阈值默认为更安全的扩展窗口，即至少 5 分钟和 3 倍的 diagnostics.stuckSessionWarnMs。
session.stuck：没有活动工作的过时会话簿记，或具有陈旧无主模型/工具活动的空闲排队会话。这会在恢复门通过后立即释放受影响的会话通道。

恢复会发出结构化的 session.recovery.requested 和 session.recovery.completed 事件。诊断会话状态仅在发生变更恢复结果（aborted 或 released）之后且仅当相同的处理世代仍然当前时，才标记为空闲。

只有 session.stuck 会发出 openclaw.session.stuck 计数器、 openclaw.session.stuck_age_ms 直方图和 openclaw.session.stuck span。当会话保持不变时，重复的 session.stuck 诊断会退避，因此仪表板应对持续增加发出警报，而不是每次心跳跳变。有关配置旋钮和默认值，请参阅 Configuration reference。

存活度警告还会发出：

openclaw.liveness.warning (counter, attrs: openclaw.liveness.reason)
openclaw.liveness.event_loop_delay_p99_ms (histogram, attrs: openclaw.liveness.reason)
openclaw.liveness.event_loop_delay_max_ms (histogram, attrs: openclaw.liveness.reason)
openclaw.liveness.event_loop_utilization (histogram, attrs: openclaw.liveness.reason)
openclaw.liveness.cpu_core_ratio (histogram, attrs: openclaw.liveness.reason)

Harness 生命周期

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

工具执行

openclaw.tool.execution.duration_ms (histogram, attrs: gen_ai.tool.name, openclaw.toolName, openclaw.tool.source, openclaw.tool.owner, openclaw.tool.params.kind, plus openclaw.errorCategory on errors)
openclaw.tool.execution.blocked (counter, attrs: gen_ai.tool.name, openclaw.toolName, openclaw.tool.source, openclaw.tool.owner, openclaw.tool.params.kind, openclaw.deniedReason)

Exec

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

诊断内部机制（内存和工具循环）

openclaw.payload.large (counter, attrs: openclaw.payload.surface, openclaw.payload.action, openclaw.channel, openclaw.plugin, openclaw.reason)
openclaw.payload.large_bytes (histogram, attrs: same as openclaw.payload.large)
openclaw.memory.heap_used_bytes（直方图，属性：openclaw.memory.kind）
openclaw.memory.rss_bytes（直方图）
openclaw.memory.pressure（计数器，属性：openclaw.memory.level）
openclaw.tool.loop.iterations（计数器，属性：openclaw.toolName，openclaw.outcome）
openclaw.tool.loop.duration_ms（直方图，属性：openclaw.toolName，openclaw.outcome）

导出的 Span

openclaw.model.usage
- openclaw.channel，openclaw.provider，openclaw.model
- openclaw.tokens.*（input/output/cache_read/cache_write/total）
- 默认为 gen_ai.system，或在选择启用最新的 GenAI 语义约定时为 gen_ai.provider.name
- 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，或在选择启用最新的 GenAI 语义约定时为 gen_ai.provider.name
- gen_ai.request.model，gen_ai.operation.name，openclaw.provider，openclaw.model，openclaw.api，openclaw.transport
- 错误时的 openclaw.errorCategory 和可选的 openclaw.failureKind
- openclaw.model_call.request_bytes，openclaw.model_call.response_bytes，openclaw.model_call.time_to_first_byte_ms
- openclaw.provider.request_id_hash（上游提供商请求 ID 的有界 SHA 哈希；原始 ID 不会被导出）
- 使用 OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental 时，模型调用 span 使用最新的 GenAI 推理 span 名称 {gen_ai.operation.name} {gen_ai.request.model} 和 CLIENT span 类型，而不是 openclaw.model.call。
openclaw.harness.run
- openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.provider, openclaw.model, openclaw.channel
- 完成时：openclaw.harness.result_classification, openclaw.harness.yield_detected, openclaw.harness.items.started, openclaw.harness.items.completed, openclaw.harness.items.active
- 错误时：openclaw.harness.phase, openclaw.errorCategory, 可选 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（无 prompt、history、response 或会话-key 内容）
openclaw.tool.loop
- openclaw.toolName, openclaw.outcome, openclaw.iterations, openclaw.errorCategory（无 loop messages、params 或工具 output）
openclaw.memory.pressure
- openclaw.memory.level, openclaw.memory.heap_used_bytes, openclaw.memory.rss_bytes

当明确启用内容捕获时，模型和工具跨度还可以包含针对您选择启用的特定内容类的受限、经过编辑的 openclaw.content.* 属性。

诊断事件目录

以下事件支持上述指标和跨度。插件也可以直接订阅这些事件，而无需通过 OTLP 导出。

模型使用情况

model.usage - tokens、cost、duration、context、提供商/模型/渠道、会话 id。usage 是用于成本和遥测的提供商/turn 计数；context.used 是当前的提示/上下文快照，当涉及缓存输入或工具循环调用时，它可能低于提供商 usage.total。

消息流

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

队列和会话

queue.lane.enqueue / queue.lane.dequeue
session.state / session.long_running / session.stalled / session.stuck
run.attempt / run.progress
diagnostic.heartbeat（聚合计数器：webhooks/queue/会话）

Harness 生命周期

harness.run.started / harness.run.completed / harness.run.error - agent harness 的每次运行生命周期。包括 harnessId、可选的 pluginId、提供商/模型/渠道和运行 id。完成时会添加 durationMs、outcome、可选的 resultClassification、yieldDetected 和 itemLifecycle 计数。错误会添加 phase (prepare/start/send/resolve/cleanup)、errorCategory 和可选的 cleanupFailed。

Exec

exec.process.completed - 终止结果、持续时间、目标、模式、退出代码和失败类型。不包含命令文本和工作目录。

不使用导出器

您可以让诊断事件可供插件或自定义接收器使用，而无需运行 diagnostics-otel：

{
  diagnostics: { enabled: true },
}

要获取定向调试输出而不引发 logging.level，请使用诊断标志。标志不区分大小写并支持通配符（例如 telegram.* 或 *）：

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

或者作为一次性的环境变量覆盖：

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

标志输出将进入标准日志文件（logging.file），并且仍会由 logging.redactSensitive 进行编辑。完整指南：Diagnostics flags。

禁用

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

您也可以将 diagnostics-otel 排除在 plugins.allow 之外，或者运行 openclaw plugins disable diagnostics-otel。