Agent Plugins 详解 - OpenClaw插件系统完全指南

世界上有一种扩展叫做插件，它在OpenClaw的骨架上生长出新的能力...

Agent Plugins（智能体插件）是OpenClaw生态系统的核心扩展机制，就像给AI装上各种"超能力模块"。无需修改核心代码，就能让Agent获得新的渠道、模型、工具、技能等能力。

💡 核心概念：插件是打包好的能力集合，可以注册channels（渠道）、model providers（模型提供商）、tools（工具）、skills（技能）、speech（语音）、image generation（图像生成）等功能。

插件类型

OpenClaw支持两种插件格式：

类型 工作原理 示例
Native openclaw.plugin.json + 运行时模块，进程内执行 官方插件、社区npm包
Bundle Codex/Claude/Cursor兼容布局，映射到OpenClaw功能 .codex-plugin/、.claude-plugin/

官方插件

可安装插件（npm）

插件 包名 功能
Matrix @openclaw/matrix Matrix协议渠道
Microsoft Teams @openclaw/msteams Teams集成
Nostr @openclaw/nostr Nostr协议渠道
Voice Call @openclaw/voice-call 语音通话能力
Zalo @openclaw/zalo Zalo渠道

核心插件（内置）

快速上手

查看已加载插件

openclaw plugins list

安装插件

# 从npm安装
openclaw plugins install @openclaw/voice-call

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

# 从压缩包安装
openclaw plugins install ./my-plugin.tgz

配置插件

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio"
        }
      }
    }
  }
}

配置详解

字段 说明
enabled 主开关（默认true）
allow 插件白名单（可选）
deny 插件黑名单（可选，deny优先级更高）
load.paths 额外的插件文件/目录
slots 独占槽位选择器（如memory、contextEngine）
entries.<id> 每个插件的开关+配置

发现与优先级

OpenClaw按以下顺序扫描插件（先匹配优先）：

  1. Config paths - plugins.load.paths指定的路径
  2. Workspace extensions - <workspace>/.openclaw/extensions/*.ts
  3. Global extensions - ~/.openclaw/extensions/*.ts
  4. Bundled plugins - OpenClaw内置插件
⚠️ 注意：配置更改需要重启Gateway。如果Gateway启用了config watch，重启会自动进行。

独占槽位

某些功能类别是互斥的，一次只能激活一个：

{
  plugins: {
    slots: {
      memory: "memory-core",     // 或 "memory-lancedb"
      contextEngine: "legacy"    // 或其他插件id
    }
  }
}
槽位 控制内容 默认值
memory 活动的内存插件 memory-core
contextEngine 活动的上下文引擎 legacy

开发插件

插件导出一个函数或对象，包含register(api)方法：

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  register(api) {
    api.registerProvider({
      // 注册模型提供商
    });
    api.registerTool({
      // 注册工具
    });
    api.registerChannel({
      // 注册渠道
    });
  },
});

常用注册方法

方法 注册内容
registerProvider 模型提供商（LLM）
registerChannel 聊天渠道
registerTool 工具
registerSkill 技能

CLI参考

# 查看插件列表
openclaw plugins list

# 查看插件详情
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json

# 安装/更新
openclaw plugins install <package>
openclaw plugins update <id>
openclaw plugins update --all

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

# 诊断
openclaw plugins status
openclaw plugins doctor

聊天命令

启用commands.plugins: true后，可在聊天中使用：

/plugin install clawhub:@openclaw/voice-call
/plugin show voice-call
/plugin enable voice-call
🎯 实战提示：开发新插件时，使用openclaw plugins install -l ./my-plugin进行链接安装，这样修改代码后无需重新安装即可测试。