第16章 Plugins —— 插件系统开发指南

OpenClaw 设计了强大的插件系统，让你可以扩展核心功能，添加新的聊天渠道、模型提供者、工具、技能等。本章我们讲解插件系统架构，以及如何开发自己的插件。

什么是插件

插件就是一个独立的代码模块，扩展 OpenClaw 核心功能，不用改核心代码就能添加新能力：

• 添加新的聊天渠道（比如一个新的聊天 App）
• 添加新的模型认证提供者
• 添加新的 agent 工具
• 添加新的 CLI 命令
• 添加后台服务
• 打包技能分享给其他人

插件进程内加载，和 Gateway 一起运行，性能好，开发简单。

插件清单文件 openclaw.plugin.json

每个插件必须有一个 openclaw.plugin.json 在插件根目录。OpenClaw 用它来验证配置，不需要运行插件代码就能验证。

必需字段

这段配置写在插件根目录的 ./openclaw.plugin.json：

可选字段

常用 CLI 命令

# 列出所有插件
openclaw plugins list

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

# 启用插件
openclaw plugins enable <id>

# 禁用插件
openclaw plugins disable <id>

# 安装插件（从 npm）
openclaw plugins install <npm-package>
openclaw plugins install ./local-path  # 本地开发
openclaw plugins install ./local-path -l  # 链接不复制，开发用

# 卸载插件
openclaw plugins uninstall <id>

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

# 检查插件健康
openclaw plugins doctor

插件配置

配置示例（写在你的主配置文件 ~/.openclaw/openclaw.json）：

{
  plugins: {
    enabled: true,            // 总开关，默认 true
    allow: ["voice-call"],    // 允许列表
    deny: ["untrusted-plugin"], // 拒绝列表，deny 优先
    load: { paths: ["~/my-plugin"] }, // 额外加载路径
    entries: {
      "voice-call": {
        enabled: true,
        config: { provider: "twilio" }, // 插件配置，按照你的 JSON Schema 验证
      },
    },
    slots: { // 排他插槽，同一时间只能有一个启用
      memory: "memory-lancedb", // 记忆插件只能选一个
    },
  },
}

配置修改后必须重启 Gateway。

插件插槽（排他分类）

有些插件分类是排他的，同一时间只能激活一个（比如长时记忆插件只能用一个）。用 slots 配置：

{
  plugins: {
    slots: {
      memory: "memory-lancedb", // 只有这个会加载，其他同类禁用
      // 填 "none" 禁用这个分类
    },
  },
}

发现顺序

OpenClaw 按这个顺序搜索插件：

1. 配置里 plugins.load.paths
2. 工作区 .openclaw/extensions/
3. 全局 ~/.openclaw/extensions/
4. 核心自带扩展（默认禁用，需要手动启用）

如果多个插件 ID 冲突，先找到的生效。

插件开发

插件入口

插件导出一个注册函数，写在插件的入口 TypeScript 文件，通常是 ./src/index.ts（相对插件根目录）：

export default function register(api) {
  // 在这里注册各种扩展
  // api 提供了各种注册方法和运行时工具
}

或者导出一个对象：

export default {
  id: "my-plugin",
  name: "My Plugin",
  configSchema: { /* ... */ },
  register(api) {
    // ...
  },
}

注册渠道插件（新增聊天渠道）

渠道插件就是添加一个新的聊天平台支持，比如 WhatsApp、Telegram、Discord 官方核心已经有了，如果你想加一个新平台，开发一个渠道插件。

最小示例，写在插件入口文件 ./src/index.ts：

const plugin = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "Acme Chat",
    selectionLabel: "Acme Chat (API)",
    docsPath: "/channels/acmechat",
    blurb: "AcmeChat  messaging.",
    aliases: ["acme"],
  },
  capabilities: {
    chatTypes: ["direct"],
  },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text }) => {
      // 发送文本到渠道
      return { ok: true };
    },
  },
};

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

配置存在用户配置的 channels.<id> 下面，不是 plugins.entries，所以用户配置渠道更方便。

完整步骤：

