https://github.com/comet-ml/opik-openclaw
🦞 Official plugin for OpenClaw that exports agent traces to Opik. See and monitor agent behaviour, cost, tokens, errors and more.
https://github.com/comet-ml/opik-openclaw
clawdbot evaluation moltbot observability openclaw testing
Last synced: 27 days ago
JSON representation
🦞 Official plugin for OpenClaw that exports agent traces to Opik. See and monitor agent behaviour, cost, tokens, errors and more.
- Host: GitHub
- URL: https://github.com/comet-ml/opik-openclaw
- Owner: comet-ml
- License: apache-2.0
- Created: 2026-03-02T19:12:21.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-30T23:11:00.000Z (about 1 month ago)
- Last Synced: 2026-05-01T01:13:09.870Z (about 1 month ago)
- Topics: clawdbot, evaluation, moltbot, observability, openclaw, testing
- Language: TypeScript
- Homepage:
- Size: 607 KB
- Stars: 575
- Watchers: 4
- Forks: 65
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-openclaw - comet-ml/opik-openclaw - ml/opik-openclaw?style=social) - Official plugin for OpenClaw that exports agent traces to Opik. Monitor agent behaviour, cost, tokens, errors. (🎛️ Dashboards & Control Centers)
- awesome-openclaw-plugins - opik-openclaw - OpenClaw plugin that exports agent traces to Opik with LLM/tool/sub-agent spans plus usage and cost metadata. By [@comet-ml](https://github.com/comet-ml). `openclaw plugins install @opik/opik-openclaw` (Skills vs Plugins: What's the Difference? / Bundled Plugins)
- awesome-openclaw - opik-openclaw - level observability in Opik. See LLM spans, tool calls, sub-agent spans, usage, and cost metadata. Setup alerts and catch issues with your claw. | (Community Projects / Monitoring & Tools)
README
🔭 OpenClaw Opik Observability Plugin
Official plugin for OpenClaw that exports agent traces to
Opik for observability and monitoring.
[](./LICENSE)
[](https://www.npmjs.com/package/@opik/opik-openclaw)
## Why This Plugin
[Opik](https://github.com/comet-ml/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`
- npm `>=10`
### 1. Install the plugin in OpenClaw
```bash
openclaw plugins install clawhub:@opik/opik-openclaw
```
And for older version of OpenClaw `<2023.3.23` you can install the npm package using:
```bash
openclaw plugins install @opik/opik-openclaw
```
If the Gateway is already running, restart it after install.
### 2. Configure the plugin
```bash
openclaw opik configure
```
The setup wizard validates endpoint and credentials, then writes config under `plugins.entries.opik-openclaw`. If you choose Opik Cloud and do not have an account yet, the wizard now points you to the free signup flow before asking for an API key.
### 3. Check effective settings
```bash
openclaw opik status
```
### 4. Send a test message
```bash
openclaw gateway run
openclaw message send "hello from openclaw"
```
Then confirm traces in your Opik project.
## Configuration
### Recommended config shape
```json
{
"plugins": {
"entries": {
"opik-openclaw": {
"enabled": true,
"hooks": {
"allowConversationAccess": 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:
```json
{
"plugins": {
"allow": ["opik-openclaw"]
}
}
```
Because Opik traces LLM prompts, responses, tools, and agent finalization events, non-bundled installs also need explicit conversation hook access:
```json
{
"plugins": {
"entries": {
"opik-openclaw": {
"hooks": {
"allowConversationAccess": true
}
}
}
}
}
```
### 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 `>=10`
```bash
npm ci
npm run build
npm run lint
npm run typecheck
npm run test
npm run smoke
```
### Packaging
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`; `openclaw.runtimeExtensions`
points at `./dist/index.js`. ClawHub also requires explicit
`openclaw.compat.pluginApi` and `openclaw.build.openclawVersion` metadata.
`npm pack` and `npm publish` run `npm run build` through `prepack`, and
`npm run pack:check` verifies the tarball contract.
Pull requests also dry-run the ClawHub package publish workflow, and GitHub
releases publish the validated package to both npm and ClawHub.
Optional live gateway E2E:
```bash
npm run test:live
```
Notes:
- uses an isolated `.artifacts/live-e2e//home/.openclaw` so it does not touch your normal OpenClaw config
- `OPIK_API_KEY`, `OPIK_URL_OVERRIDE`, `OPIK_PROJECT_NAME`, and `OPIK_WORKSPACE` win if set in env
- otherwise it reuses `~/.openclaw/openclaw.json -> plugins.entries.opik-openclaw.config` for `apiUrl` / `apiKey` / project / workspace
- set `OPENCLAW_LIVE_USE_HOST_OPIK_CONFIG=0` to disable reading host plugin config and require explicit env-only Opik settings
- still requires `OPENAI_API_KEY` in env for the real model call
- packs and installs the current plugin build into a fresh OpenClaw home
- falls back to `npx openclaw@${OPENCLAW_LIVE_OPENCLAW_VERSION:-latest}` when `openclaw` is not already on your `PATH`
- override the live model with `OPENCLAW_LIVE_MODEL` if `gpt-4o-mini` is not what you want to exercise
## Contributing
Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
## License
[Apache-2.0](./LICENSE)