OpenClaw 四层 Langfuse 全链路追踪完整详解

一、基础前置概念1. 定位与插件载体OpenClaw 的 Langfuse 追踪基于可插拔运行时Observer 观测插槽官方插件oh-my-langfuse/openclaw-langfuse-plugin实现全生命周期自动埋点是 UpClaw「可观测性」改造板块的标准落地方案。四层追踪是自上而下、父子嵌套、逐级下钻的标准化分层模型完全对齐 Langfuse 原生Session → Trace → Span → Generation数据模型并深度绑定 OpenClaw Agent 完整生命周期、三层Tool治理、MD配置体系、rules.md安全规则。2. 四层层级定义从粗到细父子包含关系第一层Session会话层最顶层第二层Trace单轮请求主链路层第三层Span子步骤执行层工具/记忆/子代理/规则校验第四层GenerationLLM模型推理原子层最细粒度层级嵌套关系1个Session ⊇ N个Trace ⊇ N个Span ⊇ N个Generation3. 核心设计目标全局成本归因按用户、会话、模型、技能、租户拆分Token消耗与费用全链路问题定位从用户对话一键下钻到模型思考、工具参数、规则拦截记录企业审计合规自动记录rules.md拦截、工具黑白名单命中、脱敏行为Agent行为复盘完整还原ReAct循环、子代理委派、长期记忆召回全过程性能监控分层统计各阶段延迟、超时、失败率支撑调度优化。二、四层分层完整拆解每层定义、埋点钩子、存储字段、生命周期介入、业务作用第一层Session 会话层全局顶层容器1. 定义一个独立Agent完整生命周期会话对应一次用户持续对话直到会话销毁关闭聊天/超时回收全局唯一session_id关联固定用户ID、租户、Agent身份IDENTITY.md。对应生命周期钩子session_start/session_close2. 自动采集元数据基础标识sessionId、userId、tenantId、agentName、IDENTITY.md身份摘要全局配置快照加载的rules.md版本、启用插件列表、全局推理预算上限聚合指标会话总Token消耗、总耗时、总工具调用次数、总规则拦截次数标签业务场景标签、渠道标签飞书/Web/API、部署环境标签测试/生产3. 生命周期介入时机onSessionCreate会话创建创建Langfuse Session根节点写入全局MD配置快照全会话生命周期所有下层Trace/Span/Generation自动挂载该SessiononSessionClose会话销毁写入会话聚合统计标记会话结束状态正常关闭/熔断超时/违规拦截终止。4. 业务作用宏观维度统计某客户/某业务线全天总AI成本、会话平均时长完整对话回放一键拉取用户全轮交互用于客服、业务问题复盘租户隔离统计区分不同业务Agent资源消耗做成本分摊。5. 与其他模块联动绑定MEMORY.md长期记忆全局配置、HEARTBEAT.md定时心跳调度记录会话内所有记忆读写、定时任务都归属该Session。第二层Trace 单轮请求主链路层每一轮用户输入顶层链路1. 定义用户单次消息输入触发的完整一轮Agent执行闭环一轮ReAct循环一条Trace对应用户一句提问唯一traceId父节点为Session。对应钩子message_received创建Trace、after_agent_turn关闭Trace2. 采集核心内容用户原始输入文本、附件、视频/文件输入本轮生效完整System Prompt快照按优先级拼接rules→IDENTITY→SOUL→TOOLS→SKILL→USER.md顶层全局规则校验结果本轮是否触发rules.md前置拦截、拦截原因、命中规则条目本轮最终输出回答、输出脱敏记录顶层聚合指标本轮总耗时、总输入/输出Token、本轮调用工具总数、子代理创建数量。3. 生命周期介入onInput消息入站初始化Trace根节点记录用户输入执行rules.md前置风控并写入Trace元数据整轮ReAct循环所有工具、记忆、模型调用全部作为子Span挂载到当前TraceonOutput结果输出记录最终回复、脱敏操作after_agent_turn关闭Trace写入本轮汇总指标标记链路状态成功/工具失败/规则熔断/模型超时。4. 业务作用单轮请求级故障定位用户反馈回答异常直接打开对应Trace查看整轮执行流程Prompt迭代效果观测对比修改rules/SOUL.md前后同类型Trace的输出质量、Token消耗高危请求审计所有被rules.md拦截的Trace单独聚合统计违规意图分布。5. 和三层Tool治理联动Trace顶层记录本轮启用的Skill集合、全局工具黑白名单快照完整记录三层Tool治理的顶层约束。第三层Span 子步骤执行层Trace下所有细分操作中间层Span是Trace内部所有独立业务操作的容器覆盖OpenClaw全部扩展插槽行为分为6大类标准Span类型完全对齐三层Tool治理、安全、记忆、多代理模块RulePolicySpanrules.md规则引擎校验Span第三层Tool治理ToolRunSpan工具执行Span第二层ToolAdapter沙箱执行SkillFlowSpan技能流程Span第一层SKILL.md业务引导MemoryRWSpanLongTermMemory记忆读写/检索SpanSubAgentDispatchSpan子代理委派SFA2A通信SpanContextEngineSpan上下文拼装、记忆注入Span1. 通用采集字段spanId、parentTraceId、parentSpanId支持多层嵌套子代理内部Span挂载父Span操作开始/结束时间、执行耗时、超时标记、异常堆栈操作入参、输出结果、自动脱敏后的内容关联配置本次操作匹配的rules条目、SKILL文档片段、记忆检索阈值资源指标单次工具调用Token、沙箱CPU/内存、并发锁等待时长。2. 各细分Span核心埋点逻辑1RulePolicySpan规则校验Span最高优先级拦截节点触发钩子on_llm_output、before_tool_run记录匹配的rules.md规则ID、工具黑白名单判定、预算熔断、高危操作二次确认结果若拦截工具调用标记阻断日志不创建后续ToolRunSpan。对应三层Tool治理第三层全局规则拦截。2SkillFlowSpan技能流程Span触发钩子before_tool_run记录加载的SKILL.md文档、规定工具调用顺序、模型是否遵循技能流程、是否出现违规工具跳转对应三层Tool治理第一层业务引导层。3ToolRunSpan工具沙箱执行Span触发钩子before_tool_run/after_tool_run记录工具名称、原始入参、沙箱隔离等级、网络白名单校验、执行超时、返回结果、报错信息、工具调用限流计数对应三层Tool治理第二层ToolAdapter沙箱执行层。4MemoryRWSpan长期记忆Span触发钩子before_memory_read/after_memory_write记录召回记忆条数、相关性阈值、记忆脱敏规则、是否禁止敏感内容入库、向量库查询耗时绑定MEMORY.md配置。5SubAgentDispatchSpan子代理委派Span触发钩子subagent_dispatch记录AGENTS.md委派规则、子代理权限收缩记录、SFA2A消息报文、子代理会话ID子代理内部完整Trace全部挂载为该Span子节点。6ContextEngineSpan上下文拼装Span触发钩子before_prompt_build记录所有MD提示词加载顺序、上下文压缩截断规则、注入的长期记忆片段、总上下文窗口Token长度。3. 生命周期介入在每个独立操作开始时创建Span操作完成/异常销毁Span所有Span内部会挂载第四层Generation模型推理节点。4. 业务核心价值实现三层Tool治理全流程可追溯一条工具调用链路完整记录「规则拦截校验→技能流程约束→沙箱真实执行」三层行为清晰区分失败根源是规则拦截、参数错误还是沙箱资源超限。第四层Generation LLM推理原子层最细粒度Span内部模型调用1. 定义单次完整大模型推理请求LLM生成/Embedding向量是四层追踪最底层原子节点父节点永远是某个Span如Agent主推理Span、子代理推理Span、记忆向量Embedding。Langfuse中Generation是特殊类型Span专门标准化LLM调用指标。2. 采集完整字段模型路由信息ModelProvider插件选中模型名称、路由降级记录、重试次数完整入参本轮System Prompt对话上下文、温度top_p、最大输出Token、rules.md推理预算限制模型原始输出思考过程、工具调用JSON、流式分段输出完整快照精准Token统计输入tokens、输出tokens、总tokens、模型计费成本推理指标首字符延迟、总推理耗时、流式分段数量、熔断超时标记元标签本次推理归属的技能、规则、子代理ID。3. 生命周期介入钩子before_model_resolve初始化Generation记录模型路由规则、预算上限llm_input记录完整Prompt上下文llm_output捕获模型完整返回内容、工具调用指令流式推理分段实时写入Langfuse完整还原模型思考过程。4. 业务作用精准成本拆分定位高Token消耗的模型、技能、用户请求模型幻觉排查直接查看模型原始输出定位违规工具调用、编造数据根源提示词迭代验证对比修改SOUL/rules.md前后Generation输出差异模型韧性监控统计模型超时、失败、自动降级频次优化ModelProvider插件路由策略。三、四层追踪完整执行数据流一次用户请求完整链路1. Session层session_start └─ 2. Trace层message_received 创建主Trace ├─ SpanContextEngineSpan拼装全部MD提示词 │ └─ GenerationEmbedding长期记忆向量召回模型调用 ├─ SpanRulePolicySpanrules.md前置意图校验 │ └─ 若拦截直接关闭Trace链路终止 │ └─ 若放行继续执行 ├─ SpanAgentMainRunSpan主代理推理容器 │ └─ Generation主LLM推理第四层模型输出工具调用指令 │ ├─ SpanRulePolicySpan二次校验模型工具调用 │ │ └─ 拦截则终止工具流程 │ ├─ SpanSkillFlowSpanSKILL.md技能流程校验 │ └─ SpanToolRunSpan沙箱执行工具 │ └─ Generation工具内辅助LLM推理如代码解析、视频理解 ├─ SpanMemoryRWSpan工具结果写入长期记忆 └─ 多轮循环直至任务完成 └─ after_agent_turn 关闭Trace汇总本轮指标 session_close 关闭顶层Session聚合全会话统计四、四层追踪与OpenClaw核心模块联动关系1. 和三层Tool治理联动最核心落地场景四层完整记录三层Tool每一步校验动作链路溯源闭环第一层SkillSKILL.md→ 对应SkillFlowSpan第二层ToolAdapter沙箱执行 → 对应ToolRunSpan第三层rules.md全局规则拦截 → 对应RulePolicySpan每一次工具调用在Langfuse链路中清晰展示三层校验的执行顺序、拦截/放行结果解决线上工具失控无法溯源问题。2. 和可插拔运行时插槽联动所有插件行为自动生成对应SpanModelProvider插件 → Generation模型节点MemoryBackend插件 → MemoryRWSpanToolAdapter插件 → ToolRunSpanSecurityPolicy插件 → RulePolicySpanChannelConnector渠道插件 → Session/Trace渠道标签Scheduler定时插件 → 独立定时SessionTrace3. 和MD配置提示词体系联动每一层节点自动快照当前生效MD配置Session全局rules.md、IDENTITY.md快照Trace本轮完整拼接System Prompt全MD合并SkillFlowSpan当前执行SKILL.md文档片段RulePolicySpan命中的rules.md规则原文4. 和SFA2A多代理委派联动父代理Trace内生成SubAgentDispatchSpan子代理完整一套「Session→Trace→Span→Generation」四层链路全部作为子节点挂载实现父子代理全链路串联追踪。五、四层Langfuse追踪核心优缺点优势分层下钻故障定位零盲区从用户会话宏观成本逐层下钻到单轮请求、工具执行步骤、模型原始输出精准区分问题是规则、技能、沙箱还是模型幻觉天然适配企业安全审计RulePolicySpan独立记录所有rules.md拦截行为完整留存违规请求、高危工具调用日志满足等保、隐私合规追溯要求多维度成本精细化归因四层均可自定义标签支持按租户、Agent、技能、模型、用户、渠道拆分Token与费用无侵入自动埋点基于OpenClaw事件总线钩子无需业务代码埋点仅安装Langfuse插件即可全链路采集优雅降级不阻塞主业务Langfuse服务离线时插件自动丢弃遥测数据Agent正常运行不会推理超时、会话中断完整适配多代理、长期记忆、定时任务覆盖OpenClaw全部企业能力区别于Codex/Claude Code仅单层模型追踪。短板四层全量采集会增加少量内存、网络IO开销超高并发场景建议开启内容脱敏/采样上报Langfuse自托管需要维护ClickHouse/PostgreSQL存储增加运维成本超大Session上千轮对话Trace数量多前端加载链路瀑布图会存在轻微延迟支持按时间分片过滤优化。六、与Codex、Claude Code追踪体系核心区别OpenAI Codex仅两层追踪任务Trace LLM Generation无独立规则、技能、记忆Span分层无全局规则拦截埋点无法区分工具调用失败是权限还是执行异常无多代理会话分层能力厂商封闭观测体系不可自定义分层埋点。Claude Code仅两层会话Trace 模型/工具Span缺少独立RulePolicy规则校验层、Skill技能流程层不支持外置规则文档rules.md审计埋点仅适合个人本地代码调试无企业多租户分层统计。OpenClaw四层Langfuse追踪四层标准化分层深度绑定企业生产管控模块rules、三层Tool治理、多代理、长期记忆插件化可配置私有化部署完全可控面向线上大规模AI智能体中台设计。七、典型企业落地使用场景场景1客服Agent线上风险审计需求统计用户高危咨询、违规工具调用、敏感数据输出四层使用方式Session层按客服租户、渠道聚合会话总量Trace层过滤被rules.md拦截的违规请求RulePolicySpan查看每条拦截命中的规则、用户原始提问Generation层查看模型是否主动生成违规工具调用指令用于迭代rules.md约束。场景2工具执行失败根因排查用户反馈查询订单工具频繁报错打开对应Trace下钻ToolRunSpan查看父级RulePolicySpan确认是否权限拦截查看SkillFlowSpan确认模型是否按标准流程调用查看Generation层确认模型输出的工具参数是否格式错误。场景3多子代理复杂任务成本优化多代理协同报表生成消耗Token过高Session层查看总消耗Trace层定位高消耗轮次SubAgentDispatchSpan下钻子代理完整四层链路Generation层区分哪个子代理/模型占用最多Token针对性调整提示词、推理预算规则。场景4提示词迭代效果验证修改SOUL.md/rules.md约束后验证效果筛选同业务场景Session对比修改前后Trace内Generation输出内容、Token消耗通过SkillFlowSpan、RulePolicySpan验证新规则是否正常生效。八、落地价值匹配UpClaw从「可用」到「可上线」工程目标可观测标准化闭环补齐原生AgentScope缺失的分层遥测能力一套四层链路覆盖会话、推理、工具、安全全环节安全与成本双管控可视化将rules.md权限、三层Tool治理、模型资源消耗全部可视化解决AI智能体线上黑盒问题企业合规审计可落地所有风险操作独立分层存储支持长期日志留存、筛选导出满足企业监管要求迭代效率提升无需复现用户问题直接通过四层Trace完整回放Agent执行全流程大幅降低排障、提示词调优成本多业务统一观测底座一套Langfuse四层追踪同时支撑客服、运维、编码、数据多类型Agent统一LLMOps观测平台。