<!-- source: https://deepwiki.com/openclaw/openclaw/5.1-plugin-architecture -->

# Plugin Architecture

- docs/.generated/plugin-sdk-api-baseline.sha256
- docs/plugins/manifest.md
- docs/plugins/plugin-inventory.md
- docs/plugins/reference.md
- docs/plugins/sdk-migration.md
- docs/plugins/sdk-subpaths.md
- extensions/acpx/npm-shrinkwrap.json
- extensions/amazon-bedrock-mantle/npm-shrinkwrap.json
- extensions/amazon-bedrock/npm-shrinkwrap.json
- extensions/anthropic-vertex/npm-shrinkwrap.json
- extensions/codex/npm-shrinkwrap.json
- extensions/diagnostics-otel/npm-shrinkwrap.json
- extensions/discord/index.ts
- extensions/discord/npm-shrinkwrap.json
- extensions/feishu/openclaw.plugin.json
- extensions/google-meet/src/realtime-node.ts
- extensions/google-meet/src/realtime.ts
- extensions/memory-core/src/memory/provider-adapters.ts
- extensions/memory-lancedb/npm-shrinkwrap.json
- extensions/tsconfig.package-boundary.paths.json
- extensions/twitch/npm-shrinkwrap.json
- extensions/whatsapp/npm-shrinkwrap.json
- extensions/xai/tsconfig.json
- npm-shrinkwrap.json
- package.json
- pnpm-lock.yaml
- pnpm-workspace.yaml
- scripts/check-plugin-sdk-exports.mjs
- scripts/lib/bundled-plugin-build-entries.mjs
- scripts/lib/extension-package-boundary.ts
- scripts/lib/plugin-sdk-entries.d.mts
- scripts/lib/plugin-sdk-entries.mjs
- scripts/lib/plugin-sdk-entrypoints.json
- scripts/lib/plugin-sdk-private-local-only-subpaths.json
- scripts/prepare-extension-package-boundary-artifacts.mjs
- scripts/release-check.ts
- scripts/run-node-watch-paths.mjs
- scripts/watch-node.mjs
- scripts/write-plugin-sdk-entry-dts.ts
- src/gateway/server-startup-log.test.ts
- src/gateway/server-startup-log.ts
- src/gateway/server.lazy.test.ts
- src/infra/git-commit.test.ts
- src/infra/npm-managed-root.test.ts
- src/infra/npm-managed-root.ts
- src/infra/tsdown-config.test.ts
- src/infra/watch-node.test.ts
- src/plugin-sdk/entrypoints.ts
- src/plugin-sdk/memory-core-host-embedding-registry.ts
- src/plugin-sdk/realtime-voice.ts
- src/plugins/config-contract-matches.ts
- src/plugins/config-contracts.test.ts
- src/plugins/config-contracts.ts
- src/plugins/discovery-threading.test.ts
- src/plugins/discovery.test.ts
- src/plugins/discovery.ts
- src/plugins/install.npm-spec.e2e.test.ts
- src/plugins/install.npm-spec.test.ts
- src/plugins/install.test.ts
- src/plugins/install.ts
- src/plugins/installed-plugin-index-registry.ts
- src/plugins/installed-plugin-index-types.ts
- src/plugins/loader.native-module-loader.test.ts
- src/plugins/loader.runtime-registry.test.ts
- src/plugins/loader.test-fixtures.ts
- src/plugins/loader.test.ts
- src/plugins/loader.ts
- src/plugins/manifest-registry.test.ts
- src/plugins/manifest-registry.ts
- src/plugins/manifest-tool-availability.ts
- src/plugins/manifest.ts
- src/plugins/package-entry-resolution.ts
- src/plugins/plugin-graceful-init-failure.test.ts
- src/plugins/plugin-sdk-dist-alias.ts
- src/plugins/plugin-sdk-native-resolver.test.ts
- src/plugins/plugin-sdk-native-resolver.ts
- src/plugins/registry.ts
- src/plugins/runtime/standalone-runtime-registry-loader.test.ts
- src/plugins/sdk-alias.test.ts
- src/plugins/sdk-alias.ts
- src/plugins/tools.optional.test.ts
- src/plugins/tools.ts
- src/security/dangerous-config-flags-current-snapshot.test.ts
- src/security/dangerous-config-flags-current.ts
- src/security/dangerous-config-flags.ts
- src/talk/output-activity-tracker.test.ts
- src/talk/output-activity-tracker.ts
- test/helpers/gateway-e2e-harness.test.ts
- test/helpers/gateway-e2e-harness.ts
- test/release-check.test.ts
- test/scripts/bundled-plugin-build-entries.test.ts
- test/scripts/prepare-extension-package-boundary-artifacts.test.ts
- test/scripts/watch-node.test.ts
- test/vitest/vitest.shared.config.ts
- tsconfig.json
- tsdown.config.ts

