@cnpinsight/cnpclawinsights 2.0.0 → 2.0.2

package/README.md

@@ -2,7 +2,9 @@
 
 `@cnpinsight/cnpclawinsights` 是一个 OpenClaw 插件，用于把 OpenClaw 产生的 trace、log、metrics 指标通过 OTLP HTTP/Protobuf 导出到 `otel-collector`。
 
-插件读取 `openclaw.json` 中的 `cnpclawinsights` 配置，配置结构参考 `diagnostics`。
+插件默认按 `plugins.entries.cnpclawinsights` 这个插件条目启用。
+
+最简配置只需要开启插件条目；如果你需要自定义 endpoint、日志导出、headers 等，再补 `config`。
 
 ## 安装
 
@@ -18,17 +20,80 @@ openclaw plugins install @cnpinsight/cnpclawinsights
 openclaw plugins install @cnpinsight/cnpclawinsights@2.0.0
 ```
 
+## 安装器
+
+如果你不想手动编辑 `openclaw.json`，可以使用安装器命令自动写入插件配置。
+
+最简单的方式：
+
+```bash
+npm exec -y --package=@cnpinsight/cnpclawinsights -- \
+  cnpclawinsights-install \
+  --non-interactive
+```
+
+这会自动把配置写入默认的 `~/.openclaw/openclaw.json`，并生成：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "cnpclawinsights": {
+        "enabled": true,
+        "config": {
+          "otel": {
+            "endpoint": "http://127.0.0.1:4318"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+指定 endpoint 并开启 logs：
+
+```bash
+npm exec -y --package=@cnpinsight/cnpclawinsights -- \
+  cnpclawinsights-install \
+  --non-interactive \
+  --endpoint http://127.0.0.1:4318 \
+  --logs
+```
+
+指定 service name 和 header：
+
+```bash
+npm exec -y --package=@cnpinsight/cnpclawinsights -- \
+  cnpclawinsights-install \
+  --non-interactive \
+  --service-name openclaw \
+  --header Authorization="Bearer <token>"
+```
+
+安装器支持的主要参数：
+
+- `--config-path <path>`：指定 `openclaw.json` 路径
+- `--endpoint <url>`：设置 OTLP endpoint
+- `--service-name <name>`：设置 OTel service name
+- `--logs` / `--no-logs`：开启或关闭 logs 导出
+- `--traces` / `--no-traces`：开启或关闭 traces 导出
+- `--metrics` / `--no-metrics`：开启或关闭 metrics 导出
+- `--sample-rate <0..1>`：设置 trace 采样率
+- `--flush-interval-ms <ms>`：设置导出刷新间隔
+- `--header <k=v>`：追加请求头，可重复传入
+
 ## 最小配置
 
 在 `openclaw.json` 中添加：
 
 ```json
 {
-  "cnpclawinsights": {
-    "enabled": true,
-    "otel": {
-      "enabled": true,
-      "endpoint": "http://127.0.0.1:4318"
+  "plugins": {
+    "entries": {
+      "cnpclawinsights": {
+        "enabled": true
+      }
     }
   }
 }
@@ -36,37 +101,65 @@ openclaw plugins install @cnpinsight/cnpclawinsights@2.0.0
 
 这个最小配置下：
 
+- 默认 OTLP endpoint 是 `http://127.0.0.1:4318`
 - `traces` 默认开启
 - `metrics` 默认开启
 - `logs` 默认关闭
 - OTLP 协议默认使用 `http/protobuf`
 
+## 自定义配置
+
+如果你需要覆盖默认行为，可以继续加 `config`：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "cnpclawinsights": {
+        "enabled": true,
+        "config": {
+          "otel": {
+            "endpoint": "http://127.0.0.1:4318",
+            "logs": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 ## 完整配置示例
 
 ```json
 {
-  "cnpclawinsights": {
-    "enabled": true,
-    "otel": {
-      "enabled": true,
-      "protocol": "http/protobuf",
-      "endpoint": "http://127.0.0.1:4318",
-      "traces": true,
-      "metrics": true,
-      "logs": true,
-      "serviceName": "openclaw",
-      "sampleRate": 1,
-      "flushIntervalMs": 5000,
-      "headers": {
-        "Authorization": "Bearer <token>"
-      },
-      "captureContent": {
+  "plugins": {
+    "entries": {
+      "cnpclawinsights": {
         "enabled": true,
-        "inputMessages": true,
-        "outputMessages": true,
-        "toolInputs": false,
-        "toolOutputs": false,
-        "systemPrompt": false
+        "config": {
+          "otel": {
+            "protocol": "http/protobuf",
+            "endpoint": "http://127.0.0.1:4318",
+            "traces": true,
+            "metrics": true,
+            "logs": true,
+            "serviceName": "openclaw",
+            "sampleRate": 1,
+            "flushIntervalMs": 5000,
+            "headers": {
+              "Authorization": "Bearer <token>"
+            },
+            "captureContent": {
+              "enabled": true,
+              "inputMessages": true,
+              "outputMessages": true,
+              "toolInputs": false,
+              "toolOutputs": false,
+              "systemPrompt": false
+            }
+          }
+        }
       }
     }
   }
@@ -77,14 +170,19 @@ openclaw plugins install @cnpinsight/cnpclawinsights@2.0.0
 
 ```json
 {
-  "cnpclawinsights": {
-    "enabled": true,
-    "otel": {
-      "enabled": true,
-      "tracesEndpoint": "http://127.0.0.1:4318/v1/traces",
-      "metricsEndpoint": "http://127.0.0.1:4318/v1/metrics",
-      "logsEndpoint": "http://127.0.0.1:4318/v1/logs",
-      "logs": true
+  "plugins": {
+    "entries": {
+      "cnpclawinsights": {
+        "enabled": true,
+        "config": {
+          "otel": {
+            "tracesEndpoint": "http://127.0.0.1:4318/v1/traces",
+            "metricsEndpoint": "http://127.0.0.1:4318/v1/metrics",
+            "logsEndpoint": "http://127.0.0.1:4318/v1/logs",
+            "logs": true
+          }
+        }
+      }
     }
   }
 }
@@ -92,85 +190,93 @@ openclaw plugins install @cnpinsight/cnpclawinsights@2.0.0
 
 ## 配置说明
 
-`cnpclawinsights.enabled`
+`plugins.entries.cnpclawinsights.enabled`
 
-- 是否启用插件本身
+- 是否启用这个插件条目
 - 必须为 `true`
 
-`cnpclawinsights.otel.enabled`
+`plugins.entries.cnpclawinsights.config.enabled`
 
-- 是否启用 OTel 导出
-- 必须为 `true`
+- 可选的插件内部总开关
+- 不写时默认按启用处理
+- 只有显式写成 `false` 才会关闭
+
+`plugins.entries.cnpclawinsights.config.otel.enabled`
 
-`cnpclawinsights.otel.protocol`
+- 可选的 OTel 导出开关
+- 不写时默认按启用处理
+- 只有显式写成 `false` 才会关闭
+
+`plugins.entries.cnpclawinsights.config.otel.protocol`
 
 - 目前只支持 `http/protobuf`
 - 不配置时默认也是 `http/protobuf`
 
-`cnpclawinsights.otel.endpoint`
+`plugins.entries.cnpclawinsights.config.otel.endpoint`
 
 - 通用 OTLP endpoint
 - 例如 `http://127.0.0.1:4318`
+- 不配置时默认值是 `http://127.0.0.1:4318`
 - 如果不带 `/v1/traces`、`/v1/metrics`、`/v1/logs`，插件会自动补全对应路径
 
-`cnpclawinsights.otel.traces`
+`plugins.entries.cnpclawinsights.config.otel.traces`
 
 - 是否导出 traces
 - 默认 `true`
 
-`cnpclawinsights.otel.metrics`
+`plugins.entries.cnpclawinsights.config.otel.metrics`
 
 - 是否导出 metrics
 - 默认 `true`
 
-`cnpclawinsights.otel.logs`
+`plugins.entries.cnpclawinsights.config.otel.logs`
 
 - 是否导出 logs
 - 默认 `false`
 
-`cnpclawinsights.otel.tracesEndpoint`
+`plugins.entries.cnpclawinsights.config.otel.tracesEndpoint`
 
 - 单独指定 traces 导出地址
 - 优先级高于 `endpoint`
 
-`cnpclawinsights.otel.metricsEndpoint`
+`plugins.entries.cnpclawinsights.config.otel.metricsEndpoint`
 
 - 单独指定 metrics 导出地址
 - 优先级高于 `endpoint`
 
-`cnpclawinsights.otel.logsEndpoint`
+`plugins.entries.cnpclawinsights.config.otel.logsEndpoint`
 
 - 单独指定 logs 导出地址
 - 优先级高于 `endpoint`
 
-`cnpclawinsights.otel.serviceName`
+`plugins.entries.cnpclawinsights.config.otel.serviceName`
 
 - OpenTelemetry service name
 - 不配置时优先读取环境变量 `OTEL_SERVICE_NAME`
 - 如果环境变量也没有，默认值是 `openclaw`
 
-`cnpclawinsights.otel.sampleRate`
+`plugins.entries.cnpclawinsights.config.otel.sampleRate`
 
 - trace 采样率
 - 取值范围 `0` 到 `1`
 
-`cnpclawinsights.otel.flushIntervalMs`
+`plugins.entries.cnpclawinsights.config.otel.flushIntervalMs`
 
 - metrics 周期导出间隔
 - 也用于 logs 批量刷新间隔
 - 最小值为 `1000`
 
-`cnpclawinsights.otel.headers`
+`plugins.entries.cnpclawinsights.config.otel.headers`
 
 - OTLP 请求头
 - 适合传认证信息
 
-`cnpclawinsights.otel.captureContent`
+`plugins.entries.cnpclawinsights.config.otel.captureContent`
 
 - 控制是否导出消息内容
 - 默认不采集正文内容
 
-`cnpclawinsights.otel.captureContent = true`
+`plugins.entries.cnpclawinsights.config.otel.captureContent = true`
 
 - 开启后会采集：
 - `inputMessages`
@@ -179,7 +285,7 @@ openclaw plugins install @cnpinsight/cnpclawinsights@2.0.0
 - `toolOutputs`
 - `systemPrompt` 仍默认不采集
 
-`cnpclawinsights.otel.captureContent = { ... }`
+`plugins.entries.cnpclawinsights.config.otel.captureContent = { ... }`
 
 - 可以按字段精细控制：
 - `enabled`
@@ -191,7 +297,15 @@ openclaw plugins install @cnpinsight/cnpclawinsights@2.0.0
 
 ## 环境变量回退
 
-如果部分配置未写入 `openclaw.json`，插件还会回退读取这些标准 OTel 环境变量：
+如果部分配置未写入 `plugins.entries.cnpclawinsights.config`，插件会按下面的优先级取值：
+
+1. `config.otel` 里的显式配置
+2. 对应的标准 OTel 环境变量
+3. 插件内置默认值
+
+其中 endpoint 的内置默认值是 `http://127.0.0.1:4318`。
+
+相关环境变量包括：
 
 - `OTEL_EXPORTER_OTLP_PROTOCOL`
 - `OTEL_EXPORTER_OTLP_ENDPOINT`
@@ -218,29 +332,63 @@ openclaw plugins install @cnpinsight/cnpclawinsights@2.0.0
 
 ```json
 {
-  "cnpclawinsights": {
-    "enabled": true,
-    "otel": {
-      "enabled": true,
-      "endpoint": "http://127.0.0.1:4318",
-      "logs": true
+  "plugins": {
+    "entries": {
+      "cnpclawinsights": {
+        "enabled": true,
+        "config": {
+          "otel": {
+            "endpoint": "http://127.0.0.1:4318",
+            "logs": true
+          }
+        }
+      }
     }
   }
 }
 ```
 
-### 3. 为什么配置了但没有导出
+### 3. 为什么只写了 `enabled: true` 也能工作
 
-请同时确认下面两个开关都为 `true`：
+插件现在支持最简模式：
 
 ```json
 {
-  "cnpclawinsights": {
-    "enabled": true,
-    "otel": {
-      "enabled": true
+  "plugins": {
+    "entries": {
+      "cnpclawinsights": {
+        "enabled": true
+      }
     }
   }
 }
 ```
 
+这时会默认：
+
+- 使用 `http/protobuf`
+- 发往 `http://127.0.0.1:4318`
+- 开启 traces 和 metrics
+- 关闭 logs
+
+### 4. 为什么配置了但没有导出
+
+如果你显式写了下面任意一个值为 `false`，插件就不会导出：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "cnpclawinsights": {
+        "enabled": true,
+        "config": {
+          "enabled": false,
+          "otel": {
+            "enabled": false
+          }
+        }
+      }
+    }
+  }
+}
+```

package/dist/cli.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const PLUGIN_ID = "cnpclawinsights";
+const LEGACY_PLUGIN_ID = "cnpclawinsight";
+const DEFAULT_CONFIG_PATH = path.join(os.homedir(), ".openclaw", "openclaw.json");
+const DEFAULT_ENDPOINT = "http://127.0.0.1:4318";
+
+function printHelp() {
+  console.log(`Usage:
+  cnpclawinsights-install [options]
+
+Options:
+  --config-path <path>       Path to openclaw.json
+  --endpoint <url>           OTLP endpoint, default: ${DEFAULT_ENDPOINT}
+  --service-name <name>      OpenTelemetry service name
+  --logs                     Enable logs export
+  --no-logs                  Disable logs export
+  --traces                   Enable traces export
+  --no-traces                Disable traces export
+  --metrics                  Enable metrics export
+  --no-metrics               Disable metrics export
+  --sample-rate <0..1>       Trace sampling rate
+  --flush-interval-ms <ms>   Export flush interval
+  --header <k=v>             Add OTLP header, repeatable
+  --non-interactive          Run without prompts
+  --help                     Show this help
+`);
+}
+
+function fail(message) {
+  console.error(`cnpclawinsights-install: ${message}`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const options = {
+    configPath: DEFAULT_CONFIG_PATH,
+    endpoint: DEFAULT_ENDPOINT,
+    headers: {}
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--config-path":
+        options.configPath = argv[++i];
+        break;
+      case "--endpoint":
+        options.endpoint = argv[++i];
+        break;
+      case "--service-name":
+        options.serviceName = argv[++i];
+        break;
+      case "--logs":
+        options.logs = true;
+        break;
+      case "--no-logs":
+        options.logs = false;
+        break;
+      case "--traces":
+        options.traces = true;
+        break;
+      case "--no-traces":
+        options.traces = false;
+        break;
+      case "--metrics":
+        options.metrics = true;
+        break;
+      case "--no-metrics":
+        options.metrics = false;
+        break;
+      case "--sample-rate":
+        options.sampleRate = Number(argv[++i]);
+        break;
+      case "--flush-interval-ms":
+        options.flushIntervalMs = Number(argv[++i]);
+        break;
+      case "--header": {
+        const raw = argv[++i];
+        const eqIndex = raw.indexOf("=");
+        if (eqIndex <= 0) fail(`invalid --header value: ${raw}`);
+        const key = raw.slice(0, eqIndex).trim();
+        const value = raw.slice(eqIndex + 1).trim();
+        if (!key || !value) fail(`invalid --header value: ${raw}`);
+        options.headers[key] = value;
+        break;
+      }
+      case "--non-interactive":
+        options.nonInteractive = true;
+        break;
+      case "--help":
+      case "-h":
+        options.help = true;
+        break;
+      default:
+        fail(`unknown argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function ensureParentDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function readConfig(configPath) {
+  if (!fs.existsSync(configPath)) {
+    return {};
+  }
+  try {
+    return JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch (error) {
+    fail(`failed to parse config file ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function normalizePluginEntry(entries) {
+  const pluralEntry = entries[PLUGIN_ID];
+  if (pluralEntry && typeof pluralEntry === "object") {
+    return pluralEntry;
+  }
+  const legacyEntry = entries[LEGACY_PLUGIN_ID];
+  if (legacyEntry && typeof legacyEntry === "object") {
+    delete entries[LEGACY_PLUGIN_ID];
+    entries[PLUGIN_ID] = legacyEntry;
+    return legacyEntry;
+  }
+  const entry = {};
+  entries[PLUGIN_ID] = entry;
+  return entry;
+}
+
+function buildPluginConfig(options) {
+  const otel = {
+    endpoint: options.endpoint
+  };
+
+  if (options.logs !== undefined) otel.logs = options.logs;
+  if (options.traces !== undefined) otel.traces = options.traces;
+  if (options.metrics !== undefined) otel.metrics = options.metrics;
+  if (options.serviceName) otel.serviceName = options.serviceName;
+  if (options.sampleRate !== undefined) otel.sampleRate = options.sampleRate;
+  if (options.flushIntervalMs !== undefined) otel.flushIntervalMs = options.flushIntervalMs;
+  if (Object.keys(options.headers).length > 0) otel.headers = options.headers;
+
+  return { otel };
+}
+
+function writeConfig(configPath, config) {
+  ensureParentDir(configPath);
+  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  if (options.sampleRate !== undefined && (!Number.isFinite(options.sampleRate) || options.sampleRate < 0 || options.sampleRate > 1)) {
+    fail("--sample-rate must be a number between 0 and 1");
+  }
+
+  if (options.flushIntervalMs !== undefined && (!Number.isInteger(options.flushIntervalMs) || options.flushIntervalMs < 1000)) {
+    fail("--flush-interval-ms must be an integer >= 1000");
+  }
+
+  const config = readConfig(options.configPath);
+  if (!config.plugins || typeof config.plugins !== "object" || Array.isArray(config.plugins)) {
+    config.plugins = {};
+  }
+  if (!config.plugins.entries || typeof config.plugins.entries !== "object" || Array.isArray(config.plugins.entries)) {
+    config.plugins.entries = {};
+  }
+  const entry = normalizePluginEntry(config.plugins.entries);
+  entry.enabled = true;
+  entry.config = {
+    ...(entry.config && typeof entry.config === "object" && !Array.isArray(entry.config) ? entry.config : {}),
+    ...buildPluginConfig(options)
+  };
+
+  if (!Array.isArray(config.plugins.allow)) {
+    config.plugins.allow = [];
+  }
+  if (!config.plugins.allow.includes(PLUGIN_ID)) {
+    config.plugins.allow.push(PLUGIN_ID);
+  }
+  config.plugins.allow = config.plugins.allow.filter((value, index, values) => value !== LEGACY_PLUGIN_ID || values.indexOf(PLUGIN_ID) === -1);
+
+  writeConfig(options.configPath, config);
+
+  console.log(`Updated ${options.configPath}`);
+  console.log(`Configured plugins.entries.${PLUGIN_ID}.enabled = true`);
+  console.log(`Configured plugins.entries.${PLUGIN_ID}.config.otel.endpoint = ${options.endpoint}`);
+  if (options.logs !== undefined) {
+    console.log(`Configured plugins.entries.${PLUGIN_ID}.config.otel.logs = ${String(options.logs)}`);
+  }
+}
+
+main();

package/dist/index.js

@@ -44,6 +44,7 @@ const OTEL_EXPORTER_OTLP_ENDPOINT_ENV = "OTEL_EXPORTER_OTLP_ENDPOINT";
 const OTEL_EXPORTER_OTLP_TRACES_ENDPOINT_ENV = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
 const OTEL_EXPORTER_OTLP_METRICS_ENDPOINT_ENV = "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT";
 const OTEL_EXPORTER_OTLP_LOGS_ENDPOINT_ENV = "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT";
+const DEFAULT_OTLP_HTTP_ENDPOINT = "http://127.0.0.1:4318";
 const OTEL_SEMCONV_STABILITY_OPT_IN_ENV = "OTEL_SEMCONV_STABILITY_OPT_IN";
 const GEN_AI_LATEST_EXPERIMENTAL_OPT_IN = "gen_ai_latest_experimental";
 const GEN_AI_TOKEN_USAGE_BUCKETS = [
@@ -354,9 +355,9 @@ function createDiagnosticsOtelService() {
 		id: "cnpclawinsights",
 		async start(ctx) {
 			await stopStarted();
-			const cfg = ctx.config.cnpclawinsights;
-			const otel = cfg?.otel;
-			if (!cfg?.enabled || !otel?.enabled) return;
+			const cfg = ctx.config?.cnpclawinsights ?? ctx.config ?? {};
+			const otel = cfg?.otel ?? {};
+			if (cfg?.enabled === false || otel.enabled === false) return;
 			const emitExporterEvent = (event) => {
 				try {
 					ctx.internalDiagnostics?.emit({
@@ -390,7 +391,7 @@ function createDiagnosticsOtelService() {
 				ctx.logger.warn(`cnpclawinsights: unsupported protocol ${protocol}`);
 				return;
 			}
-			const endpoint = normalizeEndpoint(otel.endpoint ?? process.env[OTEL_EXPORTER_OTLP_ENDPOINT_ENV]);
+			const endpoint = normalizeEndpoint(otel.endpoint ?? process.env[OTEL_EXPORTER_OTLP_ENDPOINT_ENV] ?? DEFAULT_OTLP_HTTP_ENDPOINT);
 			const headers = otel.headers ?? void 0;
 			const serviceName = otel.serviceName?.trim() || process.env.OTEL_SERVICE_NAME || DEFAULT_SERVICE_NAME;
 			const sampleRate = resolveSampleRate(otel.sampleRate);

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@cnpinsight/cnpclawinsights",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "OpenClaw insights OpenTelemetry exporter",
   "repository": {
     "type": "git",
     "url": "https://github.com/openclaw/openclaw"
   },
   "type": "module",
+  "bin": {
+    "cnpclawinsights-install": "dist/cli.mjs"
+  },
   "dependencies": {
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/api-logs": "0.218.0",