OpenTelemetry 导出

• 诊断事件是由 Gateway 网关和内置插件针对模型运行、消息流、会话、队列 和 exec 发出的结构化进程内记录。
• diagnostics-otel 订阅这些事件，并通过 OTLP/HTTP 将其导出为 OpenTelemetry 指标、追踪和日志，还可以 将日志记录镜像到 stdout JSONL。
• 当提供商传输支持自定义标头时，提供商调用会从 OpenClaw 可信的模型调用 span 上下文中接收 W3C traceparent 标头。 插件发出的追踪上下文不会被传播。
• 仅当诊断功能和插件都已启用时才会挂载导出器， 因此默认情况下进程内开销接近于零。

​

快速开始

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

​

导出的信号

​

配置参考

{
  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 会禁用 OTLP 导出
      serviceName: "openclaw-gateway", // 未设置时回退到 OTEL_SERVICE_NAME，然后回退到 "openclaw"
      headers: { "x-collector-token": "..." },
      traces: true,
      metrics: true,
      logs: true,
      logsExporter: "otlp", // otlp | stdout | both
      sampleRate: 0.2, // 根 span 采样器，0.0..1.0
      flushIntervalMs: 60000, // 指标导出间隔（最小 1000ms）
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
        toolDefinitions: false,
      },
    },
  },
}

​

环境变量

​

隐私和内容捕获

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

​

采样和刷新

• 追踪： diagnostics.otel.sampleRate 仅在根 span 上设置一个 TraceIdRatioBasedSampler （0.0 全部丢弃，1.0 全部保留）。未设置时使用 OpenTelemetry SDK 默认值（始终开启）。
• 指标： diagnostics.otel.flushIntervalMs（下限为 1000）；未设置时使用 SDK 的周期性导出默认值。
• 日志： OTLP 日志遵循 logging.level（文件日志级别），并使用 诊断日志记录脱敏路径，而非控制台格式。高流量 安装应优先使用 OTLP 收集器采样/过滤，而不是本地 采样。当你的平台已将 stdout/stderr 发送到日志处理器 且没有 OTLP 日志收集器时，请设置 diagnostics.otel.logsExporter: "stdout"。 stdout 记录每行一个 JSON 对象，其中包含 ts、signal、 service.name、严重性、正文、脱敏后的属性，以及可用时可信的追踪 字段。
• 文件日志关联： 当日志调用携带有效的 诊断追踪上下文时，JSONL 文件日志会包含顶层 traceId、 spanId、parentSpanId 和 traceFlags，使日志处理器能够将本地日志行与 导出的 span 关联起来。
• 请求关联： Gateway 网关 HTTP 请求和 WebSocket 帧会创建 内部请求追踪作用域。该作用域内的日志和诊断事件 默认继承请求追踪，而智能体运行和模型调用 span 会创建为其子项，使提供商 traceparent 标头保持在同一 追踪中。
• 模型调用关联： openclaw.model.call span 默认包含安全的提示词 组件大小，并在提供商结果公开用量时包含每次调用的 token 属性。openclaw.model.usage 仍是运行级 计费 span，用于汇总成本、上下文和渠道仪表板；当发出该 span 的运行时具有可信的 追踪上下文时，它会保持在同一诊断追踪中。

​

模型调用观测单位

• request - 一次可观测的模型/提供商请求。原生嵌入式模型 调用使用此单位；为兼容较旧或外部的发出方，导出器会将缺失值视为 request。
• turn - 一次不透明的智能体 CLI 轮次，其中可能包含隐藏的模型请求、 重试、工具工作或后台工作。Claude Code CLI 和 Codex app-server 调用使用此单位。

​

Claude Code CLI 模型调用保真度

• stdio - 一次性本地 Claude Code 进程。
• stdio-live - 托管的持久 Claude stdio 会话中的一个轮次。
• paired-node-cli - 委托给已配对 节点的一次性 Claude Code 执行。

• openclaw.model_call.request_bytes 是通过一次性 stdin/argv 发送的提示词值， 或托管 stdio JSONL 用户信封的 UTF-8 大小。它 不是 Claude Code 隐藏模型请求的大小。
• openclaw.model_call.response_bytes 是轮次期间观察到的 Claude CLI stdout 的 UTF-8 大小。 它不是 Anthropic HTTP 响应大小。
• openclaw.model_call.time_to_first_byte_ms 是首次观察到 Claude CLI stdout 或 stderr 输出所需的时间。它不是网络 TTFB。

​

导出的指标

​

模型用量

