插件 SDK

OpenClaw Plugin SDK 定义了插件如何与核心系统交互。SDK 通过 openclaw/plugin-sdk 导出路径暴露给外部插件。

核心接口

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;
}

工具工厂

工具通过 factory 模式注册——每次 Agent 会话创建时，工厂函数被调用以生成工具实例：

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

工厂函数接收上下文，可以根据会话状态决定提供哪些工具：

// 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
interface PluginChannelRegistration {
  plugin: ChannelPlugin;       // Full channel plugin implementation
  dock: ChannelDock;           // Lightweight metadata
}

工具注册

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

注册示例

// 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,
  });
}

服务注册

后台服务用于持续运行的任务：

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

HTTP 注册

插件可以注册 HTTP 路由到 Gateway 的 HTTP 服务器：

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

小结

• OpenClawPluginApi 是插件与核心系统交互的主接口
• 工具通过 factory 模式 注册，根据上下文动态生成
• OpenClawPluginToolContext 提供会话、配置和沙箱状态
• 支持五种注册类型：工具、通道、Hook、HTTP、服务
• SDK 通过 openclaw/plugin-sdk 导出路径暴露

下一章：Extension 加载