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.

Trace OpenClaw via OpenTelemetry

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 SDK, 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

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