• 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；轮次观测使用 gen_ai.operation.name = invoke_agent）
• openclaw.model_call.duration_ms（直方图，属性：openclaw.provider、openclaw.model、openclaw.api、openclaw.transport、openclaw.model_call.observation_unit，以及分类错误上的 openclaw.errorCategory 和 openclaw.failureKind）
• openclaw.model_call.request_bytes（直方图，最终模型请求负载的 UTF-8 字节大小；对于 Claude Code CLI，指上述可观测的提示词输入/信封；不含原始负载内容）
• openclaw.model_call.response_bytes（直方图，流式响应分块负载的 UTF-8 字节大小；高频文本、思考和工具调用增量仅计算递增的 delta 字节；对于 Claude Code CLI，指观察到的 stdout 字节；不含原始响应内容）
• openclaw.model_call.time_to_first_byte_ms（直方图，首个流式响应事件前经过的时间；对于 Claude Code CLI，指首次可观测的 CLI 输出，而非网络 TTFB）
• 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 音频帧事件发出）

​

队列和会话

• 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（计数器，属性：openclaw.agent、openclaw.channel、openclaw.trigger）
• openclaw.session.recovery.requested（计数器，属性：openclaw.state、openclaw.action、openclaw.active_work_kind、openclaw.reason）
• openclaw.session.recovery.completed（计数器，属性：openclaw.state、openclaw.action、openclaw.status、openclaw.active_work_kind、openclaw.reason）
• openclaw.session.recovery.age_ms（直方图，属性：与对应的恢复计数器相同）
• openclaw.run.attempt（计数器，属性：openclaw.attempt）

​

会话活性遥测

• session.long_running：活跃的嵌入式工作、模型调用或工具调用 仍在取得进展。由所有者管理的无输出模型调用在达到内置中止阈值前也会报告为长时间运行，因此，只要仍可观察中止状态，缓慢或非流式传输的模型提供商就不会看起来像停滞的 Gateway 网关会话。
• session.stalled：存在活跃工作，但活跃运行近期未报告 进度。由所有者管理的模型调用会在达到或超过内置中止阈值时从 session.long_running 切换到 session.stalled；没有所有者的 过期模型/工具活动不会被视为无害的长时间运行工作。 停滞的嵌入式运行最初仅受观察；当超过中止阈值且仍无进度时， 将进入中止排空状态，以便该通道后方排队的轮次可以恢复。
• session.stuck：没有活跃工作的过期会话记录状态，或存在过期且 无所有者模型/工具活动的空闲排队会话。恢复门控通过后，会立即释放 受影响的会话通道。

• openclaw.liveness.warning（计数器，属性：openclaw.liveness.reason）
• openclaw.liveness.event_loop_delay_p99_ms（直方图，属性：openclaw.liveness.reason）
• openclaw.liveness.event_loop_delay_max_ms（直方图，属性：openclaw.liveness.reason）
• openclaw.liveness.event_loop_utilization（直方图，属性：openclaw.liveness.reason）
• openclaw.liveness.cpu_core_ratio（直方图，属性：openclaw.liveness.reason）

​

Harness 生命周期

• openclaw.harness.duration_ms（直方图，属性：openclaw.harness.id、openclaw.harness.plugin、openclaw.outcome，发生错误时还包括 openclaw.harness.phase）

​

工具执行和循环检测

• openclaw.tool.execution.duration_ms（直方图，属性：gen_ai.tool.name、openclaw.toolName、openclaw.tool.source、openclaw.tool.owner、openclaw.tool.params.kind，发生错误时还包括 openclaw.errorCategory）
• openclaw.tool.execution.blocked（计数器，属性：gen_ai.tool.name、openclaw.toolName、openclaw.tool.source、openclaw.tool.owner、openclaw.tool.params.kind、openclaw.deniedReason）
• openclaw.tool.loop（计数器，属性：openclaw.toolName、openclaw.loop.level、openclaw.loop.action、openclaw.loop.detector、openclaw.loop.count，可选 openclaw.loop.paired_tool；检测到重复的工具调用循环时发出）

​

Exec

• openclaw.exec.duration_ms（直方图，属性：openclaw.exec.target、openclaw.exec.mode、openclaw.outcome、openclaw.failureKind）

​

诊断内部机制（内存、载荷、导出器健康状态）

