diff --git a/docs/zh-CN/cli/plugins.md b/docs/zh-CN/cli/plugins.md index f3dbb541e..ff6e5e729 100644 --- a/docs/zh-CN/cli/plugins.md +++ b/docs/zh-CN/cli/plugins.md @@ -3,30 +3,30 @@ read_when: - 你想安装或管理 Gateway 网关插件或兼容包 - 你想调试插件加载失败 sidebarTitle: Plugins -summary: CLI 参考：`openclaw plugins`（list、install、marketplace、uninstall、enable/disable、doctor） +summary: '`openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、doctor）' title: 插件 x-i18n: - generated_at: "2026-04-28T11:48:36Z" + generated_at: "2026-04-28T17:10:20Z" model: gpt-5.5 provider: openai - source_hash: b458b67b905941f8f1424db7127640a3ae033dde5092daafd9926567d1bfc6cb + source_hash: 99b34b992248eec8830471d795d1827af208f739325fa02b01d58922a969d3b2 source_path: cli/plugins.md workflow: 16 --- -管理 Gateway 网关插件、钩子包和兼容包。 +管理 Gateway 网关插件、钩子包和兼容 bundle。 - - 面向最终用户的插件安装、启用和故障排除指南。 + + 面向最终用户的指南，介绍如何安装、启用插件并排查插件问题。 - - 包兼容性模型。 + + Bundle 兼容性模型。 - - 清单字段和配置模式。 + + 清单字段和配置 schema。 - + 插件安装的安全加固。 @@ -55,12 +55,14 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` +如果要调查安装、inspect、卸载或 registry 刷新较慢的问题，请使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 运行命令。该 trace 会将阶段耗时写入 stderr，并保持 JSON 输出可解析。请参阅 [调试](/zh-CN/help/debugging#plugin-lifecycle-trace)。 + -内置插件随 OpenClaw 一起提供。有些默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）；其他插件需要使用 `plugins enable`。 +内置插件随 OpenClaw 一起发布。有些默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）；其他插件需要 `plugins enable`。 -原生 OpenClaw 插件必须随附 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空）。兼容包改用自己的包清单。 +原生 OpenClaw 插件必须随附 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空）。兼容 bundle 改用它们自己的 bundle 清单。 -`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细列表/info 输出还会显示包子类型（`codex`、`claude` 或 `cursor`）以及检测到的包能力。 +`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细 list/info 输出还会显示 bundle 子类型（`codex`、`claude` 或 `cursor`）以及检测到的 bundle 能力。 ### 安装 @@ -79,73 +81,73 @@ openclaw plugins install --marketplace https://github.com// -裸包名会先在 ClawHub 中检查，然后再检查 npm。请像运行代码一样对待插件安装。优先使用固定版本。 +裸包名会先对照 ClawHub 检查，然后再检查 npm。请像运行代码一样对待插件安装。优先使用固定版本。 - - 如果你的 `plugins` 部分由单文件 `$include` 支持，`plugins install/update/enable/disable/uninstall` 会写入该被包含的文件，并保持 `openclaw.json` 不变。根包含、包含数组，以及带同级覆盖的包含会关闭失败，而不是展平。支持的形态见 [配置包含](/zh-CN/gateway/configuration)。 + + 如果你的 `plugins` section 由单文件 `$include` 支持，`plugins install/update/enable/disable/uninstall` 会写入该 include 文件，并让 `openclaw.json` 保持不变。根 include、include 数组以及带有同级 override 的 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 artifact 重新安装相同 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 规范。 + + `--pin` 只适用于 npm 安装。不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 源元数据，而不是 npm spec。 - `--dangerously-force-unsafe-install` 是内置危险代码扫描器出现误报时的应急选项。即使内置扫描器报告 `critical` 发现，它也允许安装继续，但它**不会**绕过插件 `before_install` 钩子策略阻止，也**不会**绕过扫描失败。 + `--dangerously-force-unsafe-install` 是内置危险代码扫描器出现误报时的应急选项。即使内置扫描器报告 `critical` 发现，它也允许安装继续，但它**不会**绕过插件 `before_install` 钩子的策略拦截，也**不会**绕过扫描失败。 - 此 CLI 标志适用于插件安装/update 流程。由 Gateway 网关支持的 skill 依赖安装使用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍是单独的 ClawHub skill 下载/安装流程。 + 此 CLI 标志适用于插件安装/update 流程。由 Gateway 网关支持的 skill 依赖安装使用匹配的 `dangerouslyForceUnsafeInstall` 请求 override，而 `openclaw skills install` 仍然是单独的 ClawHub skill 下载/安装流程。 - - `plugins install` 也是安装钩子包的入口，这些钩子包会在 `package.json` 中暴露 `openclaw.hooks`。使用 `openclaw hooks` 查看经过筛选的钩子可见性和逐钩子启用，不要用于包安装。 + + `plugins install` 也是安装暴露 `openclaw.hooks` 的钩子包的界面，位置在 `package.json` 中。使用 `openclaw hooks` 查看经过筛选的钩子可见性和单个钩子启用状态，而不是用于包安装。 - Npm 规范**仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file 规范和 semver 范围会被拒绝。为安全起见，依赖安装会以项目本地方式运行并使用 `--ignore-scripts`，即使你的 shell 中有全局 npm 安装设置也是如此。 + Npm specs **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file specs 和 semver ranges 会被拒绝。为了安全，即使你的 shell 有全局 npm install 设置，依赖安装也会以项目本地方式并带 `--ignore-scripts` 运行。 - 当你想跳过 ClawHub 查找并直接从 npm 安装时，使用 `npm:`。裸包规范仍优先使用 ClawHub，并且只有在 ClawHub 没有该包或版本时才回退到 npm。 + 当你想跳过 ClawHub lookup 并直接从 npm 安装时，使用 `npm:`。裸包 specs 仍优先使用 ClawHub，只有当 ClawHub 没有该包或版本时才回退到 npm。 - 裸规范和 `@latest` 会停留在稳定轨道。如果 npm 将其中任一项解析为预发布版本，OpenClaw 会停止并要求你使用预发布标签（例如 `@beta`/`@rc`）或精确的预发布版本（例如 `@1.2.3-beta.4`）显式选择加入。 + 裸 specs 和 `@latest` 会留在 stable 轨道。如果 npm 将其中任一项解析为 prerelease，OpenClaw 会停止，并要求你通过 prerelease tag（例如 `@beta`/`@rc`）或精确 prerelease 版本（例如 `@1.2.3-beta.4`）显式选择加入。 - 如果裸安装规范匹配内置插件 id（例如 `diffs`），OpenClaw 会直接安装内置插件。若要安装同名 npm 包，请使用显式作用域规范（例如 `@scope/diffs`）。 + 如果裸 install spec 匹配内置插件 id（例如 `diffs`），OpenClaw 会直接安装该内置插件。若要安装同名 npm 包，请使用显式 scoped 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:` locator： ```bash openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -OpenClaw 现在也会优先将 ClawHub 用于裸 npm 安全插件规范。只有在 ClawHub 没有该包或版本时，它才会回退到 npm： +OpenClaw 现在还会优先为裸 npm-safe 插件 specs 使用 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 安装会保留未指定版本的记录规范，因此 `openclaw plugins update` 可以跟随后续较新的 ClawHub 发布；显式版本或标签选择器（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）会保持固定到该选择器。 +OpenClaw 会从 ClawHub 下载包归档，检查声明的插件 API / 最低 gateway 兼容性，然后通过常规归档路径安装它。记录的安装会保留其 ClawHub 源元数据，以供后续 update 使用。 +未指定版本的 ClawHub 安装会保留未指定版本的记录 spec，因此 `openclaw plugins update` 可以跟随后续较新的 ClawHub release；显式版本或 tag 选择器（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）仍固定到该选择器。 #### Marketplace 简写 @@ -166,31 +168,31 @@ openclaw plugins install --marketplace ./my-marketplace ``` - - - 来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称 + + - 来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude known-marketplace 名称 - 本地 marketplace 根目录或 `marketplace.json` 路径 - - GitHub 仓库简写，例如 `owner/repo` - - GitHub 仓库 URL，例如 `https://github.com/owner/repo` + - GitHub repo 简写，例如 `owner/repo` + - GitHub repo URL，例如 `https://github.com/owner/repo` - git URL - - 对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保留在克隆的 marketplace 仓库内。OpenClaw 接受来自该仓库的相对路径源，并拒绝来自远程清单的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径插件源。 + + 对于从 GitHub 或 git 加载的远程 marketplaces，插件条目必须保持在克隆的 marketplace repo 内。OpenClaw 接受来自该 repo 的相对路径源，并拒绝来自远程清单的 HTTP(S)、绝对路径、git、GitHub 和其他非路径插件源。 对于本地路径和归档，OpenClaw 会自动检测： - 原生 OpenClaw 插件（`openclaw.plugin.json`） -- Codex 兼容包（`.codex-plugin/plugin.json`） -- Claude 兼容包（`.claude-plugin/plugin.json` 或默认 Claude 组件布局） -- Cursor 兼容包（`.cursor-plugin/plugin.json`） +- Codex-compatible bundles（`.codex-plugin/plugin.json`） +- Claude-compatible bundles（`.claude-plugin/plugin.json` 或默认 Claude 组件布局） +- Cursor-compatible bundles（`.cursor-plugin/plugin.json`） -兼容包会安装到普通插件根目录，并参与同一套 list/info/enable/disable 流程。目前支持包 Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex 钩子目录；其他检测到的包能力会显示在诊断/info 中，但尚未接入运行时执行。 +兼容 bundle 会安装到正常插件根目录，并参与相同的 list/info/enable/disable 流程。目前支持 bundle skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex 钩子目录；其他检测到的 bundle 能力会显示在 diagnostics/info 中，但尚未接入运行时执行。 -### 列出 +### 列表 ```bash openclaw plugins list @@ -203,27 +205,23 @@ openclaw plugins list --json 仅显示已启用的插件。 - 从表格视图切换到逐插件详细行，包含 source/origin/version/activation 元数据。 + 从表格视图切换为每个插件的详情行，包含 source/origin/version/activation 元数据。 - 机器可读的清单，以及 registry 诊断。 + 机器可读 inventory 加 registry diagnostics。 -`plugins list` 会先读取持久化的本地插件 registry；如果 registry 缺失或无效，则使用仅由清单派生的回退结果。它适合检查插件是否已安装、已启用，并且对冷启动规划可见，但它不是对已运行 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、钩子策略或 `plugins.load.paths` 后，请重启服务该渠道的 Gateway 网关，再期待新的 `register(api)` 代码或钩子运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不只是包装进程。 +`plugins list` 会先读取持久化的本地插件 registry；当 registry 缺失或无效时，使用仅基于清单派生的 fallback。它适合检查插件是否已安装、启用并对冷启动规划可见，但它不是对已运行 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、钩子策略或 `plugins.load.paths` 后，请先重启服务该渠道的 Gateway 网关，再期待新的 `register(api)` 代码或钩子运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不只是 wrapper 进程。 -对于打包 Docker 镜像内的内置插件工作，请将插件 -源目录绑定挂载到匹配的打包源路径上，例如 -`/app/extensions/synology-chat`。OpenClaw 会先发现该挂载的源 -覆盖层，再发现 `/app/dist/extensions/synology-chat`；普通复制的源 -目录仍不会生效，因此常规打包安装仍会使用编译后的 dist。 +对于 packaged Docker image 内的内置插件工作，请将插件源目录 bind-mount 到匹配的 packaged source path 上，例如 `/app/extensions/synology-chat`。OpenClaw 会先发现该挂载的 source overlay，再发现 `/app/dist/extensions/synology-chat`；普通复制的源目录仍不会生效，因此正常 packaged installs 仍使用 compiled dist。 对于运行时钩子调试： -- `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`。 +- `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`）： @@ -232,16 +230,16 @@ openclaw plugins install -l ./my-plugin ``` -`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是复制到托管安装目标上。 +`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是覆盖复制到托管安装目标。 -在 npm 安装中使用 `--pin`，可将解析后的精确规格（`name@version`）保存到托管插件索引中，同时保持默认行为为不固定版本。 +在 npm 安装中使用 `--pin`，可将解析后的精确规格（`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` 记录时，会将它们移动到插件索引并移除该配置键；如果任一写入失败，配置记录会保留，避免安装元数据丢失。 ### 卸载 @@ -251,10 +249,10 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` 会从 `plugins.entries`、持久化插件索引、插件允许/拒绝列表条目以及适用时链接的 `plugins.load.paths` 条目中移除插件记录。除非设置了 `--keep-files`，卸载还会移除跟踪的托管安装目录，前提是它位于 OpenClaw 的插件扩展根目录内。对于活动的内存插件，内存槽会重置为 `memory-core`。 +`uninstall` 会从 `plugins.entries`、持久化插件索引、插件允许/拒绝列表条目，以及适用时链接的 `plugins.load.paths` 条目中移除插件记录。除非设置了 `--keep-files`，否则卸载还会在托管安装目录位于 OpenClaw 插件扩展根目录内时移除该受跟踪的托管安装目录。对于活动内存插件，内存槽会重置为 `memory-core`。 -`--keep-config` 作为 `--keep-files` 的已弃用别名受支持。 +`--keep-config` 作为 `--keep-files` 的已弃用别名仍受支持。 ### 更新 @@ -267,25 +265,25 @@ openclaw plugins update @openclaw/voice-call@beta openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -更新适用于托管插件索引中跟踪的插件安装，以及 `hooks.internal.installs` 中跟踪的钩子包安装。 +更新会应用于托管插件索引中受跟踪的插件安装，以及 `hooks.internal.installs` 中受跟踪的钩子包安装。 - - 当你传入插件 id 时，OpenClaw 会复用该插件记录的安装规格。这意味着先前存储的 dist-tag（例如 `@beta`）和精确固定版本会在之后的 `update ` 运行中继续使用。 + + 当你传入插件 id 时，OpenClaw 会复用为该插件记录的安装规格。这意味着之前存储的 dist-tag（例如 `@beta`）和精确固定版本，会在后续 `update ` 运行中继续使用。 - 对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包规格。OpenClaw 会将该包名解析回被跟踪的插件记录，更新该已安装插件，并记录新的 npm 规格以供未来基于 id 的更新使用。 + 对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包规格。OpenClaw 会将该包名解析回受跟踪的插件记录，更新该已安装插件，并记录新的 npm 规格供将来基于 id 的更新使用。 - 传入不带版本或标签的 npm 包名，也会解析回被跟踪的插件记录。当某个插件被固定到精确版本，而你想将其移回注册表默认发布线时使用此方式。 + 传入不带版本或标签的 npm 包名也会解析回受跟踪的插件记录。当某个插件被固定到精确版本，而你想将其移回注册表默认发布线时，请使用这种方式。 - - 在实时 npm 更新之前，OpenClaw 会对照 npm 注册表元数据检查已安装包版本。如果已安装版本和记录的构件身份已与解析后的目标匹配，则会跳过更新，不下载、不重新安装，也不重写 `openclaw.json`。 + + 在执行实时 npm 更新前，OpenClaw 会根据 npm 注册表元数据检查已安装包版本。如果已安装版本和记录的产物身份已经与解析目标匹配，则会跳过更新，不下载、不重新安装，也不重写 `openclaw.json`。 - 当存在已存储的完整性哈希且获取到的构件哈希发生变化时，OpenClaw 会将其视为 npm 构件漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新辅助工具会默认关闭失败，除非调用方提供显式继续策略。 + 当存在已存储的完整性哈希且获取到的产物哈希发生变化时，OpenClaw 会将其视为 npm 产物漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新辅助程序会默认关闭失败，除非调用方提供显式继续策略。 - - `--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的应急覆盖。它仍然不会绕过插件 `before_install` 策略阻止或扫描失败阻止，并且只适用于插件更新，不适用于钩子包更新。 + + `--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的破窗覆盖。它仍不会绕过插件 `before_install` 策略阻断或扫描失败阻断，并且仅适用于插件更新，不适用于钩子包更新。 @@ -296,9 +294,9 @@ openclaw plugins inspect openclaw plugins inspect --json ``` -对单个插件进行深度自省。显示身份、加载状态、来源、已注册能力、钩子、工具、命令、服务、Gateway 网关方法、HTTP 路由、策略标志、诊断信息、安装元数据、包能力，以及检测到的任何 MCP 或 LSP 服务器支持。 +对单个插件进行深度内省。显示身份、加载状态、来源、已注册能力、钩子、工具、命令、服务、Gateway 网关方法、HTTP 路由、策略标志、诊断信息、安装元数据、包能力，以及检测到的任何 MCP 或 LSP 服务器支持。 -每个插件会按其在运行时实际注册的内容分类： +每个插件都会按其在运行时实际注册的内容分类： - **plain-capability** — 一种能力类型（例如仅提供商插件） - **hybrid-capability** — 多种能力类型（例如文本 + 语音 + 图像） @@ -308,7 +306,7 @@ openclaw plugins inspect --json 有关能力模型的更多信息，请参阅 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。 -`--json` 标志会输出适合脚本和审计的机器可读报告。`inspect --all` 会渲染一张全局表格，包含形态、能力种类、兼容性通知、包能力和钩子摘要列。`info` 是 `inspect` 的别名。 +`--json` 标志会输出适合脚本和审计使用的机器可读报告。`inspect --all` 会呈现全量表格，包含形态、能力种类、兼容性通知、包能力和钩子摘要列。`info` 是 `inspect` 的别名。 ### Doctor @@ -317,9 +315,9 @@ 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` 重新运行，以在诊断输出中包含紧凑的导出形态摘要。 +对于缺少 `register`/`activate` 导出等模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以在诊断输出中包含紧凑的导出形态摘要。 ### 注册表 @@ -329,12 +327,12 @@ openclaw plugins registry --refresh openclaw plugins registry --json ``` -本地插件注册表是 OpenClaw 的持久化冷读取模型，用于已安装插件的身份、启用状态、来源元数据和贡献归属。正常启动、提供商所有者查找、渠道设置分类和插件清单都可以在不导入插件运行时模块的情况下读取它。 +本地插件注册表是 OpenClaw 为已安装插件身份、启用状态、来源元数据和贡献归属持久化的冷读取模型。正常启动、提供商所有者查找、渠道设置分类和插件清单都可以读取它，而无需导入插件运行时模块。 -使用 `plugins registry` 检查持久化注册表是否存在、是否为当前版本或是否已过期。使用 `--refresh` 可根据持久化插件索引、配置策略和清单/包元数据重建它。这是修复路径，不是运行时激活路径。 +使用 `plugins registry` 检查持久化注册表是否存在、是否当前有效或是否过期。使用 `--refresh` 可根据持久化插件索引、配置策略和 manifest/包元数据重建它。这是修复路径，不是运行时激活路径。 -`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是一个已弃用的应急兼容性开关，用于注册表读取失败。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；环境变量回退仅用于迁移推出期间的紧急启动恢复。 +`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是用于注册表读取失败的已弃用破窗兼容开关。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；该环境变量回退仅用于迁移推出期间的紧急启动恢复。 ### 市场 @@ -344,7 +342,7 @@ 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 和插件条目。 ## 相关 diff --git a/docs/zh-CN/help/debugging.md b/docs/zh-CN/help/debugging.md index 6738717f3..3c967a933 100644 --- a/docs/zh-CN/help/debugging.md +++ b/docs/zh-CN/help/debugging.md @@ -1,26 +1,26 @@ --- read_when: - - 你需要检查原始模型输出中的推理泄漏问题 - - 你想在迭代时以监视模式运行 Gateway 网关 - - 你需要一套可重复的调试工作流 -summary: 调试工具：监视模式、原始模型流以及推理泄漏追踪 + - 你需要检查原始模型输出是否泄露推理内容 + - 你想在迭代过程中以监视模式运行 Gateway 网关 + - 你需要一个可重复的调试工作流 +summary: 调试工具：监视模式、原始模型流和推理泄漏追踪 title: 调试 x-i18n: - generated_at: "2026-04-27T06:04:45Z" - model: gpt-5.4 + generated_at: "2026-04-28T17:10:23Z" + model: gpt-5.5 provider: openai - source_hash: 374af10312e07d4c4e45d07416fa2d0920dd300e739ebb7a3b72b1e327f21cc1 + source_hash: 13a49773e39041c77d4562aadcf03669bb5e66801be9908954e971a27f924cd4 source_path: help/debugging.md - workflow: 15 + workflow: 16 --- -用于调试流式输出的辅助工具，尤其适用于提供商将推理内容混入普通文本时的情况。 +流式输出的调试辅助工具，尤其适用于提供商将推理内容混入普通文本的情况。 ## 运行时调试覆盖 -在聊天中使用 `/debug` 可设置**仅运行时**的配置覆盖（存储在内存中，不写入磁盘）。 -`/debug` 默认禁用；通过 `commands.debug: true` 启用。 -当你需要切换一些冷门设置而不想编辑 `openclaw.json` 时，这很方便。 +在聊天中使用 `/debug` 设置**仅运行时**配置覆盖（保存在内存中，不写入磁盘）。 +`/debug` 默认禁用；使用 `commands.debug: true` 启用。 +当你需要切换晦涩设置但不想编辑 `openclaw.json` 时，这很方便。 示例： @@ -33,10 +33,9 @@ x-i18n: `/debug reset` 会清除所有覆盖，并恢复为磁盘上的配置。 -## 会话 trace 输出 +## 会话跟踪输出 -当你希望只在某个会话中查看插件拥有的 trace/debug 行， -而不启用完整 verbose 模式时，请使用 `/trace`。 +当你想在一个会话中查看插件拥有的跟踪/调试行，但不想开启完整详细模式时，使用 `/trace`。 示例： @@ -47,23 +46,39 @@ x-i18n: ``` 将 `/trace` 用于插件诊断，例如 Active Memory 调试摘要。 -普通 verbose 状态/工具输出仍使用 `/verbose`，而运行时专用配置覆盖仍使用 -`/debug`。 +继续使用 `/verbose` 查看常规的详细 Status/工具输出，并继续使用 `/debug` 进行仅运行时配置覆盖。 + +## 插件生命周期跟踪 + +当插件生命周期命令感觉很慢，并且你需要内置的阶段拆解来查看插件元数据、设备发现、注册表、运行时镜像、配置变更和刷新工作时，使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`。该跟踪是选择性启用的，并写入 stderr，因此 JSON 命令输出仍保持可解析。 + +示例： + +```bash +OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force +``` + +示例输出： + +```text +[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install" +[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice" +[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed" +``` + +在使用 CPU 分析器之前，先用它调查插件生命周期。 +如果命令从源码检出目录运行，建议在 `pnpm build` 后用 `node dist/entry.js ...` 测量构建后的运行时；`pnpm openclaw ...` 也会把源码运行器开销计入测量。 ## 临时 CLI 调试计时 -OpenClaw 保留 `src/cli/debug-timing.ts` 作为一个用于本地排查的小型辅助工具。 -它有意默认不接入 CLI 启动流程、命令路由或任何命令。仅在调试慢命令时使用， -然后在提交行为变更前移除相应的 import 和 span。 +OpenClaw 保留 `src/cli/debug-timing.ts` 作为本地调查的小型辅助工具。 +它有意默认不接入 CLI 启动、命令路由或任何命令。只在调试慢命令时使用它，然后在落地行为变更前移除 import 和 span。 -当某条命令很慢，而你需要先快速拆解各阶段耗时， -再决定是使用 CPU profiler 还是修复某个特定子系统时，可使用它。 +当某个命令很慢，而你需要快速查看阶段拆解，再决定是使用 CPU 分析器还是修复特定子系统时，使用它。 ### 添加临时 span -将辅助工具添加到你正在排查的代码附近。例如，在调试 -`openclaw models list` 时，可在 -`src/commands/models/list.list-command.ts` 中临时加入如下补丁： +在你正在调查的代码附近添加该辅助工具。例如，在调试 `openclaw models list` 时，`src/commands/models/list.list-command.ts` 中的临时补丁可能如下所示： ```ts // Temporary debugging only. Remove before landing. @@ -83,15 +98,15 @@ const loaded = await timing.timeAsync( ); ``` -指南： +准则： -- 临时阶段名称请使用 `debug:` 前缀。 -- 只在怀疑较慢的代码段周围添加少量 span。 -- 优先使用宽泛阶段名称，如 `registry`、`auth_store` 或 `rows`，而不是辅助函数名。 -- 对同步工作使用 `time()`，对 Promise 使用 `timeAsync()`。 -- 保持 stdout 干净。该辅助工具会写入 stderr，因此命令的 JSON 输出仍可解析。 -- 在提交最终修复 PR 前移除临时 import 和 span。 -- 在 issue 或 PR 中附上计时输出或简短摘要，以说明优化依据。 +- 用 `debug:` 作为临时阶段名称的前缀。 +- 只在疑似慢的区段周围添加少量 span。 +- 相比辅助函数名称，优先使用 `registry`、`auth_store` 或 `rows` 这类宽泛阶段。 +- 对同步工作使用 `time()`，对 promise 使用 `timeAsync()`。 +- 保持 stdout 干净。该辅助工具写入 stderr，因此命令 JSON 输出保持可解析。 +- 在打开最终修复 PR 前移除临时 import 和 span。 +- 在 issue 或 PR 中包含计时输出或简短摘要，以说明优化依据。 ### 使用可读输出运行 @@ -101,7 +116,7 @@ const loaded = await timing.timeAsync( OPENCLAW_DEBUG_TIMING=1 pnpm openclaw models list --all --provider moonshot ``` -来自一次临时 `models list` 排查的示例输出： +临时 `models list` 调查的示例输出： ```text OpenClaw CLI debug timing: models list @@ -130,30 +145,29 @@ moonshot/kimi-k2.6 text+image 256k no no 36.9s +0ms complete rows=5 ``` -从这份输出可得出的结论： +从该输出得出的发现： -| Phase | Time | 含义 | -| ----- | ---: | ---- | -| `debug:models:list:auth_store` | 20.3s | auth-profile store 加载是最大的成本，应优先排查。 | -| `debug:models:list:ensure_models_json` | 5.0s | 同步 `models.json` 的开销足够大，值得检查缓存或跳过条件。 | -| `debug:models:list:load_model_registry` | 5.9s | 注册表构建和 provider 可用性检查也有明显成本。 | -| `debug:models:list:read_registry_models` | 2.4s | 读取全部注册表模型并非没有成本，对 `--all` 可能很重要。 | -| 行追加阶段 | 总计 3.2s | 即使只构建 5 行显示结果，也用了数秒，因此应进一步查看过滤路径。 | -| `debug:models:list:print_model_table` | 0ms | 渲染不是瓶颈。 | +| 阶段 | 时间 | 含义 | +| ---------------------------------------- | ---------: | ------------------------------------------------------------------------------------------------------- | +| `debug:models:list:auth_store` | 20.3s | auth-profile 存储加载是最大成本，应优先调查。 | +| `debug:models:list:ensure_models_json` | 5.0s | 同步 `models.json` 的开销已经值得检查是否可缓存或跳过。 | +| `debug:models:list:load_model_registry` | 5.9s | 注册表构建和提供商可用性工作也是有意义的成本。 | +| `debug:models:list:read_registry_models` | 2.4s | 读取所有注册表模型并非免费，对 `--all` 可能有影响。 | +| 行追加阶段 | 总计 3.2s | 构建五个显示行仍需数秒，因此过滤路径值得进一步查看。 | +| `debug:models:list:print_model_table` | 0ms | 渲染不是瓶颈。 | -这些结论已经足以指导下一次补丁，而无需将计时代码保留在 -生产路径中。 +这些发现足以指导下一次补丁，而无需在生产路径中保留计时代码。 ### 使用 JSON 输出运行 -当你想保存或比较计时数据时，请使用 JSON 模式： +当你想保存或比较计时数据时，使用 JSON 模式： ```bash OPENCLAW_DEBUG_TIMING=json pnpm openclaw models list --all --provider moonshot \ 2> .artifacts/models-list-timing.jsonl ``` -stderr 的每一行都是一个 JSON 对象： +每一行 stderr 都是一个 JSON 对象： ```json { @@ -167,9 +181,9 @@ stderr 的每一行都是一个 JSON 对象： } ``` -### 提交前清理 +### 落地前清理 -在打开最终 PR 之前： +打开最终 PR 前： ```bash rg 'createCliDebugTiming|debug:[a-z0-9_-]+:' src/commands src/cli \ @@ -177,47 +191,36 @@ rg 'createCliDebugTiming|debug:[a-z0-9_-]+:' src/commands src/cli \ --glob '!*.test.ts' ``` -除非该 PR 明确是在添加永久性的诊断能力，否则该命令不应返回任何临时埋点调用点。 -对于普通性能修复，只保留行为变更、测试以及包含计时证据的简短说明。 +除非该 PR 明确是在添加永久诊断界面，否则该命令不应返回任何临时插桩调用点。对于常规性能修复，只保留行为变更、测试，以及包含计时证据的简短说明。 -对于更深层的 CPU 热点，请使用 Node profiling（`--cpu-prof`）或外部 -profiler，而不是继续添加更多计时包装。 +对于更深层的 CPU 热点，请使用 Node 分析（`--cpu-prof`）或外部分析器，而不是添加更多计时包装器。 -## Gateway 网关监视模式 +## Gateway 网关 watch 模式 -为了快速迭代，可在文件监视器下运行 Gateway 网关： +为了快速迭代，在文件 watcher 下运行 Gateway 网关： ```bash pnpm gateway:watch ``` -它映射到： +这会映射到： ```bash node scripts/watch-node.mjs gateway --force ``` -当 `src/` 下的构建相关文件、扩展源码文件、 -扩展 `package.json` 和 `openclaw.plugin.json` 元数据、`tsconfig.json`、 -`package.json` 以及 `tsdown.config.ts` 发生变化时，监视器会重启 -gateway。扩展元数据变更会重启 gateway，但不会强制执行 `tsdown` 重建； -源码和配置变更仍会先重建 `dist`。 +该 watcher 会在 `src/` 下与构建相关的文件、插件源文件、插件 `package.json` 和 `openclaw.plugin.json` 元数据、`tsconfig.json`、`package.json` 以及 `tsdown.config.ts` 发生变化时重启。插件元数据变更会重启 Gateway 网关，但不会强制执行 `tsdown` 重新构建；源码和配置变更仍会先重新构建 `dist`。 -在 `gateway:watch` 后追加任何 gateway CLI 标志， -这些标志都会在每次重启时透传。现在，对同一仓库/同一标志集重复运行相同的监视命令 -会替换旧的 watcher，而不是留下重复的 watcher 父进程。 +在 `gateway:watch` 后添加任何 Gateway 网关 CLI 标志，它们都会在每次重启时透传。现在，对同一仓库/标志组合重新运行相同的 watch 命令时，会替换旧 watcher，而不会留下重复的 watcher 父进程。 -## Dev profile + dev gateway（`--dev`） +## 开发配置文件 + 开发 Gateway 网关（--dev） -使用 dev profile 可以隔离状态，并为调试启动一个安全、可丢弃的环境。 -这里有**两个** `--dev` 标志： +使用开发配置文件来隔离状态，并启动一个安全、可丢弃的设置用于调试。这里有**两个** `--dev` 标志： -- **全局 `--dev`（profile）**：将状态隔离到 `~/.openclaw-dev` 下， - 并默认将 gateway 端口设为 `19001`（派生端口也会随之变动）。 -- **`gateway --dev`**：告诉 Gateway 网关在配置和工作区缺失时自动创建默认配置 + - workspace（并跳过 `BOOTSTRAP.md`）。 +- **全局 `--dev`（profile）：** 将状态隔离到 `~/.openclaw-dev` 下，并将 Gateway 网关端口默认为 `19001`（派生端口随之偏移）。 +- **`gateway --dev`：告诉 Gateway 网关在缺失时自动创建默认配置 + 工作区**（并跳过 BOOTSTRAP.md）。 -推荐流程（dev profile + dev bootstrap）： +推荐流程（开发配置文件 + 开发引导）： ```bash pnpm gateway:dev @@ -226,22 +229,22 @@ OPENCLAW_PROFILE=dev openclaw tui 如果你还没有全局安装，请通过 `pnpm openclaw ...` 运行 CLI。 -其作用如下： +这会执行以下操作： -1. **Profile 隔离**（全局 `--dev`） +1. **配置文件隔离**（全局 `--dev`） - `OPENCLAW_PROFILE=dev` - `OPENCLAW_STATE_DIR=~/.openclaw-dev` - `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json` - - `OPENCLAW_GATEWAY_PORT=19001`（browser/canvas 端口也会相应偏移） + - `OPENCLAW_GATEWAY_PORT=19001`（browser/canvas 会相应偏移） -2. **Dev bootstrap**（`gateway --dev`） - - 若配置缺失则写入一个最小配置（`gateway.mode=local`，绑定 loopback）。 - - 将 `agent.workspace` 设置为 dev workspace。 - - 设置 `agent.skipBootstrap=true`（不使用 `BOOTSTRAP.md`）。 - - 若工作区文件缺失则写入初始文件： +2. **开发引导**（`gateway --dev`） + - 如果缺失，写入最小配置（`gateway.mode=local`，绑定 local loopback）。 + - 将 `agent.workspace` 设置为开发工作区。 + - 设置 `agent.skipBootstrap=true`（无 BOOTSTRAP.md）。 + - 如果缺失，则播种工作区文件： `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`。 - - 默认身份：**C3‑PO**（protocol droid）。 - - 在 dev 模式下跳过渠道 provider（`OPENCLAW_SKIP_CHANNELS=1`）。 + - 默认身份：**C3‑PO**（礼仪机器人）。 + - 在开发模式中跳过渠道提供商（`OPENCLAW_SKIP_CHANNELS=1`）。 重置流程（全新开始）： @@ -250,7 +253,7 @@ pnpm gateway:dev:reset ``` -`--dev` 是一个**全局** profile 标志，会被某些运行器吞掉。如果你需要显式写出它，请使用环境变量形式： +`--dev` 是一个**全局**配置文件标志，会被某些运行器吞掉。如果你需要明确写出它，请使用环境变量形式： ```bash OPENCLAW_PROFILE=dev openclaw gateway --dev --reset @@ -258,11 +261,10 @@ OPENCLAW_PROFILE=dev openclaw gateway --dev --reset -`--reset` 会清除配置、凭证、会话以及 dev workspace（使用 -`trash`，而不是 `rm`），然后重新创建默认的 dev 设置。 +`--reset` 会清除配置、凭证、会话和开发工作区（使用 `trash`，而不是 `rm`），然后重新创建默认开发设置。 -如果已有非 dev 的 gateway 正在运行（launchd 或 systemd），请先停止它： +如果非开发 Gateway 网关已经在运行（launchd 或 systemd），请先停止它： ```bash openclaw gateway stop @@ -272,9 +274,8 @@ openclaw gateway stop ## 原始流日志（OpenClaw） -OpenClaw 可以记录**原始助手流**，即在任何过滤/格式化之前的内容。 -这是查看推理内容是否以普通文本 delta -（或作为独立 thinking block）到达的最佳方式。 +OpenClaw 可以在任何过滤/格式化之前记录**原始 assistant 流**。 +这是查看推理是作为纯文本增量到达，还是作为独立 thinking block 到达的最佳方式。 通过 CLI 启用： @@ -299,10 +300,9 @@ OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl `~/.openclaw/logs/raw-stream.jsonl` -## 原始分块日志（pi-mono） +## 原始 chunk 日志（pi-mono） -若要在分块被解析成 block 之前捕获**原始 OpenAI 兼容分块**， -pi-mono 提供了单独的记录器： +为了在原始 OpenAI 兼容 chunk 被解析为 block 之前捕获它们，pi-mono 提供了单独的日志记录器： ```bash PI_RAW_STREAM=1 @@ -318,16 +318,16 @@ PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl `~/.pi-mono/logs/raw-openai-completions.jsonl` -> 注意：这只会由使用 pi-mono -> `openai-completions` provider 的进程输出。 +> 注意：这只由使用 pi-mono 的 +> `openai-completions` 提供商的进程发出。 ## 安全说明 - 原始流日志可能包含完整提示词、工具输出和用户数据。 -- 请将日志保留在本地，并在调试后删除。 -- 如果你要共享日志，请先清理密钥和个人敏感信息。 +- 将日志保留在本地，并在调试后删除它们。 +- 如果你共享日志，请先清理密钥和 PII。 -## 相关内容 +## 相关 - [故障排除](/zh-CN/help/troubleshooting) - [常见问题](/zh-CN/help/faq) diff --git a/docs/zh-CN/plugins/manifest.md b/docs/zh-CN/plugins/manifest.md index b9c794a7f..d044a9d07 100644 --- a/docs/zh-CN/plugins/manifest.md +++ b/docs/zh-CN/plugins/manifest.md @@ -1,21 +1,21 @@ --- read_when: - 你正在构建一个 OpenClaw 插件 - - 你需要交付插件配置模式或调试插件验证错误 -summary: 插件清单 + JSON schema 要求（严格配置验证） + - 你需要发布插件配置模式或调试插件验证错误 +summary: 插件清单 + JSON 架构要求（严格配置验证） title: 插件清单 x-i18n: - generated_at: "2026-04-28T11:58:47Z" + generated_at: "2026-04-28T17:10:24Z" model: gpt-5.5 provider: openai - source_hash: 87c8769dac98b6e67338788492819e7b4d93cd1fa04dbc5629590f57ad5a06c7 + source_hash: c9b3c48d2173ac6d818ea5a7887cd30ccaeb056f14529175c09d022df3b69cdc source_path: plugins/manifest.md workflow: 16 --- -此页面仅适用于 **原生 OpenClaw 插件清单**。 +此页面仅适用于**原生 OpenClaw 插件清单**。 -兼容的包布局请参见 [插件包](/zh-CN/plugins/bundles)。 +有关兼容的包布局，请参阅[插件包](/zh-CN/plugins/bundles)。 兼容的包格式使用不同的清单文件： @@ -24,39 +24,35 @@ x-i18n: 布局 - Cursor 包：`.cursor-plugin/plugin.json` -OpenClaw 也会自动检测这些包布局，但不会根据此处描述的 `openclaw.plugin.json` 架构 -对它们进行验证。 +OpenClaw 也会自动检测这些包布局，但不会根据此处描述的 +`openclaw.plugin.json` schema 来验证它们。 -对于兼容包，当布局符合 OpenClaw 运行时期望时，OpenClaw 目前会读取包元数据、声明的 -Skill 根目录、Claude 命令根目录、Claude 包 `settings.json` 默认值、 +对于兼容包，OpenClaw 目前会在布局符合 OpenClaw 运行时预期时，读取包元数据以及已声明的 +Skills 根目录、Claude 命令根目录、Claude 包 `settings.json` 默认值、 Claude 包 LSP 默认值，以及受支持的钩子包。 -每个原生 OpenClaw 插件都**必须**在**插件根目录**中随附一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单来验证配置， -而**不会执行插件代码**。缺失或无效的清单会被视为 -插件错误，并阻止配置验证。 +每个原生 OpenClaw 插件都**必须**在**插件根目录**中附带一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单在**不执行插件代码**的情况下验证配置。缺失或无效的清单会被视为插件错误，并阻止配置验证。 -查看完整插件系统指南：[插件](/zh-CN/tools/plugin)。 -关于原生能力模型和当前外部兼容性指南： +请参阅完整的插件系统指南：[插件](/zh-CN/tools/plugin)。 +有关原生能力模型和当前外部兼容性指南： [能力模型](/zh-CN/plugins/architecture#public-capability-model)。 ## 此文件的作用 -`openclaw.plugin.json` 是 OpenClaw 在**加载你的 -插件代码之前**读取的元数据。以下所有内容都必须足够轻量，能够在不启动 -插件运行时的情况下检查。 +`openclaw.plugin.json` 是 OpenClaw 在**加载你的插件代码之前**读取的元数据。以下所有内容都必须足够轻量，能够在不启动插件运行时的情况下检查。 **用于：** - 插件身份、配置验证和配置 UI 提示 -- 凭证、新手引导和设置元数据（别名、自动启用、提供商环境变量、凭证选项） +- 身份验证、新手引导和设置元数据（别名、自动启用、提供商环境变量、身份验证选项） - 控制平面界面的激活提示 -- 模型家族所有权简写 +- 模型系列所有权简写 - 静态能力所有权快照（`contracts`） -- 共享 `openclaw qa` 主机可检查的 QA runner 元数据 -- 合并到目录和验证界面的渠道专用配置元数据 +- 共享 `openclaw qa` 主机可以检查的 QA 运行器元数据 +- 合并到目录和验证界面的渠道专属配置元数据 **不要用于：**注册运行时行为、声明代码入口点， -或 npm 安装元数据。这些内容应放在你的插件代码和 `package.json` 中。 +或 npm 安装元数据。这些应放在你的插件代码和 `package.json` 中。 ## 最小示例 @@ -71,7 +67,7 @@ Claude 包 LSP 默认值，以及受支持的钩子包。 } ``` -## 完整示例 +## 丰富示例 ```json { @@ -148,76 +144,74 @@ Claude 包 LSP 默认值，以及受支持的钩子包。 } ``` -## 顶级字段参考 +## 顶层字段参考 -| 字段 | 必需 | 类型 | 含义 | +| 字段 | 必需 | 类型 | 含义 | | ------------------------------------ | ---- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | 是 | `string` | 规范插件 id。这是在 `plugins.entries.` 中使用的 id。 | -| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 | -| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略它，或设置任何非 `true` 值，即可让插件默认禁用。 | -| `legacyPluginIds` | 否 | `string[]` | 会规范化为此规范插件 id 的旧版 id。 | -| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当凭证、配置或模型引用提到这些提供商 id 时，应自动启用此插件。 | -| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明由 `plugins.slots.*` 使用的互斥插件类型。 | -| `channels` | 否 | `string[]` | 此插件拥有的渠道 id。用于设备发现和配置验证。 | -| `providers` | 否 | `string[]` | 此插件拥有的提供商 id。 | -| `providerDiscoveryEntry` | 否 | `string` | 轻量级提供商发现模块路径，相对于插件根目录，用于清单作用域的提供商目录元数据，可在不激活完整插件运行时的情况下加载。 | -| `modelSupport` | 否 | `object` | 清单拥有的模型系列元数据简写，用于在运行时之前自动加载插件。 | -| `modelCatalog` | 否 | `object` | 此插件拥有的提供商的声明式模型目录元数据。这是未来只读列表、新手引导、模型选择器、别名和抑制功能的控制平面契约，无需加载插件运行时。 | -| `modelPricing` | 否 | `object` | 提供商拥有的外部定价查询策略。用它让本地/自托管提供商退出远程定价目录，或将提供商引用映射到 OpenRouter/LiteLLM 目录 id，而无需在 core 中硬编码提供商 id。 | -| `modelIdNormalization` | 否 | `object` | 提供商拥有的模型 id 别名/前缀清理，必须在提供商运行时加载之前运行。 | -| `providerEndpoints` | 否 | `object[]` | 清单拥有的提供商路由 endpoint 主机/baseUrl 元数据，core 必须在提供商运行时加载之前对其分类。 | -| `providerRequest` | 否 | `object` | 泛型请求策略在提供商运行时加载之前使用的低成本提供商系列和请求兼容性元数据。 | -| `cliBackends` | 否 | `string[]` | 此插件拥有的 CLI 推理 backend id。用于从显式配置引用进行启动时自动激活。 | -| `syntheticAuthRefs` | 否 | `string[]` | 提供商或 CLI backend 引用，其插件拥有的合成凭证钩子应在运行时加载之前的冷模型发现期间被探测。 | -| `nonSecretAuthMarkers` | 否 | `string[]` | 内置插件拥有的占位 API key 值，表示非机密的本地、OAuth 或环境凭证状态。 | -| `commandAliases` | 否 | `object[]` | 此插件拥有的命令名称，应在运行时加载之前生成感知插件的配置和 CLI 诊断。 | -| `providerAuthEnvVars` | 否 | `Record` | 已弃用的兼容性环境元数据，用于提供商凭证/Status 查询。新插件优先使用 `setup.providers[].envVars`；OpenClaw 在弃用窗口期间仍会读取此项。 | -| `providerAuthAliases` | 否 | `Record` | 应复用另一个提供商 id 进行凭证查询的提供商 id，例如共享基础提供商 API key 和凭证配置文件的编码提供商。 | -| `channelEnvVars` | 否 | `Record` | OpenClaw 可在不加载插件代码的情况下检查的低成本渠道环境元数据。将它用于环境驱动的渠道设置或泛型启动/配置辅助工具应看到的凭证界面。 | -| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI 标志接线的低成本凭证选择元数据。 | -| `activation` | 否 | `object` | 用于启动、提供商、命令、渠道、路由和能力触发加载的低成本激活规划器元数据。仅限元数据；插件运行时仍拥有实际行为。 | -| `setup` | 否 | `object` | 设备发现和设置界面可在不加载插件运行时的情况下检查的低成本设置/新手引导描述符。 | -| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` host 在插件运行时加载之前使用的低成本 QA runner 描述符。 | -| `contracts` | 否 | `object` | 外部凭证钩子、语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页获取、Web 搜索和工具所有权的静态内置能力快照。 | -| `mediaUnderstandingProviderMetadata` | 否 | `Record` | 为 `contracts.mediaUnderstandingProviders` 中声明的提供商 id 提供的低成本媒体理解默认值。 | -| `channelConfigs` | 否 | `Record` | 清单拥有的渠道配置元数据，会在运行时加载之前合并到设备发现和验证界面中。 | -| `skills` | 否 | `string[]` | 要加载的 Skill 目录，相对于插件根目录。 | -| `name` | 否 | `string` | 人类可读的插件名称。 | -| `description` | 否 | `string` | 插件界面中显示的简短摘要。 | -| `version` | 否 | `string` | 信息性的插件版本。 | -| `uiHints` | 否 | `Record` | 配置字段的 UI 标签、占位符和敏感性提示。 | +| `id` | 是 | `string` | 规范插件 id。这是在 `plugins.entries.` 中使用的 id。 | +| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 | +| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略它，或设置任何非 `true` 值，即可让插件默认保持禁用。 | +| `legacyPluginIds` | 否 | `string[]` | 会规范化到此规范插件 id 的旧版 id。 | +| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当凭证、配置或模型引用提到这些提供商 id 时，应自动启用此插件。 | +| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明一个由 `plugins.slots.*` 使用的互斥插件种类。 | +| `channels` | 否 | `string[]` | 此插件拥有的渠道 id。用于设备发现和配置验证。 | +| `providers` | 否 | `string[]` | 此插件拥有的提供商 id。 | +| `providerDiscoveryEntry` | 否 | `string` | 轻量级提供商发现模块路径，相对于插件根目录，用于清单作用域的提供商目录元数据，可在不激活完整插件运行时的情况下加载。 | +| `modelSupport` | 否 | `object` | 清单拥有的简写模型系列元数据，用于在运行时之前自动加载插件。 | +| `modelCatalog` | 否 | `object` | 此插件拥有的提供商的声明式模型目录元数据。这是未来在不加载插件运行时的情况下进行只读列表、新手引导、模型选择器、别名和抑制的控制平面契约。 | +| `modelPricing` | 否 | `object` | 提供商拥有的外部定价查找策略。可用它让本地/自托管提供商退出远程定价目录，或将提供商引用映射到 OpenRouter/LiteLLM 目录 id，而无需在核心中硬编码提供商 id。 | +| `modelIdNormalization` | 否 | `object` | 提供商拥有的模型 id 别名/前缀清理，必须在提供商运行时加载前运行。 | +| `providerEndpoints` | 否 | `object[]` | 清单拥有的端点 host/baseUrl 元数据，用于核心在提供商运行时加载前对提供商路由进行分类。 | +| `providerRequest` | 否 | `object` | 便宜的提供商系列和请求兼容性元数据，供通用请求策略在提供商运行时加载前使用。 | +| `cliBackends` | 否 | `string[]` | 此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 | +| `syntheticAuthRefs` | 否 | `string[]` | 提供商或 CLI 后端引用，其插件拥有的合成凭证钩子应在运行时加载前的冷模型发现期间被探测。 | +| `nonSecretAuthMarkers` | 否 | `string[]` | 内置插件拥有的占位 API key 值，表示非机密的本地、OAuth 或环境凭证状态。 | +| `commandAliases` | 否 | `object[]` | 此插件拥有的命令名称，应在运行时加载前生成具备插件感知能力的配置和 CLI 诊断。 | +| `providerAuthEnvVars` | 否 | `Record` | 已弃用的兼容性环境变量元数据，用于提供商凭证/Status 查找。新插件优先使用 `setup.providers[].envVars`；OpenClaw 在弃用窗口期仍会读取此字段。 | +| `providerAuthAliases` | 否 | `Record` | 应复用另一个提供商 id 进行凭证查找的提供商 id，例如共享基础提供商 API key 和凭证配置文件的编码提供商。 | +| `channelEnvVars` | 否 | `Record` | 便宜的渠道环境变量元数据，OpenClaw 可在不加载插件代码的情况下检查。用于通用启动/配置帮助器应看到的环境变量驱动渠道设置或凭证界面。 | +| `providerAuthChoices` | 否 | `object[]` | 便宜的凭证选择元数据，用于新手引导选择器、首选提供商解析和简单 CLI 标志接线。 | +| `activation` | 否 | `object` | 便宜的激活规划器元数据，用于启动、提供商、命令、渠道、路由和能力触发的加载。仅限元数据；实际行为仍由插件运行时拥有。 | +| `setup` | 否 | `object` | 便宜的设置/新手引导描述符，供发现和设置界面在不加载插件运行时的情况下检查。 | +| `qaRunners` | 否 | `object[]` | 便宜的 QA 运行器描述符，由共享的 `openclaw qa` 宿主在插件运行时加载前使用。 | +| `contracts` | 否 | `object` | 外部凭证钩子、语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、Web 获取、Web 搜索和工具所有权的静态内置能力快照。 | +| `mediaUnderstandingProviderMetadata` | 否 | `Record` | `contracts.mediaUnderstandingProviders` 中声明的提供商 id 的便宜媒体理解默认值。 | +| `channelConfigs` | 否 | `Record` | 清单拥有的渠道配置元数据，在运行时加载前合并到发现和验证界面中。 | +| `skills` | 否 | `string[]` | 要加载的 Skill 目录，相对于插件根目录。 | +| `name` | 否 | `string` | 人类可读的插件名称。 | +| `description` | 否 | `string` | 显示在插件界面中的简短摘要。 | +| `version` | 否 | `string` | 信息性插件版本。 | +| `uiHints` | 否 | `Record` | 配置字段的 UI 标签、占位符和敏感性提示。 | -## `providerAuthChoices` 参考 +## providerAuthChoices 参考 每个 `providerAuthChoices` 条目描述一个新手引导或凭证选择。 -OpenClaw 会在提供商运行时加载之前读取此项。 -提供商设置列表使用这些清单选择、由描述符派生的设置 -选择，以及安装目录元数据，而无需加载提供商运行时。 +OpenClaw 会在提供商运行时加载前读取它。 +提供商设置列表会使用这些清单选择、从描述符派生的设置选择， +以及安装目录元数据，而无需加载提供商运行时。 -| 字段 | 必填 | 类型 | 含义 | -| --------------------- | ---- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `provider` | 是 | `string` | 此选项所属的提供商 id。 | -| `method` | 是 | `string` | 要分派到的凭证方法 id。 | -| `choiceId` | 是 | `string` | 新手引导和 CLI 流程使用的稳定凭证选项 id。 | -| `choiceLabel` | 否 | `string` | 面向用户的标签。如果省略，OpenClaw 会回退到 `choiceId`。 | -| `choiceHint` | 否 | `string` | 选择器的简短辅助文本。 | -| `assistantPriority` | 否 | `number` | 在智能体驱动的交互式选择器中，值越低排序越靠前。 | -| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 从智能体选择器中隐藏该选项，同时仍允许手动 CLI 选择。 | -| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选项的旧版选项 id。 | -| `groupId` | 否 | `string` | 用于分组相关选项的可选分组 id。 | -| `groupLabel` | 否 | `string` | 该分组面向用户的标签。 | -| `groupHint` | 否 | `string` | 分组的简短辅助文本。 | -| `optionKey` | 否 | `string` | 简单单标志凭证流程的内部选项键。 | -| `cliFlag` | 否 | `string` | CLI 标志名称，例如 `--openrouter-api-key`。 | -| `cliOption` | 否 | `string` | 完整的 CLI 选项形态，例如 `--openrouter-api-key `。 | -| `cliDescription` | 否 | `string` | CLI 帮助中使用的描述。 | -| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选项应出现在哪些新手引导界面中。如果省略，默认值为 `["text-inference"]`。 | +| 字段 | 必需 | 类型 | 含义 | +| --------------------- | ---- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `provider` | 是 | `string` | 此选择所属的提供商 id。 | +| `method` | 是 | `string` | 要分派到的身份验证方法 id。 | +| `choiceId` | 是 | `string` | 新手引导和 CLI 流程使用的稳定身份验证选择 id。 | +| `choiceLabel` | 否 | `string` | 面向用户的标签。如果省略，OpenClaw 会回退到 `choiceId`。 | +| `choiceHint` | 否 | `string` | 选择器的简短辅助文本。 | +| `assistantPriority` | 否 | `number` | 在助手驱动的交互式选择器中，值越低排序越靠前。 | +| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 从助手选择器中隐藏该选择，同时仍允许手动 CLI 选择。 | +| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选择的旧版选择 id。 | +| `groupId` | 否 | `string` | 用于对相关选择分组的可选组 id。 | +| `groupLabel` | 否 | `string` | 该组面向用户的标签。 | +| `groupHint` | 否 | `string` | 该组的简短辅助文本。 | +| `optionKey` | 否 | `string` | 简单单标志身份验证流程的内部选项键。 | +| `cliFlag` | 否 | `string` | CLI 标志名称，例如 `--openrouter-api-key`。 | +| `cliOption` | 否 | `string` | 完整 CLI 选项形式，例如 `--openrouter-api-key `。 | +| `cliDescription` | 否 | `string` | CLI 帮助中使用的描述。 | +| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选择应出现在哪些新手引导表面中。如果省略，默认为 `["text-inference"]`。 | ## commandAliases 参考 -当某个插件拥有一个运行时命令名称，而用户可能会错误地将其放入 -`plugins.allow`，或尝试将其作为根 CLI 命令运行时，请使用 `commandAliases`。 -OpenClaw 使用此元数据进行诊断，而无需导入插件运行时代码。 +当插件拥有用户可能会误放进 `plugins.allow`，或尝试作为根 CLI 命令运行的运行时命令名称时，使用 `commandAliases`。OpenClaw 使用此元数据进行诊断，而无需导入插件运行时代码。 ```json { @@ -231,41 +225,26 @@ OpenClaw 使用此元数据进行诊断，而无需导入插件运行时代码 } ``` -| 字段 | 必填 | 类型 | 含义 | +| 字段 | 必需 | 类型 | 含义 | | ------------ | ---- | ----------------- | --------------------------------------------------------------------- | | `name` | 是 | `string` | 属于此插件的命令名称。 | -| `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天斜杠命令，而不是根 CLI 命令。 | -| `cliCommand` | 否 | `string` | 如果存在相关根 CLI 命令，则建议用于 CLI 操作的命令。 | +| `kind` | 否 | `"runtime-slash"` | 将别名标记为聊天斜杠命令，而不是根 CLI 命令。 | +| `cliCommand` | 否 | `string` | 如果存在，用于建议 CLI 操作的相关根 CLI 命令。 | ## activation 参考 -当插件可以低成本声明哪些控制平面事件应将其包含在激活/加载计划中时，请使用 -`activation`。 +当插件可以低成本声明哪些控制平面事件应将其纳入激活/加载计划时，使用 `activation`。 -此块是规划器元数据，不是生命周期 API。它不会注册运行时行为，不会替代 -`register(...)`，也不承诺插件代码已经执行。激活规划器会使用这些字段，在回退到现有清单所有权元数据之前缩小候选插件范围，例如 -`providers`、`channels`、`commandAliases`、`setup.providers`、 -`contracts.tools` 和钩子。 +此块是规划器元数据，而不是生命周期 API。它不会注册运行时行为，不会替代 `register(...)`，也不承诺插件代码已经执行。激活规划器使用这些字段，在回退到现有清单所有权元数据（例如 `providers`、`channels`、`commandAliases`、`setup.providers`、`contracts.tools` 和钩子）之前，缩小候选插件范围。 -优先使用已经描述所有权的最窄元数据。当 `providers`、`channels`、 -`commandAliases`、设置描述符或 `contracts` 能表达这种关系时，请使用这些字段。将 -`activation` 用于无法通过这些所有权字段表示的额外规划器提示。 -对于 CLI 运行时别名，例如 `claude-cli`、`codex-cli` 或 `google-gemini-cli`，请使用顶层 -`cliBackends`；`activation.onAgentHarnesses` 仅用于尚无所有权字段的嵌入式智能体 harness id。 +优先使用已经描述所有权的最窄元数据。当 `providers`、`channels`、`commandAliases`、设置描述符或 `contracts` 能表达这种关系时，使用这些字段。将 `activation` 用于无法由这些所有权字段表示的额外规划器提示。 +将顶层 `cliBackends` 用于 CLI 运行时别名，例如 `claude-cli`、`codex-cli` 或 `google-gemini-cli`；`activation.onAgentHarnesses` 仅用于尚无所有权字段的嵌入式 agent harness id。 -此块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、 -`setupEntry` 或其他运行时/插件入口点。当前使用者会将其作为提示，在更广泛的插件加载之前缩小范围，因此缺少激活元数据通常只会影响性能；只要旧版清单所有权回退仍然存在，就不应改变正确性。 +此块仅是元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时/插件入口点。当前消费者会在更广泛的插件加载前将其用作缩小范围的提示，因此缺少 activation 元数据通常只影响性能；只要旧版清单所有权回退仍然存在，就不应改变正确性。 -随着 OpenClaw 逐步弃用隐式启动导入，每个插件都应有意设置 -`activation.onStartup`。只有当插件必须在 Gateway 网关启动期间运行时，才将其设为 -`true`。当插件在启动时处于惰性状态，并且只应由更窄的触发器加载时，将其设为 -`false`。省略 `onStartup` 会为没有静态能力元数据的插件保留已弃用的旧版隐式启动 sidecar 回退；未来版本可能会停止在启动时加载这些插件，除非它们声明 -`activation.onStartup: true`。当插件仍依赖该回退时，插件 Status 和兼容性报告会显示 -`legacy-implicit-startup-sidecar` 警告。 +随着 OpenClaw 摆脱隐式启动导入，每个插件都应有意设置 `activation.onStartup`。仅当插件必须在 Gateway 网关启动期间运行时，才将其设为 `true`。当插件在启动时处于惰性状态，并且应仅由更窄的触发器加载时，将其设为 `false`。省略 `onStartup` 会保留已弃用的旧版隐式启动 sidecar 回退，用于没有静态能力元数据的插件；未来版本可能会停止在启动时加载这些插件，除非它们声明 `activation.onStartup: true`。当插件仍依赖该回退时，插件 Status 和兼容性报告会以 `legacy-implicit-startup-sidecar` 发出警告。 -对于迁移测试，设置 -`OPENCLAW_DISABLE_LEGACY_IMPLICIT_STARTUP_SIDECARS=1` 可仅禁用该已弃用的回退。此选择加入模式不会阻止显式 -`activation.onStartup: true` 的插件，也不会阻止由渠道、配置、智能体 harness、内存或其他更窄激活触发器加载的插件。 +对于迁移测试，设置 `OPENCLAW_DISABLE_LEGACY_IMPLICIT_STARTUP_SIDECARS=1` 以仅禁用该已弃用的回退。此选择加入模式不会阻止显式 `activation.onStartup: true` 插件，也不会阻止由渠道、配置、agent harness、内存或其他更窄激活触发器加载的插件。 ```json { @@ -281,38 +260,31 @@ OpenClaw 使用此元数据进行诊断，而无需导入插件运行时代码 } ``` -| 字段 | 必填 | 类型 | 含义 | -| ------------------ | ---- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `onStartup` | 否 | `boolean` | 显式 Gateway 网关启动激活。每个插件都应设置此项。`true` 会在启动期间导入插件；`false` 会退出已弃用的隐式 sidecar 启动回退，除非另一个匹配的触发器需要加载。 | -| `onProviders` | 否 | `string[]` | 应将此插件包含在激活/加载计划中的提供商 id。 | -| `onAgentHarnesses` | 否 | `string[]` | 应将此插件包含在激活/加载计划中的嵌入式智能体 harness 运行时 id。对于 CLI 后端别名，请使用顶层 `cliBackends`。 | -| `onCommands` | 否 | `string[]` | 应将此插件包含在激活/加载计划中的命令 id。 | -| `onChannels` | 否 | `string[]` | 应将此插件包含在激活/加载计划中的渠道 id。 | -| `onRoutes` | 否 | `string[]` | 应将此插件包含在激活/加载计划中的路由类型。 | -| `onConfigPaths` | 否 | `string[]` | 当路径存在且未被显式禁用时，应将此插件包含在启动/加载计划中的相对根目录配置路径。 | -| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的宽泛能力提示。可行时优先使用更窄的字段。 | +| 字段 | 必需 | 类型 | 含义 | +| ------------------ | ---- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `onStartup` | 否 | `boolean` | 显式 Gateway 网关启动激活。每个插件都应设置此字段。`true` 会在启动期间导入插件；`false` 会退出已弃用的隐式 sidecar 启动回退，除非另一个匹配的触发器要求加载。 | +| `onProviders` | 否 | `string[]` | 应将此插件纳入激活/加载计划的提供商 id。 | +| `onAgentHarnesses` | 否 | `string[]` | 应将此插件纳入激活/加载计划的嵌入式 agent harness 运行时 id。对 CLI 后端别名使用顶层 `cliBackends`。 | +| `onCommands` | 否 | `string[]` | 应将此插件纳入激活/加载计划的命令 id。 | +| `onChannels` | 否 | `string[]` | 应将此插件纳入激活/加载计划的渠道 id。 | +| `onRoutes` | 否 | `string[]` | 应将此插件纳入激活/加载计划的路由种类。 | +| `onConfigPaths` | 否 | `string[]` | 当路径存在且未被显式禁用时，应将此插件纳入启动/加载计划的根相对配置路径。 | +| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的宽泛能力提示。尽可能优先使用更窄的字段。 | -当前实时使用者： +当前实时消费者： - Gateway 网关启动规划使用 `activation.onStartup` 进行显式启动导入，并退出已弃用的隐式 sidecar 启动回退 -- 命令触发的 CLI 规划会回退到旧版 - `commandAliases[].cliCommand` 或 `commandAliases[].name` -- 智能体运行时启动规划会将 `activation.onAgentHarnesses` 用于嵌入式 harness，并将顶层 `cliBackends[]` 用于 CLI 运行时别名 -- 渠道触发的设置/渠道规划在缺少显式渠道激活元数据时，会回退到旧版 `channels[]` - 所有权 -- 启动插件规划会将 `activation.onConfigPaths` 用于非渠道根配置界面，例如内置浏览器插件的 `browser` 块 -- 提供商触发的设置/运行时规划在缺少显式提供商激活元数据时，会回退到旧版 - `providers[]` 和顶层 `cliBackends[]` 所有权 +- 由命令触发的 CLI 规划会回退到旧版 `commandAliases[].cliCommand` 或 `commandAliases[].name` +- agent runtime 启动规划对嵌入式 harness 使用 `activation.onAgentHarnesses`，并对 CLI 运行时别名使用顶层 `cliBackends[]` +- 由渠道触发的设置/渠道规划在缺少显式渠道 activation 元数据时，会回退到旧版 `channels[]` 所有权 +- 启动插件规划对非渠道根配置表面使用 `activation.onConfigPaths`，例如内置浏览器插件的 `browser` 块 +- 由提供商触发的设置/运行时规划在缺少显式提供商 activation 元数据时，会回退到旧版 `providers[]` 和顶层 `cliBackends[]` 所有权 -规划器诊断可以区分显式激活提示和清单所有权回退。例如，`activation-command-hint` 表示 -`activation.onCommands` 匹配，而 `manifest-command-alias` 表示规划器改用了 -`commandAliases` 所有权。这些原因标签用于主机诊断和测试；插件作者应继续声明最能描述所有权的元数据。 +规划器诊断可以区分显式激活提示和清单所有权回退。例如，`activation-command-hint` 表示 `activation.onCommands` 匹配，而 `manifest-command-alias` 表示规划器改用 `commandAliases` 所有权。这些原因标签用于主机诊断和测试；插件作者应继续声明最能描述所有权的元数据。 ## qaRunners 参考 -当插件在共享的 `openclaw qa` 根命令下贡献一个或多个传输运行器时，请使用 -`qaRunners`。保持此元数据低成本且静态；插件运行时仍通过轻量级 -`runtime-api.ts` 界面拥有实际 CLI 注册，该界面导出 `qaRunnerCliRegistrations`。 +当插件在共享的 `openclaw qa` 根之下贡献一个或多个传输运行器时，使用 `qaRunners`。保持此元数据低成本且静态；插件运行时仍通过导出 `qaRunnerCliRegistrations` 的轻量级 `runtime-api.ts` 表面拥有实际 CLI 注册。 ```json { @@ -325,14 +297,14 @@ OpenClaw 使用此元数据进行诊断，而无需导入插件运行时代码 } ``` -| 字段 | 必填 | 类型 | 含义 | -| ------------- | ---- | -------- | --------------------------------------------------------------- | -| `commandName` | 是 | `string` | 挂载在 `openclaw qa` 下的子命令，例如 `matrix`。 | -| `description` | 否 | `string` | 当共享宿主需要存根命令时使用的回退帮助文本。 | +| 字段 | 必需 | 类型 | 含义 | +| ------------- | ---- | -------- | ------------------------------------------------------------------ | +| `commandName` | 是 | `string` | 挂载在 `openclaw qa` 下的子命令，例如 `matrix`。 | +| `description` | 否 | `string` | 当共享宿主需要存根命令时使用的回退帮助文本。 | -## setup 参考 +## 设置参考 -当设置和新手引导界面在运行时加载前需要低成本的插件自有元数据时，使用 `setup`。 +当设置和新手引导界面需要在运行时加载前获取低成本的插件自有元数据时，使用 `setup`。 ```json { @@ -351,40 +323,40 @@ OpenClaw 使用此元数据进行诊断，而无需导入插件运行时代码 } ``` -顶层 `cliBackends` 仍然有效，并会继续描述 CLI 推理后端。`setup.cliBackends` 是面向控制平面/设置流程的设置专用描述符界面，这些流程应保持仅元数据。 +顶层 `cliBackends` 仍然有效，并继续描述 CLI 推断后端。`setup.cliBackends` 是用于控制平面/设置流程的设置专用描述符界面，这些流程应保持仅元数据。 -存在时，`setup.providers` 和 `setup.cliBackends` 是设置设备发现的首选描述符优先查找界面。如果描述符只缩小候选插件范围，而设置仍需要更丰富的设置时运行时钩子，请设置 `requiresRuntime: true`，并保留 `setup-api` 作为回退执行路径。 +存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现首选的描述符优先查找界面。如果描述符只是缩小候选插件范围，而设置仍需要更丰富的设置时运行时钩子，请设置 `requiresRuntime: true`，并保留 `setup-api` 作为回退执行路径。 -OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.providers[].envVars`。`providerAuthEnvVars` 在弃用窗口期间仍通过兼容适配器受支持，但仍使用它的非内置插件会收到清单诊断。新插件应将设置/Status 环境元数据放在 `setup.providers[].envVars` 上。 +OpenClaw 还会在通用提供商鉴权和环境变量查找中包含 `setup.providers[].envVars`。`providerAuthEnvVars` 在弃用窗口期间仍通过兼容适配器受支持，但仍使用它的非内置插件会收到清单诊断。新插件应将设置/Status 环境元数据放在 `setup.providers[].envVars` 上。 -当没有可用的设置入口，或者 `setup.requiresRuntime: false` 声明不需要设置运行时时，OpenClaw 也可以从 `setup.providers[].authMethods` 派生简单的设置选项。对于自定义标签、CLI 标志、新手引导范围和助手元数据，显式的 `providerAuthChoices` 条目仍然优先。 +当没有可用的设置入口，或 `setup.requiresRuntime: false` 声明不需要设置运行时时，OpenClaw 也可以从 `setup.providers[].authMethods` 派生简单的设置选项。显式的 `providerAuthChoices` 条目仍优先用于自定义标签、CLI 标志、新手引导范围和助手元数据。 -仅当这些描述符足以支撑设置界面时，才设置 `requiresRuntime: false`。OpenClaw 会将显式的 `false` 视为仅描述符契约，并且不会为设置查找执行 `setup-api` 或 `openclaw.setupEntry`。如果仅描述符插件仍随附这些设置运行时入口之一，OpenClaw 会报告一条增量诊断并继续忽略它。省略 `requiresRuntime` 会保留旧版回退行为，以免已添加描述符但未添加该标志的现有插件中断。 +仅当这些描述符足以支撑设置界面时，才设置 `requiresRuntime: false`。OpenClaw 将显式的 `false` 视为仅描述符契约，不会为设置查找执行 `setup-api` 或 `openclaw.setupEntry`。如果仅描述符插件仍提供这些设置运行时入口之一，OpenClaw 会报告一条追加诊断并继续忽略它。省略 `requiresRuntime` 会保留旧版回退行为，因此已添加描述符但未添加该标志的现有插件不会中断。 -由于设置查找可以执行插件自有的 `setup-api` 代码，规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在已发现插件之间保持唯一。所有权不明确时会关闭失败，而不是从设备发现顺序中选择胜者。 +由于设置查找可以执行插件自有的 `setup-api` 代码，规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在已发现插件之间保持唯一。所有权存在歧义时会关闭失败，而不是按发现顺序选择胜者。 -当设置运行时确实执行时，如果 `setup-api` 注册的提供商或 CLI 后端未由清单描述符声明，或者描述符没有匹配的运行时注册，设置注册表诊断会报告描述符漂移。这些诊断是增量的，不会拒绝旧版插件。 +当设置运行时确实执行时，如果 `setup-api` 注册了清单描述符未声明的提供商或 CLI 后端，或某个描述符没有匹配的运行时注册，设置注册表诊断会报告描述符漂移。这些诊断是追加式的，不会拒绝旧版插件。 -### setup.providers 参考 +### `setup.providers` 参考 -| 字段 | 必填 | 类型 | 含义 | +| 字段 | 必需 | 类型 | 含义 | | ------------- | ---- | ---------- | --------------------------------------------------------------------------- | | `id` | 是 | `string` | 在设置或新手引导期间暴露的提供商 id。保持规范化 id 全局唯一。 | -| `authMethods` | 否 | `string[]` | 此提供商在不加载完整运行时的情况下支持的设置/凭证方法 id。 | +| `authMethods` | 否 | `string[]` | 此提供商在不加载完整运行时的情况下支持的设置/鉴权方法 id。 | | `envVars` | 否 | `string[]` | 通用设置/Status 界面可在插件运行时加载前检查的环境变量。 | -### setup 字段 +### `setup` 字段 -| 字段 | 必填 | 类型 | 含义 | -| ------------------ | ---- | ---------- | ---------------------------------------------------------------------------------------- | -| `providers` | 否 | `object[]` | 在设置和新手引导期间暴露的提供商设置描述符。 | -| `cliBackends` | 否 | `string[]` | 用于描述符优先设置查找的设置时后端 id。保持规范化 id 全局唯一。 | -| `configMigrations` | 否 | `string[]` | 此插件的设置界面拥有的配置迁移 id。 | -| `requiresRuntime` | 否 | `boolean` | 设置是否仍需要在描述符查找后执行 `setup-api`。 | +| 字段 | 必需 | 类型 | 含义 | +| ------------------ | ---- | ---------- | ------------------------------------------------------------------------------------------ | +| `providers` | 否 | `object[]` | 在设置和新手引导期间暴露的提供商设置描述符。 | +| `cliBackends` | 否 | `string[]` | 用于描述符优先设置查找的设置时后端 id。保持规范化 id 全局唯一。 | +| `configMigrations` | 否 | `string[]` | 由此插件的设置界面拥有的配置迁移 id。 | +| `requiresRuntime` | 否 | `boolean` | 设置在描述符查找后是否仍需要执行 `setup-api`。 | -## uiHints 参考 +## `uiHints` 参考 -`uiHints` 是从配置字段名称到小型渲染提示的映射。 +`uiHints` 是从配置字段名到小型渲染提示的映射。 ```json { @@ -407,12 +379,12 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro | `help` | `string` | 简短帮助文本。 | | `tags` | `string[]` | 可选 UI 标签。 | | `advanced` | `boolean` | 将字段标记为高级字段。 | -| `sensitive` | `boolean` | 将字段标记为密钥或敏感信息。 | +| `sensitive` | `boolean` | 将字段标记为秘密或敏感字段。 | | `placeholder` | `string` | 表单输入的占位文本。 | -## contracts 参考 +## `contracts` 参考 -仅将 `contracts` 用于 OpenClaw 可在不导入插件运行时的情况下读取的静态能力所有权元数据。 +仅将 `contracts` 用于 OpenClaw 可以在不导入插件运行时的情况下读取的静态能力所有权元数据。 ```json { @@ -436,32 +408,32 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro 每个列表都是可选的： -| 字段 | 类型 | 含义 | -| -------------------------------- | ---------- | -------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Codex 应用服务器插件工厂 id，目前为 `codex-app-server`。 | -| `agentToolResultMiddleware` | `string[]` | 内置插件可为其注册工具结果中间件的运行时 id。 | -| `externalAuthProviders` | `string[]` | 此插件拥有其外部凭证配置文件钩子的提供商 id。 | -| `speechProviders` | `string[]` | 此插件拥有的语音提供商 id。 | -| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转录提供商 id。 | -| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音提供商 id。 | -| `memoryEmbeddingProviders` | `string[]` | 此插件拥有的记忆嵌入提供商 id。 | -| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解提供商 id。 | -| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成提供商 id。 | -| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成提供商 id。 | -| `webFetchProviders` | `string[]` | 此插件拥有的 Web 抓取提供商 id。 | -| `webSearchProviders` | `string[]` | 此插件拥有的 Web 搜索提供商 id。 | -| `migrationProviders` | `string[]` | 此插件为 `openclaw migrate` 拥有的导入提供商 id。 | -| `tools` | `string[]` | 此插件为内置契约检查拥有的 Agent 工具名称。 | +| 字段 | 类型 | 含义 | +| -------------------------------- | ---------- | --------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | Codex 应用服务器扩展工厂 id，目前为 `codex-app-server`。 | +| `agentToolResultMiddleware` | `string[]` | 内置插件可为其注册工具结果中间件的运行时 id。 | +| `externalAuthProviders` | `string[]` | 此插件拥有其外部鉴权配置文件钩子的提供商 id。 | +| `speechProviders` | `string[]` | 此插件拥有的语音提供商 id。 | +| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转写提供商 id。 | +| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音提供商 id。 | +| `memoryEmbeddingProviders` | `string[]` | 此插件拥有的 Memory 嵌入提供商 id。 | +| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解提供商 id。 | +| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成提供商 id。 | +| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成提供商 id。 | +| `webFetchProviders` | `string[]` | 此插件拥有的 Web 抓取提供商 id。 | +| `webSearchProviders` | `string[]` | 此插件拥有的 Web 搜索提供商 id。 | +| `migrationProviders` | `string[]` | 此插件为 `openclaw migrate` 拥有的导入提供商 id。 | +| `tools` | `string[]` | 此插件为内置契约检查拥有的 Agent 工具名称。 | -`contracts.embeddedExtensionFactories` 保留用于内置的仅 Codex 应用服务器插件工厂。内置工具结果转换应改为声明 `contracts.agentToolResultMiddleware`，并使用 `api.registerAgentToolResultMiddleware(...)` 注册。外部插件无法注册工具结果中间件，因为该接缝可以在模型看到之前重写高信任度工具输出。 +`contracts.embeddedExtensionFactories` 保留给内置的仅 Codex 应用服务器扩展工厂。内置工具结果转换应声明 `contracts.agentToolResultMiddleware`，并改为使用 `api.registerAgentToolResultMiddleware(...)` 注册。外部插件不能注册工具结果中间件，因为该接缝可以在模型看到高信任工具输出之前重写它。 -实现 `resolveExternalAuthProfiles` 的提供商插件应声明 `contracts.externalAuthProviders`。没有该声明的插件仍会通过已弃用的兼容回退运行，但该回退更慢，并将在迁移窗口后移除。 +实现 `resolveExternalAuthProfiles` 的提供商插件应声明 `contracts.externalAuthProviders`。没有声明的插件仍会通过已弃用的兼容回退运行，但该回退更慢，并将在迁移窗口后移除。 -内置记忆嵌入提供商应为它们暴露的每个适配器 id 声明 `contracts.memoryEmbeddingProviders`，包括 `local` 等内置适配器。独立 CLI 路径使用此清单契约，在完整 Gateway 网关运行时注册提供商之前仅加载拥有该能力的插件。 +内置 Memory 嵌入提供商应为它暴露的每个适配器 id 声明 `contracts.memoryEmbeddingProviders`，包括 `local` 等内置适配器。独立 CLI 路径会使用此清单契约，在完整 Gateway 网关运行时注册提供商之前，仅加载拥有该能力的插件。 -## mediaUnderstandingProviderMetadata 参考 +## `mediaUnderstandingProviderMetadata` 参考 -当媒体理解提供商具有默认模型、自动凭证回退优先级，或通用核心帮助程序在运行时加载前需要的原生文档支持时，使用 `mediaUnderstandingProviderMetadata`。键还必须在 `contracts.mediaUnderstandingProviders` 中声明。 +当媒体理解提供商具有默认模型、自动鉴权回退优先级，或通用核心帮助程序在运行时加载前需要的原生文档支持时，使用 `mediaUnderstandingProviderMetadata`。键也必须在 `contracts.mediaUnderstandingProviders` 中声明。 ```json { @@ -486,34 +458,34 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro 每个提供商条目可以包含： -| 字段 | 类型 | 含义 | -| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | 此提供商暴露的媒体能力。 | -| `defaultModels` | `Record` | 当配置未指定模型时使用的能力到模型默认值。 | -| `autoPriority` | `Record` | 数字越小，在基于凭证的自动提供商回退中排序越靠前。 | -| `nativeDocumentInputs` | `"pdf"[]` | 提供商支持的原生文档输入。 | +| 字段 | 类型 | 含义 | +| ---------------------- | ----------------------------------- | -------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | 此提供商暴露的媒体能力。 | +| `defaultModels` | `Record` | 配置未指定模型时使用的能力到模型默认值。 | +| `autoPriority` | `Record` | 数值越小，在基于凭证的自动提供商回退中排序越靠前。 | +| `nativeDocumentInputs` | `"pdf"[]` | 提供商支持的原生文档输入。 | -## channelConfigs 参考 +## `channelConfigs` 参考 -当渠道插件在运行时加载前需要低成本配置元数据时，使用 `channelConfigs`。当没有可用的设置入口，或者 `setup.requiresRuntime: false` 声明不需要设置运行时时，只读渠道设置/Status 设备发现可以直接对已配置的外部渠道使用此元数据。 +当渠道插件需要在运行时加载前获取低成本配置元数据时，使用 `channelConfigs`。当没有可用设置入口，或 `setup.requiresRuntime: false` 声明不需要设置运行时时，只读渠道设置/Status 发现可以直接为已配置的外部渠道使用此元数据。 -`channelConfigs` 是插件清单元数据，不是新的顶层用户配置段。用户仍在 `channels.` 下配置渠道实例。OpenClaw 会读取清单元数据，以便在插件运行时代码执行前判断哪个插件拥有该已配置渠道。 +`channelConfigs` 是插件清单元数据，不是新的顶层用户配置段。用户仍在 `channels.` 下配置渠道实例。OpenClaw 会读取清单元数据，以便在插件运行时代码执行前决定哪个插件拥有该已配置渠道。 -对于渠道插件，`configSchema` 和 `channelConfigs` 描述的是不同路径： +对于渠道插件，`configSchema` 和 `channelConfigs` 描述不同路径： - `configSchema` 验证 `plugins.entries..config` - `channelConfigs..schema` 验证 `channels.` 非内置插件如果声明了 `channels[]`，也应声明匹配的 -`channelConfigs` 条目。否则，OpenClaw 仍可加载插件，但 -冷路径配置 schema、设置和 Control UI 界面在插件运行时执行之前无法知道 -渠道所属选项的形状。 +`channelConfigs` 条目。没有这些条目，OpenClaw 仍然可以加载该插件，但 +冷路径配置 schema、设置和控制 UI 界面无法在插件运行时执行前知道 +渠道拥有的选项形状。 `channelConfigs..commands.nativeCommandsAutoEnabled` 和 -`nativeSkillsAutoEnabled` 可以为命令配置检查声明静态 `auto` 默认值， -这些检查会在渠道运行时加载前运行。内置渠道也可以通过 -`package.json#openclaw.channel.commands` 发布相同默认值，并与其他 -包所属的渠道目录元数据并列。 +`nativeSkillsAutoEnabled` 可以为在渠道运行时加载前运行的命令配置 +检查声明静态 `auto` 默认值。内置渠道也可以通过 +`package.json#openclaw.channel.commands` 与其他由 package 拥有的渠道目录元数据一起发布 +相同默认值。 ```json { @@ -546,20 +518,20 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro 每个渠道条目可以包含： -| 字段 | 类型 | 含义 | -| ------------- | ------------------------ | -------------------------------------------------------------------------------------- | -| `schema` | `object` | `channels.` 的 JSON Schema。每个已声明的渠道配置条目都必须提供。 | -| `uiHints` | `Record` | 该渠道配置区段的可选 UI 标签、占位符、敏感信息提示。 | -| `label` | `string` | 当运行时元数据尚未就绪时，合并到选择器和检查界面的渠道标签。 | -| `description` | `string` | 用于检查和目录界面的简短渠道描述。 | -| `commands` | `object` | 用于运行时前配置检查的静态原生命令和原生 skill 自动默认值。 | -| `preferOver` | `string[]` | 此渠道在选择界面中应优先于的旧版或低优先级插件 ID。 | +| 字段 | 类型 | 含义 | +| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ | +| `schema` | `object` | `channels.` 的 JSON Schema。每个已声明的渠道配置条目都必须提供。 | +| `uiHints` | `Record` | 该渠道配置部分的可选 UI 标签、占位符和敏感提示。 | +| `label` | `string` | 当运行时元数据尚未就绪时，合并到选择器和检查界面的渠道标签。 | +| `description` | `string` | 用于检查和目录界面的简短渠道描述。 | +| `commands` | `object` | 用于运行时前配置检查的静态原生命令和原生 Skills 自动默认值。 | +| `preferOver` | `string[]` | 此渠道在选择界面中应优先于的旧版或较低优先级插件 ID。 | ### 替换另一个渠道插件 -当你的插件是某个渠道 ID 的首选所有者，而另一个插件也能提供该渠道时， -使用 `preferOver`。常见场景包括重命名后的插件 ID、取代内置插件的 -独立插件，或为了配置兼容性而保留相同渠道 ID 的维护分支。 +当你的插件是某个渠道 ID 的首选拥有者，而另一个插件也可以提供该渠道时， +请使用 `preferOver`。常见场景包括重命名的插件 ID、取代内置插件的 +独立插件，或为了配置兼容性而保留相同渠道 ID 的维护版 fork。 ```json { @@ -580,20 +552,20 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro } ``` -配置了 `channels.chat` 时，OpenClaw 会同时考虑渠道 ID 和 -首选插件 ID。如果低优先级插件只是因为它是内置插件或默认启用而被选中， -OpenClaw 会在有效运行时配置中禁用它，这样就只有一个插件拥有该渠道及其工具。 -显式用户选择仍然优先：如果用户显式启用两个插件，OpenClaw 会保留该选择， -并报告重复的渠道/工具诊断，而不是静默更改所请求的插件集合。 +配置了 `channels.chat` 时，OpenClaw 会同时考虑渠道 ID 和首选插件 ID。 +如果较低优先级插件只是因为它是内置插件或默认启用而被选中，OpenClaw 会在有效 +运行时配置中禁用它，以便由一个插件拥有该渠道及其工具。显式用户选择 +仍然优先：如果用户显式启用了两个插件，OpenClaw 会保留该选择，并报告重复的渠道/工具诊断， +而不是静默更改请求的插件集。 -请将 `preferOver` 限定在确实能提供相同渠道的插件 ID 范围内。 +请将 `preferOver` 限定在确实可以提供相同渠道的插件 ID 上。 它不是通用优先级字段，也不会重命名用户配置键。 ## modelSupport 参考 当 OpenClaw 应在插件运行时加载前，根据 `gpt-5.5` 或 -`claude-sonnet-4.6` 这样的简写模型 ID 推断你的提供商插件时， -使用 `modelSupport`。 +`claude-sonnet-4.6` 这类简写模型 ID 推断你的提供商插件时，请使用 +`modelSupport`。 ```json { @@ -606,24 +578,24 @@ OpenClaw 会在有效运行时配置中禁用它，这样就只有一个插件 OpenClaw 会应用以下优先级： -- 显式 `provider/model` 引用使用拥有方 `providers` manifest 元数据 +- 显式 `provider/model` 引用使用所属的 `providers` 清单元数据 - `modelPatterns` 优先于 `modelPrefixes` -- 如果一个非内置插件和一个内置插件都匹配，则非内置插件胜出 +- 如果一个非内置插件和一个内置插件都匹配，则非内置插件获胜 - 其余歧义会被忽略，直到用户或配置指定提供商 字段： -| 字段 | 类型 | 含义 | -| --------------- | ---------- | ------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | 使用 `startsWith` 与简写模型 ID 匹配的前缀。 | -| `modelPatterns` | `string[]` | 在移除 profile 后缀后，与简写模型 ID 匹配的正则表达式源码。 | +| 字段 | 类型 | 含义 | +| --------------- | ---------- | ------------------------------------------------------------------------------ | +| `modelPrefixes` | `string[]` | 使用 `startsWith` 与简写模型 ID 匹配的前缀。 | +| `modelPatterns` | `string[]` | 在移除 profile 后缀后，与简写模型 ID 匹配的正则表达式源。 | ## modelCatalog 参考 -当 OpenClaw 应在加载插件运行时前知道提供商模型元数据时，使用 -`modelCatalog`。这是 manifest 所拥有的来源，用于固定目录行、提供商别名、 -抑制规则和发现模式。运行时刷新仍然属于提供商运行时代码，但 manifest 会告诉 -core 何时需要运行时。 +当 OpenClaw 应在加载插件运行时之前知道提供商模型元数据时，请使用 +`modelCatalog`。这是清单拥有的来源，用于固定目录行、提供商别名、 +抑制规则和发现模式。运行时刷新仍属于提供商运行时代码，但清单会告诉核心何时 +需要运行时。 ```json { @@ -676,73 +648,65 @@ core 何时需要运行时。 | 字段 | 类型 | 含义 | | -------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `providers` | `Record` | 此插件所拥有的提供商 ID 的目录行。键也应出现在顶层 `providers` 中。 | -| `aliases` | `Record` | 在目录或抑制规划中应解析到所属提供商的提供商别名。 | -| `suppressions` | `object[]` | 此插件因提供商特定原因而抑制的、来自另一个来源的模型行。 | -| `discovery` | `Record` | 提供商目录是可以从 manifest 元数据读取、刷新到缓存，还是需要运行时。 | +| `providers` | `Record` | 此插件拥有的提供商 ID 的目录行。键也应出现在顶层 `providers` 中。 | +| `aliases` | `Record` | 应解析为所拥有提供商的提供商别名，用于目录或抑制规划。 | +| `suppressions` | `object[]` | 此插件因提供商特定原因而抑制的来自其他来源的模型行。 | +| `discovery` | `Record` | 提供商目录是否可从清单元数据读取、刷新到缓存，或需要运行时。 | `aliases` 会参与模型目录规划中的提供商所有权查找。 -别名目标必须是同一插件拥有的顶层提供商。当按提供商过滤的列表使用别名时， -OpenClaw 可以读取所属 manifest，并在不加载提供商运行时的情况下应用别名 API/base URL 覆盖。 +别名目标必须是同一插件拥有的顶层提供商。当使用别名的提供商过滤列表时， +OpenClaw 可以读取所属清单，并应用别名 API/base URL 覆盖，而无需加载提供商运行时。 -`suppressions` 取代旧的提供商运行时 `suppressBuiltInModel` 钩子。 -仅当提供商由该插件拥有，或声明为 `modelCatalog.aliases` 键并指向所属提供商时， +`suppressions` 替代旧的提供商运行时 `suppressBuiltInModel` 钩子。 +只有当提供商由该插件拥有，或声明为指向所拥有提供商的 `modelCatalog.aliases` 键时， 抑制条目才会生效。模型解析期间不再调用运行时抑制钩子。 提供商字段： -| 字段 | 类型 | 含义 | -| --------- | ------------------------ | -------------------------------------------------------- | -| `baseUrl` | `string` | 此提供商目录中模型的可选默认 base URL。 | -| `api` | `ModelApi` | 此提供商目录中模型的可选默认 API adapter。 | -| `headers` | `Record` | 应用于此提供商目录的可选静态 headers。 | -| `models` | `object[]` | 必需的模型行。没有 `id` 的行会被忽略。 | +| 字段 | 类型 | 含义 | +| --------- | ------------------------ | --------------------------------------------------------------- | +| `baseUrl` | `string` | 此提供商目录中模型的可选默认 base URL。 | +| `api` | `ModelApi` | 此提供商目录中模型的可选默认 API 适配器。 | +| `headers` | `Record` | 应用于此提供商目录的可选静态 headers。 | +| `models` | `object[]` | 必需的模型行。没有 `id` 的行会被忽略。 | 模型字段： -| 字段 | 类型 | 含义 | -| --------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------- | -| `id` | `string` | 提供商本地模型 ID，不含 `provider/` 前缀。 | -| `name` | `string` | 可选显示名称。 | -| `api` | `ModelApi` | 可选的逐模型 API 覆盖。 | -| `baseUrl` | `string` | 可选的逐模型 base URL 覆盖。 | -| `headers` | `Record` | 可选的逐模型静态 headers。 | -| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | 模型接受的模态。 | -| `reasoning` | `boolean` | 模型是否公开推理行为。 | -| `contextWindow` | `number` | 原生提供商上下文窗口。 | -| `contextTokens` | `number` | 当不同于 `contextWindow` 时，可选的有效运行时上下文上限。 | -| `maxTokens` | `number` | 已知的最大输出 token 数。 | -| `cost` | `object` | 可选的每百万 token 美元定价，包括可选的 `tieredPricing`。 | -| `compat` | `object` | 与 OpenClaw 模型配置兼容性匹配的可选兼容性标志。 | -| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | 列表状态。只有当该行完全不应出现时才抑制。 | -| `statusReason` | `string` | 随非可用状态显示的可选原因。 | -| `replaces` | `string[]` | 此模型取代的较旧提供商本地模型 ID。 | -| `replacedBy` | `string` | 已弃用行的替代提供商本地模型 ID。 | -| `tags` | `string[]` | 选择器和过滤器使用的稳定标签。 | +| 字段 | 类型 | 含义 | +| --------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------- | +| `id` | `string` | 提供商本地模型 ID，不带 `provider/` 前缀。 | +| `name` | `string` | 可选显示名称。 | +| `api` | `ModelApi` | 可选的每模型 API 覆盖。 | +| `baseUrl` | `string` | 可选的每模型 base URL 覆盖。 | +| `headers` | `Record` | 可选的每模型静态 headers。 | +| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | 模型接受的模态。 | +| `reasoning` | `boolean` | 模型是否暴露 reasoning 行为。 | +| `contextWindow` | `number` | 原生提供商上下文窗口。 | +| `contextTokens` | `number` | 当与 `contextWindow` 不同时，可选的有效运行时上下文上限。 | +| `maxTokens` | `number` | 已知时的最大输出 token 数。 | +| `cost` | `object` | 可选的每百万 token 美元价格，包括可选的 `tieredPricing`。 | +| `compat` | `object` | 匹配 OpenClaw 模型配置兼容性的可选兼容性标志。 | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | 列表状态。仅当该行完全不应出现时才抑制。 | +| `statusReason` | `string` | 与非 available 状态一起显示的可选原因。 | +| `replaces` | `string[]` | 此模型取代的较旧提供商本地模型 ID。 | +| `replacedBy` | `string` | 已弃用行的替换提供商本地模型 ID。 | +| `tags` | `string[]` | 选择器和过滤器使用的稳定标签。 | 抑制字段： -| 字段 | 类型 | 含义 | +| 字段 | 类型 | 含义 | | -------------------------- | ---------- | --------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | 要抑制的上游行的提供商 ID。必须由此插件拥有，或声明为已拥有的别名。 | -| `model` | `string` | 要抑制的提供商本地模型 ID。 | -| `reason` | `string` | 直接请求被抑制的行时显示的可选消息。 | -| `when.baseUrlHosts` | `string[]` | 抑制生效前所需的有效提供商基础 URL 主机的可选列表。 | -| `when.providerConfigApiIn` | `string[]` | 抑制生效前所需的精确提供商配置 `api` 值的可选列表。 | +| `provider` | `string` | 要抑制的上游行的提供商 ID。必须由此插件拥有，或声明为已拥有的别名。 | +| `model` | `string` | 要抑制的提供商本地模型 ID。 | +| `reason` | `string` | 直接请求被抑制的行时显示的可选消息。 | +| `when.baseUrlHosts` | `string[]` | 抑制生效前必须满足的有效提供商基础 URL 主机可选列表。 | +| `when.providerConfigApiIn` | `string[]` | 抑制生效前必须满足的精确提供商配置 `api` 值可选列表。 | -不要在 `modelCatalog` 中放入仅运行时数据。仅当 manifest -行足够完整，可让按提供商过滤的列表和选择器界面跳过 -registry/运行时发现时，才使用 `static`。当 manifest 行可用作 -可列出的种子或补充项，但刷新/缓存之后可以加入更多行时，使用 `refreshable`； -refreshable 行本身不具备权威性。当 OpenClaw -必须加载提供商运行时才能知道列表时，使用 `runtime`。 +不要把仅运行时数据放入 `modelCatalog`。仅当清单行足够完整，可让按提供商筛选的列表和选择器界面跳过注册表/运行时发现时，才使用 `static`。当清单行可作为有用的可列出种子或补充项，但刷新/缓存稍后可以添加更多行时，使用 `refreshable`；可刷新的行本身不具权威性。当 OpenClaw 必须加载提供商运行时才能知道列表时，使用 `runtime`。 -## modelIdNormalization 参考 +## `modelIdNormalization` 参考 -使用 `modelIdNormalization` 进行低成本、提供商拥有的模型 ID 清理，且该清理必须 -发生在提供商运行时加载之前。这样会将短模型 -名称、提供商本地旧版 ID、代理前缀规则等别名保留在所属插件 -manifest 中，而不是放在核心模型选择表中。 +使用 `modelIdNormalization` 进行轻量的提供商自有模型 ID 清理，且该清理必须在提供商运行时加载前发生。这样可把短模型名称、提供商本地旧版 ID、代理前缀规则等别名保留在所属插件清单中，而不是放进核心模型选择表。 ```json { @@ -764,35 +728,31 @@ manifest 中，而不是放在核心模型选择表中。 提供商字段： -| 字段 | 类型 | 含义 | -| ------------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------- | -| `aliases` | `Record` | 不区分大小写的精确模型 ID 别名。值会按写入形式返回。 | -| `stripPrefixes` | `string[]` | 在别名查找前移除的前缀，适用于旧版提供商/模型重复的情况。 | -| `prefixWhenBare` | `string` | 当规范化后的模型 ID 尚未包含 `/` 时要添加的前缀。 | -| `prefixWhenBareAfterAliasStartsWith` | `object[]` | 别名查找后的条件性裸 ID 前缀规则，由 `modelPrefix` 和 `prefix` 指定。 | +| 字段 | 类型 | 含义 | +| ------------------------------------ | ----------------------- | ----------------------------------------------------------------------------------------- | +| `aliases` | `Record` | 大小写不敏感的精确模型 ID 别名。值会按写入形式返回。 | +| `stripPrefixes` | `string[]` | 别名查找前要移除的前缀，适用于旧版提供商/模型重复。 | +| `prefixWhenBare` | `string` | 当规范化后的模型 ID 尚未包含 `/` 时要添加的前缀。 | +| `prefixWhenBareAfterAliasStartsWith` | `object[]` | 别名查找后的条件裸 ID 前缀规则，以 `modelPrefix` 和 `prefix` 为键。 | -## providerEndpoints 参考 +## `providerEndpoints` 参考 -使用 `providerEndpoints` 提供端点分类，让通用请求策略能在 -提供商运行时加载前获知。核心仍然拥有每个 -`endpointClass` 的含义；插件 manifest 拥有主机和基础 URL 元数据。 +使用 `providerEndpoints` 定义通用请求策略必须在提供商运行时加载前知道的端点分类。核心仍然拥有每个 `endpointClass` 的含义；插件清单拥有主机和基础 URL 元数据。 端点字段： -| 字段 | 类型 | 含义 | -| ------------------------------ | ---------- | -------------------------------------------------------------------------------------------- | -| `endpointClass` | `string` | 已知的核心端点类别，例如 `openrouter`、`moonshot-native` 或 `google-vertex`。 | -| `hosts` | `string[]` | 映射到端点类别的精确主机名。 | -| `hostSuffixes` | `string[]` | 映射到端点类别的主机后缀。以 `.` 开头表示仅匹配域名后缀。 | -| `baseUrls` | `string[]` | 映射到端点类别的精确规范化 HTTP(S) 基础 URL。 | -| `googleVertexRegion` | `string` | 精确全局主机的静态 Google Vertex 区域。 | -| `googleVertexRegionHostSuffix` | `string` | 从匹配主机中剥离的后缀，用于暴露 Google Vertex 区域前缀。 | +| 字段 | 类型 | 含义 | +| ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------- | +| `endpointClass` | `string` | 已知核心端点类别，例如 `openrouter`、`moonshot-native` 或 `google-vertex`。 | +| `hosts` | `string[]` | 映射到该端点类别的精确主机名。 | +| `hostSuffixes` | `string[]` | 映射到该端点类别的主机后缀。以 `.` 作为前缀可仅匹配域名后缀。 | +| `baseUrls` | `string[]` | 映射到该端点类别的精确规范化 HTTP(S) 基础 URL。 | +| `googleVertexRegion` | `string` | 精确全局主机的静态 Google Vertex 区域。 | +| `googleVertexRegionHostSuffix` | `string` | 从匹配主机中剥离的后缀，用于暴露 Google Vertex 区域前缀。 | -## providerRequest 参考 +## `providerRequest` 参考 -使用 `providerRequest` 提供低成本的请求兼容性元数据，让通用 -请求策略无需加载提供商运行时即可使用。将行为特定的 -负载重写保留在提供商运行时钩子或共享的提供商家族辅助函数中。 +使用 `providerRequest` 提供通用请求策略在不加载提供商运行时的情况下所需的轻量请求兼容性元数据。将特定行为的载荷重写保留在提供商运行时钩子或共享提供商家族辅助工具中。 ```json { @@ -812,17 +772,15 @@ manifest 中，而不是放在核心模型选择表中。 提供商字段： -| 字段 | 类型 | 含义 | -| --------------------- | ------------ | ------------------------------------------------------------------------------------ | -| `family` | `string` | 通用请求兼容性决策和诊断使用的提供商家族标签。 | -| `compatibilityFamily` | `"moonshot"` | 共享请求辅助函数可选的提供商家族兼容性分组。 | -| `openAICompletions` | `object` | OpenAI 兼容补全请求标志，目前为 `supportsStreamingUsage`。 | +| 字段 | 类型 | 含义 | +| --------------------- | ------------ | -------------------------------------------------------------------------------------- | +| `family` | `string` | 通用请求兼容性决策和诊断使用的提供商家族标签。 | +| `compatibilityFamily` | `"moonshot"` | 共享请求辅助工具的可选提供商家族兼容性分组。 | +| `openAICompletions` | `object` | OpenAI 兼容的补全请求标志，当前为 `supportsStreamingUsage`。 | -## modelPricing 参考 +## `modelPricing` 参考 -当提供商需要在运行时加载前控制控制平面定价行为时，使用 `modelPricing`。 -Gateway 网关定价缓存会读取此元数据，而不会导入 -提供商运行时代码。 +当提供商需要在运行时加载前控制平面定价行为时，使用 `modelPricing`。Gateway 网关定价缓存会读取此元数据，而不导入提供商运行时代码。 ```json { @@ -845,109 +803,87 @@ Gateway 网关定价缓存会读取此元数据，而不会导入 提供商字段： -| 字段 | 类型 | 含义 | -| ------------ | ----------------- | --------------------------------------------------------------------------------------------- | -| `external` | `boolean` | 对永远不应获取 OpenRouter 或 LiteLLM 定价的本地/自托管提供商设置为 `false`。 | -| `openRouter` | `false \| object` | OpenRouter 定价查询映射。`false` 会禁用此提供商的 OpenRouter 查询。 | -| `liteLLM` | `false \| object` | LiteLLM 定价查询映射。`false` 会禁用此提供商的 LiteLLM 查询。 | +| 字段 | 类型 | 含义 | +| ------------ | ----------------- | -------------------------------------------------------------------------------------------------- | +| `external` | `boolean` | 对绝不应获取 OpenRouter 或 LiteLLM 定价的本地/自托管提供商设置为 `false`。 | +| `openRouter` | `false \| object` | OpenRouter 定价查询映射。`false` 会为此提供商禁用 OpenRouter 查询。 | +| `liteLLM` | `false \| object` | LiteLLM 定价查询映射。`false` 会为此提供商禁用 LiteLLM 查询。 | 来源字段： -| 字段 | 类型 | 含义 | -| -------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | 当外部目录提供商 ID 与 OpenClaw 提供商 ID 不同时使用，例如 `zai` 提供商对应的 `z-ai`。 | -| `passthroughProviderModel` | `boolean` | 将包含斜杠的模型 ID 视为嵌套的提供商/模型引用，适用于 OpenRouter 等代理提供商。 | -| `modelIdTransforms` | `"version-dots"[]` | 额外的外部目录模型 ID 变体。`version-dots` 会尝试像 `claude-opus-4.6` 这样的点号版本 ID。 | +| 字段 | 类型 | 含义 | +| -------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------- | +| `provider` | `string` | 当外部目录提供商 ID 与 OpenClaw 提供商 ID 不同时使用，例如 `zai` 提供商对应的 `z-ai`。 | +| `passthroughProviderModel` | `boolean` | 将包含斜杠的模型 ID 视为嵌套的提供商/模型引用，适用于 OpenRouter 等代理提供商。 | +| `modelIdTransforms` | `"version-dots"[]` | 额外的外部目录模型 ID 变体。`version-dots` 会尝试带点号版本 ID，例如 `claude-opus-4.6`。 | ### OpenClaw 提供商索引 -OpenClaw 提供商索引是 OpenClaw 拥有的提供商预览元数据， -用于插件可能尚未安装的提供商。它不是插件 manifest 的一部分。 -插件 manifest 仍是已安装插件的权威来源。提供商索引是 -内部回退契约，未来的可安装提供商和安装前 -模型选择器界面会在提供商插件未安装时使用它。 +OpenClaw 提供商索引是 OpenClaw 拥有的预览元数据，面向其插件可能尚未安装的提供商。它不是插件清单的一部分。插件清单仍然是已安装插件的权威来源。提供商索引是内部回退契约，未来的可安装提供商和预安装模型选择器界面会在未安装提供商插件时使用它。 目录权威顺序： 1. 用户配置。 -2. 已安装插件 manifest 的 `modelCatalog`。 -3. 显式刷新产生的模型目录缓存。 +2. 已安装插件清单 `modelCatalog`。 +3. 显式刷新得到的模型目录缓存。 4. OpenClaw 提供商索引预览行。 -提供商索引不得包含密钥、启用状态、运行时钩子或 -特定实时账号的模型数据。其预览目录使用与插件 manifest 相同的 -`modelCatalog` 提供商行形状，但应仅限于 -稳定的展示元数据，除非 `api`、`baseUrl`、定价或兼容性标志等 -运行时适配器字段被有意与已安装插件 manifest 保持一致。支持实时 `/models` -发现的提供商应通过显式模型目录缓存路径 -写入刷新后的行，而不是让普通列表或新手引导调用提供商 API。 +提供商索引不得包含密钥、启用状态、运行时钩子或特定实时账号的模型数据。它的预览目录使用与插件清单相同的 `modelCatalog` 提供商行形状，但应仅限于稳定的显示元数据，除非 `api`、`baseUrl`、定价或兼容性标志等运行时适配器字段被有意与已安装插件清单保持一致。具有实时 `/models` 发现的提供商应通过显式模型目录缓存路径写入刷新后的行，而不是让普通列表或新手引导调用提供商 API。 -提供商索引条目也可以携带可安装插件元数据，用于插件 -已移出核心或尚未安装的提供商。此 -元数据映射渠道目录模式：包名、npm 安装规范、 -预期完整性和低成本认证选择标签，足以显示一个 -可安装设置选项。插件安装后，其 manifest 获胜， -该提供商的提供商索引条目会被忽略。 +提供商索引条目也可以携带可安装插件元数据，用于其插件已移出核心或尚未安装的提供商。此元数据遵循渠道目录模式：包名、npm 安装规格、预期完整性和轻量的身份验证选项标签，足以显示一个可安装的设置选项。插件安装后，其清单获胜，并且该提供商的提供商索引条目会被忽略。 -旧版顶级能力键已弃用。使用 `openclaw doctor --fix` 将 -`speechProviders`、`realtimeTranscriptionProviders`、 -`realtimeVoiceProviders`、`mediaUnderstandingProviders`、 -`imageGenerationProviders`、`videoGenerationProviders`、 -`webFetchProviders` 和 `webSearchProviders` 移到 `contracts` 下；正常的 -manifest 加载不再将这些顶级字段视为能力 -所有权。 +旧版顶层能力键已弃用。使用 `openclaw doctor --fix` 将 `speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders` 和 `webSearchProviders` 移到 `contracts` 下；正常清单加载不再把这些顶层字段视为能力所有权。 -## Manifest 与 package.json +## 清单与 `package.json` 这两个文件承担不同职责： -| 文件 | 用途 | +| 文件 | 用途 | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | 发现、配置验证、认证选择元数据，以及必须在插件代码运行前存在的 UI 提示 | -| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 区块 | +| `openclaw.plugin.json` | 发现、配置校验、身份验证选项元数据，以及必须在插件代码运行前存在的 UI 提示 | +| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 块 | -如果你不确定某段元数据应该放在哪里，请使用这条规则： +如果你不确定某段元数据应放在哪里，请使用这条规则： -- 如果 OpenClaw 必须在加载插件代码前知道它，就放在 `openclaw.plugin.json` -- 如果它与打包、入口文件或 npm 安装行为有关，就放在 `package.json` +- 如果 OpenClaw 必须在加载插件代码前知道它，请放入 `openclaw.plugin.json` +- 如果它与打包、入口文件或 npm 安装行为有关，请放入 `package.json` -### 影响发现的 package.json 字段 +### 影响发现的 `package.json` 字段 -一些运行前插件元数据有意放在 `package.json` 的 -`openclaw` 区块下，而不是 `openclaw.plugin.json` 中。 +一些运行前插件元数据会有意放在 `package.json` 的 `openclaw` 块下，而不是 `openclaw.plugin.json`。 重要示例： -| 字段 | 含义 | +| 字段 | 含义 | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.extensions` | 声明原生插件入口点。必须保留在插件包目录内。 | -| `openclaw.runtimeExtensions` | 声明已安装包的已构建 JavaScript 运行时入口点。必须保留在插件包目录内。 | -| `openclaw.setupEntry` | 在新手引导、延迟渠道启动，以及只读渠道 Status/SecretRef 发现期间使用的轻量级仅设置入口点。必须保留在插件包目录内。 | -| `openclaw.runtimeSetupEntry` | 声明已安装包的已构建 JavaScript 设置入口点。必须保留在插件包目录内。 | -| `openclaw.channel` | 低成本渠道目录元数据，例如标签、文档路径、别名和选择文案。 | -| `openclaw.channel.commands` | 在渠道运行时加载前，由配置、审计和命令列表界面使用的静态原生命令和原生技能自动默认元数据。 | -| `openclaw.channel.configuredState` | 轻量级已配置状态检查器元数据，无需加载完整渠道运行时即可回答“是否已存在仅环境变量设置？”。 | -| `openclaw.channel.persistedAuthState` | 轻量级持久化凭证检查器元数据，无需加载完整渠道运行时即可回答“是否已有任何登录状态？”。 | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 面向内置和外部发布插件的安装/更新提示。 | -| `openclaw.install.defaultChoice` | 当存在多个安装来源时首选的安装路径。 | -| `openclaw.install.minHostVersion` | 支持的最低 OpenClaw 宿主版本，使用类似 `>=2026.3.22` 的 semver 下限。 | -| `openclaw.install.expectedIntegrity` | 预期的 npm dist 完整性字符串，例如 `sha512-...`；安装和更新流程会用它校验拉取到的构件。 | -| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个狭窄的内置插件重装恢复路径。 | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间先加载仅设置渠道界面，再加载完整渠道插件。 | +| `openclaw.extensions` | 声明原生插件入口点。必须保留在插件包目录内。 | +| `openclaw.runtimeExtensions` | 为已安装包声明构建后的 JavaScript 运行时入口点。必须保留在插件包目录内。 | +| `openclaw.setupEntry` | 在新手引导、延迟渠道启动和只读渠道状态/SecretRef 发现期间使用的轻量级仅设置入口点。必须保留在插件包目录内。 | +| `openclaw.runtimeSetupEntry` | 为已安装包声明构建后的 JavaScript 设置入口点。必须保留在插件包目录内。 | +| `openclaw.channel` | 低成本渠道目录元数据，例如标签、文档路径、别名和选择说明。 | +| `openclaw.channel.commands` | 在渠道运行时加载之前，供配置、审计和命令列表界面使用的静态原生命令和原生技能自动默认元数据。 | +| `openclaw.channel.configuredState` | 轻量级已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“仅环境变量设置是否已存在？”。 | +| `openclaw.channel.persistedAuthState` | 轻量级持久化认证检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何登录状态？”。 | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 内置插件和外部发布插件的安装/更新提示。 | +| `openclaw.install.defaultChoice` | 当有多个安装来源可用时的首选安装路径。 | +| `openclaw.install.minHostVersion` | 支持的最低 OpenClaw 主机版本，使用类似 `>=2026.3.22` 的 semver 下限。 | +| `openclaw.install.expectedIntegrity` | 预期的 npm dist 完整性字符串，例如 `sha512-...`；安装和更新流程会用它校验获取到的工件。 | +| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个窄范围的内置插件重装恢复路径。 | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间先加载仅设置渠道界面，再加载完整渠道插件。 | -Manifest 元数据决定运行时加载前，新手引导中会出现哪些提供商/渠道/设置选项。`package.json#openclaw.install` 告诉新手引导，当用户选择其中某个选项时应如何拉取或启用该插件。不要把安装提示移动到 `openclaw.plugin.json` 中。 +清单元数据决定在运行时加载之前，新手引导中会出现哪些提供商/渠道/设置选项。`package.json#openclaw.install` 会告诉新手引导在用户选择其中一个选项时，如何获取或启用该插件。不要把安装提示移到 `openclaw.plugin.json` 中。 -`openclaw.install.minHostVersion` 会在安装和 manifest 注册表加载期间强制执行。无效值会被拒绝；较新但有效的值会让插件在较旧宿主上被跳过。 +`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。无效值会被拒绝；较新但有效的值会让旧主机跳过该插件。 -精确 npm 版本固定已经存在于 `npmSpec` 中，例如 `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。官方外部目录条目应将精确 spec 与 `expectedIntegrity` 配对，这样如果拉取到的 npm 构件不再匹配固定版本，更新流程会以关闭方式失败。为兼容性，交互式新手引导仍会提供受信任注册表的 npm spec，包括裸包名和 dist-tag。目录诊断可以区分精确来源、浮动来源、完整性固定来源、缺少完整性来源、包名不匹配来源，以及无效默认选项来源。当存在 `expectedIntegrity` 但没有可用于固定它的有效 npm 来源时，它们也会发出警告。当存在 `expectedIntegrity` 时，安装/更新流程会强制校验它；当省略它时，注册表解析会被记录，但不会带完整性固定。 +精确的 npm 版本固定已存在于 `npmSpec` 中，例如 `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。官方外部目录条目应将精确 spec 与 `expectedIntegrity` 配对，这样如果获取到的 npm 工件不再匹配固定版本，更新流程会以关闭方式失败。为保持兼容，交互式新手引导仍会提供受信任注册表 npm spec，包括裸包名和 dist-tag。目录诊断可以区分精确、浮动、完整性固定、缺少完整性、包名不匹配和无效默认选择来源。当存在 `expectedIntegrity` 但没有可由它固定的有效 npm 来源时，诊断也会发出警告。存在 `expectedIntegrity` 时，安装/更新流程会强制校验它；省略时，注册表解析会被记录，但不带完整性固定。 -当 Status、渠道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账户时，渠道插件应提供 `openclaw.setupEntry`。设置入口应暴露渠道元数据，以及设置安全的配置、Status 和密钥适配器；将网络客户端、Gateway 网关监听器和传输运行时保留在主扩展入口点中。 +当 Status、渠道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账号时，渠道插件应提供 `openclaw.setupEntry`。设置入口应暴露渠道元数据以及设置安全的配置、Status 和 secrets 适配器；将网络客户端、Gateway 网关监听器和传输运行时保留在主扩展入口点中。 -运行时入口点字段不会覆盖源入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能让一个逃逸的 `openclaw.extensions` 路径变得可加载。 +运行时入口点字段不会覆盖源入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能让逃逸的 `openclaw.extensions` 路径变为可加载。 -`openclaw.install.allowInvalidConfigRecovery` 有意保持狭窄。它不会让任意损坏配置变得可安装。如今它只允许安装流程从特定的陈旧内置插件升级失败中恢复，例如缺少内置插件路径，或同一内置插件存在陈旧的 `channels.` 条目。无关配置错误仍会阻止安装，并将操作者引导到 `openclaw doctor --fix`。 +`openclaw.install.allowInvalidConfigRecovery` 的范围有意保持很窄。它不会让任意损坏的配置变得可安装。目前它只允许安装流程从特定的过期内置插件升级失败中恢复，例如缺少内置插件路径，或同一个内置插件存在过期的 `channels.` 条目。不相关的配置错误仍会阻止安装，并将操作员引导到 `openclaw doctor --fix`。 -`openclaw.channel.persistedAuthState` 是一个极小检查器模块的包元数据： +`openclaw.channel.persistedAuthState` 是用于小型检查器模块的包元数据： ```json { @@ -963,9 +899,9 @@ Manifest 元数据决定运行时加载前，新手引导中会出现哪些提 } ``` -当设置、Doctor、Status 或只读存在性流程需要在完整渠道插件加载前进行低成本的是/否凭证探测时使用它。持久化凭证状态不是已配置渠道状态：不要使用此元数据来自动启用插件、修复运行时依赖，或决定是否应加载渠道运行时。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 路由它。 +当设置、Doctor、Status 或只读在线状态流程需要在完整渠道插件加载之前进行低成本是/否认证探测时使用它。持久化认证状态不是已配置渠道状态：不要使用此元数据来自动启用插件、修复运行时依赖，或决定是否应加载渠道运行时。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 转接它。 -`openclaw.channel.configuredState` 对低成本仅环境变量已配置检查采用相同结构： +`openclaw.channel.configuredState` 对低成本仅环境变量已配置检查使用相同结构： ```json { @@ -981,53 +917,54 @@ Manifest 元数据决定运行时加载前，新手引导中会出现哪些提 } ``` -当渠道可以从环境变量或其他极小的非运行时输入回答已配置状态时使用它。如果检查需要完整配置解析或真实渠道运行时，请改将该逻辑保留在插件 `config.hasConfiguredState` 钩子中。 +当渠道可以根据环境变量或其他很小的非运行时输入回答已配置状态时使用它。如果检查需要完整配置解析或真实渠道运行时，请将该逻辑保留在插件的 `config.hasConfiguredState` 钩子中。 -## 发现优先级（重复插件 id） +## 设备发现优先级（重复插件 id） -OpenClaw 会从多个根发现插件（内置、全局安装、工作区、显式配置选择的路径）。如果两次发现共享同一个 `id`，只保留**最高优先级**的 manifest；较低优先级的重复项会被丢弃，而不是并排加载。 +OpenClaw 会从多个根目录发现插件（内置、全局安装、工作区、显式配置选择的路径）。如果两个发现项共享同一个 `id`，只保留**最高优先级**的清单；较低优先级的重复项会被丢弃，而不是并排加载。 优先级从高到低： 1. **配置选择** — 在 `plugins.entries.` 中显式固定的路径 -2. **内置** — 随 OpenClaw 一起发布的插件 +2. **内置** — 随 OpenClaw 发布的插件 3. **全局安装** — 安装到全局 OpenClaw 插件根目录的插件 4. **工作区** — 相对于当前工作区发现的插件 影响： -- 放在工作区中的内置插件分叉副本或陈旧副本不会遮蔽内置构建。 -- 若要真正用本地插件覆盖内置插件，请通过 `plugins.entries.` 固定它，使其凭借优先级胜出，而不是依赖工作区发现。 -- 重复丢弃会被记录，因此 Doctor 和启动诊断可以指向被丢弃的副本。 +- 位于工作区中的内置插件 fork 或过期副本不会遮蔽内置构建。 +- 若要实际用本地插件覆盖内置插件，请通过 `plugins.entries.` 固定它，使其依靠优先级获胜，而不是依赖工作区发现。 +- 重复项丢弃会被记录，因此 Doctor 和启动诊断可以指向被丢弃的副本。 ## JSON Schema 要求 - **每个插件都必须随附 JSON Schema**，即使它不接受任何配置。 -- 空 schema 是可接受的（例如 `{ "type": "object", "additionalProperties": false }`）。 -- Schema 在配置读写时验证，而不是在运行时验证。 +- 空 schema 是可以接受的（例如 `{ "type": "object", "additionalProperties": false }`）。 +- Schema 会在配置读/写时验证，而不是在运行时验证。 ## 验证行为 -- 未知的 `channels.*` 键是**错误**，除非渠道 id 由插件 manifest 声明。 -- `plugins.entries.`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现**的插件 id。未知 id 是**错误**。 -- 如果插件已安装，但 manifest 或 schema 损坏或缺失，验证会失败，Doctor 会报告插件错误。 -- 如果插件配置存在但插件已**禁用**，配置会被保留，并在 Doctor + 日志中浮现**警告**。 +- 未知的 `channels.*` 键是**错误**，除非渠道 id 由插件清单声明。 +- `plugins.entries.`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现的**插件 id。未知 id 是**错误**。 +- 如果插件已安装但清单或 schema 损坏或缺失，验证会失败，Doctor 会报告插件错误。 +- 如果插件配置存在但插件被**禁用**，配置会被保留，并在 Doctor 和日志中显示**警告**。 -完整 `plugins.*` schema 见[配置参考](/zh-CN/gateway/configuration)。 +完整的 `plugins.*` schema 见[配置参考](/zh-CN/gateway/configuration)。 ## 备注 -- manifest 对**原生 OpenClaw 插件**是**必需的**，包括本地文件系统加载。运行时仍会单独加载插件模块；manifest 仅用于设备发现 + 验证。 -- 原生 manifest 使用 JSON5 解析，因此注释、尾随逗号和未加引号的键都会被接受，只要最终值仍然是对象。 -- manifest 加载器只读取已文档化的 manifest 字段。避免使用自定义顶层键。 -- 当插件不需要 `channels`、`providers`、`cliBackends` 和 `skills` 时，它们都可以省略。 -- `providerDiscoveryEntry` 必须保持轻量，不应导入宽泛的运行时代码；将它用于静态提供商目录元数据或狭窄的发现描述符，而不是请求时执行。 -- 互斥插件类型通过 `plugins.slots.*` 选择：`kind: "memory"` 通过 `plugins.slots.memory`，`kind: "context-engine"` 通过 `plugins.slots.contextEngine`（默认 `legacy`）。 -- 环境变量元数据（`setup.providers[].envVars`、已弃用的 `providerAuthEnvVars` 和 `channelEnvVars`）仅是声明式的。Status、审计、cron 投递验证和其他只读界面在将某个环境变量视为已配置前，仍会应用插件信任和有效激活策略。 -- 对于需要提供商代码的运行时向导元数据，见[提供商运行时钩子](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 -- 如果你的插件依赖原生模块，请记录构建步骤和任何包管理器 allowlist 要求（例如 pnpm `allow-build-scripts` + `pnpm rebuild `）。 +- 原生 OpenClaw 插件**必须**提供清单，包括本地文件系统加载。运行时仍会单独加载插件模块；清单仅用于发现 + 验证。 +- 原生清单使用 JSON5 解析，因此注释、尾随逗号和未加引号的键都可接受，只要最终值仍是对象。 +- 清单加载器只读取文档化的清单字段。避免自定义顶层键。 +- 当插件不需要时，可以省略 `channels`、`providers`、`cliBackends` 和 `skills`。 +- `providerDiscoveryEntry` 必须保持轻量，不应导入宽泛的运行时代码；将它用于静态提供商目录元数据或窄范围发现描述符，而不是请求时执行。 +- 独占插件种类通过 `plugins.slots.*` 选择：`kind: "memory"` 通过 `plugins.slots.memory`，`kind: "context-engine"` 通过 `plugins.slots.contextEngine`（默认 `legacy`）。 +- 在此清单中声明独占插件种类。运行时入口 `OpenClawPluginDefinition.kind` 已弃用，仅作为旧插件的兼容后备保留。 +- 环境变量元数据（`setup.providers[].envVars`、已弃用的 `providerAuthEnvVars` 和 `channelEnvVars`）仅为声明式。Status、审计、cron 交付验证和其他只读界面在将某个环境变量视为已配置之前，仍会应用插件信任和有效激活策略。 +- 对于需要提供商代码的运行时向导元数据，请参见[提供商运行时钩子](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 +- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器 allowlist 要求（例如 pnpm `allow-build-scripts` + `pnpm rebuild `）。 -## 相关 +## 相关内容