ClawHub
SkillsPluginsOfficialDocsSupport
K
plugins/codecls/openclaw-x-langfuse-plugin
Infrastructure
#diagnostics#langfuse#observability#tracing

Langfuse Bridge

Forward OpenClaw model usage diagnostics to Langfuse

Caleb@codecls

openclaw-x-langfuse-plugin

Forward OpenClaw model-usage diagnostics to Langfuse.

The plugin registers a background service that subscribes to OpenClaw's internal diagnostics bus and reconstructs each turn as a nested Langfuse trace: one root per turn (grouped by the W3C trace id OpenClaw stamps on every event), with a child observation for every model call, tool call, and retrieval step in it. Traces are tagged with the OpenClaw session id so a conversation's turns group together in Langfuse's Sessions view.

Crucially, tool calls and RAG/retrieval steps appear as their own observations (tool and retriever types) nested under the run — so you can see the retrieval that fed a generation instead of the context just appearing in the next prompt out of nowhere.

Built on the Langfuse v5 SDK (OpenTelemetry-based), so traces appear in Langfuse's new observations-first ("fast") UI. The Langfuse SpanProcessor runs on a dedicated, isolated OTel TracerProvider (setLangfuseTracerProvider) so it never touches the global OpenTelemetry state OpenClaw's bundled diagnostics-otel service owns.

It subscribes via the public onInternalDiagnosticEvent SDK export. (The ctx.internalDiagnostics.onEvent capability is privileged — the runtime injects it only for the bundled diagnostics-otel/diagnostics-prometheus services, so third-party plugins never receive it.) The public listener delivers the run.*, model.usage, tool.execution.*, context.assembled, and model.call.error event bodies this bridge maps (minus private message content — see below).

Install

bash
openclaw plugins install openclaw-x-langfuse-plugin

OpenClaw resolves through ClawHub first and falls back to npm. For local development, install from a path with --link:

bash
openclaw plugins install ./openclaw-x-langfuse-plugin --link

Configure

Enable the plugin and provide Langfuse credentials in openclaw.json:

json
{
  "plugins": {
    "allow": ["langfuse-bridge"],
    "entries": {
      "langfuse-bridge": {
        "enabled": true,
        "config": {
          "publicKey": "pk-lf-...",
          "secretKey": "sk-lf-...",
          "baseUrl": "https://cloud.langfuse.com"
        }
      }
    }
  }
}

Credentials may also be supplied via environment variables, which take effect when the corresponding config field is absent:

Config fieldEnvironment fallbackDefault
publicKeyLANGFUSE_PUBLIC_KEY—
secretKeyLANGFUSE_SECRET_KEY—
baseUrlLANGFUSE_BASE_URLhttps://cloud.langfuse.com

Then restart the gateway:

bash
openclaw gateway restart

If publicKey/secretKey are missing, the service logs a warning and does not start — it never blocks the gateway.

What gets sent

Each OpenClaw turn becomes one Langfuse trace (keyed by the shared W3C trace id), named after the channel, with session.id set to the OpenClaw session id so a conversation's turns group in the Sessions view. Under that root:

  • Turn root (agent) — anchored by run.started/run.completed, with outcome and durationMs. Its trace-level input/output mirror the turn's prompt and final response. (OpenClaw's per-event span parents are inconsistent — model.usage hangs off the harness span while tools hang off the run span — so children are attached directly to this one root rather than reconstructing that internal chain.)
  • Generation — built from model.usage: model, usageDetails (input, output, cache_read, cache_write, total), costDetails.totalCost (USD), timing, plus provider metadata and the turn's prompt/response text as input/output.
  • Tool / Retriever — one observation per tool.execution.*, named after the tool. Retrieval/search tools (vector search, RAG, grep, web fetch, memory recall, …) are classified as Langfuse retriever observations; everything else is a tool. Carries toolSource, paramsSummary, duration, and — when recoverable — the tool's arguments and result as input/output.
  • Context — context.assembled becomes a short span with message/prompt size metadata.
  • Errors — model.call.error becomes an ERROR observation with the failure category/kind.

Message content (prompts, responses, tool arguments and results) is not delivered to third-party plugins — OpenClaw hands it only to bundled diagnostics services. The bridge recovers it best-effort from the per-session trajectory transcript (<stateDir>/agents/<agentId>/sessions/<sessionId>.trajectory.jsonl). If the transcript is unavailable, observations are still forwarded with empty input/output; the structure (which step ran, when, how long) is always present.

Robustness

