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. 四层层级定义（从粗到细，父子包含关系）

1. 第一层：Session（会话层，最顶层）
2. 第二层：Trace（单轮请求主链路层）
3. 第三层：Span（子步骤执行层，工具/记忆/子代理/规则校验）
4. 第四层：Generation（LLM模型推理原子层，最细粒度）

层级嵌套关系：

1个Session ⊇ N个Trace ⊇ N个Span ⊇ N个Generation

3. 核心设计目标

1. 全局成本归因：按用户、会话、模型、技能、租户拆分Token消耗与费用；
2. 全链路问题定位：从用户对话一键下钻到模型思考、工具参数、规则拦截记录；
3. 企业审计合规：自动记录rules.md拦截、工具黑白名单命中、脱敏行为；
4. Agent行为复盘：完整还原ReAct循环、子代理委派、长期记忆召回全过程；
5. 性能监控：分层统计各阶段延迟、超时、失败率，支撑调度优化。

二、四层分层完整拆解（每层定义、埋点钩子、存储字段、生命周期介入、业务作用）

第一层：Session 会话层（全局顶层容器）

1. 定义

一个独立Agent完整生命周期会话，对应一次用户持续对话，直到会话销毁（关闭聊天/超时回收），全局唯一 session_id，关联固定用户ID、租户、Agent身份（IDENTITY.md）。

对应生命周期钩子：session_start / session_close

2. 自动采集元数据

• 基础标识：sessionId、userId、tenantId、agentName、IDENTITY.md身份摘要
• 全局配置快照：加载的rules.md版本、启用插件列表、全局推理预算上限
• 聚合指标：会话总Token消耗、总耗时、总工具调用次数、总规则拦截次数
• 标签：业务场景标签、渠道标签（飞书/Web/API）、部署环境标签（测试/生产）

3. 生命周期介入时机

1. onSessionCreate（会话创建）：创建Langfuse Session根节点，写入全局MD配置快照；
2. 全会话生命周期：所有下层Trace/Span/Generation自动挂载该Session；
3. onSessionClose（会话销毁）：写入会话聚合统计，标记会话结束状态（正常关闭/熔断超时/违规拦截终止）。

4. 业务作用

• 宏观维度统计：某客户/某业务线全天总AI成本、会话平均时长；
• 完整对话回放：一键拉取用户全轮交互，用于客服、业务问题复盘；
• 租户隔离统计：区分不同业务Agent资源消耗，做成本分摊。

5. 与其他模块联动

绑定 MEMORY.md 长期记忆全局配置、HEARTBEAT.md 定时心跳调度记录，会话内所有记忆读写、定时任务都归属该Session。

第二层：Trace 单轮请求主链路层（每一轮用户输入顶层链路）

1. 定义

用户单次消息输入 触发的完整一轮Agent执行闭环（一轮ReAct循环），一条Trace对应用户一句提问，唯一traceId，父节点为Session。

对应钩子：message_received（创建Trace）、after_agent_turn（关闭Trace）

2. 采集核心内容

1. 用户原始输入文本、附件、视频/文件输入；
2. 本轮生效完整System Prompt快照（按优先级拼接：rules→IDENTITY→SOUL→TOOLS→SKILL→USER.md）；
3. 顶层全局规则校验结果：本轮是否触发rules.md前置拦截、拦截原因、命中规则条目；
4. 本轮最终输出回答、输出脱敏记录；
5. 顶层聚合指标：本轮总耗时、总输入/输出Token、本轮调用工具总数、子代理创建数量。

3. 生命周期介入

1. onInput（消息入站）：初始化Trace根节点，记录用户输入，执行rules.md前置风控并写入Trace元数据；
2. 整轮ReAct循环：所有工具、记忆、模型调用全部作为子Span挂载到当前Trace；
3. onOutput（结果输出）：记录最终回复、脱敏操作；
4. 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治理、安全、记忆、多代理模块：

1. RulePolicySpan：rules.md规则引擎校验Span（第三层Tool治理）
2. ToolRunSpan：工具执行Span（第二层ToolAdapter沙箱执行）
3. SkillFlowSpan：技能流程Span（第一层SKILL.md业务引导）
4. MemoryRWSpan：LongTermMemory记忆读写/检索Span
5. SubAgentDispatchSpan：子代理委派SFA2A通信Span
6. ContextEngineSpan：上下文拼装、记忆注入Span

1. 通用采集字段

• spanId、parentTraceId、parentSpanId（支持多层嵌套，子代理内部Span挂载父Span）；
• 操作开始/结束时间、执行耗时、超时标记、异常堆栈；
• 操作入参、输出结果、自动脱敏后的内容；
• 关联配置：本次操作匹配的rules条目、SKILL文档片段、记忆检索阈值；
• 资源指标：单次工具调用Token、沙箱CPU/内存、并发锁等待时长。

