Building Plugins

Plugins extend OpenClaw with new capabilities: channels, model providers, speech, image generation, web search, agent tools, or any combination. You do not need to add your plugin to the OpenClaw repository. Publish to ClawHub or npm and users install with openclaw plugins install <package-name>. OpenClaw tries ClawHub first and falls back to npm automatically.

Prerequisites

Node >= 22 and a package manager (npm or pnpm)
Familiarity with TypeScript (ESM)
For in-repo plugins: repository cloned and pnpm install done

What kind of plugin?

Channel plugin

Connect OpenClaw to a messaging platform (Discord, IRC, etc.)

Provider plugin

Add a model provider (LLM, proxy, or custom endpoint)

Tool / hook plugin

Quick start: tool plugin

This walkthrough creates a minimal plugin that registers an agent tool. Channel and provider plugins have dedicated guides linked above.

Create the package and manifest

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2",
      "minGatewayVersion": "2026.3.24-beta.2"
    },
    "build": {
      "openclawVersion": "2026.3.24-beta.2",
      "pluginSdkVersion": "2026.3.24-beta.2"
    }
  }
}

Every plugin needs a manifest, even with no config. See Manifest for the full schema. The canonical ClawHub publish snippets live in docs/snippets/plugin-publish/.

Write the entry point

// index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Adds a custom tool to OpenClaw",
  register(api) {
    api.registerTool({
      name: "my_tool",
      description: "Do a thing",
      parameters: Type.Object({ input: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: `Got: ${params.input}` }] };
      },
    });
  },
});

definePluginEntry is for non-channel plugins. For channels, use defineChannelPluginEntry — see Channel Plugins. For full entry point options, see Entry Points.

Test and publish

External plugins: validate and publish with ClawHub, then install:

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
openclaw plugins install clawhub:@myorg/openclaw-my-plugin

OpenClaw also checks ClawHub before npm for bare package specs like @myorg/openclaw-my-plugin.In-repo plugins: place under the bundled plugin workspace tree — automatically discovered.

pnpm test -- <bundled-plugin-root>/my-plugin/

Plugin capabilities

A single plugin can register any number of capabilities via the api object:

Capability	Registration method	Detailed guide
Text inference (LLM)	`api.registerProvider(...)`	Provider Plugins
CLI inference backend	`api.registerCliBackend(...)`	CLI Backends
Channel / messaging	`api.registerChannel(...)`	Channel Plugins
Speech (TTS/STT)	`api.registerSpeechProvider(...)`	Provider Plugins
Media understanding	`api.registerMediaUnderstandingProvider(...)`	Provider Plugins
Image generation	`api.registerImageGenerationProvider(...)`	Provider Plugins
Web search	`api.registerWebSearchProvider(...)`	Provider Plugins
Agent tools	`api.registerTool(...)`	Below
Custom commands	`api.registerCommand(...)`	Entry Points
Event hooks	`api.registerHook(...)`	Entry Points
HTTP routes	`api.registerHttpRoute(...)`	Internals
CLI subcommands	`api.registerCli(...)`	Entry Points

For the full registration API, see SDK Overview. Hook guard semantics to keep in mind:

before_tool_call: { block: true } is terminal and stops lower-priority handlers.
before_tool_call: { block: false } is treated as no decision.
before_tool_call: { requireApproval: true } pauses agent execution and prompts the user for approval via the exec approval overlay, Telegram buttons, Discord interactions, or the /approve command on any channel.
before_install: { block: true } is terminal and stops lower-priority handlers.
before_install: { block: false } is treated as no decision.
message_sending: { cancel: true } is terminal and stops lower-priority handlers.
message_sending: { cancel: false } is treated as no decision.

The /approve command handles both exec and plugin approvals with automatic fallback. Plugin approval forwarding can be configured independently via approvals.plugin in config. See SDK Overview hook decision semantics for details.

Registering agent tools

