@lark-apaas/openclaw-telemetry

OpenClaw 遥测插件。把 hook 事件写入本地 JSONL。

输出方式

• JSONL 文件 — 在 gateway_start 之后写入 <stateDir>/logs/telemetry.jsonl，自动轮转（10MB / 5 个文件 / gzip 压缩）

配置

{
  "plugins": {
    "entries": {
      "openclaw-telemetry": {
        "enabled": true,
        "config": {
          // 可选：默认 false；开启后 telemetry 自身日志会写入 $TMPDIR/openclaw-telemetry.log
          "debug": false,
          // 可选：默认 "*"；字符串 "*"、数组 ["*"] 或缺省表示监听全部钩子，
          // 也可以传数组只监听部分钩子，例如 ["llm_output", "message_received"]
          "events": "*"
        }
      }
    }
  }
}

events 取值说明：

| 值 | 行为 | |----|------| | "*" / ["*"] / null / 缺省 | 订阅全部 24 个已知 hook | | string[] | 仅订阅数组中列出的 hook | | 未知 hook 名 | 记 warn 后忽略，不阻止启动 | | 其他非法类型 | 记 warn 后降级为 "*" |

空数组 [] 是合法值，表示除网关生命周期外不订阅任何业务 hook。

事件格式

每条事件含完整 hook event 与 context，不做字段筛选：

{
  "type": "llm_output",
  "evt": { "runId": "...", "provider": "...", "model": "...", "usage": {...} },
  "ctx": { "sessionKey": "agent:main:main", "agentId": "main", "trigger": "user" },
  "seq": 42,
  "ts": 1738517700000
}

支持的 hook

见 src/hooks.ts 的 ALL_HOOKS——共 24 个，覆盖 model/prompt、agent 生命周期、LLM I/O、压缩/重置、消息、工具、会话、子 agent、网关全链路。

debug 模式

debug: true 时 telemetry 自身调试日志会写入 $TMPDIR/openclaw-telemetry.log。注意这个开关不影响业务 JSONL；业务事件会在 gateway_start 后写入 <stateDir>/logs/telemetry.jsonl。

构建

yarn build        # tsdown 出到 dist/
yarn build:dev    # 不 minify
yarn test         # vitest

与 openclaw-miaoda-keepalive 的关系

本插件保存 raw {type, evt, ctx}，为上游分析留足信息，并通过 config.events 支持运维侧按需裁剪。