面对OpenClaw仅回复"Done"的困惑，我们基于DuckDB为其构建了可观测插件，将Agent执行过程结构化记录，实现从黑盒到链路透明的转变。
一、起源：从"Done"回复切入
在内部自动化代码修复场景中，当用户在群内@机器人并发送需求链接后，Agent本应解析需求、修复代码并提Merge Request。但实际运行时仅返回"Done"，引发核心疑问：
- 任务是否完成？
- 是否被Prompt掩盖了错误？
- 是否存在未调用工具的虚假响应？
问题本质在于无法追溯"Done"背后的执行链路。传统日志难以处理多轮推理、工具调用、子任务分发等复杂流程，导致排障依赖原始手段：盯日志、猜原因、反复测试。
因此，我们转向构建面向Agent的可观测插件，实现链路透明化。
二、核心目标：看得见·说得清·改得动
1. 看得见：还原完整执行过程
需完整捕捉"用户输入→意图理解→Prompt组装→模型推理→工具调用→结果返回→最终输出"全链路，避免排障停留在猜测层面。
2. 说得清：证据驱动的定论分析
通过链路追踪精准定位：是工具选择错误？返回格式异常？Prompt静默策略触发？还是上下文截断？
3. 改得动：数据支撑的迭代优化
沉淀调用频率、失败率、延迟、Token消耗等数据，避免依赖主观"感觉"进行系统迭代。
三、技术架构：四层链路可视化体系
采集层 → 建模层 → 存储层 → 展示分析层
1. 采集层：关键节点拦截
基于OpenClaw Hook机制，在会话开始、LLM推理、工具调用、流式输出、任务切换等环节统一采集事件，将散落数据汇入主链路。
2. 建模层：结构化Trace构建
通过核心字段组织数据：
- TraceID/ParentID：构建树状调用关系
- Observation Type：区分llm/tool/stream事件
- Run Lineage：关联主子任务
- Snapshot：记录input/output json支持复盘
3. 存储层：高性能异步写入
采用内存缓冲+批量flush机制：
- 事件先进入内存缓冲区
- 串行队列批量写入数据库
- 主链路仅做轻量入队
流式输出阶段动态回填thinking时长，保证时间轴稳定性。
4. 展示分析层：可视化洞察
提供三类视图：
- Trace视图：展示LLM、工具调用等执行时序
- 分析视图：聚合Token消耗、失败率等指标
- 安全视图：高危行为链告警
四、实战验证：10秒定位"Done"真相
Trace视图清晰显示：Agent识别需求链接后，因群聊无明确提问及无法访问内网系统，依据规则选择简短回复。该结论避免了对Prompt的盲目修改，使问题定性效率提升至10秒。
五、DuckDB的性能优势
真实负载下的性能对比
选择DuckDB的核心原因
- 列式存储：天然适配"Token求和""模型分布统计"等聚合分析
- JSON解析能力：支持json_extract_string()等高效处理嵌套数据
- 零工程成本：单文件数据库免安装，支持本地CLI检查和Parquet导出
六、开箱即用的实施路径
一键安装：
openclaw plugins install openclaw-observability重启Gateway后自动激活以下功能：
- 本地DuckDB数据库初始化
- Trace与Metrics异步采集
- 可视化界面即时可用：http://localhost:18789/plugins/observability
七、云上拓展：企业级能力升级
- 稳定性提升：完整备份、容灾、高可用机制
- 多租户管理：租户隔离、权限控制与资源配额
- 弹性性能：应对流量高峰的资源动态扩展
支持本地数据平滑迁移至云端，并通过RDSClaw控制台实现开箱即用。
八、可观测性：AI系统的基石能力
业务落地中，系统可靠性、排障效率与解释能力远比"能跑起来"更重要。模型幻觉、工具失效、上下文污染等问题必须通过可观测能力解决。我们为OpenClaw构建插件的核心目标是将AI Agent从黑盒转为透明系统——唯有看得到执行过程，才能实现可持续优化与治理。
DuckDB分析实例：https://help.aliyun.com/zh/rds/apsaradb-rds-for-mysql/duckdb-analysis-instance/