How do I install the Opik Openclaw Observability skill?

Run npx skillmds@latest add aradotso/opik-openclaw-observability in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Opik Openclaw Observability skill do?

Add Opik LLM observability and tracing to OpenClaw AI agents for monitoring prompts, responses, tool calls, and agent behavior. It is listed under AI & ML on SkillMD.

Is Opik Openclaw Observability safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Opik Openclaw Observability?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Opik Openclaw Observability free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Opik Openclaw Observability?

aradotso (@aradotso) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Opik Openclaw Observability by aradotso

Name: Opik Openclaw Observability
Author: aradotso

opik-openclaw-observability

Skill by ara.so — Hermes Skills collection.

What It Does

@opik/opik-openclaw is the official plugin that adds native Opik observability to OpenClaw AI agents. It automatically traces:

LLM request/response spans with prompts, completions, and usage metadata
Sub-agent spawning and lifecycle events
Tool call spans with inputs, outputs, errors, and duration
Run-level finalization metadata
Cost and token usage tracking

All traces export to Opik, the open-source LLM observability platform by Comet, for visualization, debugging, and evaluation.

Installation

Prerequisites

OpenClaw >=2026.3.2
Node.js >=22.12.0
npm >=10

Install via OpenClaw CLI

For OpenClaw >= 2026.3.23:

openclaw plugins install clawhub:@opik/opik-openclaw

For older versions:

openclaw plugins install @opik/opik-openclaw

Restart the OpenClaw Gateway after installation.

Configuration

Interactive Setup

Run the configuration wizard to set up Opik credentials and endpoint:

openclaw opik configure

The wizard will:

Prompt for Opik Cloud or self-hosted endpoint
Validate API credentials
Set project name and workspace
Write config to openclaw.json

Check Configuration

Verify your settings:

openclaw opik status

Manual Configuration

Add to your openclaw.json:

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

Environment Variables

Use environment variables for sensitive credentials:

export OPIK_API_KEY="your-api-key"
export OPIK_URL_OVERRIDE="https://www.comet.com/opik/api"
export OPIK_PROJECT_NAME="my-openclaw-project"
export OPIK_WORKSPACE="my-team"

Environment variables take precedence over config file settings.

Key CLI Commands

Command	Description
`openclaw plugins install @opik/opik-openclaw`	Install the plugin
`openclaw opik configure`	Interactive setup wizard
`openclaw opik status`	Display effective configuration
`openclaw plugins list`	List all installed plugins
`openclaw gateway run`	Start OpenClaw gateway with plugin active
`openclaw message send "text"`	Send test message to trace

Usage Patterns

Basic Tracing

Once configured, tracing is automatic. Start the gateway and send messages:

# Start gateway with plugin active
openclaw gateway run

# In another terminal, send a message
openclaw message send "Analyze the current market trends"

Traces appear automatically in your Opik project dashboard.

Tagged Runs

Add custom tags in configuration to organize traces:

{
  "config": {
    "tags": ["production", "market-analysis", "v2.0"]
  }
}

Self-Hosted Opik

Point to your self-hosted instance:

{
  "config": {
    "apiUrl": "http://localhost:5000/api",
    "apiKey": null
  }
}

Self-hosted Opik typically doesn't require an API key.

Multiple Projects

Switch projects per environment:

# Development
export OPIK_PROJECT_NAME="openclaw-dev"

# Staging
export OPIK_PROJECT_NAME="openclaw-staging"

# Production
export OPIK_PROJECT_NAME="openclaw-prod"

Event Mapping

Understanding how OpenClaw events map to Opik traces:

OpenClaw Event	Opik Entity	Data Captured
`llm_input`	Trace + LLM Span	Model name, prompt, parameters
`llm_output`	LLM Span End	Completion, tokens, cost, duration
`before_tool_call`	Tool Span Start	Tool name, input arguments
`after_tool_call`	Tool Span End	Output, error, duration
`subagent_spawning`	Subagent Span Start	Subagent metadata
`subagent_spawned`	Subagent Span Update	Run ID, initialization data
`subagent_ended`	Subagent Span End	Outcome, error if any
`agent_end`	Trace Finalize	Closes all pending spans

Configuration Options Reference

Core Settings

{
  enabled: boolean;              // Enable/disable plugin
  apiKey: string;                // Opik API key (or use OPIK_API_KEY env)
  apiUrl: string;                // Opik endpoint URL
  projectName: string;           // Opik project name
  workspaceName: string;         // Opik workspace name
  tags: string[];                // Custom tags for all traces
}

Advanced Settings

