管理插件
控制界面(Control UI)涵盖发现、安装、基于 schema 的配置、有效访问权限、启用、重载和移除。CLI 则补充了更新、高级维护和显式安装源控制。有关其完整命令约定、标志、源选择规则和边界情况,请参阅 openclaw plugins。
典型工作流:找到包、安装、启用,然后验证插件的运行时注册。控制界面操作会应用于正在运行的 Gateway,无需重启它。CLI 安装也使用正在运行的本地 Gateway 来处理 npm、Git、本地路径和归档、npm-pack tarball 以及 marketplace 源。这些路径请参阅应用更改并检查。
使用控制界面¶
在控制界面中打开 Plugins(插件),或使用相对于已配置的控制界面基路径的 /plugins。例如,基路径为 /openclaw 时使用 /openclaw/plugins。
Installed plugins(已安装插件) 最多显示 12 个已安装插件,并优先显示已启用、需要设置以及需要注意的插件。使用搜索筛选完整清单,或选择 Show all(显示全部) 浏览所有已安装插件。每张卡片显示插件描述。选择卡片即可打开其设置,管理员可以在其中启用或禁用插件,只读操作员可以检查插件。
从另一个 ClawHub registry 安装的包仍可在 Installed plugins(已安装插件) 下进行管理。它不会将当前目录中间名包标记为已安装。
选择卡片将打开 /settings/plugins/<plugin-id>。该路由页面使用插件声明的 schema 进行配置,以通俗语言解释有效访问权限,并将原始能力声明和授权保留在 Advanced(高级) 下。其 Lifecycle(生命周期) 部分显示源和版本详细信息,并允许管理员 Reload(重载) 插件或在确认后卸载可移除插件。打开 /settings/plugins 可查看可搜索的已安装清单。其 Advanced(高级) 选项卡负责全局插件加载策略、允许和拒绝列表、加载路径以及能力槽位。
随附插件无需安装包。例如,Workboard 随 OpenClaw 提供,默认禁用。捆绑插件可以禁用或重载,但不能移除。
清单、配置和访问检查需要 operator.read。配置、启用、禁用、重载、安装和卸载更改需要 operator.admin。管理员启用已安装插件时,还会通过将所选插件添加到现有限制性 plugins.allow 列表中来记录这一明确的信任。显式的 plugins.deny 条目仍然具有权威性,必须先移除它才能启用该插件。
安装、启用、禁用、移除和重载操作会等待正在运行的 Gateway 应用更改。页面和插件提供的选项卡会在现有连接上刷新。如果应用失败,错误会区分被拒绝的替换与在后续运行时故障之前已发布的更改。即使插件的运行时启动失败,安装仍可能保持已保存状态。页面会刷新该已安装条目,并让失败信息保持可见。修复所报告的问题后,在其 Lifecycle(生命周期) 设置中选择 Reload(重载),或运行 openclaw plugins reload <plugin-id>;无需重复安装。
Reload(重载) 会刷新后端插件及其包条目,同时保留启用状态和当前浏览器连接。通过 plugins.load.paths 加载的已发现插件和捆绑插件也使用相同操作。如果声明的能力发生变化,可能需要在继续前进行审查。成功消息会报告已应用的 Gateway 代次;失败时则保持所报告的应用程序状态和阶段可见。重载不会重建已编译的捆绑代码;该边界请参阅 CLI 重载。单独的 Reload plugin UI(重载插件 UI) 操作只刷新浏览器 UI 模块。
在替换已启用插件之前,Gateway 会验证其元数据和配置,暂停新的插件调用,并在前一代保持活动的同时,最多等待 60 秒让进行中的工作完成。如果工作未完成,重载会失败一次,恢复调用,并让服务和通道继续运行。否则,它会停止服务和通道,排空剩余工作,并在注册替换插件之前完成关闭和释放流程。其他插件实例保持活动。如果注册或发布前激活失败,Gateway 会自动尝试使用捕获的先前代码和配置进行全新注册。恢复会还原活动运行时;它不会重写外部编辑过的配置文件。如果清理或恢复也失败,错误会报告恢复无法完成。发布后的失败仍会在已接受的代次上保持可见。
当不需要记录新的能力同意时,管理员可以使用外部管理的配置或 Nix 配置进行重载。配置和安装更改仍然不可用。如果重载需要新的能力同意,请在重试前通过部署所有者处理该接受事项。
控制界面不会从任意的 npm、git 或本地路径源安装,也不会更新插件包。请使用下面的 CLI 工作流执行这些操作。
列出并搜索插件¶
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search "calendar"
供脚本使用的 --json:
plugins list 是一种冷清单检查:它反映 OpenClaw 能从配置、manifest 和持久化插件 registry 中发现的内容。它并不证明已在运行的 Gateway 已导入该插件运行时。JSON 输出包含 registry 诊断信息以及每个插件的 dependencyStatus(即声明的 dependencies/optionalDependencies 是否能在磁盘上解析)。
plugins search 会向 ClawHub 查询可安装的插件包,并为每个结果打印安装提示(openclaw plugins install clawhub:<package>)。
启用和禁用插件¶
切换插件的配置项,而不改动已安装的文件。部分捆绑插件(捆绑的模型/语音提供商、捆绑的浏览器插件)默认启用;其他插件在安装后需要 enable。
能力授权¶
OpenClaw 会在安装或启用第三方插件之前,要求你审查该插件声明的能力。授权界面会标识插件、其版本和来源、制品完整性以及可用的信任信息。它还会列出声明的通道、提供商、工具、钩子、MCP 服务器、CLI 命令和后端、技能以及危险配置标志,并列出适用于钩子、模型访问和子代理的操作员授权。
来自 OpenClaw 官方目录的捆绑插件和已验证的第一方插件,在设置、安装、启用、更新或 Doctor 修复期间不需要此能力审查。对于单独安装的第一方插件,OpenClaw 会将实际包身份与其目录以及来自 https://clawhub.ai 的已验证 npm 来源记录或官方渠道记录进行核对。仅插件 id 或包名称匹配是不够的:本地副本、归档、git 安装、自定义 ClawHub 注册表以及冲突的来源记录仍需要审查。此豁免不会授予 OAuth 访问权限、操作系统权限或运行时工具批准,也不会创建操作员接受记录。
审查令牌会对确切的声明能力面进行哈希,而不是对插件的可执行文件进行哈希。接受操作会在可用时单独记录安装器提供的制品完整性。当已安装插件的声明面及其记录的完整性未发生变化时,重新启用该插件会复用接受记录。启用插件的更新在新制品声明了额外能力时需要新的授权;未变化或更窄的能力面可以刷新现有有效接受记录。更新已禁用插件会保留禁用状态,并将任何所需授权推迟到启用时。通过 plugins install 重新安装也会保留已编写的 enabled: false,但当无法复用有效接受记录时,需要在提交安装前获得授权。之后运行 openclaw plugins enable <plugin-id> 来激活它。
已启用的第三方旧版安装无需初始审查即可继续使用;禁用并重新启用它们需要授权。设置会在保存最终配置时重新检查授权,因此登录期间的插件更新无法激活具有未接受能力的替换插件。
拒绝更新的能力审查会使之前的插件保持启用且不变。修复缺失或损坏的制品需要新的审查;OpenClaw 无法从无法验证的制品中延续接受记录。
延续较早的接受记录要求安装记录固定制品完整性,注册表和 ClawHub 安装会提供这一点。没有记录完整性的来源——尤其是本地路径——无法证明新的字节是你之前批准的制品,因此它们会在每次安装时要求授权,而不是继承授权。
交互式 CLI 命令、入门引导以及提供商、搜索或通道设置会在需要授权时提示,包括自动安装必需的运行时插件。非交互式或静默设置无法批准新能力。使用 --accept-capabilities 审查并预安装或启用插件,然后重试设置。非交互式插件安装、更新和启用命令在需要授权时也需要显式标志:
openclaw plugins install clawhub:<package> --accept-capabilities
openclaw plugins update <plugin-id> --accept-capabilities
openclaw plugins enable <plugin-id> --accept-capabilities
Doctor 在安装或采用替换插件之前会使用相同的来源检查和审查。doctor --fix 和 --yes 不会自动批准能力。对于非交互式修复,请使用上述显式标志审查并安装插件,然后重新运行 doctor。
聊天安装和启用使用相同的能力授权。当需要授权时,在回复中审查能力,然后使用 --accept-capabilities 重新运行相同命令:
/plugins install clawhub:<package> --accept-capabilities
/plugins install npm:<package> --force --accept-capabilities
/plugins enable <plugin-id> --accept-capabilities
直接在工作区中或通过 plugins.load.paths 发现的插件,如果没有受管理的安装记录,则无法持久化能力接受记录。它们在 Control UI 中的详细信息仍会显示声明的能力。
openclaw plugins install --link <path> 会创建受管理的安装记录,并且即使它从源目录加载插件,也需要能力授权。它与添加一个单独的 plugins.load.paths 条目不同。两者都可以使用自己的插件作用域键控和 blob 状态以及入口队列。链接不会授予钩子代理轮次或 Gateway 作用域提升的信任。
安装插件¶
# Search ClawHub for plugin packages.
openclaw plugins search "calendar"
# Install from ClawHub.
openclaw plugins install clawhub:<package>
openclaw plugins install clawhub:<package>@1.2.3
openclaw plugins install clawhub:<package>@beta
# Install from npm.
openclaw plugins install npm:<package>
openclaw plugins install npm:@scope/openclaw-plugin@1.2.3
openclaw plugins install npm:@openclaw/codex
# Install from a local npm-pack artifact.
openclaw plugins install npm-pack:<path.tgz>
# Install from git or a local development checkout.
openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin
裸包规范会从 npm 安装,除非名称匹配捆绑或官方插件 id,在这种情况下 OpenClaw 会改用该本地/官方副本。使用 clawhub:、npm:、git: 或 npm-pack: 进行确定性的来源选择。OpenClaw 的捆绑和官方目录包与 ClawHub 包一样受信任。新的任意 npm、git、本地路径/归档、npm-pack: 或市场来源,在你审查并信任来源后,需要在非交互式安装中使用 --force。
--force 会确认非 ClawHub 源而不提示,并在需要时覆盖现有安装目标。对于已跟踪的 npm、ClawHub 或 hook-pack 安装的常规升级,请改用 openclaw plugins update。使用 --link 时,--force 仅确认源;链接目录不会被复制或覆盖。
如果新安装的插件需要尚未存在的配置,OpenClaw 会记录该安装,但保持插件禁用。配置 plugins.entries.<id>.config,然后运行 openclaw plugins enable <id>。如果已存在配置项但无效,安装会失败,且不会重写它。
插件包可以暴露多个子条目。安装只会跟踪该包一次,启用每个就绪的子条目,并保留你显式禁用的任何子条目。运行时策略仍可通过 plugins.entries.<child-id>、允许/拒绝列表、通道配置、精确的子加载路径,以及 memory 和 contextEngine 插槽按子条目寻址。
应用更改并检查¶
Control UI 操作和 Gateway 插件管理 RPC 可在不重启 Gateway 的情况下应用插件更改。普通的 CLI 安装、启用、禁用和卸载命令在可用时会使用正在运行的本地 Gateway;更新会在本地包操作完成后刷新它。如果没有正在运行的 Gateway,这些命令会更新本地安装,以便其下次启动时使用。
在默认的 hybrid 重载模式下,在 Control UI、通过 openclaw config 或在 openclaw.json 中保存插件配置也会自动应用。默认情况下,plugins.entries.<id> 下的更改会替换该插件的运行时实例,因此注册、工具、钩子和服务会接收到其新配置。未更改的插件保留其实例。插件可以声明更窄的策略,以保留其实例或要求重启;参见 配置热重载。
CLI 安装支持 npm、Git、本地路径和归档、npm-pack tarball、市场源,以及通过同一所有者安装的官方或 ClawHub 包。有关源选择和权限同意,参见 安装。离线安装后,启动 Gateway 以使用已安装的运行时接口。要检查其注册情况:
Gateway 会复用其当前插件清单,直到启动或显式所有者更新。在编辑源或清单后,运行 openclaw plugins reload <plugin-id>。对于 API 客户端,plugins.reload 接受 plugins: [{ pluginId }] 以重新加载一个已安装插件,或在同一请求中重新加载多个目标;plugins.refresh 会刷新清单。两者都会等待运行时应用并返回一个代次回执。重新加载未更改的捆绑代码或替换已捕获的外部代码会返回 restartRequired: false。如果编译后的捆绑代码在其文件更改后仍保持加载,或者无法验证这些文件,重载会报告 restartRequired: true 并附带警告。编辑源文件后重新构建编译输出,然后在结果要求时重启 Gateway。显式操作在 gateway.reload.mode: "off" 下也可用。参见 插件管理 RPC。
清理是尽力而为的:禁用会移除插件已注册的能力,并尝试停止其服务和清理钩子。成功的更改可能包含关于未完成清理的警告。缓存的模块、原生库或其他进程状态可能会保留到 Gateway 退出。当这些残留项导致问题时,重启是一种恢复选项。
inspect --runtime 会加载插件模块,并证明其已注册运行时接口(工具、钩子、服务、Gateway 方法、HTTP 路由、插件拥有的 CLI 命令)。普通的 inspect 和 list 仅执行冷清单/配置/注册表检查。
从代理会话中管理插件¶
仅限所有者的 plugins 工具可以通过正在运行的 Gateway 列出、检查、搜索、安装、启用、禁用、卸载和重新加载插件。代理安装接受官方目录插件 ID 或 ClawHub 包名。version 选项仅适用于 ClawHub 安装;官方安装使用目录选择。要激活对已安装本地 TypeScript 插件的编辑,请使用其插件 ID 调用 reload。安装新的本地、npm、Git 或归档源仍使用上述 CLI 工作流。
在嵌入式代理运行时中,在正在运行的代码程序稳定后,已应用的更改会在下一次模型请求之前刷新工具。已暂停的程序可能需要进一步的模型步骤来等待完成;已完成的操作和已接受的引导会保留在转录中,并且不会重放。在要求正在运行的程序使用已更改的工具之前,先完成该程序。
托管 Codex 会话会在停止当前原生轮次及其后台终端后,在同一 OpenClaw 会话中继续,然后创建一个带有更新工具的线程。已完成的工具结果、已接受的后续消息以及普通问题答案会作为有界的会话上下文带入该线程。如果原生清理或线程释放失败,该尝试会报告失败,并保留绑定以便恢复,而不是重放已完成的工作。
导入或受监督的原生会话保留其原始所有权和工具定义。它们会报告后端更改,但需要新的托管会话才能使用已更改的工具。其他没有刷新消费者的运行时也是如此。
清单和结果输出是有界的。使用 query 缩小 list 范围,检查特定插件,或使用 Control UI 的 Plugins 页面查看被省略的详情和能力审查。已保存的安装可能比失败的运行时激活存活更久:在重试激活之前,先检查该结果,而不是重新安装它。
更新插件¶
openclaw plugins update <plugin-id>
openclaw plugins update <npm-package-or-spec>
openclaw plugins update --all
openclaw plugins update <plugin-id> --dry-run
传入插件 ID 会复用其跟踪的安装规范:已存储的 dist-tags(@beta)和精确固定版本会延续到后续的 update <plugin-id> 运行中。对于多条目包,任意子 ID 都会解析到同一个被跟踪的包安装,因此所有同级项会一起更新。已移除或重命名的子项会在新的包/索引状态提交前,对其过期条目、允许/拒绝策略、精确加载路径、通道配置以及内存/上下文槽位选择进行协调;保留的/新增的子项以及无关插件会被保留。
如果 OpenClaw 无法证明恰好存在一个包所有者以及完整的子项列表,更新和卸载将失败关闭,且不更改包文件、配置或已安装索引。运行 openclaw plugins registry --refresh,检查 openclaw plugins doctor,并使用 openclaw doctor --fix 修复可修复的旧版索引状态。如果歧义仍然存在,请在重试前重新安装包。
openclaw plugins update --all 是批量维护路径。它会保留精确版本固定和显式标签,包括受信任的官方 OpenClaw 插件记录,因为旧的自动固定无法与操作员的有意固定区分开来。当存在更新的默认发布线版本时,OpenClaw 会报告它,并打印用于替换该固定的显式命令。浮动官方记录仍遵循规范通道解析器,该解析器同时使用 update.channel 和已安装的核心版本。
对于精确固定的 ClawHub 记录,请使用更新器打印的命令有意返回默认发布线:
对于 npm 安装,请传入显式包规范以切换被跟踪的记录:
当插件之前被固定到精确版本或标签时,第二条命令会将其移回注册表的默认发布线。
有关精确回退和固定规则,请参阅 openclaw plugins。
卸载插件¶
openclaw plugins uninstall <plugin-id> --dry-run
openclaw plugins uninstall <plugin-id>
openclaw plugins uninstall <plugin-id> --keep-files
卸载会从插件配置、允许/拒绝列表、内存/上下文槽位、精确关联的 plugins.load.paths 以及(如适用)通道配置条目中,移除该包的持久化安装记录和每个受其拥有的子项的设置。它仅为每个被移除的子项保留一个精确的 enabled: false 标记,以便剩余的模型、提供商或通道选择无法在启动修复期间自动重新安装包。重新安装不会静默重新启用它;再次启用插件会替换该标记。你可以通过任意子 ID 指定多条目包;预览会列出包所有者以及所有将被移除的同级项。除非传入 --keep-files,否则托管安装目录只会被移除一次。在 Gateway 运行时,普通卸载会等待该包的运行时所有者停止,然后再移除文件,并在应用新清单后返回。
如果已安装的 Claw 引用了该插件,预览和卸载会打印受影响的 Claw 包名称。普通插件卸载仍可进行,并可能破坏这些 Claw;请先使用 openclaw claws status 审查所有权。移除 Claw 会释放其对插件的引用,但默认保留进程范围的插件。
在 Nix 模式(OPENCLAW_NIX_MODE=1)下,插件安装、更新、卸载、启用和禁用均被禁用;请改为在安装的 Nix 源中管理这些选择。
选择来源¶
| 来源 | 适用情况 | 示例 |
|---|---|---|
| ClawHub | 当你需要 OpenClaw 原生发现、扫描摘要、版本和提示时 | openclaw plugins install clawhub:<package> |
| git | 当你需要从仓库获取分支、标签或提交时 | openclaw plugins install git:github.com/<owner>/<repo>@<ref> |
| 本地路径 | 当你正在同一台机器上开发或测试插件时 | openclaw plugins install --link ./my-plugin |
| 市场 | 当你正在安装 Claude 兼容的市场插件 | openclaw plugins install <plugin> --marketplace <source> |
| npm pack | 当你通过 npm 安装语义验证本地包工件时 | openclaw plugins install npm-pack:<path.tgz> |
| npmjs.com | 当你已经发布 JavaScript 包或需要 npm dist-tags/私有注册表时 | openclaw plugins install npm:@acme/openclaw-plugin |
托管的本地路径安装必须是插件目录或归档文件。请将独立插件文件放入 plugins.load.paths,而不是使用 plugins install 安装它们。
发布插件¶
ClawHub 是 OpenClaw 插件的主要公共发现界面。当你希望用户在安装前找到插件元数据、版本历史、注册表扫描结果和安装提示时,请在那里发布。
npm i -g clawhub
clawhub login
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
clawhub package publish your-org/your-plugin@v1.0.0
原生 npm 插件在发布前必须附带插件清单(openclaw.plugin.json)以及 package.json 元数据:
```json package.json { "name": "@acme/openclaw-plugin", "version": "1.0.0", "type": "module", "openclaw": { "extensions": ["./dist/index.js"] } }
```bash
npm publish --access public
openclaw plugins install npm:@acme/openclaw-plugin
openclaw plugins install npm:@acme/openclaw-plugin@beta
openclaw plugins install npm:@acme/openclaw-plugin@1.0.0
请使用这些页面作为完整的发布契约,而不是将本页视为发布参考:
- ClawHub 发布 介绍所有者、作用域、 版本发布、审核、包验证和包转移。
- 构建插件 展示完整的插件
包结构(包括
openclaw.plugin.json)以及首次发布 工作流。 - 插件清单 定义原生插件清单 字段。
如果同一个包同时可用在 ClawHub 和 npm 上,请使用显式的
clawhub: 或 npm: 前缀来强制指定其中一个来源。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw