OpenClaw-Observability：基于 DuckDB 构建 OpenClaw 的全链路可观测体系

如果你也曾盯着 OpenClaw 回复的一句Done不知道它到底做了什么——你并不孤单我们也曾经历过。于是我们基于DuckDB为 OpenClaw 构建了一套可观测插件把原本不可见的 Agent 执行过程结构化记录下来让每一次对话从黑盒运行变成链路透明。故事从一次真实的排障经历说起。一、起源从一个只有“Done”的回复说起故事发生在我们部门内部的一个自动化场景中。我们基于 OpenClaw 搭建了一个 AI Agent用于处理一些流程相对固定的代码修复任务。按照预期逻辑当用户在群里 机器人 并丢出一个需求管理平台链接时Agent 应该自动解析需求内容、在对应代码仓库中完成修复并提merge request。然而在一次实际运行中尴尬的一幕出现了看到这个回复时开发者的第一反应一定是疑惑它真的完成任务了吗还是中间某一步报错了只是被 Prompt 掩盖掉了又或者它根本没调用工具只是看着链接“脑补”了一次回答问题并不在于这句 Done 本身而在于我们无法知道这句 Done 背后到底发生了什么。而这正是很多 AI Agent 系统最真实的困境表面上只是一个聊天框背后却可能经历了多轮推理、Prompt 渲染、工具调用、子任务分发、上下文裁剪与流式生成。传统日志面对这种链路时很快就会失效。你会看到大量零散信息很长的 System Prompt层层嵌套的 JSON模型中间输出HTTP 请求上下文各种工具调用记录这些信息不是没有而是太碎、太散、太难关联。最终大家只能回到最原始的排障方式盯日志、猜原因、改 Prompt、再试一次。于是我们决定换个方向不再继续堆文本日志而是为 OpenClaw 做一套真正面向 Agent 的可观测插件。二、这个插件为了解决什么问题我们将这个插件的目标浓缩为三个层次看得见、说得清、改得动。1. 看得见把隐藏动作全部还原出来在一次看似简单的对话背后系统实际可能做了这些事用户输入 → 意图理解 → Prompt 组装 → 模型推理 → 工具调用 → 外部结果返回 → 二次生成 → 最终输出如果这些过程不能被完整还原那么所有排障都只能停留在猜测层面。2. 说得清从体感定位转向证据定论当结果不符合预期时我们真正想回答的是是模型选错了工具还是工具返回格式异常是 Prompt 约束触发了静默策略还是上下文截断导致关键信息丢失这些问题只有在链路可追踪的前提下才可能回答。3. 改得动让优化建立在数据上AI 系统的迭代不能只靠“感觉这一版更好了”。只有把调用频率、失败率、延迟、Token 消耗、异常模式等数据沉淀下来优化才有依据。这也是为什么我们后来没有把它做成一个日志搬运工具而是把它做成了一套完整的观测系统。三、技术架构我们怎么把 Agent 的思维链变成瀑布图整套插件可以拆成四层采集层 → 建模层 → 存储层 → 展示分析层1. 采集层在关键节点把数据接住我们基于 OpenClaw 的 Hook 机制在 Agent 生命周期中的几个关键位置做拦截会话开始 / 消息进入LLM 推理开始 / 结束工具调用前 / 后流式输出过程中的 thinking / assistant 事件Run / 子任务切换节点这样做的目的是把原本散落在不同模块里的事件统一拉回一条主链路上。2. 建模层把离散事件组织成可追踪的 Trace要让前端看到的是一张清晰的瀑布图底层必须先有统一的数据模型。我们抽象了几个核心字段TraceID / ParentID表示父子调用关系用来组织树状链路Observation Type区分 llm、tool、stream 等不同事件类型Run Lineage关联主任务和并行子任务避免链路串线Snapshot记录 input_json / output_json支持事后复盘这部分其实非常关键。因为真正让可观测成立的不是“采到了数据”而是这些数据最后能不能被组织成可理解的执行过程。3. 存储层异步写入不能反过来拖慢主链路可观测系统有个很现实的问题如果为了观测把主链路拖慢了那插件本身就成了问题。所以我们把记录链路设计成了异步、非阻塞模式采集事件先进入内存缓冲区通过串行队列批量 flush 到数据库主链路只做轻量入队不等待磁盘 I/O除此之外我们还做了一个细节处理流式输出阶段有些时长信息并不天然完整因此后端会按下一节点时间点回填 thinking 时长保证前端时间轴稳定可读。4. 展示分析层把链路从“能查”变成“能看懂”在展示层我们主要提供三类视图Trace 视图按时间顺序展示一次执行链路中的 LLM、工具、子任务与输出过程分析视图聚合 Token、会话数、耗时分布、失败率等指标安全视图展示规则扫描与高危行为链告警这样开发者看到的就不再是一堆散乱日志而是一条完整、可解释、可下钻的执行时间线。四、回到那个“Done”问题是怎么被 10 秒定位的有了这套插件之后我们重新回看那次只回复“Done”的会话。这一次在 Trace 视图里我们能清楚看到Agent 识别出了这是一个需求平台链接它提取了项目 ID 和需求 ID它根据内部规则判断群聊里没有明确提问时不应过度打扰同时它意识到自己无法访问企业内网系统最终它选择了简短回复而不是继续执行后续动作这个结论非常关键因为它说明这不是系统坏了也不是模型没理解而是 Agent 在既有规则约束下做出的决策。如果没有这条结构化链路团队大概率会继续在 Prompt 上盲改甚至怀疑模型能力异常。但有了 Trace问题在十秒内就能定性。这也是这套系统最直接的价值不是让我们看到更多信息而是更快地看到真正有效的信息。五、存储引擎选型在本地化方案中最初我们考虑过 SQLite但面对海量的结构化审计数据尤其涉及到聚合分析时SQLite 的表现不尽如人意。真实审计负载下的性能对比我们模拟了一个中等规模的审计负载同 Schema、同查询逻辑在 50 万条 observations 记录下进行了对比测试。为什么DuckDB在 AI 场景下这么强分析型架构DuckDB 是列式存储而可观测场景最常见的需求就是“对过去 7 天的 Token 消耗做求和”或者“统计不同模型的分布”。这类查询在列存引擎下具有天然优势。JSON 解析能力AI 的输入输出往往是嵌套的 JSON。DuckDB 提供的json_extract_string()等函数可以直接在查询时对 TEXT 字段进行高效解析减少了业务层的处理负担。工程上零阻力它和 SQLite 一样就是一个单文件数据库不需要安装任何 Server。这种单文件可移植性意味着团队可以随时把审计文件拉到本地用 CLI 检查或者导出成 Parquet 接入下游的大数据体系。六、落地实战如何让插件开箱即用我们在设计上尽量把接入门槛降到最低。只需要一条命令完成安装openclaw plugins install openclaw-observability安装完成并重启 Gateway 后插件会自动启动本地自动创建并加载 DuckDB 数据库Trace 与 Metrics 开始异步采集同时系统会默认提供可视化界面http://localhost:18789/plugins/observability打开即可查看完整执行链路与分析数据。七、从本地到上云能力边界的全面扩展我们给插件支持了接入云上RDS DuckDB的能力为企业级客户拓展了数据的稳定性。相比本地单文件存储云上部署的优势如下稳定性备份、容灾、高可用能力更完整多租户管理在统一平台下实现租户级隔离、权限控制与资源配额满足不同业务线并行接入的需求。弹性性能弹性扩展面对流量波动查询峰值时系统可以更稳定地提供服务。在此基础上我们还能进一步建设统一的数据治理与审计体系让监控、分析、归档、合规形成闭环为后续跨团队协作和企业级落地提供长期支撑。我们同时支持本地数据迁移到云上让整个本地适用到云上投入生产的流程足够顺滑。此外RDSClaw 直接在控制台上集成了可观测插件让拥有可观测能力的claw 开箱即用。八、结语可观测性不是锦上添花而是基础能力很多 AI 应用在早期都更关注能不能先跑起来。但一旦进入真实业务环境系统是否可靠、能不能排障、出了问题能不能解释就会比能跑本身更重要。模型会幻觉工具会失败上下文会被污染规则会互相冲突。如果没有可观测能力系统越复杂维护成本就越高最后大家只能在猜测中迭代。而要让可观测真正落地除了采集与建模能力之外还需要一个能够承载分析与查询的底层引擎。在我们的实践中DuckDB 让这些观测数据真正“可分析”而不只是被记录。我们给 OpenClaw 做这套插件目标其实很朴素让 AI Agent 不再是黑盒。先让执行过程看得见后面的一切优化、治理和扩展才有基础。相关链接RDSclaw试用链接https://yaochi-buy.aliyun.com/rds-ai-deploy?request%7B%22payType%22:%22Postpaid%22,%22rds_agent_class%22:%22mysql.x2.large.9cm%22%7DDuckDB分析实例https://help.aliyun.com/zh/rds/apsaradb-rds-for-mysql/duckdb-analysis-instance/