This page documents OpenClaw's plugin system comprehensively, explaining the Plugin SDK, registration APIs, the various plugin exports (providers, tools, hooks), and the discovery process. It covers the manifest-driven architecture centered around `openclaw.plugin.json`, the activation planner, capability availability checks, and the plugin boundary enforcement system that ensures security and stability.

## Overview

OpenClaw's plugin architecture is a modular extensibility framework enabling dynamic integration of new capabilities such as model providers, tools, messaging channels, and hooks without modifying core code. Plugins are first-class citizens that register themselves through a rich SDK and expose capabilities following strict contracts.

Key framework components:

- PluginRegistry : Central record keeper for plugins and registrations per capability src/plugins/registry.ts 137-140
- Plugin SDK : Typed interface presented to plugins during registration (via register(api) ) to add providers, tools, and hooks src/plugins/api-builder.ts 25-28
- Plugin Manifest : Discovered metadata ( openclaw.plugin.json ) enables manifest-driven discovery and capability activation without executing plugin code src/plugins/manifest.ts 61-63
- Activation Planner : Decides when plugins should load based on manifest activation hints such as onStartup or presence of requested providers/channels src/plugins/loader.ts 46-51
- Capability Boundary Enforcement : Ensures only enabled and authorized plugins participate, rejecting potentially dangerous plugins or invalid states src/plugins/loader.ts 63-64

Plugins have shapes - e.g., provider-only, hook-only, or hybrid - that define what registration methods they can expose [src/plugins/loader.ts163-171](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L163-L171)

