clawpro-diagnostics-metrics-cls

v1.0.3

Published

2 days ago

Cls OpenClaw diagnostics exporter: Prometheus metrics (pull/remote-write)

0High
0Medium
0Low

zhanxiangli

Diagnostics Metrics CLS 插件

OpenClaw 诊断指标导出插件，提供以下核心能力：

Prometheus 指标采集：通过 /metrics HTTP 端点暴露指标（Pull 模式），或通过 Prometheus Remote Write 协议主动推送到远端（Push 模式）
腾讯云 CLS Prometheus Remote Write：通过腾讯云 CLS 的 Prometheus Remote Write 接口推送指标数据

快速安装（推荐）

使用 onboard CLI 工具一键完成安装和配置。

前置条件

安装前需确保 ~/.openclaw/openclaw.json 中已包含 CLS 必填配置，CLI 会自动读取该文件。

静态密钥模式（默认）：需要 secretId、secretKey、endpoint（metricTopicId 可选）
CVM 角色临时密钥模式：需要 endpoint、roleName，无需 secretId 和 secretKey（metricTopicId 可选）

也可以通过命令行参数直接传入，命令行参数优先级高于配置文件中的值。

运行安装命令

npx --yes clawpro-diagnostics-metrics-cls-onboard-cli install

命令行参数

所有参数均为可选，未传入时会从 openclaw.json 中读取已有值：

| 参数 | 说明 | 是否必填 | |------|------|----------| | --metricTopicId <id> | Prometheus Remote Write 使用的 CLS 日志主题 ID | 可选（可在配置文件中动态更新） | | --secretId <id> | 腾讯云 API 密钥 SecretId | ✅ static 模式必填（配置文件或参数二选一） | | --secretKey <key> | 腾讯云 API 密钥 SecretKey | ✅ static 模式必填（配置文件或参数二选一） | | --endpoint <endpoint> | CLS 接入点（如 ap-guangzhou.cls.tencentcs.com） | ✅ 必填（配置文件或参数二选一） | | --credentialMode <mode> | 凭证模式：static（静态密钥，默认）或 cvmRole（CVM 角色临时密钥） | 可选，默认 static | | --roleName <name> | CVM 角色名称 | ✅ cvmRole 模式必填（配置文件或参数二选一） | | --enableReport <bool> | 是否启用指标推送（true/false，默认 true） | 可选 | | --prometheusEnabled <bool> | 是否开启 Prometheus 指标上报（true/false） | 可选 | | --pushIntervalMs <ms> | Prometheus Remote Write 推送间隔（毫秒） | 可选 | | --externalLabels <labels> | Prometheus 自定义标签（格式：key1=value1,key2=value2） | 可选 |

安装示例

从配置文件读取（已预先在 openclaw.json 中配置好 CLS 信息）：

npx clawpro-diagnostics-metrics-cls-onboard-cli install

通过命令行参数传入（静态密钥模式）：

npx clawpro-diagnostics-metrics-cls-onboard-cli install \
  --metricTopicId "xxxxxxxx-metric-topic-id" \
  --secretId "AKIDxxxxxxxx" \
  --secretKey "xxxxxxxxxxxxxxxx" \
  --endpoint "ap-guangzhou.cls.tencentcs.com" \
  --prometheusEnabled true

使用 CVM 角色临时密钥模式（无需传入 secretId/secretKey，但必须指定 roleName）：

npx clawpro-diagnostics-metrics-cls-onboard-cli install \
  --metricTopicId "xxxxxxxx-metric-topic-id" \
  --endpoint "ap-guangzhou.cls.tencentcs.com" \
  --credentialMode cvmRole \
  --roleName "CVM"

使用 CVM 角色临时密钥模式（自定义角色名）：

npx clawpro-diagnostics-metrics-cls-onboard-cli install \
  --endpoint "ap-guangzhou.cls.tencentcs.com" \
  --credentialMode cvmRole \
  --roleName "MyCustomRoleName"

安装完成后，CLI 会自动重启网关并输出确认信息：

✅ 安装完成，clawpro-diagnostics-metrics-cls 已启用
   凭证模式: 静态密钥
   CLS 接入点: ap-guangzhou.cls.tencentcs.com
   指标日志主题 ID: xxxxxxxx-metric-topic-id
   指标推送: 已启用
   指标上报: 已开启
   Prometheus Remote Write: https://ap-guangzhou.cls.tencentcs.com/prometheus/xxxxxxxx-metric-topic-id/api/v1/write
   推送间隔: 15000ms

运行以下命令验证插件状态：
   openclaw plugins list

使用 CVM 角色临时密钥模式时的输出示例：

✅ 安装完成，clawpro-diagnostics-metrics-cls 已启用
   凭证模式: CVM 角色临时密钥
   CVM 角色名称: CVM
   CLS 接入点: ap-guangzhou.cls.tencentcs.com
   指标日志主题 ID: xxxxxxxx-metric-topic-id
   指标推送: 已启用
   指标上报: 未开启

运行以下命令验证插件状态：
   openclaw plugins list

说明：启用 Prometheus 时，CLI 会自动根据 endpoint 和 metricTopicId 生成 Remote Write URL（格式为 https://<endpoint>/prometheus/<metricTopicId>/api/v1/write）。静态密钥模式下使用 secretId / secretKey 的 Basic Auth 进行鉴权；CVM 角色临时密钥模式下由插件运行时动态获取凭证进行鉴权。

手动安装

第一步：安装插件

openclaw plugins install clawpro-diagnostics-metrics-cls

