OpenClaw 插件系统完全指南:从架构设计到实战开发

┌─────────────────────────────────────────────────────────────┐│                      消息渠道层                               ││  WhatsApp │ Telegram │ Slack │ Discord │ Signal │ iMessage  │└─────────────────────────────────────────────────────────────┘                              ↕┌─────────────────────────────────────────────────────────────┐│                    OpenClaw AI 网关                          ││  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          ││  │ 插件系统     │  │ 路由引擎     │  │ 会话管理      │           ││  └─────────────┘  └─────────────┘  └─────────────┘          │└─────────────────────────────────────────────────────────────┘                              ↕┌─────────────────────────────────────────────────────────────┐│                    AI 编码代理层                              ││        Claude │ GPT │ Gemini │ 本地模型 │ 自定义代理           │└─────────────────────────────────────────────────────────────┘

# 捆绑插件（随 OpenClaw 发行）extensions/├── core-plugin/├── voice-call/└── memory-core/# 工作区插件（项目级别）.openclaw/extensions/├── my-custom-plugin/└── team-shared-plugin/# npm 包（社区发布）npm install @openclaw/plugin-example

┌─────────────────────────────────────────────────────────────┐│                    插件发现优先级                             │├─────────────────────────────────────────────────────────────┤│  1. 配置路径    plugins.load.paths（显式定义）                  ││     ↓                                                       ││  2. 工作区扩展  .openclaw/extensions/*.ts（当前工作区）         ││     ↓                                                       ││  3. 全局扩展    ~/.openclaw/extensions/*.ts（用户级别）        ││     ↓                                                       ││  4. 捆绑插件    随网关发行的核心插件                             │└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐│                     PluginLoader                            ││  ┌─────────────────────────────────────────────────────┐    ││  │  1. 扫描插件目录                                      │    ││  │  2. 解析 openclaw.plugin.json                        │    ││  │  3. 创建 PluginManifestRecord                        │    ││  └─────────────────────────────────────────────────────┘    │└─────────────────────────────────────────────────────────────┘                              ↓┌─────────────────────────────────────────────────────────────┐│                     PluginRegistry                          ││  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          ││  │ Providers   │  │   Tools     │  │   Hooks     │          ││  └─────────────┘  └─────────────┘  └─────────────┘          ││  ┌─────────────┐  ┌─────────────┐                           ││  │  Channels   │  │  Services   │                           ││  └─────────────┘  └─────────────┘                           │└─────────────────────────────────────────────────────────────┘                              ↓┌─────────────────────────────────────────────────────────────┐│                     PluginRuntime                           ││  ┌─────────────────────────────────────────────────────┐    ││  │  为每个插件创建独立的执行上下文                          │    ││  │  提供对系统服务的受控访问                               │    ││  └─────────────────────────────────────────────────────┘    │└─────────────────────────────────────────────────────────────┘

┌─────────────────┐│  插件模块加载     │└────────┬────────┘         ↓┌─────────────────┐│  调用 register() │└────────┬────────┘         ↓┌─────────────────────────────────────────────────┐│              OpenClawPluginApi                  ││  ┌────────────────┐  ┌─────────────┐            ││  │registerProvider│  │ registerTool│            ││  └────────────────┘  └─────────────┘            ││  ┌─────────────┐  ┌────────────────┐            ││  │registerHook │  │registerChannel │            ││  └─────────────┘  └────────────────┘            ││  ┌───────────────┐                              ││  │registerService│                              ││  └───────────────┘                              │└─────────────────────────────────────────────────┘         ↓┌─────────────────┐│  PluginRegistry ││  存储注册信息     │└─────────────────┘

{  "plugins": {    "slots": {      "memory": "memory-lancedb",      "contextEngine": "advanced-context"    }  }}

┌─────────────────────────────────────────────────────────────┐│                   插件发现流程                                │├─────────────────────────────────────────────────────────────┤│  1. 扫描配置路径                                              ││     └─ 读取 plugins.load.paths                               ││                                                             ││  2. 扫描工作区扩展                                            ││     └─ 查找 .openclaw/extensions/ 目录                       ││                                                             ││  3. 扫描全局扩展                                              ││     └─ 查找 ~/.openclaw/extensions/ 目录                     ││                                                             ││  4. 扫描捆绑插件                                              ││     └─ 查找 OPENCLAW_BUNDLED_PLUGINS_DIR                     ││                                                             ││  5. 解析清单文件                                              ││     ├─ openclaw.plugin.json                                 ││     └─ package.json（含 openclaw 字段）                       ││                                                             ││  6. 创建 PluginManifestRecord                                ││     └─ 验证元数据                                             │└─────────────────────────────────────────────────────────────┘

// openclaw.plugin.json{  "id": "my-plugin",  "name": "My Custom Plugin",  "version": "1.0.0",  "description": "A custom plugin for OpenClaw",  "main": "dist/index.js",  "config": {    "schema": "./config.schema.json"  }}

// package.json（替代方案）{  "name": "@myorg/openclaw-plugin",  "version": "1.0.0",  "openclaw": {    "id": "my-plugin",    "main": "dist/index.js"  }}

// 插件加载流程async function loadPlugin(modulePath: string) {  // 使用 jiti 动态导入 TypeScript 模块  const module = await jiti.import(modulePath);  // 创建独立的运行时上下文  const runtime = new PluginRuntime(pluginId);  // 调用插件的 register 函数  await module.register(runtime.api);  return runtime;}

┌─────────────────────────────────────────────────────────────┐│                     主进程                                   ││  ┌─────────────────────────────────────────────────────┐    ││  │              PluginRegistry（全局）                  │    ││  └─────────────────────────────────────────────────────┘    │└─────────────────────────────────────────────────────────────┘                              ↑                          受控访问接口                              │┌─────────────────────────────────────────────────────────────┐│                   插件运行时层                                ││  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          ││  │Runtime (A)  │  │Runtime (B)  │  │Runtime (C)  │          ││  │ Plugin A    │  │ Plugin B    │  │ Plugin C    │          ││  └─────────────┘  └─────────────┘  └─────────────┘          │└─────────────────────────────────────────────────────────────┘

import { definePluginEntry } from 'openclaw/plugin-sdk/core';import { PluginRuntime } from 'openclaw/plugin-sdk/runtime';export defaultdefinePluginEntry({  id: 'my-plugin',  name: 'My Plugin',  version: '1.0.0',  async register(api: OpenClawPluginApi) {    // 注册模型提供商    await api.registerProvider({      id: 'my-provider',      name: 'My AI Provider',      authMethod: 'api-key',      // ... 其他配置    });    // 注册工具    await api.registerTool({      id: 'my-tool',      name: 'My Custom Tool',      factory: async (context) => {        return {          name: 'my_tool',          description: 'A custom tool',          execute: async (params) => { /* ... */ }        };      }    });    // 注册钩子    await api.registerHook({      event: 'onMessage',      handler: async (event) => {        console.log('Message received:', event);      }    });    // 注册通道    await api.registerChannel({      id: 'my-channel',      type: 'messaging',      // ... 其他配置    });    // 注册后台服务    await api.registerService({      id: 'my-service',      start: async () => { /* 启动服务 */ },      stop: async () => { /* 停止服务 */ }    });  }});

interface ProviderDefinition {  // 唯一标识符  id: string;  // 显示名称  name: string;  // 身份验证方法  authMethod: 'oauth' | 'api-key' | 'token';  // 基础 URL  baseUrl?: string;  // 环境变量覆盖  envVar?: string;  // 模型列表  models: ModelDefinition[];  // 推理处理  handleRequest: (request: InferenceRequest) => Promise;}

// OAuth 认证流程示例const authMethod: ProviderAuthMethod = {  type: 'oauth',  async initiate(context: ProviderAuthContext) {    // 生成 PKCE    const { verifier, challenge } = await generatePKCE();    // 构建授权 URL    const authUrl = buildAuthUrl({      clientId: process.env.CLIENT_ID,      redirectUri: 'http://localhost:3000/callback',      scope: ['openid', 'profile'],      codeChallenge: challenge    });    // 打开浏览器让用户授权    await context.prompter.openUrl(authUrl);    // 等待回调    const code = await waitForCallback();    // 交换令牌    const tokens = await exchangeCodeForTokens(code, verifier);    return tokens;  },  async refresh(refreshToken: string) {    // 刷新访问令牌    return await refreshAccessToken(refreshToken);  }};

interface OpenClawPluginToolContext {  // 会话 ID  sessionId: string;  // 代理 ID  agentId: string;  // 工作区目录  workspaceDir: string;  // 配置  config: Record;}// 工具工厂示例const toolFactory: OpenClawPluginToolFactory = async (context: OpenClawPluginToolContext) => {  return {    name: 'file_operations',    description: 'Perform file operations in the workspace',    parameters: {      type: 'object',      properties: {        operation: { type: 'string', enum: ['read', 'write', 'delete'] },        path: { type: 'string' }      }    },    execute: async (params) => {      const fullPath = path.join(context.workspaceDir, params.path);      // 执行文件操作      return { success: true };    }  };};

// 钩子注册示例await api.registerHook({  event: 'onMessage',  priority: 10, // 优先级（可选）  handler: async (event: MessageEvent) => {    // 处理消息事件    console.log(`Received message from {event.content}`);    // 可以修改消息    event.content = preprocessMessage(event.content);    // 或者阻止消息传递    // event.stopPropagation();  }});

import { z } from 'zod';// 配置模式示例const configSchema: OpenClawPluginConfigSchema = {  // UI 提示（用于表单渲染）  uiHints: {    apiKey: {      label: "API Key",      sensitive: true,  // 敏感字段，显示为密码输入      help: "Your provider API key"    },    model: {      label: "Default Model",      help: "Select the default model to use",      options: ["gpt-4", "gpt-3.5-turbo", "claude-3"]    },    maxTokens: {      label: "Max Tokens",      help: "Maximum tokens per request",      defaultValue: 4096    }  },  // JSON Schema（用于验证）  jsonSchema: {    type: "object",    properties: {      apiKey: {        type: "string",        minLength: 1      },      model: {        type: "string",        enum: ["gpt-4", "gpt-3.5-turbo", "claude-3"]      },      maxTokens: {        type: "integer",        minimum: 1,        maximum: 32000      }    },    required: ["apiKey"]  }};

// 配置验证流程async function validatePluginConfig(  pluginId: string,  config: unknown): Promise {  const schema = await loadConfigSchema(pluginId);  // 使用 Zod 进行验证  const result = schema.safeParse(config);  if (!result.success) {    return {      valid: false,      errors: result.error.errors.map(e => ({        path: e.path.join('.'),        message: e.message      }))    };  }  return { valid: true, data: result.data };}

{request.accessToken}`,        'Content-Type': 'application/json'      },      body: JSON.stringify(request.body)    });    return await response.json();  }};

┌─────────────────────────────────────────────────────────────┐│                    PKCE OAuth 流程                           │├─────────────────────────────────────────────────────────────┤│                                                             ││  1. 生成 PKCE 挑战                                           ││     ├─ 生成随机 verifier                                     ││     └─ 计算 challenge = SHA256(verifier)                    ││                                                             ││  2. 构建授权 URL                                             ││     ├─ 添加 client_id                                       ││     ├─ 添加 redirect_uri (localhost)                        ││     ├─ 添加 code_challenge                                  ││     └─ 添加 scope                                           ││                                                            ││  3. 用户授权                                                 ││     ├─ 打开浏览器                                            ││     └─ 用户登录并授权                                         ││                                                             ││  4. 接收回调                                                 ││     ├─ 本地服务器接收授权码                                    ││     └─ 验证 state 参数                                       ││                                                             ││  5. 交换令牌                                                 ││     ├─ 发送 code + verifier                                 ││     ├─ 服务器验证 PKCE                                       ││     └─ 返回 access_token + refresh_token                    ││                                                             ││  6. 存储凭据                                                 ││     └─ 安全存储令牌                                           ││                                                             │└─────────────────────────────────────────────────────────────┘

async function resolveOAuthToken(providerId: string): Promise {  const credentials = await credentialStore.get(providerId);  if (isExpired(credentials)) {    // 自动刷新令牌    const newTokens = await refreshOAuthToken(credentials.refreshToken);    await credentialStore.set(providerId, newTokens);    return newTokens.accessToken;  }  return credentials.accessToken;}

┌─────────────────────────────────────────────────────────────┐│                    语音通话架构                               │├─────────────────────────────────────────────────────────────┤│                                                             ││  ┌─────────────┐         ┌─────────────┐                    ││  │   Twilio    │◄───────►│  Webhook    │                    ││  │   Provider  │  HTTP   │  Server     │                    ││  └─────────────┘         └──────┬──────┘                    ││                                 │                           ││                          WebSocket│                         ││                                 ↓                           ││                          ┌─────────────┐                    ││                          │   Media     │                    ││                          │   Stream    │                    ││                          │   Handler   │                    ││                          └──────┬──────┘                    ││                                 │                           ││                          Audio Stream│                      ││                                 ↓                           ││                          ┌─────────────┐                    ││                          │    AI       │                    ││                          │   Provider  │                    ││                          │  (OpenAI)   │                    ││                          └─────────────┘                    ││                                                             │└─────────────────────────────────────────────────────────────┘

import { createHmac } from 'crypto';async function verifyTwilioProviderWebhook(  request: Request,  authToken: string): Promise {  const signature = request.headers['x-twilio-signature'];  const url = request.url;  const params = await request.formData();  // 构建签名数据  const data = url + Object.entries(params).sort().join('');  // 计算 HMAC  const expectedSignature = createHmac('sha1', authToken)    .update(data)    .digest('base64');  return signature === expectedSignature;}

import { RealtimeVoiceCallWebhookServer, MediaStreamHandler } from 'openclaw/plugin-sdk/webhook-ingress';const voiceServer = new RealtimeVoiceCallWebhookServer({  port: 8080,  path: '/voice',  async onCallStart(callSid: string, streamSid: string) {    // 初始化媒体流处理器    const mediaHandler = new MediaStreamHandler({      streamSid,      onAudioReceived: async (audioData) => {        // 发送到 AI 提供商处理        const response = await aiProvider.processAudio(audioData);        return response;      }    });    return mediaHandler;  }});

async function startStaleCallReaper() {  setInterval(async () => {    const staleCalls = await db.calls.findStale({      maxAge: 30 * 60 * 1000 // 30 分钟    });    for (const call of staleCalls) {      await cleanupCall(call.id);      console.log(`Cleaned up stale call: ${call.id}`);    }  }, 5 * 60 * 1000); // 每 5 分钟运行一次}

┌─────────────────────────────────────────────────────────────┐│                    注册流程                                  │├─────────────────────────────────────────────────────────────┤│                                                             ││  1. 发现                                                     ││     └─ resolveProviderSetupFlowContributions                ││        扫描已注册的插件以查找设置流程                            ││                                                             ││  2. 选择                                                     ││     └─ buildAuthChoiceGroups                                ││        用户看到分组选项                                        ││                                                             ││  3. 应用                                                     ││     └─ applyNonInteractiveAuthChoice                        ││        将选择持久化到 openclaw.json 或 auth-profiles.json      ││                                                             │└─────────────────────────────────────────────────────────────┘

// openclaw.json - 引用模式（推荐）{  "providers": {    "openai": {      "apiKey": "env:OPENAI_API_KEY"    },    "google": {      "credentials": "env:GOOGLE_CREDENTIALS_PATH"    }  }}// openclaw.json - 纯文本模式（不推荐）{  "providers": {    "openai": {      "apiKey": "sk-xxxxxxxxxxxxxxxx"    }  }}

# .env 文件示例OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxGOOGLE_API_KEY=AIzaxxxxxxxxxxxxxxANTHROPIC_API_KEY=sk-ant-xxxxxxxx

┌─────────────────────────────────────────────────────────────┐│                    插件开发流程                               │├─────────────────────────────────────────────────────────────┤│                                                             ││  1. 规划                                                     ││     ├─ 确定插件类型（提供商/工具/钩子/通道）                      ││     ├─ 设计配置模式                                           ││     └─ 规划身份验证方式                                        ││                                                             ││  2. 开发                                                     ││     ├─ 创建插件目录结构                                        ││     ├─ 实现核心功能                                           ││     ├─ 编写配置模式                                           ││     └─ 实现身份验证                                           ││                                                             ││  3. 测试                                                     ││     ├─ 编写单元测试                                           ││     ├─ 编写集成测试                                           ││     └─ 手动测试                                              ││                                                             ││  4. 部署                                                     ││     ├─ 本地安装测试                                           ││     ├─ 发布到 npm（可选）                                     ││     └─ 编写文档                                              ││                                                             ││  5. 维护                                                     ││     ├─ 处理问题反馈                                           ││     ├─ 发布更新                                              ││     └─ 保持兼容性                                             ││                                                             │└─────────────────────────────────────────────────────────────┘

# 查看插件状态openclaw plugins list# 启用调试日志DEBUG=openclaw:plugin:* openclaw start# 测试特定插件openclaw plugins test my-plugin# 验证配置模式openclaw plugins validate my-plugin

DEBUG=openclaw:* openclaw start