Plugin Types Explained

Most plugin mistakes happen before the first line of code. Not because the SDK is hard, but because the extension shape is wrong.

OpenClaw gives you several plugin types for a reason. A tool plugin, a provider plugin, a channel plugin, and a CLI backend plugin solve different jobs. If you treat them as interchangeable, you usually buy extra complexity for no gain.

The easy way to think about it is this: you are not choosing a feature label. You are choosing the boundary your package will own. That boundary decides your maintenance burden, your tests, and the kind of problems you inherit later.

Start with the question that matters

Ask this first: what should OpenClaw gain when your plugin is installed?

• If it gains a new agent action, you probably want a tool plugin.
• If it gains a new model or media backend, you probably want a provider plugin.
• If it gains a new messaging surface, you want a channel plugin.
• If it gains a local AI command bridge, you want a CLI backend plugin.

That sounds obvious. It is, right up until people start blending categories because the upstream product offers both an API and a desktop app and a chat integration. Then things get messy fast.

The four core plugin types

Tool plugins: the best default starting point

Tool plugins are the cleanest first build for most people. They add one or more agent-callable tools without making you own a chat transport, a model catalog, or a local CLI runner.

Think of them as adding a new attachment to a workshop bench, not rebuilding the whole workshop. You register a capability, define its parameters, and keep the boundary tight.

The official plugin docs position the minimal tool plugin as the shortest useful plugin shape, and that is the right instinct. If your goal is “the agent should do one more thing,” starting anywhere else is often vanity architecture.

There is also a useful split inside this category. If your package is tool-only with a fixed list of tools, OpenClaw now offers a dedicated tool-plugin workflow around defineToolPlugin. If the package mixes tools with hooks, services, or other runtime surfaces, use the more general plugin entry path instead.

Provider plugins: when you are extending the inference layer

Provider plugins are not “fancy tool plugins.” They sit closer to the model pipeline. You use them when OpenClaw should understand a new provider, auth method, catalog, or family of model refs.

This is where the maintenance burden rises. A provider plugin often owns API key semantics, setup metadata, live model catalogs, and provider-specific quirks. That is powerful, but it is also more like wiring a new power source into a building than adding a handheld tool.

Use this shape when the upstream service already behaves like a real provider and should participate in normal model routing. Do not use it just because “AI is involved.” If the agent only needs one external action, you are still in tool-plugin territory.

Channel plugins: transport plus policy, not just messaging

A channel plugin looks glamorous because it puts OpenClaw into Telegram, Discord, Slack, or another messaging surface. Under the hood, it is less about sending messages and more about owning the messy parts around them.

The official channel-plugin docs are clear here: core keeps the shared message tool. Your channel plugin mainly owns config, account resolution, pairing, DM policy, outbound delivery, threading, and session grammar.

That matters because beginners often imagine a channel plugin as “just a webhook plus send API.” It is not. It is the front desk, the badge system, and the mailroom at once. If you choose this shape, you are choosing operational responsibility.

CLI backend plugins: bridge a local command, not a normal API

CLI backend plugins exist for a very specific reason. Sometimes the upstream integration already lives behind a local command, carries its own login state, or makes more sense as a local process fallback than as a standard provider API.

In that case, OpenClaw can treat the CLI like a text inference backend with config for command launch, session ids, input mode, output parsing, watchdog behavior, and serialization.

The trap is using this type when you should have written a provider plugin instead. If the service already offers a clean HTTP model API, a CLI wrapper can become an unnecessary shim. It works, but now you are debugging both a local process layer and the upstream service.

How to choose the right shape

1. Name the thing OpenClaw gains. Tool, provider, channel, or CLI backend.
2. Find the narrowest truthful boundary. Narrower plugins are easier to reason about and test.
3. Check whether OpenClaw already has the surrounding infrastructure. For example, channels reuse the shared message tool, so you should not rebuild that.
4. Pick the shape that matches runtime ownership. If your plugin owns transport, treat it like a channel. If it owns model catalogs, treat it like a provider.
5. Only mix capabilities on purpose. Mixed plugins are fine when the integration truly needs it, not when you are trying to keep everything in one folder.

What changes in maintenance burden

This is the part many tutorials skip. Plugin type is also a maintenance forecast.

• Tool plugin: Lowest ongoing complexity if the scope stays narrow.
• Provider plugin: Medium to high complexity because upstream model catalogs, auth, and compatibility change.
• Channel plugin: High operational complexity because messaging platforms are full of edge cases.
• CLI backend plugin: Medium complexity that becomes high when the wrapped CLI is unstable or loosely specified.

A decent rule of thumb is this: the closer your plugin gets to network transport, auth, or long-lived process management, the more maintenance you should expect.

The manifest still matters in every case

No matter which type you pick, openclaw.plugin.json remains the cold-start contract. OpenClaw reads that manifest before it loads plugin runtime, which is why ownership, config validation, and discovery metadata have to be explicit there.

If you want the official references, the building plugins guide is the best starting map, and the plugin manifest reference explains what metadata belongs in the manifest before runtime code ever executes.

A practical decision matrix

Where beginners go wrong

They optimize for prestige instead of fit

A provider or channel plugin can feel more “real” than a humble tool plugin. That feeling is expensive. If the smaller shape solves the problem, take the smaller shape.

They confuse the upstream product with the OpenClaw boundary

An upstream company might offer an API, a desktop app, and a chat bot. You still have to decide what your OpenClaw package is supposed to own. One upstream product can justify different plugin types for different goals.

They bundle too much too early

Mixed-capability plugins are possible, but first versions should stay sharp. A plugin that registers tools, wraps a CLI, and exposes a provider all at once gives you more places to hide mistakes.

When not to build a plugin at all

One last uncomfortable truth: sometimes the right plugin type is none. If you only need a reusable external capability for one environment, an MCP server or a simpler local workflow might be cheaper to maintain than a custom plugin package.

Plugins are worth it when you want a stable install story, clear ownership, and a reusable capability boundary. If you do not need those things yet, do not force the ceremony.

Choose the smallest truthful plugin shape first. Future you will spend less time debugging and more time shipping.

Quick decision rule

Need a new agent action? -> Tool plugin
Need a new model or media backend? -> Provider plugin
Need a new messaging surface? -> Channel plugin
Need to drive a local AI command? -> CLI backend plugin