设置

快速开始¶

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。

插件加载后，对 diagnostics.otel 的更改只会热重载其导出器服务。在替换后的导出器以新的端点、请求头、采样和信号设置启动之前，上一代导出器会先取消订阅并刷新。其他插件服务、通道和 Gateway 连接保持运行。清理或启动失败时，会请求 Gateway 恢复，而不会留下一个部分替换的导出器。

diagnostics.enabled 也会热应用到共享调度器及其心跳。该进程级心跳由 Gateway 拥有；停止某个通道不会停止它。使用插件 SDK 的独立宿主为其自身进程拥有 startDiagnosticHeartbeat 和 stopDiagnosticHeartbeat，而不是由每个通道分别拥有。禁用它会停止诊断采样和恢复监听器；启用它会重新启动它们。预加载的 OpenTelemetry SDK 继续拥有其 provider 和传输层：这些更改不会关闭或重新配置宿主 SDK。

Note

diagnostics.otel.protocol 仅接受 http/protobuf。如果持久化配置（包括通过 ${VAR} 插值提供的值）仍将该字段解析为已废弃的 grpc 值，请运行 openclaw doctor --fix。Doctor 会修复直接编写的值，以及唯一拥有已更改的 diagnostics.otel 键的最深层内部单文件 include，包括无歧义的嵌套 include 链。对于根 include、实际的数组条目 include、include 数组、同级覆盖、同路径或祖先合并、跨所有权边界的更改、外部 include 目标、仍然编写嵌套 $include 指令的属主文件，或其他歧义来源，Doctor 会保持文件不变，并列出一个或多个需要手动编辑的候选源文件。当同一次运行还需要进行根所有权的修复（例如旧的 agent 名册）时，Doctor 会拒绝该写入；被拒绝的写入会使所有文件保持不变（同一次运行中较早的写入仍会保存），Doctor 会指出需要在重新运行之前手动修复的边界；如果根文件编写了该边界的 $include，还会列出被包含的一个或多个文件（agent 名册边界被命名时不带其文件）。

当 diagnostics.otel.protocol 未设置时，每个插件拥有的 OTLP 信号首先检查其非空 OTEL_EXPORTER_OTLP_*_PROTOCOL 值，然后检查 OTEL_EXPORTER_OTLP_PROTOCOL，最后默认为 http/protobuf。Doctor 不会重写进程环境变量。不支持的取值只会禁用该插件拥有的 OTLP 信号；受支持的同类信号会继续运行，logsExporter: "both" 的 stdout 分支也是如此。预加载的 trace 和 metric SDK 拥有自己的传输选择，不会因该插件而被拒绝。

哪些进程会导出¶

Gateway 在启动时启动导出器，并针对它执行的每次运行（包括分派给它的 openclaw agent 轮次）从 Gateway 进程导出。
一次性本地运行（openclaw agent --local）在 CLI 进程中执行。当配置了 OTel 导出且插件已启用时，该 CLI 进程会为此次运行启动一个导出器实例，并在进程退出前刷新缓冲的 span、指标和日志。CLI 最多等待 5 秒让诊断事件队列排空，再等待 10 秒进行刷新，因此无法访问的 collector 无法拖住命令使其不退出。一个接受连接但从不响应的 collector 仍可能延迟退出，直到导出器自身的请求超时（OTEL_EXPORTER_OTLP_TIMEOUT）。插件注册资源会保持打开，直到导出器清理完成，即使上述任一等待超时也是如此。在 JSON 输出模式下，这些一次性运行只会抑制 stdout JSONL 日志输出，以便命令的 stdout 保留给 JSON 响应；配置后 OTLP 追踪、指标和日志仍会继续。
openclaw agent exec 也会在 CLI 进程中运行内嵌的 agent，但不会启动此导出器，因此它的运行不会导出任何遥测数据。当您需要从无头运行中获取追踪数据时，请通过 Gateway 分派，或使用 openclaw agent --local。

导出器健康状态¶

openclaw doctor 和 openclaw status --all 会显示运行中 Gateway 的每个信号和传输层的最新可信导出器状态的受限且脱敏的快照。对于 diagnostics-otel，该快照会区分：

OTLP/HTTP protobuf，其端点由配置提供，或由 OTEL_* 环境变量回退提供。
OTLP/HTTP protobuf，由于未提供端点，因此使用导出器依赖项的默认端点。
stdout 日志导出。
由外部预加载的 OpenTelemetry SDK 拥有的 trace 或 metric 导出。

OTLP 导出失败和恢复转换记录来自导出器的最终结果回调，且是在依赖项拥有的重试完成之后记录的。因此，稍后成功的可重试响应不会被报告为失败。启动、日志准备或发出、导出以及关闭失败使用固定的原因类别，而不是原始错误。

该快照绝不包含端点值、请求头、证书、有效负载或原始错误消息。传输层仅保留在此本地健康投影中。它不会被添加到现有的 openclaw.telemetry.exporter.events 指标属性中，现有的 Prometheus 标签集也不会改变。

不使用导出器¶

在不运行 diagnostics-otel 的情况下，让诊断事件继续可供插件或自定义接收器使用：

{
  diagnostics: { enabled: true },
}

如需在不提高 logging.level 的情况下进行有针对性的调试输出，请使用诊断标志。标志不区分大小写，并支持通配符（telegram.* 或 *）：

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

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

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

标志输出会写入标准日志文件（logging.file），并且仍然会被始终启用的日志脱敏策略所脱敏。完整指南：诊断标志。

禁用¶

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

或者将 diagnostics-otel 从 plugins.allow 中移除，或运行 openclaw plugins disable diagnostics-otel。

当该插件原本会持有 NodeSDK 时，可以在禁用所有插件拥有的导出器、监听器、健康检查路由和 stdout 接收器的同时，保留传播能力：

OTEL_SDK_DISABLED=true openclaw gateway

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