🔭 OpenClaw Opik Observability Plugin

Official plugin for OpenClaw that exports agent traces to
Opik for observability and monitoring.

Why This Plugin

Opik is a leading open-source LLM and agent observability, tracing, evaluation and optimization platform. @opik/opik-openclaw adds native Opik tracing for OpenClaw runs:

• LLM request/response spans
• Sub-agent request/response spans
• Tool call spans with inputs, outputs, and errors
• Run-level finalize metadata
• Usage and cost metadata

The plugin runs inside the OpenClaw Gateway process. If your gateway is remote, install and configure the plugin on that host.

Install and first run

Prerequisites:

• OpenClaw >=2026.3.2
• Node.js >=22.12.0

1. Install the plugin in OpenClaw

openclaw plugins install @opik/opik-openclaw

If the Gateway is already running, restart it after install.

2. Configure the plugin

openclaw opik configure

The setup wizard validates endpoint and credentials, then writes config under plugins.entries.opik-openclaw.

3. Check effective settings

openclaw opik status

4. Send a test message

openclaw gateway run
openclaw message send "hello from openclaw"

Then confirm traces in your Opik project.

Configuration

Recommended config shape

{
  "plugins": {
    "entries": {
      "opik-openclaw": {
        "enabled": true,
        "config": {
          // base configuration
          "enabled": true,
          "apiKey": "your-api-key",
          "apiUrl": "https://www.comet.com/opik/api",
          "projectName": "openclaw",
          "workspaceName": "default",
          // optional advanced configuration
          "tags": ["openclaw"],
          "toolResultPersistSanitizeEnabled": false,
          "staleTraceCleanupEnabled": true,
          "staleTraceTimeoutMs": 300000,
          "staleSweepIntervalMs": 60000,
          "flushRetryCount": 2,
          "flushRetryBaseDelayMs": 250
        }
      }
    }
  }
}

Plugin trust allowlist

OpenClaw warns when plugins.allow is empty and a community plugin is discovered. Pin trusted plugins explicitly:

{
  "plugins": {
    "allow": ["opik-openclaw"]
  }
}

Environment fallbacks

• OPIK_API_KEY
• OPIK_URL_OVERRIDE
• OPIK_PROJECT_NAME
• OPIK_WORKSPACE

Transcript safety default

toolResultPersistSanitizeEnabled is disabled by default. When enabled, the plugin rewrites local image refs in persisted tool transcript messages via tool_result_persist.

CLI commands

Command	Description
openclaw plugins install @opik/opik-openclaw	Install plugin package
openclaw opik configure	Interactive setup wizard
openclaw opik status	Print effective Opik configuration

Event mapping

OpenClaw event	Opik entity	Notes
llm_input	trace + llm span	starts trace and llm span
llm_output	llm span update/end	writes usage/output and closes span
before_tool_call	tool span start	captures tool name + input
after_tool_call	tool span update/end	captures output/error + duration
subagent_spawning	subagent span start	starts subagent lifecycle span on requester trace
subagent_spawned	subagent span update	enriches subagent span with run metadata
subagent_ended	subagent span update/end	finalizes subagent span with outcome/error
agent_end	trace finalize	closes pending spans and trace

Known limitation

No OpenClaw core changes are included in this repository and relies on native hooks within the OpenClaw ecosystem.

Development

Prerequisites:

• Node.js >=22.12.0
• npm >=11

npm ci
npm run lint
npm run typecheck
npm run test
npm run smoke

Contributing

Read CONTRIBUTING.md before opening a PR.

License

Apache-2.0