第二步：安装插件运行时依赖

在插件安装目录中执行：

cd ~/.openclaw/extensions/clawpro-diagnostics-metrics-cls
npm install --omit=dev

第三步：编辑配置文件

打开 ~/.openclaw/openclaw.json，添加以下配置：

静态密钥模式（默认）：

{
  "diagnostics": {
    "enabled": true
  },
  "plugins": {
    "allow": ["clawpro-diagnostics-metrics-cls"],
    "entries": {
      "clawpro-diagnostics-metrics-cls": {
        "enabled": true,
        "config": {
          "cls": {
            "metricTopicId": "your-metric-topic-id",
            "secretId": "your-secret-id",
            "secretKey": "your-secret-key",
            "endpoint": "ap-guangzhou.cls.tencentcs.com"
          }
        }
      }
    }
  }
}

CVM 角色临时密钥模式（适用于腾讯云 CVM 环境）：

{
  "diagnostics": {
    "enabled": true
  },
  "plugins": {
    "allow": ["clawpro-diagnostics-metrics-cls"],
    "entries": {
      "clawpro-diagnostics-metrics-cls": {
        "enabled": true,
        "config": {
          "cls": {
            "credentialMode": "cvmRole",
            "roleName": "CVM",
            "metricTopicId": "your-metric-topic-id",
            "endpoint": "ap-guangzhou.cls.tencentcs.com"
          }
        }
      }
    }
  }
}

重要：diagnostics.enabled 必须设为 true，否则 OpenClaw 不会发出诊断事件，Prometheus 指标将无法采集。使用 CLI 安装时会自动写入此配置。

第四步：重启网关

openclaw gateway restart

配置说明

所有配置均位于 ~/.openclaw/openclaw.json 中 plugins.entries["clawpro-diagnostics-metrics-cls"].config 下，分为 cls 和 prometheus 两个子对象。

CLS 配置

CLS 配置用于设置腾讯云 CLS Prometheus Remote Write 的凭证和接入信息。

静态密钥模式（默认）：

{
  "cls": {
    "metricTopicId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
    "secretId": "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "secretKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "endpoint": "ap-guangzhou.cls.tencentcs.com",
    "enableReport": true
  }
}

CVM 角色临时密钥模式：

{
  "cls": {
    "credentialMode": "cvmRole",
    "roleName": "CVM",
    "metricTopicId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
    "endpoint": "ap-guangzhou.cls.tencentcs.com",
    "enableReport": true
  }
}

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | metricTopicId | string | — | 可选。Prometheus Remote Write 使用的 CLS 日志主题 ID，用于构建推送 URL | | credentialMode | string | "static" | 凭证模式：static（静态密钥）或 cvmRole（CVM 角色临时密钥）。详见 CVM 角色临时密钥 | | roleName | string | — | cvmRole 模式必填。CVM 角色名称，仅在 credentialMode 为 cvmRole 时有效 | | credentialRefreshIntervalMs | number | 300000 | CVM 角色临时密钥刷新间隔（毫秒），仅在 credentialMode 为 cvmRole 时有效，最小值 60000 | | secretId | string | — | static 模式必填。腾讯云 API 密钥 SecretId（cvmRole 模式下无需配置） | | secretKey | string | — | static 模式必填。腾讯云 API 密钥 SecretKey（cvmRole 模式下无需配置） | | endpoint | string | — | 必填。CLS 接入点域名，例如 ap-guangzhou.cls.tencentcs.com 或 ap-guangzhou-open.cls.tencentcs.com | | enableReport | boolean | true | 是否启用指标推送。false 时插件不通过 Remote Write 推送任何指标数据。支持热更新，修改配置文件后约 10 秒内生效，无需重启 |

获取腾讯云密钥：登录腾讯云控制台 → 访问管理 → API 密钥管理。
获取 CLS Topic ID：登录日志服务控制台 → 日志主题 → 复制主题 ID。
CLS 接入点列表：参考 CLS 可用地域，格式为 <region>.cls.tencentcs.com（内网）、<region>-open.cls.tencentcs.com（内网开放接口）或 <region>.cls.tencentyun.com（外网）。

Prometheus 配置（可选）

Prometheus 功能通过插件的 config.prometheus 配置项控制，与 cls 配置并列放在 plugins.entries["clawpro-diagnostics-metrics-cls"].config 下。

在 ~/.openclaw/openclaw.json 中添加：

{
  "plugins": {
    "allow": ["clawpro-diagnostics-metrics-cls"],
    "entries": {
      "clawpro-diagnostics-metrics-cls": {
        "enabled": true,
        "config": {
          "prometheus": {
            "enabled": true,
            "metric_prefix": "openclaw",
            "pull": true,
            "default_metrics": true,
            "external_labels": {
              "instance": "my-openclaw-instance",
              "env": "production"
            },
            "remote_write": [
              {
                "url": "http://prometheus:9090/api/v1/write"
              }
            ],
            "push_interval_ms": 15000
          }
        }
      }
    }
  }
}

Prometheus 基础配置

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | enabled | boolean | true | 是否启用 Prometheus 功能 | | metric_prefix | string | "openclaw" | 所有指标名称的前缀 | | pull | boolean | true | 是否启用 /metrics HTTP Pull 端点 | | default_metrics | boolean | true | 是否采集 Node.js 默认指标（GC、事件循环等） | | external_labels | object | {} | 附加到所有指标的自定义标签 | | push_interval_ms | number | 15000 | Remote Write 推送间隔（毫秒） |

