插件

管理 Gateway(网关) 插件、挂钩包和兼容的包。

插件系统

用于安装、启用和故障排除插件的最终用户指南。

管理插件

用于安装、列出、更新、卸载和发布的快速示例。

插件包

包兼容性模型。

插件清单

清单字段和配置模式。

安全性

插件安装的安全加固。

命令

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search <query>
openclaw plugins search <query> --limit 20
openclaw plugins search <query> --json
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
openclaw plugins info <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins uninstall <id>
openclaw plugins doctor
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
openclaw plugins init <id>
openclaw plugins init <id> --directory ./my-plugin --name "My Plugin"
openclaw plugins build --entry ./dist/index.js
openclaw plugins build --entry ./dist/index.js --check
openclaw plugins validate --entry ./dist/index.js

针对缓慢的安装、检查、卸载或注册表刷新调查，请使用 OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 运行命令。跟踪会将阶段计时写入 stderr 并保持 JSON 输出可解析。请参阅调试。

作者

openclaw plugins init stock-quotes --name "Stock Quotes"
cd stock-quotes
npm run plugin:build
npm run plugin:validate

plugins init 创建一个使用 defineToolPlugin 的最小 TypeScript 工具插件。plugins build 导入该入口，读取其静态工具元数据，写入 openclaw.plugin.json，并保持 package.json openclaw.extensions 对齐。plugins validate 检查生成的清单、包元数据和当前入口导出是否仍然一致。有关完整的创作工作流程，请参阅工具插件。

脚手架编写 TypeScript 源代码，但从构建的 ./dist/index.jsCLI 入口生成元数据，因此该工作流程也适用于已发布的 CLI。当入口不是默认包入口时，请使用 --entry <path>。在 CI 中使用 plugins build --check，以便在生成的元数据过时且不重写文件时失败。

安装

openclaw plugins search "calendar"                   # search ClawHub plugins
openclaw plugins install <package>                      # npm by default
openclaw plugins install clawhub:<package>              # ClawHub only
openclaw plugins install npm:<package>                  # npm only
openclaw plugins install npm-pack:<path.tgz>            # local npm pack through npm install semantics
openclaw plugins install git:github.com/<owner>/<repo>  # git repo
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install <package> --force              # overwrite existing install
openclaw plugins install <package> --pin                # pin version
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path>                         # local path
openclaw plugins install <plugin>@<marketplace>         # marketplace
openclaw plugins install <plugin> --marketplace <name>  # marketplace (explicit)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>

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

plugins search 查询 ClawHub 以查找可安装的插件包并打印可安装的包名称。它搜索 code-plugin 和 bundle-plugin 包，不搜索 skills。请使用 openclaw skills search 来查找 ClawHub skills。

Config includes and invalid-config repair

如果您的 plugins 部分由单个文件 $include 支持，plugins install/update/enable/disable/uninstall 将直接写入该包含文件，并保持 openclaw.json 不变。根包含、包含数组和带有同级覆盖的包含将以失败关闭（fail closed）而不是扁平化的方式处理。有关受支持的形状，请参阅 Config includes。

如果安装期间配置无效，plugins install 通常会失败关闭并告诉您先运行 openclaw doctor --fix。在 Gateway(网关) 启动和热重载期间，无效的插件配置会像任何其他无效配置一样失败关闭；openclaw doctor --fix 可以隔离无效的插件条目。唯一有记录的安装时例外情况是针对明确选择加入 openclaw.install.allowInvalidConfigRecovery 的插件的一条狭窄的 bundled-plugin 恢复路径。

--force and reinstall vs update

--force 复用现有的安装目标并原地覆盖已安装的插件或 hook 包。当您有意从新的本地路径、归档文件、ClawHub 包或 npm 制品重新安装相同的 id 时，请使用此选项。对于已跟踪的 npm 插件的常规升级，建议使用 `openclaw plugins update

`。

如果您针对已安装的插件 id 运行 `plugins install`，OpenClaw 会停止运行，并指引您使用 `plugins update

进行常规升级，或者当您确实想从不同来源覆盖当前安装时，指引您使用plugins install

—force`。

--pin scope

--pin 仅适用于 npm 安装。不支持用于 git: 安装；当您需要固定的源时，请使用显式的 git 引用（例如 git:github.com/acme/[email protected]）。不支持用于 --marketplace，因为 marketplace 安装保留的是 marketplace 源元数据，而不是 npm 规范。

--dangerously-force-unsafe-install

