OpenClaw plugin

The Weave OpenClaw plugin automatically traces every agent session running through the OpenClaw gateway and sends the structured data to W&B Weave. The plugin logs every turn, model call, and tool execution without requiring any application code changes. Use these traces to debug sessions, audit tool usage, and monitor cost and latency across runs. This guide is for OpenClaw gateway operators who want to enable Weave tracing for the agents running behind the gateway. It walks you through how to install the plugin, configure it, view the resulting traces, and troubleshoot common issues.

This plugin sends OpenClaw session data to Weave. That data can include user prompts, model responses, tool inputs and outputs, tool results, and conversation history.The plugin doesn’t implement personally identifiable information (PII) scrubbing or sensitive-data redaction. If you need to suppress content capture, set captureContent: false in the plugin config. If you can’t send this data to Weave under your security or compliance requirements, don’t install this plugin.

Prerequisites

Node.js v22.14 or later.
OpenClaw 2026.4.25 or later with the plugin API.
A W&B account and API key.
A Weave project ([YOUR-TEAM]/[YOUR-PROJECT]) to receive traces.

Install the plugin

Complete the following steps to install the plugin, register it with the OpenClaw gateway, and confirm that traces reach your Weave project.

Install the package

openclaw plugins install weave-openclaw

Use the full name weave-openclaw (weave on its own is the W&B SDK, not this plugin). The OpenClaw gateway loads the plugin through its config. You don’t import it from application code.

Add the plugin to your gateway config

The default config location is ~/.openclaw/openclaw.json (JSON5, which allows comments and trailing commas). Run openclaw onboard to scaffold one if you don’t have it yet. Update [YOUR-TEAM] and [YOUR-PROJECT] for your project.

{
  plugins: {
    allow: ["weave"],
    entries: {
      weave: {
        enabled: true,
        config: { entity: "YOUR-TEAM", project: "YOUR-PROJECT" },
        hooks: { allowConversationAccess: true },
      },
    },
  },
}

Set hooks.allowConversationAccess to true so OpenClaw runs the content-bearing hooks (llm_input, llm_output, agent_end) and spans include input and output text, tool arguments, and tool results.diagnostics.enabled is on by default. Only set it explicitly if you need to turn it off.

Restart the gateway and verify

Restart the OpenClaw gateway, then run /weave status in any OpenClaw chat surface to confirm the plugin is active. Traces appear at https://wandb.ai/[YOUR-TEAM]/[YOUR-PROJECT] within a few seconds of your first agent run.

View OpenClaw traces in Weave

Once the plugin is active, each agent session produces a trace you can inspect in the Weave UI. After running at least one agent session, open your project in the Weave UI:

Navigate to https://wandb.ai and select your project.
In the sidebar menu, select Agents.
Select the Conversations tab to view all agent conversations saved for your project.
Select a conversation to inspect the full conversation tree.

For more information about the Agents view, see View agent activity. The plugin emits spans per the OpenTelemetry (OTel) GenAI semantic conventions:

Span	Emitted on	Key attributes
`invoke_agent <agent>`	Per agent run	`gen_ai.agent.name`, `gen_ai.conversation.id`, cumulative cost, token usage
`chat <model>`	Per model call	`gen_ai.request.model`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`
`execute_tool <tool>`	Per tool execution	`gen_ai.tool.name`, `gen_ai.tool.call.id`

Configuration reference

This section is the full configuration reference for the weave plugin entry in openclaw.json. The apiKey field supports four auth sources, resolved in this order:

A SecretRef object with source: "env" or source: "file" (see line 10 in the following example).
A literal apiKey string (supported but not recommended).
The WANDB_API_KEY environment variable.
A ~/.netrc entry for the Weave host, populated by wandb login.

{
  plugins: {
    entries: {
      weave: {
        enabled: true,
        config: {
          entity: "YOUR-TEAM",
          project: "YOUR-PROJECT",
          // Reads WANDB_API_KEY from env if apiKey is omitted.
          // SecretRef supports source: "env" or "file":
          //   { source: "env",  provider: "default", id: "WANDB_API_KEY" }
          //   { source: "file", provider: "default", id: "/run/secrets/wandb" }
          // Plain string is supported but discouraged.
          apiKey: { source: "env", provider: "default", id: "WANDB_API_KEY" },
          serviceName: "openclaw-agent",
          // Optional, improves Agents tab grouping.
          agentName: "my-agent",
          agentVersion: "v1.0",
          agentDescription: "What my agent does.",
          // ON by default. Set to false for a hard off (compliance or
          // retention policy). The plugin does not redact captured
          // strings; scrub upstream if needed.
          captureContent: true,
          flushIntervalMs: 1000,
        },
        hooks: { allowConversationAccess: true },
      },
    },
  },
}

captureContent is true by default. When captureContent is true, the plugin also emits input and output messages, tool arguments, and tool results following the gen_ai.input.messages and gen_ai.output.messages payload shape. The plugin stamps subagents, compaction events, loop detection, retry attempts, and context sizing as additional attributes and span events. Set captureContent to false to turn off capture for compliance or retention policies.

W&B Dedicated Cloud or self-hosted instances

The plugin delegates endpoint and auth to the Weave Node SDK. It reads the following environment variables using the same conventions as the Weave Python and Node SDKs:

Variable	Description
`WANDB_BASE_URL`	W&B API base URL. Default: `https://api.wandb.ai`. Set this for Dedicated Cloud or self-hosted installs.
`WF_TRACE_SERVER_URL`	Full trace-server URL override. Use for self-managed or proxied setups.

Troubleshooting

If traces aren’t reaching Weave or content fields are empty, use the following sections to diagnose the most common causes. The gateway log is the terminal output from the process running openclaw, or your process manager’s log stream if you daemonized it.

Plugin loaded but no spans show up

Run /weave status. If lifecycle is disabled, config-error, or not-started, the plugin didn’t activate. Check the gateway log for weave: config.entity is required, weave: configuration error, or [weave] incompatible plugin SDK.
Check you haven’t set diagnostics.enabled: false in the gateway config. This field should be true.
Confirm the entity and project match the URL slug of the Weave project you’re inspecting. /weave status should print project=[YOUR-TEAM]/[YOUR-PROJECT].
Confirm the auth source. /weave status should print auth=.... If it says WANDB_API_KEY env but you set the key in a different environment variable, the plugin is reading the wrong key.

Spans land but input/output text is empty

Look in the gateway log for:

[plugins] typed hook "llm_input"  blocked because non-bundled plugins must set
                                  plugins.entries.weave.hooks.allowConversationAccess=true
[plugins] typed hook "llm_output" blocked ...
[plugins] typed hook "agent_end"  blocked ...

OpenClaw gates content-bearing hooks behind an operator opt-in. Set plugins.entries.weave.hooks.allowConversationAccess: true in your config and restart the gateway. Span structure and cost and usage data come through diagnostic events, not hooks, so those keep working even when allowConversationAccess is false.

Errors sending traces to Weave

If the plugin is active and generating spans but they don’t appear in Weave, check the gateway log for an export error and match it against the following table.

Symptom	Most likely cause	Fix
`401` or `403` from `trace.wandb.ai`	Invalid or scope-limited API key	Verify the key is current and the team owns the entity and project. `wandb login` refreshes `~/.netrc`.
`404` from the agents endpoint	Wrong base or trace-server URL	For dedicated installs, set `WANDB_BASE_URL` to your install host. For self-managed or proxy, set `WF_TRACE_SERVER_URL` to the trace-server URL.
Connection refused or DNS error	DNS, proxy, or firewall	Confirm the gateway host can reach `trace.wandb.ai` (cloud) or your install host (dedicated) on `443`.

Get Started

Guides

Cookbooks

Reference

Details & Support

Prerequisites

Install the plugin

View OpenClaw traces in Weave

Configuration reference

W&B Dedicated Cloud or self-hosted instances

Troubleshooting

Plugin loaded but no spans show up

Spans land but input/output text is empty

Errors sending traces to Weave

​Prerequisites

​Install the plugin

​View OpenClaw traces in Weave

​Configuration reference

​W&B Dedicated Cloud or self-hosted instances

​Troubleshooting

​Plugin loaded but no spans show up

​Spans land but input/output text is empty

​Errors sending traces to Weave

Prerequisites

Install the plugin

View OpenClaw traces in Weave

Configuration reference

W&B Dedicated Cloud or self-hosted instances

Troubleshooting

Plugin loaded but no spans show up

Spans land but input/output text is empty

Errors sending traces to Weave