OpenTelemetry 导出

• 诊断事件是结构化的进程内记录，由 Gateway 和捆绑插件针对模型运行、消息流、会话、队列和执行操作发出。
• diagnostics-otel 订阅这些事件，并通过 OTLP/HTTP 将其导出为 OpenTelemetry 指标、追踪和日志，还可以将日志记录镜像到 stdout JSONL。
• 当提供商传输接受自定义请求头时，提供商调用会从实际当前的 OpenTelemetry 模型调用 span 接收 W3C traceparent 请求头。诊断 ID 仍是本地关联键，并且不会传播插件发出的追踪上下文。
• 只有在诊断面和插件均启用时，导出器才会挂载，因此默认情况下进程内开销接近于零。

​

快速开始

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

​

导出的信号

​

哪些进程会导出

• Gateway 会在启动时启动导出器，并为其执行的每次运行从 Gateway 进程中导出，包括分派给它的 openclaw agent 运行。
• 一次性本地运行（openclaw agent --local）在 CLI 进程中执行。当配置了 OTel 导出且插件已启用时，同一个 CLI 进程会为 此次运行启动一个导出器实例，并在进程退出前刷新缓冲的 span、指标和日志。 CLI 最多等待 5 秒以排空诊断事件队列，随后再等待 10 秒进行刷新，因此无法访问的收集器不会阻塞命令。接受连接但始终不响应的收集器仍可能使退出延迟，直到导出器自身的请求超时时间 （OTEL_EXPORTER_OTLP_TIMEOUT）到达。 在 JSON 输出模式下，这些一次性运行只会抑制 stdout JSONL 日志 sink，以便命令 stdout 保留给 JSON 响应；配置后，OTLP traces、 metrics 和 logs 仍会继续导出。
• openclaw agent exec 同样会在 CLI 进程中嵌入运行 agent，但目前 尚未启动此导出器，因此其运行不会导出任何遥测数据。需要从无头运行中获取 traces 时，请通过 Gateway 分派，或使用 openclaw agent --local。

​

导出器健康状态

• 配置或 OTEL_* 环境变量回退机制提供端点的 OTLP/HTTP protobuf。
• 未提供端点时使用导出器依赖项默认端点的 OTLP/HTTP protobuf。
• 标准输出日志导出。
• 由外部预加载的 OpenTelemetry SDK 所拥有的跟踪或指标导出。

​

配置参考

{
  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",
      serviceName: "openclaw-gateway", // 未设置时回退到 OTEL_SERVICE_NAME，然后回退到 "openclaw"
      metricNamePrefix: "acme.", // 可选；包含分隔符
      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: false,
    },
  },
}

​

环境变量

​

继续上游 WebSocket 追踪

{
  "type": "req",
  "id": "eval-item-42",
  "method": "agent",
  "params": {},
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

​

隐私与内容捕获

​

采样和刷新

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

​

模型调用观测单元

• request - 一个可观测的模型/提供商请求。原生嵌入式模型调用使用此单元，并且为兼容较旧版本或外部发射器，导出器会将缺失值视为 request。
• turn - 一个不透明的 agent 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 发送的 prompt 值的 UTF-8 大小，或受管理 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）

​

语音对话

• 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：活跃的嵌入式工作、模型调用或工具调用仍在取得进展。由系统拥有的静默模型调用在达到内置中止阈值之前也会报告为长期运行，因此在可观测到中止之前，运行缓慢或不进行流式传输的模型提供商不会被视为停滞的网关会话。
• 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；当检测到重复的工具调用循环时发出）

​

执行

• 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；导出器生命周期/失败自遥测）

​

导出的 spans

• openclaw.model.usage
  • openclaw.channel、openclaw.provider、openclaw.model
  • 仅适用于受信任插件运行时完成的、可选的源自主机的 openclaw.plugin
  • 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.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 时，使用属性 openclaw.upstreamRequestIdHash（有界、基于哈希）记录 Span 事件 openclaw.provider.request；绝不会导出原始 ID
  • 当设置 OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental 时，请求 spans 使用最新 GenAI 推理 span 名称 {gen_ai.operation.name} {gen_ai.request.model}。由于 OpenClaw 不会从不透明的 CLI 边界声明原生 agent 名称，回合 spans 使用 invoke_agent。两者都使用 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（不包含提示词、历史、响应或 session-key 内容）
• 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

​

诊断事件目录

{
  "type": "model.usage",
  "ts": 1735689600000,
  "seq": 42,
  "provider": "openai",
  "model": "gpt-5.4",
  "channel": "webchat",
  "agentId": "main",
  "sessionId": "session-123",
  "sessionKey": "agent:main:main",
  "usage": {
    "input": 120,
    "output": 40,
    "cacheRead": 30,
    "cacheWrite": 10,
    "promptTokens": 160,
    "total": 200
  },
  "lastCallUsage": {
    "input": 120,
    "output": 40,
    "cacheRead": 30,
    "cacheWrite": 10,
    "total": 200
  },
  "context": { "limit": 128000, "used": 160 },
  "costUsd": 0.0012,
  "durationMs": 850,
  "trace": {
    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "spanId": "00f067aa0ba902b7",
    "traceFlags": "01"
  }
}

• ts 是以毫秒为单位的 Unix 时间戳；seq 是进程本地的序列号。
• usage 保存单轮的令牌计数。promptTokens 包含 input、 cacheRead 和 cacheWrite；如果可用，lastCallUsage 描述 最终的模型调用。
• context.used 是当前提示词/上下文快照；当涉及缓存输入或工具循环调用时， 它可能低于 usage.total。
• 提供方/模型/会话标识符、令牌分桶、lastCallUsage、 context、costUsd、durationMs 和 trace 字段均为可选。 costUsd 是估算值；当模型定价不可用时可能缺失， 它并非提供方报告的计费金额。Trace 上下文还可以包含 parentSpanId。

openclaw gateway call sessions.usage --params '{"range":"30d","agentScope":"all"}' --json
openclaw gateway usage-cost --days 30 --all-agents --json

• 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 - 每次运行的 agent 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 } },
}

OTEL_SDK_DISABLED=true openclaw gateway

​

相关内容

• 日志记录 - 文件日志、控制台输出、CLI 尾随，以及 Control UI 的日志选项卡
• 网关日志内部机制 - WS 日志样式、子系统前缀和控制台捕获
• 诊断标志 - 定向调试日志标志
• 诊断导出 - 运维支持包工具（独立于 OTEL 导出）
• 配置参考 - 完整的 diagnostics.* 字段参考