OpenClaw Plugin Architecture: Capabilities, Ownership, and Runtime

This is the deep architecture reference for the OpenClaw plugin system. For practical guides, start with one of the focused pages below.

• Install and use plugins, End-user guide for adding, enabling, and troubleshooting plugins.

• Building plugins, First-plugin tutorial with the smallest working manifest.

• Channel plugins, Build a messaging channel plugin.

• Provider plugins, Build a model provider plugin.

• SDK overview, Import map and registration API reference.

Public capability model

Capabilities are the public native plugin model inside OpenClaw. Every native OpenClaw plugin registers against one or more capability types:

Note

A plugin that registers zero capabilities but provides hooks, tools, discovery services, or background services is a legacy hook-only plugin. That pattern is still fully supported.

External compatibility stance

The capability model is landed in core and used by bundled/native plugins today, but external plugin compatibility still needs a tighter bar than "it is exported, therefore it is frozen."

Capability registration is the intended direction. Legacy hooks remain the safest no-breakage path for external plugins during the transition. Exported helper subpaths are not all equal, prefer narrow documented contracts over incidental helper exports.

Plugin shapes

OpenClaw classifies every loaded plugin into a shape based on its actual registration behavior (not just static metadata):

plain-capability

Registers exactly one capability type (for example a provider-only plugin like arcee or chutes).

hybrid-capability

Registers multiple capability types (for example openai owns text inference, speech, media understanding, and image generation).

hook-only

Registers only hooks (typed or custom), no capabilities, tools, commands, or services.

non-capability

Tools, commands, services, or routes are registered, but capabilities are not.

A plugin's shape and capability breakdown can be inspected with openclaw plugins inspect <id>. For more detail, consult the CLI reference.

Compatibility signals

These compatibility notices are surfaced through openclaw doctor, openclaw plugins inspect <id>, openclaw status --all, and openclaw plugins doctor:

Today, none of the advisory or warn signals will break your plugin. These signals are also present in openclaw status --all and openclaw plugins doctor.

Architecture overview

Four layers make up OpenClaw's plugin system:

Manifest + discovery

Candidate plugins are located by OpenClaw from configured paths, workspace roots, global plugin roots, and bundled plugins. Native openclaw.plugin.json manifests and supported bundle manifests are read first during discovery.

Enablement + validation

Whether a discovered plugin is enabled, disabled, blocked, or selected for an exclusive slot such as memory is decided by core.

Runtime loading

In-process loading applies to native OpenClaw plugins, which register capabilities into a central registry. Packaged JavaScript loads through native require; third-party local source TypeScript is the emergency Jiti fallback. Compatible bundles are normalized into registry records without importing runtime code.

Surface consumption

Tools, channels, provider setup, hooks, HTTP routes, CLI commands, and services are exposed to the rest of OpenClaw by reading the registry.

For plugin CLI specifically, root command discovery is split in two phases:

• parse-time metadata comes from registerCli(..., { descriptors: [...] })
• the real plugin CLI module can stay lazy and register on first invocation

That keeps plugin-owned CLI code inside the plugin while still letting OpenClaw reserve root command names before parsing.

The important design boundary:

• manifest/config validation should work from manifest/schema metadata without executing plugin code
• native capability discovery may load trusted plugin entry code to build a non-activating registry snapshot
• native runtime behavior comes from the plugin module's register(api) path with api.registrationMode === "full"

Config validation, explaining missing or disabled plugins, and building UI or schema hints before the full runtime is active are all made possible by that split.

Plugin metadata snapshot and lookup table

For the current config snapshot, Gateway startup builds one PluginMetadataSnapshot. The snapshot is metadata-only: it stores the installed plugin index, manifest registry, manifest diagnostics, owner maps, a plugin id normalizer, and manifest records. Loaded plugin modules, provider SDKs, package contents, or runtime exports are not held by it.

Instead of rebuilding manifest or index metadata independently, plugin-aware config validation, startup auto-enable, and Gateway plugin bootstrap consume that snapshot. From the same snapshot, PluginLookUpTable is derived and adds the startup plugin plan for the current runtime config.

After startup, the current metadata snapshot is kept by Gateway as a replaceable runtime product. Rather than reconstructing the installed index and manifest registry for each provider-catalog pass, repeated runtime provider discovery can borrow that snapshot. On Gateway shutdown, config or plugin inventory changes, and installed index writes, the snapshot is cleared or replaced; when no compatible current snapshot exists, callers fall back to the cold manifest or index path. Plugin discovery roots such as plugins.load.paths and the default agent workspace must be included in compatibility checks, since workspace plugins fall within the metadata scope.

Repeated startup decisions stay on the fast path thanks to the snapshot and lookup table:

