How to Build an OpenClaw Plugin

Build an OpenClaw plugin with tools, Skills, model providers, channels, or harness integrations, then manage versions and telemetry with Telvine.

This guide explains how to build an OpenClaw plugin and manage it as part of a cross-harness Agent Plugin strategy. OpenClaw plugins are extension packages for the OpenClaw environment: they can add tools, Skills, channels, model providers, agent harness integrations, speech, media, web search, generation, and other capabilities.

Use the OpenClaw plugin docs for the latest platform-specific details. Use Telvine as the product layer that keeps the plugin identity, component inventory, versions, and telemetry stable across OpenClaw and the other harnesses you support.

1. Define the plugin product

Start with the product users install, not the OpenClaw folder shape:

Plugin id: stable across every harness adapter.
Audience: the team, customer segment, or workspace that needs it.
Job: the work the plugin helps an agent complete.
OpenClaw surfaces: tools, Skills, channels, model providers, agent harnesses, speech, media, web, or generation.
Other harnesses: Codex, Microsoft 365 Copilot Cowork, Claude, Hermes Agent, or direct SKILL.md.
Telemetry: package, component, version, and runtime events you will send to Telvine.

Example: a customer-escalations plugin might expose an OpenClaw tool for reading CRM tickets, a Skill for summarizing escalation history, and a model-provider policy for routing sensitive cases.

2. Create one source workspace

Keep a canonical plugin workspace before producing the OpenClaw adapter:

customer-escalations/
├── telvine.plugin.json
├── skills/
│   └── summarize-escalation/
│       └── SKILL.md
├── tools/
│   └── crm-ticket-lookup/
├── connectors/
│   └── crm-api/
├── telemetry/
│   └── events.md
└── adapters/
    ├── openclaw/
    ├── codex/
    ├── hermes/
    └── copilot-cowork/

The OpenClaw adapter should describe how this product appears in OpenClaw. The source workspace should remain the system of record for versioning, component ownership, and telemetry.

3. Choose the OpenClaw extension type

OpenClaw plugins can cover several kinds of extension. Pick the smallest surface that solves the job:

Extension surface	Use it when	Telvine component type
Tool	The agent needs a callable action or data lookup	`tool`
Skill	The agent needs task-specific instructions and workflow context	`skill`
Channel	The plugin adds a new communication surface	`channel`
Model provider	The plugin adds or routes model access	`model_provider`
Agent harness	The plugin connects another agent runtime	`harness_adapter`
Media, speech, web, or generation	The plugin adds specialized runtime capability	`runtime_component`

Do not split one product into unrelated plugins just because it has more than one component. Keep related capabilities under the same plugin id and measure each component separately.

4. Build the OpenClaw adapter

Inside adapters/openclaw/, create the package shape OpenClaw expects. Keep the adapter thin:

adapters/openclaw/
├── openclaw.plugin.json
├── package.json
├── src/
│   ├── index.ts
│   └── tools/
│       └── crm-ticket-lookup.ts
└── skills/
    └── summarize-escalation/
        └── SKILL.md

OpenClaw uses openclaw.plugin.json for cheap pre-runtime metadata such as identity, config validation, auth/setup hints, and static capability ownership. Runtime entrypoints, install metadata, and package-manager behavior belong in package.json, including the openclaw block for extension entrypoints and compatibility gates.

For a native code plugin, your package.json should declare the OpenClaw runtime entries and compatibility metadata:

{
  "name": "@acme/openclaw-customer-escalations",
  "version": "1.3.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2",
      "minGatewayVersion": "2026.3.24-beta.2"
    }
  }
}

Shared instructions, scripts, references, and telemetry conventions should live in the source workspace so the Codex, Hermes, Claude, and Copilot Cowork adapters do not drift.

5. Add telemetry at the component boundary

Emit Telvine events from the places you control:

Tool handlers.
Provider or channel adapters.
Backend connector endpoints.
Installation, update, and rollout automation.
Skill wrappers or scripts that run inside the plugin.

Example event:

{
  "event_type": "plugin.component.invoked",
  "plugin_id": "plg_customer_escalations",
  "version": "1.3.0",
  "runtime": "openclaw",
  "properties": {
    "component_type": "tool",
    "component_name": "crm-ticket-lookup",
    "operation": "lookup_ticket",
    "duration_ms": 182,
    "outcome": "completed"
  }
}

Keep the envelope typed and closed. Do not send prompts, ticket contents, documents, retrieved records, tool arguments, or model outputs.

6. Publish and compare across harnesses

The release loop should answer whether the plugin product works across every place users run agents:

Package the OpenClaw adapter.
Publish or install it through the right channel: local workspace, npm, or ClawHub.
Package the Codex, Hermes, Claude, Copilot Cowork, or SKILL.md adapters if the same product runs there.
Register the plugin version and component inventory in Telvine.
Roll out to a controlled audience.
Compare OpenClaw usage, latency, errors, and outcomes against the other harnesses.

With Telvine:

npm i -g @telvine/cli
telvine login
telvine publish ./customer-escalations

Checklist

The OpenClaw adapter is generated from or aligned with one source plugin workspace.
Each OpenClaw tool, Skill, provider, channel, or runtime component has a component id.
Telemetry includes plugin id, plugin version, runtime, component name, and outcome.
Sensitive content stays out of events.
The same plugin product can be compared against Codex, Hermes Agent, Claude, Copilot Cowork, and direct SKILL.md adapters.