OpenClaw plugin SDK: typed tool plugins for self-hosted agents

OpenClaw plugin SDK now has a clearer path for shipping agent-callable tools: defineToolPlugin, openclaw plugins init, openclaw plugins build, and openclaw plugins validate. The point is not to make every integration fancy. It is to make small, typed tools easy to package, inspect, and install without dragging unrelated channel, provider, or service code into the runtime.

That matters because personal agents are becoming less like chatbots and more like local operating surfaces. They read files, call APIs, send messages, run jobs, and remember context. Every new tool expands what the agent can do. It also expands what operators have to trust.

Why the OpenClaw plugin SDK matters now

The 2026.5.18 release added defineToolPlugin plus CLI support for plugin build, validation, and scaffolding. The related documentation describes tool plugins as the right fit when a package owns a fixed list of agent-callable tools and does not need to add a channel, model provider, hook, service, or setup backend.

That boundary is useful. A stock quote tool, internal ticket lookup, PDF normalizer, local database query, or deployment status checker should not have to pretend to be a full platform extension. It needs parameters, validation, metadata, predictable packaging, and a way for OpenClaw to discover it safely.

The release also lands in a market that is already thinking hard about tool surfaces. MCP made runtime tool attachment mainstream. Developers now expect agents to connect to local files, SaaS systems, search, calendars, and custom workflows. But not every tool needs to be a remote MCP server. Some tools are better as installed local plugins with typed manifests and explicit lifecycle checks.

For the broader product architecture, see how OpenClaw works. OpenClaw keeps the Gateway, sessions, policies, channels, memory, and tools under one self-hosted control plane. The plugin SDK is one way to extend that control plane without turning the core runtime into a junk drawer.

Tool plugins versus MCP servers

MCP and OpenClaw tool plugins solve adjacent problems. The clean choice depends on who owns the runtime, how the tool is distributed, and how much lifecycle control you need.

Question	OpenClaw tool plugin	MCP server
Best fit	Installed tools for an OpenClaw runtime	Cross-client tool servers for many AI apps
Discovery	Generated plugin metadata and OpenClaw plugin registry/lifecycle	MCP client discovers server capabilities at runtime
Packaging	npm-style package with dist/, package.json, and openclaw.plugin.json	Server process, remote endpoint, or local command
Control	Same OpenClaw policy, config, and plugin validation path	Depends on the client and server transport
Use case	Stable tools a self-hosted agent should own locally	Portable tools that several AI clients may call

A practical rule: use MCP when portability across clients is the main value. Use an OpenClaw tool plugin when the tool belongs inside an OpenClaw deployment, should follow OpenClaw plugin lifecycle rules, and benefits from generated metadata.

This is not an either-or bet. A serious agent stack will often use both. MCP is good for broad ecosystem reach. A local plugin SDK is good for repeatable operations inside one governed runtime.

How the OpenClaw plugin SDK build flow works

The documented flow is deliberately boring:

1. Scaffold a package with openclaw plugins init.
2. Write tools with defineToolPlugin.
3. Build JavaScript from TypeScript ESM.
4. Generate openclaw.plugin.json and package metadata with openclaw plugins build.
5. Run openclaw plugins validate before publishing or installing.

The requirements are also explicit: Node 22 or newer, TypeScript ESM output, typebox for config and tool parameter schemas, and OpenClaw 2026.5.17 or newer for the exported openclaw/plugin-sdk/tool-plugin path. The docs call out one small but common packaging trap: because generated plugins import typebox at runtime, keep typebox in dependencies, not only devDependencies.

That level of specificity is the difference between “copy this snippet” and “ship a package another operator can actually install.” Agent tools fail in annoying ways when metadata is stale, schemas are missing, or the runtime has to import arbitrary code just to learn what a package exposes. The SDK flow pushes those checks earlier.

What a typed tool plugin should own

A good tool plugin should be narrow. It should expose a small set of actions, define the input shape clearly, return bounded data, and leave orchestration to the agent runtime.

Good candidates include:

