首页 资讯 下载 教程 Skills 社群

OpenClaw 外部插件管理：v2026.5.2 新机制详解

· 11 分钟 进阶玩法

概述

OpenClaw v2026.5.2 重构了插件架构：

  • 核心插件仍捆绑（约 80MB）
  • 官方扩展外部托管（按需安装）
  • 主包从 250MB 瘦身到 80MB

新机制带来：

  • 启动速度：3 倍提升
  • 磁盘占用：减少 68%
  • 维护性：插件独立更新

插件分类

核心插件（捆绑）

随主包一起的核心能力：

  • 基础 Channel（消息、文件）
  • 基础 Provider（OpenAI、Anthropic）
  • 基础 Tool（read、write、exec）
  • 核心 Agent 框架

官方扩展（外部）

按需安装：

  • 媒体生成（ComfyUI、Insta-Cog）
  • 高级 Channel（Telegram、Slack）
  • 专业 Provider（Volcengine、Xiaomi）
  • 行业 Skill（金融、医疗）

第三方插件

ClawHub 社区贡献：

  • 各种自定义功能
  • 用户自建工具
  • 实验性功能

列出可用插件

已安装

openclaw plugins list

输出：

已安装：
  Core (bundled):
    - openai
    - anthropic
    - basic-tools
    
  External:
    - @openclaw/insta-cog (v1.2.0)
    - @openclaw/comfyui (v0.5.1)

可用的

openclaw plugins available

显示官方插件目录：

官方扩展插件：
  @openclaw/insta-cog          视频内容生成
  @openclaw/comfyui            ComfyUI 工作流
  @openclaw/volcengine-tts     火山引擎语音
  @openclaw/elevenlabs         ElevenLabs 语音
  @openclaw/azure-speech       Azure 语音
  ...

ClawHub 搜索

clawhub search keyword

ClawHub 仍是社区 Skill 的来源。

安装插件

单个安装

openclaw plugins install @openclaw/insta-cog

输出：

正在安装 @openclaw/insta-cog...
[下载] 5.2 MB
[验证] ✓ 签名通过
[安装] ✓ 已注册
[配置] ✓ Manifest 已加载

安装完成！

指定版本

openclaw plugins install @openclaw/insta-cog@1.2.0

批量安装

openclaw plugins install \
  @openclaw/comfyui \
  @openclaw/volcengine-tts \
  @openclaw/azure-speech

卸载插件

openclaw plugins uninstall @openclaw/insta-cog

会：

  • 从注册表移除
  • 删除文件
  • 警告依赖关系
  • 保留配置（避免数据丢失）

如果想完全清理：

openclaw plugins uninstall @openclaw/insta-cog --purge

升级老配置

检测老配置

升级到 v2026.5.2 后：

openclaw doctor

可能输出：

[警告] 配置引用了未安装的插件：
  - insta-cog
  - comfyui
  - volcengine-tts

建议：
  openclaw plugins sync
  
或单独安装：
  openclaw plugins install @openclaw/insta-cog

一键同步

最方便的方式：

openclaw plugins sync

OpenClaw 会：

  1. 读取你的配置
  2. 识别引用的插件
  3. 找到对应的官方包
  4. 自动安装

输出：

正在同步插件...
✓ insta-cog → @openclaw/insta-cog
✓ comfyui → @openclaw/comfyui
✓ volcengine-tts → @openclaw/volcengine-tts

3 个插件同步完成

手动迁移

如果想精细控制：

# 查看引用
openclaw plugins references

# 输出：
# - insta-cog (in agents.video-creator)
# - comfyui (in agents.video-creator)
# - volcengine-tts (in agents.cs.voice)

# 逐个安装
openclaw plugins install @openclaw/insta-cog
openclaw plugins install @openclaw/comfyui
openclaw plugins install @openclaw/volcengine-tts

更新插件

单个更新

openclaw plugins update @openclaw/insta-cog

批量更新

openclaw plugins update --all

查看可更新

openclaw plugins outdated

配置插件目录

默认位置

  • macOS/Linux：~/.openclaw/plugins/
  • Windows：%APPDATA%\openclaw\plugins\

自定义

# config.yaml
plugins:
  installPath: "/custom/path/plugins"

