1. 项目概述为AI Agent打造的可观测性平台如果你正在使用OpenClaw这类AI Agent框架并且对“我的Agent到底在干什么”、“它花了多少钱”、“哪个工具调用总是失败”这些问题感到头疼那么你找对地方了。今天要聊的danl5/clawo11yOpenClaw O11y就是一个专门为解决这些问题而生的开源可观测性堆栈。它不是另一个通用的APM应用性能监控工具而是从底层设计就瞄准了AI Agent工作流的独特痛点。简单来说OpenClaw O11y是一个由Go后端和React前端组成的监控平台。它的核心目标不是展示一堆冰冷的原始遥测数据而是将这些数据转化为对AI Agent开发者、运维和财务管理者真正有意义的业务视图。想象一下你不再需要从海量的日志里手动拼凑一次Agent会话的全貌而是能直接看到一个清晰的仪表盘告诉你“这次会话消耗了15美元其中80%花在了Claude-3-Opus模型上有一个文件写入工具调用失败了3次并且会话后期出现了上下文膨胀的迹象。”这就是O11y想要提供的体验。这个项目适合所有在OpenClaw生态中进行开发的团队无论是个人开发者调试自己的智能体还是企业团队需要管理一个由多个Agent组成的“数字劳动力”监控其成本、性能和安全性。它通过两种方式收集数据一是通过一个轻量级的Go Agent被动监听OpenClaw的本地运行状态和日志文件二是通过一个可选的OpenTelemetry插件深入到Agent运行时内部主动发射结构化的追踪、指标和日志数据。这两种方式互为补充让你既能获得宏观的运行概览又能进行微观的深度调试。2. 核心架构与设计思路拆解要理解O11y的价值得先拆开看看它的四层架构是怎么工作的。这不仅仅是技术组件的堆砌每一层都对应着解决AI Agent可观测性中的一个具体挑战。2.1 数据采集的双重策略广度与深度AI Agent的运行是事件驱动的一次会话可能涉及多次LLM调用、工具执行甚至子Agent的嵌套。传统的日志监控在这里会显得力不从心因为关联性差、结构松散。O11y的设计聪明地采用了双重采集策略运行时事件采集Go Agent这是一个“外部观察者”。它部署在运行OpenClaw的工作节点上持续监控~/.openclaw目录下的状态文件、日志流以及系统指标。这种方式是非侵入式的你不需要修改Agent代码就能获得基础的运行视图包括会话列表、简单的令牌统计和实时日志。它的优势在于部署简单、通用性强能提供一个快速的、宏观的健康状态俯瞰。OpenTelemetry原生采集OTel插件这是“内部探针”。你需要将openclaw-otel-plugin安装到OpenClaw运行时中。一旦启用这个插件会拦截OpenClaw的核心运行时事件如llm_input、after_tool_call并将其转化为符合OpenTelemetry标准的Traces追踪、Metrics指标和Logs日志。这种方式能提供深度关联性。例如一次失败的LLM调用、它触发的重试、以及后续执行的一个高风险Shell命令所有这些都会被记录在同一个Trace追踪树下形成一个完整的因果关系链。设计考量为什么选择OpenTelemetryOTel已经成为云原生可观测性的事实标准。采用OTel意味着O11y产生的数据可以无缝接入现有的可观测性生态如Jaeger、Prometheus未来也更容易扩展支持其他Agent框架。同时OTel强大的上下文传播Context Propagation能力正是理清AI Agent复杂调用链所必需的。2.2 数据处理与流转管道数据从产生到呈现在仪表盘上经历了一个清晰的管道[数据源] - [采集端] - [传输/聚合] - [存储/查询] - [可视化] OpenClaw OTel插件 本地代理 中心服务器 React前端 运行时事件 - 结构化OTel数据 - OTLP代理 - HTTP转发 - SQLite 聚合 - 业务视图这个流程的关键在于中心化和异步化。工作节点上的Go Agent将收集到的数据无论是解析的日志还是OTel插件发来的OTLP数据异步转发到中心的O11y Server。这样做有几个好处首先工作节点的资源开销极小不影响主Agent任务的性能其次所有数据在中心服务器统一处理、聚合和存储便于进行跨会话、跨节点的关联分析最后前端React应用只与中心服务器交互获取的是已经过初步聚合和丰富的数据响应更快。中心服务器的角色它不仅仅是个数据库。它内置了聚合引擎能够实时计算诸如“今日各模型成本占比”、“工具调用平均延迟P95”等指标。这些计算如果放在前端或每次查询时进行会对性能造成巨大压力。服务器预聚合的策略使得仪表盘能够做到近实时的数据刷新。2.3 存储选型SQLite的轻量之道你可能会惊讶一个可观测性平台的核心存储用的是SQLite而不是时序数据库如InfluxDB或Prometheus。这是一个非常务实的选择。场景契合O11y默认的数据保留期是7天可配置这瞄准的是近期的问题诊断和成本分析而非长达数月的趋势预测。在这个时间窗口和典型的数据量下SQLite的性能完全足够。简化部署使用SQLite意味着整个O11y堆栈没有任何外部数据库依赖。无论是用Docker Compose一键启动还是进行裸金属部署都极大地降低了复杂度。用户只需要关心一个二进制文件和一个数据库文件。功能足够SQLite支持JSON字段、窗口函数等足以实现O11y所需的复杂查询和聚合。对于更长期的归档需求项目设计上也预留了接口未来可以通过配置将数据转发到更专业的存储中。这个选择体现了项目“开箱即用、易于部署”的核心设计哲学优先考虑开发者和运维者的体验而不是追求技术栈的“高大上”。3. 核心功能模块深度解析O11y的仪表盘不是功能的简单罗列而是围绕三个核心角色财务、开发者、安全员的需求精心组织的。我们来逐一拆解这些视图背后的逻辑。3.1 FinOps for AI让AI开销一目了然这是O11y最具特色的部分。AI模型的调用成本高昂且不透明特别是当使用多种模型、多个提供商时。O11y的FinOps仪表盘致力于解决这个问题。成本仪表盘它不仅仅加总了一个数字。关键在于成本归因。视图会按提供商如OpenAI、Anthropic、按模型如gpt-4-turbo, claude-3-sonnet进行分层下钻。你会看到“过去24小时Claude-3-Opus模型消耗了总成本的60%”这直接指向了优化目标是否可以用更便宜的模型替代某些场景下的OpusTop Expensive Runs最昂贵会话排行这个功能直接回答“钱花在哪了”。它从所有Trace的根节点即一次完整的命令或会话中根据其总成本进行排序。点击任何一个高成本会话可以直接跳转到其详细的Trace视图让你能复盘整个昂贵的决策过程是哪个环节的LLM调用特别贵还是陷入了循环调用成本/令牌火焰图这是一个强大的诊断工具。在Trace详情页你可以将视图模式从默认的“时间”切换到“成本”或“令牌”。火焰图的宽度不再代表耗时而是代表该Span跨度消耗的成本或令牌数。一眼就能定位到整个调用树中哪个具体的LLM调用或工具执行是“资源吞噬者”。上下文膨胀预警这是针对LLM会话的一个经典问题而设计的。Agent有时会陷入循环不断将历史对话内容作为上下文喂给模型导致令牌数爆炸式增长成本激增。O11y会分析会话中Prompt Token的增长曲线自动标记出那些增长异常、疑似陷入“上下文膨胀”的会话提醒你及时干预。3.2 Agent调试从黑盒到白盒当Agent行为不符合预期时传统的调试方式是看日志这如同大海捞针。O11y的调试视图提供了多维度的透视。深度追踪视图这是OTel插件能力的集中体现。一个完整的Trace树展示了从用户输入开始到最终Agent响应的全过程。每个Span都包含了丰富的信息LLM Span使用了什么模型、提供商、请求参数、返回结果、消耗的令牌数、成本、以及是否有错误。Tool Span调用了什么工具、输入参数、输出结果、执行耗时、错误信息。Subagent Span子Agent的启动、输入输出和结束。 这种视图让你能像调试普通程序一样设置“断点”查看某个Span的详情理解控制流和数据流。工具可靠性矩阵这是一个聚合视图。它以表格形式列出所有被调用过的工具并显示关键指标调用次数、错误次数、错误率、平均延迟、P95延迟、最大延迟。对于运维来说这个视图价值连城。你可以立刻发现哪个工具是故障热点高错误率哪个工具是性能瓶颈高P95延迟。例如你可能会发现一个调用外部API的工具错误率高达30%这提示你需要检查该服务的稳定性或增加重试机制。可观测性健康度这个功能有点“元可观测”的味道它监控可观测性系统自身的数据质量。例如根节点重建当OTel插件检测到一个Trace缺少根节点时它会尝试重建一个逻辑根节点确保Trace树的完整性。这个事件会被记录并展示提示你可能存在数据丢失。孤儿事件指那些无法关联到任何已知Trace的事件这通常意味着数据采集或上下文传播出现了问题。空闲超时关闭长时间没有活动的Trace会被自动关闭释放资源。 关注这些指标能确保你看到的监控数据本身是可信的。3.3 安全与合规为AI操作加上审计日志AI Agent被赋予执行能力的同时也带来了安全风险。O11y的安全时间线功能就是对高风险操作进行结构化审计。高风险操作分类插件内置了一个分类器能将工具调用按风险等级归类Shell操作执行任意命令风险最高。代码执行在沙箱或环境中运行代码。文件系统变更写入、删除、修改文件。网络访问发起外部HTTP请求。安全时间线这是一个按时间排序的列表展示了所有被标记为高风险的操作。每条记录包括风险类别、判定理由、参数预览例如执行的命令前50个字符、操作耗时和错误状态。这对于合规审查和事故复盘至关重要。你可以快速回答“上周有没有Agent执行过rm -rf命令”。实操心得安全时间线的有效性高度依赖于工具命名的规范性。建议在开发自定义工具时采用清晰、表明意图的名称如execute_safe_shell_script而非run_cmd并在工具描述中说明其用途这样能帮助O11y插件更准确地进行风险分类。4. 部署模式详解与实操要点O11y提供了灵活的部署方式从快速体验到生产级分离部署。选择哪种方式取决于你的使用场景和基础设施。4.1 快速体验模式Docker Compose一键启动这是上手最快的方式适合个人开发者评估或内部演示。git clone https://github.com/danl5/clawo11y.git cd clawo11y docker compose up -d执行上述命令后Docker Compose会启动两个服务clawo11y-server: 中心服务器和Web前端默认监听8000端口。clawo11y-agent: 工作节点代理它会将宿主机的~/.openclaw目录挂载到容器内。关键注意事项目录映射docker-compose.yml中默认将~/.openclaw映射到了Agent容器内。如果你的OpenClaw数据存放在其他路径例如/opt/openclaw必须修改compose文件中的卷映射配置否则Agent将读取不到任何数据。仅限基础视图此模式仅部署了Server和Agent没有安装OTel插件。因此你只能看到“运行时事件”相关的视图概览、令牌、会话等而无法看到Trace、成本分析等高级OTel视图。仪表盘上对应模块会显示为不可用或没有数据。网络访问确保宿主机的8000端口未被占用。访问http://localhost:8000即可打开Web界面。4.2 生产级部署裸金属分离部署对于正式环境建议将Server和Agent分离部署以获得更好的可扩展性和安全性。4.2.1 中心服务器部署首先在一个独立的服务器或容器上部署中心服务。# 1. 克隆代码并构建 git clone https://github.com/danl5/clawo11y.git cd clawo11y # 2. 构建前端资源React和Go服务器二进制文件 # 确保系统已安装 Go 1.21 和 Node.js 18 make build-web build-server # 构建产物会输出到 ./bin/ 目录 ls -lh ./bin/ # clawo11y-server (服务器主程序) # web/ (前端静态资源文件夹) # 3. 准备运行目录和数据目录 mkdir -p /opt/clawo11y/{bin,data,logs} cp ./bin/clawo11y-server /opt/clawo11y/bin/ cp -r ./bin/web /opt/clawo11y/ # 复制前端资源 # 4. 启动服务器 cd /opt/clawo11y # 可以通过环境变量覆盖默认配置例如更换监听端口或数据库路径 O11Y_SERVER_ADDR0.0.0.0:8080 O11Y_DB_URLsqlite:///./data/o11y.db ./bin/clawo11y-server生产环境建议使用Systemd托管使用项目提供的scripts/o11y-server.service示例文件将其复制到/etc/systemd/system/并修改其中的ExecStart、WorkingDirectory、User等参数以适应你的环境。使用Systemd可以保证服务开机自启、崩溃重启并方便地管理日志。配置反向代理不建议直接将O11y Server的端口暴露给公网。应使用Nginx或Caddy等反向代理配置SSL/TLS加密并可以增加基础认证等安全层。数据持久化确保O11Y_DB_URL指向的SQLite文件所在目录如/opt/clawo11y/data有持久化存储并且定期备份。4.2.2 工作节点Agent部署在每一个运行OpenClaw Agent的服务器上都需要部署clawo11y-agent。# 在工作节点上操作 # 1. 下载或构建Agent二进制文件可以从中心服务器scp或在本机构建 # 假设从构建机复制 scp userserver-host:/path/to/clawo11y/bin/clawo11y-agent /usr/local/bin/ # 2. 创建配置文件或直接通过环境变量启动 # 最重要的环境变量是 O11Y_SERVER_URL指向中心服务器的地址 export O11Y_SERVER_URLhttp://your-server-host:8080 export OPENCLAW_BASE_DIR/home/user/.openclaw # 如果你的OpenClaw路径不同 # 3. 启动Agent /usr/local/bin/clawo11y-agentAgent配置详解O11Y_OTLP_PROXY_ADDRAgent会在本地启动一个OTLP接收代理默认在127.0.0.1:4318。这个地址必须与后面安装的OTel插件配置中的endpoint一致。O11Y_REQUEST_CONCURRENCY和O11Y_CLIENT_TIMEOUT_SEC如果Agent需要向中心服务器转发大量数据可以适当调高并发数。如果网络不稳定可以增加超时和重试参数O11Y_CLIENT_RETRY_COUNT,O11Y_CLIENT_RETRY_WAIT_MS。GATEWAY_LOG_DIR如果OpenClaw的日志目录不是默认的OPENCLAW_BASE_DIR/logs可以通过此变量指定。同样建议使用Systemd托管Agent进程参考scripts/o11y-agent.service文件。4.3 解锁完整能力安装OpenClaw OTel插件只有安装了OTel插件才能解锁前面提到的Trace、成本、高级指标和安全视图。这是从“监控”升级到“深度可观测性”的关键一步。# 在OpenClaw的工作节点上操作 # 1. 进入插件目录并构建假设clawo11y项目已克隆 cd /path/to/clawo11y/openclaw-otel-plugin npm install npm run build # 构建后插件代码会在 dist 目录 # 2. 在OpenClaw中安装插件 # 注意openclaw命令需要在OpenClaw环境内执行 openclaw plugins install ./openclaw-otel-plugin # 或者使用绝对路径 # openclaw plugins install /path/to/clawo11y/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-4-turbo-preview: { prompt: 10.0, completion: 30.0 }, claude-3-sonnet: { prompt: 3.0, completion: 15.0 }, claude-3-haiku: { prompt: 0.25, completion: 1.25 } } } } } } }配置项精讲endpoint必须与Agent环境变量O11Y_OTLP_PROXY_ADDR默认http://localhost:4318匹配。如果Agent代理监听在其他IP或端口此处需相应修改。pricing这是成本计算的核心。插件需要知道每个模型的每百万令牌通常单位是美元的价格。你需要根据你所使用的模型提供商OpenAI、Anthropic、Azure等的官方定价手动配置这个映射表。项目示例中给出了一些模型但你必须补充完整你实际使用的所有模型。价格配置不正确成本仪表盘的数据就毫无意义。root_idle_timeout_ms如果一个Trace的根节点在5分钟300000毫秒内没有收到任何新的Span插件会认为该会话已结束并关闭导出该Trace。对于长时间运行的交互式Agent可能需要调大这个值。配置完成后重启OpenClaw Gateway以使插件生效openclaw gateway restart现在启动你的OpenClaw Agent执行任务然后刷新O11y的Web界面。你应该能看到“Trace”、“Cost”、“Metrics”、“Security”等选项卡下开始有数据涌现。5. 常见问题排查与实战技巧在实际部署和使用过程中你可能会遇到一些典型问题。这里记录了我踩过的一些坑和解决方法。5.1 数据问题排查清单现象可能原因排查步骤Web界面打开但所有页面无数据1. Agent未运行或未连接。2. OpenClaw基础目录路径错误。3. 中心服务器未启动。1. 检查工作节点clawo11y-agent进程状态和日志通常有-log参数或Systemd Journal。2. 确认Agent的OPENCLAW_BASE_DIR环境变量指向正确的路径且该路径下有logs等目录。3. 访问http://server:port/health检查中心服务器健康状态。只有“Overview”、“Sessions”等基础视图有数据Trace/Cost视图为空OTel插件未安装或未正确配置。1. 执行openclaw plugins list确认插件已安装且enabled为true。2. 检查插件配置endpoint是否与Agent的O11Y_OTLP_PROXY_ADDR完全一致包括协议、主机、端口。3. 查看OpenClaw Gateway日志确认插件加载无报错。Trace视图有数据但成本始终为0或不准1. 模型定价表未配置或配置错误。2. LLM提供商返回的usage字段为空。1. 仔细核对插件配置中的pricing字段确保模型名称与OpenClaw实际调用的模型标识符完全匹配区分大小写。2. 在Trace详情中展开一个LLM Span查看其原始数据确认是否有usage: {prompt_tokens: ..., completion_tokens: ...}字段。如果没有说明该LLM调用未返回用量信息成本无法计算。安全时间线未显示任何高风险操作1. 未执行任何被归类为高风险的工具。2. 工具名称未被插件识别。1. 确认你的Agent确实执行了Shell、文件写入等操作。2. 插件内置了一个风险工具名称模式匹配列表。如果你的自定义工具名称很特殊可能未被识别。可以尝试在工具命名中包含shell、exec、write、delete、network等关键词。数据延迟很高1. Agent到Server网络不佳。2. 队列积压。1. 检查Agent日志看是否有转发失败和重试的记录。调整O11Y_CLIENT_TIMEOUT_SEC和重试参数。2. Agent有内存队列O11Y_OTLP_PROXY_QUEUE_SIZE如果队列持续满可能是Server处理不过来或网络中断。需要检查Server性能。5.2 性能与调优建议Agent资源占用Go Agent非常轻量通常内存占用在50MB以下CPU可忽略不计。主要开销在于日志文件的实时尾读tail和网络转发。Server存储增长默认7天保留期下一个中等活跃度的单节点OpenClaw环境SQLite数据库每天增长约几十到几百MB。如果数据量巨大可以考虑缩短O11Y_DATA_RETENTION_DAYS。定期手动清理或归档数据库文件。未来修改Server代码支持将数据导出到对象存储或更专业的时序数据库。高并发场景如果同时有数十个Agent向一个Server发送数据可能需要调高Server所在机器的资源并考虑使用负载均衡器将Agent分流到多个Server实例当前版本Server是无状态的但共享同一个SQLite文件会有锁冲突需要改造为支持外部数据库如PostgreSQL。5.3 插件开发与扩展O11y的OTel插件本身也是一个很好的参考展示了如何为OpenClaw框架开发可观测性插件。如果你有自定义的指标或日志想要发送可以基于此插件进行扩展。插件的主要工作流程在openclaw-otel-plugin/src目录下事件监听通过OpenClaw的插件API订阅各类运行时事件。数据转换将OpenClaw原生事件如一个工具调用结果转换为OTel的Span、Metric或Log记录。上下文管理维护和传播Trace上下文确保一次会话中的所有操作都能关联到同一个TraceId。数据导出通过OTLP协议将数据发送到配置的endpoint。例如如果你想为某个特定的内部工具添加自定义指标如缓存命中率可以在插件中监听该工具的事件然后使用OpenTelemetry Metrics API创建并记录一个Counter或Gauge。6. 总结与未来展望OpenClaw O11y从一个简单的日志查看器演进为一个面向AI Agent工作负载的综合性可观测性平台这个方向非常精准。它抓住了AI应用运维的几个核心痛点成本不可控、调试困难、安全风险。通过将OpenTelemetry标准与AI Agent领域知识相结合它提供了传统APM工具无法提供的、具有业务语义的视图。从我实际的部署和使用体验来看它的最大价值在于将碎片化的运行信息串联成了有故事线的洞察。你不必再在不同的日志文件、API账单和控制台之间切换一个平台就能告诉你关于你的AI“员工”的完整故事它的工作效率工具延迟、它的花销成本分析、它的行为是否合规安全时间线。当然作为一个开源项目它也有可以继续完善的地方。例如目前的数据存储和聚合层相对简单对于超大规模、多租户的场景可能需要架构升级告警功能目前似乎还未集成当成本超支或出现高频错误时无法主动通知与外部系统的集成如将数据推送到Slack、Teams或通用的监控平台也有待加强。但无论如何danl5/clawo11y为AI Agent的可观测性树立了一个优秀的范本。它的设计思路——即聚焦业务视图、采用开放标准、保持部署简单——值得所有从事AI应用开发和运维的团队借鉴。如果你正在严肃地使用OpenClaw花点时间部署上O11y它很可能会成为你洞察和优化AI工作流的最得力工具。