OpenClaw delivers tool.execution.* and model.call.* events asynchronously (they're queued and can be dropped under heavy load), while run.* and model.usage are synchronous — so run.completed reaches the bridge before its own tool events, and model.usage arrives after it. The engine handles this by soft-ending the turn root (fixing its duration) while keeping it resolvable, so late-arriving children still attach to it, and an idle reaper closes any observation orphaned by a dropped terminal event.

How it works

js
import { onInternalDiagnosticEvent } from "openclaw/plugin-sdk/diagnostic-runtime";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { startObservation, setLangfuseTracerProvider } from "@langfuse/tracing";
import { createTraceEngine } from "./tracer.js";

api.registerService({
  id: "langfuse-bridge",
  start(ctx) {
    // Isolated OTel pipeline -> never touches OpenClaw's global tracer provider.
    const provider = new NodeTracerProvider({
      spanProcessors: [new LangfuseSpanProcessor({ publicKey, secretKey, baseUrl })],
    });
    setLangfuseTracerProvider(provider);

    // The engine groups observations into one trace per turn, keyed by the W3C
    // trace id OpenClaw stamps on every event, and attaches model.usage /
    // tool.execution.* / context.assembled as children of that turn root.
    const engine = createTraceEngine({ startObservation }, { /* resolvers */ });
    const unsubscribe = onInternalDiagnosticEvent((evt) => engine.handle(evt));
    setInterval(() => engine.sweep(), 60_000).unref(); // reap orphans
  },
});

Note: these events are emitted on OpenClaw's reply/delivery path (channel messages, webchat/TUI turns) — not on direct openclaw agent CLI runs, which use the embedded runner and don't emit them.

License

MIT

Install

$
openclaw plugins install clawhub:openclaw-x-langfuse-plugin@latest
Downloads
Repository
langfuse/openclaw-x-langfuse-plugin
Security audit
Pass
Last updated
2mo ago
Current version
v1.5.0
Type
Code Plugin
Download
ClawHub

Skills and plugins for OpenClaw agents. Part of the wider OpenClaw ecosystem.

Explore docs

SkillsPluginsOfficialAudits

Publish SkillPublish PluginCreate org

OverviewOpenClawDocsBlog

SupportGitHubDiscord

Built alongside the OpenClaw ecosystem

LobsterCrabboxClickClackCrabfleetOctopoolClawSweeperagent-skillsdiscrawlgitcrawlslacrawlnotcrawltelecrawlgraincrawlcrawlkitcrawlbaracpxmcporterTachikomaclawpatchclawbenchPeekaboocookbookplugin-inspectorwacrawlcrabpotAll projectsLobsterCrabboxClickClackCrabfleetOctopoolClawSweeperagent-skillsdiscrawlgitcrawlslacrawlnotcrawltelecrawlgraincrawlcrawlkitcrawlbaracpxmcporterTachikomaclawpatchclawbenchPeekaboocookbookplugin-inspectorwacrawlcrabpotAll projects

© 2026 OpenClaw Foundation

Privacy policy·Status·Deployed on Vercel·Powered by Convex

....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals
  hooks runners slash-commands skill.md templates scanners review-bots     safe browse paths   official gateways   publisher handles   org trust   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@
openclaw ecosystem    crabbox clickclack crawler packs gateway plugins   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship
---- downloads installs stars lineage ownership docs package integrity   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@   :::: signed manifests ::::: moderated releases ::::: version history ::::
  safe browse paths   official gateways   publisher handles   org trust     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship     hooks runners slash-commands skill.md templates scanners review-bots
....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals
  hooks runners slash-commands skill.md templates scanners review-bots     safe browse paths   official gateways   publisher handles   org trust   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@
openclaw ecosystem    crabbox clickclack crawler packs gateway plugins   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship
---- downloads installs stars lineage ownership docs package integrity   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@   :::: signed manifests ::::: moderated releases ::::: version history ::::
  safe browse paths   official gateways   publisher handles   org trust     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship     hooks runners slash-commands skill.md templates scanners review-bots
....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals
  hooks runners slash-commands skill.md templates scanners review-bots     safe browse paths   official gateways   publisher handles   org trust   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@
openclaw ecosystem    crabbox clickclack crawler packs gateway plugins   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship
---- downloads installs stars lineage ownership docs package integrity   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@   :::: signed manifests ::::: moderated releases ::::: version history ::::
  safe browse paths   official gateways   publisher handles   org trust     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship     hooks runners slash-commands skill.md templates scanners review-bots
....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals
  hooks runners slash-commands skill.md templates scanners review-bots     safe browse paths   official gateways   publisher handles   org trust   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@
openclaw ecosystem    crabbox clickclack crawler packs gateway plugins   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship
---- downloads installs stars lineage ownership docs package integrity   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@   :::: signed manifests ::::: moderated releases ::::: version history ::::
  safe browse paths   official gateways   publisher handles   org trust     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship     hooks runners slash-commands skill.md templates scanners review-bots
....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals
  hooks runners slash-commands skill.md templates scanners review-bots     safe browse paths   official gateways   publisher handles   org trust   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@
openclaw ecosystem    crabbox clickclack crawler packs gateway plugins   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship
---- downloads installs stars lineage ownership docs package integrity   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@   :::: signed manifests ::::: moderated releases ::::: version history ::::
  safe browse paths   official gateways   publisher handles   org trust     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship     hooks runners slash-commands skill.md templates scanners review-bots
....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals