openclaw plugins

管理 Gateway 插件/扩展、Hook Pack 以及兼容包。

相关文档：

• 插件系统：Plugins
• 包兼容性：Plugin bundles
• 插件清单与 Schema：Plugin manifest
• 安全加固：Security

命令

openclaw plugins list
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins uninstall <id>
openclaw plugins doctor
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>

内置插件随 OpenClaw 捆绑发布，但默认处于禁用状态。使用 plugins enable 启用它们。

原生 OpenClaw 插件必须包含 openclaw.plugin.json，其中要有内联 JSON Schema（configSchema，即使为空也要保留）。兼容包则使用自己的包清单格式。

plugins list 会显示 Format: openclaw 或 Format: bundle。详细列表/信息输出还会显示包子类型（codex、claude 或 cursor）以及检测到的包能力。

安装

openclaw plugins install <package>                      # 先查 ClawHub，再查 npm
openclaw plugins install clawhub:<package>              # 仅查 ClawHub
openclaw plugins install <package> --pin                # 锁定版本
openclaw plugins install <path>                         # 本地路径
openclaw plugins install <plugin>@<marketplace>         # 应用市场
openclaw plugins install <plugin> --marketplace <name>  # 应用市场（显式指定）

裸包名会先检查 ClawHub，再回退到 npm。安全提示：安装插件等同于执行代码，请优先使用锁定版本。

plugins install 也是安装 Hook Pack 的入口，Hook Pack 在 package.json 中声明 openclaw.hooks。使用 openclaw hooks 可进行过滤和按钩子启用，不是用来安装包的。

npm 规范仅支持注册表形式（包名 + 可选的精确版本或 dist-tag）。Git/URL/文件规范和 semver 范围会被拒绝。依赖安装使用 --ignore-scripts 以保证安全。

裸规范和 @latest 保持在稳定轨道上。如果 npm 解析到预发布版本，OpenClaw 会停下来让你显式选择，比如 @beta/@rc 或具体预发布版本如 @1.2.3-beta.4。

如果裸安装规范与内置插件 ID 匹配（例如 diffs），OpenClaw 会直接安装内置插件。若要安装同名的 npm 包，请使用显式 scoped 规范（如 @scope/diffs）。

支持的压缩包格式：.zip、.tgz、.tar.gz、.tar。

Claude 应用市场安装同样支持。

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

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

OpenClaw 现在也会对裸 npm 安全包规范优先使用 ClawHub，只有当 ClawHub 没有该包或版本时才回退到 npm：

openclaw plugins install openclaw-codex-app-server

OpenClaw 从 ClawHub 下载包存档，检查声明的插件 API / 最低网关兼容性，再通过常规存档路径安装。已安装记录会保留 ClawHub 来源元数据，方便后续更新。

当应用市场名称存在于 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 ./my-marketplace

应用市场来源可以是：

• Claude 已知应用市场名称（来自 ~/.claude/plugins/known_marketplaces.json）
• 本地应用市场根目录或 marketplace.json 路径
• GitHub 仓库简写，如 owner/repo
• git URL

对于从 GitHub 或 git 加载的远程应用市场，插件条目必须位于克隆的应用市场仓库内。OpenClaw 接受该仓库中的相对路径来源，并拒绝来自远程清单的外部 git、GitHub、URL/存档和绝对路径插件来源。

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

• 原生 OpenClaw 插件（openclaw.plugin.json）
• Codex 兼容包（.codex-plugin/plugin.json）
• Claude 兼容包（.claude-plugin/plugin.json 或默认 Claude 组件布局）
• Cursor 兼容包（.cursor-plugin/plugin.json）

兼容包安装到普通扩展根目录，参与相同的列表/信息/启用/禁用流程。目前支持包技能、Claude 命令技能、Claude settings.json 默认值、Cursor 命令技能和兼容 Codex 钩子目录；其他检测到的包能力会显示在诊断/信息中，但暂未连接到运行时执行。

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

openclaw plugins install -l ./my-plugin

在 npm 安装上使用 --pin 可将解析的精确规范（name@version）保存到 plugins.installs，同时保持默认行为不锁定版本。

卸载

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

uninstall 会从 plugins.entries、plugins.installs、插件白名单以及关联的 plugins.load.paths 条目中删除插件记录。对于活跃的内存插件，内存槽会重置为 memory-core。

默认情况下，卸载还会删除活跃状态目录扩展根目录下的插件安装目录（$OPENCLAW_STATE_DIR/extensions/<id>）。使用 --keep-files 保留磁盘文件。

--keep-config 是 --keep-files 的废弃别名，仍然支持。

更新

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@beta

更新适用于 plugins.installs 中追踪的安装记录，以及 hooks.internal.installs 中追踪的 Hook Pack 安装记录。

传入插件 ID 时，OpenClaw 会复用该插件已记录的安装规范。这意味着之前存储的 dist-tag（如 @beta）和精确锁定版本在后续 update <id> 运行时仍会被使用。

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

当已存储完整性哈希且拉取的构件哈希发生变化时，OpenClaw 会打印警告并在继续前请求确认。在 CI/非交互运行中使用全局 --yes 跳过提示。

查看详情

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

对单个插件进行深度内省，显示标识、加载状态、来源、注册能力、钩子、工具、命令、服务、网关方法、HTTP 路由、策略标志、诊断信息和安装元数据。

每个插件按其运行时实际注册的内容分类：

• plain-capability — 单一能力类型（如仅 Provider 插件）
• hybrid-capability — 多种能力类型（如文字 + 语音 + 图像）
• hook-only — 仅有钩子，无能力或界面
• non-capability — 有工具/命令/服务但无能力

参阅 Plugin shapes 了解更多能力模型说明。

--json 输出适合脚本化和审计的机器可读报告。

info 是 inspect 的别名。

Tips：给你的小龙虾装插件就像给它喂新鲜食料一样，先 plugins list 看看它肚子里已经有什么，再决定装什么新功能。