插件权限、安装、升级和版本兼容

📅 2026/6/25 17:49:37
插件权限、安装、升级和版本兼容
插件让 OpenClaw 变得可扩展。但插件也带来新的风险谁写的插件 它注册了哪些工具 它会不会读取敏感配置 它能不能发消息、部署、调用外部 API 升级后会不会破坏旧配置所以使用 Plugin不能只会 install还要懂权限、启用、升级和兼容。先说结论插件管理是生命周期管理一个插件的完整生命周期包括发现 安装 配置 启用 运行时验证 权限控制 升级 兼容迁移 禁用 / 卸载每一步都可能出问题。安装来源OpenClaw 支持多种插件来源ClawHub npm git local path npm-pack marketplace compatible bundles选择原则ClawHub 适合公开发现、扫描状态、版本提示 npm 适合已有 JS 包发布体系 git/local 适合开发和测试 npm-pack 适合验证本地打包产物安装后通常要让 Gateway 重启或重新加载再用 runtime inspect 验证。冷检查和运行时检查不要只看openclaw plugins list它更多是冷检查manifest、config、registry、dependency status。要证明插件真的注册了工具、hook、route应该用openclaw plugins inspect plugin-id --runtime --json这能减少“插件看起来安装了但 Agent 看不到工具”的困惑。Optional tools 和 tools.allow插件工具可以是 required也可以是 optional。Optional tool 的意思是插件启用后工具不一定暴露给模型 用户需要通过 tools.allow 显式允许这适合有副作用的工具 不常用的能力 需要额外依赖的命令 风险较高的操作发现期的控制用 optional tools执行期的单次确认用 plugin permission requests。Plugin permission requestsPlugin permission requests 允许插件在动作执行前请求用户批准。适用场景部署服务 发送外部消息 写入生产系统 执行付费操作 修改重要配置它和 exec approvals 不同exec approvals 控制 host shell command plugin permission requests 控制插件拥有的动作或 hook optional tools 控制工具是否暴露给模型敏感工具可以同时使用optional tool opt-in per-call plugin approval升级和兼容插件升级不是简单替换文件。你要关注plugin API version minGatewayVersion manifest schema config schema contracts.tools 是否变化 旧配置是否迁移 工具名是否兼容 用户 allowlist 是否还有效OpenClaw 的 compatibility 文档强调旧 plugin contract 不应在引入替代方案的同一版本立刻移除。通常流程是添加新 contract 保留旧适配 发出诊断或警告 写迁移文档 测试新旧路径 经过迁移窗口 再移除旧路径这对插件作者尤其重要。卸载和禁用卸载插件可能会移除config entry install record allow/deny list entries linked load paths managed install files如果只是临时停用可以先 disable而不是 uninstall。如果保留文件用于调试可以使用--keep-files。安全使用建议使用第三方插件时先看来源和扫描状态 阅读 manifest 和权限 检查它注册了哪些 tools / hooks / routes 优先在测试环境启用 对高风险工具使用 optional approval 升级前看 release notes 和 compatibility warning不要把插件当成“只是提示词”。插件可以注册运行时能力。一个真实场景你安装一个部署插件deploy_service rollback_service deployment_status合理配置deployment_status required 或默认可见 deploy_service optional tool需要 tools.allow production 环境触发 plugin approval rollback_service optional approval 不提供 allow-always升级前检查工具名有没有改 config schema 有没有迁移 minGatewayVersion 是否满足 旧 allowlist 是否仍有效常见误解误解一插件安装后就安全可用不一定。还要看来源、manifest、权限、配置和运行时验证。误解二optional tool 等于 approval不是。optional 控制是否暴露approval 控制某次动作是否执行。误解三升级总是无风险不是。工具名、配置、SDK contract 都可能变化。误解四卸载只会删除文件不止。还可能清理配置、记录和 allow/deny 相关状态。最后总结插件能力越强生命周期管理越重要。一句话总结安装前看来源启用前看权限运行时看注册执行前看 approval升级前看兼容。本节作业选一个插件列出它的 tools、config 和权限风险。区分 optional tool、plugin approval、exec approval。设计一个部署插件的 production approval 流程。写一份插件升级检查清单。下一节预告下一部分进入部署、配置与调试本地安装与最小可运行配置。参考资料OpenClaw DocsManage pluginsOpenClaw DocsPlugin permission requestsOpenClaw DocsPlugin compatibilityOpenClaw DocsPlugin manifestOpenClaw DocsClawHub security audits原文链接插件权限、安装、升级和版本兼容 | Harries Blog™