• channel ownership
• startup plugin planning
• startup plugin ids
• provider and CLI backend ownership
• setup provider, command alias, model catalog provider, and manifest contract ownership
• plugin config schema and channel config schema validation
• startup auto-enable decisions

Snapshot replacement, not mutation, is the safety boundary. Rebuild the snapshot when config, plugin inventory, install records, or persisted index policy changes. Treating it as a broad mutable global registry is discouraged, and unbounded historical snapshots should not be kept. Metadata snapshots remain separate from runtime plugin loading, so stale runtime state cannot be concealed behind a metadata cache.

The cache rule is documented in Plugin architecture internals: manifest and discovery metadata are fresh unless a caller holds an explicit snapshot, lookup table, or manifest registry for the current flow. Hidden metadata caches and wall-clock TTLs are not part of plugin loading. Only runtime loader, module, and dependency-artifact caches may persist after code or installed artifacts are actually loaded.

Some cold-path callers still reconstruct manifest registries directly from the persisted installed plugin index instead of receiving a Gateway PluginLookUpTable. On demand, that path now reconstructs the registry; when a caller already has one, prefer passing the current lookup table or an explicit manifest registry through runtime flows.

Activation planning

Part of the control plane is activation planning. Before loading broader runtime registries, callers can ask which plugins are relevant to a concrete command, provider, channel, route, agent harness, or capability.

Current manifest behavior is kept compatible by the planner:

• activation.* fields are explicit planner hints
• providers, channels, commandAliases, setup.providers, contracts.tools, and hooks remain manifest ownership fallback
• the ids-only planner API stays available for existing callers
• the plan API reports reason labels so diagnostics can distinguish explicit hints from ownership fallback

Warning

Do not treat activation as a lifecycle hook or a replacement for register(...). It is metadata used to narrow loading. Prefer ownership fields when they already describe the relationship; use activation only for extra planner hints.

Channel plugins and the shared message tool

For normal chat actions, channel plugins are not required to register a separate send, edit, or react tool. One shared message tool is kept in core by OpenClaw, and channel plugins own the channel-specific discovery and execution behind it.

The current boundary is:

• core owns the shared message tool host, prompt wiring, session/thread bookkeeping, and execution dispatch
• channel plugins own scoped action discovery, capability discovery, and any channel-specific schema fragments
• channel plugins own provider-specific session conversation grammar, such as how conversation ids encode thread ids or inherit from parent conversations
• channel plugins execute the final action through their action adapter

For channel plugins, the SDK surface is ChannelMessageActionAdapter.describeMessageTool(...). Visible actions, capabilities, and schema contributions can be returned together by that unified discovery call, preventing those pieces from drifting apart.

A deliberately closed, core-owned vocabulary is used for message action names, so every transport can render every action. Action names are added by plugins through a core PR; runtime registration is intentionally unsupported.

When a channel-specific message-tool param carries a media source such as a local path or remote media URL, the plugin should also return mediaSourceParams from describeMessageTool(...). Sandbox path normalization and outbound media-access hints are applied by core using that explicit list, without hardcoding plugin-owned param names. Action-scoped maps are preferred there over one channel-wide flat list, so a profile-only media param does not get normalized on unrelated actions like send.

Runtime scope is passed by core into that discovery step. Important fields include:

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• trusted inbound requesterSenderId

For context-sensitive plugins, that matters. Based on the active account, current room, thread, or message, or trusted requester identity, a channel can hide or expose message actions without hardcoding channel-specific branches in the core message tool.

This is why embedded-runner routing changes are still plugin work: forwarding the current chat or session identity into the plugin discovery boundary is the runner's responsibility, so the shared message tool exposes the right channel-owned surface for the current turn.

For channel-owned execution helpers, the runtime should live inside the channel plugin's own modules. Core no longer maintains the Discord, Slack, Telegram, or WhatsApp message-action runtimes under src/agents/tools. We do not publish separate plugin-sdk/*-action-runtime subpaths, and those plugins should import their local runtime code directly from their plugin-owned modules.

This same boundary applies to provider-named SDK seams in general: core should not import channel-specific convenience barrels for Discord, Signal, Slack, WhatsApp, or similar plugins. When core needs a behavior, it should either consume the bundled plugin's own api.ts / runtime-api.ts barrel or elevate the need into a narrow generic capability in the shared SDK.

Bundled plugins follow the same rule. A bundled plugin's runtime-api.ts should not re-export its own branded openclaw/plugin-sdk/<plugin-id> facade. Those branded facades remain compatibility shims for external plugins and older consumers, but bundled plugins should use local exports plus narrow generic SDK subpaths such as openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/runtime-store, or openclaw/plugin-sdk/webhook-ingress. New code should not add plugin-id-specific SDK facades unless the compatibility boundary for an existing external ecosystem requires it.

