Plugin SDK

The OpenClaw Plugin SDK defines how plugins interact with the core system. The SDK is exposed to external plugins through the openclaw/plugin-sdk export path.

Core Interface

Source: src/plugins/types.ts

OpenClawPluginApi

// src/plugins/types.ts (simplified)
interface OpenClawPluginApi {
  // Plugin metadata
  id: string;
  name: string;
  version: string;

  // Registration methods
  registerTool(registration: PluginToolRegistration): void;
  registerChannel(registration: PluginChannelRegistration): void;
  registerHook(registration: PluginHookRegistration): void;
  registerHttp(registration: PluginHttpRegistration): void;
  registerService(registration: PluginServiceRegistration): void;
}

Tool Factory

Tools are registered through a factory pattern -- each time an Agent session is created, the factory function is called to produce tool instances:

// Tool factory pattern
type OpenClawPluginToolFactory = (
  ctx: OpenClawPluginToolContext
) => AnyAgentTool | AnyAgentTool[] | null | undefined;

The factory function receives context and can decide which tools to provide based on session state:

// Tool context
interface OpenClawPluginToolContext {
  config: PluginConfig;        // Plugin configuration
  workspaceDir: string;        // Agent workspace directory
  agentDir: string;            // Agent-specific directory
  agentId: string;             // Current agent ID
  sessionKey: string;          // Current session key
  messageChannel: string;      // Message source channel
  sandboxed: boolean;          // Is sandbox mode active
}

Channel Registration

// Channel registration
interface PluginChannelRegistration {
  plugin: ChannelPlugin;       // Full channel plugin implementation
  dock: ChannelDock;           // Lightweight metadata
}

Tool Registration

// Tool registration
interface PluginToolRegistration {
  factory: OpenClawPluginToolFactory;
  names: string[];              // Tool names this factory provides
  optional?: boolean;           // Can be disabled by user
}

Registration Example

// Example: GitHub skill plugin (conceptual)
export default function(api: OpenClawPluginApi) {
  api.registerTool({
    factory: (ctx) => {
      // Only provide tools if GitHub token is configured
      if (!ctx.config.githubToken) return null;

      return [
        createGitHubSearchTool(ctx),
        createGitHubIssueTool(ctx),
        createGitHubPRTool(ctx),
      ];
    },
    names: ["github_search", "github_issue", "github_pr"],
    optional: true,
  });
}

Service Registration

Background services are for continuously running tasks:

interface PluginServiceRegistration {
  // Service lifecycle
  start(): Promise<void>;
  stop(): Promise<void>;
}

HTTP Registration

Plugins can register HTTP routes on the Gateway's HTTP server:

interface PluginHttpRegistration {
  // HTTP route handlers
  // Mounted on Gateway's HTTP server
}

Summary

• OpenClawPluginApi is the main interface for plugin-to-core interaction
• Tools are registered via a factory pattern, dynamically generated based on context
• OpenClawPluginToolContext provides session, configuration, and sandbox state
• Five registration types are supported: tools, channels, hooks, HTTP, services
• The SDK is exposed through the openclaw/plugin-sdk export path

Next: Extension Loading