插件

管理 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_PLUGIN_LIFECYCLE_TRACE=1。跟踪会将阶段耗时写入 stderr，并保持 JSON 输出可解析。参见调试。

# 安装

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 中可安装的插件包，并打印可直接安装的包名。它搜索代码插件和捆绑插件包，而不是 Skills。对于 ClawHub Skills，请使用 openclaw skills search。

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

openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:[email protected]

在发布切换期间，裸 npm 安全插件 specs 默认从 npm 安装：

openclaw plugins install openclaw-codex-app-server

使用 npm: 来明确仅使用 npm 解析：

openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/[email protected]

OpenClaw 会在安装前检查声明的插件 API / 最低 Gateway 网关兼容性。当选定的 ClawHub 版本发布 ClawPack 构件时，OpenClaw 会下载带版本的 npm-pack .tgz，验证 ClawHub 摘要头和构件摘要，然后通过正常的归档路径安装它。没有 ClawPack 元数据的旧版 ClawHub 版本仍会通过旧版包归档验证路径安装。记录的安装会保留其 ClawHub 来源元数据、构件类型、npm 完整性、npm shasum、tarball 名称和 ClawPack 摘要事实，以供后续更新使用。 未指定版本的 ClawHub 安装会保留未指定版本的记录规范，因此 openclaw plugins update 可以跟随后续的 ClawHub 版本；显式版本或标签选择器（例如 clawhub:[email protected] 和 clawhub:pkg@beta）会继续固定到该选择器。

# 市场简写

当 marketplace 名称存在于 Claude 的本地注册表缓存 ~/.claude/plugins/known_marketplaces.json 中时，使用 plugin@marketplace 简写：

openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>

当你想显式传入 marketplace 来源时，使用 --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）
• Codex 兼容 bundle（.codex-plugin/plugin.json）
• Claude 兼容 bundle（.claude-plugin/plugin.json 或默认 Claude 组件布局）
• Cursor 兼容 bundle（.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

--enabledboolean

仅显示已启用的插件。

--verboseboolean

从表格视图切换为每个插件的详情行，包含来源/起源/版本/激活元数据。

--jsonboolean

机器可读的清单，以及注册表诊断和包依赖安装状态。

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

对于打包 Docker 镜像内的内置插件开发，将插件 源目录 bind-mount 到匹配的已打包源路径上，例如 /app/extensions/synology-chat。OpenClaw 会在 /app/dist/extensions/synology-chat 之前发现该挂载的源 overlay；普通复制的源目录仍处于非活动状态，因此正常的打包安装仍使用编译后的 dist。

用于运行时 hook 调试：

• openclaw plugins inspect <id> --runtime --json 会显示来自模块加载检查过程的已注册 hook 和诊断。运行时检查绝不会安装依赖；使用 openclaw doctor --fix 清理旧版依赖状态，或恢复配置引用的、缺失的可下载插件。
• openclaw gateway status --deep --require-rpc 会确认可访问的 Gateway 网关、服务/进程提示、配置路径和 RPC 健康状态。
• 非内置对话 hook（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 map 是安装元数据的持久来源，包括损坏或缺失插件清单的记录。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 安装。

# 检查

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

默认情况下，Inspect 会显示身份、加载状态、来源、清单能力、策略标志、诊断、安装元数据、bundle 能力，以及任何检测到的 MCP 或 LSP 服务器支持，而不会导入插件运行时。添加 --runtime 可加载插件模块，并包含已注册的 hook、工具、命令、服务、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 — 仅钩子，没有能力或界面
• non-capability — 工具/命令/服务，但没有能力

请参阅 插件形态，了解能力模型的更多信息。

# 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 会移除该陈旧包并重建注册表，以便启动时根据内置清单进行验证。

# 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 清单和插件条目。

# 相关

• 构建插件
• CLI 参考
• 社区插件