安装插件

本页介绍 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

维护者若要测试设置阶段安装（setup-time installs），可以使用受保护的环境变量覆盖自动插件安装源。参见 插件安装覆盖。

内置插件和经过验证的第一方目录插件在设置、安装、启用、更新或 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 包（不是技能；技能请使用 openclaw skills search）。默认 --limit 为 20，上限为 100。它只读取远程目录：不检查本地状态、不修改配置、不安装包，也不加载插件运行时。结果包括 ClawHub 包名、系列、渠道、版本、摘要，以及安装提示，例如 openclaw plugins install clawhub:<package>。人类可读输出只对数字版本标签添加 v，保留现有前缀和构建名称。JSON 输出保留原始版本值。

来源与定位符¶

从 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 与最低网关兼容性。当所选的 ClawHub 版本发布了 ClawPack 构件时，OpenClaw 会下载带版本号的 npm-pack .tgz，验证 ClawHub 摘要标头和构件摘要，然后通过常规存档路径进行安装。没有 ClawPack 元数据的旧版 ClawHub 仍会通过传统包存档验证路径进行安装。已记录的安装会保留其 ClawHub 来源元数据、构件类型、npm 完整性、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 的包含，都会拒绝执行（fail closed），而不是被展平。支持的形态请参阅 配置包含。

如果安装前配置无效，plugins install 通常会拒绝执行（fail closed），并提示你先运行 openclaw doctor --fix。Doctor 负责 旧版键迁移，并可隔离无效的插件条目。网关启动和热重载会拒绝无效的插件配置，而不会运行该修复。对于插件安装而言，唯一针对预先存在的配置的例外，是一条范围狭窄的捆绑插件恢复路径，仅适用于显式选择加入 openclaw.install.allowInvalidConfigRecovery 的插件。

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

--force 确认与重新安装对比更新¶

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

受管理的 npm 安装会在私有暂存目录中准备包及其依赖项。完整性与平台包检查、安装策略以及构件同意确认都会在替换已安装目录之前完成。在发布之前拒绝或取消，都会使之前的项目保持不变。升级会保留运行中的插件后续导入时可能仍需要的生成路径。

当受管理的 npm 插件缺少包元数据或所需依赖项时，状态和管理都会报告 install incomplete。相关发现与 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-catalog 来源不需要该标志。使用 --link 时，--force 会确认来源，但不会改变链接路径（linked-path）安装模式。

--pin 范围¶

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

OpenClaw 拥有的发布插件在后续更新时，可以恢复对记录版本（不高于 core 版本）的自动跟踪。这适用于旧的手动和自动 pin；当前 update 命令中显式提供的版本仍然优先。请参阅插件更新行为。

--acknowledge-install-policy-warning¶

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

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

ClawHub 安全审计¶

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

Hook 包与 npm 规范¶

plugins install 也是暴露了 package.json 中 openclaw.hooks 的 hook 包的安装入口。请使用 openclaw hooks 进行过滤后的 hook 查看和逐个 hook 启用，而不是用于包安装。

Npm spec 是仅注册表（registry-only）（包名加上可选的精确版本或dist-tag）。Git/URL/file spec 和 semver 范围会被拒绝。依赖安装会在每个插件的受管 npm 项目中以 --ignore-scripts 运行以确保安全，即使你的 shell 有全局 npm 安装设置也是如此。受管插件 npm 项目会继承 OpenClaw 依赖覆盖中与 npm 兼容的部分。pnpm 父子选择器会被跳过；npm 别名会保留，除非已安装的 npm 版本拒绝它们。

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

匹配捆绑插件的原始 @openclaw/* spec 在回退到 npm 之前会解析为镜像自带的捆绑副本。例如，openclaw plugins install @openclaw/discord@2026.5.20 --pin 会使用当前 OpenClaw 构建中的捆绑 Discord 插件，而不是创建受管 npm 覆盖。要强制使用外部 npm 包，请使用 openclaw plugins install npm:@openclaw/discord@2026.5.20 --pin。

裸 spec 和 @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-tag 保持严格：不兼容的选择会失败，并要求你升级 OpenClaw 或选择兼容版本。

如果裸安装 spec 匹配官方插件 id（例如 diffs），OpenClaw 会直接安装目录条目。要安装同名 npm 包，请使用显式的 scope spec（例如 @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>；或者使用 openclaw plugins install git:<repo>@<ref> --force 有意重新安装相同的插件 ID。--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-pack:<path.tgz>，以获得与 registry 安装相同的按插件管理的 npm 项目路径，包括 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

本地路径与打包格式¶

对于本地路径和归档，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 中显式列出独立文件。

使用 -l/--link 指向本地插件目录而不复制它（会添加到 plugins.load.paths）：

openclaw plugins install -l ./my-plugin

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

启用已安装的插件¶

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

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

每个插件保留其自身的策略和能力同意检查。命令在首次失败时停止；先前成功的启用操作保持已提交状态，后续 ID 不会被处理。当本地 Gateway 正在运行时，它会通过该 Gateway 应用每项更改。否则，更改会保存至下次 Gateway 启动时生效。

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

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