Plugins — Extensible Plugin Ecosystem

Architecture

The plugin system is organized into four major subsystems: Discovery scans plugin roots and parses manifests into a cache; Loading evaluates enable/disable config state and uses jiti to lazily import plugin code; Registration builds the plugin API surface and populates the central registry with hooks, tools, and channels; and the MCP Bridge extracts MCP server configuration from bundles for external tool serving.

flowchart TD
  subgraph Discovery["Plugin Discovery"]
    Roots["Plugin Roots"]
    Scan["Directory Scanner"]
    Manifest["Manifest Parser"]
    Cache["Discovery Cache"]
  end
  subgraph Loading["Plugin Loading"]
    ConfigState["Config State"]
    Enable["Enable/Disable Logic"]
    Jiti["Jiti Loader"]
    Runtime["Plugin Runtime"]
  end
  subgraph Registration["Capability Registration"]
    API["Plugin API Builder"]
    Registry["Plugin Registry"]
    Hooks["Hook Runner"]
    Tools["Tool Factory"]
  end
  subgraph Bridge["MCP Bridge"]
    BundleMCP["Bundle MCP Config"]
    MCPServers["MCP Server Map"]
    ToolServe["Tool Serving"]
  end
  Roots --> Scan
  Scan --> Manifest
  Manifest --> Cache
  Cache --> ConfigState
  ConfigState --> Enable
  Enable --> Jiti
  Jiti --> Runtime
  Runtime --> API
  API --> Registry
  Registry --> Hooks
  Registry --> Tools
  Runtime --> BundleMCP
  BundleMCP --> MCPServers
  MCPServers --> ToolServe

Plugin Lifecycle

The lifecycle of a plugin spans from discovery through registration to runtime hook execution. The application kicks off discovery by scanning configured plugin roots. Each discovered manifest is loaded into a registry of static metadata. The runtime then resolves enable states, lazily imports plugin modules via jiti, and calls each plugin's register() function with a typed API surface. Hooks registered during this phase are later invoked by the hook runner with priority-based ordering.

sequenceDiagram
  participant App as Application
  participant Disc as Discovery
  participant Man as Manifest Registry
  participant Loader as Plugin Loader
  participant Reg as Plugin Registry
  participant Hook as Hook Runner
  App->>Disc: discoverOpenClawPlugins(roots)
  Disc->>Man: loadPluginManifestRegistry()
  Man-->>Disc: manifest[] (static metadata)
  Disc-->>App: PluginCandidate[]
  App->>Loader: resolveRuntimePluginRegistry()
  Loader->>Loader: resolveEffectiveEnableState()
  Loader->>Loader: createJiti() + import plugin
  Loader->>Reg: buildPluginApi() → register()
  Reg->>Reg: registerHook / registerTool / registerChannel
  Reg-->>Loader: PluginRegistry
  App->>Hook: runHook('before_agent_start', event)
  Hook->>Hook: sort by priority
  Hook->>Hook: execute handlers sequentially
  Hook-->>App: accumulated result

Key Types

The plugin system defines a rich set of TypeScript types and interfaces that form the contract between the host application and plugin code.

Hook Execution Pipeline

Hooks are the primary extension mechanism in the plugin system. When the application invokes runHook(name, event), the hook runner collects all registered handlers for that hook name, sorts them by priority (highest first, with pluginId as a tiebreaker for equal priorities), and executes them sequentially. Each handler receives the current accumulated result and can transform or extend it. Results are merged via mergeResults(). A handler can signal early exit through shouldStop(), which terminates the pipeline and logs the terminal decision. This allows plugins to override default behavior or short-circuit processing when needed.

flowchart LR
  Sort["Sort by Priority"] --> Exec["Execute Handler"]
  Exec --> Merge["mergeResults(acc, next)"]
  Merge --> Stop{"shouldStop?"}
  Stop -->|No| Exec
  Stop -->|Yes| Return["Return Result"]
  Merge -->|All done| Return

Sub-modules

The plugin system is composed of several focused sub-modules, each handling a distinct concern in the plugin lifecycle.

Directory Map

Code Examples

Plugin Registration

A plugin exports a default object with a register() method. The API surface passed to register() provides typed methods for hooking into the lifecycle, registering tools, and declaring capabilities.

// Example: Registering a plugin with hooks and tools
import type { OpenClawPluginDefinition } from "./types.js";

export default {
  register(api) {
    // Register a lifecycle hook
    api.registerHook("before_agent_start", {
      priority: 100,
      handler: async (event) => {
        api.logger.info("Agent starting for", event.channelId);
        return { extraSystemPrompt: "You are helpful." };
      },
    });

    // Register a custom tool
    api.registerTool({
      name: "my-plugin-lookup",
      description: "Looks up data from my service",
      parameters: { query: { type: "string" } },
      execute: async ({ query }) => {
        return { result: await fetchFromService(query) };
      },
    });
  },
} satisfies OpenClawPluginDefinition;

Plugin Manifest

Every plugin must include an openclaw.plugin.json manifest that declares its identity, config schema, and capabilities. The manifest is validated statically before any plugin code is imported.

// openclaw.plugin.json — Plugin manifest
{
  "id": "my-custom-plugin",
  "name": "My Custom Plugin",
  "version": "1.0.0",
  "enabledByDefault": false,
  "configSchema": {
    "apiEndpoint": { "type": "string", "default": "https://api.example.com" }
  },
  "providers": ["my-provider"],
  "providerAuthEnvVars": {
    "my-provider": ["MY_PROVIDER_API_KEY"]
  }
}