OpenClaw Plugin Manifest 权限声明：收紧插件激活边界

2026-04-14 · 7 分钟安全运维

背景

在 v2026.4.12 之前，OpenClaw 的插件激活相对宽松：

插件可以请求任何 CLI 命令
可以注册任意 Provider
可以监听任意频道事件

这带来了两个问题：

安全风险：恶意插件可以请求不必要的权限
性能浪费：加载了不需要的插件运行时

v2026.4.12 引入 Plugin Manifest 权限声明，改变了这一状况。

核心原则

新的插件权限模型遵循：

最小权限原则：插件只能使用 manifest 声明的能力
显式作用域：能力边界清晰定义
信任边界保持：manifest 拥有者（开发者）策略集中管理
避免不相关插件加载：只加载需要的插件

Plugin Manifest 结构

基础示例

# plugin.yaml
name: my-plugin
version: 1.0.0
author: "your-name"

# 声明能力需求
capabilities:
  cli:
    - name: "mycmd"
      description: "我的自定义命令"

  providers:
    - id: "my-provider"
      type: "llm"

  channels:
    - type: "webhook"
      path: "/my-webhook"

  tools:
    - name: "my-tool"

完整字段说明

name: plugin-name           # 插件唯一标识
version: semver             # 版本号
author: string              # 作者
description: string         # 描述
license: string             # 许可证

# 核心：能力声明
capabilities:
  # CLI 命令注册
  cli:
    - name: command-name
      description: string
      scope: user|workspace|global
  
  # Provider 注册
  providers:
    - id: provider-id
      type: llm|embedding|stt|tts|etc
      baseUrl: string       # 如果是外部 API
  
  # 频道监听
  channels:
    - type: webhook|telegram|matrix|etc
      events: [event1, event2]
  
  # 工具注册
  tools:
    - name: tool-name
      scope: agent|global
  
  # 文件系统访问
  filesystem:
    read: [path1, path2]
    write: [path3]
  
  # 网络访问
  network:
    outbound: [domain1.com, api.example.com]
    inbound: false

# 依赖声明
dependencies:
  openclaw: ">=2026.4.12"
  plugins:
    - cellcog

# 信任级别声明
trust:
  sandbox: true              # 是否在沙箱运行
  capabilities: []           # 高危能力需显式声明

为什么要声明

用户视角

用户在安装插件前可以查看 manifest：

openclaw plugins inspect my-plugin

输出：

插件：my-plugin
版本：1.0.0
作者：your-name

需要的能力：
✓ CLI 命令：mycmd
✓ 网络访问：api.example.com
✗ 文件写入：/home/user/data

你同意安装这些能力吗？[y/N]

系统视角

OpenClaw 启动时：

只加载 manifest 中声明的功能
不扫描不相关插件
启动速度显著提升

实际影响

性能提升

v2026.4.12 之后：

指标	提升
启动时间	-30% 到 -50%
内存占用	-20% 到 -40%
命令发现	-50%

尤其是安装了大量插件的用户，差异显著。

安全性提升

恶意插件限制：恶意插件无法请求未声明的权限
越权检测：插件试图使用未声明的能力会被拒绝
审计友好：manifest 就是权限清单

插件开发者迁移

从旧格式迁移

如果你有旧的插件：

# 自动生成 manifest 骨架
openclaw plugins manifest-init

这会扫描插件代码，生成推荐的 manifest，你需要手动确认和调整。

验证 manifest

# 验证 manifest 格式正确
openclaw plugins validate

# 对照实际代码验证权限声明
openclaw plugins audit

运行时检查

在开发中启用严格模式：

# config.yaml
plugins:
  strictMode: true  # 未声明的能力调用会报错

用户安装流程

查看权限

openclaw plugins info my-plugin

同意安装

openclaw plugins install my-plugin
# 系统会显示需要的能力，确认后才安装

撤销授权

openclaw plugins revoke my-plugin --capability network
# 禁用特定能力但保留插件

高危能力

某些能力需要额外确认：

文件系统写入：可能破坏数据
exec 执行：可能运行任意代码
Provider 认证访问：可能窃取 API Key
全局钩子：可能影响所有操作

这些能力在安装时会显示警告，要求用户二次确认。

ClawHub 集成

ClawHub 会根据插件 manifest：

显示能力摘要
标注高风险能力
提供安全评级
警告权限过度的插件

ClawHub 页面：
┌─────────────────────────────────┐
│ my-plugin v1.0.0                │
│ 安全评级：★★★★☆                │
│                                 │
│ 声明的能力：                     │
│ - CLI 命令 × 1                  │
│ - 网络访问：1 个域名            │
│                                 │
│ ⚠️ 注意：此插件请求 exec 能力    │
└─────────────────────────────────┘

故障排查

插件功能缺失

错误：插件试图调用未声明的能力 "file.write"

解决：

检查 plugin.yaml 是否声明了该能力
如果是自己开发的插件，添加声明
如果是第三方插件，联系作者更新

启动速度没改善

# 查看插件加载情况
openclaw plugins status --verbose

如果发现很多插件仍在加载，可能是：

插件 manifest 声明过宽
插件被频繁触发

最佳实践

最小声明：只声明真正需要的能力
具体域名：网络访问声明具体域名而非通配符
文件路径精确：不要声明 / 级别的文件访问
定期审计：openclaw plugins audit 定期运行
版本锁定：生产环境锁定插件版本

注意事项

Plugin Manifest 系统需要 OpenClaw v2026.4.12 或更高版本
老版本插件会进入"兼容模式"，权限宽松但会显示警告
建议尽快迁移老插件到新 manifest 格式
ClawHub 未来可能强制要求所有插件提供 manifest
企业部署建议启用 strictMode 获得最强安全保障