2. 各细分Span核心埋点逻辑

（1）RulePolicySpan（规则校验Span，最高优先级拦截节点）

触发钩子：on_llm_output、before_tool_run

记录：匹配的rules.md规则ID、工具黑白名单判定、预算熔断、高危操作二次确认结果；若拦截工具调用，标记阻断日志，不创建后续ToolRunSpan。

对应三层Tool治理第三层全局规则拦截。

（2）SkillFlowSpan（技能流程Span）

触发钩子：before_tool_run

记录：加载的SKILL.md文档、规定工具调用顺序、模型是否遵循技能流程、是否出现违规工具跳转；

对应三层Tool治理第一层业务引导层。

（3）ToolRunSpan（工具沙箱执行Span）

触发钩子：before_tool_run / after_tool_run

记录：工具名称、原始入参、沙箱隔离等级、网络白名单校验、执行超时、返回结果、报错信息、工具调用限流计数；

对应三层Tool治理第二层ToolAdapter沙箱执行层。

（4）MemoryRWSpan（长期记忆Span）

触发钩子：before_memory_read / after_memory_write

记录：召回记忆条数、相关性阈值、记忆脱敏规则、是否禁止敏感内容入库、向量库查询耗时；绑定MEMORY.md配置。

（5）SubAgentDispatchSpan（子代理委派Span）

触发钩子：subagent_dispatch

记录：AGENTS.md委派规则、子代理权限收缩记录、SFA2A消息报文、子代理会话ID；子代理内部完整Trace全部挂载为该Span子节点。

（6）ContextEngineSpan（上下文拼装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. 采集完整字段

1. 模型路由信息：ModelProvider插件选中模型名称、路由降级记录、重试次数；
2. 完整入参：本轮System Prompt+对话上下文、温度top_p、最大输出Token、rules.md推理预算限制；
3. 模型原始输出：思考过程、工具调用JSON、流式分段输出完整快照；
4. 精准Token统计：输入tokens、输出tokens、总tokens、模型计费成本；
5. 推理指标：首字符延迟、总推理耗时、流式分段数量、熔断超时标记；
6. 元标签：本次推理归属的技能、规则、子代理ID。

3. 生命周期介入钩子

• before_model_resolve：初始化Generation，记录模型路由规则、预算上限；
• llm_input：记录完整Prompt上下文；
• llm_output：捕获模型完整返回内容、工具调用指令；
• 流式推理：分段实时写入Langfuse，完整还原模型思考过程。

4. 业务作用

1. 精准成本拆分：定位高Token消耗的模型、技能、用户请求；
2. 模型幻觉排查：直接查看模型原始输出，定位违规工具调用、编造数据根源；
3. 提示词迭代验证：对比修改SOUL/rules.md前后Generation输出差异；
4. 模型韧性监控：统计模型超时、失败、自动降级频次，优化ModelProvider插件路由策略。

三、四层追踪完整执行数据流（一次用户请求完整链路）

1. Session层（session_start）
  └─ 2. Trace层（message_received 创建主Trace）
      ├─ Span：ContextEngineSpan（拼装全部MD提示词）
      │   └─ Generation：Embedding（长期记忆向量召回模型调用）
      ├─ Span：RulePolicySpan（rules.md前置意图校验）
      │   └─ 若拦截：直接关闭Trace，链路终止
      │   └─ 若放行：继续执行
      ├─ Span：AgentMainRunSpan（主代理推理容器）
      │   └─ Generation：主LLM推理（第四层，模型输出工具调用指令）
      │   ├─ Span：RulePolicySpan（二次校验模型工具调用）
      │   │   └─ 拦截则终止工具流程
      │   ├─ Span：SkillFlowSpan（SKILL.md技能流程校验）
      │   └─ Span：ToolRunSpan（沙箱执行工具）
      │       └─ Generation：工具内辅助LLM推理（如代码解析、视频理解）
      ├─ Span：MemoryRWSpan（工具结果写入长期记忆）
      └─ 多轮循环直至任务完成
  └─ after_agent_turn 关闭Trace，汇总本轮指标
session_close 关闭顶层Session，聚合全会话统计

四、四层追踪与OpenClaw核心模块联动关系

1. 和三层Tool治理联动（最核心落地场景）

四层完整记录三层Tool每一步校验动作，链路溯源闭环：

1. 第一层Skill（SKILL.md）→ 对应 SkillFlowSpan
2. 第二层ToolAdapter沙箱执行 → 对应 ToolRunSpan
3. 第三层rules.md全局规则拦截 → 对应 RulePolicySpan
   每一次工具调用在Langfuse链路中清晰展示三层校验的执行顺序、拦截/放行结果，解决线上工具失控无法溯源问题。

2. 和可插拔运行时插槽联动

所有插件行为自动生成对应Span：

