OpenClaw Tracing with Litefuse

OpenClaw is an open-source autonomous AI agent. The openclaw-litefuse-plugin hooks into the gateway’s plugin pipeline and ships every agent turn to Litefuse — no agent code changes required.

The plugin attaches to OpenClaw’s lifecycle hooks (message_received, llm_input/llm_output, before_tool_call/after_tool_call, before_agent_start/agent_end, …) and emits one Litefuse trace per agent turn, with nested observations for each LLM call and each tool execution.

For AI — automated install

If you’re chatting with an AI coding agent that has shell access on this machine, paste this prompt and it will handle the install end-to-end:

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

The skill will ask for your Litefuse API keys (or walk you through signing up), then build, link, and configure the plugin against your OpenClaw install. For step-by-step manual setup instead, continue below.

What gets captured

For Anthropic models, the per-call token breakdown includes cache_read_input_tokens and cache_creation_input_tokens so Litefuse can compute accurate cached vs. non-cached cost.

Trace structure

A typical turn produces a trace shaped like:

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)

Design notes:

• Root span = enter_openclaw_system: opens on the first message_received of the turn and ends with the trace, so the trace duration matches the end-to-end user wait.
• Agent span nests under the root: opens on before_agent_start and closes on agent_end, carrying input/output and the agent’s per-turn aggregate stats.
• TOOL observations for graph rendering: each tool call is emitted with the dedicated TOOL observation type (not a generic span), which Litefuse uses for DAG view.
• Trace fields populated lazily: userId, sessionId, input, and output are set on the trace as soon as the corresponding hook fires (message_received, session_start, agent_end).
• Flush on agent_end: the plugin defers flushing for 200 ms after agent_end and 500 ms before calling flushAsync, so any late llm_output arriving after agent_end still attaches to the same trace.

Quick Start

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}'

Multiple Litefuse targets

Send identical traces to several Litefuse instances at once (e.g. a production project and an analytics project). All targets receive the same trace and observation IDs so you can join data across them:

{
  "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"
            }
          ]
        }
      }
    }
  }
}

When targets is set, the top-level publicKey/secretKey/baseUrl are ignored.

Configuration reference

Available hooks

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.

Pass a subset under enabledHooks to silence categories you don’t want (e.g. drop gateway_start if you only care about agent turns).

Troubleshooting

openclaw plugins doctor reports [Litefuse] Missing required configuration. publicKey/secretKey weren’t set or are empty. Re-run the openclaw config set commands from the Quick Start, then openclaw gateway restart.

Plugin loads but no traces appear in Litefuse. Most often a credential or network error on the first flush. Enable 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

You should see Started root span … traceId=… on each agent turn, then Flushed 1 target(s) after agent_end. If Flushed never appears, the SDK couldn’t reach Litefuse — confirm baseUrl and creds with:

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

Trace appears but agent span has no output. The turn errored before agent_end fired (most common: model auth failure). Check the agent log for lane task error — fix the underlying error and the next successful turn will export a complete trace.

package install requires compiled runtime output for TypeScript entry. You linked the plugin before running npm run build. Build, then re-run openclaw plugins install --link ….

Plugin shows in openclaw plugins list but plugins doctor flags legacy before_agent_start. Informational only — the plugin uses the legacy hook on purpose to capture the agent span; safe to ignore.

Update / Uninstall

# 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

Resources

• Plugin source on GitHub
• OpenClaw documentation
• OpenClaw plugin CLI
• Litefuse Cloud