Tools are typed functions the LLM can call. They can be required (always available) or optional (user opt-in):

register(api) {
  // Required tool — always available
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({ input: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

  // Optional tool — user must add to allowlist
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a workflow",
      parameters: Type.Object({ pipeline: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}

Users enable optional tools in config:

{
  tools: { allow: ["workflow_tool"] },
}

Tool names must not clash with core tools (conflicts are skipped)
Use optional: true for tools with side effects or extra binary requirements
Users can enable all tools from a plugin by adding the plugin id to tools.allow

Import conventions

Always import from focused openclaw/plugin-sdk/<subpath> paths:

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

// Wrong: monolithic root (deprecated, will be removed)
import { ... } from "openclaw/plugin-sdk";

For the full subpath reference, see SDK Overview. Within your plugin, use local barrel files (api.ts, runtime-api.ts) for internal imports — never import your own plugin through its SDK path.

Pre-submission checklist

package.json has correct openclaw metadata

openclaw.plugin.json manifest is present and valid

Entry point uses defineChannelPluginEntry or definePluginEntry

All imports use focused plugin-sdk/<subpath> paths

Internal imports use local modules, not SDK self-imports

Tests pass (pnpm test -- <bundled-plugin-root>/my-plugin/)

pnpm check passes (in-repo plugins)

Beta Release Testing

Watch for GitHub release tags on openclaw/openclaw and subscribe via Watch > Releases. Beta tags look like v2026.3.N-beta.1. You can also turn on notifications for the official OpenClaw X account @openclaw for release announcements.
Test your plugin against the beta tag as soon as it appears. The window before stable is typically only a few hours.
Post in your plugin’s thread in the plugin-forum Discord channel after testing with either all good or what broke. If you do not have a thread yet, create one.
If something breaks, open or update an issue titled Beta blocker: <plugin-name> - <summary> and apply the beta-blocker label. Put the issue link in your thread.
Open a PR to main titled fix(<plugin-id>): beta blocker - <summary> and link the issue in both the PR and your Discord thread. Contributors cannot label PRs, so the title is the PR-side signal for maintainers and automation. Blockers with a PR get merged; blockers without one might ship anyway. Maintainers watch these threads during beta testing.
Silence means green. If you miss the window, your fix likely lands in the next cycle.

Next steps

Channel Plugins

Build a messaging channel plugin

Provider Plugins

Build a model provider plugin

SDK Overview

Import map and registration API reference

Runtime Helpers

TTS, search, subagent via api.runtime

Testing

Test utilities and patterns

Plugin Manifest

Full manifest schema reference

Plugin Architecture — internal architecture deep dive
SDK Overview — Plugin SDK reference
Manifest — plugin manifest format
Channel Plugins — building channel plugins
Provider Plugins — building provider plugins

Overview

Plugins

Skills

Automation

Tools

Agent coordination

Building Plugins

Building Plugins

Prerequisites

What kind of plugin?

Channel plugin

Provider plugin

Tool / hook plugin

Quick start: tool plugin

Plugin capabilities

Registering agent tools

Import conventions

Pre-submission checklist

Beta Release Testing

Next steps

Channel Plugins

Provider Plugins

SDK Overview

Runtime Helpers

Testing

Plugin Manifest

Overview

Plugins

Skills

Automation

Tools

Agent coordination

​Building Plugins

​Prerequisites

​What kind of plugin?

Channel plugin

Provider plugin

Tool / hook plugin

​Quick start: tool plugin

​Plugin capabilities

​Registering agent tools

​Import conventions

​Pre-submission checklist

​Beta Release Testing

​Next steps

Channel Plugins

Provider Plugins

SDK Overview

Runtime Helpers

Testing

Plugin Manifest

​Related

Building Plugins

Prerequisites

What kind of plugin?

Quick start: tool plugin

Plugin capabilities

Registering agent tools

Import conventions

Pre-submission checklist

Beta Release Testing

Next steps

Related