接入 OpenClaw 应用-云监控(CMS)-阿里云帮助中心

OpenClaw 内置了 diagnostics-otel 插件，支持通过 OpenTelemetry 标准将 Trace 和 Metric 数据上报至云监控 2.0 应用监控。启用该插件后，您可以在云监控 2.0 应用监控中查看 OpenClaw 网关的调用链路、模型调用耗时、Token 消耗等监控数据。

使用限制

限制项	说明
OpenClaw 版本	v26.2.19 及以上。低于此版本不包含 `diagnostics-otel` 插件，请先升级。
上报协议	仅支持 HTTP/Protobuf，暂不支持 HTTP/JSON 和 gRPC。
数据类型	当前仅支持接收 Trace 和 Metric 数据，暂不支持 Log 数据。
云监控服务	已开通云监控 2.0 服务，并创建了工作空间。

步骤一：获取接入点信息

在配置 OpenClaw 之前，您需要先从云监控 2.0 控制台获取接入点信息。

登录云监控 2.0 控制台，选择目标工作空间。
在左侧导航栏单击接入中心。
在应用监控&链路追踪区域单击 OpenTelemetry 卡片。

在参数配置区域单击 LicenseKey 右侧的点击获取，然后根据需求选择连接方式、上报方式。

页面下方将根据配置参数生成相应的接入代码，代码中包含 Endpoint、LicenseKey 等接入点信息，需要记录以下信息用于后续配置：

参数	说明	示例
Endpoint	OTLP Trace/Metric 数据上报地址	`https://proj-xtrace-xxx.cn-hangzhou-intranet.log.aliyuncs.com/apm/trace/opentelemetry/v1/traces` `https://proj-xtrace-xxx.cn-hangzhou-intranet.log.aliyuncs.com/apm/trace/opentelemetry/v1/metrics`
x-arms-license-key	数据写入鉴权的 LicenseKey	`d95vgxi0cn@xxxxx`
x-arms-project	日志服务项目名称	`proj-xtrace-xxx-cn-hangzhou`
x-cms-workspace	云监控 2.0 工作空间标识	`default-cms-xxx-cn-hangzhou`

步骤二：启用 diagnostics-otel 插件

OpenClaw 内置了 diagnostics-otel 插件，但默认处于禁用状态。可以通过以下方式启用：

方式一：通过 CLI 命令启用

openclaw plugins enable diagnostics-otel

方式二：编辑配置文件

编辑配置文件 ~/.openclaw/openclaw.json，在 plugins 字段中添加：

{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  }
}

步骤三：配置上报参数

启用插件后，需要配置上报参数。将步骤一接入点信息替换到以下配置中。

方式一：通过 CLI 逐项配置

依次执行以下命令，将尖括号内的占位符替换为实际值：

openclaw config set diagnostics.enabled true
openclaw config set diagnostics.otel.enabled true
openclaw config set diagnostics.otel.traces true
openclaw config set diagnostics.otel.metrics true
openclaw config set diagnostics.otel.logs false
openclaw config set diagnostics.otel.protocol "http/protobuf"
openclaw config set diagnostics.otel.endpoint "<Endpoint>"
openclaw config set diagnostics.otel.headers '{"x-arms-license-key":"<YOUR-LICENSE-KEY>","x-arms-project":"<YOUR-ARMS-PROJECT>","x-cms-workspace":"<YOUR-WORKSPACE-ID>"}'
openclaw config set diagnostics.otel.serviceName "openclaw-gateway"
openclaw config set diagnostics.otel.sampleRate 1
openclaw config set diagnostics.otel.flushIntervalMs 5000

方式二：直接编辑配置文件

编辑 ~/.openclaw/openclaw.json，在 diagnostics 字段中写入完整配置：

{
  "enabled": true,
  "otel": {
    "enabled": true,
    "endpoint": "<Endpoint>",
    "protocol": "http/protobuf",
    "headers": {
      "x-arms-license-key": "<YOUR-LICENSE-KEY>",
      "x-arms-project": "<YOUR-ARMS-PROJECT>",
      "x-cms-workspace": "<YOUR-WORKSPACE-ID>"
    },
    "serviceName": "openclaw-gateway",
    "traces": true,
    "metrics": true,
    "logs": false,
    "sampleRate": 1,
    "flushIntervalMs": 5000
  }
}

