用 Litefuse 追踪 OpenClaw

OpenClaw 是一个开源的自主 AI Agent。openclaw-litefuse-plugin 接入网关的插件管线，把每个 Agent 回合发送到 Litefuse —— 无需修改 Agent 代码。

该插件挂接到 OpenClaw 的生命周期 hook（message_received、llm_input/llm_output、before_tool_call/after_tool_call、before_agent_start/agent_end，等等），为每个 Agent 回合生成一条 Litefuse trace，每个 LLM 调用和工具执行作为嵌套 observation。

给 AI —— 自动安装

如果你正在和一个有本机 shell 权限的 AI 编码 Agent 对话，把下面这段 prompt 粘贴过去，它会端到端完成安装：

Read https://litefuse.ai/SKILL.md and follow the instructions to install and configure Litefuse for OpenClaw.

skill 会向你索取 Litefuse 的 API Key（或者引导你注册），然后针对你的 OpenClaw 安装构建、链接并配置插件。如果你想手工一步步配置，请继续往下看。

会捕获哪些数据

对于 Anthropic 模型，单次调用的 token 拆分包含 cache_read_input_tokens 和 cache_creation_input_tokens，这样 Litefuse 可以准确计算缓存与非缓存的成本。

Trace 结构

一个典型回合产生的 trace 形如：

openclaw-3521e308                          (trace, tags=[openclaw], sessionId, userId)
└── enter_openclaw_system                  (root span — opens on message_received)
    └── invoke_agent main                  (agent span — input = user prompt)
        ├── chat <model>                   (generation — usageDetails per LLM call)
        ├── execute_tool Bash              (tool — args + result)
        ├── chat <model>                   (generation)
        └── execute_tool Edit              (tool)

设计说明：

• 根 span = enter_openclaw_system：在回合的第一个 message_received 时开启，并随 trace 一起结束，所以 trace 时长就等于用户端到端等待时间。
• Agent span 嵌套在根之下：在 before_agent_start 时开启，在 agent_end 时关闭，携带 input/output 与 Agent 的回合级聚合统计。
• 使用 TOOL observation 用于图视图渲染：每次工具调用使用专用的 TOOL observation 类型（不是通用 span），Litefuse 用它来绘制 DAG 视图。
• Trace 字段惰性填充：userId、sessionId、input 和 output 在对应的 hook 触发（message_received、session_start、agent_end）后立即写入 trace。
• 在 agent_end 上 flush：插件会在 agent_end 后延迟 200ms，并在调用 flushAsync 前再等 500ms，这样在 agent_end 之后晚到的 llm_output 仍能挂到同一个 trace 上。

快速开始

git clone https://github.com/litefuse/openclaw-litefuse-plugin.git \
  ~/.openclaw/extensions/openclaw-litefuse-plugin
cd ~/.openclaw/extensions/openclaw-litefuse-plugin
npm install
npm run build

openclaw plugins install --link ~/.openclaw/extensions/openclaw-litefuse-plugin

openclaw plugins inspect openclaw-litefuse-plugin
# Status: loaded
# Source: ~/.openclaw/extensions/openclaw-litefuse-plugin/dist/index.js

openclaw config set plugins.entries.openclaw-litefuse-plugin.config.publicKey "pk-lf-xxx"
openclaw config set plugins.entries.openclaw-litefuse-plugin.config.secretKey "sk-lf-xxx"
openclaw config set plugins.entries.openclaw-litefuse-plugin.config.baseUrl   "https://litefuse.cloud"
openclaw config set plugins.entries.openclaw-litefuse-plugin.config.environment "production"

openclaw gateway restart

openclaw plugins doctor 2>&1 | grep Litefuse
# Expected:
#   [Litefuse] Target added: https://litefuse.cloud
#   [Litefuse] Plugin initialized with 1 target(s)
#   [Litefuse] Plugin activated (baseUrl: https://litefuse.cloud)

openclaw agent --model anthropic/claude-haiku-4-5 \
  --session-id "litefuse-verify-$(date +%s)" \
  -m "say hello"
 
curl -sS -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  "https://litefuse.cloud/api/public/traces?limit=1&tags=openclaw" | jq '.data[0] | {id,name,timestamp}'

多个 Litefuse 目标

可以同时把同一份 trace 发送到多个 Litefuse 实例（比如生产项目和分析项目）。所有目标都收到相同的 trace 与 observation ID，便于跨实例做数据关联：

{
  "plugins": {
    "entries": {
      "openclaw-litefuse-plugin": {
        "enabled": true,
        "config": {
          "targets": [
            {
              "name": "production",
              "publicKey": "pk-lf-xxx",
              "secretKey": "sk-lf-xxx",
              "baseUrl": "https://litefuse.cloud"
            },
            {
              "name": "analytics",
              "publicKey": "pk-lf-yyy",
              "secretKey": "sk-lf-yyy",
              "baseUrl": "http://litefuse-analytics:3000"
            }
          ]
        }
      }
    }
  }
}

设置了 targets 之后，顶层的 publicKey/secretKey/baseUrl 会被忽略。

配置参考

可用的 hook

session_start、session_end、message_received、message_sending、message_sent、llm_input、llm_output、before_tool_call、after_tool_call、before_agent_start、agent_end、gateway_start。

通过 enabledHooks 传入子集来屏蔽你不关心的类别（例如只关心 Agent 回合，可以去掉 gateway_start）。

故障排查

openclaw plugins doctor 报告 [Litefuse] Missing required configuration。 publicKey/secretKey 没设或为空。重新运行快速开始里的 openclaw config set 命令，然后 openclaw gateway restart。

插件加载了但 Litefuse 中没有 trace。 通常是首次 flush 时的凭据或网络错误。打开 debug：

openclaw config set plugins.entries.openclaw-litefuse-plugin.config.debug true
openclaw gateway restart
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep Litefuse

每个 Agent 回合应该看到 Started root span … traceId=…，agent_end 之后看到 Flushed 1 target(s)。如果 Flushed 一直不出现，说明 SDK 联系不到 Litefuse —— 用以下命令确认 baseUrl 和凭据：

curl -sS -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  "$LANGFUSE_BASE_URL/api/public/projects" | jq .

Trace 出现了，但 agent span 没有 output。 回合在 agent_end 触发前就出错了（最常见的是模型鉴权失败）。检查 Agent 日志中的 lane task error —— 修复底层错误，下一次成功的回合会导出完整 trace。

package install requires compiled runtime output for TypeScript entry。 你在跑 npm run build 之前就 link 了插件。先构建，再重跑 openclaw plugins install --link …。

插件出现在 openclaw plugins list 中，但 plugins doctor 提示 legacy before_agent_start。 仅信息提示 —— 插件有意使用旧版 hook 来捕获 agent span；可以放心忽略。

升级 / 卸载

# Update from GitHub
cd ~/.openclaw/extensions/openclaw-litefuse-plugin && git pull && npm install && npm run build
openclaw gateway restart
 
# Uninstall
openclaw plugins uninstall openclaw-litefuse-plugin

资源

• GitHub 上的插件源码
• OpenClaw 文档
• OpenClaw 插件 CLI
• Litefuse Cloud