{
  toolResultPersistSanitizeEnabled: boolean;  // Rewrite local image refs in tool results
  staleTraceCleanupEnabled: boolean;          // Auto-cleanup orphaned traces
  staleTraceTimeoutMs: number;                // Trace staleness timeout (default: 300000)
  staleSweepIntervalMs: number;               // Cleanup check interval (default: 60000)
  flushRetryCount: number;                    // Retry failed trace uploads (default: 2)
  flushRetryBaseDelayMs: number;              // Base retry delay (default: 250)
}

Security & Trust

Plugin Allowlist

OpenClaw requires explicit trust for community plugins:

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

Conversation Hook Access

The plugin needs conversation access to trace LLM interactions:

{
  "plugins": {
    "entries": {
      "opik-openclaw": {
        "hooks": {
          "allowConversationAccess": true
        }
      }
    }
  }
}

Troubleshooting

Traces Not Appearing

Check plugin status:
```
openclaw opik status
```
Verify API key:
```
echo $OPIK_API_KEY
```
Check gateway logs: Look for Opik plugin initialization and trace flush messages.

Confirm plugin is enabled:

{
  "config": {
    "enabled": true
  }
}

Authentication Errors

For Opik Cloud, ensure you have a valid API key from comet.com
For self-hosted, verify apiUrl points to your instance
Check that OPIK_API_KEY or config apiKey is set correctly

Stale Traces

If traces accumulate without finishing:

{
  "config": {
    "staleTraceCleanupEnabled": true,
    "staleTraceTimeoutMs": 300000,
    "staleSweepIntervalMs": 60000
  }
}

This auto-closes traces older than 5 minutes.

Plugin Not Loading

Reinstall the plugin:

openclaw plugins uninstall @opik/opik-openclaw
openclaw plugins install @opik/opik-openclaw

Restart gateway:

# Stop gateway (Ctrl+C)
openclaw gateway run

Check OpenClaw version:

openclaw --version
# Should be >= 2026.3.2

Remote Gateway

If running OpenClaw Gateway on a remote host:

Install the plugin on the gateway host, not the client
Configure credentials on the gateway host
Restart the remote gateway process

Development & Testing

Local Development

# Clone and install
git clone https://github.com/comet-ml/opik-openclaw
cd opik-openclaw
npm ci

# Build
npm run build

# Run tests
npm run test

# Type check
npm run typecheck

# Lint
npm run lint

Live End-to-End Test

Test against a real OpenClaw gateway:

# Set required environment variables
export OPIK_API_KEY="your-key"
export OPENAI_API_KEY="your-openai-key"

# Optional overrides
export OPENCLAW_LIVE_MODEL="gpt-4o"
export OPENCLAW_LIVE_OPENCLAW_VERSION="latest"

# Run live test
npm run test:live

The live test:

Creates isolated OpenClaw home in .artifacts/live-e2e/<run-id>/
Installs current plugin build
Starts gateway and sends test message
Verifies trace upload to Opik

Package Verification

# Check package contents before publish
npm run pack:check

Real-World Examples

Production Agent with Cost Tracking

{
  "plugins": {
    "allow": ["opik-openclaw"],
    "entries": {
      "opik-openclaw": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        },
        "config": {
          "enabled": true,
          "apiKey": "${OPIK_API_KEY}",
          "apiUrl": "https://www.comet.com/opik/api",
          "projectName": "customer-support-agent",
          "workspaceName": "production",
          "tags": ["production", "customer-support", "v1.5"]
        }
      }
    }
  }
}

Development with Self-Hosted Opik

{
  "plugins": {
    "allow": ["opik-openclaw"],
    "entries": {
      "opik-openclaw": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        },
        "config": {
          "enabled": true,
          "apiUrl": "http://localhost:5000/api",
          "projectName": "dev-experiments",
          "workspaceName": "engineering",
          "tags": ["dev", "local"]
        }
      }
    }
  }
}

Multi-Environment Setup Script

#!/bin/bash

ENV=${1:-dev}

case $ENV in
  dev)
    export OPIK_PROJECT_NAME="openclaw-dev"
    export OPIK_WORKSPACE="engineering"
    ;;
  staging)
    export OPIK_PROJECT_NAME="openclaw-staging"
    export OPIK_WORKSPACE="qa"
    ;;
  prod)
    export OPIK_PROJECT_NAME="openclaw-prod"
    export OPIK_WORKSPACE="production"
    ;;
esac

openclaw gateway run

Best Practices

Use environment variables for API keys in production
Tag traces by environment, version, or feature
Enable stale cleanup to prevent memory leaks from orphaned traces
Set up separate projects for dev, staging, and production
Review cost metrics regularly in Opik dashboard
Monitor error spans to catch tool failures early
Use allowlist to control plugin trust explicitly

Opik Openclaw Observability

File contents