管理插件

使用控制界面¶

控制界面涵盖发现、安装、基于 schema 的配置、有效访问、启用、重新加载和移除。CLI 则增加了更新、高级维护以及显式的安装源控制。有关其完整的命令契约、标志、来源选择规则和边界情况，请参阅 openclaw plugins。

典型工作流程：查找包，安装它，启用它，然后验证插件的运行时注册。控制界面操作会应用到正在运行的 Gateway，而无需重启它。CLI 安装同样使用正在运行的本地 Gateway 来处理 npm、Git、本地路径和归档、npm-pack tarball 以及市场来源。有关这些路径，请参阅应用更改并检查。

打开控制界面中的插件，或使用相对于已配置控制界面基础路径的 /plugins。例如，基础路径为 /openclaw 时，使用 /openclaw/plugins。

已安装插件最多显示 12 个已安装插件，优先显示已启用插件、需要设置的插件和需要关注的插件。使用搜索来筛选完整清单，或选择显示全部浏览所有已安装插件。每张卡片显示插件描述。选择一张卡片以打开其设置，管理员可以在其中启用或禁用该插件，只读操作员可以检查它。

从其他 ClawHub 注册表安装的包仍可在已安装插件下管理。它不会将当前目录中的同名包标记为已安装。

选择一张卡片以打开 /settings/plugins/<plugin-id>。 该路由页面使用插件声明的 schema 进行配置，以通俗易懂的语言解释有效访问，并将原始能力声明和授予保留在高级下。其生命周期部分显示来源和版本详情，并允许管理员在确认后重新加载插件或卸载可移除的插件。 打开 /settings/plugins 以查看可搜索的已安装清单。其高级选项卡负责全局插件加载策略、允许和拒绝列表、加载路径以及能力槽位。

内置插件不需要安装包。例如，Workboard 随 OpenClaw 提供，默认禁用。捆绑插件可以禁用或重新加载，但不能移除。

清单、配置和访问检查需要 operator.read 权限。 配置、启用、禁用、重新加载、安装和卸载更改需要 operator.admin 权限。 管理员启用已安装插件时，还会通过将所选插件添加到现有的限制性 plugins.allow 列表来记录该显式信任。显式的 plugins.deny 条目仍然具有权威性，必须先移除它才能启用该插件。

安装、启用、禁用、移除和重新加载操作会等待正在运行的 Gateway 应用更改。页面和插件提供的选项卡会在现有连接上刷新。如果应用失败，错误信息会区分被拒绝的替换与在后续运行时失败之前已发布的更改。 即使运行时无法启动，安装记录也可能保持保存状态。页面会刷新该已安装条目并保持失败可见。修复报告的问题后，在其生命周期设置中选择重新加载，或运行 openclaw plugins reload <plugin-id>；无需重复安装。

重新加载会刷新后端插件及其包条目，同时保留启用状态和当前浏览器连接。通过 plugins.load.paths 选择的已发现插件和捆绑插件也使用同一操作。已更改的声明能力可能需要审核后才能继续。成功消息会报告已应用的 Gateway 代次；失败则保持其报告的应用状态和阶段可见。重新加载不会重建编译后的捆绑代码；有关该边界，请参阅 CLI 重新加载。单独的 重新加载插件 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 用于脚本：

openclaw plugins list --json \
  | jq '.plugins[] | {id, enabled, format, source, dependencyStatus}'

plugins list 是一项冷清单检查：OpenClaw 可以从配置、清单和持久化插件注册表中发现什么。它并不证明已经正在运行的 Gateway 已导入插件运行时。JSON 输出包含注册表诊断信息以及每个插件的 dependencyStatus（声明的 dependencies/optionalDependencies 是否在磁盘上可解析）。

plugins search 会向 ClawHub 查询可安装的插件包，并为每个结果打印安装提示（openclaw plugins install clawhub:<package>）。

启用和禁用插件¶

openclaw plugins enable <plugin-id>
openclaw plugins disable <plugin-id>

在不改动已安装文件的情况下，切换插件的配置项。某些捆绑插件（捆绑的模型/语音提供商、捆绑的浏览器插件）默认启用；其他插件在安装后需要 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 条目不同。

安装插件¶

# 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。如果没有正在运行的 Gateway，这些命令会更新本地安装，以便其下次启动时使用。

在默认的 hybrid 重载模式下，在 Control UI、通过 openclaw config 或在 openclaw.json 中保存插件配置也会自动应用。默认情况下，plugins.entries.<id> 下的更改会替换该插件的运行时实例，因此注册、工具、钩子和服务会收到其新配置。未更改的插件会保留其实例。插件可以声明更窄的策略，以保留其实例或要求重启；参见配置热重载。

CLI 安装支持 npm、Git、本地路径和归档、npm-pack tar 包、市场来源，以及通过同一所有者安装的官方或 ClawHub 包。有关来源选择和能力授权，参见安装。离线安装后，请启动 Gateway 以使用已安装的运行时表面。要检查其注册：

openclaw plugins inspect <plugin-id> --runtime --json

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 记录，请使用更新器打印的命令有意返回默认发布线：

openclaw plugins install clawhub:<package> --force

对于 npm 安装，请传入显式包规范以切换受跟踪记录：

openclaw plugins update @scope/openclaw-plugin@beta
openclaw plugins update @scope/openclaw-plugin

第二个命令会在插件之前被固定到精确版本或标签时，将其移回注册表的默认发布线。

有关精确的回退和固定规则，请参阅 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 源中管理这些选择。

选择来源¶

托管的本地路径安装必须是插件目录或归档文件。请将独立插件文件放入 plugins.load.paths，而不是使用 plugins install 安装它们。

发布插件¶

ClawHub 是 OpenClaw 插件的主要公共发现入口。当你希望用户在安装前找到插件元数据、版本历史、注册表扫描结果和安装提示时，请发布到 ClawHub。

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: 前缀来强制使用其中一个来源。

相关¶

• 插件 - 安装、配置、重新加载和故障排查
• openclaw plugins - 完整 CLI 参考
• 社区插件 - 公共发现和 ClawHub 发布
• ClawHub - 注册表 CLI 操作
• 构建插件 - 创建插件包
• 插件清单 - 清单和包元数据