为AI Agent构建可观测性平台:从OpenTelemetry到成本与性能监控
1. 项目概述:为AI Agent打造的可观测性平台
如果你正在使用OpenClaw这类AI Agent框架,并且已经不止一次地对着日志文件发愁,想知道“刚才那个任务到底花了多少钱?”、“哪个工具调用又失败了?”或者“这次上下文膨胀是不是又失控了?”,那么你遇到的情况,正是我当初决定深入折腾clawo11y这个项目的起点。这不仅仅是一个监控面板,它是一个专门为AI Agent工作流设计的可观测性堆栈,目标是把那些隐藏在运行时事件和原始遥测数据背后的业务洞察,清晰地呈现出来。
简单来说,clawo11y帮你回答几个核心问题:成本(钱花哪儿了)、性能(哪儿慢了)、可靠性(哪儿出错了)以及安全(有没有危险操作)。它通过一个轻量级的Go代理(Agent)收集本地OpenClaw的状态和日志,并通过一个可选的OpenTelemetry插件,将Agent内部运行时事件转化为结构化的追踪、指标和日志数据。这些数据被发送到一个中心化的Go服务器(Server)进行存储、聚合,最终在一个专注于业务视图而非原始数据管道的React前端(Web)上展示。这意味着,你看到的不是冰冷的每秒请求数,而是“单次运行成本最高的会话”、“最不稳定的模型”或者“疑似陷入循环导致上下文爆炸的任务”。
2. 核心架构与设计思路拆解
clawo11y的设计清晰地分为了两层:运行时事件视图和OTel原生Agent可观测性。理解这两层的区别和协作方式,是有效部署和使用它的关键。
2.1 双层观测模型:从事件到洞察
第一层,运行时事件视图,是基础。它依赖于部署在AI Agent工作节点上的clawo11y-agent。这个Go进程就像一个本地哨兵,持续监视~/.openclaw目录下的状态文件(如会话、定时任务记录)和网关日志。它解析这些原生事件——比如llm_input、after_tool_call、agent_end——并将它们实时转发到中心服务器。这一层为你提供了最直接的运行概览:有哪些活跃会话、令牌消耗趋势、定时任务执行历史、工作空间状态以及实时日志流。它的优势是轻量、无侵入,只要Agent能访问OpenClaw的目录和日志,你就能立刻获得这个基础的监控能力。
注意:这一层的数据粒度相对较粗,它基于OpenClaw运行时暴露的事件,可能不包含每次LLM调用的详细用量(如输入/输出token数),因此无法进行精确的成本计算。
第二层,OTel原生Agent可观测性,是进阶能力,也是整个项目的精髓所在。要启用这一层,你必须在OpenClaw运行时中安装并配置openclaw-otel-plugin插件。这个插件运行在Agent进程内部,能够“深入肌理”,将每一次LLM调用、工具执行、子代理启动都转化为标准的OpenTelemetry数据(Trace, Metric, Log)。这些富含细节的数据(包括每次调用的token数、模型、耗时、错误信息)通过OTLP协议发送给本地的clawo11y-agent(它内置了一个OTLP代理),再中转到中心服务器。
这一层解锁了真正的深度洞察:
- 成本面板:基于真实的token消耗和预设的模型单价,计算并展示总花费、日均趋势、模型开销占比。
- 追踪视图:以树状或瀑布图形式展示一次完整“运行”(Run)的调用链,让你看清从主任务到每一个嵌套工具调用的全貌。
- 上下文膨胀预警:通过分析提示token的增长模式,自动标记出那些可能陷入无意义循环或上下文无限扩大的会话。
- 安全时间线:自动分类并高亮显示高风险操作,如执行Shell命令、代码运行、文件系统修改等。
2.2 数据流与组件职责
整个系统的数据流可以概括为以下路径:
OpenClaw 运行时事件 ↓ (通过插件转化) OpenTelemetry 数据 (Traces, Metrics, Logs) ↓ (通过 OTLP/gRPC 或 HTTP) clawo11y-agent (本地 OTLP 代理) ↓ (通过 HTTP 转发) clawo11y-server (中心服务器) ↓ (存储与聚合) SQLite 数据库 ↓ (API 查询) React 前端 Dashboard每个组件的职责非常明确:
openclaw-otel-plugin:数据生产者。负责埋点、转换、发射遥测数据。它是获取高质量数据的源头。clawo11y-agent:数据收集与转发者。兼职工:一是作为OTLP接收端,二是作为本地事件日志的抓取器。它需要部署在每一个运行OpenClaw Agent的工作节点上。clawo11y-server:数据大脑。接收所有数据,进行聚合、存储(SQLite),并提供查询API。通常一个集群部署一个即可。services/web:数据展示者。提供用户交互界面,将服务器处理后的数据以业务视角(成本、性能、安全)呈现。
这种分离架构的好处是显而易见的:Agent轻量,便于大规模部署;Server集中处理,方便数据聚合分析;前端专注展示逻辑。在实际部署时,你需要根据你的环境是单机开发、多节点测试还是生产集群,来选择不同的部署模式。
3. 部署模式详解与实操要点
clawo11y提供了从快速体验到生产部署的多种方式。选择哪种,取决于你的使用场景和基础设施。
3.1 快速体验模式:Docker Compose一键启动
这是最快上手的方式,适合本地评估或演示。它会在单台机器上启动所有组件。
git clone https://github.com/danl5/clawo11y.git cd clawo11y docker compose up -d执行后,Docker Compose会启动两个服务:
clawo11y-server+clawo11y-web:中心服务器和前端界面,通常映射到主机的8000端口。clawo11y-agent:工作节点代理。这里有一个关键配置:在docker-compose.yml中,它将宿主机的~/.openclaw目录挂载到了容器内。这是为了让Agent能够读取到OpenClaw的运行时数据。
实操心得:如果你的OpenClaw数据目录不在默认的
~/.openclaw,务必在启动前修改docker-compose.yml中clawo11y-agent服务的volumes配置。例如,如果你的数据在/opt/openclaw/data,则需要将挂载项改为- /opt/openclaw/data:/root/.openclaw:ro(建议只读挂载)。
启动后,访问http://localhost:8000就能看到Web界面。此时,由于只部署了Agent和Server,你只能看到运行时事件视图(Overview, Tokens, Sessions等)。要解锁完整的OTel能力,还需要完成后续的插件安装。
3.2 本地开发模式:分组件独立运行
如果你打算参与贡献或进行深度定制,在本地分别启动各个组件是最佳方式。这需要你的开发环境已安装Go、Node.js等。
# 克隆代码 git clone https://github.com/danl5/clawo11y.git cd clawo11y # 终端1:启动中心服务器 cd services/server go run . # 或 make run # 终端2:启动前端开发服务器 cd services/web npm install npm run dev # 通常前端会运行在如 3000 端口,并通过代理连接后端 8000 端口 # 终端3:启动工作节点代理 cd services/agent # 需要指定中心服务器的地址,假设服务器运行在本机 8000 端口 O11Y_SERVER_URL=http://127.0.0.1:8000 go run .这种模式下,各个组件日志分离,方便调试。你需要确保Agent配置的环境变量O11Y_SERVER_URL指向了正确的服务器地址。
3.3 生产部署模式:裸金属与服务分离
对于正式环境,通常建议将Server和Agent分离部署,以获得更好的可扩展性和资源隔离。
部署中心服务器:
- 选择一台机器作为可观测性服务器,确保网络可达。
- 构建或下载Server和Web的二进制文件/静态资源。项目提供了Makefile简化步骤:
git clone https://github.com/danl5/clawo11y.git cd clawo11y make build-web build-server # 这会构建前端资源并编译Go服务器 - 启动服务器。你可以直接运行二进制文件,但更推荐使用systemd等进程管理器托管:
# 直接运行 ./bin/clawo11y-server # 使用systemd(推荐) sudo cp scripts/o11y-server.service /etc/systemd/system/ # 编辑服务文件,确认二进制路径、工作目录、用户、环境变量(如监听地址、数据库路径)正确 sudo systemctl daemon-reload sudo systemctl enable --now o11y-server
部署工作节点Agent:
- 在每一台运行OpenClaw Agent的机器上,部署
clawo11y-agent。 - 同样进行构建:
cd clawo11y make build-agent - 启动Agent。最关键的一步是设置
O11Y_SERVER_URL环境变量,指向你上一步部署的中心服务器地址。O11Y_SERVER_URL=http://<your-server-ip>:8000 ./bin/clawo11y-agent - 同样建议使用systemd管理:
sudo cp scripts/o11y-agent.service /etc/systemd/system/ # 编辑服务文件,必须设置 O11Y_SERVER_URL 环境变量! sudo systemctl daemon-reload sudo systemctl enable --now o11y-agent
注意事项:生产部署时,务必考虑网络安全性。如果Server和Agent跨公网或不同安全域通信,应配置TLS加密。目前项目默认使用HTTP,在敏感环境中你需要通过反向代理(如Nginx)为Server添加HTTPS,并确保Agent端配置的
O11Y_SERVER_URL使用https协议。
4. 核心功能实现:插件配置与数据打通
要让clawo11y发挥全部威力,安装和配置openclaw-otel-plugin是必不可少的一步。这个插件是连接OpenClaw运行时与clawo11y OTel体系的桥梁。
4.1 插件安装与配置
插件位于项目根目录的openclaw-otel-plugin文件夹中。安装方式如下:
# 进入项目目录 cd /path/to/clawo11y # 在OpenClaw环境中安装插件 openclaw plugins install ./openclaw-otel-plugin安装后,需要在OpenClaw的配置文件(通常是~/.openclaw/openclaw.json)中启用并配置插件。一个完整的配置示例如下:
{ "plugins": { "entries": { "@clawo11y/openclaw-otel-plugin": { "enabled": true, "config": { "endpoint": "http://localhost:4318", "metric_interval_ms": 30000, "export_timeout_ms": 10000, "root_idle_timeout_ms": 300000, "pricing": { "gpt-4o": { "prompt": 5.0, "completion": 15.0 }, "gpt-4-turbo": { "prompt": 10.0, "completion": 30.0 }, "claude-3-opus": { "prompt": 15.0, "completion": 75.0 }, "claude-3-sonnet": { "prompt": 3.0, "completion": 15.0 } } } } } } }关键配置项解析:
endpoint: 指向clawo11y-agent提供的本地OTLP接收地址,默认是http://localhost:4318。如果Agent部署在容器内或不同网络,需相应调整。metric_interval_ms: 指标数据的推送间隔,单位为毫秒。太短会增加负载,太长则实时性差,30秒是个平衡点。pricing:这是成本计算的核心!你必须在这里为你使用的每个模型配置单价(通常单位是每百万tokens的美元或人民币费用)。插件会使用这里的价格,结合LLM调用返回的usage字段中的token数,计算出每次调用的成本。如果模型未配置单价,成本面板中将显示为0或未知。
配置完成后,重启OpenClaw网关以使插件生效:
openclaw gateway restart4.2 数据源与成本计算原理
理解成本数据的来源至关重要,因为它决定了面板上数字的准确性。clawo11y的成本计算依赖于两个可能的数据源:
OTel路径(主要来源):当插件启用后,每次LLM调用结束,OpenClaw运行时通常会返回一个
usage对象(包含prompt_tokens,completion_tokens)。插件会捕获这个信息,并将其附加到对应的Trace Span上。中心服务器在接收到Trace数据后,会根据插件配置中pricing字段对应的模型单价,进行成本计算:成本 = (prompt_tokens * prompt单价 + completion_tokens * completion单价) / 1,000,000。运行时事件路径(辅助/备用):即使没有插件,Agent通过解析OpenClaw日志也可能获得一些token信息,但通常不完整或格式不一致,主要用于基础的Tokens视图,无法用于精确的、按模型划分的成本分析。
常见问题:如果你的成本面板显示为0或明显不准,请按以下步骤排查:
- 检查插件是否真的生效:在OpenClaw日志中搜索“otel”或“clawo11y”,看是否有插件加载和发送数据的记录。
- 检查模型单价配置:确认
openclaw.json中pricing字段包含了你正在使用的所有模型,且单价正确。模型名称必须与API调用中使用的名称完全一致(区分大小写)。- 检查LLM提供商是否返回usage:并非所有提供商或所有模型都返回标准的token用量。你需要确认你的OpenClaw LLM配置和调用方式能获取到
usage数据。- 检查网络连通性:确认插件配置的
endpoint(localhost:4318) 确实能被访问。可以尝试用curl命令测试:curl -v http://localhost:4318/v1/traces(虽然可能返回405,但能确认服务存在)。
5. 核心功能视图深度解析
成功部署并配置好插件后,你将在Web界面上看到一系列强大的功能视图。这些视图不是简单的数据罗列,而是经过聚合和关联分析后的业务洞察。
5.1 FinOps for AI:把AI开销管起来
这是clawo11y最具价值的模块之一,它让AI实验的成本从“黑盒”变得透明。
- 成本仪表盘 (Cost Dashboard):这里展示全局视图。你会看到总花费、总调用次数、总token消耗以及平均每次调用成本。下方的趋势图会按天、按模型提供商(如OpenAI、Anthropic)堆叠显示成本,让你一眼看出花钱的大头在哪天、哪个提供商。另一个饼图则展示不同模型间的成本分布,帮你识别出“贵”的模型。
- 高成本运行排行 (Top Expensive Runs):这个列表直接揪出“烧钱大王”。它从所有根追踪(Root Trace)中,汇总出单次会话(Session)或运行(Run)的总成本,并降序排列。点击任意一项,可以直接钻取到该次运行的详细追踪视图。
- 成本/令牌火焰图 (Cost Flame Graph):在追踪详情页,你可以切换到“Cost”或“Token”模式查看火焰图。这个视图将一次运行中每个Span(LLM调用、工具执行)的成本或token消耗,用横向堆叠条的长度直观表示。哪个步骤最“烧钱”,一目了然。这对于优化复杂工作流、定位成本瓶颈极其有效。
- 上下文膨胀预警 (Context Bloat Alert):这是一个智能检测功能。AI Agent有时会陷入循环或反复检索无关信息,导致提示(Prompt)的token数不断增长,既拖慢速度又增加成本。clawo11y会分析会话过程中提示token的增长曲线,如果发现异常的增长模式(如指数增长、长时间线性增长),就会在“Context Bloat Candidates”区域标记出来,提醒你介入审查。
5.2 Agent调试:深入每一次调用
当Agent行为不符合预期时,传统的日志排查如同大海捞针。clawo11y的调试视图提供了手术刀般的精度。
- 深度追踪视图 (Deep Trace View):这是整个系统的核心。它以树状结构完整还原一次“运行”的生命周期。从根部的
command.process开始,向下展开每一次LLM调用、每一个工具执行、每一层子代理的调用。每个Span节点都包含了丰富的信息:持续时间、使用的模型、提供商、成本、输入输出token数、错误状态、关键参数甚至输出摘要。你可以像查看分布式系统调用链一样,看清AI工作流的执行脉络。 - 工具可靠性矩阵 (Tool Reliability Matrix):以表格形式汇总所有被调用过的工具。表格列包括:调用次数、错误次数、错误率、平均延迟、P95延迟、最大延迟。这个视图能迅速帮你发现团队中哪个自定义工具或API接口最不稳定、最慢,是进行性能优化和稳定性建设的关键依据。
- 可观测性健康度 (Observability Health):这个视图监控的是可观测性系统自身的数据质量。它会报告诸如“根追踪重建”(可能因数据丢失导致)、“孤儿事件”(未能关联到父Span的事件)、“空闲超时关闭”等异常。这些指标能帮助你判断当前收集到的数据是否完整、可靠。
5.3 安全与合规:为AI操作加上审计
让AI执行工具(尤其是Shell、文件操作)存在固有风险。clawo11y的安全模块提供了事中可监控、事后可审计的能力。
- 高风险操作时间线 (High-Risk Operation Timeline):插件内置了风险分类规则,会自动将工具调用标记为不同风险等级,例如:
- Shell:执行任意Shell命令。
- 代码执行:在沙箱或环境中运行代码。
- 文件系统变更:创建、删除、修改文件。
- 网络访问:发起外部网络请求。 时间线视图按发生顺序列出所有这些操作,并展示风险类别、原因、参数预览、持续时间和错误状态。这为安全审查和合规性报告提供了清晰、结构化的记录。
6. 环境变量与高级调优
clawo11y的Agent和Server都提供了环境变量用于调优,以适应不同的部署规模和网络条件。
6.1 Agent端关键调优参数
| 变量名 | 默认值 | 描述与调优建议 |
|---|---|---|
O11Y_SERVER_URL | http://127.0.0.1:8000 | 必须修改。指向中心服务器的完整URL(包括http://或https://)。 |
O11Y_OTLP_PROXY_ADDR | 127.0.0.1:4318 | Agent上OTLP接收器的监听地址。如果插件运行在容器或不同网络命名空间,可能需要改为0.0.0.0:4318。 |
O11Y_REQUEST_CONCURRENCY | 3 | Agent向Server发送数据的最大并发HTTP请求数。如果Agent节点数据量巨大,可以适当调高(如10)以提升吞吐。 |
O11Y_CLIENT_TIMEOUT_SEC | 10 | HTTP请求超时时间。在网络不稳定或Server压力大时,可以适当增加。 |
O11Y_OTLP_PROXY_QUEUE_SIZE | 5000 | OTLP数据转发队列的容量。如果出现数据丢失,可能是队列满了,可以增大此值。但需注意内存消耗。 |
OPENCLAW_BASE_DIR | ~/.openclaw | OpenClaw的根目录路径。如果OpenClaw数据存放在自定义位置,必须修改此变量。 |
6.2 Server端关键调优参数
| 变量名 | 默认值 | 描述与调优建议 |
|---|---|---|
O11Y_SERVER_ADDR | 0.0.0.0:8000 | Server的监听地址。生产环境如果前面有负载均衡或反向代理,保持默认即可。 |
O11Y_DB_URL | sqlite:///./o11y_server.db | 数据库连接字符串。默认使用SQLite文件。对于生产环境,如果数据量大或要求高可用,强烈建议更换为PostgreSQL。例如:postgres://user:pass@host:5432/o11ydb。 |
O11Y_DATA_RETENTION_DAYS | 7 | 数据保留天数。后台清理任务会根据此设置删除旧数据。根据你的存储容量和审计需求调整。 |
生产环境建议:
- 数据库:SQLite适用于轻量级或Demo。对于任何严肃的生产部署,请将
O11Y_DB_URL指向一个PostgreSQL实例。这能获得更好的并发性能和可靠性。- 存储与备份:定期备份数据库。如果使用SQLite,备份整个
.db文件;如果使用PostgreSQL,使用其自身的备份机制。- 高可用:目前Server是单点。对于关键业务,可以考虑将其部署在Kubernetes等容器编排平台,并配置多个副本和持久化存储。
7. 常见问题排查与实战技巧
在实际部署和使用中,你可能会遇到一些问题。以下是一些常见问题的排查思路和解决技巧。
7.1 数据类问题
问题:Web界面一片空白,或看不到任何数据。
- 排查步骤:
- 检查Server日志:查看
clawo11y-server的日志输出,确认它已启动且无报错。 - 检查Agent日志:查看
clawo11y-agent的日志,确认它已连接至Server (Connected to server at ...),并且正在转发数据 (Forwarding events...)。 - 检查插件日志:查看OpenClaw网关日志,确认
openclaw-otel-plugin已加载,并且没有连接endpoint失败的错误。 - 检查网络连通性:在Agent机器上,使用
curl http://<server-ip>:8000/health测试是否能访问Server。在OpenClaw机器上,使用curl http://localhost:4318/v1/traces测试插件是否能访问本地Agent的OTLP端点。 - 检查OpenClaw数据:确认Agent配置的
OPENCLAW_BASE_DIR路径下确实有正在运行的OpenClaw产生的日志和数据文件。
- 检查Server日志:查看
问题:成本面板显示为0,但Trace里有LLM调用。
- 排查步骤:
- 确认插件已启用且配置正确:这是最常见的原因。
- 检查模型单价配置:在
openclaw.json的插件配置中,核对pricing字段是否包含了你使用的模型,且价格单位正确(通常是每百万tokens的价格)。 - 检查Trace详情:在Trace视图中,点击一个LLM调用的Span,查看其属性(Attributes)。里面应该有
llm.usage.prompt_tokens和llm.usage.completion_tokens字段。如果这些字段缺失,说明OpenClaw运行时没有收到或没有传递usage信息。这可能与LLM提供商或具体的OpenClaw配置有关。 - 检查插件定价逻辑:有些模型定价配置可能需要
input和output键,而不是prompt和completion。请参考插件文档中的定价配置示例。
7.2 性能与稳定性问题
问题:Agent或Server进程内存/CPU占用过高。
- 调优建议:
- 调整数据粒度:在插件配置中,增加
metric_interval_ms(如从30000改为60000),降低指标发送频率。 - 调整队列大小:如果Agent内存吃紧,可以适当降低
O11Y_OTLP_PROXY_QUEUE_SIZE(如从5000改为1000),但需接受极端峰值下可能的数据丢失风险。 - 缩短数据保留期:如果数据增长过快,降低
O11Y_DATA_RETENTION_DAYS(如从7改为3),让系统自动清理更早的数据。 - 升级数据库:如果数据量很大,将SQLite切换到PostgreSQL通常会带来显著的性能提升和更好的内存管理。
- 调整数据粒度:在插件配置中,增加
问题:数据延迟高,Web界面看到的数据不是实时的。
- 排查步骤:
- 检查Agent到Server的网络延迟。
- 检查Server的负载:可能是Server正在处理大量数据聚合查询,导致API响应变慢。可以观察Server的CPU和内存使用情况。
- 前端轮询间隔:Web前端默认以一定间隔(如5秒)轮询数据。这个间隔是固定的,不是实时推送(尽管有WebSocket用于部分实时日志)。
7.3 部署与配置技巧
技巧:在多节点环境中批量部署Agent。对于拥有数十上百个AI工作节点的集群,手动部署Agent不可行。建议:
- 将
clawo11y-agent二进制文件、systemd服务文件(o11y-agent.service)和一份预配置的环境变量文件打包。 - 使用Ansible、SaltStack等配置管理工具,或通过集群镜像,将包分发到所有节点。
- 在服务文件或启动脚本中,通过环境变量
O11Y_SERVER_URL指定中心服务器的地址。这个地址最好是一个内部负载均衡器或DNS域名,方便后续Server端扩容或迁移。 - 确保每个节点上的
OPENCLAW_BASE_DIR路径正确,且Agent进程有权限读取该目录。
技巧:自定义风险分类规则。插件内置了高风险工具的分类规则,但你可能有自己的安全策略。目前,规则定义在插件代码中。如果你需要修改,可以:
- 克隆
openclaw-otel-plugin目录。 - 在源码中查找风险分类的逻辑(通常是一个工具名到风险类别的映射函数)。
- 修改后,重新构建插件 (
npm run build),并在你的OpenClaw环境中重新安装此自定义版本。
技巧:集成到现有监控体系。clawo11y的Server提供了HTTP API(可查看其源码或文档了解端点),你可以从中提取聚合后的指标(如总成本、错误率),并通过Prometheus exporter或自定义脚本,将这些业务指标推送到你已有的监控系统(如Prometheus + Grafana),实现统一监控。
经过一段时间的实际使用,我的体会是,clawo11y的价值在于它成功地将“可观测性”这个在传统软件工程中成熟的概念,无缝地引入了AI Agent的开发与运维流程。它不再让你盲目地运行Agent,而是提供了成本、性能、可靠性、安全四个维度的“仪表盘”。尤其是在进行复杂的多步骤AI工作流调试和成本优化时,深度追踪视图和成本火焰图几乎是不可替代的工具。最后一个小建议是,在团队中推广使用时,可以先从“成本面板”入手,让成员直观地看到不同实验、不同模型的花销,这往往能立刻引起大家对效率和优化的重视。
