chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
4859df1811
commit
32b4add8e6
@ -1,21 +1,21 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想安装或管理 Gateway 网关插件或兼容捆绑包
|
||||
- 你想安装或管理 Gateway 网关插件或兼容的捆绑包
|
||||
- 你想调试插件加载失败问题
|
||||
summary: '`openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、doctor）'
|
||||
title: 插件
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T03:15:12Z"
|
||||
generated_at: "2026-04-24T14:42:51Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 35ef8f54c64ea52d7618a0ef8b90d3d75841a27ae4cd689b4ca8e0cfdcddc408
|
||||
source_hash: bc693d5e3bc49057e1a108ba65a4dcb3bb662c00229e6fa38a0335afba8240e5
|
||||
source_path: cli/plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# `openclaw plugins`
|
||||
|
||||
管理 Gateway 网关插件、hook 包和兼容捆绑包。
|
||||
管理 Gateway 网关插件、hook 包和兼容的捆绑包。
|
||||
|
||||
相关内容：
|
||||
|
||||
@ -46,16 +46,16 @@ openclaw plugins marketplace list <marketplace>
|
||||
openclaw plugins marketplace list <marketplace> --json
|
||||
```
|
||||
|
||||
内置插件会随 OpenClaw 一起提供。其中一些默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）；另一些则需要执行 `plugins enable`。
|
||||
内置插件随 OpenClaw 一起提供。其中一些默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）；其他则需要使用 `plugins enable`。
|
||||
|
||||
原生 OpenClaw 插件必须提供 `openclaw.plugin.json`，并带有内联 JSON Schema（`configSchema`，即使为空也需要）。兼容捆绑包则使用它们自己的捆绑包清单。
|
||||
原生 OpenClaw 插件必须提供 `openclaw.plugin.json`，并内联 JSON Schema（`configSchema`，即使为空也需要）。兼容的捆绑包则使用它们自己的捆绑包清单。
|
||||
|
||||
`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细列表/info 输出还会显示捆绑包子类型（`codex`、`claude` 或 `cursor`）以及检测到的捆绑包能力。
|
||||
`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细的 list/info 输出还会显示捆绑包子类型（`codex`、`claude` 或 `cursor`）以及检测到的捆绑包能力。
|
||||
|
||||
### 安装
|
||||
|
||||
```bash
|
||||
openclaw plugins install <package> # 先 ClawHub，后 npm
|
||||
openclaw plugins install <package> # 先查 ClawHub，再查 npm
|
||||
openclaw plugins install clawhub:<package> # 仅 ClawHub
|
||||
openclaw plugins install <package> --force # 覆盖现有安装
|
||||
openclaw plugins install <package> --pin # 固定版本
|
||||
@ -66,29 +66,29 @@ openclaw plugins install <plugin> --marketplace <name> # marketplace（显式
|
||||
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
|
||||
```
|
||||
|
||||
裸包名会先在 ClawHub 中检查，然后再检查 npm。安全提示：请将插件安装视为运行代码。优先使用固定版本。
|
||||
裸包名会先在 ClawHub 中检查，然后再查 npm。安全提示：请将插件安装视为运行代码。优先使用固定版本。
|
||||
|
||||
如果你的 `plugins` 部分由单文件 `$include` 提供支持，`plugins install/update/enable/disable/uninstall` 会将变更写入该被包含文件，并保持 `openclaw.json` 不变。根级 include、include 数组，以及带有同级覆盖项的 include 会以失败即关闭的方式处理，而不会被展平。支持的结构请参见 [配置 include](/zh-CN/gateway/configuration)。
|
||||
如果你的 `plugins` 部分由单文件 `$include` 提供支持，`plugins install/update/enable/disable/uninstall` 会直接写入该被包含的文件，并保持 `openclaw.json` 不变。根级 include、include 数组以及带有同级覆盖的 include 会以失败关闭的方式处理，而不会被扁平化。支持的形态见 [配置 includes](/zh-CN/gateway/configuration)。
|
||||
|
||||
如果配置无效，`plugins install` 通常会以失败即关闭的方式终止，并提示你先运行 `openclaw doctor --fix`。唯一有文档记录的例外是一个狭窄的内置插件恢复路径，仅适用于显式选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。
|
||||
如果配置无效，`plugins install` 通常会以失败关闭的方式终止，并提示你先运行 `openclaw doctor --fix`。唯一有文档记录的例外是一个狭窄的内置插件恢复路径，仅适用于显式选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。
|
||||
|
||||
`--force` 会复用现有安装目标，并原地覆盖已安装的插件或 hook 包。当你有意从新的本地路径、归档文件、ClawHub 包或 npm 制品重新安装同一个 id 时，请使用它。对于已跟踪 npm 插件的常规升级，优先使用 `openclaw plugins update <id-or-npm-spec>`。
|
||||
`--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`。
|
||||
如果你对一个已安装的插件 id 运行 `plugins install`，OpenClaw 会停止并提示你：常规升级请使用 `plugins update <id-or-npm-spec>`；如果你确实想从不同来源覆盖当前安装，请使用 `plugins install <package> --force`。
|
||||
|
||||
`--pin` 仅适用于 npm 安装。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 源元数据，而不是 npm spec。
|
||||
`--pin` 仅适用于 npm 安装。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。
|
||||
|
||||
`--dangerously-force-unsafe-install` 是用于内置危险代码扫描器误报的紧急破窗选项。即使内置扫描器报告 `critical` 级别问题，它也允许安装继续进行，但它**不会**绕过插件 `before_install` hook 策略阻止，也**不会**绕过扫描失败。
|
||||
`--dangerously-force-unsafe-install` 是一个应急选项，用于处理内置危险代码扫描器的误报。即使内置扫描器报告了 `critical` 发现，它也允许安装继续进行，但它**不会**绕过插件 `before_install` hook 策略拦截，也**不会**绕过扫描失败。
|
||||
|
||||
这个 CLI 标志适用于插件 install/update 流程。由 Gateway 网关支持的 skill 依赖安装使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是单独的 ClawHub skill 下载/安装流程。
|
||||
这个 CLI 标志适用于插件 install/update 流程。由 Gateway 网关支持的 Skills 依赖安装使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载/安装流程。
|
||||
|
||||
`plugins install` 也是暴露 `openclaw.hooks` 的 hook 包在 `package.json` 中的安装入口。请使用 `openclaw hooks` 来进行经过过滤的 hook 可见性查看和按 hook 启用，而不是进行包安装。
|
||||
`plugins install` 也是安装暴露了 `openclaw.hooks` 的 hook 包的安装入口，前提是它们在 `package.json` 中声明。使用 `openclaw hooks` 来查看经过筛选的 hook 可见性以及逐个 hook 启用情况，而不是用于安装包。
|
||||
|
||||
npm spec **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。出于安全考虑，依赖安装会使用 `--ignore-scripts` 运行。
|
||||
Npm spec **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。出于安全考虑，依赖安装使用 `--ignore-scripts` 运行。
|
||||
|
||||
裸 spec 和 `@latest` 会保持在稳定通道上。如果 npm 将它们中的任意一个解析为预发布版本，OpenClaw 会停止，并要求你显式选择加入预发布标签，例如 `@beta`/`@rc`，或者像 `@1.2.3-beta.4` 这样的精确预发布版本。
|
||||
裸 spec 和 `@latest` 会保持在稳定通道。如果 npm 将其中任意一种解析为预发布版本，OpenClaw 会停止，并要求你显式选择加入，例如使用 `@beta`/`@rc` 这样的预发布标签，或使用 `@1.2.3-beta.4` 这样的精确预发布版本。
|
||||
|
||||
如果一个裸安装 spec 与某个内置插件 id 匹配（例如 `diffs`），OpenClaw 会直接安装该内置插件。若要安装同名 npm 包，请使用显式的作用域 spec（例如 `@scope/diffs`）。
|
||||
如果一个裸安装 spec 与内置插件 id 匹配（例如 `diffs`），OpenClaw 会直接安装该内置插件。若要安装同名的 npm 包，请使用显式的带作用域 spec（例如 `@scope/diffs`）。
|
||||
|
||||
支持的归档格式：`.zip`、`.tgz`、`.tar.gz`、`.tar`。
|
||||
|
||||
@ -101,22 +101,22 @@ openclaw plugins install clawhub:openclaw-codex-app-server
|
||||
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
|
||||
```
|
||||
|
||||
现在，OpenClaw 对于裸 npm-safe 插件 spec 也会优先使用 ClawHub。只有当 ClawHub 没有该包或该版本时，它才会回退到 npm：
|
||||
OpenClaw 现在也会优先为裸的 npm-safe 插件 spec 使用 ClawHub。只有当 ClawHub 没有该包或该版本时，它才会回退到 npm：
|
||||
|
||||
```bash
|
||||
openclaw plugins install openclaw-codex-app-server
|
||||
```
|
||||
|
||||
OpenClaw 会从 ClawHub 下载包归档，检查公布的插件 API / 最低网关兼容性，然后通过常规归档路径安装它。记录下来的安装会保留其 ClawHub 源元数据，以便后续更新。
|
||||
OpenClaw 会从 ClawHub 下载包归档，检查其声明的插件 API / 最低 Gateway 网关兼容性，然后通过常规归档路径完成安装。已记录的安装会保留其 ClawHub 来源元数据，以便后续更新。
|
||||
|
||||
当 marketplace 名称存在于 Claude 本地注册表缓存 `~/.claude/plugins/known_marketplaces.json` 中时，可使用 `plugin@marketplace` 简写：
|
||||
当 marketplace 名称存在于 Claude 的本地注册表缓存 `~/.claude/plugins/known_marketplaces.json` 中时，使用 `plugin@marketplace` 简写：
|
||||
|
||||
```bash
|
||||
openclaw plugins marketplace list <marketplace-name>
|
||||
openclaw plugins install <plugin-name>@<marketplace-name>
|
||||
```
|
||||
|
||||
当你想显式传递 marketplace 源时，使用 `--marketplace`：
|
||||
当你想显式传递 marketplace 来源时，使用 `--marketplace`：
|
||||
|
||||
```bash
|
||||
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
|
||||
@ -125,24 +125,24 @@ openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/
|
||||
openclaw plugins install <plugin-name> --marketplace ./my-marketplace
|
||||
```
|
||||
|
||||
Marketplace 源可以是：
|
||||
Marketplace 来源可以是：
|
||||
|
||||
- `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知 marketplace 名称
|
||||
- 本地 marketplace 根目录或 `marketplace.json` 路径
|
||||
- GitHub 仓库简写，例如 `owner/repo`
|
||||
- GitHub 仓库 URL，例如 `https://github.com/owner/repo`
|
||||
- 类似 `owner/repo` 的 GitHub 仓库简写
|
||||
- 类似 `https://github.com/owner/repo` 的 GitHub 仓库 URL
|
||||
- git URL
|
||||
|
||||
对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保留在克隆的 marketplace 仓库内。OpenClaw 接受来自该仓库的相对路径源，并拒绝远程清单中的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径插件源。
|
||||
对于通过 GitHub 或 git 加载的远程 marketplace，插件条目必须保留在克隆后的 marketplace 仓库内部。OpenClaw 接受来自该仓库的相对路径来源，并拒绝远程清单中的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径插件来源。
|
||||
|
||||
对于本地路径和归档文件，OpenClaw 会自动检测：
|
||||
对于本地路径和归档，OpenClaw 会自动检测：
|
||||
|
||||
- 原生 OpenClaw 插件（`openclaw.plugin.json`）
|
||||
- Codex 兼容捆绑包（`.codex-plugin/plugin.json`）
|
||||
- Claude 兼容捆绑包（`.claude-plugin/plugin.json` 或默认 Claude 组件布局）
|
||||
- Cursor 兼容捆绑包（`.cursor-plugin/plugin.json`）
|
||||
|
||||
兼容捆绑包会安装到常规插件根目录中，并参与相同的 list/info/enable/disable 流程。目前，已支持 bundle skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor command-skills 以及兼容的 Codex hook 目录；其他已检测到的捆绑包能力会在诊断/info 中显示，但尚未接入运行时执行。
|
||||
兼容的捆绑包会安装到常规插件根目录中，并参与相同的 list/info/enable/disable 流程。目前，支持捆绑包 Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录；其他检测到的捆绑包能力会显示在 diagnostics/info 中，但尚未接入运行时执行。
|
||||
|
||||
### 列表
|
||||
|
||||
@ -153,7 +153,15 @@ openclaw plugins list --verbose
|
||||
openclaw plugins list --json
|
||||
```
|
||||
|
||||
使用 `--enabled` 仅显示已加载的插件。使用 `--verbose` 可从表格视图切换到按插件显示的详细行，其中包含 source/origin/version/activation 元数据。使用 `--json` 获取机器可读的清单以及注册表诊断信息。
|
||||
使用 `--enabled` 仅显示已加载的插件。使用 `--verbose` 可从表格视图切换为按插件显示的详细行，其中包含 source/origin/version/activation 元数据。使用 `--json` 可获取机器可读的清单和 registry diagnostics。
|
||||
|
||||
`plugins list` 会基于当前 CLI 环境和配置运行设备发现。它适合用于检查某个插件是否已启用/可加载，但它不是对已运行 Gateway 网关进程的实时运行时探测。在修改插件代码、启用状态、hook 策略或 `plugins.load.paths` 后，请重启为该渠道提供服务的 Gateway 网关，然后再期望新的 `register(api)` 代码或 hook 开始运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不仅仅是包装进程。
|
||||
|
||||
对于运行时 hook 调试：
|
||||
|
||||
- `openclaw plugins inspect <id> --json` 会显示在模块加载检查过程中注册的 hook 和 diagnostics。
|
||||
- `openclaw gateway status --deep --require-rpc` 会确认可访问的 Gateway 网关、服务/进程提示、配置路径以及 RPC 健康状态。
|
||||
- 非内置的会话 hook（`llm_input`、`llm_output`、`agent_end`）要求 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
|
||||
|
||||
使用 `--link` 可避免复制本地目录（会添加到 `plugins.load.paths`）：
|
||||
|
||||
@ -161,9 +169,9 @@ openclaw plugins list --json
|
||||
openclaw plugins install -l ./my-plugin
|
||||
```
|
||||
|
||||
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是复制到受管安装目标。
|
||||
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是覆盖受管的安装目标。
|
||||
|
||||
在 npm 安装中使用 `--pin`，可将解析后的精确 spec（`name@version`）保存到 `plugins.installs` 中，而默认行为则保持不固定版本。
|
||||
在 npm 安装时使用 `--pin`，可将解析后的精确 spec（`name@version`）保存到 `plugins.installs` 中，同时保留默认的不固定行为。
|
||||
|
||||
### 卸载
|
||||
|
||||
@ -173,9 +181,9 @@ openclaw plugins uninstall <id> --dry-run
|
||||
openclaw plugins uninstall <id> --keep-files
|
||||
```
|
||||
|
||||
`uninstall` 会从 `plugins.entries`、`plugins.installs`、插件 allowlist，以及在适用时从已链接的 `plugins.load.paths` 条目中移除插件记录。对于活跃的 memory 插件，memory 槽位会重置为 `memory-core`。
|
||||
`uninstall` 会从 `plugins.entries`、`plugins.installs`、插件 allowlist，以及适用时的已链接 `plugins.load.paths` 条目中移除插件记录。对于处于活动状态的 memory 插件，memory 槽位会重置为 `memory-core`。
|
||||
|
||||
默认情况下，卸载还会删除活动 state-dir 插件根目录下的插件安装目录。使用 `--keep-files` 可保留磁盘上的文件。
|
||||
默认情况下，卸载还会删除活动 state-dir 插件根目录下的插件安装目录。使用 `--keep-files` 可以将文件保留在磁盘上。
|
||||
|
||||
`--keep-config` 作为 `--keep-files` 的已弃用别名仍受支持。
|
||||
|
||||
@ -189,19 +197,19 @@ openclaw plugins update @openclaw/voice-call@beta
|
||||
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
|
||||
```
|
||||
|
||||
更新会应用到 `plugins.installs` 中已跟踪的安装，以及 `hooks.internal.installs` 中已跟踪的 hook 包安装。
|
||||
更新适用于 `plugins.installs` 中被跟踪的安装，以及 `hooks.internal.installs` 中被跟踪的 hook 包安装。
|
||||
|
||||
当你传入一个插件 id 时，OpenClaw 会复用为该插件记录的安装 spec。这意味着之前存储的 dist-tag（如 `@beta`）和精确固定版本会在后续 `update <id>` 运行中继续使用。
|
||||
当你传入插件 id 时，OpenClaw 会复用该插件记录的安装 spec。这意味着之前保存的 dist-tag（如 `@beta`）和固定的精确版本，在后续 `update <id>` 运行时会继续被使用。
|
||||
|
||||
对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会将该包名解析回已跟踪的插件记录，更新这个已安装插件，并为将来的基于 id 的更新记录新的 npm spec。
|
||||
对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会将该包名解析回被跟踪的插件记录，更新该已安装插件，并记录新的 npm spec，供未来基于 id 的更新使用。
|
||||
|
||||
传入不带版本或标签的 npm 包名也会解析回已跟踪的插件记录。当某个插件被固定到精确版本，而你想让它回到 registry 的默认发布线时，请使用这种方式。
|
||||
仅传入 npm 包名而不附带版本或标签，也会解析回被跟踪的插件记录。当某个插件被固定到精确版本，而你希望让它回到 registry 的默认发布线时，请使用这种方式。
|
||||
|
||||
在执行实际 npm 更新之前，OpenClaw 会根据 npm registry 元数据检查已安装包版本。如果已安装版本和记录的制品标识已与解析目标匹配，则会跳过更新，不会下载、重新安装或重写 `openclaw.json`。
|
||||
在执行实际的 npm 更新之前，OpenClaw 会根据 npm registry 元数据检查已安装的包版本。如果已安装版本和已记录的构件标识已经与解析出的目标一致，则会跳过更新，不会下载、重新安装，也不会重写 `openclaw.json`。
|
||||
|
||||
当存在已存储的完整性哈希，而抓取到的制品哈希发生变化时，OpenClaw 会将其视为 npm 制品漂移。交互式 `openclaw plugins update` 命令会打印期望哈希和实际哈希，并在继续前请求确认。非交互式更新助手会以失败即关闭的方式终止，除非调用方提供显式的继续策略。
|
||||
当存在已存储的完整性哈希，而获取到的构件哈希发生变化时，OpenClaw 会将其视为 npm 构件漂移。交互式的 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新辅助工具会以失败关闭的方式终止，除非调用方提供显式的继续策略。
|
||||
|
||||
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的紧急破窗覆盖。它仍然不会绕过插件 `before_install` 策略阻止，也不会绕过扫描失败阻止，并且它仅适用于插件更新，不适用于 hook 包更新。
|
||||
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的应急覆盖选项。它仍然不会绕过插件 `before_install` 策略拦截或扫描失败拦截，并且它仅适用于插件更新，不适用于 hook 包更新。
|
||||
|
||||
### 检查
|
||||
|
||||
@ -210,20 +218,20 @@ openclaw plugins inspect <id>
|
||||
openclaw plugins inspect <id> --json
|
||||
```
|
||||
|
||||
对单个插件进行深度检查。显示身份、加载状态、来源、已注册能力、hooks、工具、命令、服务、网关方法、HTTP 路由、策略标志、诊断、安装元数据、捆绑包能力，以及任何已检测到的 MCP 或 LSP 服务器支持。
|
||||
针对单个插件的深度内省。会显示身份信息、加载状态、来源、已注册能力、hook、工具、命令、服务、Gateway 网关方法、HTTP 路由、策略标志、diagnostics、安装元数据、捆绑包能力，以及任何检测到的 MCP 或 LSP 服务器支持。
|
||||
|
||||
每个插件都会根据其在运行时实际注册的内容进行分类：
|
||||
|
||||
- **plain-capability** — 单一能力类型（例如，仅提供商插件）
|
||||
- **hybrid-capability** — 多种能力类型（例如，文本 + 语音 + 图像）
|
||||
- **hook-only** — 仅有 hooks，没有能力或入口面
|
||||
- **non-capability** — 有工具/命令/服务，但没有能力
|
||||
- **plain-capability** —— 一种能力类型（例如仅提供 provider 的插件）
|
||||
- **hybrid-capability** —— 多种能力类型（例如文本 + 语音 + 图像）
|
||||
- **hook-only** —— 只有 hook，没有能力或界面
|
||||
- **non-capability** —— 有工具/命令/服务，但没有能力
|
||||
|
||||
关于能力模型的更多信息，请参见 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。
|
||||
有关能力模型的更多信息，请参见[插件形态](/zh-CN/plugins/architecture#plugin-shapes)。
|
||||
|
||||
`--json` 标志会输出适合脚本和审计使用的机器可读报告。
|
||||
|
||||
`inspect --all` 会渲染一个覆盖全量插件的表格，其中包含形态、能力种类、兼容性提示、捆绑包能力和 hook 摘要列。
|
||||
`inspect --all` 会渲染一个全局表格，其中包含 shape、capability kinds、兼容性提示、捆绑包能力和 hook 摘要列。
|
||||
|
||||
`info` 是 `inspect` 的别名。
|
||||
|
||||
@ -233,8 +241,7 @@ openclaw plugins inspect <id> --json
|
||||
openclaw plugins doctor
|
||||
```
|
||||
|
||||
`doctor` 会报告插件加载错误、清单/发现诊断以及兼容性提示。当一切正常时，它会打印 `No plugin issues
|
||||
detected.`
|
||||
`doctor` 会报告插件加载错误、清单/设备发现 diagnostics，以及兼容性提示。当一切正常时，它会打印 `No plugin issues detected.`。
|
||||
|
||||
对于诸如缺少 `register`/`activate` 导出之类的模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以在诊断输出中包含紧凑的导出形态摘要。
|
||||
|
||||
@ -245,7 +252,7 @@ openclaw plugins marketplace list <source>
|
||||
openclaw plugins marketplace list <source> --json
|
||||
```
|
||||
|
||||
Marketplace 列表支持本地 marketplace 路径、`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL 或 git URL。`--json` 会打印解析后的源标签，以及解析出的 marketplace 清单和插件条目。
|
||||
Marketplace list 接受本地 marketplace 路径、`marketplace.json` 路径、像 `owner/repo` 这样的 GitHub 简写、GitHub 仓库 URL 或 git URL。`--json` 会打印已解析的来源标签，以及解析后的 marketplace 清单和插件条目。
|
||||
|
||||
## 相关内容
|
||||
|
||||
|
||||
@ -7,20 +7,20 @@ sidebarTitle: Install and Configure
|
||||
summary: 安装、配置和管理 OpenClaw 插件
|
||||
title: 插件
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T08:40:03Z"
|
||||
generated_at: "2026-04-24T14:42:52Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 83ab1218d6677ad518a4991ca546d55eed9648e1fa92b76b7433ecd5df569e28
|
||||
source_hash: 947bb7ffc13280fd63f79bb68cb18a37c6614144b91a83afd38e5ac3c5187aed
|
||||
source_path: tools/plugin.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
插件通过新增能力来扩展 OpenClaw：渠道、模型提供商、智能体 harness、工具、技能、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是 **核心** 插件（随 OpenClaw 一起发布），另一些则是 **外部** 插件（由社区在 npm 上发布）。
|
||||
插件通过新增能力来扩展 OpenClaw：渠道、模型提供商、智能体 harness、工具、技能、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是 **核心** 插件（随 OpenClaw 一起发布），另一些则是 **外部** 插件（由社区发布到 npm）。
|
||||
|
||||
## 快速开始
|
||||
|
||||
<Steps>
|
||||
<Step title="查看已加载的内容">
|
||||
<Step title="查看已加载内容">
|
||||
```bash
|
||||
openclaw plugins list
|
||||
```
|
||||
@ -43,12 +43,12 @@ x-i18n:
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
然后在你的配置文件中通过 `plugins.entries.\<id\>.config` 进行配置。
|
||||
然后在你的配置文件中，通过 `plugins.entries.\<id\>.config` 进行配置。
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
如果你更喜欢聊天原生的控制方式，可启用 `commands.plugins: true` 并使用：
|
||||
如果你更喜欢聊天原生控制方式，启用 `commands.plugins: true`，然后使用：
|
||||
|
||||
```text
|
||||
/plugin install clawhub:@openclaw/voice-call
|
||||
@ -56,32 +56,22 @@ x-i18n:
|
||||
/plugin enable voice-call
|
||||
```
|
||||
|
||||
安装路径使用与 CLI 相同的解析器：本地路径/归档文件、显式
|
||||
`clawhub:<pkg>`，或裸包规范（先 ClawHub，后回退到 npm）。
|
||||
安装路径使用与 CLI 相同的解析器：本地路径/归档、显式 `clawhub:<pkg>`，或裸包规范（优先 ClawHub，然后回退到 npm）。
|
||||
|
||||
如果配置无效，安装通常会以安全失败方式终止，并提示你运行
|
||||
`openclaw doctor --fix`。唯一的恢复例外是一个针对内置插件的有限重装路径，
|
||||
适用于选择加入
|
||||
`openclaw.install.allowInvalidConfigRecovery`
|
||||
的插件。
|
||||
如果配置无效，安装通常会以安全失败的方式终止，并引导你使用 `openclaw doctor --fix`。唯一的恢复例外是一个范围很窄的内置插件重装路径，仅适用于选择启用 `openclaw.install.allowInvalidConfigRecovery` 的插件。
|
||||
|
||||
已打包的 OpenClaw 安装不会急切安装每个内置插件的全部运行时依赖树。
|
||||
当某个 OpenClaw 自带的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于活跃状态时，
|
||||
启动过程只会在导入该插件之前修复它声明的运行时依赖。
|
||||
外部插件和自定义加载路径仍然必须通过
|
||||
`openclaw plugins install`
|
||||
进行安装。
|
||||
打包后的 OpenClaw 安装不会急切地安装每个内置插件的运行时依赖树。当某个 OpenClaw 自有的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于活动状态时，启动过程只会在导入该插件前修复它声明的运行时依赖。外部插件和自定义加载路径仍然必须通过 `openclaw plugins install` 安装。
|
||||
|
||||
## 插件类型
|
||||
|
||||
OpenClaw 可识别两种插件格式：
|
||||
|
||||
| 格式 | 工作方式 | 示例 |
|
||||
| ---------- | ---------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
|
||||
| **Bundle** | 与 Codex/Claude/Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
|
||||
| 格式 | 工作方式 | 示例 |
|
||||
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
|
||||
| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 软件包 |
|
||||
| **Bundle** | 与 Codex/Claude/Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
|
||||
|
||||
两者都会显示在 `openclaw plugins list` 中。有关 Bundle 的详细信息，请参阅 [Plugin Bundles](/zh-CN/plugins/bundles)。
|
||||
这两种格式都会显示在 `openclaw plugins list` 中。有关 bundle 的详细信息，请参阅 [Plugin Bundles](/zh-CN/plugins/bundles)。
|
||||
|
||||
如果你正在编写原生插件，请从 [Building Plugins](/zh-CN/plugins/building-plugins)
|
||||
和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。
|
||||
@ -90,37 +80,37 @@ OpenClaw 可识别两种插件格式：
|
||||
|
||||
### 可安装（npm）
|
||||
|
||||
| 插件 | 包 | 文档 |
|
||||
| ---------------- | ---------------------- | ------------------------------------ |
|
||||
| Matrix | `@openclaw/matrix` | [Matrix](/zh-CN/channels/matrix) |
|
||||
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/zh-CN/channels/msteams) |
|
||||
| Nostr | `@openclaw/nostr` | [Nostr](/zh-CN/channels/nostr) |
|
||||
| Voice Call | `@openclaw/voice-call` | [Voice Call](/zh-CN/plugins/voice-call) |
|
||||
| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) |
|
||||
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) |
|
||||
| 插件 | 软件包 | 文档 |
|
||||
| --------------- | ---------------------- | ------------------------------------ |
|
||||
| Matrix | `@openclaw/matrix` | [Matrix](/zh-CN/channels/matrix) |
|
||||
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/zh-CN/channels/msteams) |
|
||||
| Nostr | `@openclaw/nostr` | [Nostr](/zh-CN/channels/nostr) |
|
||||
| Voice Call | `@openclaw/voice-call` | [Voice Call](/zh-CN/plugins/voice-call) |
|
||||
| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) |
|
||||
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) |
|
||||
|
||||
### 核心（随 OpenClaw 一起发布）
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="模型提供商（默认启用）">
|
||||
`anthropic`、`byteplus`、`cloudflare-ai-gateway`、`github-copilot`、`google`、
|
||||
`huggingface`、`kilocode`、`kimi-coding`、`minimax`、`mistral`、`qwen`、
|
||||
`moonshot`、`nvidia`、`openai`、`opencode`、`opencode-go`、`openrouter`、
|
||||
`qianfan`、`synthetic`、`together`、`venice`、
|
||||
`vercel-ai-gateway`、`volcengine`、`xiaomi`、`zai`
|
||||
`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
|
||||
`huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
|
||||
`moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
|
||||
`qianfan`, `synthetic`, `together`, `venice`,
|
||||
`vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Memory 插件">
|
||||
- `memory-core` — 内置的 Memory 搜索（默认通过 `plugins.slots.memory`）
|
||||
- `memory-lancedb` — 按需安装的长期 Memory，支持自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`）
|
||||
- `memory-core` — 内置的 memory 搜索（默认通过 `plugins.slots.memory` 使用）
|
||||
- `memory-lancedb` — 按需安装的长期 memory，带自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`）
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="语音提供商（默认启用）">
|
||||
`elevenlabs`、`microsoft`
|
||||
`elevenlabs`, `microsoft`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="其他">
|
||||
- `browser` — 用于 browser 工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、browser 运行时以及默认 browser 控制服务的内置 browser 插件（默认启用；在替换它之前请先禁用）
|
||||
- `browser` — 用于 browser 工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、browser 运行时以及默认 browser 控制服务的内置 browser 插件（默认启用；替换前请先禁用）
|
||||
- `copilot-proxy` — VS Code Copilot Proxy 桥接（默认禁用）
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -143,32 +133,32 @@ OpenClaw 可识别两种插件格式：
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
| 字段 | 描述 |
|
||||
| ---------------- | --------------------------------------------------------- |
|
||||
| `enabled` | 主开关（默认：`true`） |
|
||||
| `allow` | 插件允许列表（可选） |
|
||||
| `deny` | 插件拒绝列表（可选；拒绝优先） |
|
||||
| `load.paths` | 额外的插件文件/目录 |
|
||||
| `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） |
|
||||
| `entries.\<id\>` | 每个插件的开关 + 配置 |
|
||||
| `enabled` | 总开关（默认：`true`） |
|
||||
| `allow` | 插件允许列表（可选） |
|
||||
| `deny` | 插件拒绝列表（可选；`deny` 优先） |
|
||||
| `load.paths` | 额外的插件文件/目录 |
|
||||
| `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） |
|
||||
| `entries.\<id\>` | 每个插件的开关 + 配置 |
|
||||
|
||||
配置更改 **需要重启 Gateway 网关**。如果 Gateway 网关正在以启用配置监听和进程内重启的方式运行
|
||||
（默认的 `openclaw gateway` 路径），那么在配置写入完成后，
|
||||
通常会自动稍后执行该重启。
|
||||
配置变更 **需要重启 Gateway 网关**。如果 Gateway 网关正在以启用配置监视 + 进程内重启的方式运行（默认的 `openclaw gateway` 路径），通常会在配置写入完成后稍等片刻自动执行重启。原生插件运行时代码或生命周期 hook 没有受支持的热重载路径；在期望更新后的 `register(api)` 代码、`api.on(...)` hook、工具、服务或提供商/运行时 hook 生效之前，请重启为实时渠道提供服务的 Gateway 网关进程。
|
||||
|
||||
`openclaw plugins list` 是本地 CLI/配置快照。那里显示某个插件为 `loaded`，表示从该次 CLI 调用看到的配置/文件来看，该插件可被发现且可被加载。这并不能证明一个已经运行中的远程 Gateway 网关子进程已经重启到相同的插件代码。在 VPS/容器部署且带包装进程的环境中，请向实际的 `openclaw gateway run` 进程发送重启信号，或对正在运行的 Gateway 网关使用 `openclaw gateway restart`。
|
||||
|
||||
<Accordion title="插件状态：已禁用 vs 缺失 vs 无效">
|
||||
- **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。
|
||||
- **缺失**：配置引用了某个插件 id，但在发现过程中未找到该插件。
|
||||
- **缺失**：配置引用了某个插件 id，但发现流程未找到它。
|
||||
- **无效**：插件存在，但其配置与声明的 schema 不匹配。
|
||||
</Accordion>
|
||||
|
||||
## 发现与优先级
|
||||
## 发现顺序与优先级
|
||||
|
||||
OpenClaw 按以下顺序扫描插件（先匹配者生效）：
|
||||
OpenClaw 按以下顺序扫描插件（先匹配者优先）：
|
||||
|
||||
<Steps>
|
||||
<Step title="配置路径">
|
||||
`plugins.load.paths` — 显式文件或目录路径。
|
||||
`plugins.load.paths` — 显式的文件或目录路径。
|
||||
</Step>
|
||||
|
||||
<Step title="工作区插件">
|
||||
@ -192,18 +182,35 @@ OpenClaw 按以下顺序扫描插件（先匹配者生效）：
|
||||
- `plugins.entries.\<id\>.enabled: false` 会禁用该插件
|
||||
- 来自工作区的插件 **默认禁用**（必须显式启用）
|
||||
- 内置插件遵循内建的默认启用集合，除非被覆盖
|
||||
- 独占槽位可强制启用为该槽位选中的插件
|
||||
- 某些选择加入的内置插件会在配置命名了某个
|
||||
由插件拥有的表面时自动启用，例如提供商模型引用、渠道配置或 harness
|
||||
运行时
|
||||
- OpenAI 家族的 Codex 路由保持独立的插件边界：
|
||||
- 独占槽位可以为该槽位强制启用所选插件
|
||||
- 某些内置的可选加入插件会在配置命名了某个插件拥有的表面时自动启用，例如 provider model 引用、渠道配置或 harness 运行时
|
||||
- OpenAI 系列的 Codex 路由保持独立的插件边界：
|
||||
`openai-codex/*` 属于 OpenAI 插件，而内置的 Codex
|
||||
app-server 插件则通过 `embeddedHarness.runtime: "codex"` 或旧版
|
||||
`codex/*` 模型引用来选择
|
||||
`codex/*` model 引用来选择
|
||||
|
||||
## 运行时 Hook 故障排除
|
||||
|
||||
如果某个插件出现在 `plugins list` 中，但 `register(api)` 的副作用或 hook
|
||||
没有在实时聊天流量中运行，请先检查以下几点：
|
||||
|
||||
- 运行 `openclaw gateway status --deep --require-rpc`，确认当前活动的
|
||||
Gateway 网关 URL、profile、配置路径和进程，就是你正在编辑的那些。
|
||||
- 在插件安装/配置/代码变更后重启正在提供服务的 Gateway 网关。在包装容器中，
|
||||
PID 1 可能只是一个 supervisor；请重启或发送信号给子进程
|
||||
`openclaw gateway run`。
|
||||
- 使用 `openclaw plugins inspect <id> --json` 确认 hook 注册和
|
||||
诊断信息。像 `llm_input`、
|
||||
`llm_output` 和 `agent_end` 这样的非内置会话 hook，需要
|
||||
`plugins.entries.<id>.hooks.allowConversationAccess=true`。
|
||||
- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体回合的模型解析前运行；`llm_output` 只会在某次模型尝试产出 assistant 输出后才运行。
|
||||
- 要证明实际生效的会话模型，请使用 `openclaw sessions` 或
|
||||
Gateway 网关的 session/status 表面；调试 provider 负载时，
|
||||
请使用 `--raw-stream --raw-stream-path <path>` 启动 Gateway 网关。
|
||||
|
||||
## 插件槽位（独占类别）
|
||||
|
||||
某些类别是独占的（同一时间只能激活一个）：
|
||||
某些类别是独占的（同一时间只能有一个处于活动状态）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -216,37 +223,37 @@ OpenClaw 按以下顺序扫描插件（先匹配者生效）：
|
||||
}
|
||||
```
|
||||
|
||||
| 槽位 | 控制内容 | 默认值 |
|
||||
| ---------------- | -------------------- | ------------------- |
|
||||
| `memory` | 活跃的 Memory 插件 | `memory-core` |
|
||||
| `contextEngine` | 活跃的上下文引擎 | `legacy`（内建） |
|
||||
| 槽位 | 控制内容 | 默认值 |
|
||||
| --------------- | --------------------- | ------------------- |
|
||||
| `memory` | 活动的 memory 插件 | `memory-core` |
|
||||
| `contextEngine` | 活动的 context engine | `legacy`（内建） |
|
||||
|
||||
## CLI 参考
|
||||
|
||||
```bash
|
||||
openclaw plugins list # 精简清单
|
||||
openclaw plugins list --enabled # 仅显示已加载插件
|
||||
openclaw plugins list --verbose # 每个插件的详细信息行
|
||||
openclaw plugins list --json # 机器可读清单
|
||||
openclaw plugins inspect <id> # 深度详情
|
||||
openclaw plugins inspect <id> --json # 机器可读
|
||||
openclaw plugins inspect --all # 全部插件表格
|
||||
openclaw plugins info <id> # inspect 别名
|
||||
openclaw plugins doctor # 诊断
|
||||
openclaw plugins list # compact inventory
|
||||
openclaw plugins list --enabled # only loaded plugins
|
||||
openclaw plugins list --verbose # per-plugin detail lines
|
||||
openclaw plugins list --json # machine-readable inventory
|
||||
openclaw plugins inspect <id> # deep detail
|
||||
openclaw plugins inspect <id> --json # machine-readable
|
||||
openclaw plugins inspect --all # fleet-wide table
|
||||
openclaw plugins info <id> # inspect alias
|
||||
openclaw plugins doctor # diagnostics
|
||||
|
||||
openclaw plugins install <package> # 安装（先 ClawHub，后 npm）
|
||||
openclaw plugins install clawhub:<pkg> # 仅从 ClawHub 安装
|
||||
openclaw plugins install <spec> --force # 覆盖现有安装
|
||||
openclaw plugins install <path> # 从本地路径安装
|
||||
openclaw plugins install -l <path> # 链接（不复制），用于开发
|
||||
openclaw plugins install <package> # install (ClawHub first, then npm)
|
||||
openclaw plugins install clawhub:<pkg> # install from ClawHub only
|
||||
openclaw plugins install <spec> --force # overwrite existing install
|
||||
openclaw plugins install <path> # install from local path
|
||||
openclaw plugins install -l <path> # link (no copy) for dev
|
||||
openclaw plugins install <plugin> --marketplace <source>
|
||||
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
|
||||
openclaw plugins install <spec> --pin # 记录精确解析后的 npm spec
|
||||
openclaw plugins install <spec> --pin # record exact resolved npm spec
|
||||
openclaw plugins install <spec> --dangerously-force-unsafe-install
|
||||
openclaw plugins update <id-or-npm-spec> # 更新单个插件
|
||||
openclaw plugins update <id-or-npm-spec> # update one plugin
|
||||
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
|
||||
openclaw plugins update --all # 更新全部
|
||||
openclaw plugins uninstall <id> # 移除配置/安装记录
|
||||
openclaw plugins update --all # update all
|
||||
openclaw plugins uninstall <id> # remove config/install records
|
||||
openclaw plugins uninstall <id> --keep-files
|
||||
openclaw plugins marketplace list <source>
|
||||
openclaw plugins marketplace list <source> --json
|
||||
@ -255,59 +262,31 @@ openclaw plugins enable <id>
|
||||
openclaw plugins disable <id>
|
||||
```
|
||||
|
||||
内置插件随 OpenClaw 一起发布。许多插件默认启用（例如
|
||||
内置模型提供商、内置语音提供商以及内置 browser
|
||||
插件）。其他内置插件仍然需要执行 `openclaw plugins enable <id>`。
|
||||
内置插件随 OpenClaw 一起发布。许多插件默认启用（例如内置模型提供商、内置语音提供商，以及内置 browser 插件）。其他内置插件仍然需要执行 `openclaw plugins enable <id>`。
|
||||
|
||||
`--force` 会原地覆盖已安装的现有插件或 hook 包。对于已跟踪 npm
|
||||
插件的常规升级，请使用 `openclaw plugins update <id-or-npm-spec>`。
|
||||
它不支持与 `--link` 一起使用，因为后者会复用源路径，
|
||||
而不是复制到受管理的安装目标。
|
||||
`--force` 会就地覆盖现有已安装的插件或 hook 包。对于受跟踪的 npm 插件的常规升级，请使用 `openclaw plugins update <id-or-npm-spec>`。它不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，而不是复制到受管理的安装目标中。
|
||||
|
||||
当 `plugins.allow` 已经设置时，`openclaw plugins install` 会在启用插件之前
|
||||
将已安装插件的 id 添加到该允许列表中，因此重启后即可立即加载。
|
||||
当已经设置了 `plugins.allow` 时，`openclaw plugins install` 会在启用插件之前，将已安装插件的 id 添加到该允许列表中，因此重启后即可立即加载。
|
||||
|
||||
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。
|
||||
传入带有 dist-tag 或精确版本的 npm 包 spec 时，会将包名解析回已跟踪的插件记录，
|
||||
并记录新的 spec 以供后续更新使用。
|
||||
传入不带版本的包名时，会将精确固定版本的安装移回
|
||||
registry 的默认发布线。如果已安装的 npm 插件已经与解析后的版本和记录的制品标识一致，
|
||||
OpenClaw 会跳过更新，而不会下载、重装或重写配置。
|
||||
`openclaw plugins update <id-or-npm-spec>` 适用于受跟踪的安装。传入带有 dist-tag 或精确版本的 npm 包规范时，会将该包名解析回受跟踪的插件记录，并为后续更新记录新的规范。传入不带版本的包名时，会将一个精确 pin 住的安装移回注册表的默认发布线。如果已安装的 npm 插件已经匹配解析后的版本和记录的制品标识，OpenClaw 会跳过更新，不会下载、重新安装或重写配置。
|
||||
|
||||
`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为
|
||||
marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。
|
||||
`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 源元数据，而不是 npm 规范。
|
||||
|
||||
`--dangerously-force-unsafe-install` 是一个紧急兜底覆盖选项，用于处理内置危险代码扫描器的误报。
|
||||
它允许插件安装和插件更新在遇到内置 `critical` 发现后继续进行，
|
||||
但仍然不会绕过插件 `before_install` 策略阻止或扫描失败阻止。
|
||||
`--dangerously-force-unsafe-install` 是一个“破玻璃”式覆盖选项，用于处理内置危险代码扫描器的误报。它允许插件安装和插件更新在遇到内置 `critical` 级别发现后继续进行，但仍然不会绕过插件 `before_install` 策略拦截或扫描失败拦截。
|
||||
|
||||
这个 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 Skills
|
||||
依赖安装则使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖项，而
|
||||
`openclaw skills install` 仍然是独立的 ClawHub
|
||||
技能下载/安装流程。
|
||||
这个 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的技能依赖安装则使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是独立的 ClawHub 技能下载/安装流程。
|
||||
|
||||
兼容的 Bundle 会参与相同的插件 list/inspect/enable/disable
|
||||
流程。当前运行时支持包括 Bundle Skills、Claude command-skills、
|
||||
Claude `settings.json` 默认值、Claude `.lsp.json` 以及由清单声明的
|
||||
`lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook
|
||||
目录。
|
||||
兼容的 bundle 也会参与相同的插件 list/inspect/enable/disable 流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和 manifest 声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
|
||||
|
||||
`openclaw plugins inspect <id>` 还会报告已检测到的 Bundle 能力，以及
|
||||
由 Bundle 支持的插件中受支持或不受支持的 MCP 和 LSP server 条目。
|
||||
`openclaw plugins inspect <id>` 还会报告检测到的 bundle 能力，以及由 bundle 支持的或不支持的 MCP 和 LSP server 条目。
|
||||
|
||||
Marketplace 来源可以是 Claude 已知 marketplace 名称（来自
|
||||
`~/.claude/plugins/known_marketplaces.json`）、本地 marketplace 根目录或
|
||||
`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库
|
||||
URL，或 git URL。对于远程 marketplace，插件条目必须保留在已克隆的
|
||||
marketplace 仓库内，并且只能使用相对路径来源。
|
||||
Marketplace 源可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保留在克隆的 marketplace 仓库内，并且只能使用相对路径源。
|
||||
|
||||
有关完整详情，请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。
|
||||
完整详情请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。
|
||||
|
||||
## 插件 API 概览
|
||||
|
||||
原生插件会导出一个入口对象，该对象暴露 `register(api)`。较旧的
|
||||
插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应使用
|
||||
`register`。
|
||||
原生插件会导出一个入口对象，并暴露 `register(api)`。较旧的插件可能仍使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。
|
||||
|
||||
```typescript
|
||||
export default definePluginEntry({
|
||||
@ -327,48 +306,46 @@ export default definePluginEntry({
|
||||
});
|
||||
```
|
||||
|
||||
OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api)`。
|
||||
对于旧插件，加载器仍会回退到 `activate(api)`，
|
||||
但内置插件和新的外部插件应将 `register` 视为公共契约。
|
||||
OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api)`。对于旧插件，加载器仍会回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。
|
||||
|
||||
常见的注册方法：
|
||||
|
||||
| 方法 | 注册内容 |
|
||||
| 方法 | 注册内容 |
|
||||
| --------------------------------------- | --------------------------- |
|
||||
| `registerProvider` | 模型提供商（LLM） |
|
||||
| `registerChannel` | 聊天渠道 |
|
||||
| `registerTool` | 智能体工具 |
|
||||
| `registerHook` / `on(...)` | 生命周期 hook |
|
||||
| `registerSpeechProvider` | 文本转语音 / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | 流式 STT |
|
||||
| `registerRealtimeVoiceProvider` | 双向实时语音 |
|
||||
| `registerMediaUnderstandingProvider` | 图像/音频分析 |
|
||||
| `registerImageGenerationProvider` | 图像生成 |
|
||||
| `registerMusicGenerationProvider` | 音乐生成 |
|
||||
| `registerVideoGenerationProvider` | 视频生成 |
|
||||
| `registerWebFetchProvider` | 网页抓取 / 爬取提供商 |
|
||||
| `registerWebSearchProvider` | 网页搜索 |
|
||||
| `registerHttpRoute` | HTTP 端点 |
|
||||
| `registerCommand` / `registerCli` | CLI 命令 |
|
||||
| `registerContextEngine` | 上下文引擎 |
|
||||
| `registerService` | 后台服务 |
|
||||
| `registerProvider` | 模型提供商（LLM） |
|
||||
| `registerChannel` | 聊天渠道 |
|
||||
| `registerTool` | 智能体工具 |
|
||||
| `registerHook` / `on(...)` | 生命周期 hook |
|
||||
| `registerSpeechProvider` | 文本转语音 / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | 流式 STT |
|
||||
| `registerRealtimeVoiceProvider` | 双工实时语音 |
|
||||
| `registerMediaUnderstandingProvider` | 图像/音频分析 |
|
||||
| `registerImageGenerationProvider` | 图像生成 |
|
||||
| `registerMusicGenerationProvider` | 音乐生成 |
|
||||
| `registerVideoGenerationProvider` | 视频生成 |
|
||||
| `registerWebFetchProvider` | 网页抓取 / 爬取提供商 |
|
||||
| `registerWebSearchProvider` | 网页搜索 |
|
||||
| `registerHttpRoute` | HTTP 端点 |
|
||||
| `registerCommand` / `registerCli` | CLI 命令 |
|
||||
| `registerContextEngine` | context engine |
|
||||
| `registerService` | 后台服务 |
|
||||
|
||||
类型化生命周期 hook 的 hook guard 行为：
|
||||
|
||||
- `before_tool_call`：`{ block: true }` 为终止结果；会跳过更低优先级的处理程序。
|
||||
- `before_tool_call`：`{ block: false }` 为 no-op，不会清除更早的 block。
|
||||
- `before_install`：`{ block: true }` 为终止结果；会跳过更低优先级的处理程序。
|
||||
- `before_install`：`{ block: false }` 为 no-op，不会清除更早的 block。
|
||||
- `message_sending`：`{ cancel: true }` 为终止结果；会跳过更低优先级的处理程序。
|
||||
- `message_sending`：`{ cancel: false }` 为 no-op，不会清除更早的 cancel。
|
||||
- `before_tool_call`：`{ block: true }` 是终止性的；低优先级处理器会被跳过。
|
||||
- `before_tool_call`：`{ block: false }` 是无操作，不会清除更早的拦截。
|
||||
- `before_install`：`{ block: true }` 是终止性的；低优先级处理器会被跳过。
|
||||
- `before_install`：`{ block: false }` 是无操作，不会清除更早的拦截。
|
||||
- `message_sending`：`{ cancel: true }` 是终止性的；低优先级处理器会被跳过。
|
||||
- `message_sending`：`{ cancel: false }` 是无操作，不会清除更早的取消。
|
||||
|
||||
有关完整的类型化 hook 行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
|
||||
完整的类型化 hook 行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [Building Plugins](/zh-CN/plugins/building-plugins) — 创建你自己的插件
|
||||
- [Plugin Bundles](/zh-CN/plugins/bundles) — Codex/Claude/Cursor Bundle 兼容性
|
||||
- [Plugin Manifest](/zh-CN/plugins/manifest) — 清单 schema
|
||||
- [Plugin Bundles](/zh-CN/plugins/bundles) — Codex/Claude/Cursor bundle 兼容性
|
||||
- [Plugin Manifest](/zh-CN/plugins/manifest) — manifest schema
|
||||
- [Registering Tools](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具
|
||||
- [Plugin Internals](/zh-CN/plugins/architecture) — 能力模型和加载管线
|
||||
- [Plugin Internals](/zh-CN/plugins/architecture) — 能力模型与加载流水线
|
||||
- [Community Plugins](/zh-CN/plugins/community) — 第三方列表
|
||||
|
||||
Loading…
Reference in New Issue
Block a user