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-serverclawo11y-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_URLhttp://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_URLhttp://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”模式查看火焰图。这个视图将一次运行中每个SpanLLM调用、工具执行的成本或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_URLhttp://127.0.0.1:8000必须修改。指向中心服务器的完整URL包括http://或https://。O11Y_OTLP_PROXY_ADDR127.0.0.1:4318Agent上OTLP接收器的监听地址。如果插件运行在容器或不同网络命名空间可能需要改为0.0.0.0:4318。O11Y_REQUEST_CONCURRENCY3Agent向Server发送数据的最大并发HTTP请求数。如果Agent节点数据量巨大可以适当调高如10以提升吞吐。O11Y_CLIENT_TIMEOUT_SEC10HTTP请求超时时间。在网络不稳定或Server压力大时可以适当增加。O11Y_OTLP_PROXY_QUEUE_SIZE5000OTLP数据转发队列的容量。如果出现数据丢失可能是队列满了可以增大此值。但需注意内存消耗。OPENCLAW_BASE_DIR~/.openclawOpenClaw的根目录路径。如果OpenClaw数据存放在自定义位置必须修改此变量。6.2 Server端关键调优参数变量名默认值描述与调优建议O11Y_SERVER_ADDR0.0.0.0:8000Server的监听地址。生产环境如果前面有负载均衡或反向代理保持默认即可。O11Y_DB_URLsqlite:///./o11y_server.db数据库连接字符串。默认使用SQLite文件。对于生产环境如果数据量大或要求高可用强烈建议更换为PostgreSQL。例如postgres://user:passhost:5432/o11ydb。O11Y_DATA_RETENTION_DAYS7数据保留天数。后台清理任务会根据此设置删除旧数据。根据你的存储容量和审计需求调整。生产环境建议数据库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产生的日志和数据文件。问题成本面板显示为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工作流调试和成本优化时深度追踪视图和成本火焰图几乎是不可替代的工具。最后一个小建议是在团队中推广使用时可以先从“成本面板”入手让成员直观地看到不同实验、不同模型的花销这往往能立刻引起大家对效率和优化的重视。