@shichen335/openclaw-logfire

openclaw-logfire sends OpenClaw agent activity to Pydantic Logfire as OTLP traces and metrics.

It captures the real execution shape of an OpenClaw run:

• one root invoke_agent span per agent invocation
• staged chat <model> spans reconstructed from llm_input and llm_output
• one execute_tool <tool> span per tool call
• token usage metrics and cumulative session usage
• optional traceparent injection for HTTP commands such as curl, wget, http, and httpie

The plugin is designed around the latest OpenClaw hook flow and OTEL GenAI semantic conventions, while staying practical about privacy controls and debugging.

Requirements

• OpenClaw >= 2026.2.1
• Node.js >= 20
• A Logfire write token
• Network access to Logfire OTLP endpoints:
  • https://logfire-us.pydantic.dev
  • https://logfire-eu.pydantic.dev

Install

For most users, install it as an OpenClaw plugin:

openclaw plugins install @shichen335/openclaw-logfire

Then enable it in openclaw.json:

{
  "plugins": {
    "entries": {
      "openclaw-logfire": {
        "enabled": true,
        "config": {}
      }
    }
  }
}

The plugin id must be openclaw-logfire.

Get A Logfire Write Token

This plugin uses a Logfire write token. The environment variable name is LOGFIRE_TOKEN.

1. Open Logfire Login and sign up or sign in.
2. If this is your first time in Logfire, finish the onboarding flow.
3. If you want a dedicated project for OpenClaw, open Organization > Projects and create one.
4. Open the target project.
5. Go to Settings > Write tokens.
6. Click New write token.
7. Copy the token immediately. Logfire does not show the full token again later.
8. Export it in your shell:

export LOGFIRE_TOKEN="<your-write-token>"

Useful official links:

• Logfire Getting Started
• Create Write Tokens

Quick Start

Minimal configuration:

{
  "plugins": {
    "entries": {
      "openclaw-logfire": {
        "enabled": true,
        "config": {}
      }
    }
  }
}

Then restart OpenClaw. The plugin reads LOGFIRE_TOKEN at runtime and starts exporting spans.

If LOGFIRE_TOKEN is missing, the plugin disables itself and logs an error instead of starting half-configured.

What You See In Logfire

Once the plugin is configured, OpenClaw runs show up in Logfire as a trace timeline with alternating chat and tool phases, plus detailed per-span token and payload views.

Trace timeline

This is the high-level view of an agent run in Logfire:

Chat span details

You can also open an individual chat <model> span to inspect model, token, and captured input details:

Recommended Configuration

This example is based on a real OpenClaw setup and works well when you want rich debugging and full message capture. Replace placeholders before use.

{
  "plugins": {
    "entries": {
      "openclaw-logfire": {
        "enabled": true,
        "config": {
          // Prefer LOGFIRE_TOKEN via environment variable.
          // You can set "token" here, but env var is safer.
          "projectUrl": "https://logfire.pydantic.dev/<org>/<project>",

          // Map non-standard provider ids to OTel-friendly names.
          "providerNameMap": {
            "customprovider": "openai"
          },

          // Full payload capture for debugging.
          "captureMessageContent": true,
          "captureHistoryMessages": true,
          "historyMessagesMaxLength": 100000,
          "toolInputMaxLength": 100000,
          "toolOutputMaxLength": 16384,

          // Privacy and persistence switches.
          "redactSecrets": false,
          "saveHookLogs": false
        }
      }
    }
  }
}

Notes:

• projectUrl enables clickable trace links when enableTraceLinks is on.
• providerNameMap is useful when your OpenClaw provider id is not a standard OTel GenAI provider name.
• captureMessageContent: true also increases what can be captured from tool inputs and outputs. Review privacy expectations before enabling it.
• captureToolDefinitions is accepted by the schema, but it is currently reserved and does not change runtime behavior in 1.0.0.

What The Plugin Captures

Span tree

A typical trace looks like this:

invoke_agent main
  |- chat gpt-5.4
  |- running 2 tools
  |   |- execute_tool Read
  |   `- execute_tool Shell
  `- chat gpt-5.4

Root span

The root invoke_agent <agent> span stores:

• conversation id and channel metadata when available
• cumulative input, output, cache read, and cache write token counts
• tool count and overall duration
• reconstructed pydantic_ai.all_messages
• final_result when a final assistant result can be extracted

Chat spans

The plugin does not keep a single long-lived chat span open through the whole turn. Instead, it reconstructs one or more chat <model> spans from the final conversation shape emitted by llm_output.

That means:

• tool-call boundaries appear as separate chat phases
• final assistant content is more accurate when OpenClaw emits llm_output after lastAssistant is fully assembled
• if lastAssistant is incomplete, the plugin falls back to assistantTexts

Tool spans

Each tool call becomes execute_tool <tool>.

Depending on configuration, the span may include:

• gen_ai.tool.call.arguments
• gen_ai.tool.call.result
• output size and timing metadata

Tool calls from the same runId also produce a synthetic group span such as running 1 tool or running 3 tools.

Metrics

When enableMetrics is true, the plugin exports:

• gen_ai.client.token.usage
• gen_ai.client.operation.duration

Configuration Reference

All config lives under plugins.entries.openclaw-logfire.config.

Environment variable fallbacks

Variable	Used for	Notes
LOGFIRE_TOKEN	token	Required at runtime unless token is set directly
LOGFIRE_PROJECT_URL	projectUrl	Optional
LOGFIRE_ENVIRONMENT	environment	Defaults to development
LOGFIRE_PROVIDER_NAME	providerName	Optional

Active runtime options