--dangerously-force-unsafe-install 是针对内置危险代码扫描器误报的应急选项。它允许安装继续进行，即使内置扫描器报告 critical 发现，但它不会绕过插件 before_install 挂钩策略阻止，也不会绕过扫描失败。

安装扫描会忽略常见的测试文件和目录，例如 tests/、__tests__/、*.test.* 和 *.spec.*，以避免阻止打包的测试模拟；声明的插件运行时入口点即使使用这些名称之一，仍会被扫描。

此 CLI 标志适用于插件安装/更新流程。Gateway(网关) 支持的技能依赖安装使用匹配的 dangerouslyForceUnsafeInstall 请求覆盖，而 openclaw skills install 仍然是一个独立的 ClawHub 技能下载/安装流程。

如果您在 ClawHub 上发布的插件被注册表扫描隐藏或阻止，请使用 ClawHub 发布中的发布者步骤。--dangerously-force-unsafe-install 仅影响您自己计算机上的安装；它不会要求 ClawHub 重新扫描插件或将被阻止的发布版本设为公开。

npmHook packs and npm specs

plugins install 也是在 package.json 中暴露 openclaw.hooks 的 hook 包的安装界面。使用 openclaw hooks 来过滤 hook 可见性并逐个启用 hook，而不是用于安装包。

npm 规范是 仅限注册表（包名称 + 可选的 确切版本 或 dist-tag）。拒绝 Git/URL/文件规范和 semver 范围。出于安全考虑，依赖安装使用 --ignore-scriptsnpmnpmOpenClawnpm 在项目本地运行，即使您的 shell 具有全局 npm 安装设置。托管插件 npm 根目录继承 OpenClaw 的包级 npm overrides，因此主机安全引脚也适用于提升的插件依赖项。

当您想要明确 npm 解析时，请使用 `npm:

`npmnpm。在启动切换期间，裸包规范也会直接从 npm 安装。

裸规范和 `@latest`OpenClaw 保持在稳定轨道上。OpenClaw 日期戳修正版本（例如 `2026.5.3-1`npmOpenClaw）是用于此检查的稳定版本。如果 npm 将其中任何一个解析为预发布版本，OpenClaw 将停止并要求您使用预发布标签（例如 `@beta`/`@rc`）或确切的预发布版本（例如 `@1.2.3-beta.4`）明确选择加入。

如果裸安装规范与官方插件 ID 匹配（例如 `diffs`OpenClawnpm），OpenClaw 将直接安装目录条目。要安装具有相同名称的 npm 包，请使用显式作用域规范（例如 `@scope/diffs`）。

Git 仓库

使用 `git:

直接从 git 仓库安装。支持的形式包括git:github.com/owner/repo、git:owner/repo、完整的 https://、ssh://、git://、file://以及git@host:owner/repo.git克隆 URL。添加@

或#

` 以在安装前检出分支、标签或提交。

Git 安装会将仓库克隆到一个临时目录，在存在请求的 ref 时对其进行检出，然后使用常规的插件目录安装程序。这意味着清单验证、危险代码扫描、包管理器安装工作以及安装记录的行为与 npm 安装类似。记录的 git 安装包括源 URL/ref 以及解析出的提交，以便 `openclaw plugins update` 可以在稍后重新解析源。

从 git 安装后，使用 `openclaw plugins inspect

—runtime —json来验证运行时注册，例如网关方法和 CLI 命令。如果插件使用api.registerCli注册了一个 CLI 根，请通过 OpenClaw 根 CLI 直接执行该命令，例如openclaw demo-plugin ping`。

Marketplace 简写

当市场名称存在于 ~/.claude/plugins/known_marketplaces.json 处的 Claude 本地注册表缓存中时，使用 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

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

对于本地路径和归档，OpenClaw 会自动检测：

原生 OpenClaw 插件 (OpenClawopenclaw.plugin.json)
Codex 兼容的捆绑包 (.codex-plugin/plugin.json)
Claude 兼容的捆绑包 (.claude-plugin/plugin.json 或默认的 Claude 组件布局)
Cursor 兼容的捆绑包 (.cursor-plugin/plugin.json)

列表

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search <query>
openclaw plugins search <query> --limit 20
openclaw plugins search <query> --json

仅显示已启用的插件。从表格视图切换到包含源/来源/版本/激活元数据的每个插件的详细行。机器可读的清单以及注册表诊断和包依赖安装状态。

Note

