配置

导出的信号¶

信号	包含内容
指标	用于 token 用量、成本、运行时长、故障转移、技能使用、消息流、Talk 事件、队列通道、会话状态/恢复、工具执行、exec、内存、存活性以及导出器健康的计数器/直方图。
追踪	用于模型使用、模型调用、harness 生命周期、技能使用、工具执行、exec、webhook/消息处理、上下文组装和工具循环的跨度。
日志	当 `diagnostics.otel.logs` 启用时，通过 OTLP 或 stdout JSONL 导出的结构化 `logging.file` 记录；除非显式启用内容捕获，否则不包含日志正文。

可独立切换 traces、metrics 和 logs。当 diagnostics.otel.enabled 为 true 时，追踪和指标默认开启；日志默认关闭，仅在 diagnostics.otel.logs 显式设为 true 时导出。日志导出默认为 OTLP；将 diagnostics.otel.logsExporter 设置为 stdout 可在 stdout 上输出 JSONL，或设置为 both 同时输出两者。

Note

共享的 endpoint 和 OTEL_EXPORTER_OTLP_ENDPOINT 是所有已启用信号的基础。OpenClaw 会在根路径和自定义收集器路径后附加 /v1/traces、/v1/metrics 或 /v1/logs。为与托管前端兼容，如果共享端点已以这些信号路径之一结尾，则对其匹配的信号保留该路径，并为其他信号替换末尾路径段。

信号特定的 tracesEndpoint、metricsEndpoint 和 logsEndpoint 设置，以及对应的 OTEL_EXPORTER_OTLP_*_ENDPOINT 回退值，会作为精确 URL 传递给导出器。OpenClaw 不会追加或重写这些路径。

配置参考¶

{
  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", // unset falls back to OTEL_SERVICE_NAME, then "openclaw"
      metricNamePrefix: "acme.", // optional; include the separator
      headers: { "x-collector-token": "..." },
      traces: true,
      metrics: true,
      logs: true,
      logsExporter: "otlp", // otlp | stdout | both
      sampleRate: 0.2, // root-span sampler, 0.0..1.0
      flushIntervalMs: 60000, // metric export interval (min 1000ms)
      captureContent: false,
    },
  },
}

metricNamePrefix 仅对 OpenClaw 自有指标替换默认的 openclaw. 前缀。例如，"acme." 会将 openclaw.tokens 导出为 acme.tokens；将其设置为 "" 可导出不带前缀的 tokens。非空值必须以 ASCII 字母开头，只能包含字母、数字、下划线、点、连字符和斜杠，且长度最多为 128 个字符。如果你希望得到 acme.openclaw.tokens，请将其设置为 "acme.openclaw."。标准语义约定指标（如 gen_ai.client.token.usage 和 gen_ai.client.operation.duration）保留其原始名称。保持该选项未设置可保留所有当前指标名称。启用或更改此选项会重命名受影响的指标序列，因此请更新查询旧名称的仪表盘、告警和记录规则。

环境变量¶

