管理 Gateway 插件、hook 包和兼容捆绑包。Documentation Index
Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt
Use this file to discover all available pages before exploring further.
插件系统
安装、启用和排查插件问题的最终用户指南。
Manage plugins
安装、列出、更新、卸载和发布的快速示例。
Plugin bundles
捆绑包兼容性模型。
插件清单
清单字段和配置 schema。
安全
为插件安装提供安全加固。
命令
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 运行命令。该 trace 会将各阶段耗时写入 stderr，并保持 JSON 输出可解析。参见 调试。
捆绑插件随 OpenClaw 一起发布。其中一些默认启用（例如捆绑的模型提供者、捆绑的语音提供者以及捆绑的浏览器插件）；其他则需要
plugins enable。原生 OpenClaw 插件必须包含带内联 JSON Schema（configSchema，即使为空也需要）的 openclaw.plugin.json。兼容捆绑包则使用它们自己的 bundle manifest。plugins list 会显示 Format: openclaw 或 Format: bundle。详细列表/信息输出还会显示 bundle 子类型（codex、claude 或 cursor）以及检测到的 bundle 能力。安装
plugins search 会查询 ClawHub 中可安装的插件包，并打印
可直接安装的包名。它搜索的是 code-plugin 和 bundle-plugin 包，
不是 skills。请使用 openclaw skills search 查询 ClawHub skills。
ClawHub 是大多数插件的主要分发和发现入口。npm
仍然是受支持的后备和直接安装路径。OpenClaw 自有的
@openclaw/* 插件包已重新发布到 npm；请查看当前列表
npmjs.com/org/openclaw 或
插件清单。稳定安装使用 latest。
Beta 通道的安装和更新会优先在可用时使用 npm 的 beta dist-tag，
然后再回退到 latest。Config includes 和无效配置修复
Config includes 和无效配置修复
如果你的
plugins 部分由单文件 $include 支持，plugins install/update/enable/disable/uninstall 会写回到那个被包含的文件，而保持 openclaw.json 不变。根级 includes、include 数组以及带有同级覆盖的 includes 会直接失败，而不是被扁平化。支持的形状请参见 Config includes。如果安装期间配置无效，plugins install 通常会失败并提示你先运行 openclaw doctor --fix。在 Gateway 启动和热重载期间，无效插件配置会像其他无效配置一样直接失败；openclaw doctor --fix 可以隔离无效的插件条目。唯一文档化的安装时例外，是一个狭窄的内置插件恢复路径，适用于显式选择加入 openclaw.install.allowInvalidConfigRecovery 的插件。--force 以及 reinstall 与 update 的区别
--force 以及 reinstall 与 update 的区别
--force 会复用现有安装目标，并就地覆盖已经安装的插件或 hook 包。当你有意从新的本地路径、压缩包、ClawHub 包或 npm 产物重新安装相同 id 时，请使用它。对于已跟踪的 npm 插件常规升级，优先使用 openclaw plugins update <id-or-npm-spec>。如果你对一个已经安装的插件 id 运行 plugins install，OpenClaw 会停止并提示你：正常升级请使用 plugins update <id-or-npm-spec>；如果你确实想从不同来源覆盖当前安装，则使用 plugins install <package> --force。--pin 范围
--pin 范围
--pin 仅适用于 npm 安装。不支持 git: 安装；当你想要锁定来源时，请使用显式 git ref，例如 git:github.com/acme/plugin@v1.2.3。它也不支持 --marketplace，因为 marketplace 安装会持久化 marketplace 源元数据，而不是 npm spec。--dangerously-force-unsafe-install
--dangerously-force-unsafe-install
--dangerously-force-unsafe-install 是一个用于内置危险代码扫描器误报的“破窗”选项。即使内置扫描器报告 critical 发现，它也会允许安装继续，但它不会绕过插件 before_install 钩子策略阻断，也不会绕过扫描失败。这个 CLI 标志适用于插件 install/update 流程。Gateway 支持的 skill 依赖安装使用对应的 dangerouslyForceUnsafeInstall 请求覆盖，而 openclaw skills install 仍是一个独立的 ClawHub skill 下载/安装流程。如果你发布在 ClawHub 上的插件被 registry 扫描阻止，请使用 ClawHub 中的发布者步骤。Hook 包和 npm spec
Hook 包和 npm spec
plugins install 也是安装暴露 package.json 中 openclaw.hooks 的 hook 包的入口。请使用 openclaw hooks 进行过滤后的 hook 可见性和单个 hook 启用，而不是用于包安装。Npm spec 仅限 registry（包名 + 可选的精确版本或 dist-tag）。Git/URL/file spec 和 semver 范围都会被拒绝。出于安全考虑，依赖安装会在项目本地使用 --ignore-scripts 运行，即使你的 shell 配置了全局 npm 安装设置也是如此。当你想显式使用 npm 解析时，请使用 npm:<package>。在启动切换期间，裸包 spec 也会直接从 npm 安装。裸 spec 和 @latest 会保持在稳定通道。如果 npm 将它们解析为预发布版本，OpenClaw 会停止并要求你显式选择预发布标签，例如 @beta/@rc，或者精确的预发布版本，例如 @1.2.3-beta.4。如果一个裸安装 spec 匹配到官方插件 id（例如 diffs），OpenClaw 会直接安装目录条目。若要安装同名的 npm 包，请使用显式的作用域 spec（例如 @scope/diffs）。Git 仓库
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，然后使用常规插件目录安装器。这意味着 manifest 验证、危险代码扫描、包管理器安装工作以及安装记录都表现得像 npm 安装。记录的 git 安装会包含源 URL/ref 以及解析后的提交，以便 openclaw plugins update 之后可以重新解析来源。从 git 安装后，请使用 openclaw plugins inspect <id> --runtime --json 验证运行时注册，例如 gateway 方法和 CLI 命令。如果插件使用 api.registerCli 注册了 CLI 根命令，请通过 OpenClaw 根 CLI 直接执行该命令，例如 openclaw demo-plugin ping。压缩包
压缩包
支持的压缩包：
.zip、.tgz、.tar.gz、.tar。原生 OpenClaw 插件压缩包必须在解压后的插件根目录中包含有效的 openclaw.plugin.json；仅包含 package.json 的压缩包会在 OpenClaw 写入安装记录之前被拒绝。也支持 Claude marketplace 安装。clawhub:<package> 定位符：
npm: 可显式指定仅从 npm 解析：
.tgz，验证 ClawHub digest 头和产物 digest，然后通过常规归档路径安装它。没有 ClawPack 元数据的旧版 ClawHub 版本仍然会通过传统的包归档验证路径安装。已记录的安装会保留其 ClawHub 源元数据、产物类型、npm integrity、npm shasum、tarball 名称和 ClawPack digest 事实，以便后续更新使用。
未版本化的 ClawHub 安装会保留未版本化的已记录 spec，因此 openclaw plugins update 可以跟随较新的 ClawHub 发布；显式版本或标签选择器，例如 clawhub:pkg@1.2.3 和 clawhub:pkg@beta，仍会固定在该选择器上。
Marketplace 简写
当 marketplace 名称存在于 Claude 的本地 registry 缓存~/.claude/plugins/known_marketplaces.json 中时，可使用 plugin@marketplace 简写：
--marketplace：
- Marketplace 源
- 远程 marketplace 规则
- 来自
~/.claude/plugins/known_marketplaces.json的 Claude 已知 marketplace 名称 - 本地 marketplace 根目录或
marketplace.json路径 - GitHub 仓库简写，例如
owner/repo - GitHub 仓库 URL，例如
https://github.com/owner/repo - git URL
- 原生 OpenClaw 插件（
openclaw.plugin.json） - 兼容 Codex 的捆绑包（
.codex-plugin/plugin.json） - 兼容 Claude 的捆绑包（
.claude-plugin/plugin.json或默认 Claude component 布局） - 兼容 Cursor 的捆绑包（
.cursor-plugin/plugin.json）
兼容捆绑包会安装到常规插件根目录，并参与相同的 list/info/enable/disable 流程。当前支持 bundle skills、Claude 命令技能、Claude
settings.json 默认项、Claude .lsp.json / manifest 声明的 lspServers 默认项、Cursor 命令技能，以及兼容的 Codex hook 目录；其他已检测到的 bundle 能力会在诊断/info 中显示，但尚未接入运行时执行。列表
仅显示已启用的插件。
从表格视图切换为每个插件的详细行，显示 source/origin/version/activation 元数据。
机器可读的清单，加上 registry 诊断和包依赖安装状态。
plugins list 会先读取持久化的本地插件 registry；如果 registry 缺失或无效，则回退为仅基于 manifest 的派生结果。它适用于检查插件是否已安装、是否已启用，以及是否对冷启动规划可见，但它并不是对已经运行中的 Gateway 进程的实时探测。更改插件代码、启用状态、hook 策略或 plugins.load.paths 之后，在期望新的 register(api) 代码或 hooks 运行之前，请重启提供该通道的 Gateway。对于远程/容器部署，请确认你重启的是实际的 openclaw gateway run 子进程，而不只是包装进程。plugins list --json 会包含每个插件从 package.json
dependencies 和 optionalDependencies 读取的 dependencyStatus。OpenClaw 会检查这些包名是否存在于插件常规的 Node node_modules 查找路径中；它不会导入插件运行时代码、运行包管理器，或修复缺失的依赖。plugins search 是对远程 ClawHub 目录的查询。它不会检查本地
状态、修改配置、安装包或加载插件运行时代码。搜索结果包括
ClawHub 包名、family、channel、version、summary，以及类似 openclaw plugins install clawhub:<package> 的安装提示。
对于已打包 Docker 镜像中的捆绑插件工作，请将插件
源码目录 bind-mount 到对应的打包源码路径上，例如
/app/extensions/synology-chat。OpenClaw 会在
/app/dist/extensions/synology-chat 之前发现该已挂载的源码覆盖层；单纯复制的源码
目录仍然不会生效，因此常规打包安装仍会使用已编译的 dist。
用于运行时 hook 调试：
openclaw plugins inspect <id> --runtime --json显示来自模块加载检查的已注册 hooks 和诊断信息。运行时检查绝不会安装依赖；请使用openclaw doctor --fix清理旧的依赖状态，或安装缺失的已配置可下载插件。openclaw gateway status --deep --require-rpc确认可达的 Gateway、服务/进程提示、配置路径和 RPC 健康状态。- 未捆绑的 conversation hooks（
llm_input、llm_output、before_agent_finalize、agent_end）需要plugins.entries.<id>.hooks.allowConversationAccess=true。
--link 可避免复制本地目录（会添加到 plugins.load.paths）：
--force 不支持与 --link 同用，因为链接安装会复用源路径，而不是覆盖到一个受管理的安装目标上。在 npm 安装上使用 --pin 会将解析得到的精确 spec（name@version）保存到受管理的插件索引中，同时保留默认的不锁定行为。插件索引
插件安装元数据是机器管理的状态，不是用户配置。安装和更新会将其写入活动 OpenClaw 状态目录下的plugins/installs.json。其顶层的 installRecords map 是安装元数据的持久来源，包括损坏或缺失插件 manifest 的记录。plugins 数组是基于 manifest 派生的冷 registry 缓存。该文件包含“请勿编辑”警告，并被 openclaw plugins update、uninstall、diagnostics 以及冷插件 registry 使用。
当 OpenClaw 看到配置中已写入的旧版 plugins.installs 记录时，它会把它们迁移到插件索引中并移除该配置键；如果任一写入失败，则会保留配置记录，以免安装元数据丢失。
卸载
uninstall 会从 plugins.entries、持久化的插件索引、插件 allow/deny 列表条目，以及相关联的 plugins.load.paths 条目中移除插件记录。除非设置了 --keep-files，否则如果已跟踪的受管理安装目录位于 OpenClaw 的插件扩展根目录内，卸载还会删除该目录。对于活动的 memory 插件，memory 槽位会重置为 memory-core。
--keep-config 作为已弃用的 --keep-files 别名仍受支持。更新
hooks.internal.installs 中已跟踪的 hook 包安装。
解析 plugin id 与 npm spec 的区别
解析 plugin id 与 npm spec 的区别
当你传入插件 id 时，OpenClaw 会复用该插件记录中的安装 spec。这意味着之前存储的 dist-tag（如
@beta）和精确锁定版本会继续在后续的 update <id> 运行中使用。对于 npm 安装，你也可以传入带 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会把该包名解析回已跟踪的插件记录，更新该已安装插件，并记录新的 npm spec 以供未来基于 id 的更新使用。只传入不带版本或标签的 npm 包名也会解析回已跟踪的插件记录。当某个插件曾被锁定到精确版本，而你想把它切回 registry 的默认发布线时，可以使用这种方式。Beta channel updates
Beta channel updates
openclaw plugins update 会在你未传入新 spec 时复用已跟踪的插件 spec。openclaw update 还会识别当前 OpenClaw 更新通道：在 beta 通道上，默认发布线的 npm 和 ClawHub 插件记录会先尝试 @beta，如果没有 beta 版本则回退到记录中的默认/latest spec。精确版本和显式标签会继续固定在该选择器上。Version checks and integrity drift
Version checks and integrity drift
在进行实时 npm 更新之前，OpenClaw 会将已安装包版本与 npm registry 元数据进行检查。如果已安装版本与记录的产物标识已经匹配解析目标，则会跳过更新，不会下载、重新安装或重写
openclaw.json。当存储的完整性哈希存在且获取到的产物哈希发生变化时，OpenClaw 会将其视为 npm 产物漂移。交互式的 openclaw plugins update 命令会打印预期和实际哈希，并在继续之前要求确认。非交互式更新助手会失败关闭，除非调用方提供明确的继续策略。更新时的 --dangerously-force-unsafe-install
更新时的 --dangerously-force-unsafe-install
--dangerously-force-unsafe-install 也可用于 plugins update，作为插件更新期间内置危险代码扫描误报的破窗覆盖。它仍然不会绕过插件 before_install 策略阻断或扫描失败阻断，并且它只适用于插件更新，不适用于 hook 包更新。检查
--runtime 可加载插件模块并包含已注册的 hooks、工具、命令、服务、gateway 方法和 HTTP 路由。运行时检查会直接报告缺失的插件依赖；安装和修复仍在 openclaw plugins install、openclaw plugins update 和 openclaw doctor --fix 中进行。
插件拥有的 CLI 命令会作为根级 openclaw 命令组安装。inspect --runtime 显示 cliCommands 下的命令后，请以 openclaw <command> ... 的形式运行；例如，注册了 demo-git 的插件可通过 openclaw demo-git ping 验证。
每个插件都会根据其在运行时实际注册的内容进行分类：
- plain-capability — 一种能力类型（例如仅提供者插件）
- hybrid-capability — 多种能力类型（例如文本 + 语音 + 图像）
- hook-only — 只有 hooks，没有能力或 surface
- non-capability — 有工具/命令/服务，但没有能力
--json 标志会输出适合脚本处理和审计的机器可读报告。inspect --all 会渲染全量表格，包含形态、能力类型、兼容性提示、bundle 能力和 hook 摘要列。info 是 inspect 的别名。Doctor
doctor 会报告插件加载错误、manifest/发现诊断信息以及兼容性提示。当一切正常时，它会输出 No plugin issues detected.
如果某个已配置插件存在于磁盘上，但被加载器的路径安全检查阻止，配置验证会保留该插件条目并将其报告为 present but blocked。请修复前面的被阻止插件诊断，例如路径所有权或 world-writable 权限，而不是移除 plugins.entries.<id> 或 plugins.allow 配置。
对于诸如缺少 register/activate 导出的模块形状故障，请使用 OPENCLAW_PLUGIN_LOAD_DEBUG=1 重新运行，以便在诊断输出中包含一个简洁的导出形状摘要。
Registry
plugins registry 来检查持久化 registry 是否存在、是否最新或是否过期。使用 --refresh 可根据持久化插件索引、配置策略以及 manifest/package 元数据重建它。这是一条修复路径，不是运行时激活路径。
Marketplace
marketplace.json 路径、类似 owner/repo 的 GitHub 简写、GitHub 仓库 URL 或 git URL。--json 会输出解析后的源标签以及已解析的 marketplace manifest 和插件条目。