适合：

  • 共享插件（团队）
  • 网络挂载（NFS）
  • 容器化部署

多目录

plugins:
  searchPaths:
    - "/etc/openclaw/plugins"          # 系统级
    - "/home/team/openclaw/plugins"    # 团队
    - "~/.openclaw/plugins"             # 个人

按顺序查找。

离线安装

下载离线包

openclaw plugins download @openclaw/insta-cog \
  --output ./plugins-offline/

离线安装

openclaw plugins install \
  ./plugins-offline/insta-cog-1.2.0.tar.gz

适合：

  • 内网环境
  • 安全要求高
  • 离线服务器

插件版本管理

锁定版本

# config.yaml
plugins:
  versionLock:
    "@openclaw/insta-cog": "1.2.0"
    "@openclaw/comfyui": ">=0.5.0,<1.0.0"

避免不期望的升级。

测试新版本

# 安装到测试环境
OPENCLAW_PROFILE=test \
  openclaw plugins install @openclaw/insta-cog@2.0.0-beta

# 验证
openclaw test plugins

# 通过后升级生产
openclaw plugins update @openclaw/insta-cog

团队共享

Git 化管理

# 团队仓库结构
team-openclaw/
├── config.yaml
├── plugins.lock      # 插件版本锁定
└── README.md

plugins.lock 文件：

plugins:
  "@openclaw/insta-cog": "1.2.0"
  "@openclaw/comfyui": "0.5.1"
  "@openclaw/volcengine-tts": "2.0.0"

团队成员同步

# 拉取仓库
git pull

# 同步插件版本
openclaw plugins sync --from-lock plugins.lock

确保团队插件版本一致。

容器化部署

Dockerfile 优化

FROM node:22-alpine

# 安装 OpenClaw 核心
RUN npm install -g openclaw

# 安装需要的外部插件
RUN openclaw plugins install \
  @openclaw/comfyui \
  @openclaw/volcengine-tts

# 复制配置
COPY config.yaml /etc/openclaw/

CMD ["openclaw", "gateway"]

镜像更小（之前 ~500MB，现在 ~150MB）。

多阶段构建

FROM node:22 AS plugin-builder
RUN npm install -g openclaw
RUN openclaw plugins install @openclaw/comfyui

FROM node:22-alpine
RUN npm install -g openclaw
COPY --from=plugin-builder ~/.openclaw/plugins ~/.openclaw/plugins

故障排查

安装失败

错误：无法连接到插件仓库

检查：

  • 网络连接
  • 防火墙
  • 代理设置
# 配置代理
openclaw config set plugins.registry.proxy "http://proxy:8080"

# 镜像源（国内用户）
openclaw config set plugins.registry "https://mirror.cn/openclaw"

签名验证失败

错误：插件签名验证失败

可能原因：

  • 插件来源不可信
  • 网络中间人攻击
  • 包损坏

解决：

  • 重新下载
  • 验证来源
  • 临时绕过（不推荐）：--no-verify

依赖冲突

错误：@openclaw/comfyui 需要 @openclaw/cellcog ≥ 2.0
当前 cellcog 版本：1.5.0

解决：

openclaw plugins update @openclaw/cellcog
# 或
openclaw plugins install @openclaw/cellcog@latest

自定义插件仓库

私有仓库

企业可以搭建私有插件仓库：

plugins:
  registries:
    - url: "https://plugins.example.com/registry"
      auth:
        type: "token"
        token: "$REGISTRY_TOKEN"

镜像加速

国内用户：

plugins:
  registries:
    - url: "https://openclaw.npmmirror.com/"
      priority: 1  # 高优先级
    - url: "https://registry.openclaw.ai/"
      priority: 2  # 备份

注意事项

  • 外部插件机制需要 OpenClaw v2026.5.2 或更高版本
  • 升级时仔细看提示，不要忽略
  • plugins sync 是最方便的迁移方式
  • 团队部署使用 plugins.lock 锁定版本
  • 容器化部署利用新机制大幅瘦身
  • 国内用户配置镜像源加速
  • 私有/敏感插件可自建仓库
  • 升级前测试新版本
  • 保持插件及时更新获得修复和新功能
← 上一篇 file-transfer 文件传输 下一篇 → Personas 多人格