OpenTelemetry 导出

OpenClaw 通过官方 diagnostics-otel 插件导出诊断数据， 使用 OTLP/HTTP（protobuf）。日志也可以写入 stdout JSONL，供 容器和沙箱日志管道使用。任何接受 OTLP/HTTP 的收集器或后端都无需更改代码即可使用。有关本地文件日志，请参阅 日志。

• 诊断事件是由 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,    },  },}

或者通过 CLI 启用该插件：openclaw plugins enable diagnostics-otel。

导出的信号

可以单独切换 traces、metrics 和 logs。当 diagnostics.otel.enabled 为 true 时，追踪和指标默认开启；日志默认关闭， 仅当 diagnostics.otel.logs 显式设为 true 时才会导出。日志默认通过 OTLP 导出；将 diagnostics.otel.logsExporter 设为 stdout 可输出 stdout JSONL，设为 both 则同时使用两者。

配置参考

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

环境变量

隐私和内容捕获

默认情况下，不会导出原始模型/工具内容。span 仅携带有界标识符 （渠道、提供商、模型、错误类别、仅哈希形式的请求 ID、工具来源、工具所有者、 技能名称/来源），绝不包含提示词文本、响应文本、工具输入、工具输出、技能文件路径 或会话键。看起来像带作用域的智能体会话键的值（例如以 agent: 开头）在低基数属性中会被替换为 unknown。默认情况下，OTLP 日志 记录会保留严重级别、记录器、代码位置、可信追踪上下文和经过清理的属性； 仅当 diagnostics.otel.captureContent 为布尔值 true 时才会导出原始日志消息正文。 细粒度的 captureContent.* 子键永远不会启用日志正文。Talk 指标仅导出 有界事件元数据（模式、传输方式、提供商、事件类型），不包含文字记录、音频载荷、 会话 ID、轮次 ID、调用 ID、房间 ID 或交接令牌。

出站模型请求可能包含一个 W3C traceparent 标头，该标头仅根据 当前模型调用的 OpenClaw 自有诊断追踪上下文生成。现有调用方提供的 traceparent 标头会被替换，因此插件或自定义提供商选项无法伪造 跨服务追踪祖先关系。

仅当你的收集器和保留策略已获准处理提示词、响应、工具或系统提示词文本时， 才将 diagnostics.otel.captureContent.* 设为 true。各子键相互独立：

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

启用任何子键后，模型和工具 span 只会获得该类别的有界、已脱敏 openclaw.content.* 属性。

内置智能体运行时的工具执行会捕获 toolInputs/toolOutputs 内容 （完成/错误 span 上的 openclaw.content.tool_input 和 gen_ai.tool.call.arguments；完成 span 上的 openclaw.content.tool_output 和 gen_ai.tool.call.result）。 openclaw.content.* 名称仍是稳定的 OpenClaw 属性名称； gen_ai.tool.call.* 副本则为采用语义约定原生格式的查看器提供镜像。 外部 harness 工具调用（Codex、Claude CLI）会发出不含内容载荷的 tool.execution.* span。捕获的内容通过仅限监听器的可信渠道传输， 绝不会放到公共诊断事件总线上。

采样和刷新

• 链路追踪： 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 的运行时具有可信链路追踪上下文时，它会保持在 同一条诊断链路追踪上。

已导出的指标

模型用量

• 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 字节大小；高频文本、思考和工具调用增量仅计算增量 delta 字节；不包含原始响应内容）
• 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 音频帧事件发出）

队列和会话

• 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）

会话活跃性遥测

diagnostics.stuckSessionWarnMs 是会话活跃性诊断的无进展时长阈值。 当 OpenClaw 观察到回复、工具、状态、分块或 ACP 运行时 进展时，processing 会话不会朝此阈值累积时长。输入状态保活不算作进展， 因此仍可检测到静默的模型或 harness。

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

• session.long_running：活跃的嵌入式工作、模型调用或工具调用 仍在取得进展。静默时间超过 diagnostics.stuckSessionWarnMs 的归属明确模型调用，在达到 diagnostics.stuckSessionAbortMs 前也会报告为长时间运行，因此缓慢或非流式模型提供商 在仍可观察到中止状态时不会表现为停滞的 Gateway 网关会话。
• session.stalled：存在活跃工作，但活跃运行近期未报告 进展。归属明确的模型调用会在达到或超过 diagnostics.stuckSessionAbortMs 时从 session.long_running 切换到 session.stalled；无归属的过期模型/工具活动不会被视为无害的长时间运行工作。 停滞的嵌入式运行起初仅保持观察；随后，如果达到 diagnostics.stuckSessionAbortMs 且无进展，则执行中止并排空， 使该通道后方排队的轮次可以恢复。当未设置时，中止阈值默认为更安全的 扩展时间窗口，即至少 5 分钟且为 diagnostics.stuckSessionWarnMs 的 3 倍。
• 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 诊断会退避，因此仪表板应对持续增长发出警报， 而不是对每次 Heartbeat 触发发出警报。有关配置项和默认值，请参阅 配置参考。

活跃性警告还会发出：

• 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.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（有界、基于哈希）的跨度事件 openclaw.provider.request；绝不导出原始 ID
  • 使用 OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental 时，模型调用跨度使用最新的 GenAI 推理跨度名称 {gen_ai.operation.name} {gen_ai.request.model} 和 CLIENT 跨度类型，而不是 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

明确启用内容捕获后，模型和工具跨度还可以针对你选择启用的特定内容类别，包含有界且经过脱敏处理的 openclaw.content.* 属性。

诊断事件目录

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

模型用量

• model.usage - 令牌、成本、持续时间、上下文、提供商/模型/渠道、会话 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
• diagnostic.heartbeat（汇总计数器：Webhook/队列/会话）

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 - 终端结果、持续时间、目标、模式、退出 代码和失败类型。不包含命令文本和工作目录。
• exec.approval.followup_suppressed - 会话重新绑定后丢弃过期的审批后续操作。 包含 approvalId、reason （session_rebound）、phase（direct_delivery 或 gateway_preflight） 和分派器时间戳。不包含会话键、路由和命令文本。

不使用导出器

无需运行 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: { otel: { enabled: false } },}

或者不在 plugins.allow 中加入 diagnostics-otel，也可以运行 openclaw plugins disable diagnostics-otel。

相关内容

• 日志 - 文件日志、控制台输出、CLI 尾部追踪和 Control UI 的 Logs 标签页
• Gateway 网关日志内部机制 - WS 日志样式、子系统前缀和控制台捕获
• 诊断标志 - 针对性的调试日志标志
• 诊断导出 - 操作员支持包工具（独立于 OTEL 导出）
• 配置参考 - 完整的 diagnostics.* 字段参考