• A linear_issue_lookup tool that accepts an issue id and returns title, status, owner, and URL.
• A deploy_status tool that checks one deployment provider and returns the current state plus last error.
• A stock_quote tool that accepts a ticker and returns a quote with source timestamp.
• A pdf_extract_text tool that accepts a file path already allowed by policy and returns extracted text.
• A warehouse_query tool that runs approved read-only queries against a narrow analytics view.

Bad candidates are usually too broad. If the plugin wants to run a long-lived service, register a model provider, add a chat channel, create background hooks, or manage OAuth setup, it probably belongs in a different plugin shape. OpenClaw’s own docs point provider, channel, hook, service, and mixed-capability plugins toward the broader plugin guides instead of the simple tool plugin path.

Security and operations checklist

Typed metadata does not make a dangerous tool safe. It does make dangerous edges easier to see.

Before installing or publishing a tool plugin, check these points:

1. Inputs are narrow. Do not expose an unbounded shell, URL fetcher, SQL runner, or file reader unless policy constrains it hard.
2. Return values are bounded. Agents do not need a 20 MB API dump when a status object would do.
3. Secrets stay in config or SecretRef-style storage. Do not bake credentials into package files, examples, or test fixtures.
4. Build metadata is fresh. Run the build and validation steps in CI so openclaw.plugin.json matches the current entrypoint.
5. The package can be inspected locally. Operators should be able to run plugin list, inspect, validate, and doctor commands without guessing which code path failed.
6. Tool names are boring and precise. A model should know whether it is calling ticket_lookup, ticket_create, or ticket_comment_add.

OpenClaw has already been moving optional integration weight out of the core install path. The companion post on provider plugins and leaner self-hosted installs covers that packaging side. The plugin SDK continues the same direction for custom tools: keep the core lean, put extension logic at defined edges, and make those edges inspectable.

Where this fits in an agent tool strategy

If you are building a self-hosted agent stack, do not start by making tools available everywhere. Start by deciding which tools deserve to exist under your agent’s authority.

Use this split:

• Put personal or team-owned operational tools in OpenClaw tool plugins when they should inherit the local runtime’s policy, logging, and plugin lifecycle.
• Use MCP servers when the same capability should be portable across Claude, ChatGPT, IDEs, and other clients.
• Keep high-risk tools behind narrower wrappers, even if the underlying API is broad.
• Prefer read-only tools first. Add write actions only when approvals, audit trails, and rollback paths are clear.

This is also why OpenClaw versus alternatives is not just a model comparison. The harder question is who owns the tool boundary. Hosted chat apps can attach connectors. Local agent systems can own the whole path from permission to execution to delivery.

For teams experimenting with custom capabilities, start with one boring read-only plugin. Make it pass validation. Install it locally. Watch one real agent turn call it. Then decide whether it should grow.

FAQ

What is the OpenClaw plugin SDK?

The OpenClaw plugin SDK is the developer surface for building installable OpenClaw plugins. For simple agent-callable tools, the tool plugin path uses defineToolPlugin plus CLI build and validation commands to generate metadata and keep tools discoverable.

Is a tool plugin the same as an MCP server?

No. A tool plugin is installed into an OpenClaw runtime and follows OpenClaw’s plugin lifecycle. An MCP server exposes tools through the Model Context Protocol so multiple clients can connect to it. They can complement each other.

When should I use defineToolPlugin?

Use defineToolPlugin when your package owns a fixed list of tools and does not need to add a provider, channel, hook, service, or setup backend. If the integration has broader runtime behavior, use the broader plugin SDK path.

Does the plugin SDK remove the need for security review?

No. It improves structure and validation, but humans still need to review permissions, secrets, package scripts, network calls, and write actions. Typed tools are easier to inspect; they are not automatically safe.

Bottom line

The OpenClaw plugin SDK is useful because it makes the smallest useful extension shape first class. A self-hosted agent does not need every integration in core, and it does not need every custom action to run as a separate remote server. Typed tool plugins give operators a middle path: local, inspectable, packageable tools that fit the OpenClaw runtime.

Sources: OpenClaw v2026.5.18 release notes, OpenClaw tool plugins docs, OpenClaw plugins CLI docs, Model Context Protocol introduction, Hacker News discussion on MCP versus APIs.