OpenClaw可观测性数据接入Agent-lens和一站式可观测-云数据库 ClickHouse-阿里云帮助中心

openclaw-exporter-to-langfuse是OpenClaw的可观测性扩展插件，支持将Agent运行数据投递到云数据库ClickHouse的Agent-lens和一站式可观测平台，帮助您全面监控和分析Agent应用的运行状态。

背景信息

openclaw-exporter-to-langfuse提供两类互补的可观测能力：

能力	数据链路	投递组件	主要用途	查看工具
投递到Agent-lens	OpenClaw → openclaw-exporter-to-langfuse → Langfuse	openclaw-exporter-to-langfuse	分析单次Agent调用链路与LLM交互效果	Langfuse
投递到一站式可观测	OpenClaw → diagnostics-otel → otelcol-contrib → ClickHouse	otelcol-contrib	分析OpenClaw运行指标、Gateway日志与整体健康状态	HyperDX

开源地址：https://github.com/aliyun/openclaw-exporter-to-langfuse

使用限制

OpenClaw插件openclaw-exporter-to-langfuse需要Node.js 18及以上版本。
投递Trace、Metric和Log到一站式可观测时，OpenClaw需支持diagnostics-otel插件，建议OpenClaw版本不低于v2026.2.19。
otelcol-contrib默认监听4317和4318端口，请确保端口未被占用。

前提条件

已创建云数据库ClickHouse集群，并获取以下信息：
- VPC地址
- 用户名（例如openclaw，需具备读写权限）
- 密码
已在控制台为ClickHouse集群开启一站式可观测。
已在控制台为ClickHouse集群开启Agent观测套件（Agent-lens），创建项目并获取：
- VPC地址
- Public Key（格式为pk-lf-xxx）
- Secret Key（格式为sk-lf-yyy）
已安装并运行OpenClaw。

注意事项

Trace、Metric、Log是不同的观测维度。默认情况下，Trace进入Agent-lens，Metric和Log进入一站式可观测。
如需在一站式可观测中分析Trace，需要在安装时指定--diag-traces true参数。
ClickHouse时区需设置为UTC时区，否则Agent观测套件可能出现数据异常。

操作步骤

通过OpenClaw一键安装

推荐通过OpenClaw对话方式完成安装。OpenClaw会自动识别本机配置路径、安装目录和运行环境。

让OpenClaw下载安装说明

在OpenClaw对话框中输入以下内容：

下载安装文件（如果存在则覆盖）：https://ck-langfuse-public.oss-cn-beijing.aliyuncs.com/openclaw-exporter-to-langfuse/INSTALLATION.md，按照提示进行安装。

OpenClaw将返回安装参数的填写说明。

提供安装参数并执行安装

在OpenClaw对话框中输入以下内容，并将参数替换为实际值：

同时安装 openclaw-exporter-to-langfuse 和 otelcol-contrib。

openclaw-exporter-to-langfuse 配置：
endpoint = http://<LANGFUSE_ENDPOINT>:3000/api/public/otel/v1/traces
pk = <PK>
sk = <SK>
serviceName = <SERVICE_NAME>
debug = true

otelcol-contrib 配置：
ck-endpoint = http://<CK_ENDPOINT>:8123
用户名 = <USERNAME>
密码 = <PASSWORD>

参数说明：

参数	说明
`endpoint`	Langfuse Trace入口地址。将`<LANGFUSE_ENDPOINT>`替换为Agent-lens的VPC地址。
`pk`	Agent-lens项目的Public Key。
`sk`	Agent-lens项目的Secret Key。
`serviceName`	Agent服务名称，用于标识数据来源。
`debug`	是否开启插件debug日志。首次安装或排查问题时建议设置为`true`。
`ck-endpoint`	ClickHouse集群接入地址。将`<CK_ENDPOINT>`替换为集群的VPC地址。
`用户名`	ClickHouse集群用户名。
`密码`	ClickHouse集群密码。

OpenClaw返回安装成功后，表示openclaw-exporter-to-langfuse与otelcol-contrib均已完成配置。

查看组件配置
在OpenClaw对话框中输入以下内容确认安装结果：
```
查看两个组件的配置
```
OpenClaw将返回两个组件的安装状态和配置信息，预期输出包括：
- openclaw-exporter-to-langfuse（Langfuse插件）：显示enabled为true，以及endpoint、authorization、serviceName等参数及其配置值。
- diagnostics-otel + otelcol-contrib（一站式可观测）：显示diagnostics-otel的启用状态、端点地址等参数，以及otelcol-contrib服务的运行状态、gRPC/HTTP接收端口和ClickHouse接入信息。
如果两个组件均显示为已启用且参数正确，表示安装成功。

验证数据同步

通过Agent观测套件查看Trace

登录Agent观测套件控制台。
进入对应项目。
打开Traces页面。
在OpenClaw中发起一次Agent对话。
检查是否生成新的Trace记录。

如果配置正确，Traces列表中将出现新的Trace记录。点击某条Trace可查看完整的调用链路树（包括enter_openclaw_system、invoke_agent_main、tool_call等节点），以及每个节点的耗时、Token消耗、输入输出内容和LLM交互详情。

通过ClickHouse验证数据

登录ClickHouse后执行以下SQL语句验证数据是否成功写入：

SHOW DATABASES;

SHOW TABLES FROM clickobserve_service;

SELECT count() FROM clickobserve_service.otel_logs;

SELECT count() FROM clickobserve_service.otel_metrics_sum;

通过一站式可观测查看和分析

登录ClickHouse一站式可观测控制台。
通过AI Notebook分析数据。

常见分析示例：

查看过去 1 小时 OpenClaw 错误日志

AI Notebook将自动分析查询意图，生成对应的SQL语句并执行，最终返回错误日志的时间、来源、错误内容等分析结果。

常见问题

一站式可观测中看不到Trace

默认情况下Trace只进入Langfuse（Agent-lens），不进入ClickHouse一站式可观测。如需在一站式可观测中分析Trace，请重新安装并增加以下参数：

--diag-traces true