plugins list 首先读取持久化的本地插件注册表，当注册表缺失或无效时，使用仅基于清单的派生回退机制。这对于检查插件是否已安装、已启用以及是否对冷启动计划可见非常有用，但它不是对正在运行的 Gateway(网关) 进程的实时运行时探测。在更改插件代码、启用状态、Hook 策略或 plugins.load.paths 后，在期望新的 register(api) 代码或 Hooks 运行之前，请重启服务于该渠道的 Gateway(网关)。对于远程/容器部署，请验证您正在重启的是实际的 openclaw gateway run 子进程，而不仅仅是包装进程。

plugins list --json 包含每个插件的 dependencyStatus，这些依赖来自 package.json dependencies 和 optionalDependencies。OpenClaw 会检查这些包名称是否存在于插件的常规 Node node_modules 查找路径中；它不会导入插件运行时代码，运行包管理器，或修复缺失的依赖项。

plugins search 是一个远程 ClawHub 目录查找操作。它不检查本地状态、变更配置、安装包或加载插件运行时代码。搜索结果包括 ClawHub 包名称、系列、渠道、版本、摘要以及一个安装提示，例如 openclaw plugins install clawhub:<package>。

对于打包的 Docker 镜像内的捆绑插件工作，请将插件源目录绑定挂载到匹配的打包源路径上，例如 /app/extensions/synology-chat。OpenClaw 将在 /app/dist/extensions/synology-chat 之前发现该挂载的源覆盖层；普通的复制源目录将保持惰性，因此正常的打包安装仍使用编译后的 dist 目录。

对于运行时 Hook 调试：

openclaw plugins inspect <id> --runtime --json 显示从模块加载检查过程中注册的钩子和诊断信息。运行时检查从不安装依赖项；使用 openclaw doctor --fix 清理旧的依赖项状态或恢复配置中引用的缺失的可下载插件。
openclaw gateway status --deep --require-rpc 确认可访问的 Gateway(网关) URL/配置文件、服务/进程提示、配置路径和 RPC 运行状况。
非捆绑的对话钩子（llm_input、llm_output、before_model_resolve、before_agent_reply、before_agent_run、before_agent_finalize、agent_end）需要 plugins.entries.<id>.hooks.allowConversationAccess=true。

使用 --link 避免复制本地目录（添加到 plugins.load.paths）：

openclaw plugins install -l ./my-plugin

插件索引

插件安装元数据是机器管理的状态，而非用户配置。安装和更新会将其写入活动 OpenClaw 状态目录下的 plugins/installs.json 中。其顶层 installRecords 映射是安装元数据的持久来源，包括损坏或缺失插件清单的记录。plugins 数组是从清单派生的冷注册表缓存。该文件包含请勿编辑的警告，并由 openclaw plugins update、卸载、诊断和冷插件注册表使用。

当 OpenClaw 在配置中看到已交付的旧版 plugins.installs 记录时，运行时读取会将它们视为兼容性输入，而不重写 openclaw.json。显式插件写入和 openclaw doctor --fix 会将这些记录移动到插件索引中，并在允许配置写入时移除配置键；如果任一写入失败，则保留配置记录，以免丢失安装元数据。

卸载

openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files

uninstall 会从 plugins.entries、持久化插件索引、插件允许/拒绝列表条目以及适用的关联 plugins.load.paths 条目中移除插件记录。除非设置了 --keep-files，否则当受管安装目录位于 OpenClaw 的插件扩展根目录下时，卸载也会移除该目录。对于活动的内存插件，内存插槽将重置为 memory-core。

更新

openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins update <id-or-npm-spec> --dry-run
openclaw plugins update @openclaw/voice-call
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install

更新适用于受管插件索引中已跟踪的插件安装以及 hooks.internal.installs 中已跟踪的 hook-pack 安装。

解析插件 ID 与 npm 规范

当您传递插件 ID 时，OpenClaw 会重用该插件的已记录安装规范。这意味着之前存储的 dist-tag（例如 @beta）和精确固定的版本将在后续 `update

` 运行中继续使用。

对于 npm 安装，您还可以传递带有 dist-tag 或精确版本的显式 npm 包规范。OpenClaw 会将该包名称解析回已跟踪的插件记录，更新该已安装的插件，并记录新的 npm 规范以供将来基于 ID 的更新使用。

在不带版本或标签的情况下传递 npm 包名称也会解析回已跟踪的插件记录。当插件被固定到精确版本且您希望将其移回注册表的默认发布线时，请使用此方法。

Beta 渠道更新

openclaw plugins update 会重用已跟踪的插件规格，除非您传递新的规格。openclaw updateOpenClawnpmClawHub 还知道当前活动的 OpenClaw 更新渠道：在 beta 渠道上，默认行 npm 和 ClawHub 插件记录会首先尝试 @betanpm。如果不存在插件 beta 版本，它们会回退到记录的默认/最新规格；如果 beta 包存在但安装验证失败，npm 插件也会回退。该回退会作为警告报告，不会导致核心更新失败。精确版本和显式标签将保持固定为该选择器。