参数说明

参数	类型	必填	说明
`enabled`	Boolean	是	是否启用 diagnostics 诊断功能。设置为 `true` 开启。
`otel.enabled`	Boolean	是	是否启用 OpenTelemetry 数据导出。设置为 `true` 开启。
`otel.endpoint`	String	是	OTLP 数据上报地址。从云监控 2.0 接入中心获取。插件会自动在末尾追加 `/v1/traces` 或 `/v1/metrics` 路径，无需手动添加。
`otel.protocol`	String	是	上报协议。当前仅支持 `http/protobuf`，设置为 `grpc` 会被静默忽略。
`otel.headers`	Object	是	上报请求携带的认证头信息，从云监控 2.0 接入中心获取。
`otel.headers.x-arms-license-key`	String	是	数据写入鉴权的 LicenseKey，用于身份认证。
`otel.headers.x-arms-project`	String	是	项目标识，指链路与指标数据归属的日志服务项目名称。
`otel.headers.x-cms-workspace`	String	是	云监控 2.0 工作空间标识，指定数据上报的目标工作空间。
`otel.serviceName`	String	是	上报的服务名称，将作为应用名显示在云监控 2.0 的应用列表中。建议设置为有业务辨识度的名称。
`otel.traces`	Boolean	是	是否上报 Trace 数据。设置为 `true` 可查看模型调用等操作的调用链路和耗时分布。
`otel.metrics`	Boolean	是	是否上报 Metric 数据。设置为 `true` 可查看 Token 用量、调用次数、耗时、会话状态等指标。
`otel.logs`	Boolean	是	是否上报 Log 数据。云监控 2.0 应用监控当前暂不支持 Log 数据，建议设置为 `false`。
`otel.sampleRate`	Number	否	Trace 采样率，取值范围 0.0 ~ 1.0，仅对根 Span 生效。`1` 表示全量采集，`0.5` 表示采集 50%。
`otel.flushIntervalMs`	Number	否	数据批量刷新间隔，单位为毫秒，最小值为 `1000`。默认值为 `60000`（60 秒），意味着短时任务的 Trace 最长需等待 1 分钟才能在控制台看到。

步骤四：验证配置

执行以下命令检查配置是否生效：

openclaw config get diagnostics

预期输出类似如下内容：

{
  "enabled": true,
  "otel": {
    "enabled": true,
    "endpoint": "https://xxxxx.log.aliyuncs.com",
    "protocol": "http/protobuf",
    "headers": {
      "x-arms-license-key": "xxxxx",
      "x-arms-project": "xxxxx",
      "x-cms-workspace": "xxxxx"
    },
    "serviceName": "openclaw-gateway",
    "traces": true,
    "metrics": true,
    "logs": false,
    "sampleRate": 1,
    "flushIntervalMs": 5000
  }
}

步骤五：重启网关

配置完成后，需重启网关使配置生效：

openclaw gateway restart

步骤六：查看监控数据

配置生效后，您可以在云监控 2.0 控制台查看 OpenClaw 上报的监控数据。

登录云监控 2.0 控制台，选择目标工作空间。
在左侧导航栏选择应用可观测 > 应用监控。
在应用列表中找到您配置的服务名称（如 openclaw-gateway）。
单击应用名称或选择调用链分析查看调用链路和耗时分布。

常见问题

配置完成后控制台看不到数据？

请依次排查：

确认 OpenClaw 版本 ≥ v26.2.19（执行 openclaw --version 检查）。
确认 openclaw config get diagnostics 输出中 enabled 和 otel.enabled 均为 true。
确认 Endpoint 地址正确，且网络可达（可通过 curl 测试连通性）。
确认三个 Header 值（x-arms-license-key、x-arms-project、x-cms-workspace）均已正确填写。
注意 flushIntervalMs 默认为 60 秒，短时任务可能需要等待一段时间才能看到数据。

可以使用 gRPC 协议上报吗？

当前 OpenClaw 的 diagnostics-otel 插件仅支持 http/protobuf 协议，设置 grpc 会被静默忽略，不会有报错但也不会生效。