11.4 插件系统

插件系统（扩展）

快速入门

插件是"一个小型代码模块，用于扩展 OpenClaw 的额外功能。"操作步骤：

# 列出可用插件
openclaw plugins list

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

# 重启网关
# 重启后插件即可生效

可用插件（官方）

• Voice Call - 语音通话插件
• Microsoft Teams - 微软 Teams 集成
• Memory (Core/LanceDB) - 记忆系统
• Matrix - Matrix 协议支持
• Zalo / Zalo Personal - Zalo 消息平台
• Nostr - Nostr 协议支持
• OAuth Providers - OAuth 提供商（Gemini、Qwen 等）
• Copilot Proxy - Copilot 代理

运行时辅助函数

插件可以使用运行时 API，例如：

api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config
});

发现与优先级

OpenClaw 按以下顺序扫描插件：

1. 配置路径（plugins.load.paths）
2. 工作区（/.openclaw/extensions/）
3. 全局目录（~/.openclaw/extensions/）
4. 内置扩展

包集合

使用 package.json 中的 "openclaw.extensions" 声明多个入口点；id 变为 name/。

频道目录元数据

插件可以通过 openclaw.channel 和 openclaw.install 进行广告；支持通过 JSON 文件扩展外部目录。

插件 ID

默认为 package.json.name 或文件基名；导出的 id 会被使用，但如果不匹配会发出警告。

配置示例

{
  "plugins": {
    "enabled": true,
    "allow": ["@openclaw/voice-call", "@openclaw/matrix"],
    "deny": [],
    "load": {
      "paths": ["./custom-plugins"]
    },
    "entries": {
      "voice-call": {
        "enabled": true
      }
    }
  }
}

配置要点：

• plugins.enabled - 全局启用/禁用插件系统
• plugins.allow / plugins.deny - 插件白名单/黑名单
• plugins.load.paths - 自定义插件加载路径
• plugins.entries.{id} - 单个插件的配置
• 严格的验证规则确保配置安全

插件插槽

独占类别（例如 memory）通过 plugins.slots.memory 控制，同一类别只能有一个插件处于活动状态。

控制 UI

使用 config.schema + uiHints 提供标签、占位符、敏感字段等 UI 提示。

CLI 命令

# 列出所有插件
openclaw plugins list

# 安装插件（支持 npm、本地路径、tarball、链接）
openclaw plugins install @openclaw/matrix
openclaw plugins install ./path/to/plugin
openclaw plugins install /path/to/plugin.tgz

# 更新插件
openclaw plugins update @openclaw/voice-call

# 启用/禁用插件
openclaw plugins enable voice-call
openclaw plugins disable voice-call

# 诊断插件问题
openclaw plugins doctor

插件 API

插件导出一个函数或对象：

// 函数形式
export default function(api) {
  // 注册功能
}

// 对象形式
export default {
  id: "my-plugin",
  register(api) {
    // 注册功能
  }
}

插件钩子

通过插件生命周期管理的钩子：

api.registerPluginHooksFromDir(api, "./hooks");

提供商插件

注册认证流程（OAuth、API 密钥）：

api.registerProvider({
  id: "my-provider",
  // OAuth 或 API 密钥配置
});

消息频道

通过 api.registerChannel 注册频道：

api.registerChannel({
  plugin: "my-channel",
  // 频道配置
});

// 配置位于 channels.{id} 下

代理工具

插件可以注册代理可以使用的工具：

api.registerTool({
  name: "my_tool",
  description: "工具描述",
  handler: async (params) => {
    // 工具逻辑
  }
});

RPC 方法

注册 RPC 方法供外部调用：

api.registerRPC({
  method: "pluginId.action",
  handler: async (params) => {
    // RPC 逻辑
  }
});

CLI 命令注册

插件可以添加自定义 CLI 命令：

api.registerCLICommand({
  name: "my-command",
  description: "命令描述",
  handler: async (args) => {
    // 命令逻辑
  }
});

自动回复命令

注册斜杠命令用于聊天中的自动回复。

后台服务

插件可以注册在网关启动时运行的后台服务。

命名约定

• RPC: pluginId.action
• 工具: snake_case
• CLI: kebab-case 或 camelCase，避免与核心命令冲突

技能

插件可以包含技能文件 skills/{id}/SKILL.md；通过配置启用。

分发（npm）

以 @openclaw/{name} 发布到 npm；openclaw plugins install 使用 npm pack。

示例插件：Voice Call

Voice Call 插件包含：

• CLI 命令
• 代理工具
• RPC 方法
• Twilio / 日志配置
• 技能文件

安全说明

测试插件

推荐使用 Vitest 在 src/ 中进行测试，或在 CI 中验证 dist 构建。

# 运行插件测试
npm test

# 构建插件
npm run build

# 本地测试安装
openclaw plugins install ./path/to/plugin

插件开发最佳实践

• 使用 TypeScript 获得类型安全
• 提供清晰的配置模式和 UI 提示
• 编写完整的文档和示例
• 处理错误并提供有用的日志
• 遵循命名约定避免冲突
• 在发布前彻底测试

相关资源

• 网关配置
• 技能系统
• OpenClaw GitHub