For polls specifically, there are two execution paths:

• outbound.sendPoll is the shared baseline for channels that fit the common poll model
• actions.handleAction("poll") is the preferred path for channel-specific poll semantics or extra poll parameters

Core now defers shared poll parsing until after plugin poll dispatch declines the action, so plugin-owned poll handlers can accept channel-specific poll fields without being blocked by the generic poll parser first.

See Plugin architecture internals for the full startup sequence.

Capability ownership model

OpenClaw treats a native plugin as the ownership boundary for a company or a feature, not as a grab bag of unrelated integrations.

That means:

• a company plugin should usually own all of that company's OpenClaw-facing surfaces
• a feature plugin should usually own the full feature surface it introduces
• channels should consume shared core capabilities instead of re-implementing provider behavior ad hoc

Vendor multi-capability

google owns text inference, CLI backend, embeddings, speech, realtime voice, media understanding, image/music/video generation, and web search. openai owns text inference, embeddings, speech, realtime transcription, realtime voice, media understanding, image/video generation. minimax owns text inference plus media understanding, speech, image/music/video generation, and web search.

Vendor single-capability

arcee and chutes own text inference only; microsoft owns speech only. A vendor plugin can stay this narrow until it needs to cover more of that vendor's surface.

Feature plugin

voice-call owns call transport, tools, CLI, routes, and Twilio media-stream bridging, but consumes shared speech, realtime transcription, and realtime voice capabilities instead of importing vendor plugins directly.

The intended end state is:

• a vendor's OpenClaw-facing surface lives in one plugin even if it spans text models, speech, images, and video
• other vendors can do the same for their own surface area
• channels do not care which vendor plugin owns the provider; they consume the shared capability contract exposed by core

This is the key distinction:

• plugin = ownership boundary
• capability = core contract that multiple plugins can implement or consume

So if OpenClaw adds a new domain such as video, the first question is not "which provider should hardcode video handling?" The first question is "what is the core video capability contract?" Once that contract exists, vendor plugins can register against it and channel/feature plugins can consume it.

If the capability does not exist yet, the right move is usually:

Define the capability

Define the missing capability in core.

Expose through the SDK

Expose it through the plugin API/runtime in a typed way.

Wire consumers

Wire channels/features against that capability.

Vendor implementations

Let vendor plugins register implementations.

This keeps ownership explicit while avoiding core behavior that depends on a single vendor or a one-off plugin-specific code path.

Capability layering

Use this mental model when deciding where code belongs:

Core capability layer

Shared orchestration, policy, fallback, config merge rules, delivery semantics, and typed contracts.

Vendor plugin layer

Vendor-specific APIs, auth, model catalogs, speech synthesis, image generation, video backends, usage endpoints.

Channel/feature plugin layer

Discord/Slack/voice-call/etc. integration that consumes core capabilities and presents them on a surface.

For example, TTS follows this shape:

• core owns reply-time TTS policy, fallback order, prefs, and channel delivery
• elevenlabs, google, microsoft, and openai own synthesis implementations
• voice-call consumes the telephony TTS runtime helper

That same pattern should be preferred for future capabilities.

Multi-capability company plugin example

A company plugin should feel cohesive from the outside. If OpenClaw has shared contracts for models, speech, realtime transcription, realtime voice, media understanding, image generation, video generation, web fetch, and web search, a vendor can own all of its surfaces in one place:

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { exampleAiMedia } from "./exampleai-media.js";

export default definePluginEntry({
  id: "exampleai",
  name: "ExampleAI",
  description: "ExampleAI models and media capabilities.",
  register(api) {
    api.registerProvider({
      id: "exampleai",
      // auth/model catalog/runtime hooks
    });

    api.registerSpeechProvider({
      id: "exampleai",
      // vendor speech config — implement the SpeechProviderPlugin interface directly
    });

    api.registerMediaUnderstandingProvider({
      id: "exampleai",
      capabilities: ["image", "audio", "video"],
      describeImage: (req) => exampleAiMedia.describeImage(req),
      transcribeAudio: (req) => exampleAiMedia.transcribeAudio(req),
      describeVideo: (req) => exampleAiMedia.describeVideo(req),
    });

    api.registerWebSearchProvider({
      id: "exampleai-search",
      createTool() {
        // Return the vendor-owned web search tool.
      },
    });
  },
});

What matters is not the exact helper names. The shape matters:

