跳到主要内容

插件开发

扩展 OpenClaw 功能的核心方式

6.1 什么是插件？​

插件是小型代码模块，用额外功能扩展 OpenClaw，包括：

  • 新的聊天渠道（如 Microsoft Teams、Matrix）
  • 新的智能体工具
  • 自定义 CLI 命令
  • 后台服务
  • 自动化钩子

6.2 快速开始​

查看已加载的插件​

openclaw plugins list

安装官方插件​

# 安装语音通话插件
openclaw plugins install @openclaw/voice-call

# 安装飞书插件
openclaw plugins install @openclaw/feishu

# 安装 Teams 插件
openclaw plugins install @openclaw/msteams

安装本地插件​

# 从本地目录安装
openclaw plugins install ./extensions/my-plugin

# 从 tarball 安装
openclaw plugins install ./plugin.tgz

6.3 插件结构​

基础目录结构​

my-plugin/
├── openclaw.plugin.json    # 插件清单（必需）
├── index.ts                # 入口文件
├── src/
│   └── ...
├── skills/                 # 可选：附带 Skills
└── README.md

openclaw.plugin.json 清单​

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "A sample plugin",
  "configSchema": {
    "type": "object",
    "properties": {
      "apiKey": { "type": "string" }
    }
  },
  "uiHints": {
    "apiKey": { "label": "API Key", "sensitive": true }
  }
}

6.4 编写第一个插件​

入口文件​

// index.ts
export default function register(api) {
  // 注册 Gateway RPC 方法
  api.registerGatewayMethod("myplugin.status", ({ respond }) => {
    respond(true, { ok: true, message: "Plugin is running!" });
  });

  // 注册 CLI 命令
  api.registerCli(({ program }) => {
    program
      .command("mycmd")
      .description("My custom command")
      .action(() => {
        console.log("Hello from my plugin!");
      });
  }, { commands: ["mycmd"] });

  // 注册自动回复命令
  api.registerCommand({
    name: "hello",
    description: "Say hello",
    handler: (ctx) => ({
      text: `Hello! I'm ${ctx.channel} bot.`
    })
  });
}

导出方式​

插件可以导出以下之一：

// 方式1：函数
export default function(api) { ... }

// 方式2：对象
export default {
  id: "my-plugin",
  name: "My Plugin",
  configSchema: { ... },
  register(api) { ... }
}

6.5 注册智能体工具​

插件可以注册供 AI 使用的工具：

import { registerTool } from "openclaw/plugin-sdk";

export default function(api) {
  registerTool(api, {
    name: "my_tool",
    description: "Do something useful",
    parameters: {
      type: "object",
      properties: {
        input: { type: "string", description: "Input text" }
      },
      required: ["input"]
    },
    handler: async ({ input }, ctx) => {
      // 处理逻辑
      return { result: `Processed: ${input}` };
    }
  });
}

6.6 注册消息渠道​

插件可以添加新的聊天渠道：

const myChannel = {
  id: "mychat",
  meta: {
    id: "mychat",
    label: "MyChat",
    selectionLabel: "MyChat (API)",
    docsPath: "/channels/mychat",
    blurb: "My custom chat channel",
    aliases: ["mc"]
  },
  capabilities: { chatTypes: ["direct", "group"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.mychat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.mychat?.accounts?.[accountId ?? "default"] ?? { accountId }
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text, to }) => {
      // 发送消息到你的渠道
      return { ok: true };
    }
  }
};

export default function(api) {
  api.registerChannel({ plugin: myChannel });
}

6.7 注册后台服务​

export default function(api) {
  api.registerService({
    id: "my-service",
    start: () => {
      api.logger.info("My service starting...");
      // 初始化服务
    },
    stop: () => {
      api.logger.info("My service stopping...");
      // 清理资源
    }
  });
}

6.8 配置管理​

插件配置​

{
  "plugins": {
    "entries": {
      "my-plugin": {
        "enabled": true,
        "config": {
          "apiKey": "your-api-key"
        }
      }
    }
  }
}

配置验证​

清单中的 JSON Schema 会在配置时验证：

{
  "configSchema": {
    "type": "object",
    "properties": {
      "apiKey": { "type": "string" },
      "endpoint": { "type": "string", "format": "uri" }
    },
    "required": ["apiKey"]
  }
}

6.9 插件发现与优先级​

OpenClaw 按顺序扫描以下位置：

  1. 配置路径 — plugins.load.paths
  2. 工作区扩展 — ~/.openclaw/extensions/*.ts
  3. 全局扩展 — /Users/john/.openclaw/extensions/*.ts
  4. 捆绑扩展 — 内置但默认禁用

包集合​

插件目录可以包含多个插件：

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"]
  }
}

6.10 CLI 命令参考​

# 列出所有插件
openclaw plugins list

# 查看插件详情
openclaw plugins info <id>

# 安装插件
openclaw plugins install @openclaw/voice-call
openclaw plugins install ./local-plugin

# 链接模式（开发时）
openclaw plugins install -l ./my-plugin

# 更新插件
openclaw plugins update <id>
openclaw plugins update --all

# 启用/禁用
openclaw plugins enable <id>
openclaw plugins disable <id>

# 诊断
openclaw plugins doctor

6.11 官方插件列表​

插件说明
@openclaw/feishu飞书聊天渠道
@openclaw/voice-call语音通话（Twilio）
@openclaw/msteamsMicrosoft Teams
@openclaw/matrixMatrix 协议
@openclaw/nostrNostr 去中心化消息
@openclaw/zaloZalo 越南聊天

6.12 安全注意事项​

  • 插件与 Gateway 在同一进程运行，视为受信任代码
  • 只安装你信任的插件
  • 建议使用 plugins.allow 允许列表
  • 配置更改后需重启 Gateway