Skip to main content

​
插件系统概览

OpenClaw 的插件系统允许开发者扩展核心功能,添加新的消息平台、工具、命令和服务。插件运行在网关进程中,可以访问完整的配置和运行时能力。

​
插件能力

插件可以注册以下类型的扩展:

代理工具

注册 AI 代理可以调用的工具函数,支持必需和可选工具

消息平台

添加新的聊天平台集成(Telegram、Discord、Matrix 等)

网关方法

注册自定义 RPC 方法,通过网关协议调用

HTTP 路由

添加 webhook 端点和自定义 HTTP 处理器

CLI 命令

扩展 openclaw 命令行工具的子命令

后台服务

注册随网关启动/停止的长期运行服务

生命周期钩子

监听代理运行、消息处理和会话事件

自定义命令

注册绕过 LLM 的简单命令(/tts、/status 等)

​
插件安装

​
从 npm 安装(推荐)

openclaw plugins install @openclaw/voice-call
安装后重启网关以加载插件。

​
从本地目录安装(开发用)

openclaw plugins install ./extensions/voice-call
适合开发时快速迭代,无需发布到 npm。

​
从 Git 安装

openclaw plugins install github:username/repo

​
插件配置

插件配置位于 plugins.entries.<plugin-id>.config 下: 
{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio",
          fromNumber: "+15550001234",
          toNumber: "+15550005678",
          twilio: {
            accountSid: "ACxxxxxxxx",
            authToken: "...",
          },
        },
      },
    },
  },
}

​
启用和禁用插件

使用允许列表/拒绝列表控制: 
{
  plugins: {
    allow: ["voice-call", "diffs"],
    deny: ["diagnostics-otel"],
  },
}
或在每个插件条目中设置: 
{
  plugins: {
    entries: {
      "voice-call": { enabled: false },
    },
  },
}
  • 同时设置 allow 和 deny 时,deny 优先级更高
  • 插件禁用后,配置保留但不会加载
  • Doctor 命令会警告已禁用但有配置的插件

​
插件类型

​
内置插件(Bundled)

随 OpenClaw 发行版一起打包的插件,位于 extensions/ 目录:
  • 消息平台: telegram、discord、slack、signal、imessage、whatsapp
  • 扩展平台: matrix、msteams、googlechat、line、feishu、irc、nostr
  • 功能插件: voice-call、diffs、memory-lancedb、device-pair
  • 工具插件: llm-task、phone-control、talk-voice

​
全局插件(Global)

通过 openclaw plugins install 安装到 ~/.openclaw/plugins/。

​
工作区插件(Workspace)

项目本地插件,位于工作区目录下。

​
配置引用插件(Config)

通过配置路径引用的外部插件: 
{
  plugins: {
    entries: {
      "custom-plugin": {
        source: "/path/to/plugin",
      },
    },
  },
}

​
插件发现

插件必须提供 openclaw.plugin.json 清单文件,包含: 
{
  "id": "voice-call",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}
查看完整清单规范: 插件清单

​
运行时隔离

插件运行在网关进程中,可以:
  • 访问完整配置 (api.config)
  • 读写文件系统
  • 启动 HTTP 服务器
  • 调用外部进程
  • 访问环境变量
插件拥有完整的进程权限。仅安装可信来源的插件。

​
Plugin SDK

OpenClaw 提供丰富的 SDK 模块: 
import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/core";

​
核心模块

  • openclaw/plugin-sdk - 主要 API 类型和工具
  • openclaw/plugin-sdk/core - 核心工具和帮助函数
  • openclaw/plugin-sdk/compat - 向后兼容层

​
平台模块

每个消息平台都有专门的 SDK 模块:
  • openclaw/plugin-sdk/telegram
  • openclaw/plugin-sdk/discord
  • openclaw/plugin-sdk/slack
  • openclaw/plugin-sdk/signal
  • openclaw/plugin-sdk/whatsapp
  • 等等…
查看完整 API 参考: Plugin SDK

​
最佳实践

1

使用 TypeScript

插件 SDK 提供完整的 TypeScript 类型定义,建议使用 TS 开发以获得类型安全和 IDE 支持。
2

提供配置模式

使用 JSON Schema 或 Zod 验证插件配置,在启动前捕获错误:
import { z } from "zod";

const ConfigSchema = z.object({
  apiKey: z.string(),
  enabled: z.boolean().default(true),
});
3

记录日志

使用 api.logger 记录调试信息:
api.logger.info("Plugin initialized");
api.logger.warn("Deprecated config option");
api.logger.error("Failed to connect");
4

处理错误

优雅处理异常,避免崩溃整个网关:
try {
  await riskyOperation();
} catch (err) {
  api.logger.error(`Operation failed: ${err.message}`);
}
5

清理资源

在服务 stop 方法中清理资源:
api.registerService({
  id: "my-service",
  async start() {
    // 启动服务
  },
  async stop() {
    // 关闭连接、清理定时器
  },
});

​
社区插件

查看社区维护的第三方插件: 社区插件列表

​
下一步

创建插件

从零开始构建你的第一个插件

Plugin SDK

探索完整的 SDK API 参考

插件清单

了解清单文件的结构和验证规则

代理工具

为 AI 代理添加自定义工具