These options are parsed by the config resolver and currently affect runtime behavior.

Key	Type	Default	Description
token	string	""	Logfire write token. Prefer LOGFIRE_TOKEN instead of committing it into config.
projectUrl	string	""	Project URL used to build clickable trace links.
region	"us" | "eu"	"us"	Selects the OTLP base endpoint.
environment	string	"development"	Deployment environment resource attribute.
serviceName	string	"openclaw-agent"	OTEL service.name.
providerName	string	""	Default provider name when OpenClaw metadata does not provide one.
providerNameMap	Record<string, string>	{}	Maps OpenClaw provider ids to OTEL provider names.
captureToolInput	boolean	true	Captures tool arguments.
captureToolOutput	boolean	false	Captures tool results.
toolInputMaxLength	integer	2048	Truncation limit for tool input capture.
toolOutputMaxLength	integer	512	Truncation limit for tool output capture and chat output capture.
captureMessageContent	boolean	false	Captures chat input, chat output, and system instructions. Privacy-sensitive.
captureHistoryMessages	boolean	false	Helps reconstruct multi-turn conversation history on the root span.
historyMessagesMaxLength	integer	16384	Truncation limit for serialized history messages.
redactSecrets	boolean	true	Redacts common API keys, bearer tokens, JWTs, passwords, and similar secrets before capture.
distributedTracing.enabled	boolean	false	Enables command-level trace propagation.
distributedTracing.injectIntoCommands	boolean	true	Injects traceparent into matching HTTP commands.
distributedTracing.urlPatterns	string[]	["*"]	URL glob patterns that are allowed for injection.
enableMetrics	boolean	true	Enables OTLP metric export.
metricsIntervalMs	integer	60000	Metric export interval in milliseconds.
enableTraceLinks	boolean	true	Logs clickable project trace links when projectUrl is configured.
saveHookLogs	boolean	false	Persists raw hook payloads to ~/.openclaw/logs/ for debugging.
resourceAttributes	Record<string, string>	{}	Additional OTEL resource attributes.
spanProcessorType	"batch" | "simple"	"batch"	Use simple when debugging exporter behavior.
batchConfig.maxQueueSize	integer	2048	Batch span processor queue size.
batchConfig.maxExportBatchSize	integer	512	Maximum spans per export batch.
batchConfig.scheduledDelayMs	integer	5000	Delay between batch exports.

Accepted but currently reserved options

These keys are accepted by the schema and config resolver, but they are not fully wired into runtime behavior in 1.0.0.

Key	Current status
captureStackTraces	Reserved. Current runtime does not branch on this flag.
captureToolDefinitions	Reserved. Accepted by schema, but not currently attached to spans.
distributedTracing.extractFromWebhooks	Reserved. Current implementation focuses on outbound command injection.
logLevel	Reserved. Accepted by config, but plugin logging does not currently change behavior from it.
useGenAiCompatibilityScope	Legacy compatibility field kept in config code, not surfaced in plugin schema.

Privacy And Safety Notes

• captureMessageContent: true is the highest-impact privacy switch.
• captureToolOutput: true can capture large or sensitive tool results.
• redactSecrets: true helps, but it is best-effort rather than a formal DLP guarantee.
• saveHookLogs: true writes raw payloads to local disk. Turn it off after debugging.
• Prefer LOGFIRE_TOKEN in the shell environment instead of committing tokens into openclaw.json.

Distributed Tracing

When enabled, the plugin injects W3C traceparent into matching command parameters before the tool runs.

{
  "plugins": {
    "entries": {
      "openclaw-logfire": {
        "enabled": true,
        "config": {
          "distributedTracing": {
            "enabled": true,
            "injectIntoCommands": true,
            "urlPatterns": [
              "https://api.example.com/*",
              "http://localhost:8000/*"
            ]
          }
        }
      }
    }
  }
}

Current scope:

• works for outbound command injection only
• targets HTTP-like commands such as curl, wget, http, and httpie
• respects distributedTracing.urlPatterns

Troubleshooting

No traces appear

Check these first:

1. LOGFIRE_TOKEN is set in the environment seen by OpenClaw.
2. The plugin entry key is exactly openclaw-logfire.
3. OpenClaw is at least 2026.2.1.
4. OpenClaw was restarted after config changes.
5. Your machine can reach the selected Logfire region endpoint.

Agent spans exist, but chat spans are incomplete

Make sure OpenClaw emits llm_output after the final lastAssistant object is fully assembled. The plugin reconstructs chat phases from the completed assistant payload.

Tool spans do not show failures clearly

Current OpenClaw hook payloads do not always expose tool-level error details at tool_result_persist, so failures may be reflected on the root agent span rather than the individual tool span.

I need raw hook payloads

Temporarily set:

{
  "plugins": {
    "entries": {
      "openclaw-logfire": {
        "enabled": true,
        "config": {
          "saveHookLogs": true
        }
      }
    }
  }
}

This writes hook payloads to ~/.openclaw/logs/.

Local Development

git clone https://github.com/chenbaiyujason/openclaw-logfire
cd openclaw-logfire
npm install
npm run build
npm run typecheck
npm test

To load the local checkout in OpenClaw, either symlink it into your extensions directory or add the repo path to plugins.load.paths.

ln -s "$(pwd)" ~/.openclaw/extensions/openclaw-logfire

Or:

{
  "plugins": {
    "load": {
      "paths": [
        "/absolute/path/to/openclaw-logfire"
      ]
    }
  }
}

Then export LOGFIRE_TOKEN, restart OpenClaw, and verify with:

openclaw plugins list

License

MIT