Plugins

插件系统

插件是 OpenClaw 的系统级扩展机制。它解决的是"把新的代码能力装进系统"，而不是"把工作流写得更长"。理解插件的安装、配置、启停和更新，是扩展 OpenClaw 能力的第一步。

插件分类

按功能分类的插件生态

OpenClaw 插件覆盖渠道接入、记忆存储、语音处理、工具执行和第三方集成等多个领域。

渠道插件

扩展消息渠道接入能力

telegramTelegram Bot 接入stable

discordDiscord Bot 接入stable

whatsappWhatsApp Business 接入stable

feishu飞书机器人接入stable

dingtalk钉钉机器人接入beta

slackSlack App 接入stable

记忆插件

扩展记忆存储和检索能力

chromaChroma 向量数据库stable

pineconePinecone 云向量库stable

qdrantQdrant 向量数据库stable

postgresPostgreSQL 存储stable

语音插件

扩展语音识别和合成能力

whisperOpenAI Whisper 语音识别stable

elevenlabsElevenLabs 语音合成stable

azure-speechAzure 语音服务stable

工具插件

扩展执行和集成能力

browser浏览器自动化stable

exec命令执行能力stable

filesystem文件系统操作stable

httpHTTP 请求能力stable

集成插件

扩展第三方系统集成

githubGitHub 集成stable

notionNotion 集成stable

googleGoogle 服务集成stable

linearLinear 项目管理beta

Lifecycle

插件生命周期管理

从发现到维护，插件管理遵循一套完整的生命周期流程。

发现

查找和评估插件

浏览官方插件市场
查看插件文档和评分
检查维护状态和更新频率
确认与当前版本兼容性

安装

安装插件到系统

选择安装源（npm/本地/git）
执行安装命令
验证安装成功
检查依赖是否满足

配置

配置插件参数

阅读配置文档
设置必要参数
配置凭证和密钥
调整运行参数

启用

激活插件功能

启用插件
验证功能可用
测试基本场景
监控运行状态

维护

更新和问题处理

定期检查更新
测试新版本兼容性
处理运行问题
必要时回滚版本

CLI Reference

命令行参考

掌握这些命令，完成插件的日常管理操作。

openclaw plugins list列出所有已安装插件

# 列出所有插件
$ openclaw plugins list

┌─────────────┬─────────┬─────────┬──────────┐
│ Plugin      │ Version │ Status  │ Enabled  │
├─────────────┼─────────┼─────────┼──────────┤
│ telegram    │ 1.2.3   │ active  │ true     │
│ chroma      │ 0.8.1   │ active  │ true     │
│ whisper     │ 1.0.0   │ active  │ false    │
└─────────────┴─────────┴─────────┴──────────┘

openclaw plugins install <name>安装插件

# 从 npm 安装
$ openclaw plugins install @openclaw/plugin-telegram

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

# 从 git 仓库安装
$ openclaw plugins install github:user/repo

openclaw plugins enable <name>启用插件

# 启用单个插件
$ openclaw plugins enable telegram

# 启用多个插件
$ openclaw plugins enable telegram discord

openclaw plugins disable <name>禁用插件

# 禁用插件（保留配置）
$ openclaw plugins disable telegram

# 禁用后可随时重新启用
$ openclaw plugins enable telegram

openclaw plugins update <name>更新插件

# 更新到最新版本
$ openclaw plugins update telegram

# 更新到指定版本
$ openclaw plugins update telegram@1.3.0

openclaw plugins remove <name>移除插件

# 移除插件（会提示确认）
$ openclaw plugins remove telegram

# 强制移除（不确认）
$ openclaw plugins remove telegram --force

openclaw plugins info <name>查看插件详情

# 查看插件详细信息
$ openclaw plugins info telegram

Name:        @openclaw/plugin-telegram
Version:     1.2.3
Author:      OpenClaw Team
Description: Telegram bot integration
Config:      ~/.openclaw/plugins/telegram.json
Status:      enabled

Configuration

配置位置说明

插件配置不一定都写在同一个位置，这是最常见的踩坑点之一。

`plugins.entries.<id>.config`

通用插件配置入口

{
  "plugins": {
    "entries": {
      "my-plugin": {
        "enabled": true,
        "config": {
          "apiKey": "${MY_PLUGIN_API_KEY}",
          "timeout": 30000
        }
      }
    }
  }
}

`channels.<channelId>`

渠道型插件配置

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "dmPolicy": "pairing"
    }
  }
}

`plugins.slots.memory`

记忆插件槽位配置

{
  "plugins": {
    "slots": {
      "memory": {
        "provider": "chroma",
        "config": {
          "path": "~/.openclaw/data/chroma"
        }
      }
    }
  }
}

`独立配置文件`

插件独立配置文件

# ~/.openclaw/plugins/telegram.json
{
  "botToken": "xxx",
  "allowedUsers": [123456789],
  "parseMode": "Markdown"
}

Comparison

插件 vs Skills vs Tools

理解三者的区别，才能选择正确的扩展方式。

维度	Plugin	Skill	Tool
定义	系统级代码扩展，注册新能力到 Gateway	任务级能力包，组织提示词和工具调用	单个执行能力，如读文件、执行命令
安装方式	npm install / 本地目录 / git	放入 skills 目录 / 配置加载	内置或通过插件注册
配置位置	plugins.entries / channels / slots	skills.entries / SOUL.md	tools 配置项
启停控制	enable / disable 命令	enabled 字段控制	tools.enabled 控制
更新方式	plugins update 命令	替换文件 / git pull	随插件或系统更新
风险等级	高（代码级扩展）	中（提示词和流程）	取决于具体工具

Best Practices

最佳实践

遵循这些实践，让插件管理更加稳健。

先盘点再安装

使用 `plugins list` 确认系统已有能力，避免重复安装功能相似的插件。

优先官方插件

官方插件经过测试和维护，第三方插件需评估可信度和维护状态。

测试环境先行

新插件先在测试环境验证，确认无问题后再部署到生产环境。

记录配置变更

插件配置变更应记录在版本控制中，便于回滚和问题追踪。

定期检查更新

定期检查插件更新，但更新前需查看变更日志和兼容性说明。

保留回滚路径

更新前记录当前版本，确保可以快速回滚到稳定状态。

FAQ

常见问题

插件安装后不生效怎么办？

按以下顺序检查：1) 插件是否已启用；2) 是否需要重启 Gateway；3) 配置是否正确；4) 依赖是否满足。

如何判断应该用插件还是 Skill？

如果需要注册新的执行能力或系统集成，用插件。如果只是组织现有能力完成任务，用 Skill。

插件配置写在哪里？

取决于插件类型。通用配置在 plugins.entries，渠道配置在 channels，记忆配置在 plugins.slots。查看插件文档确认具体位置。

如何开发自己的插件？

参考官方插件模板，实现必要的接口，通过本地目录安装测试，稳定后可发布到 npm。

插件更新后出现问题怎么办？

使用 `plugins update <name>@<version>` 回滚到之前的稳定版本，然后查看变更日志定位问题。

多个插件可以同时使用吗？

可以，但需注意资源占用和潜在冲突。建议按需启用，不用的插件及时禁用。