本页列出 OpenClaw 插件管理的常用命令：搜索、安装、更新、检查运行状态和卸载。安装后由托管网关自动重启；未托管时需手动 openclaw gateway restart 后使用 inspect --runtime 验证注册。Nix 模式下（OPENCLAW_NIX_MODE=1）插件的增删改查命令被禁用，需在 Nix 源中管理。

OpenClaw 插件管理命令：安装、更新、卸载与排查

适用以下场景：

• 想快速列出、安装、更新、检查或卸载插件
• 需要选择插件的安装源（ClawHub / npm / git / 本地路径）
• 准备发布插件包，需参考正确的命令

完整的 CLI 协议、标志、源选择规则和边界情况，请参见 openclaw plugins。

大部分安装流程：

1. 搜索包
2. 从 ClawHub、npm、git 或本地路径安装
3. 托管网关自动重启；未托管时手动重启
4. 验证插件的运行时注册

搜索和列出插件

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search "calendar"

在脚本中使用 --json：

openclaw plugins list --json \
  | jq '.plugins[] | {id, enabled, format, source, dependencyStatus}'

plugins list 是冷库存检查，显示 OpenClaw 能从配置、清单和插件注册表中发现的内容；它不证明已运行的网关导入了插件的运行时。JSON 输出包含注册表诊断信息以及每个插件声明的 dependencies 或 optionalDependencies 的静态 dependencyStatus。

plugins search 查询 ClawHub 可安装的插件包，并打印安装提示，如 openclaw plugins install clawhub:<package>。

安装插件

# 从 ClawHub 搜索插件包
openclaw plugins search "calendar"

# 从 ClawHub 安装
openclaw plugins install clawhub:<package>
openclaw plugins install clawhub:<package>@1.2.3
openclaw plugins install clawhub:<package>@beta

# 从 npm 安装
openclaw plugins install npm:<package>
openclaw plugins install npm:@scope/openclaw-plugin@1.2.3
openclaw plugins install npm:@openclaw/codex

# 从本地 npm pack 产物安装
openclaw plugins install npm-pack:<path.tgz>

# 从 git 或本地开发目录安装
openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin

裸包名（不带前缀）在启动切换期间从 npm 安装。需要指定源时请使用 clawhub:、npm:、git: 或 npm-pack: 前缀。如果裸名匹配官方插件 ID，OpenClaw 可直接安装目录条目。

仅在有意覆盖现有安装目标时使用 --force。对于跟踪的 npm、ClawHub 或 hook-pack 安装的常规升级，请使用 openclaw plugins update。

重启与检查

安装、更新或卸载插件代码后，开启配置重载的托管网关会自动重启。若网关未托管或重载已禁用，请手动重启后再检查实时运行时：

openclaw gateway restart
openclaw plugins inspect <plugin-id> --runtime --json

需要证明插件注册了工具、钩子、服务、网关方法、HTTP 路由或插件自带的 CLI 命令等运行时表面时，使用 inspect --runtime。普通的 inspect 和 list 只做冷清单、配置和注册表检查。

更新插件

openclaw plugins update <plugin-id>
openclaw plugins update <npm-package-or-spec>
openclaw plugins update --all
openclaw plugins update <plugin-id> --dry-run

传入插件 ID 时，OpenClaw 重用跟踪的安装规范。之前存储的 dist-tag（如 @beta）和精确固定版本会在后续 update <plugin-id> 中继续使用。

对于 npm 安装，可以传入显式的包规范来切换跟踪记录：

openclaw plugins update @scope/openclaw-plugin@beta
openclaw plugins update @scope/openclaw-plugin

第二条命令将插件从之前固定的精确版本或 tag 移回注册表的默认发布线。

当 openclaw update 在 beta 频道运行时，插件记录可能优先匹配 @beta 版本。关于精确的回退和固定规则，请参见 openclaw plugins。

卸载插件

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

卸载会移除插件的配置项、持久化插件索引记录、允许/拒绝列表条目以及关联的加载路径（如果适用）。托管安装目录会被移除，除非你传入 --keep-files。当卸载改变插件源时，运行中的托管网关会自动重启。

在 Nix 模式（OPENCLAW_NIX_MODE=1）下，插件的安装、更新、卸载、启用和禁用命令均被禁用。需在 Nix 源中管理这些选择。

选择安装源

源	使用场景	示例
ClawHub	想要 OpenClaw 原生发现、扫描摘要、版本和安装提示	openclaw plugins install clawhub:<package>
npmjs.com	已发布 JavaScript 包，或需要 npm dist-tag / 私有注册表	openclaw plugins install npm:@acme/openclaw-plugin
git	需要仓库的某个分支、tag 或 commit	openclaw plugins install git:github.com/<owner>/<repo>@<ref>
本地路径	在同一台机器上开发或测试插件	openclaw plugins install --link ./my-plugin
npm pack	通过 npm 安装语义验证本地包产物	openclaw plugins install npm-pack:<path.tgz>
marketplace	安装 Claude 兼容的 marketplace 插件	openclaw plugins install &lt;plugin&gt; --marketplace <source>

发布插件

ClawHub 是 OpenClaw 插件的公共发现主界面。当你想让用户找到插件的元数据、版本历史、注册表扫描结果和安装提示时，在那里发布。

npm i -g clawhub
clawhub login
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
clawhub package publish your-org/your-plugin@v1.0.0

原生 npm 插件在发布前必须包含插件清单和包元数据：

{
  "name": "@acme/openclaw-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

npm publish --access public
openclaw plugins install npm:@acme/openclaw-plugin
openclaw plugins install npm:@acme/openclaw-plugin@beta
openclaw plugins install npm:@acme/openclaw-plugin@1.0.0

完整的发布协议请查看以下页面：

• ClawHub 发布：所有者、作用域、发布、审查、包验证和包转移。
• 构建插件：插件包结构和首次发布工作流。
• 插件清单：原生插件清单字段定义。

如果同一个包同时存在于 ClawHub 和 npm，使用显式 clawhub: 或 npm: 前缀来强制指定源。

相关文档

• 插件：安装、配置、重启和故障排除
• openclaw plugins：完整 CLI 参考
• 社区插件：公共发现和 ClawHub 发布
• ClawHub：注册表 CLI 操作
• 构建插件：创建插件包
• 插件清单：清单和包元数据

常见问题

怎么搜索 OpenClaw 插件？

使用 openclaw plugins search "关键词" 在 ClawHub 中搜索可安装的插件包，命令会返回安装提示（如 openclaw plugins install clawhub:<package>）。只列出已安装的插件用 openclaw plugins list。

安装插件后没有反应，怎么检查？

先确认网关是否已重启：托管网关会自动重启，未托管时执行 openclaw gateway restart。然后使用 openclaw plugins inspect <插件ID> --runtime --json 查看该插件是否注册了工具、钩子、路由等运行时表面。如果 inspect 显示正常，检查网关日志中是否有加载错误。

如何卸载插件并保留文件？

执行 openclaw plugins uninstall <插件ID> --keep-files。该命令会移除配置项、索引记录和允许/拒绝列表，但保留安装目录下的文件。如果不加 --keep-files，托管安装目录也会被删除。卸载后托管网关会自动重启（若为托管模式）。