Trace OpenClaw with Langfuse

What is OpenClaw? OpenClaw is a free and open-source autonomous AI agent created by Peter Steinberger. It is model-agnostic, supporting Claude, GPT, DeepSeek, and other LLMs. It runs locally and is accessed through messaging platforms like Signal, Telegram, Discord, and WhatsApp. OpenClaw can execute tasks, write its own skills, and maintain long-term memory of user preferences.

What is Langfuse? Langfuse is an open-source AI engineering platform that helps teams trace LLM calls, monitor performance, and debug issues in their AI applications.

Why trace OpenClaw?

Understand agent behavior. Read the prompts, reasoning traces, and tool calls that OpenClaw makes under the hood.
Improve your agent. Identify where the agent gets confused so you can tweak skills, system prompts, and configurations.
Track costs. Monitor spending across models and sessions.

Set up tracing

There are two ways to send OpenClaw data to Langfuse. Pick the one that fits your needs:

OpenClaw x Langfuse plugin (recommended) — install a plugin from ClawHub, paste your Langfuse keys, and you're done. It forwards model usage as Langfuse generations grouped by session, including token counts, costs, and errors.
OpenTelemetry export — point OpenClaw's native OTLP exporter at Langfuse for the full span tree (model calls, tool execution, skill usage, harness lifecycle, and context assembly). Choose this when you want complete agent observability rather than usage and cost tracking alone.

The OpenClaw x Langfuse plugin (the "Langfuse Bridge") subscribes to OpenClaw's internal diagnostics bus and translates model.usage and error events into Langfuse generations, grouped by OpenClaw session. Input and output text is recovered from session transcripts when available.

Set up Langfuse

Sign up for Langfuse Cloud or self-host Langfuse. Create a project and copy your public and secret API keys from the project settings.

Install the plugin

Install the plugin from ClawHub:

openclaw plugins install clawhub:openclaw-x-langfuse-plugin

Configure the plugin

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

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

baseUrl selects your Langfuse data region: 🇪🇺 EU https://cloud.langfuse.com, 🇺🇸 US https://us.cloud.langfuse.com, 🇯🇵 Japan https://jp.cloud.langfuse.com, ⚕️ HIPAA https://hipaa.cloud.langfuse.com, or your own URL for a 🏠 local deployment (e.g. http://localhost:3000).

You can also supply the credentials through the LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and LANGFUSE_BASE_URL environment variables instead of putting them in openclaw.json.

Restart the gateway

Apply the configuration by restarting the OpenClaw gateway:

openclaw gateway restart

View traces in Langfuse

Run OpenClaw as usual. Open your Langfuse project to see generations grouped by session, with token usage, costs, and any forwarded errors.

OpenClaw has built-in OpenTelemetry export, and Langfuse is an OpenTelemetry backend. Point OpenClaw's exporter directly at Langfuse's OTLP endpoint and traces flow in with no plugin, no proxy, and no code changes.

Because the export happens inside OpenClaw itself, it is model-agnostic (it works whether you call Claude, GPT, DeepSeek, or a local model) and captures OpenClaw's full span tree: model calls, tool execution, skill usage, harness lifecycle, and context assembly, along with gen_ai.* attributes for model, token usage, and cost.

OpenClaw exports OTLP over HTTP (http/protobuf), which is exactly what Langfuse's OTLP endpoint accepts. OpenClaw ignores grpc, and Langfuse does not support gRPC, so no extra configuration is needed.

Set up Langfuse

Sign up for Langfuse Cloud or self-host Langfuse. Create a project and copy your public and secret API keys from the project settings.

Create your Basic Auth header

Langfuse authenticates OTLP requests with Basic Auth. Generate the header value by base64-encoding your keys as public_key:secret_key:

# macOS / BSD
echo -n "pk-lf-1234567890:sk-lf-1234567890" | base64
# Linux / GNU (disable line wrapping)
echo -n "pk-lf-1234567890:sk-lf-1234567890" | base64 -w 0

Enable OpenTelemetry export in OpenClaw

Add the diagnostics.otel block to your OpenClaw configuration, pointing it at the Langfuse OTLP endpoint and passing the auth header from the previous step:

{
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "https://cloud.langfuse.com/api/public/otel", // 🇪🇺 EU data region
      // Other Langfuse data regions: 🇺🇸 US https://us.cloud.langfuse.com/api/public/otel,
      // 🇯🇵 Japan https://jp.cloud.langfuse.com/api/public/otel, ⚕️ HIPAA https://hipaa.cloud.langfuse.com/api/public/otel
      // 🏠 Local deployment: http://localhost:3000/api/public/otel
      protocol: "http/protobuf",
      traces: true,
      headers: {
        Authorization: "Basic <AUTH_STRING>", // the base64 value from the previous step
        "x-langfuse-ingestion-version": "4", // surfaces spans in real time in Fast Preview
      },
    },
  },
}

For the richest GenAI attributes, opt in to the latest OpenTelemetry GenAI semantic conventions by setting an environment variable before starting OpenClaw:

OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental

View traces in Langfuse

Run OpenClaw as usual. Open your Langfuse project to see captured traces, where you can inspect individual LLM calls, tool and skill executions, token usage, costs, and the full content of prompts and responses.

Did you know?

Already routing OpenClaw's LLM calls through OpenRouter? You can also capture traces without touching OpenClaw's config by connecting your Langfuse keys in OpenRouter settings to enable Broadcast. Note that this only traces the LLM calls routed through OpenRouter, not OpenClaw's tool and skill spans.

Learn more

OpenClaw x Langfuse plugin: Install and configuration details on ClawHub
Langfuse OpenTelemetry endpoint: Endpoint, authentication, and supported protocols
Getting started with Langfuse: Setting up API keys and projects
OpenClaw OpenTelemetry docs: Full list of OTel configuration options

Was this page helpful?

On this page