说明：当部署在腾讯云环境时，插件会自动注入实例元数据作为标签（cvm_instance_id、cvm_instance_name、cvm_instance_intra_ip、cvm_instance_internet_ip、cvm_instance_region）。若在 external_labels 中手动配置了同名标签，则以手动配置的值为准。

Remote Write 配置

remote_write 为数组，支持同时配置多个推送目标：

{
  "remote_write": [
    {
      "url": "http://prometheus:9090/api/v1/write",
      "headers": {
        "Authorization": "Bearer <token>"
      },
      "queue_config": {
        "capacity": 2500,
        "max_samples_per_send": 500,
        "batch_send_deadline_ms": 5000,
        "max_retries": 3
      },
      "tls_config": {
        "insecure_skip_verify": false
      }
    }
  ]
}

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | url | string | — | 必填。Remote Write 端点 URL | | headers | object | — | 自定义 HTTP 请求头（可用于传入 Authorization 等认证头） | | tls_config.ca_file | string | — | CA 证书文件路径 | | tls_config.cert_file | string | — | 客户端证书文件路径 | | tls_config.key_file | string | — | 客户端私钥文件路径 | | tls_config.insecure_skip_verify | boolean | false | 跳过 TLS 证书验证 | | queue_config.capacity | number | 2500 | 队列容量（超出后丢弃最旧数据） | | queue_config.max_samples_per_send | number | 500 | 每批最大发送样本数 | | queue_config.batch_send_deadline_ms | number | 5000 | 批次最大等待时间（毫秒） | | queue_config.max_retries | number | 3 | 5xx/429 错误最大重试次数 | | queue_config.min_backoff_ms | number | 30 | 重试最小退避时间（毫秒） | | queue_config.max_backoff_ms | number | 5000 | 重试最大退避时间（毫秒） |

使用 CLI 安装时：启用 Prometheus 后，CLI 会自动根据 endpoint 和 metricTopicId 生成 Remote Write URL（格式为 https://<endpoint>/prometheus/<metricTopicId>/api/v1/write）。静态密钥模式下使用 secretId:secretKey 的 Basic Auth 进行鉴权；CVM 角色临时密钥模式下由插件运行时动态获取凭证进行鉴权。无需手动配置 remote_write 和 headers。

功能说明

Prometheus 指标列表

所有指标名称均以 metric_prefix（默认 openclaw）为前缀。指标的维度标签统一使用 openclaw_ 前缀。

维度（Label）字典

| 维度名 | 说明 | 示例值 | |--------|------|--------| | openclaw_type | Token 类型 / 上下文类型 | input, output, cache_read, cache_write, prompt, total, limit, used | | openclaw_provider | 模型提供商 | qwen, anthropic | | openclaw_model | 模型名称 | glm-5, claude-3-5-sonnet | | openclaw_channel | 消息渠道 | feishu, dingtalk, wechat, telegram | | openclaw_update_type | Webhook 更新类型 | message, callback_query | | openclaw_source | 消息来源 | user, system | | openclaw_outcome | 消息处理结果 | success, error, skipped | | openclaw_lane | 队列通道 | default, priority | | openclaw_state | 会话状态 | idle, running, waiting | | openclaw_reason | 状态转换原因 | timeout, completed | | openclaw_attempt | Agent 运行尝试序号 | 1, 2, 3 | | openclaw_tool | 工具名称 | web_search, code_exec | | openclaw_detector | 循环检测器名称 | repetition, token_waste | | openclaw_level | 检测等级 | warn, critical | | openclaw_action | 检测后执行的动作 | skip, abort |

Counter 类型指标

| 指标名 | 说明 | 维度 | |--------|------|------| | openclaw_tokens_total | 模型 Token 消耗总量 | openclaw_type, openclaw_provider, openclaw_model, openclaw_channel | | openclaw_cost_usd_total | 模型调用预估费用（USD） | openclaw_provider, openclaw_model, openclaw_channel | | openclaw_webhook_received_total | 收到的 Webhook 请求数 | openclaw_channel, openclaw_update_type | | openclaw_webhook_error_total | Webhook 处理错误数 | openclaw_channel, openclaw_update_type | | openclaw_message_queued_total | 入队消息总数 | openclaw_channel, openclaw_source | | openclaw_message_processed_total | 已处理消息总数 | openclaw_channel, openclaw_outcome | | openclaw_queue_lane_enqueue_total | 队列入队事件数 | openclaw_lane | | openclaw_queue_lane_dequeue_total | 队列出队事件数 | openclaw_lane | | openclaw_session_state_total | 会话状态转换次数 | openclaw_state, openclaw_reason | | openclaw_session_stuck_total | 检测到的卡住会话数 | openclaw_state | | openclaw_run_attempt_total | Agent 运行尝试次数 | openclaw_attempt | | openclaw_tool_loop_total | 工具循环检测次数 | openclaw_tool, openclaw_detector, openclaw_level, openclaw_action |

Histogram 类型指标

Histogram 类型指标在 Prometheus 中会自动展开为 _bucket（带 le 标签）、_count、_sum 三条子指标。

| 指标名 | 说明 | 维度 | 桶边界（Buckets） | |--------|------|------|-------------------| | openclaw_run_duration_ms | Agent 单次运行耗时（ms） | openclaw_provider, openclaw_model, openclaw_channel | 100, 250, 500, 1k, 2.5k, 5k, 10k, 30k, 60k | | openclaw_context_tokens | 上下文窗口 Token 数量 | openclaw_provider, openclaw_model, openclaw_channel, openclaw_type | 1k, 4k, 8k, 16k, 32k, 64k, 128k, 200k | | openclaw_webhook_duration_ms | Webhook 处理耗时（ms） | openclaw_channel, openclaw_update_type | 10, 50, 100, 250, 500, 1k, 2.5k, 5k | | openclaw_message_duration_ms | 消息处理耗时（ms） | openclaw_channel, openclaw_outcome | 100, 500, 1k, 2.5k, 5k, 10k, 30k, 60k | | openclaw_queue_wait_ms | 队列等待时间（ms） | openclaw_lane | 10, 50, 100, 500, 1k, 5k, 10k | | openclaw_session_stuck_age_ms | 卡住会话持续时间（ms） | openclaw_state | 1k, 5k, 10k, 30k, 60k, 120k, 300k |

Gauge 类型指标

| 指标名 | 说明 | 维度 | |--------|------|------| | openclaw_active_sessions | 当前活跃会话数 | — | | openclaw_waiting_sessions | 当前等待中的会话数 | — | | openclaw_queued_messages | 当前队列中的消息总数 | — | | openclaw_queue_depth | 当前队列深度（按通道分） | openclaw_lane |

其他指标

| 指标名 | 类型 | 说明 | |--------|------|------| | openclaw_node_* | 多种 | Node.js 运行时指标（GC、事件循环、内存等，default_metrics: true 时启用） |

注意：
所有指标均可通过 external_labels 配置项追加全局标签（如 job、instance 等）
Pull 模式下 job 标签由 Prometheus 服务端自动注入
Push 模式下 job 标签需通过 external_labels 手动配置

腾讯云实例元数据注入

插件会自动从腾讯云 Metadata 接口获取当前实例的元数据信息，并注入到 Prometheus 指标（Push 模式）中作为 external_labels 自动合并（cvm_instance_id、cvm_instance_name、cvm_instance_intra_ip、cvm_instance_internet_ip、cvm_instance_region）。

获取的元数据字段

| 字段 | Metadata 接口路径 | 说明 | |------|-------------------|------| | cvm_instance_id | /latest/meta-data/instance-id | 实例 ID | | cvm_instance_name | /latest/meta-data/instance-name | 实例名称 | | cvm_instance_intra_ip | /latest/meta-data/local-ipv4 | 内网 IPv4 地址 | | cvm_instance_internet_ip | /latest/meta-data/public-ipv4 | 公网 IPv4 地址 | | cvm_instance_region | /latest/meta-data/placement/region | 所在地域 |

刷新策略

启动时立即获取一次元数据（请求超时 2 秒）
首次获取失败的字段会在 30 秒后重试，最多重试 3 次
成功后每 1 小时自动刷新
非腾讯云环境下，元数据字段为空字符串，不影响插件正常运行

更新配置（UpdateParameter）

已安装插件后，如需修改配置参数（如更换密钥、切换凭证模式、调整推送间隔等），可使用 UpdateParameter 命令，无需重新安装插件。

运行更新命令

npx --yes clawpro-diagnostics-metrics-cls-onboard-cli UpdateParameter [选项]

命令行参数

至少需要传入一个参数，未传入的参数保持当前配置不变：

| 参数 | 说明 | 是否需要重启网关 | |------|------|------------------| | --metricTopicId <id> | CLS 指标日志主题 ID | ❌ 热加载（约 10 秒内生效） | | --secretId <id> | 腾讯云 API 密钥 SecretId | ❌ 热加载（约 10 秒内生效） | | --secretKey <key> | 腾讯云 API 密钥 SecretKey | ❌ 热加载（约 10 秒内生效） | | --endpoint <endpoint> | CLS 接入点 | ❌ 热加载（约 10 秒内生效） | | --enableReport <bool> | 是否启用指标推送（true/false） | ❌ 热加载（约 10 秒内生效） | | --credentialMode <mode> | 凭证模式：static 或 cvmRole | ✅ 需要重启网关 | | --roleName <name> | CVM 角色名称 | ✅ 需要重启网关 | | --prometheusEnabled <bool> | 是否开启 Prometheus 指标上报（true/false） | ✅ 需要重启网关 | | --pushIntervalMs <ms> | Prometheus Remote Write 推送间隔（毫秒） | ✅ 需要重启网关 | | --externalLabels <labels> | Prometheus 自定义标签（格式：key1=value1,key2=value2） | ✅ 需要重启网关 |

智能重启判断：CLI 会自动分析本次更新的参数，如果所有参数均支持热加载，则不会重启网关；如果包含需要重启的参数，CLI 会自动重启网关使配置生效。

更新示例

更换静态密钥（热加载，无需重启）：

npx clawpro-diagnostics-metrics-cls-onboard-cli UpdateParameter \
  --secretId "AKIDxxxxxxxx-new" \
  --secretKey "xxxxxxxx-new"

更换 CLS 接入点和日志主题（热加载，无需重启）：

npx clawpro-diagnostics-metrics-cls-onboard-cli UpdateParameter \
  --endpoint "ap-beijing.cls.tencentcs.com" \
  --metricTopicId "new-metric-topic-id"

临时关闭指标推送（热加载，无需重启）：

npx clawpro-diagnostics-metrics-cls-onboard-cli UpdateParameter \
  --enableReport false

切换到 CVM 角色临时密钥模式（需要重启网关）：

npx clawpro-diagnostics-metrics-cls-onboard-cli UpdateParameter \
  --credentialMode cvmRole \
  --roleName "CVM"

修改 Prometheus 推送间隔和自定义标签（需要重启网关）：

npx clawpro-diagnostics-metrics-cls-onboard-cli UpdateParameter \
  --pushIntervalMs 30000 \
  --externalLabels "env=staging,region=ap-beijing"

混合更新（热加载 + 需重启参数，CLI 会自动重启网关）：

npx clawpro-diagnostics-metrics-cls-onboard-cli UpdateParameter \
  --endpoint "ap-beijing.cls.tencentcs.com" \
  --pushIntervalMs 30000

输出示例

仅更新热加载参数时：

✅ 已更新 openclaw.json 中的插件配置
✅ 配置更新完成，以下参数支持热加载，无需重启网关: metricTopicId, endpoint
   插件将在下一次轮询周期（约 10 秒内）自动应用新配置

📋 更新后的配置：
   凭证模式: 静态密钥
   CLS 接入点: ap-beijing.cls.tencentcs.com
   指标日志主题 ID: new-metric-topic-id
   指标推送: 已启用
   Prometheus 指标上报: 已开启
   Remote Write URL: https://ap-beijing.cls.tencentcs.com/prometheus/new-metric-topic-id/api/v1/write
   推送间隔: 15000ms

包含需要重启的参数时：

✅ 已更新 openclaw.json 中的插件配置

以下参数需要重启网关才能生效: pushIntervalMs
✅ 配置更新完成，网关已重启

📋 更新后的配置：
   凭证模式: 静态密钥
   CLS 接入点: ap-guangzhou.cls.tencentcs.com
   指标日志主题 ID: xxxxxxxx-metric-topic-id
   指标推送: 已启用
   Prometheus 指标上报: 已开启
   Remote Write URL: https://ap-guangzhou.cls.tencentcs.com/prometheus/xxxxxxxx-metric-topic-id/api/v1/write
   推送间隔: 30000ms

错误处理

插件未安装：如果插件尚未安装，命令会提示先执行 install
未指定参数：如果未传入任何配置参数，命令会提示可用参数
回滚机制：更新过程中发生错误（如网关重启失败），CLI 会自动回滚配置到更新前的状态
超时保护：整个更新流程有 5 分钟超时限制，防止进程无限挂起

配置热更新

插件支持以下配置字段的热更新，修改 openclaw.json 后约 10 秒内自动生效，无需重启网关：

| 字段 | 热更新行为 | |------|-----------| | cls.metricTopicId | 自动更新 Remote Write URL，切换到新的日志主题 | | cls.endpoint | 自动更新 Remote Write URL，切换到新的接入点 | | cls.enableReport | false 时立即停止 Remote Write 指标推送；true 时立即恢复推送 | | cls.secretId | 自动更新静态密钥（static 模式），新密钥加密后回写配置文件 | | cls.secretKey | 自动更新静态密钥（static 模式），新密钥加密后回写配置文件 |

注意：credentialMode、roleName 等凭证模式相关字段，以及 prometheusEnabled、pushIntervalMs、externalLabels 等 Prometheus 配置字段变更后需要重启网关才能生效。可通过 UpdateParameter 命令更新，CLI 会自动判断是否需要重启。

密钥加密存储

为避免 secretId 和 secretKey 以明文形式暴露在 openclaw.json 配置文件中，插件采用 AES-256-CBC + 加盐 的方式对密钥进行加密存储。

工作原理

CLI 安装时自动加密：通过 npx clawpro-diagnostics-metrics-cls-onboard-cli install 安装时，CLI 会自动将 secretId 和 secretKey 加密后写入配置文件
插件启动时自动解密：插件在初始化读取配置时，自动检测并解密密钥，对业务逻辑完全透明
自动加密明文：若配置文件中存在明文密钥（手动编辑场景），插件启动时会自动将其加密后回写
向下兼容：如果配置中的密钥是明文（旧版本配置），插件会直接使用，不会报错

加密格式

加密后的值以 ENC: 前缀标识，格式为：

ENC:<base64(iv + ciphertext)>

配置文件中的加密效果示例：

{
  "cls": {
    "secretId": "ENC:dGhpcyBpcyBhIGJhc2U2NCBleGFtcGxl...",
    "secretKey": "ENC:YW5vdGhlciBiYXNlNjQgZXhhbXBsZQ=="
  }
}

加密方案说明

| 项目 | 说明 | |------|------| | 算法 | AES-256-CBC | | 密钥派生 | SHA-256 哈希固定盐值 | | IV | 每次加密生成 16 字节随机初始化向量 | | 编码 | Base64 编码存储 | | 标识 | ENC: 前缀区分密文与明文 |

⚠️ 安全说明：此方案属于对称加密混淆存储，主要目的是防止配置文件被直接浏览时泄露明文密钥。密钥派生因子内嵌在代码中，并非高安全级别的加密方案。如有更高安全需求，建议：
使用腾讯云密钥管理服务（KMS）或密钥保险箱（SSM）
限制配置文件读取权限（chmod 600 openclaw.json）

手动配置时的注意事项

使用 CLI 安装：无需关心加密细节，CLI 会自动处理
手动编辑配置文件：可以直接写入明文密钥，插件启动时会自动检测并加密后回写
重新安装/更新密钥：再次运行 CLI 会自动将新密钥加密后覆盖
CVM 角色临时密钥模式：使用 cvmRole 模式时，配置文件中不会存储 secretId 和 secretKey，密钥加密存储功能不适用

CVM 角色临时密钥

对于部署在腾讯云 CVM 上的实例，插件支持通过 CVM 角色（CAM Role）自动获取临时密钥，无需在配置文件中存储静态的 secretId / secretKey，提升安全性。

工作原理