• openclaw.payload.large（计数器，属性：openclaw.payload.surface、openclaw.payload.action、openclaw.channel、openclaw.plugin、openclaw.reason）
• openclaw.payload.large_bytes（直方图，属性：与 openclaw.payload.large 相同）
• openclaw.memory.rss_bytes / openclaw.memory.heap_used_bytes / openclaw.memory.heap_total_bytes / openclaw.memory.external_bytes / openclaw.memory.array_buffers_bytes（直方图，无属性；进程内存样本）
• openclaw.memory.pressure（计数器，属性：openclaw.memory.level、openclaw.memory.reason）
• openclaw.diagnostic.async_queue.dropped（计数器，属性：openclaw.diagnostic.async_queue.drop_class；内部诊断队列背压导致的丢弃）
• openclaw.telemetry.exporter.events（计数器，属性：openclaw.exporter、openclaw.signal、openclaw.status，可选 openclaw.reason、可选 openclaw.errorCategory；导出器生命周期/故障自遥测）

​

导出的 span

• openclaw.model.usage
  • openclaw.channel、openclaw.provider、openclaw.model
  • openclaw.tokens.*（输入/输出/缓存读取/缓存写入/总计）
  • 默认使用 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.model_call.observation_unit（request 或 turn）
  • openclaw.errorCategory、error.type，发生错误时还包括可选的 openclaw.failureKind
  • openclaw.model_call.request_bytes、openclaw.model_call.response_bytes、openclaw.model_call.time_to_first_byte_ms
  • openclaw.model_call.prompt.input_messages_count、openclaw.model_call.prompt.input_messages_chars、openclaw.model_call.prompt.system_prompt_chars、openclaw.model_call.prompt.tool_definitions_count、openclaw.model_call.prompt.tool_definitions_chars、openclaw.model_call.prompt.total_chars（仅包含安全的组件大小，不包含提示词文本）
  • 当结果包含该请求或聚合轮次的用量时，包括 openclaw.model_call.usage.* 和 gen_ai.usage.*
  • 当上游提供商结果公开请求 ID 时，span 事件 openclaw.provider.request 带有属性 openclaw.upstreamRequestIdHash（有界、基于哈希）；绝不会导出原始 ID
  • 使用 OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental 时，请求 span 使用最新的 GenAI 推理 span 名称 {gen_ai.operation.name} {gen_ai.request.model}。轮次 span 使用 invoke_agent，因为 OpenClaw 不会从不透明的 CLI 边界声称原生智能体名称。两者都使用 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、gen_ai.operation.name（execute_tool）、openclaw.toolName、openclaw.tool.source、可选 gen_ai.tool.call.id、openclaw.tool.owner、openclaw.tool.params.*
  • 发生错误时可选 openclaw.errorCategory/openclaw.errorCode，被策略或沙箱拒绝时包括 openclaw.deniedReason 和 openclaw.outcome=blocked
• openclaw.exec
  • openclaw.exec.target、openclaw.exec.mode、openclaw.outcome、openclaw.failureKind、openclaw.exec.command_length、openclaw.exec.exit_code、openclaw.exec.exit_signal、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（不包含提示词、历史记录、响应或会话键内容）
• openclaw.tool.loop
  • openclaw.toolName、openclaw.loop.level、openclaw.loop.action、openclaw.loop.detector、openclaw.loop.count、可选 openclaw.loop.paired_tool（不包含循环消息、参数或工具输出）
• openclaw.memory.pressure
  • openclaw.memory.level、openclaw.memory.reason、openclaw.memory.rss_bytes、openclaw.memory.heap_used_bytes、openclaw.memory.heap_total_bytes、openclaw.memory.external_bytes、openclaw.memory.array_buffers_bytes、可选 openclaw.memory.threshold_bytes/openclaw.memory.rss_growth_bytes/openclaw.memory.window_ms

​

诊断事件目录

• model.usage - token、成本、持续时间、上下文、提供商/模型/渠道、 会话 ID。usage 是用于成本和遥测的提供商/轮次计量； 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
• run.execution_phase（公开的、与会话关联的嵌入式运行器启动里程碑）
• diagnostic.heartbeat（聚合计数器：webhook/队列/会话）

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

• exec.process.completed - 终端结果、持续时间、目标、模式、退出 代码和失败类型。不包括命令文本和工作目录。
• exec.approval.followup_suppressed - 会话重新绑定后丢弃的过期审批后续操作。 包括 approvalId、reason （session_rebound）、phase（direct_delivery 或 gateway_preflight） 以及调度器时间戳。不包括会话键、路由和命令文本。

​

不使用导出器

{
  diagnostics: { enabled: true },
}

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

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

​

禁用

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

​

相关内容

• 日志 - 文件日志、控制台输出、CLI 尾随查看以及 Control UI 的 Logs 选项卡
• Gateway 网关日志内部机制 - WS 日志样式、子系统前缀和控制台捕获
• 诊断标志 - 有针对性的调试日志标志
• 诊断导出 - 面向操作员的支持包工具（与 OTEL 导出分开）
• 配置参考 - 完整的 diagnostics.* 字段参考