Use this file to discover all available pages before exploring further.

Building plugins

Plugins extend OpenClaw with new capabilities: channels, model providers, speech, realtime transcription, realtime voice, media understanding, image generation, video generation, web fetch, web search, agent tools, or any combination.

You do not need to add your plugin to the OpenClaw repository. Publish to ClawHub and users install with

text

openclaw plugins install <package-name>

. OpenClaw tries ClawHub first and falls back to npm automatically for packages that still use npm distribution.

Prerequisites

Node >= 22 and a package manager (npm or pnpm)
Familiarity with TypeScript (ESM)
For in-repo plugins: repository cloned and
text
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

For a channel plugin that isn't guaranteed to be installed when onboarding/setup runs, use

text

createOptionalChannelSetupSurface(...)

from

text

openclaw/plugin-sdk/channel-setup

. It produces a setup adapter + wizard pair that advertises the install requirement and fails closed on real config writes until the plugin is installed.

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

```json package.json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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" } } } ```


text
  ```json openclaw.plugin.json theme={"theme":{"light":"min-light","dark":"min-dark"}}
  {
    "id": "my-plugin",
    "name": "My Plugin",
    "description": "Adds a custom tool to OpenClaw",
    "activation": {
      "onStartup": true
    },
    "configSchema": {
      "type": "object",
      "additionalProperties": false
    }
  }
  ```
</CodeGroup>

Every plugin needs a manifest, even with no config, and every plugin should
declare `activation.onStartup` intentionally. Runtime-registered tools need
startup import, so this example sets it to `true`. See
[Manifest](/plugins/manifest) for the full schema. The canonical ClawHub
publish snippets live in `docs/snippets/plugin-publish/`.

Write the entry point

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


text
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](/plugins/sdk-channel-plugins).
For full entry point options, see [Entry Points](/plugins/sdk-entrypoints).

Test and publish

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


text
```bash}
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`; npm remains a fallback for packages that have
not migrated to ClawHub yet.

**In-repo plugins:** place under the bundled plugin workspace tree — automatically discovered.

```bash}
pnpm test -- <bundled-plugin-root>/my-plugin/
```

Plugin capabilities

A single plugin can register any number of capabilities via the

text

api

object:

Capability	Registration method	Detailed guide
Text inference (LLM)	text `api.registerProvider(...)`	Provider Plugins
CLI inference backend	text `api.registerCliBackend(...)`	CLI Backends
Channel / messaging	text `api.registerChannel(...)`	Channel Plugins
Speech (TTS/STT)	text `api.registerSpeechProvider(...)`	Provider Plugins
Realtime transcription	text `api.registerRealtimeTranscriptionProvider(...)`	Provider Plugins
Realtime voice	text `api.registerRealtimeVoiceProvider(...)`	Provider Plugins
Media understanding	text `api.registerMediaUnderstandingProvider(...)`	Provider Plugins
Image generation	text `api.registerImageGenerationProvider(...)`	Provider Plugins
Music generation	text `api.registerMusicGenerationProvider(...)`	Provider Plugins
Video generation	text `api.registerVideoGenerationProvider(...)`	Provider Plugins
Web fetch	text `api.registerWebFetchProvider(...)`	Provider Plugins
Web search	text `api.registerWebSearchProvider(...)`	Provider Plugins
Tool-result middleware	text `api.registerAgentToolResultMiddleware(...)`	SDK Overview
Agent tools	text `api.registerTool(...)`	Below
Custom commands	text `api.registerCommand(...)`	Entry Points
Plugin hooks	text `api.on(...)`	Plugin hooks
Internal event hooks	text `api.registerHook(...)`	Entry Points
HTTP routes	text `api.registerHttpRoute(...)`	Internals
CLI subcommands	text `api.registerCli(...)`	Entry Points

For the full registration API, see SDK Overview.

Bundled plugins can use

text

api.registerAgentToolResultMiddleware(...)

when they need async tool-result rewriting before the model sees the output. Declare the targeted runtimes in

text

contracts.agentToolResultMiddleware

, for example

text

["pi", "codex"]