元数据接口获取凭证：插件通过腾讯云 CVM 元数据接口（http://metadata.tencentyun.com/latest/meta-data/cam/security-credentials/<roleName>）获取绑定了 CAM 角色的临时密钥（TmpSecretId / TmpSecretKey / Token）
自动缓存与刷新：首次获取后缓存凭证，过期前自动重新获取，对业务完全透明
并发安全：相同 roleName 共享同一个 Provider 实例，并发调用时只发起一次元数据请求
自愈机制：凭证刷新失败时暂停 Remote Write 推送，下次刷新成功后自动恢复
Prometheus Remote Write 鉴权：使用 secretId 作为 username，secretKey#token 作为 password 的 Basic Auth 方式进行鉴权

前置条件

实例必须部署在腾讯云 CVM 上，且能访问元数据接口
CVM 实例需要绑定 CAM 角色，角色需要拥有 CLS 写入权限
必须通过 roleName 参数指定 CVM 角色名称（如 CVM）

启用方式

通过 CLI 安装：

npx clawpro-diagnostics-metrics-cls-onboard-cli install \
  --credentialMode cvmRole \
  --roleName "CVM" \
  --metricTopicId "your-metric-topic-id" \
  --endpoint "ap-guangzhou.cls.tencentcs.com"

手动配置：

在 openclaw.json 的 cls 配置中设置：

{
  "cls": {
    "credentialMode": "cvmRole",
    "roleName": "CVM",
    "metricTopicId": "your-metric-topic-id",
    "endpoint": "ap-guangzhou.cls.tencentcs.com"
  }
}

注意事项

CVM 角色模式仅适用于腾讯云 CVM 环境，非 CVM 环境下无法访问元数据接口
使用 CVM 角色模式时，配置文件中不会存储 secretId 和 secretKey，CLI 安装时会自动清除已有的静态密钥
cvmRole 模式下 roleName 为必填参数，必须通过命令行参数或配置文件提供
Prometheus Remote Write 鉴权：静态密钥模式下 CLI 会自动生成 Basic Auth 头；CVM 角色模式下由插件运行时动态获取凭证进行鉴权

验证插件状态

查看插件列表

openclaw plugins list

输出示例：

Name                  Status    Version
Diagnostics Metrics   loaded    2026.3.2

Status 为 loaded 表示插件已成功加载。

验证 Prometheus 指标端点

curl http://localhost:<openclaw-port>/metrics

正常响应示例：

# HELP openclaw_tokens_total Total tokens consumed
# TYPE openclaw_tokens_total counter
openclaw_tokens_total{openclaw_type="input",openclaw_provider="anthropic",openclaw_model="claude-3-5-sonnet",openclaw_channel="telegram"} 1234
...

验证 CLS Prometheus Remote Write

查看 OpenClaw 日志中是否有如下日志，表示 Remote Write 推送正常：

diagnostics-metrics/prometheus: remote write enabled for 1 target(s), push interval 15000ms

也可在腾讯云日志服务控制台的指标日志主题中查看是否有数据写入。

卸载插件

快速卸载（推荐）

使用 onboard CLI 工具一键完成卸载，自动清理配置和安装文件。

运行卸载命令

npx --yes clawpro-diagnostics-metrics-cls-onboard-cli uninstall

命令行参数

| 参数 | 说明 | |------|------| | --force | 跳过交互式确认，直接执行卸载（适用于自动化脚本场景） |

卸载示例

交互式卸载（默认，需手动确认）：

npx clawpro-diagnostics-metrics-cls-onboard-cli uninstall

跳过确认直接卸载（适用于 CI/CD 或自动化脚本）：

npx clawpro-diagnostics-metrics-cls-onboard-cli uninstall --force

卸载流程

CLI 卸载命令会按以下顺序自动执行：

环境检查：检测 OpenClaw CLI 是否可用
配置修复：修复可能损坏的配置文件，防止清理操作丢失其他插件配置
幂等性检查：如果插件当前未安装，提前告知用户并退出
交互式确认：提示用户确认卸载操作（--force 可跳过）
备份：备份当前配置文件和插件安装文件到临时目录，用于失败时回滚
执行 openclaw plugins uninstall：通过 OpenClaw CLI 正式卸载插件，清理内部注册表
清理配置：从 openclaw.json 中移除插件配置（plugins.entries、plugins.allow），并在无其他插件依赖时将 diagnostics.enabled 还原为 false
清理文件：删除插件安装目录及所有相关文件
重启网关：自动重启 OpenClaw 网关使变更生效
验证结果：检查插件是否已完全清理

输出示例

🗑️  正在卸载 clawpro-diagnostics-metrics-cls 插件...

✅ 已通过 openclaw plugins uninstall 卸载插件
✅ 已从 openclaw.json 中移除插件配置
✅ 已清理插件安装文件
✅ 卸载完成，clawpro-diagnostics-metrics-cls 已禁用

运行以下命令验证插件状态：
   openclaw plugins list

安全机制

| 机制 | 说明 | |------|------| | 配置回滚 | 卸载过程中发生错误时，自动回滚 openclaw.json 到卸载前的状态 | | 文件恢复 | 插件文件在删除前会备份到临时目录，失败时自动从备份恢复 | | 超时保护 | 整个卸载流程有 5 分钟超时限制，防止进程无限挂起 | | 幂等操作 | 重复执行不会产生副作用，插件未安装时会提前退出 | | 信号处理 | 异常退出（如 Ctrl+C）时也会尝试清理临时备份文件 |

手动卸载