Sources: [src/plugins/registry.ts137-140](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/registry.ts#L137-L140) [src/plugins/api-builder.ts25-28](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/api-builder.ts#L25-L28) [src/plugins/manifest.ts61-63](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/manifest.ts#L61-L63) [src/plugins/loader.ts46-51](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L46-L51) [src/plugins/loader.ts63-64](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L63-L64) [src/plugins/loader.ts163-171](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L163-L171)

## Plugin Discovery and Loading

### Discovery Mechanism

OpenClaw discovers plugins by scanning directories for manifests or explicit paths defined in the configuration. The discovery order respects explicit user paths, workspace-level plugins, global installations, and finally built-in bundled plugins:

- Explicit Load Paths : Plugins explicitly loaded from user config paths.
- Workspace Extensions : Plugins in extensions/ within the current workspace pnpm-workspace.yaml 5
- Global Extensions : Usually in a global user directory path.
- Bundled Plugins : Packaged with OpenClaw; discovered using OPENCLAW_BUNDLED_PLUGINS_DIR src/plugins/loader.test.ts 204

Discovery results in a list of `PluginCandidate` objects representing possible plugins with their paths and manifest data [src/plugins/loader.ts54-57](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L54-L57) The `discoverOpenClawPlugins` function handles the recursive scanning and identification of plugin roots [src/plugins/discovery.ts54-57](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/discovery.ts#L54-L57)

```

```

### Plugin Loading and Activation Planning

The main loading routine `loadOpenClawPlugins` takes the discovered manifests and activation hints to decide which plugins to import and execute their `register(api)` calls [src/plugins/loader.ts53-57](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L53-L57)

- The Activation Planner evaluates activation conditions such as: Load on gateway startup ( onStartup ). Load on provider requests ( onProviders ). Load on messaging channel presence ( onChannels ) src/plugins/loader.ts 46-51
- loadOpenClawPlugins then dynamically imports plugin entry points and calls their registration functions with an instance of OpenClawPluginApi src/plugins/loader.ts 28-30
- The API is the plugin's main interface to register capabilities into the global PluginRegistry src/plugins/registry.ts 137-140

```

```

Sources: [src/plugins/loader.ts46-57](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L46-L57) [src/plugins/registry.ts137-140](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/registry.ts#L137-L140) [src/plugins/loader.test.ts204](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.test.ts#L204-L204) [pnpm-workspace.yaml5](https://github.com/openclaw/openclaw/blob/fbdf5937/pnpm-workspace.yaml#L5-L5) [src/plugins/discovery.ts54-57](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/discovery.ts#L54-L57)

## Plugin SDK and Capability Registration API

The **Plugin SDK** is exposed as narrow public subpaths under `openclaw/plugin-sdk/` [docs/plugins/sdk-subpaths.md9-10](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/plugins/sdk-subpaths.md?plain=1#L9-L10) Upon load, the plugin receives an instance of `OpenClawPluginApi` exposing registration methods [src/plugins/loader.ts165-171](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L165-L171):

### SDK Subpaths

The SDK is modularized to prevent broad barrel imports. Key subpaths include:

- plugin-sdk/plugin-entry : Basic entry point definitions docs/plugins/sdk-subpaths.md 26
- plugin-sdk/core : Channel and setup plugin primitives docs/plugins/sdk-subpaths.md 27
- plugin-sdk/config-schema : Root configuration schemas docs/plugins/sdk-subpaths.md 28
- plugin-sdk/health : Diagnostic health-check registration docs/plugins/sdk-subpaths.md 32

### Capability Availability Checks and Filtering

OpenClaw enforces capability boundary restrictions:

- Only enabled plugins from the InstalledPluginIndex participate at runtime src/plugins/loader.ts 66-67
- Plugins declare capabilities in openclaw.plugin.json so the system can reason about them before loading code src/plugins/loader.ts 98-101

Sources: [src/plugins/loader.ts165-171](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L165-L171) [docs/plugins/sdk-subpaths.md9-32](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/plugins/sdk-subpaths.md?plain=1#L9-L32) [src/plugins/loader.ts66-101](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L66-L101)

## Plugin Manifests: The openclaw.plugin.json File

Each native plugin must include an `openclaw.plugin.json` manifest file that exposes metadata [src/plugins/loader.test.ts177-179](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.test.ts#L177-L179):

OpenClaw leverages the manifest for **discovery, validation, and planning load activation** without executing plugin code [src/plugins/loader.ts98-101](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L98-L101)

Sources: [src/plugins/loader.test.ts177-179](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.test.ts#L177-L179) [src/plugins/loader.ts98-101](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L98-L101)

## Plugin Boundary Enforcement System

### Security and Sandboxing

Plugin boundary enforcement is critical to maintain the host's integrity and security.

- Security Scan : Installation runs static analysis ( scanBundleInstallSource , scanPackageInstallSource ) to detect dangerous operations src/plugins/install.test.ts 38-43
- Integrity Checks : NPM plugin integrity hashes are validated against registry metadata src/plugins/install.ts 13-14
- Managed NPM Root : Plugins are installed under a controlled managed root ( _openclaw-managed-npm ) with peer dependencies linked to the Gateway host src/plugins/install.ts 27

### Manifest-Driven Restrictions

- Version Compatibility : The system checks minHostVersion and pluginApi ranges in package.json src/plugins/install.ts 112-116 src/plugins/install.ts 150-165
- Slot Isolation : Slot declarations prevent multiple plugins from occupying exclusive roles, such as memory backends src/plugins/loader.ts 163
- SDK Alias Enforcement : The loader ensures plugins import the correct SDK version via a virtual alias system src/plugins/sdk-alias.ts 12-21 This maps openclaw/plugin-sdk imports to either the source ( src/ ) or distribution ( dist/ ) folders depending on the environment src/plugins/sdk-alias.ts 150-165

### Installation and Removal

- Install : Plugins can be installed from archives, directories, or NPM specs src/plugins/install.ts 12-17
- Uninstall : Removal operations clean up directories and indices safely src/plugins/install.ts 21

Sources: [src/plugins/install.test.ts38-43](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/install.test.ts#L38-L43) [src/plugins/install.ts12-27](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/install.ts#L12-L27) [src/plugins/install.ts112-165](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/install.ts#L112-L165) [src/plugins/loader.ts163](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L163-L163) [src/plugins/sdk-alias.ts12-165](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/sdk-alias.ts#L12-L165)

## Tool and Hook Export System

Plugins augment the agent runtime through specific exports:

- Tools : Registered using api.registerTool , providing Zod/JSON schemas and execution handlers src/plugins/registry.ts 150-153
- Hooks : Offer lifecycle event subscriptions (e.g., before_prompt_build ) to modify runtime behavior src/plugins/registry.ts 21-22
- Interactive Handlers : Register handlers for UI-driven interactions src/plugins/loader.ts 69-72

Sources: [src/plugins/registry.ts21-22](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/registry.ts#L21-L22) [src/plugins/registry.ts150-153](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/registry.ts#L150-L153) [src/plugins/loader.ts69-72](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L69-L72)

## Diagrams Bridging Natural Language and Code Entities

### Activation and Capability Flow

This diagram shows how natural language concepts of activation map onto code-level components:

```

```

Sources: [src/plugins/loader.ts46-57](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L46-L57) [src/plugins/manifest-registry.ts98-101](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/manifest-registry.ts#L98-L101)

### Manifest & Registry Management Flow

This diagram relates plugin artifacts on disk to their representation in the internal registry and index systems:

```

```

Sources: [src/plugins/loader.ts54-57](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L54-L57) [src/plugins/manifest-registry.ts98-101](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/manifest-registry.ts#L98-L101) [src/plugins/registry.ts137-140](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/registry.ts#L137-L140)

# Summary

OpenClaw's plugin architecture is a manifest-driven, capability-based system enabling flexible extension of the gateway. The manifest `openclaw.plugin.json` lies at the heart of the discovery and activation system, enabling selective, safe, and policy-driven plugin integration. The Plugin SDK provides the API surface for plugins to register providers, channels, tools, and hooks. The architecture includes rigorous boundary enforcement mechanisms-security scanning, manifest validation, and activation planning-to ensure runtime safety.

# References

- src/plugins/registry.ts
- src/plugins/api-builder.ts
- src/plugins/loader.ts
- src/plugins/manifest.ts
- src/plugins/manifest-registry.ts
- src/plugins/install.ts
- src/plugins/sdk-alias.ts
- docs/plugins/sdk-subpaths.md

Sources: [src/plugins/registry.ts1-182](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/registry.ts#L1-L182) [src/plugins/api-builder.ts1-60](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/api-builder.ts#L1-L60) [src/plugins/loader.ts1-188](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/loader.ts#L1-L188) [src/plugins/manifest.ts1-100](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/manifest.ts#L1-L100) [src/plugins/manifest-registry.ts1-150](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/manifest-registry.ts#L1-L150) [src/plugins/install.ts1-180](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/install.ts#L1-L180) [src/plugins/sdk-alias.ts1-165](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/sdk-alias.ts#L1-L165) [docs/plugins/sdk-subpaths.md1-85](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/plugins/sdk-subpaths.md?plain=1#L1-L85)