• one plugin owns the vendor surface
• core still owns the capability contracts
• provider request translation and HTTP helpers stay in the vendor plugin
• channels and feature plugins consume api.runtime.* helpers, not vendor code
• contract tests can assert that the plugin registered the capabilities it claims to own

Capability example: video understanding

OpenClaw already treats image/audio/video understanding as one shared capability. The same ownership model applies there:

Core defines the contract

Core defines the media-understanding contract.

Vendor plugins register

Vendor plugins register describeImage, transcribeAudio, and describeVideo as applicable.

Consumers use the shared behavior

Channels and feature plugins consume the shared core behavior instead of wiring directly to vendor code.

That avoids baking one provider's video assumptions into core. The plugin owns the vendor surface; core owns the capability contract and fallback behavior.

Video generation already uses that same sequence: core owns the typed capability contract and runtime helper, and vendor plugins register api.registerVideoGenerationProvider(...) implementations against it.

Need a concrete rollout checklist? See Capability Cookbook.

Contracts and enforcement

The plugin API surface is intentionally typed and centralized in OpenClawPluginApi. That contract defines the supported registration points and the runtime helpers a plugin may rely on.

Why this matters:

• plugin authors get one stable internal standard
• core can reject duplicate ownership such as two plugins registering the same provider id
• startup can surface actionable diagnostics for malformed registration
• contract tests can enforce bundled-plugin ownership and prevent silent drift

There are two layers of enforcement:

Runtime registration enforcement

The plugin registry validates registrations as plugins load. Examples: duplicate provider ids, duplicate speech provider ids, and malformed registrations produce plugin diagnostics instead of undefined behavior.

Contract tests

Bundled plugins are captured in contract registries during test runs so OpenClaw can assert ownership explicitly. Today this is used for model providers, speech providers, web search providers, and bundled registration ownership.

The practical effect is that OpenClaw knows, up front, which plugin owns which surface. That lets core and channels compose seamlessly because ownership is declared, typed, and testable rather than implicit.

What belongs in a contract

Good contracts

• typed
• small
• capability-specific
• owned by core
• reusable by multiple plugins
• consumable by channels/features without vendor knowledge

Bad contracts

• vendor-specific policy hidden in core
• one-off plugin escape hatches that bypass the registry
• channel code reaching straight into a vendor implementation
• ad hoc runtime objects that are not part of OpenClawPluginApi or api.runtime

When in doubt, raise the abstraction level: define the capability first, then let plugins plug into it.

Execution model

Native OpenClaw plugins run in-process with the Gateway. They are not sandboxed. A loaded native plugin has the same process-level trust boundary as core code.

Warning

Native plugin implications: a plugin can register tools, network handlers, hooks, and services; a plugin bug can crash or destabilize the gateway; and a malicious native plugin is equivalent to arbitrary code execution inside the OpenClaw process.

Compatible bundles carry less risk by default, since OpenClaw currently interprets them as metadata and content packages. In the present releases, this mostly translates to bundled skills.

For anything that isn't a bundle, rely on allowlists and explicit install or load paths. Workspace plugins should be regarded as development-time code rather than production defaults.

When naming a bundled workspace package, anchor the plugin id inside the npm name: @openclaw/<id> by default, or an approved typed suffix such as -provider, -plugin, -speech, -sandbox, or -media-understanding when the package deliberately exposes a more limited plugin role.

Note

Trust note: plugins.allow trusts plugin ids, not where the source came from. A workspace plugin sharing an id with a bundled plugin intentionally overrides the bundled version when that workspace plugin is enabled or allowlisted. That behavior is expected and valuable for local development, testing patches, and applying hotfixes. Trust for bundled plugins is determined from the source snapshot, meaning the manifest and code present on disk at load time, not from install metadata. A corrupted or swapped install record cannot silently expand a bundled plugin's trust surface beyond what the actual source declares.

Export boundary

OpenClaw exposes capabilities, not implementation shortcuts.

Keep capability registration public. Cut back on non-contract helper exports:

• helper subpaths tied specifically to bundled plugins
• runtime plumbing subpaths never meant as public API
• convenience helpers aimed at particular vendors
• setup and onboarding helpers that remain internal details

Reserved helper subpaths for bundled plugins have been removed from the generated SDK export map. Keep owner-specific helpers inside the owning plugin package; only promote reusable host behavior to generic SDK contracts such as plugin-sdk/gateway-runtime, plugin-sdk/security-runtime, and injected plugin API capabilities.

Internals and reference

For details on the load pipeline, registry model, provider runtime hooks, Gateway HTTP routes, message tool schemas, channel target resolution, provider catalogs, context engine plugins, and the guide to adding a new capability, consult Plugin architecture internals.

Related

• Building plugins
• Plugin manifest
• Plugin SDK setup