如果 CLI 工具不可用，可按以下步骤手动卸载。

第一步：卸载插件

openclaw plugins uninstall clawpro-diagnostics-metrics-cls

第二步：清理配置文件

编辑 ~/.openclaw/openclaw.json，执行以下操作：

从 plugins.entries 中删除 clawpro-diagnostics-metrics-cls 条目
从 plugins.allow 数组中移除 "clawpro-diagnostics-metrics-cls"
如果没有其他插件依赖诊断功能，将 diagnostics.enabled 设为 false

清理前：

{
  "diagnostics": {
    "enabled": true
  },
  "plugins": {
    "allow": ["clawpro-diagnostics-metrics-cls", "other-plugin"],
    "entries": {
      "clawpro-diagnostics-metrics-cls": {
        "enabled": true,
        "config": { ... }
      },
      "other-plugin": { ... }
    }
  }
}

清理后（有其他插件时保留 diagnostics.enabled: true）：

{
  "diagnostics": {
    "enabled": true
  },
  "plugins": {
    "allow": ["other-plugin"],
    "entries": {
      "other-plugin": { ... }
    }
  }
}

清理后（无其他插件时将 diagnostics.enabled 还原为 false）：

{
  "diagnostics": {
    "enabled": false
  },
  "plugins": {
    "allow": [],
    "entries": {}
  }
}

第三步：清理插件安装文件

删除插件安装目录：

rm -rf ~/.openclaw/extensions/clawpro-diagnostics-metrics-cls

第四步：重启网关

openclaw gateway restart

第五步：验证卸载结果

openclaw plugins list

确认输出中不再包含 Diagnostics Metrics 插件。

常见问题

Q：插件状态显示 error 而非 loaded？

检查 OpenClaw 日志中是否有 clawpro-diagnostics-metrics-cls 相关错误。常见原因：

依赖未安装：在插件安装目录执行 npm install --omit=dev
配置缺失：静态密钥模式下确认 cls.secretId、cls.secretKey、cls.endpoint 均已填写；CVM 角色模式下确认 cls.endpoint、cls.roleName 已填写且 cls.credentialMode 设为 cvmRole
diagnostics.enabled 未设置为 true（使用 CLI 安装可自动写入）

Q：Prometheus Remote Write 推送失败？

静态密钥模式：检查 secretId / secretKey 是否正确，且对应账号有 CLS 写入权限
CVM 角色模式：检查 CVM 实例是否绑定了正确的 CAM 角色，角色是否拥有 CLS 写入权限
检查 endpoint 是否与日志主题所在地域匹配
检查网络连通性：curl https://<endpoint>
检查 cls.enableReport 是否为 true（默认为 true）

Q：Prometheus /metrics 端点返回 503？

确认插件已正常加载。prometheus.enabled 默认为 true，无需额外设置即可启用。如果之前手动设置为 false，请将 plugins.entries["clawpro-diagnostics-metrics-cls"].config.prometheus.enabled 改回 true。

Q：如何只启用 Prometheus Pull 模式，不推送到 CLS？

不配置 cls 节点（或不填写 secretId / secretKey），插件会自动跳过 CLS Remote Write 功能，仅启用 Prometheus /metrics 端点。

Q：如何关闭 Prometheus 端点？

设置 "prometheus": { "enabled": false } 即可关闭 Prometheus 功能（默认启用）。

Q：如何更新 CLS 配置（如更换密钥）？

推荐使用 UpdateParameter 命令（不会重新安装插件，仅更新配置）：

npx clawpro-diagnostics-metrics-cls-onboard-cli UpdateParameter --secretId "新SecretId" --secretKey "新SecretKey"

secretId 和 secretKey 支持热加载，CLI 会自动判断无需重启网关，约 10 秒内生效。

也可以通过 install 命令重新安装（会重新安装插件并重启网关）：

npx clawpro-diagnostics-metrics-cls-onboard-cli install --secretId "新SecretId" --secretKey "新SecretKey"

两种方式均会读取已有配置作为默认值，只需传入需要更新的字段。

Q：如何临时关闭指标推送？

方式一：使用 UpdateParameter 命令（推荐）：

npx clawpro-diagnostics-metrics-cls-onboard-cli UpdateParameter --enableReport false

恢复推送：

npx clawpro-diagnostics-metrics-cls-onboard-cli UpdateParameter --enableReport true

方式二：直接修改 openclaw.json 中的 cls.enableReport 为 false：

{
  "cls": {
    "enableReport": false
  }
}

两种方式均支持热加载，约 10 秒内自动生效，无需重启网关。恢复推送时将 enableReport 改回 true 即可。

Q：非腾讯云环境下能正常使用吗？

可以。实例元数据获取失败时（超时 2 秒），对应字段为空字符串，不影响 Prometheus 指标采集功能。但注意：CVM 角色临时密钥模式（credentialMode: cvmRole）仅适用于腾讯云 CVM 环境，非 CVM 环境下请使用静态密钥模式。

Q：如何从静态密钥模式切换到 CVM 角色模式？

推荐使用 UpdateParameter 命令：

npx clawpro-diagnostics-metrics-cls-onboard-cli UpdateParameter --credentialMode cvmRole --roleName "CVM"

也可以通过 install 命令：

npx clawpro-diagnostics-metrics-cls-onboard-cli install --credentialMode cvmRole --roleName "CVM"

两种方式均会自动清除配置文件中已有的 secretId / secretKey，并写入 credentialMode 和 roleName。

注意：credentialMode 和 roleName 不支持热加载，CLI 会自动重启网关使配置生效。