. This is a trusted bundled-plugin seam; external plugins should prefer regular OpenClaw plugin hooks unless OpenClaw grows an explicit trust policy for this capability.

If your plugin registers custom gateway RPC methods, keep them on a plugin-specific prefix. Core admin namespaces (

text

config.*

text

exec.approvals.*

text

wizard.*

text

update.*

) stay reserved and always resolve to

text

operator.admin

, even if a plugin asks for a narrower scope.

Hook guard semantics to keep in mind:

text
before_tool_call
:
text
{ block: true }
is terminal and stops lower-priority handlers.
text
before_tool_call
:
text
{ block: false }
is treated as no decision.
text
before_tool_call
:
text
{ requireApproval: true }
pauses agent execution and prompts the user for approval via the exec approval overlay, Telegram buttons, Discord interactions, or the
text
/approve
command on any channel.
text
before_install
:
text
{ block: true }
is terminal and stops lower-priority handlers.
text
before_install
:
text
{ block: false }
is treated as no decision.
text
message_sending
:
text
{ cancel: true }
is terminal and stops lower-priority handlers.
text
message_sending
:
text
{ cancel: false }
is treated as no decision.
text
message_received
: prefer the typed
text
threadId
field when you need inbound thread/topic routing. Keep
text
metadata
for channel-specific extras.
text
message_sending
: prefer typed
text
replyToId
/
text
threadId
routing fields over channel-specific metadata keys.

The

text

/approve

command handles both exec and plugin approvals with bounded fallback: when an exec approval id is not found, OpenClaw retries the same id through plugin approvals. Plugin approval forwarding can be configured independently via

text

approvals.plugin

in config.

If custom approval plumbing needs to detect that same bounded fallback case, prefer

text

isApprovalNotFoundError

from

text

openclaw/plugin-sdk/error-runtime

instead of matching approval-expiry strings manually.

See Plugin hooks for examples and the hook reference.

Registering agent tools

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


typescript
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:


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

Tool names must not clash with core tools (conflicts are skipped)
Tools with malformed registration objects, including missing
text
parameters
, are skipped and reported in plugin diagnostics instead of breaking agent runs
Use
text
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
text
tools.allow

Import conventions

Always import from focused

text

openclaw/plugin-sdk/<subpath>

paths:


typescript
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 (

text

api.ts

text

runtime-api.ts

) for internal imports — never import your own plugin through its SDK path.

For provider plugins, keep provider-specific helpers in those package-root barrels unless the seam is truly generic. Current bundled examples:

Anthropic: Claude stream wrappers and
text
service_tier
/ beta helpers
OpenAI: provider builders, default-model helpers, realtime providers
OpenRouter: provider builder plus onboarding/config helpers

If a helper is only useful inside one bundled provider package, keep it on that package-root seam instead of promoting it into

text

openclaw/plugin-sdk/*

Some generated

text

openclaw/plugin-sdk/<bundled-id>

helper seams still exist for bundled-plugin maintenance when they have tracked owner usage. Treat those as reserved surfaces, not as the default pattern for new third-party plugins.

Pre-submission checklist

package.json has correct

text

openclaw

metadata openclaw.plugin.json manifest is present and valid Entry point uses

text

defineChannelPluginEntry

text

definePluginEntry

All imports use focused

text

plugin-sdk/<subpath>

paths Internal imports use local modules, not SDK self-imports Tests pass (

text

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

)

text

pnpm check

passes (in-repo plugins)

Beta release testing

Watch for GitHub release tags on openclaw/openclaw and subscribe via
text
Watch
>
text
Releases
. Beta tags look like
text
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
text
plugin-forum
Discord channel after testing with either
text
all good
or what broke. If you do not have a thread yet, create one.
If something breaks, open or update an issue titled
text
Beta blocker: <plugin-name> - <summary>
and apply the
text
beta-blocker
label. Put the issue link in your thread.
Open a PR to
text
main
titled
text
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

OpenClaw Docs

Building plugins

Prerequisites

What kind of plugin?

Channel plugin

Provider plugin

Tool / hook plugin

Quick start: tool plugin

Create the package and manifest

Write the entry point

Test and publish

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