• ModelProvider插件 → Generation模型节点
• MemoryBackend插件 → MemoryRWSpan
• ToolAdapter插件 → ToolRunSpan
• SecurityPolicy插件 → RulePolicySpan
• ChannelConnector渠道插件 → Session/Trace渠道标签
• Scheduler定时插件 → 独立定时Session+Trace

3. 和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追踪核心优缺点

优势

1. 分层下钻，故障定位零盲区
   从用户会话宏观成本，逐层下钻到单轮请求、工具执行步骤、模型原始输出，精准区分问题是规则、技能、沙箱还是模型幻觉；
2. 天然适配企业安全审计
   RulePolicySpan独立记录所有rules.md拦截行为，完整留存违规请求、高危工具调用日志，满足等保、隐私合规追溯要求；
3. 多维度成本精细化归因
   四层均可自定义标签，支持按租户、Agent、技能、模型、用户、渠道拆分Token与费用；
4. 无侵入自动埋点
   基于OpenClaw事件总线钩子，无需业务代码埋点，仅安装Langfuse插件即可全链路采集；
5. 优雅降级不阻塞主业务
   Langfuse服务离线时插件自动丢弃遥测数据，Agent正常运行，不会推理超时、会话中断；
6. 完整适配多代理、长期记忆、定时任务
   覆盖OpenClaw全部企业能力，区别于Codex/Claude Code仅单层模型追踪。

短板

1. 四层全量采集会增加少量内存、网络IO开销，超高并发场景建议开启内容脱敏/采样上报；
2. Langfuse自托管需要维护ClickHouse/PostgreSQL存储，增加运维成本；
3. 超大Session（上千轮对话）Trace数量多，前端加载链路瀑布图会存在轻微延迟，支持按时间分片过滤优化。

六、与Codex、Claude Code追踪体系核心区别

1. OpenAI Codex
   仅两层追踪：任务Trace + LLM Generation，无独立规则、技能、记忆Span分层；无全局规则拦截埋点，无法区分工具调用失败是权限还是执行异常；无多代理会话分层能力，厂商封闭观测体系，不可自定义分层埋点。
2. Claude Code
   仅两层：会话Trace + 模型/工具Span，缺少独立RulePolicy规则校验层、Skill技能流程层；不支持外置规则文档（rules.md）审计埋点，仅适合个人本地代码调试，无企业多租户分层统计。
3. OpenClaw四层Langfuse追踪
   四层标准化分层，深度绑定企业生产管控模块（rules、三层Tool治理、多代理、长期记忆），插件化可配置，私有化部署完全可控，面向线上大规模AI智能体中台设计。

七、典型企业落地使用场景

场景1：客服Agent线上风险审计

需求：统计用户高危咨询、违规工具调用、敏感数据输出

四层使用方式：

1. Session层：按客服租户、渠道聚合会话总量；
2. Trace层：过滤被rules.md拦截的违规请求；
3. RulePolicySpan：查看每条拦截命中的规则、用户原始提问；
4. Generation层：查看模型是否主动生成违规工具调用指令，用于迭代rules.md约束。

场景2：工具执行失败根因排查

用户反馈查询订单工具频繁报错：

1. 打开对应Trace，下钻ToolRunSpan；
2. 查看父级RulePolicySpan确认是否权限拦截；
3. 查看SkillFlowSpan确认模型是否按标准流程调用；
4. 查看Generation层确认模型输出的工具参数是否格式错误。

场景3：多子代理复杂任务成本优化

多代理协同报表生成消耗Token过高：

1. Session层查看总消耗；
2. Trace层定位高消耗轮次；
3. SubAgentDispatchSpan下钻子代理完整四层链路；
4. Generation层区分哪个子代理/模型占用最多Token，针对性调整提示词、推理预算规则。

场景4：提示词迭代效果验证

修改SOUL.md/rules.md约束后验证效果：

1. 筛选同业务场景Session；
2. 对比修改前后Trace内Generation输出内容、Token消耗；
3. 通过SkillFlowSpan、RulePolicySpan验证新规则是否正常生效。

八、落地价值（匹配UpClaw从「可用」到「可上线」工程目标）

1. 可观测标准化闭环：补齐原生AgentScope缺失的分层遥测能力，一套四层链路覆盖会话、推理、工具、安全全环节；
2. 安全与成本双管控可视化：将rules.md权限、三层Tool治理、模型资源消耗全部可视化，解决AI智能体线上黑盒问题；
3. 企业合规审计可落地：所有风险操作独立分层存储，支持长期日志留存、筛选导出，满足企业监管要求；
4. 迭代效率提升：无需复现用户问题，直接通过四层Trace完整回放Agent执行全流程，大幅降低排障、提示词调优成本；
5. 多业务统一观测底座：一套Langfuse四层追踪同时支撑客服、运维、编码、数据多类型Agent，统一LLMOps观测平台。