Q：UpdateParameter 和 install 命令有什么区别？

| 对比项 | install | UpdateParameter | |--------|-----------|--------------------| | 用途 | 首次安装或重新安装插件 | 仅更新已安装插件的配置参数 | | 插件安装 | ✅ 会重新安装插件（清理旧安装 → 安装新插件 → 安装依赖） | ❌ 不安装插件，仅修改 openclaw.json | | 网关重启 | ✅ 每次都重启 | 🔄 智能判断：热加载参数不重启，冷参数才重启 | | 前置条件 | 无（可在未安装时使用） | 插件必须已安装 | | 适用场景 | 首次部署、版本升级、修复损坏的安装 | 日常配置调整（如更换密钥、修改推送间隔等） |

Q：CVM 角色临时密钥获取失败怎么办？

确认 CVM 实例已绑定 CAM 角色，且角色拥有 CLS 写入权限
确认实例能访问元数据接口：curl http://metadata.tencentyun.com/latest/meta-data/cam/security-credentials/CVM
检查 OpenClaw 日志中是否有 刷新临时密钥失败 等错误信息
插件具备自愈机制：凭证刷新失败时暂停推送，下次刷新成功后自动恢复

完整配置示例

静态密钥模式

{
  "diagnostics": {
    "enabled": true
  },
  "plugins": {
    "allow": ["clawpro-diagnostics-metrics-cls"],
    "entries": {
      "clawpro-diagnostics-metrics-cls": {
        "enabled": true,
        "config": {
          "prometheus": {
            "enabled": true,
            "metric_prefix": "openclaw",
            "pull": true,
            "default_metrics": true,
            "external_labels": {
              "instance": "prod-01",
              "env": "production"
            },
            "remote_write": [
              {
                "url": "https://ap-guangzhou.cls.tencentcs.com/prometheus/yyyyyyyy-metric-topic-id/api/v1/write",
                "headers": {
                  "Authorization": "Basic <base64(secretId:secretKey)>"
                },
                "queue_config": {
                  "max_samples_per_send": 500,
                  "batch_send_deadline_ms": 5000
                }
              }
            ],
            "push_interval_ms": 15000
          },
          "cls": {
            "metricTopicId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
            "secretId": "ENC:dGhpcyBpcyBhIGJhc2U2NCBleGFtcGxl...",
            "secretKey": "ENC:YW5vdGhlciBiYXNlNjQgZXhhbXBsZQ==",
            "endpoint": "ap-guangzhou.cls.tencentcs.com",
            "enableReport": true
          }
        }
      }
    }
  }
}

注意：上述 secretId 和 secretKey 的值以 ENC: 前缀标识，表示已加密存储。使用 CLI 安装时会自动加密写入，手动配置时也可直接写入明文（插件启动时会自动加密后回写）。详见密钥加密存储章节。

CVM 角色临时密钥模式

{
  "diagnostics": {
    "enabled": true
  },
  "plugins": {
    "allow": ["clawpro-diagnostics-metrics-cls"],
    "entries": {
      "clawpro-diagnostics-metrics-cls": {
        "enabled": true,
        "config": {
          "prometheus": {
            "enabled": true,
            "metric_prefix": "openclaw",
            "pull": true,
            "default_metrics": true,
            "external_labels": {
              "instance": "prod-01",
              "env": "production"
            },
            "remote_write": [
              {
                "url": "https://ap-guangzhou.cls.tencentcs.com/prometheus/yyyyyyyy-metric-topic-id/api/v1/write",
                "queue_config": {
                  "max_samples_per_send": 500,
                  "batch_send_deadline_ms": 5000
                }
              }
            ],
            "push_interval_ms": 15000
          },
          "cls": {
            "credentialMode": "cvmRole",
            "roleName": "CVM",
            "metricTopicId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
            "endpoint": "ap-guangzhou.cls.tencentcs.com",
            "enableReport": true
          }
        }
      }
    }
  }
}

注意：CVM 角色模式下无需配置 secretId / secretKey，插件运行时通过 CVM 元数据接口自动获取临时密钥。Prometheus Remote Write 的 headers 中也不包含 Authorization，由插件运行时动态鉴权。详见 CVM 角色临时密钥章节。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Diagnostics Metrics CLS 插件

目录

快速安装（推荐）

前置条件

运行安装命令

命令行参数

安装示例

手动安装

第一步：安装插件

第二步：安装插件运行时依赖

第三步：编辑配置文件

第四步：重启网关

配置说明

CLS 配置

Prometheus 配置（可选）

Prometheus 基础配置

Remote Write 配置

功能说明

Prometheus 指标列表

维度（Label）字典

Counter 类型指标

Histogram 类型指标

Gauge 类型指标

其他指标

腾讯云实例元数据注入

获取的元数据字段

刷新策略

更新配置（UpdateParameter）

运行更新命令

命令行参数

更新示例

输出示例

错误处理

配置热更新

密钥加密存储

工作原理

加密格式

加密方案说明

手动配置时的注意事项

CVM 角色临时密钥

工作原理

前置条件

启用方式

注意事项

验证插件状态

查看插件列表

验证 Prometheus 指标端点

验证 CLS Prometheus Remote Write

卸载插件

快速卸载（推荐）

运行卸载命令

命令行参数

卸载示例

卸载流程

输出示例

安全机制

手动卸载

第一步：卸载插件

第二步：清理配置文件

第三步：清理插件安装文件

第四步：重启网关

第五步：验证卸载结果

常见问题

完整配置示例

静态密钥模式

CVM 角色临时密钥模式