跳转至

安装插件

本页介绍 openclaw plugins install:所有受支持的来源定位器、限制安装的信任与安装策略规则,以及它接受的市场界面。它还说明如何启用已安装插件。

安装

当本地 Gateway 正在运行时,plugins install 会通过该 Gateway 应用所有受支持的插件来源,并返回其已应用的代次。如果没有本地 Gateway,它会保存安装以供下次启动使用。丢失的响应或运行时激活失败不会触发第二次本地安装;请检查报告的状态,并在修复激活失败后使用 plugins reload <id>。

替换安装会等待旧插件的进行中工作完成,然后再应用新代次。针对安装自身未变更配置的文件监视器通知不会取消该等待;更新的配置更改仍可能取代它。

当配置已负责插件激活时,请使用 --no-enable。它会安装并记录插件,但不将其添加到 plugins.allow、不将其从 plugins.deny 移除、不启用其条目,也不选择其独占槽位。现有已启用条目保持启用;此标志不会禁用插件。必需配置检查仍然适用,缺少必需配置的插件保持禁用。Hook-pack 安装不支持此标志。

本地路径、归档、npm-pack tarball 和本地 Git 仓库必须位于 Gateway 主机上。市场请求也需要本地连接,因为市场名称可能解析为主机本地注册项。CLI 在发送请求前解析本地路径。Control UI 继续仅提供官方和 ClawHub 来源。

由 claws add 安装的插件依赖会保留 Claw 批次租约;该批次的实时激活与此单插件命令相互独立。

openclaw plugins search "calendar"                      # search ClawHub plugins
openclaw plugins install @openclaw/<package>            # trusted official catalog
openclaw plugins install <package>                       # arbitrary npm package
openclaw plugins install clawhub:<package>                # ClawHub only
openclaw plugins install npm:<package>                    # npm only
openclaw plugins install npm-pack:<path.tgz>               # local npm-pack tarball
openclaw plugins install git:github.com/<owner>/<repo>     # git repo
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install <path>                            # local path or archive
openclaw plugins install -l <path>                         # link instead of copy
openclaw plugins install <plugin>@<marketplace>             # marketplace shorthand
openclaw plugins install <plugin> --marketplace <name>      # marketplace (explicit)
openclaw plugins install <package> --force                  # confirm source / overwrite existing
openclaw plugins install <package> --pin                    # pin resolved npm version
openclaw plugins install <package> --no-enable              # preserve activation policy
openclaw plugins install <package> --acknowledge-install-policy-warning

维护者在测试安装时安装插件时,可使用受保护的环境变量覆盖自动插件安装来源。参见 插件安装覆盖。

Warning

裸包名默认从 npm 安装。捆绑插件 ID 会选择捆绑副本。官方插件 ID 和未限定的官方包名(裸名或 @latest)遵循其目录声明的来源顺序,仅当目标被下架时才切换。仅限 ClawHub 的插件保持在 ClawHub。完整性、兼容性、信任、安装策略和能力授权失败会停止安装,而不会切换来源。如果你确实想要外部 npm 包,请使用 npm:<package>。对于 ClawHub,请使用 clawhub:<package>。将插件安装视为运行代码;优先使用固定版本。

Warning

ClawHub 包和 OpenClaw 的捆绑/官方目录是受信任的安装来源。新的任意 npm、npm-pack:、git、本地路径/归档或市场来源会在继续前发出警告并询问。非交互式任意安装必须在审查并信任来源后传入 --force。同一标志在需要时覆盖现有安装目标。对已跟踪安装的常规更新不需要它。--force 不会绕过 security.installPolicy 或其余安装安全检查。

捆绑插件和已验证的第一方目录插件在设置、安装、启用、更新或 Doctor 修复期间不需要 --accept-capabilities。本地副本和未验证来源仍需要能力授权,即使其包名与官方插件匹配。此豁免不会授予 OAuth、操作系统或运行时工具权限。参见 能力授权。

通过 plugins.load.paths 选择的本地副本(包括 --link 安装)不会继承官方包信任。--force 不会改变该边界。如果通道需要受信任的插件状态(例如其持久入站队列),启动时会记录拒绝并让通道保持阻塞,而不自动重试。Doctor 和 openclaw update status 会显示正在运行的 Gateway 记录的失败,包括来源和补救措施。安装官方 npm 包或 ClawHub 列表项,并从 plugins.load.paths 中移除本地覆盖,然后重启通道。

plugins search 会查询 ClawHub 中可安装的 code-plugin 和 bundle-plugin 包(不是 skills;请使用 openclaw skills search 查询它们)。默认 --limit 为 20,上限为 100。它只读取远程目录:不检查本地状态、不修改配置、不安装包,也不加载插件运行时。结果包括 ClawHub 包名、系列、通道、版本、摘要以及安装提示,例如 openclaw plugins install clawhub:<package>。人类可读输出仅对数字版本标签添加 v,保留现有前缀和构建名称。JSON 输出保留原始版本值。

Note

默认官方安装遵循目录声明的源顺序。 ClawHub 还提供插件发现。OpenClaw 拥有的 @openclaw/* 插件包再次发布在 npm 上;当前列表见 npmjs.com/org/openclaw 或 插件清单。稳定的官方 ClawHub 安装 会先尝试当前运行的 OpenClaw 版本。如果该构建已下架,安装 会回退到原始目录候选项,并显示可见警告,同时保留 该候选项的完整性固定。不兼容的回退会指明所需的 插件 API 或 OpenClaw 版本,并要求你升级或选择明确的 兼容插件版本。 对于 bare/default 或 @latest 意图的全新 beta 通道安装,符合条件的官方 npm 和受信任的 官方 ClawHub 插件会指向已安装核心的精确 beta 版本。如果核心不是 beta 版本,则指向 @beta。 所选版本必须存在于已声明的源中;传入明确版本 可选择其他版本。Doctor、onboarding 和插件更新恢复路径 可以回退到已记录或默认选择器,并显示可见警告。 在 extended-stable 通道上,符合条件的官方插件若为 bare/default 或 @latest 意图,会解析到已安装核心版本(版本绑定插件的基础版本队列)。 安装记录保留请求的选择器。精确固定和明确的 非 latest 标签保留其目标。无关的第三方包不会固定 到核心版本。Doctor 会单独刷新过期的官方运行时插件, 这些插件绑定到当前 OpenClaw 版本队列;现有精确 npm 固定会成为同一注册表上的精确替换版本。

来源与定位器

ClawHub 安装使用显式 clawhub:<package> 定位器:

openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3

裸 npm 安全插件规范默认从 npm 安装,除非它们匹配官方插件 id:

openclaw plugins install openclaw-codex-app-server

使用 npm: 明确指定仅 npm 解析:

openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@openclaw/discord@2026.5.20
openclaw plugins install npm:@scope/plugin-name@1.0.1

OpenClaw 在安装前会检查所声明的插件 API / 最低 gateway 兼容性。当所选 ClawHub 版本发布了 ClawPack 工件时,OpenClaw 会下载带版本的 npm-pack .tgz,验证 ClawHub 摘要头和工件摘要,然后通过常规归档路径安装它。没有 ClawPack 元数据的旧版 ClawHub 版本仍通过旧版软件包归档验证路径安装。已记录的安装会保留其 ClawHub 源元数据、工件类型、npm integrity、npm shasum、tarball 名称以及 ClawPack 摘要事实,用于后续更新。 无版本 ClawHub 安装会保留无版本的已记录规范,以便 openclaw plugins update 可以跟随更新的 ClawHub 版本;显式版本或标签选择器(如 clawhub:pkg@1.2.3 和 clawhub:pkg@beta)仍固定到该选择器。

当旧版元数据提供 files[] 但没有归档摘要时,OpenClaw 会在安装前验证规范提取路径和 SHA-256 哈希。无害的归档拼写(例如反斜杠分隔符)可能规范化为这些路径;缺失、更改或多余的文件以及命名的不支持记录仍会导致验证失败。仅根记录且不产生输出的记录会被忽略。服务器提供的路径和生成的 _meta.json 元数据仍会严格验证。

条目名称仅因大小写或 Unicode 规范化而不同的 ZIP 归档会在所有平台上被拒绝。ClawHub 回退验证会报告归档冲突;软件包作者必须重命名冲突条目并发布更正后的归档,安装才能继续。

配置包含与无效配置修复

如果你的 plugins 部分,或正在更改的 plugins.entries.<id> 条目,由单文件 $include 支撑,plugins install/update/enable/disable/uninstall 会透传写入拥有该更改的最深层包含文件,并保持 openclaw.json 不变。根包含(配置中根对象定义 $include 的每个部分)、包含数组、带有同级覆盖的包含、跨越多个包含文件的更改,以及其自身文件仍定义嵌套 $include 的包含,会失败关闭而不是展平。支持的形状见 配置包含。

如果安装前配置无效,plugins install 通常会失败关闭,并提示你先运行 openclaw doctor --fix。Doctor 负责 旧版键迁移,并可以隔离无效插件条目。Gateway 启动和热重载会拒绝无效插件配置,而不会运行该修复。插件安装中唯一针对现有配置的例外,是一个狭窄的捆绑插件恢复路径,仅适用于明确选择加入 openclaw.install.allowInvalidConfigRecovery 的插件。

当现有主机配置有效,但新安装插件自身的配置缺失时,OpenClaw 会记录该安装为禁用状态,而不是写入无效的启用条目。配置 plugins.entries.<id>.config,然后运行 openclaw plugins enable <id>。如果现有插件配置条目存在但无效,安装会失败且不会重写它。

--force 确认以及重新安装与更新

--force 会在不提示的情况下确认非 ClawHub 源。它不会绕过 security.installPolicy 或其余安装安全检查。当插件或 hook 包已安装时,它还允许替换现有安装。在审查任意 npm、本地、归档、git 或 marketplace 源之后,或在有意重新安装相同 id 时使用它。对于已跟踪 npm 插件的常规升级,优先使用 openclaw plugins update <id-or-npm-spec>。

受管理的 npm 安装会在私有暂存目录中准备包及其依赖项。完整性检查、平台包检查、安装策略和工件授权会在替换已安装目录之前完成。在发布前拒绝或取消会保持之前的项目不变。升级会保留生成路径,运行中的插件后续导入可能仍需要这些路径。

当受管理的 npm 插件缺少包元数据或必需依赖项时,状态和管理会报告 安装不完整。诊断结果和 Doctor 会给出 openclaw plugins install <package-selector> --force,在可用时使用已记录的包选择器。完整的插件仍可能需要对你尚未接受的能力进行同意。仅在审阅该同意请求后,再添加 --accept-capabilities。

如果安装所有权在备份复制期间结束,清理会停止,并保留完整备份和剩余的原始文件。恢复失败时会报告恢复路径。在检查当前安装之前,请保留这些文件;较旧的事务无法覆盖较新的安装进行恢复,也不能使用被替换的备份。

对于已识别的 npm 项目损坏或不完整的安装元数据,OpenClaw 会将受影响的 node_modules、lockfile 和 shrinkwrap 文件隔离到暂存目录之外,并尝试一次重建。报告的隔离路径在失败后仍可用;恢复失败会保持之前的项目不变。

重新安装会保留已编写的 plugins.entries.<id>.enabled: false。--force 不会批准能力:当没有可复用的有效先前接受时,请在安装提交前审阅并接受它们。之后使用 openclaw plugins enable <id> 激活该插件。参见 能力同意。

如果你对已安装的插件 id 运行 plugins install,OpenClaw 会停止,并指向 plugins update <id-or-npm-spec> 以进行常规升级,或指向 plugins install <package> --force(当你确实想从不同来源覆盖当前安装时)。任意来源仍会显示交互式来源警告;非交互式安装必须在审阅后传递 --force。受信任的 ClawHub 和 OpenClaw 目录来源不需要它。使用 --link 时,--force 会确认来源,但不会更改链接路径安装模式。

--pin 作用范围

--pin 仅适用于 npm 安装,并记录解析后的精确 <name>@<version>。它不支持 git: 安装(改为在规范中固定 ref,例如 git:github.com/acme/plugin@v1.2.3),也不支持 --marketplace(marketplace 安装会持久化 marketplace 来源元数据,而不是 npm 规范)。

OpenClaw 拥有的发布插件的后续更新可以恢复对不新于 core 的已记录版本的自动跟踪。这适用于旧的手动和自动 pin;提供给当前更新命令的显式版本仍然优先。参见 插件更新行为。

--acknowledge-install-policy-warning

当 security.installPolicy 在交互式终端中返回 warn 时,OpenClaw 会打印原因和发现,然后使用与可疑 ClawHub 发布相同的确认文案:type: '<plugin>' to install anyway。如果完整渲染的审阅超过 4,000 个字符,OpenClaw 会在提示前失败关闭;请先减少或合并策略输出。匹配的回答会在继续前重新评估已暂存的来源。被拒绝或非交互式的直接 CLI 安装会在提交前停止;审阅后,--acknowledge-install-policy-warning 会显式批准该命令调用的所有警告。Control UI 安装在显示警告后提供 仍然安装;Gateway API 客户端可以使用 acknowledgeInstallPolicyWarning: true 确认已审阅的请求。自动安装本身不会批准策略警告。对于没有显式确认步骤的受管理界面,如果存在等效的直接 CLI 命令,请重新运行该命令;或者在重试受管理流程之前,将 security.installPolicy 更改为对已审阅请求返回 allow。每个已批准的警告都会在继续前重新评估。确认或 --force 都不能覆盖 block 或策略失败。

如果你在 ClawHub 上发布的插件被注册表扫描隐藏或阻止,请使用 ClawHub 发布 中的发布者步骤。此标志不会要求 ClawHub 重新扫描插件,也不会使被阻止的发布公开。已弃用的 --dangerously-force-unsafe-install 标志仍然是空操作。

ClawHub 安全审计

社区 ClawHub 安装会在下载前检查所选发布的信任记录。OpenClaw 会打印结果、精确的审计概览和详情链接。Review 结果是信息性的,安装会继续。如果 ClawHub 禁用下载或返回阻止性审核结果,OpenClaw 会拒绝该发布。官方 ClawHub 包和捆绑的 OpenClaw 插件来源会绕过此发布信任检查。

Hook 包和 npm 规范

plugins install 也是暴露 package.json 中 openclaw.hooks 的 hook 包的安装入口。使用 openclaw hooks 进行过滤后的 hook 可见性和按 hook 启用,而不是包安装。

npm 规范是 仅限注册表(包名加上可选的 精确版本 或 dist-tag)。Git/URL/文件规范和 semver 范围会被拒绝。依赖安装会在每个插件的一个受管理 npm 项目中运行,并出于安全考虑使用 --ignore-scripts,即使你的 shell 有全局 npm 安装设置。受管理的插件 npm 项目会继承 OpenClaw 依赖覆盖中 npm 兼容的部分。pnpm 父子选择器会被跳过;npm 别名会保留,除非已安装的 npm 版本拒绝它们。

使用 npm:<package> 使 npm 解析显式化。裸包规范也会直接从 npm 安装,除非它们匹配官方插件 id。

匹配捆绑插件的原始 @openclaw/* 规范会优先解析到镜像拥有的捆绑副本,而不是 npm 回退。例如,openclaw plugins install @openclaw/discord@2026.5.20 --pin 会使用当前 OpenClaw 构建中的捆绑 Discord 插件,而不是创建受管理的 npm 覆盖。若要强制使用外部 npm 包,请使用 openclaw plugins install npm:@openclaw/discord@2026.5.20 --pin。

裸安装规格和 @latest 保持在稳定轨道上。OpenClaw 带日期戳的修正版本(例如 2026.5.3-1)在此检查中视为稳定版本。如果 npm 将任一形式解析为预发布版本,OpenClaw 会停止,并要求你通过预发布标签(@beta/@rc)或精确预发布版本(@1.2.3-beta.4)显式选择加入。

对于没有精确版本的 npm 安装(npm:<package> 或 npm:<package>@latest),OpenClaw 会在安装前检查解析后的包元数据。如果最新稳定包需要更新的 OpenClaw 插件 API 或最低宿主版本,OpenClaw 会检查较旧的稳定版本,并改为安装最新的兼容版本。精确版本和显式非 latest 的 dist-tags 保持严格:不兼容的选择会失败,并要求你升级 OpenClaw 或选择兼容版本。

如果裸安装规格匹配官方插件 id(例如 diffs),OpenClaw 会直接安装目录条目。要安装同名的 npm 包,请使用显式作用域规格(例如 @scope/diffs)。

Git 仓库

使用 git:<repo> 直接从 git 仓库安装。支持的形式:git:github.com/owner/repo、git:owner/repo、完整的 https://、ssh://、git://、file:// 以及 git@host:owner/repo.git 克隆 URL。添加 @<ref> 或 #<ref> 可在安装前检出分支、标签或提交。

Git 安装会克隆到临时目录,在存在请求的 ref 时检出该 ref,然后使用常规插件目录安装器,因此清单验证、操作员安装策略、包管理器安装操作以及安装记录的行为与 npm 安装一致。记录的 git 安装包含源 URL/ref 以及解析后的提交,以便 openclaw plugins update 之后可以重新解析源。

在不使用 --force 的情况下重新安装相同的 Git 源和 ref 会拒绝已存在的受管检出,即使仓库现在声明了不同的插件 id。对于受跟踪的升级,请使用 openclaw plugins update <id>;若要有意重新安装相同的插件 id,请使用 openclaw plugins install git:<repo>@<ref> --force。--force 不会将现有安装记录迁移到不同的插件 id。

从 git 安装后,使用 openclaw plugins inspect <id> --runtime --json 验证运行时注册项,例如网关方法和 CLI 命令。如果插件通过 api.registerCli 注册了 CLI 根命令,请通过 OpenClaw 根 CLI 直接运行该命令,例如 openclaw demo-plugin ping。

归档

支持的归档:.zip、.tgz、.tar.gz、.tar。原生 OpenClaw 插件归档必须在解压后的插件根目录中包含有效的 openclaw.plugin.json;仅包含 package.json 的归档会在 OpenClaw 写入安装记录之前被拒绝。

当文件是 npm-pack tarball,并且你希望使用与注册表安装相同的按插件管理的 npm 项目路径时,请使用 npm-pack:<path.tgz>,包括 package-lock.json 验证、提升依赖扫描和 npm 安装记录。普通归档路径仍会作为本地归档安装在插件扩展根目录下。

对于扩展根目录中已注册的归档插件,openclaw doctor --fix 会使用已安装的包修复过期或悬空的 node_modules/openclaw 宿主链接。此修复不需要原始归档,也不会重新安装插件。

也支持 Claude 市场安装。

市场简写

当市场名称存在于 Claude 位于 ~/.claude/plugins/known_marketplaces.json 的本地注册表缓存中时,使用 plugin@marketplace 简写:

openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>

使用 --marketplace 显式传递市场源:

openclaw plugins install <plugin-name> --marketplace <marketplace-name>
openclaw plugins install <plugin-name> --marketplace <owner/repo>
openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <plugin-name> --marketplace ./my-marketplace

=== "市场源" {#marketplace-sources}

- 来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知市场名称
- 本地市场根目录或 `marketplace.json` 路径
- GitHub 仓库简写,例如 `owner/repo`
- GitHub 仓库 URL,例如 `https://github.com/owner/repo`
- git URL

=== "远程市场规则" {#remote-marketplace-rules}

对于从 GitHub 或 git 加载的远程市场,插件条目必须保留在克隆的市场仓库内。OpenClaw 接受来自该仓库的相对路径源,并拒绝远程清单中的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径插件源。

本地路径和捆绑包格式

对于本地路径和归档,OpenClaw 会自动检测:

  • 原生 OpenClaw 插件(openclaw.plugin.json)
  • Agent Plugins 捆绑包(根 plugin.json 声明 Agent Plugins 的 $schema)
  • 兼容 Codex 的捆绑包(.codex-plugin/plugin.json)
  • 兼容 Claude 的捆绑包(.claude-plugin/plugin.json,或当该清单文件不存在时默认的 Claude 组件布局)
  • 兼容 Cursor 的捆绑包(.cursor-plugin/plugin.json)

受管的本地安装必须是插件目录或归档。独立的 .js、.mjs、.cjs 和 .ts 插件文件不会被 plugins install 复制到受管插件根目录,也不会通过直接放置在 ~/.openclaw/extensions 或 <workspace>/.openclaw/extensions 中而加载;这些自动发现的根目录会加载插件包或捆绑包目录,并跳过顶层脚本文件作为本地辅助文件。请改为在 plugins.load.paths 中显式列出独立文件。

Note

兼容捆绑包会安装到常规插件根目录,并参与相同的 list/info/enable/disable 流程。目前,捆绑包 skills、捆绑包 MCP 服务器、Agent Plugins skills/MCP(带有 PLUGIN_ROOT/PLUGIN_DATA 子进程契约)、Claude command-skills、Claude settings.json 默认值、Claude .lsp.json / 清单声明的 lspServers 默认值、Cursor command-skills 以及兼容的 Codex hook 目录均受支持;其他检测到的捆绑包能力会显示在 diagnostics/info 中,但尚未接入运行时执行。有关每种格式的映射,请参阅 插件捆绑包。

使用 -l/--link 指向本地插件目录而不复制它(会追加到 plugins.load.paths):

openclaw plugins install -l ./my-plugin

--link 不支持与 --marketplace 或 git: 安装一起使用,并且要求提供一个已存在的本地路径。对于非交互式本地链接,请在审查来源后传递 --force;它会确认来源,但不会复制或覆盖被链接的目录。

Note

从工作区扩展根目录中发现的工作区来源插件,在显式启用之前不会被导入或执行。对于本地开发,请运行 openclaw plugins enable <plugin-id> 或设置 plugins.entries.<plugin-id>.enabled: true;如果你的配置使用了 plugins.allow,也请在那里包含相同的插件 ID。此失败关闭规则 同样适用于通道设置显式针对工作区来源插件进行仅设置加载的情况,因此在该 工作区插件保持禁用或被排除在允许列表之外时,本地通道插件设置代码不会运行。链接安装 和显式的 plugins.load.paths 条目遵循其解析插件来源的常规策略。参见 配置插件策略 和配置参考。

在 npm 安装上使用 --pin 可在受管理的插件索引中保存解析后的精确规格(name@version),同时保持默认行为未固定。

启用已安装的插件

按提供的顺序启用一个或多个已安装的插件:

openclaw plugins enable codex cua-computer
openclaw plugins enable <ids...> --accept-capabilities

每个插件保留自己的策略和能力同意检查。命令会在第一个失败处停止;之前成功启用的插件会保持已提交状态,后续 ID 不会被处理。如果有本地 Gateway 正在运行,它会通过该 Gateway 应用每项更改。否则,更改会保存供下次 Gateway 启动时使用。

openclaw plugins disable <ids...> 遵循相同的输入顺序,并在第一个失败处停止,保留之前的更改。两个命令都保留重复的 ID;每个操作都会看到前一个操作提交的配置。

无论 Gateway 正在运行还是已停止,plugins enable 都会遵守全局禁用、拒绝列表和限制性允许列表。策略拒绝发生在记录能力同意之前;--accept-capabilities 不会将插件添加到允许列表。现有的 ClickClack 显式选择例外仍然适用。当启用请求被阻止时,请先更新已配置的策略。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw