opik-openclaw: tracing OpenClaw agents into Opik

The gap opik-openclaw fills inside an OpenClaw gateway

An OpenClaw agent run is not one request. It is an LLM call, then a tool call, then another LLM call that reacts to the tool output, and possibly a sub-agent spawned to handle part of the work. Once the run ends, the gateway keeps no durable record you can open later and compare against the run before it. opik-openclaw exists to close that gap. It is the official plugin from Comet that hooks into OpenClaw and writes each of those steps to Opik as spans under a single trace.

The intended reader is someone already running OpenClaw who wants cost, token usage, tool inputs and outputs, and errors in a queryable place. The README lists exactly what gets exported: LLM request and response spans, sub-agent request and response spans, tool call spans with inputs, outputs and errors, run-level finalize metadata, and usage and cost metadata. That list is the whole product. There is no evaluation harness here, no prompt management, no dashboard of its own; Opik is the destination and the plugin is the pipe.

How OpenClaw events become Opik spans

The mechanism is a fixed event mapping, documented in a table in the README, and it is worth reading closely because it tells you what you will and will not see in Opik.

An llm_input event starts a trace and an llm span. The matching llm_output writes usage and output onto that span and closes it. Tool calls are bracketed the same way: before_tool_call starts a tool span and captures the tool name and input, after_tool_call attaches output, error and duration. Sub-agents get their own three-event lifecycle, subagent_spawning starts a subagent span on the requester's trace, subagent_spawned enriches it with run metadata, and subagent_ended finalizes it with outcome or error. Finally agent_end closes any pending spans and finalizes the trace.

Two design consequences follow. First, the trace boundary is the agent run, so a long run with many tool calls produces one trace with many child spans, which is what you want for cost attribution. Second, the plugin is stateful across events: it holds open spans between the start and end events. The README exposes staleTraceCleanupEnabled, staleTraceTimeoutMs (300000) and staleSweepIntervalMs (60000) for exactly this reason. A run that never emits its end event would otherwise leave a span open forever, and the sweep is the fallback that closes it.

Installing opik-openclaw and sending a first traced message

The plugin runs inside the OpenClaw Gateway process. The README is explicit that if your gateway is remote, you install and configure the plugin on that host, not on your laptop. Prerequisites are OpenClaw >=2026.3.2, Node.js >=22.12.0 and npm >=10.

Install through OpenClaw's plugin command:

openclaw plugins install clawhub:@opik/opik-openclaw

The README also gives an npm-package form, openclaw plugins install @opik/opik-openclaw, for older OpenClaw versions. If the Gateway is already running, restart it after install.

Then run the setup wizard. The README states it validates endpoint and credentials and writes config under plugins.entries.opik-openclaw, and that if you pick Opik Cloud without an account it points you to the signup flow before asking for an API key:

openclaw opik configure
openclaw opik status

The status command prints the effective Opik configuration, which is the fastest way to catch a wizard run that landed in the wrong project or workspace.

Finally, start the gateway and send yourself a message:

openclaw gateway run
openclaw message send "hello from openclaw"

What you should see is a trace in the Opik project you configured, with an llm span for the request. If the project stays empty, check status before anything else.

Config shape, environment fallbacks and the trust allowlist

The recommended configuration nests everything under plugins.entries.opik-openclaw, with enabled and hooks at the entry level and the Opik settings under config. The base keys are enabled, apiKey, apiUrl, projectName and workspaceName. The README's example uses apiUrl https://www.comet.com/opik/api and projectName openclaw.

The advanced keys are where the operational behaviour lives: tags, toolResultPersistSanitizeEnabled, staleTraceCleanupEnabled, staleTraceTimeoutMs, staleSweepIntervalMs, flushRetryCount and flushRetryBaseDelayMs. The flush retry pair matters if your Opik endpoint is remote; the default of 2 retries with a 250 ms base delay is modest, and a flaky network will drop spans rather than buffer them indefinitely.

Four environment variables act as fallbacks: OPIK_API_KEY, OPIK_URL_OVERRIDE, OPIK_PROJECT_NAME and OPIK_WORKSPACE. The .env.example file also shows a self-hosted endpoint shape, OPIK_URL_OVERRIDE="http://localhost:5173/api", and notes that the API key is optional for unauthenticated local deployments.

Two OpenClaw-side settings are easy to miss. The README recommends pinning the plugin in plugins.allow, since OpenClaw warns when that list is empty and a community plugin is discovered. And because the plugin traces prompts, responses, tools and finalization events, non-bundled installs need hooks.allowConversationAccess set to true. Without it, expect a plugin that loads and then exports nothing useful.

What opik-openclaw does not cover

The README names one limitation outright: no OpenClaw core changes are included in this repository, and the plugin relies on native hooks within the OpenClaw ecosystem. That is the honest version of the trade-off. The plugin is a consumer of an event surface it does not control. If an OpenClaw release renames an event, changes a payload shape, or stops emitting one of the eight mapped events, the corresponding span silently stops appearing. There is no compatibility shim in this repository to absorb that.

The peer dependency reflects the same coupling. openclaw is declared as a peer at >=2026.3.2 and marked optional, so npm will not stop you from installing the plugin against an OpenClaw that does not emit the hooks it needs. The README's own install section hedges further, offering the npm form for older OpenClaw versions, which suggests the ClawHub path and the npm path are not equivalent across versions.

Two narrower points. Transcript sanitization is off by default: toolResultPersistSanitizeEnabled is disabled, and when enabled the plugin rewrites local image refs in persisted tool transcript messages via tool_result_persist. If your tool results contain local image paths and you care what lands in Opik, that default is worth a deliberate decision rather than an inherited one. And the plugin is the wrong tool if you are not on OpenClaw at all, or if you want tracing that spans several agent frameworks under one vendor-neutral schema. This is a single-framework bridge.

opik-openclaw against wiring the Opik SDK yourself

The real alternative is not another plugin. It is importing the opik package, which this project depends on at ^2.0.9, directly into your own OpenClaw integration and emitting spans from your own hook handlers.

That path buys you control. You decide which events become spans, you can attach your own metadata, you can batch or sample, and you are not bound to the eight-event mapping or to the plugin's stale-trace sweep. It also means you own the maintenance: when OpenClaw's event surface moves, the fix is yours to write, and you will be debugging your handler rather than reading a changelog.

opik-openclaw's value is that the mapping is already decided and the wizard handles credentials. The event table in the README is the specification you would otherwise have to reverse-engineer from OpenClaw's hook documentation. If your needs match that table, the plugin is less work. If they do not, no amount of configuration will reshape it, because the mapping is compiled into the hook modules listed in the package files (src/service/hooks/llm.ts, tool.ts, subagent.ts).

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-08-27. Releases are versioned and frequent enough to show a live line: v0.2.15 on 2026-05-06, v0.2.16 on 2026-05-21, v0.2.17 on 2026-05-22. Note that the release cadence and the push cadence are not the same thing; the release tags stop in May while commits continued into August.

The licence is Apache-2.0, declared in both the LICENSE file and the package.json license field. That is a permissive licence with an explicit patent grant, and it imposes no copyleft obligation on your own code. It does not, however, say anything about the hosted Opik Cloud service, which is governed by Comet's terms rather than by this repository. If you point apiUrl at a self-hosted Opik instead, the plugin's licence is the only licence in play on the client side. This is a description of what the files state, not legal advice; check your own obligations.

Upgrade cost is dominated by the OpenClaw peer range, not by the plugin's own version number. The package publishes built JavaScript for installed OpenClaw runtime loads while keeping TypeScript source metadata for development and older OpenClaw fallback loads: openclaw.extensions points at ./index.ts and openclaw.runtimeExtensions points at ./dist/index.js. That dual-loading arrangement is what makes the older-version fallback work, and it is also the part most likely to need attention when OpenClaw's loader changes. The repository guards this with npm run pack:check, which verifies the tarball contract, and prepack runs the build on npm pack and npm publish.

Editorial conclusion

Adopt opik-openclaw if you already run OpenClaw and want per-run LLM, tool and sub-agent spans in Opik without writing your own hook handler; the install is two commands and the config lives under plugins.entries.opik-openclaw. Skip it if you are not on OpenClaw, if your gateway runs on a host you cannot install into, or if you need tracing to survive OpenClaw core changes, since the repository ships no core changes and depends on native hooks. Before rolling it out, verify three things on your own gateway: that OpenClaw reports at least 2026.3.2, that openclaw opik status prints the project and workspace you expect, and that a single openclaw message send produces one trace in that project.

Frequently asked questions

Official sources

1. comet-ml/opik-openclaw on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases