> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-hivemind-launch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw plugin

> Track OpenClaw agent sessions in W&B Weave for observability and debugging.

<Note>
  Weave for Agents is in public preview. Features, APIs, and the Agents view UI may change before general availability.
</Note>

The Weave OpenClaw plugin automatically traces every agent session running through the OpenClaw gateway and sends the structured data to W\&B Weave. Every turn, model call, and tool execution is logged with no application code changes required. Use these traces to debug sessions, audit tool usage, and monitor cost and latency across runs.

<Warning>
  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.

  PII scrubbing and sensitive-data redaction aren't implemented by the plugin. 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.
</Warning>

## Prerequisites

* [Node.js](https://nodejs.org/) v22 or later.
* [OpenClaw](https://openclaw.dev) >= 2026.4.25 with the plugin API.
* A W\&B account and [API key](https://wandb.ai/authorize).
* A Weave project (`[YOUR-TEAM]/[YOUR-PROJECT]`) to receive traces.

## Install the plugin

<Steps>
  <Step title="Install the package:">
    ```bash lines theme={null}
    pnpm add weave-openclaw
    ```

    The plugin is loaded by the OpenClaw gateway through its config. You don't import it from application code.
  </Step>

  <Step title="Add the plugin to your gateway config:">
    The default config location is `~/.openclaw/openclaw.json` (JSON5, so comments and trailing commas are allowed). Run `openclaw onboard` to scaffold one if you don't have it yet.
    Update `[YOUR-TEAM]` and `[YOUR-PROJECT]` for your project.

    ```json lines theme={null}
    {
      diagnostics: { enabled: true },
      plugins: {
        allow: ["weave"],
        entries: {
          weave: {
            enabled: true,
            config: { entity: "YOUR-TEAM", project: "YOUR-PROJECT" },
            hooks: { allowConversationAccess: true },
          },
        },
      },
    }
    ```

    As shown in the example config, your gateway config must include these two settings:

    * Set **`diagnostics.enabled`** to **`true`** so OpenClaw emits the diagnostic events the plugin consumes.
    * Set **`hooks.allowConversationAccess`** to **`true`** so OpenClaw runs the content-bearing hooks (`llm_input`, `llm_output`, `agent_end`) and spans include input/output text and tool arguments and results.
  </Step>

  <Step title="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 will appear at `wandb.ai/[YOUR-TEAM]/[YOUR-PROJECT]` within a few seconds of your first agent run.
  </Step>
</Steps>

## View OpenClaw traces in Weave

After running at least one agent session, open your project in the Weave UI:

1. Navigate to [https://wandb.ai](https://wandb.ai) and select your project.
2. In the sidebar, select **Agents** for the multi-turn chat view and per-agent version grouping, or select **Traces** for the raw span tree.
3. Select a conversation to inspect the full session tree.

For more on the Agents view, see [View agent activity](/weave/guides/tracking/view-agent-activity).

The plugin emits spans per the [OTel GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/):

| 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:

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

```json lines theme={null}
{
  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: 5000,
        },
        hooks: { allowConversationAccess: true },
      },
    },
  },
}
```

`captureContent` is `true` by default. When `captureContent` is `true`, input and output messages, tool arguments, and tool results are also emitted following the `gen_ai.input.messages` / `gen_ai.output.messages` payload shape. Subagents, compaction events, loop detection, retry attempts, and context sizing are stamped 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](https://github.com/wandb/weave/tree/master/sdks/node). 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

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

1. Run `/weave status`. If lifecycle is `disabled`, `config-error`, or `not-started`, the plugin did not activate. Check the gateway log for `weave: config.entity is required`, `weave: configuration error`, or `[weave] incompatible plugin SDK`.
2. Confirm `diagnostics.enabled: true` in the gateway config.
3. Confirm the entity and project match the URL slug of the Weave project you're inspecting. `/weave status` should print `project=<entity>/<project>`.
4. 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:

```text theme={null}
[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/usage data come through diagnostic events, not hooks, so those keep working even without the gate flipped.

### Errors sending traces to Weave

If the plugin is active and spans are being generated but not appearing in Weave, check the gateway log for an export error and match it against the table below.

| Symptom                         | Most likely cause                | Fix                                                                                                                                              |
| ------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| 401 / 403 from `trace.wandb.ai` | Invalid or scope-limited API key | Verify the key is current and the team owns the entity/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 / DNS error  | DNS, proxy, or firewall          | Confirm the gateway host can reach `trace.wandb.ai` (cloud) or your install host (dedicated) on 443.                                             |