版本检查与完整性漂移

在进行实际的 npm 更新之前，OpenClaw 会根据 npm 注册表元数据检查已安装的软件包版本。如果已安装的版本和记录的工件标识已匹配解析到的目标，则会跳过更新，而无需下载、重新安装或重写 openclaw.jsonOpenClawnpm。

当存在存储的完整性哈希值且获取的工件哈希值发生变化时，OpenClaw 会将其视为 npm 工件漂移。交互式 openclaw plugins update 命令会打印预期和实际哈希值，并在继续之前请求确认。非交互式更新助手将执行故障关闭，除非调用方提供了显式的继续策略。

更新时的 --dangerously-force-unsafe-install

--dangerously-force-unsafe-install 也可在 plugins update 上作为用于插件更新期间内置危险代码扫描误报的紧急覆盖手段使用。它仍然不会绕过插件 before_install 策略阻止或扫描失败阻止，并且仅适用于插件更新，不适用于 hook-pack 更新。

检查

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

Inspect 默认显示身份、加载状态、来源、清单功能、策略标志、诊断信息、安装元数据、bundle 功能以及检测到的任何 MCP 或 LSP 服务器支持，而不导入插件运行时。添加 --runtime 以加载插件模块并包含已注册的挂钩、工具、命令、服务、网关方法和 HTTP 路由。运行时检查会直接报告缺失的插件依赖；安装和修复操作保留在 openclaw plugins install、openclaw plugins update 和 openclaw doctor --fix 中。

插件拥有的 CLI 命令通常作为根 openclaw 命令组安装，但插件也可以在核心父级（例如 openclaw nodes）下注册嵌套命令。在 inspect --runtime 显示 cliCommands 下的命令后，在列出的路径处运行它；例如，注册了 demo-git 的插件可以使用 openclaw demo-git ping 进行验证。

每个插件根据其在运行时实际注册的内容进行分类：

plain-capability — 一种功能类型（例如仅提供商的插件）
hybrid-capability — 多种功能类型（例如文本 + 语音 + 图像）
hook-only — 仅有挂钩，没有功能或 surfaces
non-capability — 工具/命令/服务但没有功能

有关功能模型的更多信息，请参阅 Plugin shapes。

Doctor

openclaw plugins doctor

doctor 报告插件加载错误、清单/发现诊断、兼容性通知以及过时的插件配置引用（例如缺少的插件槽位）。当安装树和插件配置干净时，它会打印 No plugin issues detected. 如果存在过时的配置但安装树总体健康，摘要会说明这一点，而不是暗示插件完全健康。

如果磁盘上存在已配置的插件，但被加载器的路径安全检查阻止，配置验证将保留插件条目并将其报告为 present but blocked 。请修复先前的插件被阻止诊断（例如路径所有权或全局可写权限），而不是删除 plugins.entries.<id> 或 plugins.allow 配置。

对于模块形状故障（例如缺少 register / activate 导出），请使用 OPENCLAW_PLUGIN_LOAD_DEBUG=1 重新运行，以在诊断输出中包含紧凑的导出形状摘要。

注册表

openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins registry --json

本地插件注册表是 OpenClaw 的持久化冷读模型，用于存储已安装插件的标识、启用状态、源元数据和贡献所有权。正常启动、提供商所有者查找、渠道设置分类和插件清单可以在不导入插件运行时模块的情况下读取它。

使用 plugins registry 检查持久化注册表是否存在、当前还是过时。使用 --refresh 从持久化插件索引、配置策略和清单/包元数据重建它。这是一条修复路径，而不是运行时激活路径。

openclaw doctor --fix 还会修复与注册表相邻的托管 npm 偏差：如果托管插件 npm 根目录下的孤立或已恢复的 @openclaw/* 包遮蔽了捆绑插件，doctor 会删除该过时的包并重建注册表，以便启动时根据捆绑清单进行验证。Doctor 还会将主机 openclaw 包重新链接到声明 peerDependencies.openclaw 的托管 npm 插件中，以便 openclaw/plugin-sdk/* 等包本地运行时导入在更新或 npm 修复后能够正确解析。

Marketplace

openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json

Marketplace 列表接受本地 marketplace 路径、marketplace.json 路径、类似于 owner/repo 的 GitHub 简写、GitHub 仓库 URL 或 git URL。--json 会打印解析的源标签以及解析后的 marketplace 清单和插件条目。