变量	用途
`OTEL_EXPORTER_OTLP_ENDPOINT`	当配置键未设置时，作为 `diagnostics.otel.endpoint` 的回退值。
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	信号特定的端点回退值，当对应的 `diagnostics.otel.*Endpoint` 配置键未设置时使用。信号特定配置优先于信号特定环境变量，后者优先于共享端点。
`OTEL_SERVICE_NAME`	当配置键未设置时，作为 `diagnostics.otel.serviceName` 的回退值。默认服务名为 `openclaw`。
`OTEL_EXPORTER_OTLP_PROTOCOL`	当 `diagnostics.otel.protocol` 和信号专用协议变量均未设置时，使用的共享进程环境回退值。只有 `http/protobuf` 会启用插件自有的 OTLP 导出器。
`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` / `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` / `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL`	当 `diagnostics.otel.protocol` 未设置时，使用的信号专用协议回退值。非空的信号专用值优先于共享协议值。不支持的取值只会禁用对应的插件自有 OTLP 信号。
`OTEL_PROPAGATORS`	为每个插件自有的 generation 注册的传播器，包括在 `OTEL_SDK_DISABLED=true` 时。默认为 `tracecontext,baggage`；`none` 会禁用自动传播。取值不区分大小写。不可用的取值及已弃用的 `jaeger` 用法会发出插件警告。
`OTEL_SDK_DISABLED`	不区分大小写的 `true` 会在端点、协议或 TLS 设置之前禁用所有插件自有的 trace、metric、log 和 stdout 路由。任何其他值都会使 SDK 保持启用；无法识别的值会发出插件警告并回退为 `false`。异步上下文和 `OTEL_PROPAGATORS` 仍然保持激活。
`OTEL_NODE_RESOURCE_DETECTORS`	为插件自有的 trace 和 metric 提供程序选择资源检测器。受支持的 token 为 `env`、`host`、`os`、`process` 和 `serviceinstance`；`all` 按 host、OS、service-instance、process、environment 的顺序运行它们，而 `none` 则禁用检测。默认顺序为 environment、process、host。显式的 OpenClaw 服务配置优先于检测器属性。
`OTEL_TRACES_SAMPLER` / `OTEL_TRACES_SAMPLER_ARG`	当 `diagnostics.otel.sampleRate` 未设置时，使用的标准 OpenTelemetry 采样器选择。显式的 `sampleRate` 仍然是更高优先级的 OpenClaw 采样器。
`OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT` / `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` / `OTEL_SPAN_EVENT_COUNT_LIMIT` / `OTEL_SPAN_LINK_COUNT_LIMIT` / `OTEL_SPAN_ATTRIBUTE_PER_EVENT_COUNT_LIMIT` / `OTEL_SPAN_ATTRIBUTE_PER_LINK_COUNT_LIMIT`	由每个插件自有的 tracer 提供程序应用的标准 OpenTelemetry span 限制。
`OTEL_BSP_MAX_QUEUE_SIZE` / `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` / `OTEL_BSP_SCHEDULE_DELAY` / `OTEL_BSP_EXPORT_TIMEOUT`	插件自有跟踪导出的批量 span 处理器设置。值必须为正数；无效值使用 OpenTelemetry 默认值。导出批量大小以队列大小为上限。
`OTEL_METRIC_EXPORT_INTERVAL` / `OTEL_METRIC_EXPORT_TIMEOUT`	插件自有指标的定期导出间隔和超时时间。值必须为正数；无效值使用 OpenTelemetry 默认值，超时时间以当前生效的间隔为上限。`diagnostics.otel.flushIntervalMs` 会覆盖该间隔。
`OTEL_NODE_EXPERIMENTAL_SDK_METRICS`	当设置为 `true` 时，为私有 meter、tracer 和批量 span 处理器启用 OpenTelemetry SDK 自观测指标。
`OTEL_LOG_LEVEL`	自有模式不会替换进程全局的 OpenTelemetry 诊断记录器，因为公共 SDK API 不提供代次私有的等价物。预加载器或宿主进程可以在 OpenClaw 启动前配置此变量；插件会保留该外部诊断所有者。
`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 provider 时，设置为 `1`。插件会接管外部的 trace、metric、context、propagation 和 logger 所有权，而不会注册、替换、禁用、注销或关闭它。当 `OTEL_SDK_DISABLED=true` 时，外部所有权保持生效，而插件自有的日志保持禁用。

在未设置 OPENCLAW_OTEL_PRELOADED=1 时，trace、metric 和 log provider 是代次私有的。插件仅通过公共 OpenTelemetry API 发布其异步上下文管理器和传播器，并且仅在这些公共行为仍然与正在停止的代次匹配时才移除它们。因此，替换宿主进程或后续代次会在清理过程中保持所有权。

采样与刷新¶

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

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw