opik-openclaw: exporting OpenClaw agent traces to Opik
🦞 Official plugin for OpenClaw that exports agent traces to Opik. See and monitor agent behaviour, cost, tokens, errors and more.
At a glance
- What is it?
- @opik/opik-openclaw is the official OpenClaw plugin that maps gateway lifecycle hooks onto Opik traces, spans and cost metadata. It is a thin adapter, so its value and its limits both come from the hooks OpenClaw already exposes.
- Who is it for?
- Adopt opik-openclaw if you already run an OpenClaw gateway and want its runs visible in Opik without patching OpenClaw core; the install is one command and the config lives under plugins.entries.opik-openclaw. Do not adopt it if you need tracing for a framework other than OpenClaw, or if you cannot grant conversation hook access to a non-bundled plugin.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap this plugin fills for OpenClaw operators
An OpenClaw gateway runs agents that call models, call tools, and spawn sub-agents. The README describes the plugin as adding native Opik tracing for those runs, covering LLM request and response spans, sub-agent spans, tool call spans with inputs, outputs and errors, run-level finalize metadata, and usage and cost metadata. That list is the product. Without a plugin like this, an operator watching a gateway sees whatever OpenClaw itself surfaces; the trace tree, the per-tool duration and the token accounting have to be reconstructed elsewhere. The intended user is the person who already runs OpenClaw and wants the same run visible in Opik, most likely because Opik is already the place their other LLM work is evaluated. It is not a general agent framework, and it is not a standalone tracer you point at arbitrary code.
How OpenClaw events become Opik spans
The mechanism is event mapping, not instrumentation of your application code. The plugin runs inside the OpenClaw Gateway process, and the README states plainly that if your gateway is remote, you install and configure the plugin on that host. The mapping table is the architecture: llm_input starts a trace and an llm span; llm_output updates that span with usage and output and closes it; before_tool_call starts a tool span capturing tool name and input; after_tool_call ends it with output, error and duration; subagent_spawning starts a subagent lifecycle span on the requester trace; subagent_spawned enriches it with run metadata; subagent_ended finalizes it with outcome or error; agent_end closes pending spans and the trace. Two details matter more than the table. First, sub-agent spans attach to the requester trace, so the parent-child relationship is expressed through the trace rather than through a separate service. Second, there is a stale trace cleanup path with staleTraceCleanupEnabled, staleTraceTimeoutMs and staleSweepIntervalMs, which implies the plugin expects runs that never reach agent_end and needs a sweep to close them.
Install and configuration commands
Prerequisites are OpenClaw >=2026.3.2, Node.js >=22.12.0 and npm >=10. Install with openclaw plugins install clawhub:@opik/opik-openclaw. For OpenClaw versions below the stated threshold the README gives an npm fallback: openclaw plugins install @opik/opik-openclaw. If the gateway is already running, restart it after install. Then run openclaw opik configure, which the README says validates endpoint and credentials and writes config under plugins.entries.opik-openclaw. Check the result with openclaw opik status. The recommended config block sets enabled, apiKey, apiUrl, projectName and workspaceName, plus optional tags, toolResultPersistSanitizeEnabled, the three stale-trace keys, and flushRetryCount with flushRetryBaseDelayMs. Environment fallbacks exist for OPIK_API_KEY, OPIK_URL_OVERRIDE, OPIK_PROJECT_NAME and OPIK_WORKSPACE. Two non-obvious requirements sit outside the config block: plugins.allow should pin opik-openclaw to silence the warning about an empty allowlist and a discovered community plugin, and because the plugin traces prompts, responses, tools and finalization events, non-bundled installs need hooks.allowConversationAccess set to true.
The conversation access grant is the real adoption decision
Most of this configuration is routine. The hooks.allowConversationAccess flag is not. The README frames it as a consequence of what the plugin traces: prompts, responses, tool payloads and agent finalization events. That means the plugin is reading conversation content, and OpenClaw requires you to say so explicitly for a non-bundled install. Teams that treat model prompts as sensitive data have to weigh that grant against the observability they get, and the decision belongs to whoever owns the gateway host, not to whoever wants the dashboard. The related setting toolResultPersistSanitizeEnabled is disabled by default, and the README says that when enabled the plugin rewrites local image refs in persisted tool transcript messages via tool_result_persist. Read that as a narrow, opt-in redaction step rather than a general scrubbing layer. If your tool results carry secrets in text, nothing in this material suggests the plugin removes them before export.
Where opik-openclaw is the wrong tool
The repository ships no OpenClaw core changes and depends on native hooks in the OpenClaw ecosystem; the README lists this as the known limitation. The consequence is that anything OpenClaw does not emit as a hook cannot be traced by this plugin, and a change in hook semantics upstream is a change in what you see. Two practical failure modes follow. A run that never reaches agent_end leaves spans open until the stale sweep runs, which is why staleTraceCleanupEnabled defaults to true with a five-minute timeout and a one-minute sweep interval; a short-lived process that exits before a flush completes is a different problem, and the flushRetryCount and flushRetryBaseDelayMs keys exist precisely because exports can fail and be retried. Second, this is OpenClaw-specific. If your agents run under a different framework, or if you want one tracing layer across several agent runtimes, this plugin does not provide it. It is also the wrong choice if you cannot install on the gateway host, since the plugin runs in that process and a remote gateway needs the install there.
How this differs from instrumenting the agent yourself
The obvious alternative is the Opik SDK for your language, wrapped around your own agent loop. That approach gives you control over span boundaries: you decide what a trace is, what counts as a tool span, and which fields are attached. It also means you own every call site, and you own the mapping from your agent's lifecycle to Opik's entities. opik-openclaw inverts that trade. You write no tracing code and you get a fixed mapping, the one in the README's event table, with the span names and boundaries that mapping implies. You cannot easily add a custom span for something OpenClaw does not emit as a hook, and you inherit the plugin's decisions about when a trace starts and ends. The choice is between a fixed mapping maintained upstream and a hand-written one you maintain. The plugin wins when OpenClaw is your runtime and the default mapping is close enough; the SDK wins when you need span shapes the hook set cannot express.
Packaging, releases and what maintenance looks like
The project is Apache-2.0, so you can read, modify and redistribute it under those terms; that is a statement about the licence, not legal advice, and if you fork it for internal use the notice requirements still apply. Maintenance cost is mostly version tracking. The README documents a packaging split: openclaw.extensions points at ./index.ts while openclaw.runtimeExtensions points at ./dist/index.js, so the package publishes built JavaScript for installed runtime loads and keeps TypeScript source metadata for development and older OpenClaw fallback loads. ClawHub requires explicit openclaw.compat.pluginApi and openclaw.build.openclawVersion metadata, npm pack and npm publish run the build through prepack, and npm run pack:check verifies the tarball contract. For an operator, the practical implication is that the plugin's declared OpenClaw compatibility is part of the artifact, and a gateway upgrade can move you outside it. The release cadence visible in the material is frequent patch-level bumps, which suggests active maintenance but also means you should pin a version rather than track the latest tag on a production gateway. The live end-to-end test, npm run test:live, uses an isolated .artifacts/live-e2e/<run-id>/home/.openclaw directory so it does not touch your normal OpenClaw config, and it reads OPIK_API_KEY, OPIK_URL_OVERRIDE, OPIK_PROJECT_NAME and OPIK_WORKSPACE from the environment first, falling back to ~/.openclaw/openclaw.json unless OPENCLAW_LIVE_USE_HOST_OPIK_CONFIG=0 is set.
Editorial conclusion
Adopt opik-openclaw if you already run an OpenClaw gateway and want its runs visible in Opik without patching OpenClaw core; the install is one command and the config lives under plugins.entries.opik-openclaw. Do not adopt it if you need tracing for a framework other than OpenClaw, or if you cannot grant conversation hook access to a non-bundled plugin. Verify first that your gateway meets OpenClaw >=2026.3.2 and Node.js >=22.12.0, then run openclaw opik status and send one test message before trusting the trace shape.
Community notes