1. 定义渠道 ID 和元数据（名称、描述、别名）
2. 实现配置查询接口（列出账号、解析账号配置）
3. 实现发送消息接口
4. 可选：添加更多功能（状态检查、mention 处理、流媒体等）
5. api.registerChannel 注册

注册工具插件

插件可以注册 Agent 工具，让 AI 调用：

详见 Plugin agent tools。

注册钩子

插件可以注册钩子，在特定事件发生时运行，代码写在插件入口文件 ./src/index.ts：

export default function register(api) {
  api.registerHook(
    "command:new",
    async () => {
      // 每次 /new 清空会话后运行
    },
    {
      name: "my-plugin.command-new",
      description: "Runs when /new is invoked",
    }
  );
}

钩子通过插件启用/禁用控制，不能单独开关。

注册模型提供者认证

插件可以添加新的模型提供者认证流程，代码写在插件入口文件：

api.registerProvider({
  id: "acme",
  label: "Acme AI",
  auth: [
    {
      id: "oauth",
      label: "OAuth",
      kind: "oauth",
      run: async (ctx) => {
        // 执行 OAuth 流程，返回凭证
        return {
          profiles: [{
            profileId: "acme:default",
            credential: { ... },
          }],
          defaultModel: "acme/opus-1",
        };
      },
    },
  ],
});

注册自定义命令

插件可以注册斜杠命令，不经过 AI 直接执行，适合状态查询、开关操作等，代码写在插件入口文件：

api.registerCommand({
  name: "mystatus",
  description: "Show my plugin status",
  acceptsArgs: true,
  requireAuth: true,
  handler: async (ctx) => {
    // ctx 包含 senderId, channel, args, config
    return { text: "Plugin is running!" };
  },
});

• 命令在 AI 之前处理，匹配到就不发给 AI
• 不能覆盖核心命令（help/status/reset 等）
• 不区分大小写

注册后台服务

插件可以注册后台服务，Gateway 启动时运行，停止时关闭，代码写在插件入口文件：

export default function (api) {
  api.registerService({
    id: "my-service",
    start: () => api.logger.info("service started"),
    stop: () => api.logger.info("service stopped"),
  });
}

注册 Gateway RPC 方法

插件可以添加 Gateway RPC 方法，代码写在插件入口文件：

export default function (api) {
  api.registerGatewayMethod("myplugin.status", ({ respond }) => {
    respond(true, { ok: true });
  });
}

安全注意事项

插件进程内运行，所以插件代码就是你的 Gateway 代码，安全责任你自己承担：

1. 只安装你信任的插件 —— 插件能访问你的配置、文件、API 密钥
2. 使用 allowlist —— plugins.allow 只允许明确信任的插件
3. 修改后重启 —— 配置改完必须重启 Gateway 才生效
4. npm install 安全 —— openclaw plugins install 安装依赖时用 --ignore-scripts，不运行 postinstall 脚本

分发插件

推荐方式：

• 核心插件：放在 OpenClaw 源代码 extensions/ 目录，默认禁用，用户手动启用
• 社区插件：发布到 npm，包名 @openclaw/your-plugin，用户 openclaw plugins install 直接安装

package.json 需要声明扩展入口，写在 ./package.json（npm 包根目录）：

一个 npm 包可以包含多个扩展，每个扩展是一个独立插件。

社区插件提交

想让你的插件列在官方社区插件页面？需要满足：

1. npm 上发布
2. GitHub 公开仓库
3. 有使用文档
4. 有维护者，活跃更新

提交 PR 到 OpenClaw，添加到 plugins/community.md 即可。

开发新渠道插件 vs 核心内置

什么时候做插件，什么时候合并到核心：

• 插件：小众平台、第三方集成、实验性功能 —— 插件更灵活，不影响核心大小
• 核心：主流平台、稳定功能 —— 核心内置，用户不用额外安装

本章小结

• OpenClaw 插件系统支持扩展渠道、提供者、工具、命令、服务
• 每个插件必须有 openclaw.plugin.json 描述，包含 JSON Schema 验证配置
• 插件进程内加载，性能好，开发简单
• 支持排他插槽（比如记忆插件只能选一个）
• 安全提示：只装信任插件，用 allowlist 控制
• 社区插件通过 npm 分发，用户一键安装