OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Plugins

管理插件

Control UI 涵盖常见的发现、安装、启用和禁用工作流。CLI 还提供更新、卸载、高级配置和明确的安装源控制。有关其完整命令契约、标志、源选择规则和边缘情况，请参阅 openclaw plugins。

典型的 CLI 工作流：查找软件包，从 ClawHub、npm、git 或本地路径安装，让托管的 Gateway 网关自动重启（或手动重启），然后验证插件的运行时注册项。

使用 Control UI

在 Control UI 中打开 插件，或使用相对于已配置 Control UI 基础路径的 /settings/plugins。例如，基础路径为 /openclaw 时使用 /openclaw/settings/plugins。该页面有两个选项卡：

  • 已安装显示按类别（渠道、模型提供商、记忆、工具）分组的完整本地清单。每一行都可打开详细信息视图；其溢出 (…) 菜单可启用或禁用插件，对于外部安装的插件，还提供 移除。该选项卡还列出已配置的 MCP 服务器，并提供相同的菜单式启用、禁用和移除操作，同时编辑 Gateway 配置中的 mcp.servers。
  • 发现是插件商店：包括 OpenClaw 随附的精选插件、官方外部插件和精选连接器陈列区。连接器卡片可以一键添加托管的 MCP 服务器（GitHub、Notion、Linear、Sentry、Home Assistant），也可以跳转到预填内容的 ClawHub 搜索。在搜索框中输入内容会以内联方式查询 ClawHub，并附加一个 来自 ClawHub 部分，其中包含下载次数和源验证徽章。

随附插件无需安装软件包。其菜单操作为 启用 或 禁用。例如，Workboard 随 OpenClaw 提供且默认禁用，因此选择 启用 即可将其开启。内置插件无法移除，只能禁用。

目录和搜索访问需要 operator.read。安装、启用、禁用、移除和 MCP 服务器变更需要 operator.admin。ClawHub 安装由 Gateway 网关执行，并保留其信任、完整性和插件安装策略检查。管理员启用已安装的插件时，还会将所选插件添加到现有的限制性 plugins.allow 列表中，以记录这项明确的信任。显式的 plugins.deny 条目仍具有决定权，必须先移除该条目才能启用插件。

安装或移除插件代码需要重启 Gateway 网关。如果已安装的插件和当前 Gateway 网关运行时支持，则启用状态变更无需重启即可应用；否则 UI 会提示需要重启。基于 OAuth 的 MCP 连接器在添加后，仍需通过 CLI 执行一次 openclaw mcp login <name>。

Control UI 不支持从任意 npm、git 或本地路径源安装，也不支持更新插件或公开丰富的插件配置。请使用以下 CLI 工作流执行这些操作。

列出和搜索插件

bash
openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --jsonopenclaw plugins search "calendar"

用于脚本的 --json：

bash
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>）。

启用和禁用插件

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

切换插件的配置条目，而不改动已安装的文件。部分内置插件（内置模型/语音提供商、内置浏览器插件）默认启用；其他插件安装后需要执行 enable。

安装插件

bash
# 在 ClawHub 中搜索插件软件包。openclaw plugins search "calendar" # 从 ClawHub 安装。openclaw plugins install clawhub:<package>openclaw plugins install clawhub:<package>@1.2.3openclaw plugins install clawhub:<package>@beta # 从 npm 安装。openclaw plugins install npm:<package>openclaw plugins install npm:@scope/openclaw-plugin@1.2.3openclaw plugins install npm:@openclaw/codex # 从本地 npm-pack 工件安装。openclaw plugins install npm-pack:<path.tgz> # 从 git 或本地开发检出目录安装。openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0openclaw plugins install ./my-pluginopenclaw 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>。如果现有配置条目存在但无效，安装会失败且不会重写该条目。

重启和检查

启用了配置重新加载的托管 Gateway 网关在安装、更新或卸载插件代码后会自动重启。如果 Gateway 网关未受托管或重新加载已禁用，请在检查实时运行时表面之前自行重启：

bash
openclaw gateway restartopenclaw plugins inspect <plugin-id> --runtime --json

inspect --runtime 会加载插件模块，并证明它已注册运行时表面（工具、钩子、服务、Gateway 网关方法、HTTP 路由、插件自有的 CLI 命令）。普通的 inspect 和 list 仅执行冷清单/配置/注册表检查。

更新插件

bash
openclaw plugins update <plugin-id>openclaw plugins update <npm-package-or-spec>openclaw plugins update --allopenclaw plugins update <plugin-id> --dry-run

传入插件 ID 会复用其受跟踪的安装规范：存储的 dist-tag（@beta）和精确固定版本会沿用到后续的 update <plugin-id> 运行中。

openclaw plugins update --all 是批量维护路径。它仍遵循普通的受跟踪安装规范，但受信任的官方 OpenClaw 插件记录会同步到当前官方目录目标，而不是继续固定到过时的精确官方软件包；当 update.channel 为 beta 时，该同步优先选择 beta 发布线。使用针对性的 update <plugin-id> 可保持精确或带标签的官方规范不变。

对于 npm 安装，传入显式软件包规范可切换受跟踪的记录：

bash
openclaw plugins update @scope/openclaw-plugin@betaopenclaw plugins update @scope/openclaw-plugin

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

有关确切的回退和版本固定规则，请参阅 openclaw plugins。

卸载插件

bash
openclaw plugins uninstall <plugin-id> --dry-runopenclaw plugins uninstall <plugin-id>openclaw plugins uninstall <plugin-id> --keep-files

卸载会移除插件的配置条目、持久化插件索引记录、允许/拒绝列表条目，以及适用时已链接的 plugins.load.paths 条目。除非传入 --keep-files，否则托管安装目录也会被移除。当卸载操作更改插件源时，正在运行的托管 Gateway 网关会自动重启。

在 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-tag/私有注册表 openclaw plugins install npm:@acme/openclaw-plugin

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

发布插件

ClawHub 是 OpenClaw 插件的主要公开发现界面。如果希望用户在安装前找到插件元数据、版本历史记录、注册表扫描结果和安装提示，请发布到该平台。

bash
npm i -g clawhubclawhub loginclawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-pluginclawhub package publish your-org/your-plugin@v1.0.0

原生 npm 插件在发布前必须提供插件清单（openclaw.plugin.json）和 package.json 元数据：

package.json
{  "name": "@acme/openclaw-plugin",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./dist/index.js"]  }}
bash
npm publish --access publicopenclaw plugins install npm:@acme/openclaw-pluginopenclaw plugins install npm:@acme/openclaw-plugin@betaopenclaw plugins install npm:@acme/openclaw-plugin@1.0.0

请使用以下页面了解完整的发布契约，而不要将本页面视为发布参考：

  • ClawHub 发布介绍所有者、作用域、发布、审查、软件包验证和软件包转移。
  • 构建插件展示完整的插件软件包结构（包括 openclaw.plugin.json）和首次发布工作流。
  • 插件清单定义原生插件清单字段。

如果同一软件包同时在 ClawHub 和 npm 上提供，请使用显式的 clawhub: 或 npm: 前缀强制选择其中一个源。

相关内容

Was this useful?
On this page

On this page