diff --git a/docs/zh-CN/cli/plugins.md b/docs/zh-CN/cli/plugins.md index 9fd6d46d7..3c20b174c 100644 --- a/docs/zh-CN/cli/plugins.md +++ b/docs/zh-CN/cli/plugins.md @@ -1,15 +1,15 @@ --- read_when: - - 你想安装或管理 Gateway 网关插件或兼容的捆绑包 + - 你想安装或管理 Gateway 网关插件或兼容包 - 你想调试插件加载失败 sidebarTitle: Plugins -summary: '`openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、doctor）' +summary: '`openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、deps、doctor）' title: 插件 x-i18n: - generated_at: "2026-04-29T05:39:32Z" + generated_at: "2026-04-29T22:26:50Z" model: gpt-5.5 provider: openai - source_hash: 68d6a2734c7b4a3608467c64426f48bdf8dc1a36e33b51ba024313fc36762b5b + source_hash: c1ba79bccbbb74e3403188afc2dffc06e4215d433e2b23ed998b1fb09419601b source_path: cli/plugins.md workflow: 16 --- @@ -24,7 +24,7 @@ x-i18n: 包兼容性模型。 - 清单字段和配置 schema。 + 清单字段和配置架构。 插件安装的安全加固。 @@ -48,6 +48,10 @@ openclaw plugins disable openclaw plugins registry openclaw plugins registry --refresh openclaw plugins uninstall +openclaw plugins deps +openclaw plugins deps --repair +openclaw plugins deps --prune +openclaw plugins deps --json openclaw plugins doctor openclaw plugins update openclaw plugins update --all @@ -55,14 +59,14 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -如需调查安装、检查、卸载或刷新 registry 速度慢的问题，请带上 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 运行命令。该 trace 会将阶段耗时写入 stderr，并保持 JSON 输出可解析。参见[调试](/zh-CN/help/debugging#plugin-lifecycle-trace)。 +若要调查安装、检查、卸载或注册表刷新缓慢的问题，请在运行命令时设置 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`。跟踪会将各阶段耗时写入 stderr，并保持 JSON 输出可解析。参见 [调试](/zh-CN/help/debugging#plugin-lifecycle-trace)。 -内置插件随 OpenClaw 一起发布。其中一些默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）；其他插件需要使用 `plugins enable`。 +内置插件随 OpenClaw 一起发布。其中一些默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）；其他插件需要运行 `plugins enable`。 原生 OpenClaw 插件必须随附 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空）。兼容包则使用自己的包清单。 -`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细的 list/info 输出还会显示包子类型（`codex`、`claude` 或 `cursor`）以及检测到的包能力。 +`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细列表/info 输出还会显示包子类型（`codex`、`claude` 或 `cursor`）以及检测到的包能力。 ### 安装 @@ -81,90 +85,90 @@ openclaw plugins install --marketplace https://github.com// -裸包名会先在 ClawHub 中检查，然后再检查 npm。请像运行代码一样对待插件安装。优先使用固定版本。 +裸包名会先检查 ClawHub，再检查 npm。请像运行代码一样对待插件安装。优先使用固定版本。 -ClawHub 是大多数插件的主要分发和发现界面。Npm 仍然是受支持的后备方案和直接安装路径。在迁移到 ClawHub 期间，OpenClaw 仍会在 npm 上发布一些 OpenClaw 自有的 `@openclaw/*` 插件包；在插件发布列车之间，这些包版本可能落后于内置源码。如果 npm 报告某个 OpenClaw 自有插件包已废弃，则该已发布版本是旧的外部制品；请使用当前 OpenClaw 内置的插件或本地 checkout，直到发布更新的 npm 包。 +对于大多数插件，ClawHub 是主要的分发和发现界面。Npm 仍是受支持的回退和直接安装路径。在迁移到 ClawHub 期间，OpenClaw 仍会在 npm 上发布一些 OpenClaw 自有的 `@openclaw/*` 插件包；在插件发布列车之间，这些包版本可能落后于内置源码。如果 npm 将某个 OpenClaw 自有插件包标记为已弃用，那么该已发布版本是旧的外部构件；请使用当前 OpenClaw 内置的插件，或使用本地检出，直到发布更新的 npm 包。 - 如果你的 `plugins` 区段由单文件 `$include` 支撑，`plugins install/update/enable/disable/uninstall` 会写入该被 include 的文件，并保持 `openclaw.json` 不变。root include、include 数组以及带有同级覆盖的 include 会失败关闭，而不是被展开。支持的形状请参见[配置 include](/zh-CN/gateway/configuration)。 + 如果你的 `plugins` 部分由单文件 `$include` 支持，`plugins install/update/enable/disable/uninstall` 会写入该被包含的文件，并保持 `openclaw.json` 不变。根 include、include 数组以及带有同级覆盖项的 include 会失败关闭，而不会被扁平化。支持的形状见[配置 include](/zh-CN/gateway/configuration)。 - 如果安装期间配置无效，`plugins install` 通常会失败关闭，并提示你先运行 `openclaw doctor --fix`。在 Gateway 网关启动期间，某个插件的无效配置会被隔离到该插件，因此其他渠道和插件可以继续运行；`openclaw doctor --fix` 可以隔离该无效插件条目。唯一有文档说明的安装时例外，是一个面向显式选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件的狭窄内置插件恢复路径。 + 如果安装期间配置无效，`plugins install` 通常会失败关闭，并提示你先运行 `openclaw doctor --fix`。Gateway 网关启动期间，某个插件的无效配置会隔离到该插件，以便其他渠道和插件继续运行；`openclaw doctor --fix` 可以隔离该无效插件条目。唯一有文档说明的安装时例外，是一条狭窄的内置插件恢复路径，适用于显式选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。 - - `--force` 会复用现有安装目标，并就地覆盖已安装的插件或钩子包。当你有意从新的本地路径、归档、ClawHub 包或 npm 制品重新安装同一 id 时使用它。对于已被跟踪的 npm 插件的常规升级，请优先使用 `openclaw plugins update `。 + + `--force` 会复用现有安装目标，并就地覆盖已安装的插件或钩子包。当你有意从新的本地路径、归档、ClawHub 包或 npm 构件重新安装同一个 id 时使用它。对于已跟踪 npm 插件的常规升级，请优先使用 `openclaw plugins update `。 - 如果你对已经安装的插件 id 运行 `plugins install`，OpenClaw 会停止，并在正常升级时指向 `plugins update `，或者在你确实想从其他来源覆盖当前安装时指向 `plugins install --force`。 + 如果你对已安装的插件 id 运行 `plugins install`，OpenClaw 会停止，并提示你使用 `plugins update ` 进行常规升级，或在确实想从不同来源覆盖当前安装时使用 `plugins install --force`。 - - `--pin` 仅适用于 npm 安装。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 源元数据，而不是 npm spec。 + + `--pin` 仅适用于 npm 安装。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。 - `--dangerously-force-unsafe-install` 是用于内置危险代码扫描器误报的应急选项。即使内置扫描器报告 `critical` 发现，它也允许安装继续，但它**不会**绕过插件 `before_install` 钩子策略阻断，也**不会**绕过扫描失败。 + `--dangerously-force-unsafe-install` 是一个应急选项，用于处理内置危险代码扫描器的误报。即使内置扫描器报告 `critical` 发现项，它也允许继续安装，但它**不会**绕过插件 `before_install` 钩子策略阻止，也**不会**绕过扫描失败。 - 此 CLI 标志适用于插件安装/更新流程。由 Gateway 网关支撑的 skill 依赖安装使用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍是单独的 ClawHub skill 下载/安装流程。 + 此 CLI 标志适用于插件安装/更新流程。由 Gateway 网关支持的 skill 依赖安装使用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍是独立的 ClawHub skill 下载/安装流程。 - 如果你在 ClawHub 上发布的插件被 registry 扫描阻止，请使用 [ClawHub](/zh-CN/tools/clawhub) 中的发布者步骤。 + 如果你发布到 ClawHub 的插件被注册表扫描阻止，请使用 [ClawHub](/zh-CN/tools/clawhub) 中的发布者步骤。 - `plugins install` 也是安装钩子包的界面，这些钩子包会在 `package.json` 中暴露 `openclaw.hooks`。使用 `openclaw hooks` 查看经过筛选的钩子可见性和按钩子启用，不要用它安装包。 + `plugins install` 也是安装钩子包的入口，这类包会在 `package.json` 中暴露 `openclaw.hooks`。请使用 `openclaw hooks` 查看过滤后的钩子可见性并启用单个钩子，而不是用于包安装。 - Npm spec **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。为确保安全，即使你的 shell 有全局 npm 安装设置，依赖安装也会在项目本地以 `--ignore-scripts` 运行。 + Npm spec 是**仅注册表**的（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。为了安全，即使你的 shell 中有全局 npm 安装设置，依赖安装也会在项目本地以 `--ignore-scripts` 运行。 - 当你想跳过 ClawHub 查找并直接从 npm 安装时，请使用 `npm:`。裸包 spec 仍会优先使用 ClawHub，并且仅在 ClawHub 没有该包或版本时回退到 npm。 + 当你想跳过 ClawHub 查找并直接从 npm 安装时，请使用 `npm:`。裸包 spec 仍会优先使用 ClawHub，只有当 ClawHub 没有该包或版本时才回退到 npm。 - 裸 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 包，请使用显式 scoped spec（例如 `@scope/diffs`）。 + 如果裸安装 spec 匹配内置插件 id（例如 `diffs`），OpenClaw 会直接安装内置插件。若要安装同名 npm 包，请使用显式作用域 spec（例如 `@scope/diffs`）。 - 支持的归档：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw 插件归档必须在解压后的插件根目录包含有效的 `openclaw.plugin.json`；仅包含 `package.json` 的归档会在 OpenClaw 写入安装记录之前被拒绝。 + 支持的归档：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw 插件归档必须在解压后的插件根目录包含有效的 `openclaw.plugin.json`；仅包含 `package.json` 的归档会在 OpenClaw 写入安装记录前被拒绝。 也支持 Claude marketplace 安装。 -ClawHub 安装使用显式 `clawhub:` 定位器： +ClawHub 安装使用显式的 `clawhub:` 定位符： ```bash openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -OpenClaw 现在也会对裸 npm 安全插件 spec 优先使用 ClawHub。仅当 ClawHub 没有该包或版本时才会回退到 npm： +OpenClaw 现在也会对裸 npm 安全插件 spec 优先使用 ClawHub。只有当 ClawHub 没有该包或版本时，它才会回退到 npm： ```bash openclaw plugins install openclaw-codex-app-server ``` -使用 `npm:` 强制仅通过 npm 解析，例如当 ClawHub 无法访问，或你知道该包只存在于 npm 上时： +使用 `npm:` 强制仅 npm 解析，例如当 ClawHub 无法访问，或你知道该包只存在于 npm 上时： ```bash openclaw plugins install npm:openclaw-codex-app-server openclaw plugins install npm:@scope/plugin-name@1.0.1 ``` -OpenClaw 会从 ClawHub 下载包归档，检查声明的插件 API / 最低 gateway 兼容性，然后通过常规归档路径安装。记录的安装会保留其 ClawHub 源元数据，以便后续更新。 -未指定版本的 ClawHub 安装会保留未指定版本的记录 spec，因此 `openclaw plugins update` 可以跟随更新的 ClawHub 发布；显式版本或标签选择器（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）仍会固定到该选择器。 +OpenClaw 会从 ClawHub 下载包归档，检查声明的插件 API / 最低 Gateway 网关兼容性，然后通过正常归档路径安装它。记录的安装会保留其 ClawHub 来源元数据，以便后续更新。 +未带版本的 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 名称存在于 Claude 的本地注册表缓存 `~/.claude/plugins/known_marketplaces.json` 中时，请使用 `plugin@marketplace` 简写： ```bash openclaw plugins marketplace list openclaw plugins install @ ``` -当你想显式传入 marketplace 源时，使用 `--marketplace`： +当你想显式传入 marketplace 来源时，请使用 `--marketplace`： ```bash openclaw plugins install --marketplace @@ -174,16 +178,16 @@ openclaw plugins install --marketplace ./my-marketplace ``` - + - 来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称 - 本地 marketplace 根目录或 `marketplace.json` 路径 - - GitHub repo 简写，例如 `owner/repo` - - GitHub repo URL，例如 `https://github.com/owner/repo` + - GitHub 仓库简写，例如 `owner/repo` + - GitHub 仓库 URL，例如 `https://github.com/owner/repo` - git URL - 对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保持在克隆的 marketplace repo 内部。OpenClaw 接受来自该 repo 的相对路径源，并拒绝远程清单中的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径插件源。 + 对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保持在克隆的 marketplace 仓库内。OpenClaw 接受来自该仓库的相对路径来源，并拒绝远程清单中的 HTTP(S)、绝对路径、git、GitHub 和其他非路径插件来源。 @@ -195,10 +199,10 @@ openclaw plugins install --marketplace ./my-marketplace - Cursor 兼容包（`.cursor-plugin/plugin.json`） -兼容包会安装到常规插件根目录，并参与相同的 list/info/enable/disable 流程。目前支持包 skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor command-skills 以及兼容的 Codex 钩子目录；其他检测到的包能力会显示在诊断/info 中，但尚未接入运行时执行。 +兼容包会安装到正常插件根目录，并参与同一套 list/info/enable/disable 流程。目前支持包 Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex 钩子目录；其他检测到的包能力会显示在诊断/info 中，但尚未接入运行时执行。 -### 列出 +### 列表 ```bash openclaw plugins list @@ -211,29 +215,25 @@ openclaw plugins list --json 仅显示已启用的插件。 - 从表格视图切换到每个插件的详细行，包含 source/origin/version/activation 元数据。 + 从表格视图切换为逐插件详情行，包含来源/源头/版本/激活元数据。 - 机器可读的清单以及 registry 诊断。 + 机器可读清单以及注册表诊断。 -`plugins list` 会先读取持久化的本地插件注册表；当注册表缺失或无效时，会使用仅由清单派生的回退。它适合用于检查插件是否已安装、已启用，并且对冷启动规划可见，但它不是对已运行 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、钩子策略或 `plugins.load.paths` 后，需要重启为该渠道提供服务的 Gateway 网关，才能期待新的 `register(api)` 代码或钩子运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不仅仅是包装器进程。 +`plugins list` 会先读取持久化的本地插件注册表；当注册表缺失或无效时，会使用仅基于 manifest 派生的回退。它适合用于检查某个插件是否已安装、已启用，并且对冷启动规划可见，但它不是对已运行 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、钩子策略或 `plugins.load.paths` 后，请先重启服务于该渠道的 Gateway 网关，再期待新的 `register(api)` 代码或钩子运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不仅是包装进程。 -对于打包 Docker 镜像内的内置插件工作，请将插件 -源目录绑定挂载到匹配的打包源路径上，例如 -`/app/extensions/synology-chat`。OpenClaw 会先发现该挂载的源码 -覆盖层，然后才是 `/app/dist/extensions/synology-chat`；普通复制的源码 -目录仍然不会生效，因此常规打包安装仍会使用编译后的 dist。 +对于打包 Docker 镜像中的内置插件工作，请将插件源目录绑定挂载到匹配的打包源路径上，例如 `/app/extensions/synology-chat`。OpenClaw 会先发现这个挂载的源覆盖层，然后才是 `/app/dist/extensions/synology-chat`；普通复制的源目录仍然不会生效，因此正常的打包安装仍会使用已编译的 dist。 对于运行时钩子调试： -- `openclaw plugins inspect --json` 会显示来自模块加载检查过程的已注册钩子和诊断信息。 +- `openclaw plugins inspect --json` 会显示已注册的钩子，以及来自一次模块加载检查过程的诊断信息。 - `openclaw gateway status --deep --require-rpc` 会确认可访问的 Gateway 网关、服务/进程提示、配置路径和 RPC 健康状态。 - 非内置对话钩子（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）需要 `plugins.entries..hooks.allowConversationAccess=true`。 -使用 `--link` 避免复制本地目录（会添加到 `plugins.load.paths`）： +使用 `--link` 可避免复制本地目录（会添加到 `plugins.load.paths`）： ```bash openclaw plugins install -l ./my-plugin @@ -242,14 +242,27 @@ openclaw plugins install -l ./my-plugin `--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是覆盖托管安装目标。 -在 npm 安装时使用 `--pin`，可将解析出的精确规范（`name@version`）保存到托管插件索引中，同时保持默认行为为不固定版本。 +在 npm 安装中使用 `--pin`，可将解析得到的精确 spec（`name@version`）保存到托管插件索引中，同时保持默认行为不固定版本。 ### 插件索引 -插件安装元数据是机器管理的状态，不是用户配置。安装和更新会把它写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。其顶层 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件清单的记录。`plugins` 数组是由清单派生的冷注册表缓存。该文件包含不要编辑的警告，并会被 `openclaw plugins update`、卸载、诊断和冷插件注册表使用。 +插件安装元数据是机器管理状态，而不是用户配置。安装和更新会将其写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。其顶层 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件 manifest 的记录。`plugins` 数组是由 manifest 派生的冷注册表缓存。该文件包含不要编辑的警告，并由 `openclaw plugins update`、卸载、诊断和冷插件注册表使用。 -当 OpenClaw 在配置中看到已发布的旧版 `plugins.installs` 记录时，会将它们移动到插件索引并移除该配置键；如果任一写入失败，则保留配置记录，避免安装元数据丢失。 +当 OpenClaw 在配置中看到已发布的旧版 `plugins.installs` 记录时，会将它们移动到插件索引并移除该配置键；如果任一写入失败，会保留配置记录，避免安装元数据丢失。 + +### 运行时依赖 + +```bash +openclaw plugins deps +openclaw plugins deps --repair +openclaw plugins deps --prune +openclaw plugins deps --json +``` + +`plugins deps` 会检查 OpenClaw 拥有的内置插件的打包运行时依赖阶段。它不是第三方 npm 或 ClawHub 插件的安装/更新路径。 + +当打包安装在 Gateway 网关启动或 `plugins doctor` 期间报告缺少内置运行时依赖时，请使用 `--repair`。修复只会安装缺失的已启用内置插件依赖，并禁用生命周期脚本。使用 `--prune` 可移除旧打包布局遗留下来的陈旧未知外部运行时依赖根目录。 ### 卸载 @@ -259,7 +272,7 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` 会从 `plugins.entries`、持久化插件索引、插件允许/拒绝列表条目，以及适用时的已链接 `plugins.load.paths` 条目中移除插件记录。除非设置了 `--keep-files`，卸载还会移除跟踪的托管安装目录，前提是该目录位于 OpenClaw 的插件 extensions 根目录内。对于活动的记忆插件，记忆槽会重置为 `memory-core`。 +`uninstall` 会从 `plugins.entries`、持久化插件索引、插件允许/拒绝列表条目，以及适用时的已链接 `plugins.load.paths` 条目中移除插件记录。除非设置了 `--keep-files`，否则卸载还会移除被跟踪的托管安装目录，前提是它位于 OpenClaw 的插件扩展根目录内。对于主动记忆插件，记忆槽会重置为 `memory-core`。 `--keep-config` 作为 `--keep-files` 的已弃用别名受支持。 @@ -275,25 +288,25 @@ openclaw plugins update @openclaw/voice-call@beta openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -更新适用于托管插件索引中跟踪的插件安装，以及 `hooks.internal.installs` 中跟踪的 hook-pack 安装。 +更新适用于托管插件索引中被跟踪的插件安装，以及 `hooks.internal.installs` 中被跟踪的 hook-pack 安装。 - - 当你传入插件 id 时，OpenClaw 会复用该插件已记录的安装规范。这意味着先前存储的 dist-tag（例如 `@beta`）和精确固定版本会在后续 `update ` 运行中继续使用。 + + 当你传入插件 id 时，OpenClaw 会复用该插件记录的安装 spec。这意味着此前存储的 dist-tag（例如 `@beta`）和精确固定版本会在之后的 `update ` 运行中继续使用。 - 对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包规范。OpenClaw 会将该包名解析回跟踪的插件记录，更新该已安装插件，并记录新的 npm 规范以供未来基于 id 的更新使用。 + 对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会将该包名解析回被跟踪的插件记录，更新该已安装插件，并记录新的 npm spec 以供将来基于 id 的更新使用。 - 传入不带版本或标签的 npm 包名也会解析回跟踪的插件记录。当插件被固定到精确版本，而你希望将它移回注册表的默认发布线时，请使用这种方式。 + 传入不带版本或标签的 npm 包名也会解析回被跟踪的插件记录。当插件已固定到精确版本，而你想将其移回注册表的默认发布线时，请使用这种方式。 - - 在实时 npm 更新前，OpenClaw 会根据 npm 注册表元数据检查已安装包版本。如果已安装版本和已记录的工件身份已经与解析出的目标匹配，则会跳过更新，不下载、不重新安装，也不重写 `openclaw.json`。 + + 在实时 npm 更新之前，OpenClaw 会根据 npm 注册表元数据检查已安装包版本。如果已安装版本和记录的 artifact 身份已经与解析目标匹配，则会跳过更新，不下载、不重新安装，也不重写 `openclaw.json`。 - 当存在已存储的完整性哈希且获取的工件哈希发生变化时，OpenClaw 会将其视为 npm 工件漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新辅助程序默认失败关闭，除非调用方提供显式继续策略。 + 当存在已存储的 integrity 哈希且获取到的 artifact 哈希发生变化时，OpenClaw 会将其视为 npm artifact 漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新辅助工具会默认失败关闭，除非调用方提供显式继续策略。 - - `--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的紧急覆盖。它仍然不会绕过插件 `before_install` 策略阻断或扫描失败阻断，并且只适用于插件更新，不适用于 hook-pack 更新。 + + `--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的破窗覆盖。它仍然不会绕过插件 `before_install` 策略阻断或扫描失败阻断，并且只适用于插件更新，不适用于 hook-pack 更新。 @@ -304,7 +317,7 @@ openclaw plugins inspect openclaw plugins inspect --json ``` -对单个插件进行深度自省。显示身份、加载状态、来源、已注册能力、钩子、工具、命令、服务、Gateway 网关方法、HTTP 路由、策略标志、诊断信息、安装元数据、包能力，以及任何检测到的 MCP 或 LSP 服务器支持。 +对单个插件进行深度自省。显示身份、加载状态、来源、已注册能力、钩子、工具、命令、服务、Gateway 网关方法、HTTP 路由、策略标志、诊断、安装元数据、bundle 能力，以及任何检测到的 MCP 或 LSP 服务器支持。 每个插件会按其在运行时实际注册的内容分类： @@ -313,10 +326,10 @@ openclaw plugins inspect --json - **hook-only** — 只有钩子，没有能力或表面 - **non-capability** — 有工具/命令/服务，但没有能力 -有关能力模型的更多信息，请参阅 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。 +有关能力模型的更多内容，请参阅 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。 -`--json` 标志会输出适合脚本和审计使用的机器可读报告。`inspect --all` 会渲染覆盖整个插件群的表格，包含形态、能力种类、兼容性通知、包能力和钩子摘要列。`info` 是 `inspect` 的别名。 +`--json` 标志会输出适合脚本和审计使用的机器可读报告。`inspect --all` 会渲染全局表格，其中包含形态、能力类别、兼容性通知、bundle 能力和钩子摘要列。`info` 是 `inspect` 的别名。 ### Doctor @@ -325,7 +338,7 @@ openclaw plugins inspect --json openclaw plugins doctor ``` -`doctor` 会报告插件加载错误、清单/发现诊断信息和兼容性通知。当一切正常时，它会打印 `No plugin issues detected.` +`doctor` 会报告插件加载错误、manifest/设备发现诊断和兼容性通知。当一切正常时，它会打印 `No plugin issues detected.` 对于缺少 `register`/`activate` 导出等模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以便在诊断输出中包含紧凑的导出形态摘要。 @@ -337,12 +350,12 @@ openclaw plugins registry --refresh openclaw plugins registry --json ``` -本地插件注册表是 OpenClaw 持久化的冷读取模型，用于已安装插件身份、启用状态、来源元数据和贡献所有权。常规启动、提供商所有者查找、渠道设置分类和插件清单可以在不导入插件运行时模块的情况下读取它。 +本地插件注册表是 OpenClaw 针对已安装插件身份、启用状态、来源元数据和贡献归属持久化的冷读取模型。正常启动、提供商所有者查找、渠道设置分类和插件清单都可以读取它，而无需导入插件运行时模块。 -使用 `plugins registry` 检查持久化注册表是否存在、当前有效或已过期。使用 `--refresh` 可从持久化插件索引、配置策略和清单/包元数据重建它。这是修复路径，不是运行时激活路径。 +使用 `plugins registry` 检查持久化注册表是否存在、是否最新或是否陈旧。使用 `--refresh` 可基于持久化插件索引、配置策略和 manifest/package 元数据重建它。这是修复路径，不是运行时激活路径。 -`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是已弃用的注册表读取失败紧急兼容开关。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；该环境变量回退仅用于迁移推出期间的紧急启动恢复。 +`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是一个已弃用的破窗兼容性开关，用于注册表读取失败。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；该环境变量回退仅用于迁移推出期间的紧急启动恢复。 ### 市场 @@ -352,9 +365,9 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -市场列表接受本地市场路径、`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL 或 git URL。`--json` 会打印解析出的来源标签，以及解析后的市场清单和插件条目。 +市场列表接受本地市场路径、`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL 或 git URL。`--json` 会打印解析后的来源标签，以及解析后的市场 manifest 和插件条目。 -## 相关 +## 相关内容 - [构建插件](/zh-CN/plugins/building-plugins) - [CLI 参考](/zh-CN/cli) diff --git a/docs/zh-CN/plugins/bundles.md b/docs/zh-CN/plugins/bundles.md index 7aeaef5ea..99e5a4535 100644 --- a/docs/zh-CN/plugins/bundles.md +++ b/docs/zh-CN/plugins/bundles.md @@ -1,41 +1,45 @@ --- read_when: - - 你想安装一个与 Codex、Claude 或 Cursor 兼容的套件 - - 你需要了解 OpenClaw 如何将套件内容映射到原生功能 - - 你正在调试套件检测或缺失的功能 -summary: 将 Codex、Claude 和 Cursor 套件作为 OpenClaw 插件进行安装和使用 -title: 插件套件 + - 你想安装一个与 Codex、Claude 或 Cursor 兼容的捆绑包 + - 你需要了解 OpenClaw 如何将包内容映射到原生功能 + - 你正在调试 bundle 检测或缺失的能力 +summary: 将 Codex、Claude 和 Cursor 捆绑包作为 OpenClaw 插件安装并使用 +title: 插件包 x-i18n: - generated_at: "2026-04-27T12:54:19Z" - model: gpt-5.4 + generated_at: "2026-04-29T22:26:51Z" + model: gpt-5.5 provider: openai - source_hash: 7d8dcd6eae5e740c27429454a7396332f1bd3b16c0a4e939321d047b5e2e4ff7 + source_hash: 6d03643c3029f5c6c81fab3aa1c00accba94da64a834e381b29db8f405d6bdee source_path: plugins/bundles.md - workflow: 15 + workflow: 16 --- -OpenClaw 可以从三个外部生态安装插件：**Codex**、**Claude** 和 **Cursor**。这些被称为**套件**——内容和元数据包，OpenClaw 会将其映射为原生功能，例如 Skills、钩子和 MCP 工具。 +OpenClaw 可以从三个外部生态系统安装插件：**Codex**、**Claude** +和 **Cursor**。这些称为 **bundles**，即内容和元数据包，OpenClaw 会将其映射为 Skills、钩子和 MCP 工具等原生功能。 - 套件**不**等同于原生 OpenClaw 插件。原生插件在进程内运行，并且可以注册任意能力。套件是内容包，只进行选择性的功能映射，并且信任边界更窄。 + bundles **不同于**原生 OpenClaw 插件。原生插件在进程内运行， + 并且可以注册任何能力。bundles 是内容包，带有选择性的功能映射和更窄的信任边界。 -## 为什么有套件 +## 为什么存在 bundles -许多有用的插件是以 Codex、Claude 或 Cursor 格式发布的。OpenClaw 不要求作者将它们重写为原生 OpenClaw 插件，而是检测这些格式并将其支持的内容映射到原生功能集中。这意味着你可以安装一个 Claude 命令包或 Codex Skills 套件，并立即使用它。 +许多有用的插件以 Codex、Claude 或 Cursor 格式发布。OpenClaw +不会要求作者将它们重写为原生 OpenClaw 插件，而是检测这些格式，并将其受支持的内容映射到原生功能集。这意味着你可以安装 Claude 命令包或 Codex skill bundle +并立即使用。 -## 安装一个套件 +## 安装 bundle - + ```bash - # 本地目录 + # Local directory openclaw plugins install ./my-bundle - # 归档文件 + # Archive openclaw plugins install ./my-bundle.tgz - # Claude 市场 + # Claude marketplace openclaw plugins marketplace list openclaw plugins install @ ``` @@ -48,7 +52,7 @@ OpenClaw 可以从三个外部生态安装插件：**Codex**、**Claude** 和 ** openclaw plugins inspect ``` - 套件会显示为 `Format: bundle`，其子类型为 `codex`、`claude` 或 `cursor`。 + bundles 会显示为 `Format: bundle`，其子类型为 `codex`、`claude` 或 `cursor`。 @@ -57,54 +61,57 @@ OpenClaw 可以从三个外部生态安装插件：**Codex**、**Claude** 和 ** openclaw gateway restart ``` - 已映射的功能（Skills、钩子、MCP 工具、LSP 默认值）会在下一个会话中可用。 + 映射后的功能（Skills、钩子、MCP 工具、LSP 默认值）将在下一个会话中可用。 -## OpenClaw 从套件中映射什么 +## OpenClaw 从 bundles 映射什么 -目前并不是每项套件功能都能在 OpenClaw 中运行。以下是当前可用的功能，以及已检测但尚未接入的功能。 +并非每个 bundle 功能目前都能在 OpenClaw 中运行。下面列出可用的功能，以及已检测但尚未接线的功能。 -### 当前支持 +### 目前支持 -| 功能 | 映射方式 | 适用范围 | +| 功能 | 映射方式 | 适用对象 | | ------------- | ------------------------------------------------------------------------------------------- | -------------- | -| Skills 内容 | 套件 Skills 根目录会作为普通 OpenClaw Skills 加载 | 所有格式 | -| 命令 | `commands/` 和 `.cursor/commands/` 会被视为 Skills 根目录 | Claude、Cursor | -| 钩子包 | OpenClaw 风格的 `HOOK.md` + `handler.ts` 布局 | Codex | -| MCP 工具 | 套件 MCP 配置会合并到嵌入式 Pi 设置中；支持的 stdio 和 HTTP 服务器会被加载 | 所有格式 | -| LSP 服务器 | Claude `.lsp.json` 和 manifest 声明的 `lspServers` 会合并到嵌入式 Pi LSP 默认值中 | Claude | -| 设置 | Claude `settings.json` 会作为嵌入式 Pi 默认值导入 | Claude | +| Skill 内容 | Bundle skill 根目录会作为普通 OpenClaw Skills 加载 | 所有格式 | +| 命令 | `commands/` 和 `.cursor/commands/` 会作为 skill 根目录处理 | Claude、Cursor | +| 钩子包 | OpenClaw 风格的 `HOOK.md` + `handler.ts` 布局 | Codex | +| MCP 工具 | Bundle MCP 配置会合并到嵌入式 Pi 设置中；加载受支持的 stdio 和 HTTP 服务器 | 所有格式 | +| LSP 服务器 | Claude `.lsp.json` 和清单声明的 `lspServers` 会合并到嵌入式 Pi LSP 默认值中 | Claude | +| 设置 | Claude `settings.json` 会作为嵌入式 Pi 默认值导入 | Claude | -#### Skills 内容 +#### Skill 内容 -- 套件 Skills 根目录会作为普通 OpenClaw Skills 根目录加载 -- Claude `commands` 根目录会被视为额外的 Skills 根目录 -- Cursor `.cursor/commands` 根目录会被视为额外的 Skills 根目录 +- bundle skill 根目录会作为普通 OpenClaw skill 根目录加载 +- Claude `commands` 根目录会作为额外的 skill 根目录处理 +- Cursor `.cursor/commands` 根目录会作为额外的 skill 根目录处理 -这意味着 Claude Markdown 命令文件可以通过正常的 OpenClaw Skills 加载器工作。Cursor 命令 Markdown 也通过同一路径工作。 +这意味着 Claude markdown 命令文件会通过普通 OpenClaw skill +加载器工作。Cursor 命令 markdown 也会通过同一路径工作。 #### 钩子包 -- 只有当套件钩子根目录使用普通 OpenClaw 钩子包布局时，才会生效。当前这主要是 Codex 兼容场景： +- bundle 钩子根目录**仅在**使用普通 OpenClaw 钩子包布局时可用。 + 目前这主要是 Codex 兼容场景： - `HOOK.md` - `handler.ts` 或 `handler.js` -#### 用于 Pi 的 MCP +#### Pi 的 MCP -- 已启用的套件可以提供 MCP 服务器配置 -- OpenClaw 会将套件 MCP 配置合并到生效的嵌入式 Pi 设置中，作为 `mcpServers` -- OpenClaw 会在嵌入式 Pi 智能体轮次期间，通过启动 stdio 服务器或连接到 HTTP 服务器，公开受支持的套件 MCP 工具 -- `coding` 和 `messaging` 工具配置默认包含套件 MCP 工具；使用 `tools.deny: ["bundle-mcp"]` 可为某个智能体或 Gateway 网关选择退出 -- 项目本地 Pi 设置仍会在套件默认值之后应用，因此工作区设置可在需要时覆盖套件 MCP 条目 -- 套件 MCP 工具目录会在注册前进行确定性排序，因此上游 `listTools()` 顺序变化不会导致 prompt-cache 工具块抖动 +- 已启用的 bundles 可以贡献 MCP 服务器配置 +- OpenClaw 会将 bundle MCP 配置合并到有效的嵌入式 Pi 设置中， + 作为 `mcpServers` +- OpenClaw 会在嵌入式 Pi 智能体轮次期间，通过启动 stdio 服务器或连接到 HTTP 服务器，暴露受支持的 bundle MCP 工具 +- `coding` 和 `messaging` 工具配置文件默认包含 bundle MCP 工具；使用 `tools.deny: ["bundle-mcp"]` 可为智能体或 Gateway 网关退出使用 +- 项目本地 Pi 设置仍会在 bundle 默认值之后应用，因此工作区设置可以在需要时覆盖 bundle MCP 条目 +- bundle MCP 工具目录会在注册前按确定性顺序排序，因此上游 `listTools()` 顺序变化不会扰动提示缓存工具块 ##### 传输协议 MCP 服务器可以使用 stdio 或 HTTP 传输协议： -**Stdio** 会启动子进程： +**Stdio** 会启动一个子进程： ```json { @@ -120,7 +127,7 @@ MCP 服务器可以使用 stdio 或 HTTP 传输协议： } ``` -**HTTP** 默认通过 `sse` 连接到正在运行的 MCP 服务器；在请求时也可使用 `streamable-http`： +**HTTP** 默认通过 `sse` 连接到运行中的 MCP 服务器，或在请求时使用 `streamable-http`： ```json { @@ -140,86 +147,86 @@ MCP 服务器可以使用 stdio 或 HTTP 传输协议： ``` - `transport` 可以设置为 `"streamable-http"` 或 `"sse"`；省略时，OpenClaw 使用 `sse` -- `type: "http"` 是下游 CLI 原生格式；在 OpenClaw 配置中应使用 `transport: "streamable-http"`。`openclaw mcp set` 和 `openclaw doctor --fix` 会规范化这个常见别名。 +- `type: "http"` 是 CLI 原生的下游形状；在 OpenClaw 配置中使用 `transport: "streamable-http"`。`openclaw mcp set` 和 `openclaw doctor --fix` 会规范化这个常见别名。 - 仅允许 `http:` 和 `https:` URL scheme - `headers` 值支持 `${ENV_VAR}` 插值 - 同时包含 `command` 和 `url` 的服务器条目会被拒绝 -- URL 凭证（userinfo 和查询参数）会从工具说明和日志中脱敏 +- URL 凭证（userinfo 和查询参数）会从工具描述和日志中遮蔽 - `connectionTimeoutMs` 会覆盖 stdio 和 HTTP 传输协议默认的 30 秒连接超时 ##### 工具命名 -OpenClaw 会使用 provider 安全名称为套件 MCP 工具注册，格式为 `serverName__toolName`。例如，键为 `"vigil-harbor"` 且暴露 `memory_search` 工具的服务器，会被注册为 `vigil-harbor__memory_search`。 +OpenClaw 会以 `serverName__toolName` 形式，为 bundle MCP 工具注册提供商安全名称。例如，键名为 `"vigil-harbor"` 的服务器暴露 `memory_search` 工具时，会注册为 `vigil-harbor__memory_search`。 -- `A-Za-z0-9_-` 之外的字符会被替换为 `-` -- 服务器前缀最长为 30 个字符 -- 完整工具名最长为 64 个字符 +- `A-Za-z0-9_-` 以外的字符会替换为 `-` +- 服务器前缀最多 30 个字符 +- 完整工具名称最多 64 个字符 - 空服务器名称会回退为 `mcp` -- 发生清洗后名称冲突时，会使用数字后缀消歧 -- 最终暴露的工具顺序按安全名称确定排序，以保持重复 Pi 轮次的缓存稳定 -- 配置过滤会将来自同一个套件 MCP 服务器的所有工具视为由 `bundle-mcp` 插件拥有，因此配置允许列表和拒绝列表可以包含单个暴露工具名称，也可以包含 `bundle-mcp` 插件键 +- 发生冲突的清理后名称会用数字后缀消歧 +- 最终暴露的工具顺序会按安全名称确定性排序，以保持重复 Pi 轮次的缓存稳定 +- 配置文件过滤会将来自同一个 bundle MCP 服务器的所有工具视为由 `bundle-mcp` 拥有的插件工具，因此配置文件允许列表和拒绝列表可以包含单个已暴露工具名称，也可以包含 `bundle-mcp` 插件键 #### 嵌入式 Pi 设置 -- 当套件启用时，Claude `settings.json` 会作为默认嵌入式 Pi 设置导入 -- OpenClaw 会在应用前清洗 shell 覆盖键 +- Claude `settings.json` 会在 bundle 启用时作为默认嵌入式 Pi 设置导入 +- OpenClaw 会在应用 shell 覆盖键之前对其进行清理 -已清洗的键： +清理后的键： - `shellPath` - `shellCommandPrefix` #### 嵌入式 Pi LSP -- 已启用的 Claude 套件可以提供 LSP 服务器配置 -- OpenClaw 会加载 `.lsp.json` 以及 manifest 中声明的任意 `lspServers` 路径 -- 套件 LSP 配置会合并到生效的嵌入式 Pi LSP 默认值中 -- 当前仅支持运行基于 stdio 的 LSP 服务器；不支持的传输协议仍会显示在 `openclaw plugins inspect ` 中 +- 已启用的 Claude bundles 可以贡献 LSP 服务器配置 +- OpenClaw 会加载 `.lsp.json` 以及任何清单声明的 `lspServers` 路径 +- bundle LSP 配置会合并到有效的嵌入式 Pi LSP 默认值中 +- 目前只有受支持的 stdio 后端 LSP 服务器可以运行；不受支持的传输协议仍会显示在 `openclaw plugins inspect ` 中 -### 已检测但不执行 +### 已检测但未执行 这些内容会被识别并显示在诊断中，但 OpenClaw 不会运行它们： - Claude `agents`、`hooks.json` 自动化、`outputStyles` - Cursor `.cursor/agents`、`.cursor/hooks.json`、`.cursor/rules` -- Codex 内联/应用元数据中超出能力报告范围的内容 +- Codex 内联/app 元数据，能力报告以外的部分 -## 套件格式 +## Bundle 格式 - + 标记：`.codex-plugin/plugin.json` 可选内容：`skills/`、`hooks/`、`.mcp.json`、`.app.json` - 当 Codex 套件使用 Skills 根目录和 OpenClaw 风格钩子包目录（`HOOK.md` + `handler.ts`）时，最适合 OpenClaw。 + 当 Codex bundles 使用 skill 根目录和 OpenClaw 风格钩子包目录（`HOOK.md` + `handler.ts`）时，最适合 OpenClaw。 - + 两种检测模式： - - **基于 Manifest：** `.claude-plugin/plugin.json` - - **无 Manifest：** 默认 Claude 布局（`skills/`、`commands/`、`agents/`、`hooks/`、`.mcp.json`、`.lsp.json`、`settings.json`） + - **基于清单：** `.claude-plugin/plugin.json` + - **无清单：** 默认 Claude 布局（`skills/`、`commands/`、`agents/`、`hooks/`、`.mcp.json`、`.lsp.json`、`settings.json`） - Claude 特有行为： + Claude 特定行为： - - `commands/` 会被视为 Skills 内容 - - `settings.json` 会导入到嵌入式 Pi 设置中（shell 覆盖键会被清洗） + - `commands/` 会作为 skill 内容处理 + - `settings.json` 会导入到嵌入式 Pi 设置中（shell 覆盖键会被清理） - `.mcp.json` 会向嵌入式 Pi 暴露受支持的 stdio 工具 - - `.lsp.json` 加上 manifest 声明的 `lspServers` 路径会加载到嵌入式 Pi LSP 默认值中 - - `hooks/hooks.json` 会被检测，但不会执行 - - manifest 中的自定义组件路径是增量添加的（扩展默认值，而不是替换默认值） + - `.lsp.json` 加上清单声明的 `lspServers` 路径会加载到嵌入式 Pi LSP 默认值中 + - `hooks/hooks.json` 会被检测但不会执行 + - 清单中的自定义组件路径是追加式的（它们会扩展默认值，而不是替换默认值） - + 标记：`.cursor-plugin/plugin.json` 可选内容：`skills/`、`.cursor/commands/`、`.cursor/agents/`、`.cursor/rules/`、`.cursor/hooks.json`、`.mcp.json` - - `.cursor/commands/` 会被视为 Skills 内容 - - `.cursor/rules/`、`.cursor/agents/` 和 `.cursor/hooks.json` 仅检测，不执行 + - `.cursor/commands/` 会作为 skill 内容处理 + - `.cursor/rules/`、`.cursor/agents/` 和 `.cursor/hooks.json` 仅会被检测 @@ -228,48 +235,50 @@ OpenClaw 会使用 provider 安全名称为套件 MCP 工具注册，格式为 ` OpenClaw 会先检查原生插件格式： -1. `openclaw.plugin.json` 或包含 `openclaw.extensions` 的有效 `package.json` —— 视为**原生插件** -2. 套件标记（`.codex-plugin/`、`.claude-plugin/` 或默认 Claude/Cursor 布局）—— 视为**套件** +1. `openclaw.plugin.json` 或带有 `openclaw.extensions` 的有效 `package.json` — 作为**原生插件**处理 +2. Bundle 标记（`.codex-plugin/`、`.claude-plugin/` 或默认 Claude/Cursor 布局）— 作为 **bundle** 处理 -如果一个目录同时包含两者，OpenClaw 会使用原生路径。这样可以防止双格式包被部分安装为套件。 +如果一个目录同时包含两者，OpenClaw 会使用原生路径。这可以防止双格式包被部分安装为 bundles。 ## 运行时依赖和清理 -- 打包插件的运行时依赖会作为 OpenClaw 包的一部分发布在 `dist/*` 下。OpenClaw **不会**在启动时为打包插件运行 `npm install`；发布流水线负责提供完整的打包依赖载荷（参见[发布]((/reference/RELEASING))中的 postpublish 验证规则）。 +- 第三方兼容 bundles 不会获得启动时 `npm install` 修复。它们应该通过 `openclaw plugins install` 安装，并在已安装插件目录中随附所需的一切内容。 +- OpenClaw 自有的打包 bundled 插件有一个窄例外：当其中一个启用时，Gateway 网关启动可以在导入前修复缺失的已声明运行时依赖。操作员可以用 `openclaw plugins deps` 检查或修复该阶段。 +- 发布流水线仍负责在可行时交付完整的 bundled 依赖载荷（请参阅 [发布](/zh-CN/reference/RELEASING) 中的 postpublish 验证规则）。 ## 安全 -与原生插件相比，套件的信任边界更窄： +bundles 的信任边界比原生插件更窄： -- OpenClaw **不会**在进程内加载任意套件运行时模块 -- Skills 和钩子包路径必须保留在插件根目录内（边界检查） -- 设置文件会使用相同的边界检查来读取 -- 支持的 stdio MCP 服务器可以作为子进程启动 +- OpenClaw **不会**在进程内加载任意 bundle 运行时模块 +- Skills 和钩子包路径必须保留在插件根目录内（会做边界检查） +- 设置文件使用相同的边界检查读取 +- 受支持的 stdio MCP 服务器可以作为子进程启动 -这使得套件在默认情况下更安全，但对于它们暴露的那些功能，你仍应将第三方套件视为受信任内容。 +这使 bundles 默认更安全，但你仍应将第三方 bundles 视为其所暴露功能的可信内容。 ## 故障排除 - - 运行 `openclaw plugins inspect `。如果某项能力已列出但标记为未接线，那是产品限制——不是安装损坏。 + + 运行 `openclaw plugins inspect `。如果某个能力已列出但标记为未接线，那是产品限制，而不是安装损坏。 - - 确保套件已启用，并且 Markdown 文件位于已检测到的 `commands/` 或 `skills/` 根目录中。 + + 确认 bundle 已启用，并且 markdown 文件位于已检测到的 `commands/` 或 `skills/` 根目录中。 - - 仅支持来自 `settings.json` 的嵌入式 Pi 设置。OpenClaw 不会将套件设置视为原始配置补丁。 + + 仅支持来自 `settings.json` 的嵌入式 Pi 设置。OpenClaw 不会将 bundle 设置视为原始配置补丁。 - - `hooks/hooks.json` 仅检测，不执行。如果你需要可运行的钩子，请使用 OpenClaw 钩子包布局，或发布一个原生插件。 + + `hooks/hooks.json` 仅用于检测。如果你需要可运行的钩子，请使用 OpenClaw 钩子包布局或发布原生插件。 -## 相关内容 +## 相关 - [安装和配置插件](/zh-CN/tools/plugin) - [构建插件](/zh-CN/plugins/building-plugins) — 创建原生插件 -- [插件 Manifest](/zh-CN/plugins/manifest) — 原生 Manifest 模式 +- [插件清单](/zh-CN/plugins/manifest) — 原生清单架构 diff --git a/docs/zh-CN/plugins/sdk-setup.md b/docs/zh-CN/plugins/sdk-setup.md index cd92ab26a..5461842bd 100644 --- a/docs/zh-CN/plugins/sdk-setup.md +++ b/docs/zh-CN/plugins/sdk-setup.md @@ -2,15 +2,15 @@ read_when: - 你正在为插件添加设置向导 - 你需要理解 setup-entry.ts 与 index.ts 的区别 - - 你正在定义插件配置模式或 package.json 中的 openclaw 元数据 + - 你正在定义插件配置模式或 `package.json` 的 `openclaw` 元数据 sidebarTitle: Setup and config -summary: 设置向导、setup-entry.ts、配置模式和 package.json 元数据 +summary: 设置向导、setup-entry.ts、配置架构和 package.json 元数据 title: 插件设置和配置 x-i18n: - generated_at: "2026-04-29T16:09:06Z" + generated_at: "2026-04-29T22:26:52Z" model: gpt-5.5 provider: openai - source_hash: 92f470a5c7e8fe06b9244a737de80c0509b26aa983d05e60dd1689cc628fc90d + source_hash: ded93227e0db13311870a9f45f01c2a0892a7204262fab17d09fdecd7c71579a source_path: plugins/sdk-setup.md workflow: 16 --- @@ -18,12 +18,12 @@ x-i18n: 插件打包（`package.json` 元数据）、清单（`openclaw.plugin.json`）、设置入口和配置架构的参考。 -**想看演练？** 操作指南结合上下文介绍了打包：[渠道插件](/zh-CN/plugins/sdk-channel-plugins#step-1-package-and-manifest) 和 [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-1-package-and-manifest)。 +**想看演练？** 操作指南会结合上下文介绍打包：[渠道插件](/zh-CN/plugins/sdk-channel-plugins#step-1-package-and-manifest) 和 [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-1-package-and-manifest)。 ## 包元数据 -你的 `package.json` 需要一个 `openclaw` 字段，用于告诉插件系统你的插件提供了什么： +你的 `package.json` 需要一个 `openclaw` 字段，用于告诉插件系统你的插件提供什么： @@ -67,7 +67,7 @@ x-i18n: -如果你在 ClawHub 上对外发布插件，则这些 `compat` 和 `build` 字段是必需的。规范发布片段位于 `docs/snippets/plugin-publish/`。 +如果你在 ClawHub 上外部发布插件，则必须包含这些 `compat` 和 `build` 字段。规范发布片段位于 `docs/snippets/plugin-publish/`。 ### `openclaw` 字段 @@ -76,10 +76,10 @@ x-i18n: 入口点文件（相对于包根目录）。 - 轻量级的仅设置入口（可选）。 + 轻量级仅设置入口（可选）。 - 用于设置、选择器、快速开始和 Status 界面的渠道目录元数据。 + 用于设置、选择器、快速开始和 Status 表面的渠道目录元数据。 此插件注册的提供商 ID。 @@ -93,29 +93,29 @@ x-i18n: ### `openclaw.channel` -`openclaw.channel` 是低成本的包元数据，用于在运行时加载之前提供渠道发现和设置界面。 +`openclaw.channel` 是低成本的包元数据，用于在运行时加载前支持渠道发现和设置表面。 | 字段 | 类型 | 含义 | | -------------------------------------- | ---------- | ----------------------------------------------------------------------------- | | `id` | `string` | 规范渠道 ID。 | -| `label` | `string` | 主要渠道标签。 | -| `selectionLabel` | `string` | 当需要不同于 `label` 时使用的选择器/设置标签。 | -| `detailLabel` | `string` | 用于更丰富的渠道目录和 Status 界面的次级详情标签。 | +| `label` | `string` | 主渠道标签。 | +| `selectionLabel` | `string` | 当需要与 `label` 不同时使用的选择器/设置标签。 | +| `detailLabel` | `string` | 用于更丰富渠道目录和 Status 表面的次要详情标签。 | | `docsPath` | `string` | 用于设置和选择链接的文档路径。 | -| `docsLabel` | `string` | 当文档链接标签需要不同于渠道 ID 时使用的覆盖标签。 | +| `docsLabel` | `string` | 当文档链接标签需要与渠道 ID 不同时使用的覆盖标签。 | | `blurb` | `string` | 简短的新手引导/目录描述。 | | `order` | `number` | 渠道目录中的排序顺序。 | -| `aliases` | `string[]` | 渠道选择的额外查找别名。 | -| `preferOver` | `string[]` | 此渠道应优先于的低优先级插件/渠道 ID。 | +| `aliases` | `string[]` | 用于渠道选择的额外查找别名。 | +| `preferOver` | `string[]` | 此渠道应优先于的较低优先级插件/渠道 ID。 | | `systemImage` | `string` | 渠道 UI 目录的可选图标/系统图像名称。 | -| `selectionDocsPrefix` | `string` | 选择界面中文档链接前的前缀文本。 | +| `selectionDocsPrefix` | `string` | 选择表面中文档链接前的前缀文本。 | | `selectionDocsOmitLabel` | `boolean` | 在选择文案中直接显示文档路径，而不是带标签的文档链接。 | | `selectionExtras` | `string[]` | 追加到选择文案中的额外短字符串。 | -| `markdownCapable` | `boolean` | 将渠道标记为支持 Markdown，以便做出出站格式化决策。 | -| `exposure` | `object` | 用于设置、已配置列表和文档界面的渠道可见性控制。 | -| `quickstartAllowFrom` | `boolean` | 让此渠道加入标准快速开始 `allowFrom` 设置流程。 | -| `forceAccountBinding` | `boolean` | 即使只有一个账户存在，也要求显式账户绑定。 | -| `preferSessionLookupForAnnounceTarget` | `boolean` | 为此渠道解析公告目标时优先使用会话查找。 | +| `markdownCapable` | `boolean` | 将渠道标记为支持 Markdown，用于出站格式决策。 | +| `exposure` | `object` | 用于设置、已配置列表和文档表面的渠道可见性控制。 | +| `quickstartAllowFrom` | `boolean` | 将此渠道加入标准快速开始 `allowFrom` 设置流程。 | +| `forceAccountBinding` | `boolean` | 即使只有一个账号存在，也要求显式账号绑定。 | +| `preferSessionLookupForAnnounceTarget` | `boolean` | 解析此渠道的公告目标时优先使用会话查找。 | 示例： @@ -149,9 +149,9 @@ x-i18n: `exposure` 支持： -- `configured`：在已配置/Status 风格的列表界面中包含该渠道 +- `configured`：在已配置/Status 风格的列表表面中包含该渠道 - `setup`：在交互式设置/配置选择器中包含该渠道 -- `docs`：在文档/导航界面中将该渠道标记为面向公众 +- `docs`：在文档/导航表面中将该渠道标记为面向公众 `showConfigured` 和 `showInSetup` 仍作为旧版别名受支持。优先使用 `exposure`。 @@ -165,14 +165,14 @@ x-i18n: | ---------------------------- | -------------------- | ---------------------------------------------------------------------------------- | | `npmSpec` | `string` | 用于安装/更新流程的规范 npm 规格。 | | `localPath` | `string` | 本地开发或内置安装路径。 | -| `defaultChoice` | `"npm"` \| `"local"` | 当两者都可用时首选的安装来源。 | -| `minHostVersion` | `string` | 支持的最低 OpenClaw 版本，格式为 `>=x.y.z`。 | +| `defaultChoice` | `"npm"` \| `"local"` | 两者都可用时的首选安装来源。 | +| `minHostVersion` | `string` | 受支持的最低 OpenClaw 版本，格式为 `>=x.y.z`。 | | `expectedIntegrity` | `string` | 预期的 npm dist 完整性字符串，通常为 `sha512-...`，用于固定版本安装。 | -| `allowInvalidConfigRecovery` | `boolean` | 允许内置插件重新安装流程从特定的过期配置失败中恢复。 | +| `allowInvalidConfigRecovery` | `boolean` | 允许内置插件重装流程从特定的陈旧配置失败中恢复。 | - 交互式新手引导也会将 `openclaw.install` 用于按需安装界面。如果你的插件在运行时加载之前公开提供商认证选择或渠道设置/目录元数据，新手引导可以显示该选项，提示选择 npm 或本地安装，安装或启用插件，然后继续所选流程。npm 新手引导选项需要受信任的目录元数据，并带有注册表 `npmSpec`；精确版本和 `expectedIntegrity` 是可选固定项。如果存在 `expectedIntegrity`，安装/更新流程会强制校验它。将“显示什么”的元数据放在 `openclaw.plugin.json` 中，将“如何安装它”的元数据放在 `package.json` 中。 + 交互式新手引导也会将 `openclaw.install` 用于按需安装表面。如果你的插件在运行时加载前公开提供商认证选择或渠道设置/目录元数据，新手引导可以显示该选择，提示选择 npm 或本地安装，安装或启用插件，然后继续所选流程。Npm 新手引导选择需要带有注册表 `npmSpec` 的可信目录元数据；精确版本和 `expectedIntegrity` 是可选固定项。如果存在 `expectedIntegrity`，安装/更新流程会强制校验它。将“显示什么”的元数据放在 `openclaw.plugin.json` 中，将“如何安装它”的元数据放在 `package.json` 中。 如果设置了 `minHostVersion`，安装和清单注册表加载都会强制执行它。较旧的宿主会跳过该插件；无效的版本字符串会被拒绝。 @@ -194,7 +194,7 @@ x-i18n: - `allowInvalidConfigRecovery` 不是损坏配置的通用绕过机制。它只用于狭窄的内置插件恢复场景，以便重新安装/设置能够修复已知的升级残留，例如缺少内置插件路径，或同一插件的过期 `channels.` 条目。如果配置因无关原因损坏，安装仍会以关闭方式失败，并提示操作员运行 `openclaw doctor --fix`。 + `allowInvalidConfigRecovery` 不是破损配置的通用绕过机制。它仅用于狭窄的内置插件恢复场景，因此重装/设置可以修复已知的升级遗留问题，例如缺失的内置插件路径，或同一插件的陈旧 `channels.` 条目。如果配置因无关原因破损，安装仍会失败关闭，并告知操作员运行 `openclaw doctor --fix`。 @@ -214,17 +214,17 @@ x-i18n: } ``` -启用后，即使对于已配置的渠道，OpenClaw 在监听前启动阶段也只加载 `setupEntry`。完整入口会在 Gateway 网关开始监听后加载。 +启用后，即使对于已配置的渠道，OpenClaw 在监听前启动阶段也只会加载 `setupEntry`。完整入口会在 Gateway 网关开始监听后加载。 -只有当你的 `setupEntry` 在 Gateway 网关开始监听之前注册了所需的一切（渠道注册、HTTP 路由、Gateway 网关方法）时，才启用延迟加载。如果完整入口拥有必需的启动能力，请保留默认行为。 +只有当你的 `setupEntry` 在 Gateway 网关开始监听前注册了所需的一切（渠道注册、HTTP 路由、Gateway 网关方法）时，才启用延迟加载。如果完整入口拥有必需的启动能力，请保留默认行为。 -如果你的设置/完整入口注册 Gateway 网关 RPC 方法，请将它们放在插件专用前缀下。保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍由核心拥有，并且始终解析为 `operator.admin`。 +如果你的设置/完整入口注册 Gateway 网关 RPC 方法，请将它们放在插件专用前缀下。保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍归核心所有，并始终解析为 `operator.admin`。 ## 插件清单 -每个原生插件都必须在包根目录中附带 `openclaw.plugin.json`。OpenClaw 使用它在不执行插件代码的情况下验证配置。 +每个原生插件都必须在包根目录中随附一个 `openclaw.plugin.json`。OpenClaw 使用它在不执行插件代码的情况下验证配置。 ```json { @@ -244,7 +244,7 @@ x-i18n: } ``` -对于渠道插件，添加 `kind` 和 `channels`： +对于渠道插件，请添加 `kind` 和 `channels`： ```json { @@ -259,7 +259,7 @@ x-i18n: } ``` -即使没有配置的插件也必须附带架构。空架构是有效的： +即使插件没有配置，也必须随附架构。空架构是有效的： ```json { @@ -271,11 +271,11 @@ x-i18n: } ``` -完整架构参考见 [插件清单](/zh-CN/plugins/manifest)。 +完整架构参考请参阅 [插件清单](/zh-CN/plugins/manifest)。 ## ClawHub 发布 -对于插件包，请使用特定于包的 ClawHub 命令： +对于插件包，请使用包专用的 ClawHub 命令： ```bash clawhub package publish your-org/your-plugin --dry-run @@ -288,7 +288,7 @@ clawhub package publish your-org/your-plugin ## 设置入口 -`setup-entry.ts` 文件是 `index.ts` 的轻量级替代入口，OpenClaw 仅需要设置界面（新手引导、配置修复、已禁用渠道检查）时会加载它。 +`setup-entry.ts` 文件是 `index.ts` 的轻量级替代项，OpenClaw 仅需要设置表面（新手引导、配置修复、已禁用渠道检查）时会加载它。 ```typescript // setup-entry.ts @@ -298,21 +298,21 @@ import { myChannelPlugin } from "./src/channel.js"; export default defineSetupPluginEntry(myChannelPlugin); ``` -这可以避免在设置流程中加载繁重的运行时代码（加密库、CLI 注册、后台服务）。 +这可避免在设置流程中加载较重的运行时代码（加密库、CLI 注册、后台服务）。 -在 sidecar 模块中保留设置安全导出的内置工作区渠道，可以使用来自 `openclaw/plugin-sdk/channel-entry-contract` 的 `defineBundledChannelSetupEntry(...)`，而不是 `defineSetupPluginEntry(...)`。该内置契约还支持可选的 `runtime` 导出，使设置时的运行时接线保持轻量且显式。 +将设置安全导出放在 sidecar 模块中的内置工作区渠道，可以使用来自 `openclaw/plugin-sdk/channel-entry-contract` 的 `defineBundledChannelSetupEntry(...)`，而不是 `defineSetupPluginEntry(...)`。该内置契约还支持可选的 `runtime` 导出，使设置时的运行时接线保持轻量且明确。 - 渠道已禁用，但需要设置/新手引导界面。 - - 渠道已启用，但尚未配置。 + - 渠道已启用但尚未配置。 - 已启用延迟加载（`deferConfiguredChannelFullLoadUntilAfterListen`）。 - 渠道插件对象（通过 `defineSetupPluginEntry`）。 - Gateway 网关监听前所需的任何 HTTP 路由。 - - 启动期间需要的任何 Gateway 网关方法。 + - 启动期间所需的任何 Gateway 网关方法。 这些启动 Gateway 网关方法仍应避免使用保留的核心管理命名空间，例如 `config.*` 或 `update.*`。 @@ -320,43 +320,43 @@ export default defineSetupPluginEntry(myChannelPlugin); - CLI 注册。 - 后台服务。 - - 繁重的运行时导入（加密、SDK）。 + - 较重的运行时导入（加密、SDK）。 - 仅在启动后才需要的 Gateway 网关方法。 -### 窄设置辅助导入 +### 窄范围设置辅助导入 -对于热路径中的仅设置代码，如果你只需要设置界面的一部分，请优先使用窄设置辅助接缝，而不是更宽泛的 `plugin-sdk/setup` 总入口： +对于热门的仅设置路径，如果你只需要设置界面的一部分，优先使用窄范围设置辅助 seam，而不是更宽泛的 `plugin-sdk/setup` 汇总入口： | 导入路径 | 用途 | 关键导出 | | ---------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/setup-runtime` | 在 `setupEntry` / 延迟渠道启动中仍可用的设置时运行时辅助工具 | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | +| `plugin-sdk/setup-runtime` | 设置时运行时辅助工具，在 `setupEntry` / 延迟渠道启动中保持可用 | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | 感知环境的账号设置适配器 | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | 设置/安装 CLI/归档/文档辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | -当你需要完整的共享设置工具箱时，请使用更宽泛的 `plugin-sdk/setup` 接缝，包括配置补丁辅助工具，例如 `moveSingleAccountChannelSectionToDefaultAccount(...)`。 +当你需要完整的共享设置工具箱（包括 `moveSingleAccountChannelSectionToDefaultAccount(...)` 等配置补丁辅助工具）时，使用更宽泛的 `plugin-sdk/setup` seam。 -设置补丁适配器在导入时保持热路径安全。它们内置的单账号提升契约界面查找是惰性的，因此导入 `plugin-sdk/setup-runtime` 不会在适配器实际使用前急切加载内置契约界面发现。 +设置补丁适配器在导入时保持热门路径安全。它们内置的单账号提升契约界面查找是惰性的，因此导入 `plugin-sdk/setup-runtime` 不会在适配器实际使用前急切加载内置契约界面发现逻辑。 ### 渠道拥有的单账号提升 当一个渠道从单账号顶层配置升级到 `channels..accounts.*` 时，默认共享行为会将提升后的账号作用域值移动到 `accounts.default`。 -内置渠道可以通过其设置契约界面缩小或覆盖该提升： +内置渠道可以通过其设置契约界面收窄或覆盖该提升： - `singleAccountKeysToMove`：应移动到提升账号中的额外顶层键 -- `namedAccountPromotionKeys`：当命名账号已存在时，只有这些键会移动到提升账号；共享策略/投递键保留在渠道根级 -- `resolveSingleAccountPromotionTarget(...)`：选择哪个现有账号接收提升后的值 +- `namedAccountPromotionKeys`：当命名账号已存在时，只有这些键会移动到提升账号中；共享策略/投递键会保留在渠道根级别 +- `resolveSingleAccountPromotionTarget(...)`：选择哪个现有账号接收提升值 -Matrix 是当前的内置示例。如果恰好已存在一个命名 Matrix 账号，或者 `defaultAccount` 指向现有的非规范键（例如 `Ops`），提升会保留该账号，而不是创建新的 `accounts.default` 条目。 +Matrix 是当前的内置示例。如果已经恰好存在一个命名的 Matrix 账号，或者 `defaultAccount` 指向一个现有的非规范键（例如 `Ops`），提升会保留该账号，而不是创建新的 `accounts.default` 条目。 -## 配置架构 +## 配置 schema -插件配置会根据你的清单中的 JSON Schema 进行验证。用户通过以下方式配置插件： +插件配置会根据清单中的 JSON Schema 进行验证。用户通过以下方式配置插件： ```json5 { @@ -372,9 +372,9 @@ Matrix 是当前的内置示例。如果恰好已存在一个命名 Matrix 账 } ``` -你的插件在注册期间会通过 `api.pluginConfig` 接收此配置。 +你的插件会在注册期间以 `api.pluginConfig` 接收此配置。 -对于渠道特定配置，请改用渠道配置部分： +对于渠道专用配置，请改用渠道配置部分： ```json5 { @@ -387,9 +387,9 @@ Matrix 是当前的内置示例。如果恰好已存在一个命名 Matrix 账 } ``` -### 构建渠道配置架构 +### 构建渠道配置 schema -使用 `buildChannelConfigSchema` 将 Zod 架构转换为插件拥有的配置构件所使用的 `ChannelConfigSchema` 包装器： +使用 `buildChannelConfigSchema` 将 Zod schema 转换为插件拥有的配置构件使用的 `ChannelConfigSchema` 包装器： ```typescript import { z } from "zod"; @@ -405,11 +405,11 @@ const accountSchema = z.object({ const configSchema = buildChannelConfigSchema(accountSchema); ``` -对于第三方插件，冷路径契约仍然是插件清单：将生成的 JSON Schema 镜像到 `openclaw.plugin.json#channelConfigs`，这样配置架构、设置和 UI 界面就可以在不加载运行时代码的情况下检查 `channels.`。 +对于第三方插件，冷路径契约仍然是插件清单：将生成的 JSON Schema 镜像到 `openclaw.plugin.json#channelConfigs`，这样配置 schema、设置和 UI 界面无需加载运行时代码即可检查 `channels.`。 ## 设置向导 -渠道插件可以为 `openclaw onboard` 提供交互式设置向导。向导是 `ChannelPlugin` 上的 `ChannelSetupWizard` 对象： +渠道插件可以为 `openclaw onboard` 提供交互式设置向导。该向导是 `ChannelPlugin` 上的 `ChannelSetupWizard` 对象： ```typescript import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup"; @@ -442,17 +442,17 @@ const setupWizard: ChannelSetupWizard = { }; ``` -`ChannelSetupWizard` 类型支持 `credentials`、`textInputs`、`dmPolicy`、`allowFrom`、`groupAccess`、`prepare`、`finalize` 等。完整示例请参阅内置插件包（例如 Discord 插件 `src/channel.setup.ts`）。 +`ChannelSetupWizard` 类型支持 `credentials`、`textInputs`、`dmPolicy`、`allowFrom`、`groupAccess`、`prepare`、`finalize` 等。完整示例请参阅内置插件包（例如 Discord 插件的 `src/channel.setup.ts`）。 - 对于只需要标准 `note -> prompt -> parse -> merge -> patch` 流程的私信允许列表提示，请优先使用来自 `openclaw/plugin-sdk/setup` 的共享设置辅助工具：`createPromptParsedAllowFromForAccount(...)`、`createTopLevelChannelParsedAllowFromPrompt(...)` 和 `createNestedChannelParsedAllowFromPrompt(...)`。 + 对于只需要标准 `note -> prompt -> parse -> merge -> patch` 流程的私信 allowlist 提示，优先使用来自 `openclaw/plugin-sdk/setup` 的共享设置辅助工具：`createPromptParsedAllowFromForAccount(...)`、`createTopLevelChannelParsedAllowFromPrompt(...)` 和 `createNestedChannelParsedAllowFromPrompt(...)`。 - 对于仅在标签、分数和可选额外行上有所不同的渠道设置 Status 块，请优先使用来自 `openclaw/plugin-sdk/setup` 的 `createStandardChannelSetupStatus(...)`，而不是在每个插件中手写相同的 `status` 对象。 + 对于只因标签、分数和可选额外行而不同的渠道设置 Status 块，优先使用来自 `openclaw/plugin-sdk/setup` 的 `createStandardChannelSetupStatus(...)`，而不是在每个插件中手写相同的 `status` 对象。 - 对于只应在特定上下文中出现的可选设置界面，请使用来自 `openclaw/plugin-sdk/channel-setup` 的 `createOptionalChannelSetupSurface`： + 对于只应在特定上下文中出现的可选设置界面，使用来自 `openclaw/plugin-sdk/channel-setup` 的 `createOptionalChannelSetupSurface`： ```typescript import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; @@ -466,15 +466,15 @@ const setupWizard: ChannelSetupWizard = { // Returns { setupAdapter, setupWizard } ``` - 当你只需要该可选安装界面的一半时，`plugin-sdk/channel-setup` 还会公开更底层的 `createOptionalChannelSetupAdapter(...)` 和 `createOptionalChannelSetupWizard(...)` 构建器。 + 当你只需要该可选安装界面的一半时，`plugin-sdk/channel-setup` 还公开了更底层的 `createOptionalChannelSetupAdapter(...)` 和 `createOptionalChannelSetupWizard(...)` 构建器。 - 生成的可选适配器/向导会在真实配置写入时失败关闭。它们在 `validateInput`、`applyAccountConfig` 和 `finalize` 中复用同一条需要安装的消息，并在设置了 `docsPath` 时追加文档链接。 + 生成的可选适配器/向导会对真实配置写入采取失败关闭策略。它们在 `validateInput`、`applyAccountConfig` 和 `finalize` 中复用同一条需要安装的消息，并在设置了 `docsPath` 时追加文档链接。 - 对于二进制支持的设置 UI，请优先使用共享委托辅助工具，而不是把相同的二进制/Status 胶水复制到每个渠道： + 对于二进制支持的设置 UI，优先使用共享的委托辅助工具，而不是把相同的二进制/Status 粘合逻辑复制到每个渠道中： - - `createDetectedBinaryStatus(...)`：用于仅在标签、提示、分数和二进制检测上变化的 Status 块 + - `createDetectedBinaryStatus(...)`：用于仅因标签、提示、分数和二进制检测而不同的 Status 块 - `createCliPathTextInput(...)`：用于路径支持的文本输入 - 当 `setupEntry` 需要惰性转发到更重的完整向导时，使用 `createDelegatedSetupWizardStatusResolvers(...)`、`createDelegatedPrepare(...)`、`createDelegatedFinalize(...)` 和 `createDelegatedResolveConfigured(...)` - 当 `setupEntry` 只需要委托 `textInputs[*].shouldPrompt` 决策时，使用 `createDelegatedTextInputShouldPrompt(...)` @@ -487,12 +487,12 @@ const setupWizard: ChannelSetupWizard = { **外部插件：**发布到 [ClawHub](/zh-CN/tools/clawhub)，然后安装： - + ```bash openclaw plugins install @myorg/openclaw-my-plugin ``` - OpenClaw 会先尝试 ClawHub，并在需要时自动回退到 npm。 + OpenClaw 会先尝试 ClawHub，并自动回退到 npm。 @@ -500,8 +500,8 @@ const setupWizard: ChannelSetupWizard = { openclaw plugins install clawhub:@myorg/openclaw-my-plugin ``` - - 当包尚未迁移到 ClawHub，或者迁移期间需要直接 npm 安装路径时，请使用 npm： + + 当包尚未迁移到 ClawHub，或迁移期间需要直接的 npm 安装路径时，使用 npm： ```bash openclaw plugins install npm:@myorg/openclaw-my-plugin @@ -510,7 +510,7 @@ const setupWizard: ChannelSetupWizard = { -**仓库内插件：**放在内置插件工作区树下，构建期间会自动发现。 +**仓库内插件：**放在内置插件工作区树下，它们会在构建期间自动被发现。 **用户可以安装：** @@ -519,17 +519,17 @@ openclaw plugins install ``` -对于来自 npm 的安装，`openclaw plugins install` 会运行项目本地的 `npm install --ignore-scripts`（无生命周期脚本），并忽略继承的全局 npm 安装设置。保持插件依赖树为纯 JS/TS，并避免需要 `postinstall` 构建的包。 +对于源自 npm 的安装，`openclaw plugins install` 会运行项目本地的 `npm install --ignore-scripts`（无生命周期脚本），并忽略继承的全局 npm 安装设置。请保持插件依赖树为纯 JS/TS，并避免使用需要 `postinstall` 构建的包。 -内置的 OpenClaw 自有插件是唯一的启动修复例外：当打包安装通过插件配置、旧版渠道配置或其内置的默认启用清单发现某个插件已启用时，启动过程会在导入前安装该插件缺失的运行时依赖。第三方插件不应依赖启动时安装；请继续使用显式插件安装器。 +OpenClaw 自有的内置插件是唯一的启动修复例外：当打包安装通过插件配置、旧版渠道配置或其内置的默认启用清单看到某个插件已启用时，启动会在导入前安装该插件缺失的运行时依赖。运维人员可以使用 `openclaw plugins deps` 检查或修复这个阶段。第三方插件不应依赖启动安装；请继续使用显式插件安装器。 -内置的包级运行时依赖是显式元数据，并非在 Gateway 网关启动时从构建后的 JavaScript 中推断。如果某个共享的 OpenClaw 根依赖必须在外部内置插件运行时镜像中可用，请在根包清单的 `openclaw.bundle.mirroredRootRuntimeDependencies` 中声明它。 +内置的包级运行时依赖是显式元数据，而不是在 Gateway 网关启动时从构建后的 JavaScript 推断出来的。如果共享的 OpenClaw 根依赖必须在外部内置插件运行时镜像中可用，请在根包清单的 `openclaw.bundle.mirroredRootRuntimeDependencies` 中声明它。 -## 相关内容 +## 相关 - [构建插件](/zh-CN/plugins/building-plugins) — 分步入门指南 -- [插件清单](/zh-CN/plugins/manifest) — 完整清单架构参考 +- [插件清单](/zh-CN/plugins/manifest) — 完整的清单模式参考 - [SDK 入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 和 `defineChannelPluginEntry`