From b8f3801135bb7ebb452e89eda3d3275f0c40d4a8 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 26 Apr 2026 00:18:48 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/cli/plugins.md | 134 ++-- docs/zh-CN/gateway/bonjour.md | 125 ++-- docs/zh-CN/gateway/configuration-reference.md | 669 +++++++++--------- docs/zh-CN/gateway/security/audit-checks.md | 226 +++--- docs/zh-CN/plugins/architecture-internals.md | 575 ++++++++------- docs/zh-CN/plugins/community.md | 120 ++-- docs/zh-CN/plugins/manifest.md | 521 +++++++------- docs/zh-CN/tools/plugin.md | 221 +++--- 8 files changed, 1313 insertions(+), 1278 deletions(-) diff --git a/docs/zh-CN/cli/plugins.md b/docs/zh-CN/cli/plugins.md index a34c476dc..efc0e2c4d 100644 --- a/docs/zh-CN/cli/plugins.md +++ b/docs/zh-CN/cli/plugins.md @@ -1,26 +1,26 @@ --- read_when: - - 你想要安装或管理 Gateway 网关插件或兼容的捆绑包。 - - 你想要调试插件加载失败问题。 + - 你想要安装或管理 Gateway 网关插件或兼容的软件包合集 + - 你想要调试插件加载失败问题 summary: '`openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、doctor）' title: 插件 x-i18n: - generated_at: "2026-04-25T21:53:54Z" + generated_at: "2026-04-26T00:16:05Z" model: gpt-5.4 provider: openai - source_hash: 3c8abd8c8faf9fbbe1e586a94d5a84848b03746bff05fdac35ffd47032dda292 + source_hash: da98084eb695f0180f928475e31c649a6fc45431b59067688d37417b3727f587 source_path: cli/plugins.md workflow: 15 --- # `openclaw plugins` -管理 Gateway 网关插件、hook 包和兼容的捆绑包。 +管理 Gateway 网关插件、hook 软件包，以及兼容的软件包合集。 相关内容： - 插件系统：[插件](/zh-CN/tools/plugin) -- 捆绑包兼容性：[插件捆绑包](/zh-CN/plugins/bundles) +- 软件包兼容性：[插件软件包](/zh-CN/plugins/bundles) - 插件清单 + schema：[插件清单](/zh-CN/plugins/manifest) - 安全加固：[安全](/zh-CN/gateway/security) @@ -48,17 +48,17 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -OpenClaw 附带了一些内置插件。其中有些默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）；另一些则需要执行 `plugins enable`。 +内置插件会随 OpenClaw 一起提供。其中一些默认启用（例如内置模型提供商、内置语音提供商，以及内置浏览器插件）；另一些则需要使用 `plugins enable`。 -原生 OpenClaw 插件必须提供 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空也必须提供）。兼容的捆绑包则改用它们自己的 bundle manifest。 +原生 OpenClaw 插件必须提供 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空也需要）。兼容的软件包合集则改用它们自己的 bundle 清单。 -`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细的 list/info 输出还会显示 bundle 子类型（`codex`、`claude` 或 `cursor`）以及检测到的 bundle 能力。 +`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细的 list/info 输出还会显示 bundle 子类型（`codex`、`claude` 或 `cursor`），以及检测到的 bundle 能力。 ### 安装 ```bash -openclaw plugins install # 优先 ClawHub，然后 npm -openclaw plugins install clawhub: # 仅 ClawHub +openclaw plugins install # 先查找 ClawHub，然后再查找 npm +openclaw plugins install clawhub: # 仅使用 ClawHub openclaw plugins install --force # 覆盖现有安装 openclaw plugins install --pin # 固定版本 openclaw plugins install --dangerously-force-unsafe-install @@ -68,29 +68,29 @@ openclaw plugins install --marketplace # marketplace（显式 openclaw plugins install --marketplace https://github.com// ``` -裸包名会先在 ClawHub 中检查，然后再检查 npm。安全说明：应将插件安装视为运行代码。建议优先使用固定版本。 +裸包名会先在 ClawHub 中查找，然后再查找 npm。安全提示：安装插件相当于运行代码。建议优先使用固定版本。 -如果你的 `plugins` 部分由单文件 `$include` 提供支持，那么 `plugins install/update/enable/disable/uninstall` 会直接写入该被包含文件，而不会修改 `openclaw.json`。根级 include、include 数组以及带有同级覆盖项的 include 会以失败关闭方式处理，而不是被展平。支持的形态请参见 [Config includes](/zh-CN/gateway/configuration)。 +如果你的 `plugins` 配置段由单文件 `$include` 提供支持，`plugins install/update/enable/disable/uninstall` 会将更改写入该被包含文件，并保持 `openclaw.json` 不变。根级 includes、include 数组，以及带有同级 override 的 include 都会以安全关闭方式失败，而不会被扁平化处理。支持的形式请参见 [配置 includes](/zh-CN/gateway/configuration)。 -如果配置无效，`plugins install` 通常会以失败关闭方式终止，并提示你先运行 `openclaw doctor --fix`。唯一有文档说明的例外是一个范围很窄的内置插件恢复路径，仅适用于显式启用了 `openclaw.install.allowInvalidConfigRecovery` 的插件。 +如果配置无效，`plugins install` 通常会以安全关闭方式失败，并提示你先运行 `openclaw doctor --fix`。唯一记录在文档中的例外，是一个较窄的内置插件恢复路径，适用于明确启用了 `openclaw.install.allowInvalidConfigRecovery` 的插件。 -`--force` 会复用现有安装目标，并原地覆盖一个已安装的插件或 hook 包。当你有意使用新的本地路径、归档文件、ClawHub 包或 npm 制品重新安装同一 id 时，请使用它。对于已跟踪的 npm 插件的常规升级，优先使用 `openclaw plugins update `。 +`--force` 会复用现有安装目标，并原地覆盖一个已安装的插件或 hook 软件包。当你有意从新的本地路径、归档文件、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` hook 策略阻止，也**不会**绕过扫描失败。 +`--dangerously-force-unsafe-install` 是内置危险代码扫描器出现误报时的紧急开关选项。即使内置扫描器报告 `critical` 级发现，它也允许安装继续进行，但它**不会**绕过插件 `before_install` hook 策略拦截，也**不会**绕过扫描失败。 -这个 CLI 标志适用于插件 install/update 流程。由 Gateway 网关支持的 Skills 依赖安装使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是单独的 ClawHub Skills 下载/安装流程。 +这个 CLI 标志适用于插件安装/更新流程。由 Gateway 网关支持的 Skills 依赖安装使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖项，而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载/安装流程。 -`plugins install` 也是暴露 `openclaw.hooks` 于 `package.json` 中的 hook 包的安装入口。要查看筛选后的 hook 可见性和按 hook 启用，请使用 `openclaw hooks`，而不是用它来安装包。 +`plugins install` 也是暴露 `openclaw.hooks` 于 `package.json` 中的 hook 软件包的安装入口。请使用 `openclaw hooks` 来查看经过筛选的 hook 可见性以及按 hook 启用，而不是用于安装软件包。 -npm spec **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。为保证安全，依赖安装会在项目本地使用 `--ignore-scripts` 运行，即使你的 shell 配置了全局 npm 安装设置也是如此。 +Npm spec **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围都会被拒绝。为安全起见，依赖安装会在项目本地使用 `--ignore-scripts` 运行，即使你的 shell 配置了全局 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 包，请使用显式的带作用域 spec（例如 `@scope/diffs`）。 +如果一个裸安装 spec 与某个内置插件 id 匹配（例如 `diffs`），OpenClaw 会直接安装该内置插件。要安装同名的 npm 包，请使用显式作用域 spec（例如 `@scope/diffs`）。 支持的归档格式：`.zip`、`.tgz`、`.tar.gz`、`.tar`。 @@ -103,22 +103,22 @@ openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -OpenClaw 现在也会优先为裸的 npm-safe 插件 spec 使用 ClawHub。只有当 ClawHub 没有该包或版本时，它才会回退到 npm： +OpenClaw 现在也会优先为裸 npm-safe 插件 spec 使用 ClawHub。只有在 ClawHub 没有该包或该版本时，才会回退到 npm： ```bash openclaw plugins install openclaw-codex-app-server ``` -OpenClaw 会从 ClawHub 下载包归档，检查其声明的插件 API / 最低 gateway 兼容性，然后通过常规归档路径进行安装。已记录的安装会保留其 ClawHub 来源元数据，以便后续更新。 +OpenClaw 会从 ClawHub 下载软件包归档，检查所声明的插件 API / 最低 Gateway 网关兼容性，然后通过常规归档路径安装它。已记录的安装会保留其 ClawHub 来源元数据，以便后续更新。 -当 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 @@ -129,22 +129,22 @@ openclaw plugins install --marketplace ./my-marketplace Marketplace 来源可以是： -- `~/.claude/plugins/known_marketplaces.json` 中 Claude 已知 marketplace 名称 +- 来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称 - 本地 marketplace 根目录或 `marketplace.json` 路径 - GitHub 仓库简写，例如 `owner/repo` - GitHub 仓库 URL，例如 `https://github.com/owner/repo` - git URL -对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保留在克隆后的 marketplace 仓库内部。OpenClaw 接受来自该仓库的相对路径来源，并拒绝远程 manifest 中的 HTTP(S)、绝对路径、git、GitHub 及其他非路径插件来源。 +对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保持在克隆后的 marketplace 仓库内部。OpenClaw 接受来自该仓库的相对路径来源，并拒绝远程清单中的 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 兼容的软件包合集（`.codex-plugin/plugin.json`） +- Claude 兼容的软件包合集（`.claude-plugin/plugin.json` 或默认 Claude 组件布局） +- Cursor 兼容的软件包合集（`.cursor-plugin/plugin.json`） -兼容捆绑包会安装到常规插件根目录中，并参与相同的 list/info/enable/disable 流程。目前，bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / manifest 声明的 `lspServers` 默认值、Cursor command-skills 以及兼容的 Codex hook 目录均已支持；其他检测到的 bundle 能力会显示在诊断/info 中，但尚未接入运行时执行。 +兼容的软件包合集会安装到常规插件根目录中，并参与相同的 list/info/enable/disable 流程。目前，已支持 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 由清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录；其他检测到的 bundle 能力会在诊断/info 中显示，但尚未接入运行时执行。 ### 列表 @@ -155,15 +155,15 @@ openclaw plugins list --verbose openclaw plugins list --json ``` -使用 `--enabled` 仅显示已启用的插件。使用 `--verbose` 可从表格视图切换为每个插件的详细行，其中包含 source/origin/version/activation 元数据。使用 `--json` 可获取适用于机器读取的清单以及 registry 诊断信息。 +使用 `--enabled` 仅显示已启用插件。使用 `--verbose` 可从表格视图切换为按插件显示的详细行，其中包含 source/origin/version/activation 元数据。使用 `--json` 可获取适合机器读取的清单以及注册表诊断信息。 -`plugins list` 会先读取持久化的本地插件 registry；如果 registry 缺失或无效，则回退为仅基于 manifest 推导的结果。它适合用来检查某个插件是否已安装、已启用，以及在冷启动规划中是否可见，但它不是对已运行 Gateway 网关进程的实时运行时探测。在更改插件代码、启用状态、hook 策略或 `plugins.load.paths` 后，需重启为该渠道提供服务的 Gateway 网关，之后新 `register(api)` 代码或 hook 才会运行。对于远程/容器部署，请确认你重启的是真正的 `openclaw gateway run` 子进程，而不只是一个包装进程。 +`plugins list` 会先读取持久化的本地插件注册表；如果注册表缺失或无效，则回退为仅基于清单推导出的结果。它适用于检查插件是否已安装、已启用，以及对冷启动规划是否可见，但它并不是对已运行 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、hook 策略或 `plugins.load.paths` 后，请重启为该渠道提供服务的 Gateway 网关，然后再期待新的 `register(api)` 代码或 hook 开始运行。对于远程/容器部署，请确认你重启的是真正的 `openclaw gateway run` 子进程，而不只是某个包装进程。 对于运行时 hook 调试： -- `openclaw plugins inspect --json` 会显示来自模块加载检查过程的已注册 hook 和诊断信息。 -- `openclaw gateway status --deep --require-rpc` 会确认可访问的 Gateway 网关、服务/进程提示、配置路径以及 RPC 健康状态。 -- 非内置的会话 hook（`llm_input`、`llm_output`、`agent_end`）要求 `plugins.entries..hooks.allowConversationAccess=true`。 +- `openclaw plugins inspect --json` 会显示已注册的 hook 以及来自模块加载检查过程的诊断信息 +- `openclaw gateway status --deep --require-rpc` 会确认可达的 Gateway 网关、服务/进程提示、配置路径以及 RPC 健康状态 +- 非内置的会话 hook（`llm_input`、`llm_output`、`agent_end`）需要 `plugins.entries..hooks.allowConversationAccess=true` 使用 `--link` 可避免复制本地目录（会添加到 `plugins.load.paths`）： @@ -171,15 +171,13 @@ openclaw plugins list --json openclaw plugins install -l ./my-plugin ``` -`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是覆盖一个受管安装目标。 +`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是复制覆盖一个受管安装目标。 -在 npm 安装中使用 `--pin`，可以把解析后的精确 spec（`name@version`）保存到受管安装 ledger 中，同时保留默认的非固定行为。 +在 npm 安装中使用 `--pin`，可以把解析后的精确 spec（`name@version`）保存到受管插件索引中，同时保持默认行为不固定版本。 -### 安装台账 +### 插件索引 -插件安装元数据是机器管理状态，不是用户配置。新的安装和更新会将其写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。该文件包含“请勿手动编辑”的警告，并被 `openclaw plugins update`、卸载、诊断以及冷插件 registry 使用。 - -`openclaw.json` 中旧版的 `plugins.installs` 条目仍可读取，作为已弃用的兼容性回退。当 install/update/uninstall 路径重写插件安装状态时，OpenClaw 会写入 ledger 文件，并从持久化配置负载中移除 `plugins.installs`。 +插件安装元数据是机器管理的状态，而不是用户配置。安装和更新会将其写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。其中顶层 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件清单的记录。`plugins` 数组则是基于清单派生的冷注册表缓存。该文件包含“请勿手动编辑”的警告，并被 `openclaw plugins update`、卸载、诊断以及冷插件注册表使用。 ### 卸载 @@ -189,11 +187,10 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` 会从 `plugins.entries`、受管安装 ledger、插件 allowlist，以及适用时的已链接 `plugins.load.paths` 条目中移除插件记录。 -对于活动中的 memory 插件，memory 插槽会重置为 `memory-core`。 +`uninstall` 会从 `plugins.entries`、持久化插件索引、插件 allowlist，以及关联的 `plugins.load.paths` 条目中移除插件记录（如适用）。 +对于活跃的内存插件，memory 插槽会重置为 `memory-core`。 -默认情况下，卸载还会删除活动 state-dir 插件根目录下的插件安装目录。使用 -`--keep-files` 可保留磁盘上的文件。 +默认情况下，卸载还会删除活动 state-dir 插件根目录下的插件安装目录。使用 `--keep-files` 可保留磁盘上的文件。 `--keep-config` 作为 `--keep-files` 的已弃用别名仍受支持。 @@ -207,19 +204,19 @@ openclaw plugins update @openclaw/voice-call@beta openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -更新适用于受管安装 ledger 中已跟踪的插件安装，以及 `hooks.internal.installs` 中已跟踪的 hook-pack 安装。 +更新会应用于受管插件索引中已跟踪的插件安装，以及 `hooks.internal.installs` 中已跟踪的 hook 软件包安装。 -当你传入一个插件 id 时，OpenClaw 会复用为该插件记录的安装 spec。这意味着先前存储的 dist-tag（如 `@beta`）和精确固定版本，在后续执行 `update ` 时仍会继续使用。 +当你传入一个插件 id 时，OpenClaw 会复用该插件已记录的安装 spec。这意味着此前存储的 dist-tag（如 `@beta`）和精确固定版本，会在后续运行 `update ` 时继续使用。 -对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm package spec。OpenClaw 会将该包名解析回已跟踪的插件记录，更新那个已安装插件，并记录新的 npm spec，以供未来基于 id 的更新使用。 +对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会将该包名解析回已跟踪的插件记录，更新该已安装插件，并记录新的 npm spec，以供后续基于 id 的更新使用。 -传入不带版本或标签的 npm 包名，同样会解析回已跟踪的插件记录。当某个插件被固定到精确版本，而你想让它回到 registry 的默认发布线路时，可使用这种方式。 +不带版本或标签地传入 npm 包名，也会解析回已跟踪的插件记录。当某个插件被固定到精确版本，而你想让它回到 registry 的默认发布线时，请使用这种方式。 -在执行实时 npm 更新之前，OpenClaw 会根据 npm registry 元数据检查已安装的包版本。如果已安装版本和记录的制品身份已与解析出的目标一致，则会跳过更新，不会下载、重新安装，也不会重写 `openclaw.json`。 +在执行实际的 npm 更新前，OpenClaw 会将已安装的软件包版本与 npm registry 元数据进行比较。如果已安装版本和已记录制品标识已经与解析后的目标一致，则会跳过更新，不会下载、重新安装，也不会重写 `openclaw.json`。 -当已存储完整性哈希且拉取到的制品哈希发生变化时，OpenClaw 会将其视为 npm 制品漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新辅助流程会以失败关闭方式终止，除非调用方提供显式的继续策略。 +当存在已存储的完整性哈希，而获取到的制品哈希发生变化时，OpenClaw 会将其视为 npm 制品漂移。交互式的 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新辅助工具会以安全关闭方式失败，除非调用方提供显式的继续策略。 -`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的紧急覆盖开关。它仍然不会绕过插件 `before_install` 策略阻止或扫描失败阻止，并且它仅适用于插件更新，不适用于 hook-pack 更新。 +`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新过程中内置危险代码扫描误报时的紧急覆盖选项。它仍然不会绕过插件 `before_install` 策略拦截或扫描失败拦截，并且它只适用于插件更新，不适用于 hook 软件包更新。 ### 检查 @@ -228,20 +225,20 @@ openclaw plugins inspect openclaw plugins inspect --json ``` -对单个插件进行深度检查。显示身份、加载状态、来源、已注册能力、hooks、工具、命令、服务、gateway 方法、HTTP 路由、策略标志、诊断信息、安装元数据、bundle 能力，以及任何检测到的 MCP 或 LSP 服务器支持。 +针对单个插件的深度自省。显示身份信息、加载状态、来源、已注册能力、hook、工具、命令、服务、Gateway 网关方法、HTTP 路由、策略标志、诊断信息、安装元数据、bundle 能力，以及任何检测到的 MCP 或 LSP 服务器支持。 每个插件都会根据它在运行时实际注册的内容进行分类： -- **plain-capability** — 一种能力类型（例如仅 provider 的插件） +- **plain-capability** — 单一能力类型（例如仅 provider 的插件） - **hybrid-capability** — 多种能力类型（例如文本 + 语音 + 图像） -- **hook-only** — 仅有 hooks，没有能力或表面 +- **hook-only** — 仅有 hook，没有能力或其他表面 - **non-capability** — 有工具/命令/服务，但没有能力 -关于能力模型的更多内容，请参见 [Plugin shapes](/zh-CN/plugins/architecture#plugin-shapes)。 +关于能力模型的更多信息，请参见 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。 `--json` 标志会输出适合脚本和审计使用的机器可读报告。 -`inspect --all` 会渲染一个全量表格，其中包含 shape、能力种类、兼容性提示、bundle 能力和 hook 摘要列。 +`inspect --all` 会渲染一个面向整组插件的表格，其中包含 shape、capability kinds、兼容性提示、bundle 能力，以及 hook 摘要列。 `info` 是 `inspect` 的别名。 @@ -251,11 +248,11 @@ openclaw plugins inspect --json openclaw plugins doctor ``` -`doctor` 会报告插件加载错误、manifest/设备发现诊断信息以及兼容性提示。当一切正常时，它会打印 `No plugin issues detected.`。 +`doctor` 会报告插件加载错误、清单/发现诊断信息，以及兼容性提示。当一切正常时，它会打印 `No plugin issues detected.`。 -对于缺少 `register`/`activate` 导出这类模块形态失败，请在重新运行时设置 `OPENCLAW_PLUGIN_LOAD_DEBUG=1`，以便在诊断输出中包含紧凑的导出形态摘要。 +对于缺少 `register`/`activate` 导出之类的模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以在诊断输出中包含紧凑的导出形态摘要。 -### Registry +### 注册表 ```bash openclaw plugins registry @@ -263,12 +260,11 @@ openclaw plugins registry --refresh openclaw plugins registry --json ``` -本地插件 registry 是 OpenClaw 持久化的冷读取模型，用于保存已安装插件的身份、启用状态、来源元数据和贡献归属。 -正常启动、provider 所有者查找、channel 设置分类和插件清单都可以在不导入插件运行时模块的情况下读取它。 +本地插件注册表是 OpenClaw 针对已安装插件身份、启用状态、来源元数据和贡献归属所持久化的冷读模型。正常启动、provider 归属查询、渠道设置分类，以及插件清单，都可以在不导入插件运行时模块的情况下读取它。 -使用 `plugins registry` 可检查持久化 registry 是否存在、是否最新或是否已过期。使用 `--refresh` 可根据持久安装 ledger、配置策略以及 manifest/package 元数据重新构建它。这是修复路径，不是运行时激活路径。 +使用 `plugins registry` 可检查持久化注册表是否存在、是否最新、是否已过期。使用 `--refresh` 可基于持久化插件索引、配置策略以及清单/软件包元数据重建它。这是修复路径，不是运行时激活路径。 -`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是一个已弃用的紧急兼容性开关，用于处理 registry 读取失败。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；这个环境变量回退仅用于迁移发布期间的紧急启动恢复。 +`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是一个已弃用的紧急兼容开关，用于应对注册表读取失败。更推荐使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；这个环境变量回退仅用于迁移发布期间的紧急启动恢复。 ### Marketplace @@ -277,9 +273,9 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Marketplace list 接受本地 marketplace 路径、`marketplace.json` 路径、如 `owner/repo` 这样的 GitHub 简写、GitHub 仓库 URL，或 git URL。`--json` 会打印解析后的来源标签，以及已解析的 marketplace manifest 和插件条目。 +Marketplace list 接受本地 marketplace 路径、`marketplace.json` 路径、像 `owner/repo` 这样的 GitHub 简写、GitHub 仓库 URL，或 git URL。`--json` 会打印解析后的来源标签，以及已解析的 marketplace 清单和插件条目。 -## 相关内容 +## 相关 - [CLI 参考](/zh-CN/cli) - [构建插件](/zh-CN/plugins/building-plugins) diff --git a/docs/zh-CN/gateway/bonjour.md b/docs/zh-CN/gateway/bonjour.md index 552980d7c..ced362c60 100644 --- a/docs/zh-CN/gateway/bonjour.md +++ b/docs/zh-CN/gateway/bonjour.md @@ -5,38 +5,38 @@ read_when: summary: Bonjour/mDNS 发现 + 调试（Gateway 网关信标、客户端以及常见故障模式） title: Bonjour 发现 x-i18n: - generated_at: "2026-04-24T06:33:27Z" + generated_at: "2026-04-26T00:16:08Z" model: gpt-5.4 provider: openai - source_hash: 62961714a0c9880be457c254e1cfc1701020ea51b89f2582757cddc8b3dd2113 + source_hash: ced3a4a81ab6a4e8c32a33c967ff3e173485c3e644885192012eaca8b81a065f source_path: gateway/bonjour.md workflow: 15 --- # Bonjour / mDNS 发现 -OpenClaw 使用 Bonjour（mDNS / DNS‑SD）来发现活动中的 Gateway 网关（WebSocket 端点）。 -多播 `local.` 浏览是一种**仅限局域网的便利机制**。内置的 `bonjour` -插件负责局域网广播，且默认启用。对于跨网络发现， +OpenClaw 使用 Bonjour（mDNS / DNS-SD）来发现处于活动状态的 Gateway 网关（WebSocket 端点）。 +多播 `local.` 浏览是一种**仅限 LAN 的便利机制**。内置的 `bonjour` +插件负责 LAN 广播，并且默认启用。对于跨网络发现， 同一个信标也可以通过已配置的广域 DNS-SD 域发布。 -发现机制仍然是尽力而为，**不能**替代 SSH 或基于 Tailnet 的连接方式。 +发现机制仍然是尽力而为，**不能**替代 SSH 或基于 Tailnet 的连接。 -## 通过 Tailscale 使用广域 Bonjour（单播 DNS-SD） +## 通过 Tailscale 实现广域 Bonjour（单播 DNS-SD） -如果节点和 Gateway 网关位于不同网络，多播 mDNS 不会跨越该 -边界。你可以切换到**单播 DNS‑SD** -（“广域 Bonjour”）并通过 Tailscale 使用它，从而保留相同的发现 UX。 +如果节点和网关位于不同网络，多播 mDNS 将无法跨越该 +边界。你可以通过在 Tailscale 上切换到**单播 DNS-SD** +（“广域 Bonjour”）来保留相同的发现 UX。 -高级步骤如下： +高层步骤： -1. 在 Gateway 网关主机上运行 DNS 服务器（可通过 Tailnet 访问）。 -2. 在专用区域下为 `_openclaw-gw._tcp` 发布 DNS‑SD 记录 +1. 在网关主机上运行一个 DNS 服务器（可通过 Tailnet 访问）。 +2. 在专用区域下发布 `_openclaw-gw._tcp` 的 DNS-SD 记录 （示例：`openclaw.internal.`）。 -3. 配置 Tailscale **split DNS**，使你的选定域通过该 - DNS 服务器为客户端（包括 iOS）解析。 +3. 配置 Tailscale 的**拆分 DNS**，使客户端（包括 iOS）通过该 + DNS 服务器解析你选择的域。 -OpenClaw 支持任意发现域；`openclaw.internal.` 只是一个示例。 -iOS/Android 节点会同时浏览 `local.` 和你配置的广域域名。 +OpenClaw 支持任何发现域；`openclaw.internal.` 只是一个示例。 +iOS/Android 节点会同时浏览 `local.` 和你配置的广域域。 ### Gateway 网关配置（推荐） @@ -47,7 +47,7 @@ iOS/Android 节点会同时浏览 `local.` 和你配置的广域域名。 } ``` -### 一次性 DNS 服务器设置（Gateway 网关主机） +### 一次性 DNS 服务器设置（网关主机） ```bash openclaw dns setup --apply @@ -55,10 +55,10 @@ openclaw dns setup --apply 这会安装 CoreDNS 并将其配置为： -- 仅在 Gateway 网关的 Tailscale 接口上的 53 端口监听 +- 仅在网关的 Tailscale 接口上的 53 端口监听 - 从 `~/.openclaw/dns/.db` 为你选择的域（示例：`openclaw.internal.`）提供服务 -在已连接 tailnet 的机器上验证： +在连接到 tailnet 的机器上验证： ```bash dns-sd -B _openclaw-gw._tcp openclaw.internal. @@ -69,55 +69,55 @@ dig @ -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short 在 Tailscale 管理控制台中： -- 添加一个指向 Gateway 网关 tailnet IP 的 nameserver（UDP/TCP 53）。 -- 添加 split DNS，使你的发现域使用该 nameserver。 +- 添加一个指向网关 tailnet IP 的名称服务器（UDP/TCP 53）。 +- 添加拆分 DNS，使你的发现域使用该名称服务器。 -一旦客户端接受 tailnet DNS，iOS 节点和 CLI 发现就可以在你的发现域中浏览 +一旦客户端接受 tailnet DNS，iOS 节点和 CLI 发现功能就可以在你的发现域中浏览 `_openclaw-gw._tcp`，而无需多播。 ### Gateway 网关监听器安全性（推荐） -Gateway 网关 WS 端口（默认 `18789`）默认绑定到 loopback。对于局域网/tailnet -访问，请显式绑定并保持身份验证启用。 +Gateway 网关 WS 端口（默认 `18789`）默认绑定到 loopback。对于 LAN/tailnet +访问，请显式绑定并保持启用身份验证。 对于仅 tailnet 的设置： - 在 `~/.openclaw/openclaw.json` 中设置 `gateway.bind: "tailnet"`。 - 重启 Gateway 网关（或重启 macOS 菜单栏应用）。 -## 广播内容 +## 谁会广播 -只有 Gateway 网关会广播 `_openclaw-gw._tcp`。局域网多播广播由 +只有 Gateway 网关会广播 `_openclaw-gw._tcp`。LAN 多播广播由 内置的 `bonjour` 插件提供；广域 DNS-SD 发布仍由 Gateway 网关负责。 ## 服务类型 -- `_openclaw-gw._tcp` — Gateway 网关传输信标（由 macOS/iOS/Android 节点使用）。 +- `_openclaw-gw._tcp` — 网关传输信标（由 macOS/iOS/Android 节点使用）。 -## TXT 键（非敏感提示） +## TXT 键（非机密提示） -Gateway 网关会广播少量非敏感提示，以便让 UI 流程更方便： +Gateway 网关会广播一些小型的非机密提示，以便让 UI 流程更方便： - `role=gateway` - `displayName=` - `lanHost=.local` - `gatewayPort=`（Gateway 网关 WS + HTTP） -- `gatewayTls=1`（仅在启用 TLS 时） -- `gatewayTlsSha256=`（仅在启用 TLS 且指纹可用时） -- `canvasPort=`（仅在启用 canvas host 时；当前与 `gatewayPort` 相同） +- `gatewayTls=1`（仅当启用 TLS 时） +- `gatewayTlsSha256=`（仅当启用 TLS 且指纹可用时） +- `canvasPort=`（仅当启用 canvas host 时；当前与 `gatewayPort` 相同） - `transport=gateway` - `tailnetDns=`（仅限 mDNS 完整模式；当 Tailnet 可用时的可选提示） -- `sshPort=`（仅限 mDNS 完整模式；广域 DNS-SD 可能省略它） -- `cliPath=`（仅限 mDNS 完整模式；广域 DNS-SD 仍会将其写入，作为远程安装提示） +- `sshPort=`（仅限 mDNS 完整模式；广域 DNS-SD 可能会省略它） +- `cliPath=`（仅限 mDNS 完整模式；广域 DNS-SD 仍会将其写入作为远程安装提示） 安全说明： - Bonjour/mDNS TXT 记录是**未经身份验证的**。客户端不得将 TXT 视为权威路由信息。 -- 客户端应使用解析后的服务端点（SRV + A/AAAA）进行路由。仅将 `lanHost`、`tailnetDns`、`gatewayPort` 和 `gatewayTlsSha256` 视为提示。 -- SSH 自动定向同样应使用解析后的服务主机，而不是仅依赖 TXT 提示。 +- 客户端应使用已解析的服务端点（SRV + A/AAAA）进行路由。仅将 `lanHost`、`tailnetDns`、`gatewayPort` 和 `gatewayTlsSha256` 视为提示。 +- SSH 自动目标选择同样应使用已解析的服务主机，而不是仅依赖 TXT 提示。 - TLS pinning 绝不能允许已广播的 `gatewayTlsSha256` 覆盖先前存储的 pin。 -- iOS/Android 节点应将基于发现的直连视为**仅限 TLS**，并在信任首次出现的指纹前要求用户明确确认。 +- iOS/Android 节点应将基于发现的直接连接视为**仅限 TLS**，并在首次信任指纹前要求用户明确确认。 ## 在 macOS 上调试 @@ -129,32 +129,33 @@ Gateway 网关会广播少量非敏感提示，以便让 UI 流程更方便： dns-sd -B _openclaw-gw._tcp local. ``` -- 解析单个实例（将 `` 替换为实际值）： +- 解析单个实例（替换 ``）： ```bash dns-sd -L "" _openclaw-gw._tcp local. ``` -如果浏览正常但解析失败，通常意味着你遇到了局域网策略或 +如果浏览可用但解析失败，通常意味着你遇到了 LAN 策略或 mDNS 解析器问题。 ## 在 Gateway 网关日志中调试 -Gateway 网关会写入滚动日志文件（启动时会打印为 -`gateway log file: ...`）。请查找 `bonjour:` 日志行，尤其是： +Gateway 网关会写入一个滚动日志文件（启动时会打印为 +`gateway log file: ...`）。请查找 `bonjour:` 行，特别是： - `bonjour: advertise failed ...` - `bonjour: ... name conflict resolved` / `hostname conflict resolved` - `bonjour: watchdog detected non-announced service ...` +- `bonjour: disabling advertiser after ... failed restarts ...` ## 在 iOS 节点上调试 -iOS 节点使用 `NWBrowser` 发现 `_openclaw-gw._tcp`。 +iOS 节点使用 `NWBrowser` 来发现 `_openclaw-gw._tcp`。 要捕获日志： -- 设置 → Gateway 网关 → 高级 → **发现调试日志** -- 设置 → Gateway 网关 → 高级 → **发现日志** → 复现问题 → **复制** +- 设置 → Gateway 网关 → 高级 → **Discovery Debug Logs** +- 设置 → Gateway 网关 → 高级 → **Discovery Logs** → 复现问题 → **Copy** 日志包含浏览器状态转换和结果集变化。 @@ -162,30 +163,34 @@ iOS 节点使用 `NWBrowser` 发现 `_openclaw-gw._tcp`。 - **Bonjour 无法跨网络工作**：请使用 Tailnet 或 SSH。 - **多播被阻止**：某些 Wi‑Fi 网络会禁用 mDNS。 -- **睡眠 / 接口频繁变化**：macOS 可能会暂时丢失 mDNS 结果；请重试。 -- **浏览正常但解析失败**：请保持机器名简单（避免使用表情符号或 +- **广播器卡在 probing/announcing**：在多播被阻止、 + 容器网桥、WSL 或接口频繁变化的主机上，`ciao` 广播器可能会停留在 + 未广播状态。OpenClaw 会重试几次，然后为当前 Gateway 网关进程禁用 Bonjour， + 而不是无限重启广播器。 +- **睡眠 / 接口变化**：macOS 可能会暂时丢失 mDNS 结果；请重试。 +- **浏览可用但解析失败**：请保持机器名称简洁（避免使用表情符号或 标点符号），然后重启 Gateway 网关。服务实例名称派生自 - 主机名，因此过于复杂的名称可能会让某些解析器混淆。 + 主机名，因此过于复杂的名称可能会让某些解析器产生混淆。 -## 转义的实例名称（`\032`） +## 转义后的实例名称（`\032`） -Bonjour/DNS‑SD 通常会将服务实例名称中的字节转义为十进制 `\DDD` -序列（例如，空格会变成 `\032`）。 +Bonjour/DNS-SD 通常会将服务实例名称中的字节转义为十进制 `\DDD` +序列（例如空格会变成 `\032`）。 -- 这在协议层面是正常现象。 -- UI 应为显示进行解码（iOS 使用 `BonjourEscapes.decode`）。 +- 这在协议层面是正常的。 +- UI 应为显示目的进行解码（iOS 使用 `BonjourEscapes.decode`）。 ## 禁用 / 配置 -- `openclaw plugins disable bonjour` 会通过禁用内置插件来禁用局域网多播广播。 -- `openclaw plugins enable bonjour` 会恢复默认的局域网发现插件。 -- `OPENCLAW_DISABLE_BONJOUR=1` 会在不更改插件配置的情况下禁用局域网多播广播；接受的真值包括 `1`、`true`、`yes` 和 `on`（旧版：`OPENCLAW_DISABLE_BONJOUR`）。 -- `gateway.bind`（位于 `~/.openclaw/openclaw.json`）控制 Gateway 网关绑定模式。 +- `openclaw plugins disable bonjour` 通过禁用内置插件来禁用 LAN 多播广播。 +- `openclaw plugins enable bonjour` 恢复默认的 LAN 发现插件。 +- `OPENCLAW_DISABLE_BONJOUR=1` 在不更改插件配置的情况下禁用 LAN 多播广播；可接受的真值包括 `1`、`true`、`yes` 和 `on`（旧版：`OPENCLAW_DISABLE_BONJOUR`）。 +- `gateway.bind` 位于 `~/.openclaw/openclaw.json` 中，用于控制 Gateway 网关绑定模式。 - `OPENCLAW_SSH_PORT` 会在广播 `sshPort` 时覆盖 SSH 端口（旧版：`OPENCLAW_SSH_PORT`）。 - `OPENCLAW_TAILNET_DNS` 会在启用 mDNS 完整模式时在 TXT 中发布 MagicDNS 提示（旧版：`OPENCLAW_TAILNET_DNS`）。 -- `OPENCLAW_CLI_PATH` 会覆盖已广播的 CLI 路径（旧版：`OPENCLAW_CLI_PATH`）。 +- `OPENCLAW_CLI_PATH` 会覆盖广播的 CLI 路径（旧版：`OPENCLAW_CLI_PATH`）。 ## 相关文档 -- 设备发现策略和传输选择：[Discovery](/zh-CN/gateway/discovery) -- 节点配对 + 批准：[Gateway pairing](/zh-CN/gateway/pairing) +- 设备发现策略与传输选择：[设备发现](/zh-CN/gateway/discovery) +- 节点配对 + 批准：[Gateway 网关配对](/zh-CN/gateway/pairing) diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index e4cf160e5..66c7456ab 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -1,70 +1,70 @@ --- read_when: - 你需要精确到字段级别的配置语义或默认值 - - 你正在验证渠道、模型、Gateway 网关 或工具配置块 -summary: Gateway 网关 配置参考，涵盖 OpenClaw 核心键名、默认值以及指向各专用子系统参考的链接 + - 你正在验证渠道、模型、Gateway 网关或工具配置块 +summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值以及指向专用子系统参考文档的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-25T23:50:21Z" + generated_at: "2026-04-26T00:16:04Z" model: gpt-5.4 provider: openai - source_hash: 6506e09f5bd8d45892bb519ebb66ee827967f785a11dda16e9aea4d941b7cfd1 + source_hash: 0c9019c54bb8fbeb9fa52312a8d97ea4481f4cb1bcb38bac745d726eaa648407 source_path: gateway/configuration-reference.md workflow: 15 --- -`~/.openclaw/openclaw.json` 的核心配置参考。若需按任务分类的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。 -涵盖 OpenClaw 的主要配置面，并在某个子系统有自己更深入的参考文档时提供外链。由渠道和插件拥有的命令目录，以及更深入的内存 / QMD 调节项，分别放在各自页面中，而不是集中在本页。 +本文档涵盖 OpenClaw 的主要配置面，并在某个子系统拥有更深入的独立参考时提供跳转链接。由渠道和插件自行管理的命令目录，以及更深层的 memory/QMD 调整项，均位于各自独立页面，而不在本页中展开。 代码事实来源： -- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置 / 插件 / 渠道元数据 -- `config.schema.lookup` 返回一个按路径限定作用域的 schema 节点，供深入查看工具使用 -- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面校验配置文档基线哈希 +- `openclaw config schema` 会输出用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 +- `config.schema.lookup` 会返回一个按路径范围限定的 schema 节点，供下钻工具使用 +- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 范围校验配置文档基线哈希 -专门的深度参考： +专用深入参考： -- [Memory configuration reference](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 -- [Slash commands](/zh-CN/tools/slash-commands)，适用于当前内置 + 内置打包的命令目录 -- 各自拥有渠道专属命令面的渠道 / 插件页面 +- [Memory configuration reference](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 +- [Slash commands](/zh-CN/tools/slash-commands)，适用于当前内建 + 内置命令目录 +- 适用于渠道专属命令面的对应渠道/插件页面 -配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。 +配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段均为可选 —— OpenClaw 在省略时会使用安全的默认值。 --- ## 渠道 -每个渠道的配置键已移至专门页面——请参见 -[Configuration — channels](/zh-CN/gateway/config-channels)，了解 `channels.*`， -包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 以及其他 -内置渠道（身份验证、访问控制、多账号、提及门控）。 +各渠道配置键已迁移到独立页面 —— 请参阅 +[配置 — 渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`， +其中包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 及其他 +内置渠道（认证、访问控制、多账号、提及门控）。 ## 智能体默认值、多智能体、会话和消息 -已移至专门页面——请参见 -[Configuration — agents](/zh-CN/gateway/config-agents)，内容包括： +已迁移到独立页面 —— 请参阅 +[配置 — 智能体](/zh-CN/gateway/config-agents)，内容包括： - `agents.defaults.*`（工作区、模型、思考、心跳、内存、媒体、Skills、沙箱） - `multiAgent.*`（多智能体路由与绑定） - `session.*`（会话生命周期、压缩、清理） -- `messages.*`（消息投递、TTS、Markdown 渲染） +- `messages.*`（消息传递、TTS、Markdown 渲染） - `talk.*`（Talk 模式） - - `talk.speechLocale`：Talk 在 iOS / macOS 上进行语音识别时可选的 BCP 47 locale id - - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保持平台默认的停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`） + - `talk.speechLocale`：iOS/macOS 上 Talk 语音识别可选的 BCP 47 locale id + - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录内容前保持平台默认的停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`） ## 工具和自定义提供商 工具策略、实验性开关、由提供商支持的工具配置，以及自定义 -提供商 / base-URL 设置已移至专门页面——请参见 -[Configuration — tools and custom providers](/zh-CN/gateway/config-tools)。 +provider / base-URL 设置已迁移到独立页面 —— 请参阅 +[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。 ## MCP 由 OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下， -供嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、 -`show`、`set` 和 `unset` 命令可管理该配置块，而无需在编辑配置时连接到 -目标服务器。 +并由嵌入式 Pi 及其他运行时适配器使用。`openclaw mcp list`、 +`show`、`set` 和 `unset` 命令可管理该配置块，并且在编辑配置时 +不会连接到目标服务器。 ```json5 { @@ -88,15 +88,15 @@ x-i18n: } ``` -- `mcp.servers`：为暴露已配置 MCP 工具的运行时提供命名的 stdio 或远程 MCP 服务器定义。 +- `mcp.servers`：供运行时使用的命名 stdio 或远程 MCP 服务器定义，这些运行时会暴露已配置的 MCP 工具。 - `mcp.sessionIdleTtlMs`：面向会话作用域的内置 MCP 运行时的空闲 TTL。 - 一次性嵌入式运行会请求在运行结束时清理；此 TTL 是面向 + 一次性嵌入式运行会请求在运行结束时清理；该 TTL 是对 长生命周期会话和未来调用方的兜底机制。 - `mcp.*` 下的更改会通过释放缓存的会话 MCP 运行时来热应用。 - 下一次工具发现 / 使用时会根据新配置重新创建它们，因此被移除的 - `mcp.servers` 条目会立即清理，而不是等待空闲 TTL 到期。 + 下一次工具发现/使用时会基于新配置重新创建它们，因此被移除的 + `mcp.servers` 条目会立即被回收，而不是等到空闲 TTL 到期。 -运行时行为请参见 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 +有关运行时行为，请参阅 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 [CLI backends](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)。 ## Skills @@ -124,14 +124,12 @@ x-i18n: } ``` -- `allowBundled`：仅针对内置 Skills 的可选允许列表（不影响托管 / 工作区 Skills）。 -- `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。 -- `install.preferBrew`：为 `true` 时，如果存在 `brew`， - 则优先使用 Homebrew 安装器，再回退到其他安装器类型。 -- `install.nodeManager`：`metadata.openclaw.install` - 规范的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使 Skill 已内置 / 安装，也会禁用该 Skill。 -- `entries..apiKey`：为声明主环境变量的 Skills 提供的便捷字段（明文字符串或 SecretRef 对象）。 +- `allowBundled`：仅适用于内置 Skills 的可选允许列表（不影响托管/工作区 Skills）。 +- `load.extraDirs`：额外的共享 skill 根目录（优先级最低）。 +- `install.preferBrew`：为 true 时，若 `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。 +- `install.nodeManager`：`metadata.openclaw.install` 规范使用的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使某个 skill 已内置/已安装，也会将其禁用。 +- `entries..apiKey`：为声明主环境变量的 skills 提供的便捷字段（明文字符串或 SecretRef 对象）。 --- @@ -159,50 +157,42 @@ x-i18n: } ``` -- 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 设备发现同时接受原生 OpenClaw 插件，以及兼容的 Codex bundles 和 Claude bundles，包括无 manifest 的 Claude 默认布局 bundles。 +- 加载来源包括 `~/.openclaw/extensions`、`/.openclaw/extensions`，以及 `plugins.load.paths`。 +- 设备发现支持原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，其中也包括无 manifest 的 Claude 默认布局 bundle。 - **配置更改需要重启 Gateway 网关。** -- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先生效。 -- `plugins.entries..apiKey`：插件级 API 密钥便捷字段（插件支持时可用）。 +- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（插件支持时可用）。 - `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子以及受支持的 bundle 提供钩子目录。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改 prompt 的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子，以及受支持 bundle 提供的 hook 目录。 - `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可从 `llm_input`、`llm_output` 和 `agent_end` 等类型化钩子中读取原始对话内容。 -- `plugins.entries..subagent.allowModelOverride`：显式信任此插件可为后台子智能体运行请求按次执行的 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖可用的规范 `provider/model` 目标的可选允许列表。仅当你确实想允许任意模型时才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（可用时由原生 OpenClaw 插件 schema 验证）。 -- 渠道插件的账号 / 运行时设置位于 `channels.` 下，应由所属插件 manifest 的 `channelConfigs` 元数据描述，而不是由一个集中式 OpenClaw 选项注册表描述。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 提供商设置。 - - `apiKey`：Firecrawl API 密钥（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 - - `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`）。 +- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可为后台子智能体运行请求按次执行的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖所允许的规范 `provider/model` 目标可选列表。仅当你确实希望允许任意模型时，才使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（若可用，会由原生 OpenClaw 插件 schema 验证）。 +- 渠道插件的账号/运行时设置位于 `channels.` 下，应由所属插件 manifest 中的 `channelConfigs` 元数据描述，而不是由集中式 OpenClaw 选项注册表描述。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl 网页抓取 provider 设置。 + - `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 环境变量。 + - `baseUrl`：Firecrawl API 基础 URL（默认：`https://api.firecrawl.dev`）。 - `onlyMainContent`：仅提取页面主体内容（默认：`true`）。 - - `maxAgeMs`：最大缓存时长（毫秒）（默认：`172800000` / 2 天）。 - - `timeoutSeconds`：抓取请求超时时间（秒）（默认：`60`）。 -- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web search）设置。 - - `enabled`：启用 X Search 提供商。 + - `maxAgeMs`：缓存最大时长（毫秒）（默认：`172800000` / 2 天）。 + - `timeoutSeconds`：抓取请求超时秒数（默认：`60`）。 +- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 + - `enabled`：启用 X Search provider。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。有关阶段和阈值，请参见 [Dreaming](/zh-CN/concepts/dreaming)。 +- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。阶段与阈值请参阅 [Dreaming](/zh-CN/concepts/dreaming)。 - `enabled`：dreaming 总开关（默认 `false`）。 - `frequency`：每次完整 dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。 - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 完整的内存配置位于 [Memory configuration reference](/zh-CN/reference/memory-config)： +- 完整 memory 配置位于 [Memory configuration reference](/zh-CN/reference/memory-config)： - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 已启用的 Claude bundle 插件也可通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为清洗后的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。 -- `plugins.slots.memory`：选择当前激活的 memory 插件 id，或设为 `"none"` 以禁用 memory 插件。 -- `plugins.slots.contextEngine`：选择当前激活的 context engine 插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 -- `plugins.installs`：已弃用的兼容性回退字段，用于旧版 - CLI 管理的安装元数据。新的插件安装会改为写入托管的 - `plugins/installs.json` 状态账本。 - - 旧版记录包括 `source`、`spec`、`sourcePath`、`installPath`、 - `version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、 - `shasum`、`resolvedAt`、`installedAt`。 - - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是 - 手动编辑。 +- 已启用的 Claude bundle 插件也可以通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为已净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择当前活动的 memory 插件 id，或设为 `"none"` 以禁用 memory 插件。 +- `plugins.slots.contextEngine`：选择当前活动的上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 -请参见 [Plugins](/zh-CN/tools/plugin)。 +请参阅 [插件](/zh-CN/tools/plugin)。 --- @@ -253,48 +243,48 @@ x-i18n: ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `tabCleanup` 会在空闲一段时间后，或当某个 - 会话超过其上限时，回收被跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为 - `0` 可分别禁用这些单独的清理模式。 -- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 为禁用状态，因此默认情况下浏览器导航保持严格限制。 -- 仅当你有意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性 / 设备发现检查期间也会受到相同的私有网络阻止。 +- `tabCleanup` 会在空闲超时后，或某个 + 会话超出其上限时，回收被跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为 + 0，可分别禁用这些单独的清理模式。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用状态，因此浏览器导航默认保持严格模式。 +- 仅当你明确信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间，同样会受到私有网络阻止策略的约束。 - `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 - 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 来配置显式例外。 -- 远程配置文件仅支持附加模式（禁用 start / stop / reset）。 +- 远程配置文件仅支持附加模式（禁用 start/stop/reset）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时，使用 HTTP(S)； - 当你的提供商直接提供 DevTools WebSocket URL 时，使用 WS(S)。 + 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)；使用 WS(S) + 则适用于你的提供商直接给出 DevTools WebSocket URL 的情况。 - `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程和 - `attachOnly` CDP 的可达性检查以及标签页打开请求。受管的 loopback - 配置文件仍使用本地 CDP 默认值。 + `attachOnly` CDP 可达性，以及打开标签页请求。受管的 loopback + 配置文件则保留本地 CDP 默认值。 - 如果某个外部管理的 CDP 服务可通过 loopback 访问，请将该 - 配置文件的 `attachOnly: true` 设为 `true`；否则 OpenClaw 会将该 loopback 端口视为 - 本地受管浏览器配置文件，并可能报告本地端口归属错误。 -- `existing-session` 配置文件使用 Chrome MCP 而非 CDP，并且可以附加到 + 配置文件的 `attachOnly: true` 打开；否则 OpenClaw 会将该 loopback 端口视为 + 本地受管浏览器配置文件，并可能报告本地端口占用错误。 +- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以附加到 所选主机上，或通过已连接的浏览器节点附加。 -- `existing-session` 配置文件可以设置 `userDataDir`，以指向特定的 - 基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。 -- `existing-session` 配置文件保留当前 Chrome MCP 的路由限制： - 使用 snapshot / ref 驱动的操作，而不是 CSS 选择器定位；单文件上传 - 钩子；不支持对话框超时覆盖；不支持 `wait --load networkidle`；也不支持 +- `existing-session` 配置文件可以设置 `userDataDir`，以指定某个特定的 + Chromium 内核浏览器配置文件，例如 Brave 或 Edge。 +- `existing-session` 配置文件保留当前 Chrome MCP 路由限制： + 使用 snapshot/ref 驱动的操作而非 CSS-selector 定位，单文件上传 + hooks，不支持对话框超时覆盖，不支持 `wait --load networkidle`，也不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地受管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下 - 才需显式设置 `cdpUrl`。 -- 本地受管配置文件可设置 `executablePath`，以覆盖该配置文件的全局 - `browser.executablePath`。用它可让一个配置文件运行在 - Chrome 中，另一个运行在 Brave 中。 -- 本地受管配置文件在进程启动后，使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP - 发现，并使用 `browser.localCdpReadyTimeoutMs` 检查 - 启动后 CDP websocket 就绪状态。在主机较慢、Chrome 虽然成功启动但就绪检查与启动竞态时， - 请调高这两个值。两个值都必须是 - 不超过 `120000` ms 的正整数；无效配置值会被拒绝。 -- 自动检测顺序：默认浏览器（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 本地受管 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下 + 才需要显式设置 `cdpUrl`。 +- 本地受管配置文件可以设置 `executablePath` 以覆盖该配置文件的全局 + `browser.executablePath`。你可以用它让一个配置文件运行在 + Chrome 中，而另一个运行在 Brave 中。 +- 本地受管配置文件在进程启动后，会使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP + 设备发现，并使用 `browser.localCdpReadyTimeoutMs` 进行 + 启动后 CDP websocket 就绪检查。在较慢的主机上，如果 Chrome 虽然成功启动， + 但就绪检查与启动过程发生竞争，请提高这两个值。这两个值都必须是 + 不超过 `120000` ms 的正整数；无效的配置值会被拒绝。 +- 自动检测顺序：默认浏览器（若为 Chromium 内核）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 - `browser.executablePath` 和 `browser.profiles..executablePath` 都 - 接受 `~` 和 `~/...`，并会在启动 Chromium 前解析为你的操作系统主目录。 - `existing-session` 配置文件上的逐配置文件 `userDataDir` 也支持波浪号展开。 -- 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认值为 `18791`）。 -- `extraArgs` 会为本地 Chromium 启动追加额外的启动标志（例如 + 支持在 Chromium 启动前，将 `~` 和 `~/...` 展开为你的操作系统主目录。 + `existing-session` 配置文件上的按配置文件 `userDataDir` 也会进行波浪线展开。 +- 控制服务：仅限 loopback（端口由 `gateway.port` 派生，默认值为 `18791`）。 +- `extraArgs` 会将额外的启动标志追加到本地 Chromium 启动参数中（例如 `--disable-gpu`、窗口大小设置或调试标志）。 --- @@ -313,8 +303,8 @@ x-i18n: } ``` -- `seamColor`：原生应用 UI 外框的强调色（Talk Mode 气泡着色等）。 -- `assistant`：Control UI 身份覆盖。回退到当前激活智能体的身份。 +- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。 +- `assistant`：Control UI 身份覆盖设置。默认回退到当前活动智能体身份。 --- @@ -389,53 +379,54 @@ x-i18n: } ``` - + -- `mode`：`local`（运行 gateway）或 `remote`（连接到远程 gateway）。只有在 `local` 模式下，Gateway 网关 才允许启动。 -- `port`：用于 WS + HTTP 的单一多路复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 +- `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 - **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会从 `eth0` 到达，因此 Gateway 网关 不可访问。请使用 `--network host`，或设置 `bind: "lan"`（或设置 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有接口。 -- **身份验证**：默认必需。非 loopback bind 要求启用 gateway 身份验证。实际来说，这意味着使用共享 token / password，或使用设置了 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成一个 token。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请将 `gateway.auth.mode` 明确设为 `token` 或 `password`。如果两者都已配置但未设置 mode，启动以及服务安装 / 修复流程都会失败。 -- `gateway.auth.mode: "none"`：显式无身份验证模式。仅用于受信任的本地 local loopback 设置；新手引导提示中有意不提供此选项。 -- `gateway.auth.mode: "trusted-proxy"`：将身份验证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份标头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 代理来源；同主机 loopback 反向代理不满足 trusted-proxy 身份验证要求。 -- `gateway.auth.allowTailscale`：设为 `true` 时，Tailscale Serve 身份标头可以满足 Control UI / WebSocket 身份验证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头身份验证；它们仍遵循 gateway 的常规 HTTP 身份验证模式。这个无 token 流程假定 gateway 主机受信任。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的身份验证失败限速器。按客户端 IP 和身份验证作用域生效（共享密钥和设备 token 分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，来自同一 `{scope, clientIp}` 的失败尝试会在写入失败记录之前串行化处理。因此，同一客户端的并发错误尝试，可能会在第二个请求时触发限速器，而不是两个请求都像普通不匹配那样竞态通过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；如果你确实希望对 localhost 流量也进行限速（例如测试环境或严格代理部署），请设为 `false`。 -- 来自浏览器来源的 WS 身份验证尝试始终会启用限速，且禁用 loopback 豁免（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 -- 在 loopback 上，这些来自浏览器来源的锁定会按规范化后的 `Origin` - 值隔离，因此来自某个 localhost origin 的重复失败不会自动 - 锁定另一个 origin。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，要求身份验证）。 -- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期有来自非 loopback 来源的浏览器客户端时，此项为必需。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 标头来源策略的部署启用 Host 标头来源回退。 -- `remote.transport`：`ssh`（默认）或 `direct`（ws / wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境变量级别的紧急放行开关，允许对受信任私有网络 - IP 使用明文 `ws://`；默认仍仅允许 loopback 使用明文连接。没有与之对应的 `openclaw.json` - 配置项，浏览器私有网络配置（例如 - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`）也不会影响 Gateway 网关 +- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关将无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有网络接口。 +- **认证**：默认必须启用。非 loopback bind 需要 Gateway 网关认证。实际中，这意味着使用共享 token/password，或使用设置了 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请将 `gateway.auth.mode` 显式设置为 `token` 或 `password`。当两者都已配置但未设置 mode 时，启动以及服务安装/修复流程都会失败。 +- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 配置；新手引导提示中不会提供此选项。 +- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求 **非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy 认证要求。 +- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve 身份头可满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点 **不会** 使用该 Tailscale 头认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。当 `tailscale.mode = "serve"` 时，默认值为 `true`。这种无 token 流程假定 Gateway 网关主机是受信任的。 +- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证范围生效（共享密钥和设备 token 分别独立跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败记录前被串行化。因此，来自同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个请求都作为普通不匹配同时穿过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；当你明确希望 localhost 流量也受到限流时（用于测试配置或严格代理部署），请设为 `false`。 +- 来自浏览器源的 WS 认证尝试始终会在禁用 loopback 豁免的情况下被限流（作为对基于浏览器的 localhost 暴力破解的纵深防御）。 +- 在 loopback 上，这些来自浏览器源的锁定会按标准化后的 `Origin` + 值隔离，因此某个 localhost origin 的重复失败不会自动 + 锁定另一个不同的 origin。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开访问，需要认证）。 +- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当预期浏览器客户端来自非 loopback 源时，这是必需项。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 头 origin 策略的部署启用基于 Host 头的 origin 回退。 +- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。当使用 `direct` 时，`remote.url` 必须是 `ws://` 或 `wss://`。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境变量级别的 + 紧急放行覆盖项，允许对受信任私有网络 + IP 使用明文 `ws://`；默认情况下，明文仍仅限 loopback。没有对应的 `openclaw.json` + 配置项，且浏览器私有网络配置，例如 + `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`，不会影响 Gateway 网关 WebSocket 客户端。 -- `gateway.remote.token` / `.password`：远程客户端凭证字段。它们本身不会配置 gateway 身份验证。 -- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方版 / TestFlight iOS 构建在将基于 relay 的注册发布到 gateway 后使用。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。 -- `gateway.push.apns.relay.timeoutMs`：gateway 到 relay 的发送超时时间（毫秒）。默认值为 `10000`。 -- 基于 relay 的注册会委托给特定的 gateway 身份。配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将注册作用域的发送授权转发给 gateway。另一个 gateway 不能复用该已存储注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：对上述 relay 配置的临时环境变量覆盖。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发的逃生开关，允许使用 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。 -- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔，单位为分钟。设为 `0` 可全局禁用健康监控重启。默认值：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：陈旧套接字阈值，单位为分钟。应保持大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 -- `gateway.channelMaxRestartsPerHour`：每个渠道 / 账号在滚动一小时内允许的最大健康监控重启次数。默认值：`10`。 -- `channels..healthMonitor.enabled`：逐渠道选择退出健康监控重启，同时保持全局监控启用。 -- `channels..accounts..healthMonitor.enabled`：多账号渠道的逐账号覆盖。设置后，其优先级高于渠道级覆盖。 -- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关 调用路径才可将 `gateway.remote.*` 用作回退。 -- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password`，但未能解析，则解析会以封闭失败方式处理（不会被远程回退掩盖）。 -- `trustedProxies`：终止 TLS 或注入转发客户端标头的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理 / 本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**使 loopback 请求满足 `gateway.auth.mode: "trusted-proxy"`。 -- `allowRealIpFallback`：设为 `true` 时，如果缺少 `X-Forwarded-For`，gateway 会接受 `X-Real-IP`。默认值为 `false`，以保持封闭失败行为。 -- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR / IP 允许列表，用于自动批准未请求任何作用域的首次节点设备配对。未设置时禁用。它不会自动批准 operator / browser / Control UI / WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。 -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和允许列表评估之后，对已声明节点命令进行全局允许 / 拒绝整形。 +- `gateway.remote.token` / `.password`：远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 +- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方/TestFlight iOS 构建在向 Gateway 网关发布基于 relay 的注册后使用。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。 +- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值为 `10000`。 +- 基于 relay 的注册会委托给某个特定 Gateway 网关身份。配对后的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将一个基于注册范围的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储注册。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：用于上述 relay 配置的临时环境变量覆盖项。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅限开发环境的逃生口，用于 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。 +- `gateway.channelHealthCheckMinutes`：渠道健康监视器的时间间隔（分钟）。设为 `0` 可在全局禁用基于健康监视器的重启。默认值：`5`。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelMaxRestartsPerHour`：滚动一小时内每个渠道/账号允许的健康监视器最大重启次数。默认值：`10`。 +- `channels..healthMonitor.enabled`：渠道级退出选项，可在保持全局监视器启用的同时，关闭该渠道的健康监视器重启。 +- `channels..accounts..healthMonitor.enabled`：多账号渠道的账号级覆盖项。设置后，其优先级高于渠道级覆盖项。 +- 本地 Gateway 网关调用路径仅会在 `gateway.auth.*` 未设置时，使用 `gateway.remote.*` 作为回退。 +- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但无法解析，则解析会以关闭方式失败（不会用远程回退来掩盖问题）。 +- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。仅列出你控制的代理。loopback 条目对于同主机代理/本地检测配置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们 **不会** 让 loopback 请求具备使用 `gateway.auth.mode: "trusted-proxy"` 的资格。 +- `allowRealIpFallback`：当为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关将接受 `X-Real-IP`。默认值为 `false`，以保持失败关闭行为。 +- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于对首次节点设备配对且未请求任何作用域的情况自动批准。未设置时为禁用状态。它不会自动批准 operator/browser/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。 +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和 allowlist 评估之后，对已声明节点命令进行全局允许/拒绝整形。 - `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认拒绝列表）。 -- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。 +- `gateway.tools.allow`：将工具名称从默认 HTTP 拒绝列表中移除。 @@ -448,13 +439,13 @@ x-i18n: - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` 空允许列表会被视为未设置；请使用 `gateway.http.endpoints.responses.files.allowUrl=false` - 和 / 或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 获取。 -- 可选的响应加固标头： - - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 来源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） + 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 抓取。 +- 可选的响应加固头： + - `gateway.http.securityHeaders.strictTransportSecurity`（仅在你控制的 HTTPS 源上设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 -在同一主机上运行多个 gateway，并使用唯一端口和状态目录： +通过使用唯一的端口和状态目录，在同一主机上运行多个 Gateway 网关： ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -462,9 +453,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile `（使用 `~/.openclaw-`）。 +便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`），`--profile `（使用 `~/.openclaw-`）。 -请参见 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。 +请参阅 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。 ### `gateway.tls` @@ -482,11 +473,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`：在 gateway 监听器处启用 TLS 终止（HTTPS / WSS）（默认：`false`）。 -- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书 / 密钥对；仅供本地 / 开发使用。 +- `enabled`：在 Gateway 网关监听器处启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 +- `autoGenerate`：当未配置显式文件时，自动生成本地自签名 cert/key 对；仅适用于本地/开发用途。 - `certPath`：TLS 证书文件的文件系统路径。 -- `keyPath`：TLS 私钥文件的文件系统路径；请保持权限受限。 -- `caPath`：可选的 CA bundle 路径，用于客户端校验或自定义信任链。 +- `keyPath`：TLS 私钥文件的文件系统路径；请限制其访问权限。 +- `caPath`：可选的 CA bundle 路径，用于客户端验证或自定义信任链。 ### `gateway.reload` @@ -502,13 +493,13 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制配置编辑在运行时的应用方式。 +- `mode`：控制在运行时如何应用配置编辑。 - `"off"`：忽略实时编辑；更改需要显式重启。 - - `"restart"`：配置变更时总是重启 gateway 进程。 - - `"hot"`：在进程内应用更改而不重启。 - - `"hybrid"`（默认）：先尝试热重载；如有需要则回退到重启。 -- `debounceMs`：应用配置变更前的防抖窗口，单位为毫秒（非负整数）。 -- `deferralTimeoutMs`：可选的最大等待时间，单位为毫秒，用于等待正在进行中的操作完成，超过后强制重启。省略或设为 `0` 表示无限等待，并定期记录“仍在等待中”的警告。 + - `"restart"`：配置变更时始终重启 Gateway 网关进程。 + - `"hot"`：不重启，直接在进程内应用更改。 + - `"hybrid"`（默认）：先尝试热重载；如有需要则回退为重启。 +- `debounceMs`：应用配置更改前的防抖窗口（毫秒）（非负整数）。 +- `deferralTimeoutMs`：可选的最大等待时间（毫秒），用于等待正在进行中的操作完成，超时后将强制重启。省略此项或设为 `0` 表示无限等待，并定期记录仍在等待中的警告日志。 --- @@ -545,47 +536,47 @@ openclaw gateway --port 19001 } ``` -身份验证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 -拒绝使用查询字符串 hook token。 +认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 +查询字符串中的 hook token 会被拒绝。 验证和安全说明： -- `hooks.enabled=true` 要求 `hooks.token` 为非空。 -- `hooks.token` 必须与 `gateway.auth.token` **不同**；重复使用 Gateway 网关 token 会被拒绝。 -- `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。 +- `hooks.enabled=true` 要求提供非空的 `hooks.token`。 +- `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关 token 会被拒绝。 +- `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。 - 如果 `hooks.allowRequestSessionKey=true`，请限制 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 -- 如果某个映射或 preset 使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要此显式启用。 +- 如果某个映射或 preset 使用了模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要此显式启用。 **端点：** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - 仅当 `hooks.allowRequestSessionKey=true`（默认：`false`）时，才接受来自请求负载的 `sessionKey`。 + - 仅当 `hooks.allowRequestSessionKey=true` 时（默认：`false`），才接受请求负载中的 `sessionKey`。 - `POST /hooks/` → 通过 `hooks.mappings` 解析 - - 通过模板渲染得到的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。 + - 通过模板渲染的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。 -- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 -- `match.source` 匹配通用路径的某个负载字段。 -- 类似 `{{messages[0].subject}}` 这样的模板会从负载中读取。 -- `transform` 可以指向一个返回 hook action 的 JS / TS 模块。 - - `transform.module` 必须是相对路径，并且需保持在 `hooks.transformsDir` 之内（绝对路径和路径穿越会被拒绝）。 +- `match.path` 会匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 +- `match.source` 会匹配通用路径中的某个负载字段。 +- 类似 `{{messages[0].subject}}` 的模板会从负载中读取。 +- `transform` 可以指向一个返回 hook 动作的 JS/TS 模块。 + - `transform.module` 必须是相对路径，并且必须位于 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。 - `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。 - `defaultSessionKey`：可选的固定会话键，用于没有显式 `sessionKey` 的 hook 智能体运行。 -- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动映射的会话键设置 `sessionKey`（默认：`false`）。 -- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任一映射或 preset 使用模板化 `sessionKey` 时，它就成为必需项。 -- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 -- `model` 会为本次 hook 运行覆盖 LLM（如果设置了模型目录，则该模型必须被允许）。 +- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。 +- `allowedSessionKeyPrefixes`：对显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或 preset 使用模板化 `sessionKey` 时，它就变为必填项。 +- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认值为 `last`。 +- `model` 会覆盖本次 hook 运行的 LLM（如果设置了模型目录，则必须是被允许的模型）。 ### Gmail 集成 -- 内置的 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 -- 如果你保留这种按消息路由方式，请设置 `hooks.allowRequestSessionKey: true`，并将 `hooks.allowedSessionKeyPrefixes` 限制为匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 -- 如果你需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖 preset，而不要使用其默认的模板化值。 +- 内置 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 +- 如果你保留这种按消息路由的方式，请设置 `hooks.allowRequestSessionKey: true`，并限制 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 +- 如果你需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖该 preset，而不是使用默认的模板化值。 ```json5 { @@ -608,8 +599,8 @@ openclaw gateway --port 19001 } ``` -- 配置后，Gateway 网关 会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 -- 不要在 Gateway 网关 旁边单独运行另一个 `gog gmail watch serve`。 +- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 +- 不要在 Gateway 网关运行的同时，单独运行另一个 `gog gmail watch serve`。 --- @@ -625,18 +616,18 @@ openclaw gateway --port 19001 } ``` -- 通过 Gateway 网关 端口下的 HTTP 提供智能体可编辑的 HTML / CSS / JS 和 A2UI： +- 在 Gateway 网关端口下，通过 HTTP 提供可由智能体编辑的 HTML/CSS/JS 和 A2UI： - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- 仅限本地：保持 `gateway.bind: "loopback"`（默认）。 -- 非 loopback bind：canvas 路由需要 Gateway 网关 身份验证（token / password / trusted-proxy），与其他 Gateway 网关 HTTP 面一致。 -- Node WebView 通常不会发送身份验证标头；节点完成配对并连接后，Gateway 网关 会为 canvas / A2UI 访问通告节点作用域的能力 URL。 -- 能力 URL 绑定到当前活动的节点 WS 会话，并且会很快过期。不使用基于 IP 的回退。 -- 会将 live-reload 客户端注入到所提供的 HTML 中。 -- 为空时会自动创建起始 `index.html`。 -- 也会在 `/__openclaw__/a2ui/` 下提供 A2UI。 +- 仅限本地：请保持 `gateway.bind: "loopback"`（默认）。 +- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 面相同，要求 Gateway 网关认证（token/password/trusted-proxy）。 +- 节点 WebView 通常不会发送认证头；在某个节点完成配对并连接后，Gateway 网关会通告节点作用域的能力 URL，供访问 canvas/A2UI 使用。 +- 能力 URL 绑定到当前活动的节点 WS 会话，并且会很快过期。不使用基于 IP 的回退方式。 +- 会向所提供的 HTML 中注入实时重载客户端。 +- 当目录为空时，会自动创建初始 `index.html`。 +- 同时也会在 `/__openclaw__/a2ui/` 提供 A2UI。 - 更改需要重启 Gateway 网关。 -- 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。 +- 如果目录较大或出现 `EMFILE` 错误，请禁用实时重载。 --- @@ -654,8 +645,8 @@ openclaw gateway --port 19001 } ``` -- `minimal`（默认）：从 TXT 记录中省略 `cliPath` + `sshPort`。 -- `full`：包含 `cliPath` + `sshPort`。 +- `minimal`（默认）：在 TXT 记录中省略 `cliPath` 和 `sshPort`。 +- `full`：包含 `cliPath` 和 `sshPort`。 - 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 ### 广域（DNS-SD） @@ -668,7 +659,7 @@ openclaw gateway --port 19001 } ``` -会在 `~/.openclaw/dns/` 下写入一个单播 DNS-SD 区域。若要进行跨网络设备发现，请配合 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。 +会在 `~/.openclaw/dns/` 下写入一个单播 DNS-SD 区域。对于跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）和 Tailscale split DNS。 设置：`openclaw dns setup --apply`。 @@ -694,13 +685,13 @@ openclaw gateway --port 19001 ``` - 仅当进程环境中缺少对应键时，才会应用内联环境变量。 -- `.env` 文件：当前工作目录的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 +- `.env` 文件：当前工作目录下的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 - `shellEnv`：从你的登录 shell profile 中导入缺失的预期键名。 -- 完整优先级请参见 [Environment](/zh-CN/help/environment)。 +- 完整优先级请参阅 [Environment](/zh-CN/help/environment)。 ### 环境变量替换 -可在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： +可以在任何配置字符串中通过 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -711,37 +702,37 @@ openclaw gateway --port 19001 ``` - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失 / 为空的变量会在加载配置时报错。 -- 使用 `$${VAR}` 转义，以得到字面量 `${VAR}`。 -- 对 `$include` 同样有效。 +- 缺失或为空的变量会在加载配置时抛出错误。 +- 使用 `$${VAR}` 可转义为字面量 `${VAR}`。 +- 适用于 `$include`。 --- ## Secrets -SecretRef 是增量式的：明文值仍然可用。 +SecretRef 为增量能力：明文值仍然可用。 ### `SecretRef` -使用以下对象结构之一： +使用以下对象结构： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } ``` -校验规则： +验证规则： - `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$` -- `source: "env"` 的 `id` 模式：`^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` 的 `id`：绝对 JSON pointer（例如 `"/providers/openai/apiKey"`） -- `source: "exec"` 的 `id` 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"` 的 `id` 不得包含以斜杠分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝） +- `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` +- `source: "file"` 的 id：绝对 JSON pointer（例如 `"/providers/openai/apiKey"`） +- `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- `source: "exec"` 的 id 不得包含 `.` 或 `..` 这样的以斜杠分隔的路径段（例如 `a/../b` 会被拒绝） ### 支持的凭证面 -- 规范矩阵：[SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) +- 规范矩阵： [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) - `secrets apply` 会作用于受支持的 `openclaw.json` 凭证路径。 -- `auth-profiles.json` 中的引用也包含在运行时解析和审计覆盖范围内。 +- `auth-profiles.json` 中的 refs 也包含在运行时解析和审计覆盖范围内。 ### Secret providers 配置 @@ -773,18 +764,18 @@ SecretRef 是增量式的：明文值仍然可用。 说明： -- `file` provider 支持 `mode: "json"` 和 `mode: "singleValue"`（在 `singleValue` 模式下，`id` 必须为 `"value"`）。 -- 当 Windows ACL 校验不可用时，file 和 exec provider 路径会以封闭失败方式处理。仅对无法验证但受信任的路径设置 `allowInsecurePath: true`。 -- `exec` provider 要求使用绝对 `command` 路径，并通过 stdin / stdout 上的协议负载进行通信。 -- 默认情况下，符号链接 command 路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时校验解析后的目标路径。 -- 如果配置了 `trustedDirs`，则受信任目录检查会作用于解析后的目标路径。 -- `exec` 子进程环境默认最小化；请通过 `passEnv` 显式传递所需变量。 -- Secret 引用会在激活时解析为内存快照，之后请求路径只读取该快照。 -- 激活期间会应用活动面过滤：已启用面的未解析引用会导致启动 / 重载失败，而非活动面会被跳过并附带诊断信息。 +- `file` provider 支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 +- 当无法验证 Windows ACL 时，file 和 exec provider 路径会以关闭方式失败。仅当路径受信任但无法验证时，才设置 `allowInsecurePath: true`。 +- `exec` provider 要求使用绝对 `command` 路径，并通过 stdin/stdout 传递协议负载。 +- 默认情况下，符号链接 command 路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时验证其解析后的目标路径。 +- 如果配置了 `trustedDirs`，则受信任目录检查会应用到解析后的目标路径。 +- `exec` 子进程环境默认最小化；请通过 `passEnv` 显式传入所需变量。 +- Secret refs 会在激活时解析为内存快照，之后请求路径只会读取该快照。 +- 激活期间会应用活动表面过滤：已启用表面上的未解析 refs 会导致启动/重载失败，而非活动表面会被跳过并输出诊断信息。 --- -## Auth 存储 +## 认证存储 ```json5 { @@ -802,13 +793,13 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- 每个智能体的配置文件存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持值级引用（静态凭证模式下，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 -- OAuth 模式配置文件（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 -- 静态运行时凭证来自内存中的解析快照；发现旧版静态 `auth.json` 条目时会进行清理。 +- 每个智能体的 profile 存储在 `/auth-profiles.json`。 +- `auth-profiles.json` 支持值级 refs（静态凭证模式下，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- OAuth 模式 profile（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 +- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会将其清理。 - 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。 -- 请参见 [OAuth](/zh-CN/concepts/oauth)。 -- Secrets 的运行时行为以及 `audit/configure/apply` 工具：请参见 [Secrets Management](/zh-CN/gateway/secrets)。 +- 参见 [OAuth](/zh-CN/concepts/oauth)。 +- Secrets 运行时行为以及 `audit/configure/apply` 工具：参见 [Secrets Management](/zh-CN/gateway/secrets)。 ### `auth.cooldowns` @@ -830,20 +821,20 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `billingBackoffHours`：当配置文件因真正的 - 计费 / 余额不足错误而失败时的基础退避时长（小时）（默认：`5`）。即使在 `401` / `403` 响应中，明确的计费文本 - 也仍可能落入这里，但提供商特定文本 - 匹配器仍然限定在拥有它们的提供商范围内（例如 OpenRouter 的 - `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或 - 组织 / 工作区支出限制消息则仍然归入 `rate_limit` 路径。 -- `billingBackoffHoursByProvider`：可选的逐提供商计费退避时长覆盖（单位：小时）。 -- `billingMaxHours`：计费退避指数增长的上限（单位：小时）（默认：`24`）。 -- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时长（分钟）（默认：`10`）。 -- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限（分钟）（默认：`60`）。 -- `failureWindowHours`：用于退避计数器的滚动窗口（小时）（默认：`24`）。 -- `overloadedProfileRotations`：因过载错误而切换到模型回退前，同一提供商 auth-profile 允许的最大轮换次数（默认：`1`）。像 `ModelNotReadyException` 这样的提供商繁忙形态归入此项。 -- `overloadedBackoffMs`：在重试某个过载提供商 / 配置文件轮换前的固定延迟（默认：`0`）。 -- `rateLimitedProfileRotations`：因速率限制错误而切换到模型回退前，同一提供商 auth-profile 允许的最大轮换次数（默认：`1`）。该速率限制桶包括提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 +- `billingBackoffHours`：当某个 profile 因真实的 + 计费/余额不足错误而失败时使用的基础退避时间（小时）（默认：`5`）。即使是在 `401`/`403` 响应上，明确的计费相关文本 + 仍可能归入此类，但 provider 专属文本 + 匹配器仍只作用于拥有它们的 provider（例如 OpenRouter + `Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或 + organization/workspace 支出上限消息则仍归入 `rate_limit` 路径。 +- `billingBackoffHoursByProvider`：可选的按 provider 覆盖的计费退避小时数。 +- `billingMaxHours`：计费退避指数增长的小时上限（默认：`24`）。 +- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时间（分钟）（默认：`10`）。 +- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的分钟上限（默认：`60`）。 +- `failureWindowHours`：用于退避计数器的滚动时间窗口（小时）（默认：`24`）。 +- `overloadedProfileRotations`：对于过载错误，在切换到模型回退之前，同一 provider 的 auth-profile 最多轮换次数（默认：`1`）。像 `ModelNotReadyException` 这样的 provider 繁忙形态会归入这里。 +- `overloadedBackoffMs`：在重试过载 provider/profile 轮换前的固定延迟（默认：`0`）。 +- `rateLimitedProfileRotations`：对于限流错误，在切换到模型回退之前，同一 provider 的 auth-profile 最多轮换次数（默认：`1`）。该限流桶包括 provider 形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 --- @@ -865,7 +856,7 @@ SecretRef 是增量式的：明文值仍然可用。 - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 - 设置 `logging.file` 可使用稳定路径。 - 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 -- `maxFileBytes`：在抑制写入之前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 +- `maxFileBytes`：在抑制写入前，日志文件允许的最大大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 --- @@ -910,23 +901,23 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：插桩输出的总开关（默认：`true`）。 -- `flags`：用于启用定向日志输出的标志字符串数组（支持如 `"telegram.*"` 或 `"*"` 这样的通配符）。 -- `stuckSessionWarnMs`：当会话持续处于处理中状态时，发出卡住会话警告的时长阈值（毫秒）。 -- `otel.enabled`：启用 OpenTelemetry 导出管道（默认：`false`）。完整配置、信号目录和隐私模型请参见 [OpenTelemetry export](/zh-CN/gateway/opentelemetry)。 +- `enabled`：instrumentation 输出的总开关（默认：`true`）。 +- `flags`：用于启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 这类通配符）。 +- `stuckSessionWarnMs`：当某个会话持续处于处理中状态时，发出卡住会话警告的时长阈值（毫秒）。 +- `otel.enabled`：启用 OpenTelemetry 导出流水线（默认：`false`）。完整配置、信号目录和隐私模型请参阅 [OpenTelemetry export](/zh-CN/gateway/opentelemetry)。 - `otel.endpoint`：用于 OTel 导出的 collector URL。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 -- `otel.headers`：随 OTel 导出请求发送的额外 HTTP / gRPC 元数据标头。 -- `otel.serviceName`：资源属性中的服务名称。 +- `otel.headers`：随 OTel 导出请求一起发送的额外 HTTP/gRPC 元数据头。 +- `otel.serviceName`：资源属性的服务名称。 - `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。 - `otel.sampleRate`：trace 采样率，范围 `0`–`1`。 -- `otel.flushIntervalMs`：定期刷新遥测数据的间隔（毫秒）。 -- `otel.captureContent`：为 OTEL span 属性选择性启用原始内容捕获。默认关闭。布尔值 `true` 会捕获非系统消息 / 工具内容；对象形式可让你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：环境变量开关，用于启用最新的实验性 GenAI span provider 属性。默认情况下，span 会保留旧版 `gen_ai.system` 属性以保持兼容；GenAI metrics 使用有界语义属性。 -- `OPENCLAW_OTEL_PRELOADED=1`：环境变量开关，适用于已注册全局 OpenTelemetry SDK 的主机。此时 OpenClaw 会跳过由插件拥有的 SDK 启动 / 关闭流程，同时保持诊断监听器处于活动状态。 -- `cacheTrace.enabled`：为嵌入式运行记录缓存追踪快照（默认：`false`）。 -- `cacheTrace.filePath`：缓存追踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存追踪输出中包含哪些内容（默认全部为 `true`）。 +- `otel.flushIntervalMs`：定期刷新遥测数据的时间间隔（毫秒）。 +- `otel.captureContent`：用于 OTEL span 属性的原始内容捕获显式启用项。默认关闭。布尔值 `true` 会捕获非 system 消息/工具内容；对象形式则可让你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：环境变量开关，用于启用最新实验性 GenAI span provider 属性。默认情况下，span 会保留旧版 `gen_ai.system` 属性以保持兼容；GenAI metrics 则使用有界语义属性。 +- `OPENCLAW_OTEL_PRELOADED=1`：环境变量开关，适用于宿主环境已注册全局 OpenTelemetry SDK 的场景。此时 OpenClaw 会跳过插件自有 SDK 的启动/关闭，同时保持诊断监听器处于活动状态。 +- `cacheTrace.enabled`：为嵌入式运行记录缓存 trace 快照（默认：`false`）。 +- `cacheTrace.filePath`：缓存 trace JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存 trace 输出中包含哪些内容（默认均为 `true`）。 --- @@ -948,12 +939,12 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `channel`：用于 npm / git 安装的发布渠道——`"stable"`、`"beta"` 或 `"dev"`。 -- `checkOnStart`：gateway 启动时检查 npm 更新（默认：`true`）。 -- `auto.enabled`：为 package 安装启用后台自动更新（默认：`false`）。 +- `channel`：npm/git 安装的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 +- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认：`true`）。 +- `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。 - `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟（小时）（默认：`6`；最大：`168`）。 -- `auto.stableJitterHours`：stable 渠道额外的发布分散窗口（小时）（默认：`12`；最大：`168`）。 -- `auto.betaCheckIntervalHours`：beta 渠道检查运行的频率（小时）（默认：`1`；最大：`24`）。 +- `auto.stableJitterHours`：stable 渠道额外的发布扩散时间窗口（小时）（默认：`12`；最大：`168`）。 +- `auto.betaCheckIntervalHours`：beta 渠道检查运行频率（小时）（默认：`1`；最大：`24`）。 --- @@ -986,23 +977,23 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：全局 ACP 功能开关（默认：`true`；设为 `false` 可隐藏 ACP 分发和 spawn 入口）。 -- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 -- `backend`：默认 ACP 运行时后端 id（必须与已注册的 ACP 运行时插件匹配）。 - 如果设置了 `plugins.allow`，请包含后端插件 id（例如 `acpx`），否则内置的默认插件将不会加载。 -- `defaultAgent`：当 spawn 未指定显式目标时，使用的 ACP 默认目标智能体 id。 -- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；为空表示无额外限制。 -- `maxConcurrentSessions`：同时活跃的 ACP 会话最大数量。 +- `enabled`：全局 ACP 功能门控（默认：`true`；设为 `false` 可隐藏 ACP 分发和 spawn 入口）。 +- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认：`true`）。设为 `false` 可在阻止执行的同时保留 ACP 命令可用。 +- `backend`：默认 ACP 运行时 backend id（必须匹配已注册的 ACP 运行时插件）。 + 如果设置了 `plugins.allow`，则必须包含 backend 插件 id（例如 `acpx`），否则内置默认插件将不会加载。 +- `defaultAgent`：当 spawn 未指定显式目标时使用的 ACP 目标智能体 id。 +- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；空数组表示不添加额外限制。 +- `maxConcurrentSessions`：最大并发活动 ACP 会话数。 - `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口（毫秒）。 -- `stream.maxChunkChars`：在拆分流式分块投影前允许的最大分块大小。 -- `stream.repeatSuppression`：每轮抑制重复的状态 / 工具行（默认：`true`）。 -- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲到轮次终止事件后再输出。 -- `stream.hiddenBoundarySeparator`：在隐藏工具事件后的可见文本前使用的分隔符（默认：`"paragraph"`）。 -- `stream.maxOutputChars`：每个 ACP 轮次投影的智能体输出最大字符数。 -- `stream.maxSessionUpdateChars`：投影的 ACP 状态 / 更新行最大字符数。 -- `stream.tagVisibility`：记录 tag 名称到布尔可见性覆盖的映射，用于流式事件。 -- `runtime.ttlMinutes`：ACP 会话工作进程在符合清理条件前的空闲 TTL（分钟）。 -- `runtime.installCommand`：在引导 ACP 运行时环境时运行的可选安装命令。 +- `stream.maxChunkChars`：在拆分流式分块投影前的最大分块大小。 +- `stream.repeatSuppression`：每轮抑制重复的状态/工具行（默认：`true`）。 +- `stream.deliveryMode`：`"live"` 表示增量流式输出；`"final_only"` 表示缓冲直到轮次终止事件。 +- `stream.hiddenBoundarySeparator`：在隐藏工具事件之后、可见文本之前使用的分隔符（默认：`"paragraph"`）。 +- `stream.maxOutputChars`：每个 ACP 轮次投影的最大助手输出字符数。 +- `stream.maxSessionUpdateChars`：投影 ACP 状态/更新行的最大字符数。 +- `stream.tagVisibility`：记录标签名到布尔可见性覆盖值的映射，用于流式事件。 +- `runtime.ttlMinutes`：ACP 会话 worker 在可被清理前的空闲 TTL（分钟）。 +- `runtime.installCommand`：在引导 ACP 运行时环境时执行的可选安装命令。 --- @@ -1018,11 +1009,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `cli.banner.taglineMode` 控制 banner 标语样式： - - `"random"`（默认）：轮换有趣 / 季节性标语。 - - `"default"`：固定中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：不显示标语文本（仍显示 banner 标题 / 版本）。 -- 若要隐藏整个 banner（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 +- `cli.banner.taglineMode` 控制横幅标语样式： + - `"random"`（默认）：轮换显示有趣/季节性标语。 + - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 + - `"off"`：不显示标语文本（仍显示横幅标题/版本）。 +- 若要隐藏整个横幅（而不仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -1046,13 +1037,13 @@ SecretRef 是增量式的：明文值仍然可用。 ## 身份 -请参见 [Agent defaults](/zh-CN/gateway/config-agents#agent-defaults) 下 `agents.list` 的身份字段。 +请参阅 [智能体默认值](/zh-CN/gateway/config-agents#agent-defaults) 下的 `agents.list` 身份字段。 --- -## Bridge protocol（旧版节点，历史参考）（旧版，已移除） +## Bridge 协议（旧版节点，历史参考）（旧版，已移除） -当前构建版本已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前校验会失败；`openclaw doctor --fix` 可剥离未知键）。 +当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前会导致验证失败；`openclaw doctor --fix` 可剥离未知键）。 @@ -1092,11 +1083,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `sessionRetention`：在从 `sessions.json` 中清理前，已完成的隔离 cron 运行会话保留多久。也控制已归档、已删除 cron 转录的清理。默认：`24h`；设为 `false` 可禁用。 -- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在触发裁剪前的最大大小。默认：`2_000_000` 字节。 -- `runLog.keepLines`：触发运行日志裁剪时保留的最新行数。默认：`2000`。 -- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略则不发送身份验证标头。 -- `webhook`：已弃用的旧版回退 webhook URL（http / https），仅用于仍保留 `notify: true` 的已存储作业。 +- `sessionRetention`：在从 `sessions.json` 清理前，保留已完成隔离 cron 运行会话的时长。也控制已归档删除的 cron transcript 的清理。默认：`24h`；设为 `false` 可禁用。 +- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在触发清理前的最大大小。默认：`2_000_000` 字节。 +- `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认：`2000`。 +- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略，则不会发送认证头。 +- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于那些仍然设置了 `notify: true` 的已存储任务。 ### `cron.retry` @@ -1112,11 +1103,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `maxAttempts`：一次性作业在瞬态错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。 -- `backoffMs`：每次重试尝试对应的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。 -- `retryOn`：触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则会对所有瞬态类型重试。 +- `maxAttempts`：对于瞬时错误，一次性任务的最大重试次数（默认：`3`；范围：`0`–`10`）。 +- `backoffMs`：每次重试尝试使用的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。 +- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则表示对所有瞬时类型进行重试。 -仅适用于一次性 cron 作业。周期性作业使用单独的失败处理机制。 +仅适用于一次性 cron 任务。周期性任务使用单独的失败处理机制。 ### `cron.failureAlert` @@ -1134,10 +1125,10 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：启用 cron 作业失败告警（默认：`false`）。 +- `enabled`：启用 cron 任务失败告警（默认：`false`）。 - `after`：连续失败多少次后触发告警（正整数，最小值：`1`）。 -- `cooldownMs`：同一作业重复告警之间的最小间隔（毫秒）（非负整数）。 -- `mode`：投递模式——`"announce"` 通过渠道消息发送；`"webhook"` 向已配置 webhook 发起 POST。 +- `cooldownMs`：同一任务重复告警之间的最小时间间隔（毫秒）（非负整数）。 +- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 向已配置 webhook 发起 POST。 - `accountId`：可选的账号或渠道 id，用于限定告警投递范围。 ### `cron.failureDestination` @@ -1155,16 +1146,16 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- 所有作业共用的 cron 失败通知默认目标。 +- 所有任务共用的 cron 失败通知默认目标。 - `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认值为 `"announce"`。 -- `channel`：announce 投递的渠道覆盖。`"last"` 会复用最后一次已知投递渠道。 -- `to`：显式的 announce 目标或 webhook URL。在 webhook 模式下为必填。 -- `accountId`：可选的投递账号覆盖。 -- 每个作业的 `delivery.failureDestination` 会覆盖这个全局默认值。 -- 当全局和每个作业的失败目标都未设置时，原本已通过 `announce` 投递的作业会在失败时回退到其主 announce 目标。 -- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的作业，除非该作业的主 `delivery.mode` 为 `"webhook"`。 +- `channel`：announce 投递的渠道覆盖项。`"last"` 会复用最近一次已知投递渠道。 +- `to`：显式的 announce 目标或 webhook URL。webhook 模式下为必填。 +- `accountId`：可选的投递账号覆盖项。 +- 每个任务的 `delivery.failureDestination` 会覆盖该全局默认值。 +- 当既未设置全局失败目标，也未设置每任务失败目标时，那些原本已通过 `announce` 投递的任务会在失败时回退到其主 announce 目标。 +- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的任务，除非该任务的主 `delivery.mode` 为 `"webhook"`。 -请参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [background tasks](/zh-CN/automation/tasks) 进行跟踪。 +请参阅 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 --- @@ -1172,34 +1163,34 @@ SecretRef 是增量式的：明文值仍然可用。 在 `tools.media.models[].args` 中展开的模板占位符： -| Variable | 描述 | -| ------------------ | ---- | -| `{{Body}}` | 完整的入站消息正文 | -| `{{RawBody}}` | 原始正文（无历史记录 / 发送者包装） | +| 变量 | 说明 | +| ------------------ | ------------------------------------------------- | +| `{{Body}}` | 完整的入站消息正文 | +| `{{RawBody}}` | 原始正文（无历史记录/发送者包装） | | `{{BodyStripped}}` | 去除群组提及后的正文 | -| `{{From}}` | 发送者标识符 | -| `{{To}}` | 目标标识符 | -| `{{MessageSid}}` | 渠道消息 id | -| `{{SessionId}}` | 当前会话 UUID | -| `{{IsNewSession}}` | 创建新会话时为 `"true"` | -| `{{MediaUrl}}` | 入站媒体伪 URL | -| `{{MediaPath}}` | 本地媒体路径 | -| `{{MediaType}}` | 媒体类型（image / audio / document / …） | -| `{{Transcript}}` | 音频转录文本 | -| `{{Prompt}}` | CLI 条目的已解析媒体提示词 | -| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 | -| `{{ChatType}}` | `"direct"` 或 `"group"` | -| `{{GroupSubject}}` | 群组主题（尽力提供） | -| `{{GroupMembers}}` | 群组成员预览（尽力提供） | -| `{{SenderName}}` | 发送者显示名称（尽力提供） | -| `{{SenderE164}}` | 发送者电话号码（尽力提供） | -| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | +| `{{From}}` | 发送者标识符 | +| `{{To}}` | 目标标识符 | +| `{{MessageSid}}` | 渠道消息 id | +| `{{SessionId}}` | 当前会话 UUID | +| `{{IsNewSession}}` | 新建会话时为 `"true"` | +| `{{MediaUrl}}` | 入站媒体伪 URL | +| `{{MediaPath}}` | 本地媒体路径 | +| `{{MediaType}}` | 媒体类型（image/audio/document/…） | +| `{{Transcript}}` | 音频转录文本 | +| `{{Prompt}}` | CLI 条目的已解析媒体提示词 | +| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 | +| `{{ChatType}}` | `"direct"` 或 `"group"` | +| `{{GroupSubject}}` | 群组主题（尽力而为） | +| `{{GroupMembers}}` | 群组成员预览（尽力而为） | +| `{{SenderName}}` | 发送者显示名称（尽力而为） | +| `{{SenderE164}}` | 发送者电话号码（尽力而为） | +| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | --- ## 配置包含（`$include`） -将配置拆分到多个文件中： +将配置拆分为多个文件： ```json5 // ~/.openclaw/openclaw.json @@ -1214,20 +1205,20 @@ SecretRef 是增量式的：明文值仍然可用。 **合并行为：** -- 单个文件：替换所在的整个对象。 -- 文件数组：按顺序深度合并（后面的覆盖前面的）。 -- 同级键：在 include 之后合并（覆盖被包含的值）。 -- 嵌套 include：最多 10 层。 -- 路径：相对于发起包含的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）之内。只有在最终仍解析到该边界内时，才允许使用绝对路径 / `../` 形式。 -- 仅更改某个由单文件 include 支持的顶层部分时，OpenClaw 自有写入会直接写回该被包含文件。例如，`plugins install` 会更新 `plugins: { $include: "./plugins.json5" }` 中的 `plugins.json5`，并保持 `openclaw.json` 不变。 -- 根 include、include 数组，以及带有同级覆盖的 include，对于 OpenClaw 自有写入均为只读；这些写入会以封闭失败方式处理，而不是将配置拍平。 -- 错误：对缺失文件、解析错误和循环 include 提供清晰消息。 +- 单个文件：替换其所在的包含对象。 +- 文件数组：按顺序深度合并（后者覆盖前者）。 +- 同级键：在包含内容之后合并（覆盖包含值）。 +- 嵌套包含：最多支持 10 层。 +- 路径：相对于发起包含的文件解析，但必须始终位于顶层配置目录（`openclaw.json` 的 `dirname`）之内。仅当绝对路径或 `../` 形式最终仍解析到该边界内时，才允许使用。 +- 当 OpenClaw 自有写入仅修改某个由单文件 include 支持的顶层分区时，该写入会透传到对应的被包含文件。例如，`plugins install` 会更新 `plugins: { $include: "./plugins.json5" }` 中的 `plugins.json5`，并保持 `openclaw.json` 不变。 +- 根级 include、include 数组，以及带有同级覆盖项的 include，对于 OpenClaw 自有写入都是只读的；这些写入会以关闭方式失败，而不是将配置拍平。 +- 错误：对于缺失文件、解析错误和循环包含，会提供清晰的错误消息。 --- -_相关内容：[Configuration](/zh-CN/gateway/configuration) · [Configuration Examples](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ +_相关内容：[配置](/zh-CN/gateway/configuration) · [配置示例](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ ## 相关 -- [Configuration](/zh-CN/gateway/configuration) -- [Configuration examples](/zh-CN/gateway/configuration-examples) +- [配置](/zh-CN/gateway/configuration) +- [配置示例](/zh-CN/gateway/configuration-examples) diff --git a/docs/zh-CN/gateway/security/audit-checks.md b/docs/zh-CN/gateway/security/audit-checks.md index a96ca8732..8db8f9f0f 100644 --- a/docs/zh-CN/gateway/security/audit-checks.md +++ b/docs/zh-CN/gateway/security/audit-checks.md @@ -1,129 +1,125 @@ --- read_when: - - 你在 `openclaw security audit` 输出中看到了特定的 `checkId`，想知道它是什么意思 - - 你需要某个发现项对应的修复键/路径 - - 你正在对一次安全审计运行中的严重性进行分级 -summary: '`openclaw security audit` 发出的 checkId 参考目录' -title: 安全审计检查项 + - 你在 `openclaw security audit` 输出中看到了一个特定的 `checkId`，想知道它是什么意思 + - 你需要某个给定发现项的修复键名/路径 + - 你正在对一次安全审计运行中的严重性进行分类排查 +summary: openclaw 安全审计发出的 checkId 参考目录 +title: 安全审计检查 x-i18n: - generated_at: "2026-04-23T20:50:11Z" + generated_at: "2026-04-26T00:16:06Z" model: gpt-5.4 provider: openai - source_hash: 107232e94aae9e12b160840691f5a12be6c354dd6162ff5f59b6a56475d27649 + source_hash: 7a5463bd1cec8382eb480cbbe1d8f8cceef0c15efc1f9124990df1e8f70b209a source_path: gateway/security/audit-checks.md workflow: 15 --- -`openclaw security audit` 会输出按 `checkId` 标识的结构化发现项。本页是这些 ID 的参考目录。有关高层威胁模型和加固指南，请参见 [Security](/zh-CN/gateway/security)。 +`openclaw security audit` 会输出以 `checkId` 为键的结构化发现项。本页是这些 ID 的参考目录。有关高层级威胁模型和加固指南，请参阅 [Security](/zh-CN/gateway/security)。 -在真实部署中你最有可能看到的高信号 `checkId` 值（非完整列表）： +你在真实部署中最可能看到的高信号 `checkId` 值包括（并非穷尽）： -| `checkId` | 严重性 | 为什么重要 | 主要修复键/路径 | 自动修复 | -| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | -------- | -| `fs.state_dir.perms_world_writable` | critical | 其他用户/进程可以修改完整 OpenClaw 状态 | `~/.openclaw` 上的文件系统权限 | yes | -| `fs.state_dir.perms_group_writable` | warn | 同组用户可以修改完整 OpenClaw 状态 | `~/.openclaw` 上的文件系统权限 | yes | -| `fs.state_dir.perms_readable` | warn | 状态目录对其他人可读 | `~/.openclaw` 上的文件系统权限 | yes | -| `fs.state_dir.symlink` | warn | 状态目录目标会变成另一个信任边界 | 状态目录文件系统布局 | no | -| `fs.config.perms_writable` | critical | 其他人可以更改认证/工具策略/配置 | `~/.openclaw/openclaw.json` 上的文件系统权限 | yes | -| `fs.config.symlink` | warn | 符号链接配置文件不支持写入，并增加另一个信任边界 | 替换为常规配置文件，或将 `OPENCLAW_CONFIG_PATH` 指向真实文件 | no | -| `fs.config.perms_group_readable` | warn | 同组用户可以读取配置 token/设置 | 配置文件上的文件系统权限 | yes | -| `fs.config.perms_world_readable` | critical | 配置可能泄露 token/设置 | 配置文件上的文件系统权限 | yes | -| `fs.config_include.perms_writable` | critical | 配置 include 文件可被其他人修改 | `openclaw.json` 引用的 include 文件权限 | yes | -| `fs.config_include.perms_group_readable` | warn | 同组用户可以读取包含的密钥/设置 | `openclaw.json` 引用的 include 文件权限 | yes | -| `fs.config_include.perms_world_readable` | critical | 包含的密钥/设置对所有人可读 | `openclaw.json` 引用的 include 文件权限 | yes | -| `fs.auth_profiles.perms_writable` | critical | 其他人可以注入或替换已存储的模型凭证 | `agents//agent/auth-profiles.json` 权限 | yes | -| `fs.auth_profiles.perms_readable` | warn | 其他人可以读取 API 密钥和 OAuth token | `agents//agent/auth-profiles.json` 权限 | yes | -| `fs.credentials_dir.perms_writable` | critical | 其他人可以修改渠道配对/凭证状态 | `~/.openclaw/credentials` 上的文件系统权限 | yes | -| `fs.credentials_dir.perms_readable` | warn | 其他人可以读取渠道凭证状态 | `~/.openclaw/credentials` 上的文件系统权限 | yes | -| `fs.sessions_store.perms_readable` | warn | 其他人可以读取会话转录/元数据 | 会话存储权限 | yes | -| `fs.log_file.perms_readable` | warn | 其他人可以读取虽经脱敏但仍敏感的日志 | gateway 日志文件权限 | yes | -| `fs.synced_dir` | warn | 将状态/配置放在 iCloud/Dropbox/Drive 中会扩大 token/转录暴露范围 | 将配置/状态移出同步文件夹 | no | -| `gateway.bind_no_auth` | critical | 远程绑定但没有共享密钥 | `gateway.bind`、`gateway.auth.*` | no | -| `gateway.loopback_no_auth` | critical | 反向代理后的 loopback 可能变成未认证 | `gateway.auth.*`、代理设置 | no | -| `gateway.trusted_proxies_missing` | warn | 存在反向代理头，但未被信任 | `gateway.trustedProxies` | no | -| `gateway.http.no_auth` | warn/critical | 使用 `auth.mode="none"` 时 Gateway 网关 HTTP API 可达 | `gateway.auth.mode`、`gateway.http.endpoints.*` | no | -| `gateway.http.session_key_override_enabled` | info | HTTP API 调用方可以覆盖 `sessionKey` | `gateway.http.allowSessionKeyOverride` | no | -| `gateway.tools_invoke_http.dangerous_allow` | warn/critical | 通过 HTTP API 重新启用危险工具 | `gateway.tools.allow` | no | -| `gateway.nodes.allow_commands_dangerous` | warn/critical | 启用高影响节点命令（camera/screen/contacts/calendar/SMS） | `gateway.nodes.allowCommands` | no | -| `gateway.nodes.deny_commands_ineffective` | warn | 类似模式的 deny 条目不会匹配 shell 文本或分组 | `gateway.nodes.denyCommands` | no | -| `gateway.tailscale_funnel` | critical | 暴露到公共互联网 | `gateway.tailscale.mode` | no | -| `gateway.tailscale_serve` | info | 已通过 Serve 启用 tailnet 暴露 | `gateway.tailscale.mode` | no | -| `gateway.control_ui.allowed_origins_required` | critical | 非 loopback 的 Control UI 未显式设置浏览器来源允许列表 | `gateway.controlUi.allowedOrigins` | no | -| `gateway.control_ui.allowed_origins_wildcard` | warn/critical | `allowedOrigins=["*"]` 会禁用浏览器来源允许列表 | `gateway.controlUi.allowedOrigins` | no | -| `gateway.control_ui.host_header_origin_fallback` | warn/critical | 启用 Host 标头来源回退（降低 DNS rebinding 加固强度） | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | no | -| `gateway.control_ui.insecure_auth` | warn | 启用了不安全认证兼容开关 | `gateway.controlUi.allowInsecureAuth` | no | -| `gateway.control_ui.device_auth_disabled` | critical | 禁用了设备身份检查 | `gateway.controlUi.dangerouslyDisableDeviceAuth` | no | -| `gateway.real_ip_fallback_enabled` | warn/critical | 信任 `X-Real-IP` 回退可能因代理配置错误而导致源 IP 伪造 | `gateway.allowRealIpFallback`、`gateway.trustedProxies` | no | -| `gateway.token_too_short` | warn | 共享 token 过短，更容易被暴力破解 | `gateway.auth.token` | no | -| `gateway.auth_no_rate_limit` | warn | 暴露的认证没有速率限制会增加暴力破解风险 | `gateway.auth.rateLimit` | no | -| `gateway.trusted_proxy_auth` | critical | 代理身份现在成为认证边界 | `gateway.auth.mode="trusted-proxy"` | no | -| `gateway.trusted_proxy_no_proxies` | critical | 没有受信任代理 IP 的 trusted-proxy 认证是不安全的 | `gateway.trustedProxies` | no | -| `gateway.trusted_proxy_no_user_header` | critical | trusted-proxy 认证无法安全解析用户身份 | `gateway.auth.trustedProxy.userHeader` | no | -| `gateway.trusted_proxy_no_allowlist` | warn | trusted-proxy 认证会接受任何已认证的上游用户 | `gateway.auth.trustedProxy.allowUsers` | no | -| `checkId` | 严重性 | 为什么重要 | 主要修复键/路径 | 自动修复 | -| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | -------- | -| `gateway.probe_auth_secretref_unavailable` | warn | 深度探测无法在此命令路径中解析认证 SecretRef | 深度探测认证来源 / SecretRef 可用性 | no | -| `gateway.probe_failed` | warn/critical | 实时 Gateway 网关探测失败 | gateway 可达性/认证 | no | -| `discovery.mdns_full_mode` | warn/critical | mDNS full 模式会在本地网络上广播 `cliPath`/`sshPort` 元数据 | `discovery.mdns.mode`、`gateway.bind` | no | -| `config.insecure_or_dangerous_flags` | warn | 启用了任意不安全/危险调试标志 | 多个键（见发现详情） | no | -| `config.secrets.gateway_password_in_config` | warn | Gateway 网关密码被直接存储在配置中 | `gateway.auth.password` | no | -| `config.secrets.hooks_token_in_config` | warn | Hook bearer token 被直接存储在配置中 | `hooks.token` | no | -| `hooks.token_reuse_gateway_token` | critical | Hook 入口 token 同时也能解锁 Gateway 网关认证 | `hooks.token`、`gateway.auth.token` | no | -| `hooks.token_too_short` | warn | 更容易对 hook 入口进行暴力破解 | `hooks.token` | no | -| `hooks.default_session_key_unset` | warn | Hook 智能体运行会分散到按请求生成的会话中 | `hooks.defaultSessionKey` | no | -| `hooks.allowed_agent_ids_unrestricted` | warn/critical | 已认证的 hook 调用方可以路由到任何已配置智能体 | `hooks.allowedAgentIds` | no | -| `hooks.request_session_key_enabled` | warn/critical | 外部调用方可以选择 `sessionKey` | `hooks.allowRequestSessionKey` | no | -| `hooks.request_session_key_prefixes_missing` | warn/critical | 外部会话键形状没有边界限制 | `hooks.allowedSessionKeyPrefixes` | no | -| `hooks.path_root` | critical | Hook 路径为 `/`，使入口更容易发生冲突或误路由 | `hooks.path` | no | -| `hooks.installs_unpinned_npm_specs` | warn | Hook 安装记录未固定到不可变 npm specs | hook 安装元数据 | no | -| `hooks.installs_missing_integrity` | warn | Hook 安装记录缺少完整性元数据 | hook 安装元数据 | no | -| `hooks.installs_version_drift` | warn | Hook 安装记录与已安装包发生漂移 | hook 安装元数据 | no | -| `logging.redact_off` | warn | 敏感值会泄露到日志/状态中 | `logging.redactSensitive` | yes | -| `browser.control_invalid_config` | warn | 运行前浏览器控制配置无效 | `browser.*` | no | -| `browser.control_no_auth` | critical | 浏览器控制在无 token/password 认证下暴露 | `gateway.auth.*` | no | -| `browser.remote_cdp_http` | warn | 通过明文 HTTP 访问远程 CDP 缺乏传输加密 | 浏览器 profile `cdpUrl` | no | -| `browser.remote_cdp_private_host` | warn | 远程 CDP 指向私有/内部主机 | 浏览器 profile `cdpUrl`、`browser.ssrfPolicy.*` | no | -| `sandbox.docker_config_mode_off` | warn | 沙箱 Docker 配置存在但未激活 | `agents.*.sandbox.mode` | no | -| `sandbox.bind_mount_non_absolute` | warn | 相对 bind mount 可能以不可预测方式解析 | `agents.*.sandbox.docker.binds[]` | no | -| `sandbox.dangerous_bind_mount` | critical | 沙箱 bind mount 指向被阻止的系统、凭证或 Docker socket 路径 | `agents.*.sandbox.docker.binds[]` | no | -| `sandbox.dangerous_network_mode` | critical | 沙箱 Docker 网络使用 `host` 或 `container:*` 命名空间加入模式 | `agents.*.sandbox.docker.network` | no | -| `sandbox.dangerous_seccomp_profile` | critical | 沙箱 seccomp 配置会削弱容器隔离 | `agents.*.sandbox.docker.securityOpt` | no | -| `sandbox.dangerous_apparmor_profile` | critical | 沙箱 AppArmor 配置会削弱容器隔离 | `agents.*.sandbox.docker.securityOpt` | no | -| `sandbox.browser_cdp_bridge_unrestricted` | warn | 沙箱浏览器桥接在没有来源范围限制的情况下暴露 | `sandbox.browser.cdpSourceRange` | no | -| `sandbox.browser_container.non_loopback_publish` | critical | 现有浏览器容器在非 loopback 接口上发布 CDP | 浏览器沙箱容器发布配置 | no | -| `sandbox.browser_container.hash_label_missing` | warn | 现有浏览器容器早于当前配置哈希标签 | `openclaw sandbox recreate --browser --all` | no | -| `sandbox.browser_container.hash_epoch_stale` | warn | 现有浏览器容器早于当前浏览器配置 epoch | `openclaw sandbox recreate --browser --all` | no | -| `tools.exec.host_sandbox_no_sandbox_defaults` | warn | 当沙箱关闭时，`exec host=sandbox` 会以关闭失败方式终止 | `tools.exec.host`、`agents.defaults.sandbox.mode` | no | -| `tools.exec.host_sandbox_no_sandbox_agents` | warn | 当沙箱关闭时，按智能体的 `exec host=sandbox` 会以关闭失败方式终止 | `agents.list[].tools.exec.host`、`agents.list[].sandbox.mode` | no | -| `tools.exec.security_full_configured` | warn/critical | 主机 exec 正在使用 `security="full"` 运行 | `tools.exec.security`、`agents.list[].tools.exec.security` | no | -| `tools.exec.auto_allow_skills_enabled` | warn | Exec 审批会隐式信任 skill bin | `~/.openclaw/exec-approvals.json` | no | -| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn | 解释器允许列表允许内联 eval，且未强制重新审批 | `tools.exec.strictInlineEval`、`agents.list[].tools.exec.strictInlineEval`、exec approvals allowlist | no | -| `tools.exec.safe_bins_interpreter_unprofiled` | warn | `safeBins` 中的解释器/运行时 bin 没有显式 profile，会扩大 exec 风险 | `tools.exec.safeBins`、`tools.exec.safeBinProfiles`、`agents.list[].tools.exec.*` | no | -| `tools.exec.safe_bins_broad_behavior` | warn | `safeBins` 中的广行为工具会削弱低风险 stdin 过滤信任模型 | `tools.exec.safeBins`、`agents.list[].tools.exec.safeBins` | no | -| `tools.exec.safe_bin_trusted_dirs_risky` | warn | `safeBinTrustedDirs` 包含可变或有风险目录 | `tools.exec.safeBinTrustedDirs`、`agents.list[].tools.exec.safeBinTrustedDirs` | no | -| `skills.workspace.symlink_escape` | warn | 工作区 `skills/**/SKILL.md` 解析到了工作区根目录之外（符号链接链漂移） | 工作区 `skills/**` 文件系统状态 | no | -| `plugins.extensions_no_allowlist` | warn | 安装插件时没有显式插件允许列表 | `plugins.allowlist` | no | -| `plugins.installs_unpinned_npm_specs` | warn | 插件安装记录未固定到不可变 npm specs | 插件安装元数据 | no | -| `checkId` | 严重性 | 为什么重要 | 主要修复键/路径 | 自动修复 | -| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | -------- | -| `plugins.installs_missing_integrity` | warn | 插件安装记录缺少完整性元数据 | 插件安装元数据 | no | -| `plugins.installs_version_drift` | warn | 插件安装记录与已安装包发生漂移 | 插件安装元数据 | no | -| `plugins.code_safety` | warn/critical | 插件代码扫描发现可疑或危险模式 | 插件代码 / 安装来源 | no | -| `plugins.code_safety.entry_path` | warn | 插件入口路径指向隐藏目录或 `node_modules` 位置 | 插件 manifest `entry` | no | -| `plugins.code_safety.entry_escape` | critical | 插件入口逃逸出插件目录 | 插件 manifest `entry` | no | -| `plugins.code_safety.scan_failed` | warn | 插件代码扫描无法完成 | 插件路径 / 扫描环境 | no | -| `skills.code_safety` | warn/critical | Skills 安装器元数据/代码包含可疑或危险模式 | skill 安装来源 | no | -| `skills.code_safety.scan_failed` | warn | skill 代码扫描无法完成 | skill 扫描环境 | no | -| `security.exposure.open_channels_with_exec` | warn/critical | 共享/公共房间可以访问启用了 exec 的智能体 | `channels.*.dmPolicy`、`channels.*.groupPolicy`、`tools.exec.*`、`agents.list[].tools.exec.*` | no | -| `security.exposure.open_groups_with_elevated` | critical | 开放群组 + elevated 工具会形成高影响提示词注入路径 | `channels.*.groupPolicy`、`tools.elevated.*` | no | -| `security.exposure.open_groups_with_runtime_or_fs` | critical/warn | 开放群组可以在没有沙箱/工作区防护的情况下访问命令/文件工具 | `channels.*.groupPolicy`、`tools.profile/deny`、`tools.fs.workspaceOnly`、`agents.*.sandbox.mode` | no | -| `security.trust_model.multi_user_heuristic` | warn | 配置看起来是多用户环境，但 gateway 信任模型是个人助理 | 拆分信任边界，或进行共享用户加固（`sandbox.mode`、工具 deny/工作区范围控制） | no | -| `tools.profile_minimal_overridden` | warn | 智能体覆盖绕过了全局最小配置文件 | `agents.list[].tools.profile` | no | -| `plugins.tools_reachable_permissive_policy` | warn | 扩展工具在宽松上下文中可达 | `tools.profile` + 工具 allow/deny | no | -| `models.legacy` | warn | 仍配置了旧版模型家族 | 模型选择 | no | -| `models.weak_tier` | warn | 已配置模型低于当前推荐层级 | 模型选择 | no | -| `models.small_params` | critical/info | 小模型 + 不安全工具界面会提高注入风险 | 模型选择 + 沙箱/工具策略 | no | -| `summary.attack_surface` | info | 对认证、渠道、工具和暴露姿态的汇总摘要 | 多个键（见发现详情） | no | +| `checkId` | 严重性 | 为什么重要 | 主要修复键名/路径 | 自动修复 | +| ------------------------------------------------------------- | ------ | ---------- | ---------------------------------------------------------------------------------------------------- | -------- | +| `fs.state_dir.perms_world_writable` | 严重 | 其他用户/进程可以修改完整的 OpenClaw 状态 | `~/.openclaw` 的文件系统权限 | 是 | +| `fs.state_dir.perms_group_writable` | 警告 | 同组用户可以修改完整的 OpenClaw 状态 | `~/.openclaw` 的文件系统权限 | 是 | +| `fs.state_dir.perms_readable` | 警告 | 状态目录可被其他人读取 | `~/.openclaw` 的文件系统权限 | 是 | +| `fs.state_dir.symlink` | 警告 | 状态目录目标会变成另一个信任边界 | 状态目录文件系统布局 | 否 | +| `fs.config.perms_writable` | 严重 | 其他人可以更改凭证/工具策略/配置 | `~/.openclaw/openclaw.json` 的文件系统权限 | 是 | +| `fs.config.symlink` | 警告 | 不支持对符号链接配置文件进行写入，且会引入另一个信任边界 | 替换为常规配置文件，或将 `OPENCLAW_CONFIG_PATH` 指向真实文件 | 否 | +| `fs.config.perms_group_readable` | 警告 | 同组用户可以读取配置中的令牌/设置 | 配置文件的文件系统权限 | 是 | +| `fs.config.perms_world_readable` | 严重 | 配置可能暴露令牌/设置 | 配置文件的文件系统权限 | 是 | +| `fs.config_include.perms_writable` | 严重 | 配置包含文件可被其他人修改 | `openclaw.json` 引用的包含文件权限 | 是 | +| `fs.config_include.perms_group_readable` | 警告 | 同组用户可以读取被包含的密钥/设置 | `openclaw.json` 引用的包含文件权限 | 是 | +| `fs.config_include.perms_world_readable` | 严重 | 被包含的密钥/设置对所有人可读 | `openclaw.json` 引用的包含文件权限 | 是 | +| `fs.auth_profiles.perms_writable` | 严重 | 其他人可以注入或替换已存储的模型凭证 | `agents//agent/auth-profiles.json` 权限 | 是 | +| `fs.auth_profiles.perms_readable` | 警告 | 其他人可以读取 API 密钥和 OAuth 令牌 | `agents//agent/auth-profiles.json` 权限 | 是 | +| `fs.credentials_dir.perms_writable` | 严重 | 其他人可以修改渠道配对/凭证状态 | `~/.openclaw/credentials` 的文件系统权限 | 是 | +| `fs.credentials_dir.perms_readable` | 警告 | 其他人可以读取渠道凭证状态 | `~/.openclaw/credentials` 的文件系统权限 | 是 | +| `fs.sessions_store.perms_readable` | 警告 | 其他人可以读取会话转录内容/元数据 | 会话存储权限 | 是 | +| `fs.log_file.perms_readable` | 警告 | 其他人可以读取虽经脱敏但仍然敏感的日志 | Gateway 网关日志文件权限 | 是 | +| `fs.synced_dir` | 警告 | iCloud/Dropbox/Drive 中的状态/配置会扩大令牌/转录内容暴露范围 | 将配置/状态移出同步文件夹 | 否 | +| `gateway.bind_no_auth` | 严重 | 远程绑定时未使用共享密钥 | `gateway.bind`, `gateway.auth.*` | 否 | +| `gateway.loopback_no_auth` | 严重 | 经反向代理的 loopback 可能变为未鉴权状态 | `gateway.auth.*`, 代理设置 | 否 | +| `gateway.trusted_proxies_missing` | 警告 | 存在反向代理头，但未将代理标记为受信任 | `gateway.trustedProxies` | 否 | +| `gateway.http.no_auth` | 警告/严重 | 在 `auth.mode="none"` 时，Gateway 网关 HTTP API 可被访问 | `gateway.auth.mode`, `gateway.http.endpoints.*` | 否 | +| `gateway.http.session_key_override_enabled` | 信息 | HTTP API 调用方可以覆盖 `sessionKey` | `gateway.http.allowSessionKeyOverride` | 否 | +| `gateway.tools_invoke_http.dangerous_allow` | 警告/严重 | 重新允许通过 HTTP API 使用危险工具 | `gateway.tools.allow` | 否 | +| `gateway.nodes.allow_commands_dangerous` | 警告/严重 | 启用高影响节点命令（相机/屏幕/联系人/日历/SMS） | `gateway.nodes.allowCommands` | 否 | +| `gateway.nodes.deny_commands_ineffective` | 警告 | 类似模式的拒绝项无法匹配 shell 文本或分组 | `gateway.nodes.denyCommands` | 否 | +| `gateway.tailscale_funnel` | 严重 | 暴露到公共互联网 | `gateway.tailscale.mode` | 否 | +| `gateway.tailscale_serve` | 信息 | 已通过 Serve 启用 Tailnet 暴露 | `gateway.tailscale.mode` | 否 | +| `gateway.control_ui.allowed_origins_required` | 严重 | 非 loopback 的 Control UI 未设置明确的浏览器源允许列表 | `gateway.controlUi.allowedOrigins` | 否 | +| `gateway.control_ui.allowed_origins_wildcard` | 警告/严重 | `allowedOrigins=["*"]` 会禁用浏览器源允许列表 | `gateway.controlUi.allowedOrigins` | 否 | +| `gateway.control_ui.host_header_origin_fallback` | 警告/严重 | 启用 Host 头源回退（降低 DNS 重绑定加固强度） | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | 否 | +| `gateway.control_ui.insecure_auth` | 警告 | 已启用不安全鉴权兼容开关 | `gateway.controlUi.allowInsecureAuth` | 否 | +| `gateway.control_ui.device_auth_disabled` | 严重 | 禁用设备身份校验 | `gateway.controlUi.dangerouslyDisableDeviceAuth` | 否 | +| `gateway.real_ip_fallback_enabled` | 警告/严重 | 信任 `X-Real-IP` 回退可能因代理配置错误而允许伪造源 IP | `gateway.allowRealIpFallback`, `gateway.trustedProxies` | 否 | +| `gateway.token_too_short` | 警告 | 共享令牌过短，更容易被暴力破解 | `gateway.auth.token` | 否 | +| `gateway.auth_no_rate_limit` | 警告 | 暴露的鉴权接口若无限速，会增加暴力破解风险 | `gateway.auth.rateLimit` | 否 | +| `gateway.trusted_proxy_auth` | 严重 | 代理身份现在成为鉴权边界 | `gateway.auth.mode="trusted-proxy"` | 否 | +| `gateway.trusted_proxy_no_proxies` | 严重 | 在没有受信任代理 IP 的情况下使用 trusted-proxy 鉴权并不安全 | `gateway.trustedProxies` | 否 | +| `gateway.trusted_proxy_no_user_header` | 严重 | trusted-proxy 鉴权无法安全解析用户身份 | `gateway.auth.trustedProxy.userHeader` | 否 | +| `gateway.trusted_proxy_no_allowlist` | 警告 | trusted-proxy 鉴权会接受任何已通过上游鉴权的用户 | `gateway.auth.trustedProxy.allowUsers` | 否 | +| `gateway.probe_auth_secretref_unavailable` | 警告 | 在此命令路径中，深度探测无法解析凭证 SecretRef | 深度探测凭证来源 / SecretRef 可用性 | 否 | +| `gateway.probe_failed` | 警告/严重 | 实时 Gateway 网关探测失败 | Gateway 网关可达性/鉴权 | 否 | +| `discovery.mdns_full_mode` | 警告/严重 | mDNS 完整模式会在本地网络中通告 `cliPath`/`sshPort` 元数据 | `discovery.mdns.mode`, `gateway.bind` | 否 | +| `config.insecure_or_dangerous_flags` | 警告 | 已启用任意不安全/危险的调试标志 | 多个键名（见发现详情） | 否 | +| `config.secrets.gateway_password_in_config` | 警告 | Gateway 网关密码直接存储在配置中 | `gateway.auth.password` | 否 | +| `config.secrets.hooks_token_in_config` | 警告 | Hook bearer 令牌直接存储在配置中 | `hooks.token` | 否 | +| `hooks.token_reuse_gateway_token` | 严重 | Hook 入口令牌同时也能解锁 Gateway 网关鉴权 | `hooks.token`, `gateway.auth.token` | 否 | +| `hooks.token_too_short` | 警告 | Hook 入口更容易被暴力破解 | `hooks.token` | 否 | +| `hooks.default_session_key_unset` | 警告 | Hook 智能体运行会扇出到按请求生成的会话 | `hooks.defaultSessionKey` | 否 | +| `hooks.allowed_agent_ids_unrestricted` | 警告/严重 | 已鉴权的 Hook 调用方可路由到任意已配置智能体 | `hooks.allowedAgentIds` | 否 | +| `hooks.request_session_key_enabled` | 警告/严重 | 外部调用方可以选择 `sessionKey` | `hooks.allowRequestSessionKey` | 否 | +| `hooks.request_session_key_prefixes_missing` | 警告/严重 | 对外部会话键格式没有限制 | `hooks.allowedSessionKeyPrefixes` | 否 | +| `hooks.path_root` | 严重 | Hook 路径为 `/`，更容易发生入口冲突或误路由 | `hooks.path` | 否 | +| `hooks.installs_unpinned_npm_specs` | 警告 | Hook 安装记录未固定到不可变的 npm 规格 | Hook 安装元数据 | 否 | +| `hooks.installs_missing_integrity` | 警告 | Hook 安装记录缺少完整性元数据 | Hook 安装元数据 | 否 | +| `hooks.installs_version_drift` | 警告 | Hook 安装记录与已安装包发生漂移 | Hook 安装元数据 | 否 | +| `logging.redact_off` | 警告 | 敏感值会泄露到日志/Status | `logging.redactSensitive` | 是 | +| `browser.control_invalid_config` | 警告 | 浏览器控制配置在运行前即无效 | `browser.*` | 否 | +| `browser.control_no_auth` | 严重 | 浏览器控制在没有令牌/密码鉴权的情况下暴露 | `gateway.auth.*` | 否 | +| `browser.remote_cdp_http` | 警告 | 通过明文 HTTP 使用远程 CDP 缺少传输加密 | 浏览器配置文件 `cdpUrl` | 否 | +| `browser.remote_cdp_private_host` | 警告 | 远程 CDP 指向私有/内部主机 | 浏览器配置文件 `cdpUrl`, `browser.ssrfPolicy.*` | 否 | +| `sandbox.docker_config_mode_off` | 警告 | 沙箱 Docker 配置已存在但未激活 | `agents.*.sandbox.mode` | 否 | +| `sandbox.bind_mount_non_absolute` | 警告 | 相对绑定挂载可能以不可预测方式解析 | `agents.*.sandbox.docker.binds[]` | 否 | +| `sandbox.dangerous_bind_mount` | 严重 | 沙箱绑定挂载目标指向被阻止的系统、凭证或 Docker socket 路径 | `agents.*.sandbox.docker.binds[]` | 否 | +| `sandbox.dangerous_network_mode` | 严重 | 沙箱 Docker 网络使用 `host` 或 `container:*` 命名空间加入模式 | `agents.*.sandbox.docker.network` | 否 | +| `sandbox.dangerous_seccomp_profile` | 严重 | 沙箱 seccomp 配置文件削弱了容器隔离 | `agents.*.sandbox.docker.securityOpt` | 否 | +| `sandbox.dangerous_apparmor_profile` | 严重 | 沙箱 AppArmor 配置文件削弱了容器隔离 | `agents.*.sandbox.docker.securityOpt` | 否 | +| `sandbox.browser_cdp_bridge_unrestricted` | 警告 | 沙箱浏览器桥接暴露时未限制来源地址范围 | `sandbox.browser.cdpSourceRange` | 否 | +| `sandbox.browser_container.non_loopback_publish` | 严重 | 现有浏览器容器在非 loopback 接口上发布 CDP | 浏览器沙箱容器发布配置 | 否 | +| `sandbox.browser_container.hash_label_missing` | 警告 | 现有浏览器容器早于当前配置哈希标签 | `openclaw sandbox recreate --browser --all` | 否 | +| `sandbox.browser_container.hash_epoch_stale` | 警告 | 现有浏览器容器早于当前浏览器配置纪元 | `openclaw sandbox recreate --browser --all` | 否 | +| `tools.exec.host_sandbox_no_sandbox_defaults` | 警告 | 当沙箱关闭时，`exec host=sandbox` 会以关闭失败方式运行 | `tools.exec.host`, `agents.defaults.sandbox.mode` | 否 | +| `tools.exec.host_sandbox_no_sandbox_agents` | 警告 | 当沙箱关闭时，按智能体配置的 `exec host=sandbox` 会以关闭失败方式运行 | `agents.list[].tools.exec.host`, `agents.list[].sandbox.mode` | 否 | +| `tools.exec.security_full_configured` | 警告/严重 | 主机 exec 正在使用 `security="full"` 运行 | `tools.exec.security`, `agents.list[].tools.exec.security` | 否 | +| `tools.exec.auto_allow_skills_enabled` | 警告 | Exec 审批会隐式信任 Skills 二进制文件 | `~/.openclaw/exec-approvals.json` | 否 | +| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | 警告 | 解释器允许列表允许内联求值，且未强制重新审批 | `tools.exec.strictInlineEval`, `agents.list[].tools.exec.strictInlineEval`, exec 审批允许列表 | 否 | +| `tools.exec.safe_bins_interpreter_unprofiled` | 警告 | `safeBins` 中的解释器/运行时二进制文件若无显式配置文件，会扩大 exec 风险 | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*` | 否 | +| `tools.exec.safe_bins_broad_behavior` | 警告 | `safeBins` 中的广泛行为工具会削弱低风险 stdin 过滤信任模型 | `tools.exec.safeBins`, `agents.list[].tools.exec.safeBins` | 否 | +| `tools.exec.safe_bin_trusted_dirs_risky` | 警告 | `safeBinTrustedDirs` 包含可变或高风险目录 | `tools.exec.safeBinTrustedDirs`, `agents.list[].tools.exec.safeBinTrustedDirs` | 否 | +| `skills.workspace.symlink_escape` | 警告 | 工作区 `skills/**/SKILL.md` 解析到工作区根目录之外（符号链接链漂移） | 工作区 `skills/**` 文件系统状态 | 否 | +| `plugins.extensions_no_allowlist` | 警告 | 安装插件时未设置显式插件允许列表 | `plugins.allowlist` | 否 | +| `plugins.installs_unpinned_npm_specs` | 警告 | 插件索引记录未固定到不可变的 npm 规格 | 插件安装元数据 | 否 | +| `plugins.installs_missing_integrity` | 警告 | 插件索引记录缺少完整性元数据 | 插件安装元数据 | 否 | +| `plugins.installs_version_drift` | 警告 | 插件索引记录与已安装包发生漂移 | 插件安装元数据 | 否 | +| `plugins.code_safety` | 警告/严重 | 插件代码扫描发现可疑或危险模式 | 插件代码 / 安装来源 | 否 | +| `plugins.code_safety.entry_path` | 警告 | 插件入口路径指向隐藏目录或 `node_modules` 位置 | 插件清单 `entry` | 否 | +| `plugins.code_safety.entry_escape` | 严重 | 插件入口逃逸出插件目录 | 插件清单 `entry` | 否 | +| `plugins.code_safety.scan_failed` | 警告 | 插件代码扫描无法完成 | 插件路径 / 扫描环境 | 否 | +| `skills.code_safety` | 警告/严重 | Skills 安装器元数据/代码包含可疑或危险模式 | Skills 安装来源 | 否 | +| `skills.code_safety.scan_failed` | 警告 | Skills 代码扫描无法完成 | Skills 扫描环境 | 否 | +| `security.exposure.open_channels_with_exec` | 警告/严重 | 共享/公开房间可以访问启用了 exec 的智能体 | `channels.*.dmPolicy`, `channels.*.groupPolicy`, `tools.exec.*`, `agents.list[].tools.exec.*` | 否 | +| `security.exposure.open_groups_with_elevated` | 严重 | 开放群组 + 提权工具会形成高影响提示注入路径 | `channels.*.groupPolicy`, `tools.elevated.*` | 否 | +| `security.exposure.open_groups_with_runtime_or_fs` | 严重/警告 | 开放群组可以访问命令/文件工具，且没有沙箱/工作区防护 | `channels.*.groupPolicy`, `tools.profile/deny`, `tools.fs.workspaceOnly`, `agents.*.sandbox.mode` | 否 | +| `security.trust_model.multi_user_heuristic` | 警告 | 配置看起来像多用户场景，而 Gateway 网关信任模型仍是个人助手 | 拆分信任边界，或启用共享用户加固（`sandbox.mode`, 工具 deny/workspace 范围限定） | 否 | +| `tools.profile_minimal_overridden` | 警告 | 智能体覆盖配置绕过了全局最小权限配置文件 | `agents.list[].tools.profile` | 否 | +| `plugins.tools_reachable_permissive_policy` | 警告 | 扩展工具在宽松上下文中可被访问 | `tools.profile` + 工具 allow/deny | 否 | +| `models.legacy` | 警告 | 仍配置了旧版模型家族 | 模型选择 | 否 | +| `models.weak_tier` | 警告 | 已配置的模型低于当前推荐层级 | 模型选择 | 否 | +| `models.small_params` | 严重/信息 | 小模型 + 不安全工具暴露面会提高注入风险 | 模型选择 + 沙箱/工具策略 | 否 | +| `summary.attack_surface` | 信息 | 对鉴权、渠道、工具和暴露状况的汇总摘要 | 多个键名（见发现详情） | 否 | ## 相关内容 diff --git a/docs/zh-CN/plugins/architecture-internals.md b/docs/zh-CN/plugins/architecture-internals.md index 79b2f0d43..99d86dd5c 100644 --- a/docs/zh-CN/plugins/architecture-internals.md +++ b/docs/zh-CN/plugins/architecture-internals.md @@ -1,41 +1,41 @@ --- read_when: - - 实现提供商运行时钩子、渠道生命周期或软件包打包 bundles + - 实现提供商运行时钩子、渠道生命周期或包打包集合 - 调试插件加载顺序或注册表状态 - 添加新的插件能力或上下文引擎插件 -summary: 插件架构内部机制：加载管线、注册表、运行时钩子、HTTP 路由和参考表格 +summary: 插件架构内部机制：加载流水线、注册表、运行时钩子、HTTP 路由和参考表格 title: 插件架构内部机制 x-i18n: - generated_at: "2026-04-25T21:54:01Z" + generated_at: "2026-04-26T00:16:05Z" model: gpt-5.4 provider: openai - source_hash: d521f78bbd6aa4da09a28dcffa3c2309d46c8c1ec08f2f6b0616b3c2259339fc + source_hash: b8d82e74fc30e47dc5d699c5cf2268a7a65f4e3871d06cb0a1936aede5591625 source_path: plugins/architecture-internals.md workflow: 15 --- -对于公开的能力模型、插件形状以及所有权/执行契约，请参阅 [插件架构](/zh-CN/plugins/architecture)。本页是内部机制的参考文档：加载管线、注册表、运行时钩子、Gateway 网关 HTTP 路由、导入路径和模式表。 +有关公开能力模型、插件形状以及所有权/执行契约，请参见 [插件架构](/zh-CN/plugins/architecture)。本页是内部机制的参考：加载流水线、注册表、运行时钩子、Gateway 网关 HTTP 路由、导入路径和模式表。 -## 加载管线 +## 加载流水线 -在启动时，OpenClaw 大致会执行以下步骤： +启动时，OpenClaw 大致会执行以下步骤： 1. 发现候选插件根目录 -2. 读取原生或兼容 bundle 清单以及软件包元数据 +2. 读取原生或兼容 bundle 清单以及包元数据 3. 拒绝不安全的候选项 -4. 标准化插件配置（`plugins.enabled`、`allow`、`deny`、`entries`、`slots`、`load.paths`） -5. 决定每个候选项是否启用 +4. 规范化插件配置（`plugins.enabled`、`allow`、`deny`、`entries`、`slots`、`load.paths`） +5. 为每个候选项决定是否启用 6. 加载已启用的原生模块：已构建的内置模块使用原生加载器；未构建的原生插件使用 `jiti` 7. 调用原生 `register(api)` 钩子，并将注册内容收集到插件注册表中 -8. 将注册表暴露给命令/运行时表面 +8. 向命令/运行时表面暴露注册表 -`activate` 是 `register` 的旧别名——加载器会解析当前存在的那个（`def.register ?? def.activate`），并在相同位置调用它。所有内置插件都使用 `register`；新插件优先使用 `register`。 +`activate` 是 `register` 的旧别名——加载器会解析其中存在的那个（`def.register ?? def.activate`），并在同一时机调用它。所有内置插件都使用 `register`；新插件优先使用 `register`。 -安全门禁发生在**运行时执行之前**。当入口逃逸出插件根目录、路径对所有用户可写，或对于非内置插件而言路径所有权看起来可疑时，候选项会被阻止。 +安全门控会在运行时执行**之前**发生。当入口逃逸出插件根目录、路径可被所有用户写入，或对于非内置插件来说路径所有权看起来可疑时，候选项会被阻止。 -### 清单优先行为 +### Manifest-first 行为 清单是控制平面的事实来源。OpenClaw 使用它来： @@ -44,22 +44,22 @@ x-i18n: - 验证 `plugins.entries..config` - 增强 Control UI 标签/占位符 - 显示安装/目录元数据 -- 在不加载插件运行时的情况下保留轻量的激活和设置描述符 +- 在不加载插件运行时的情况下保留低成本激活和设置描述符 -对于原生插件，运行时模块是数据平面部分。它会注册实际行为，例如钩子、工具、命令或 provider 流程。 +对于原生插件，运行时模块是数据平面部分。它会注册实际行为，例如钩子、工具、命令或提供商流程。 -可选的清单 `activation` 和 `setup` 块仍然保留在控制平面。它们是仅含元数据的描述符，用于激活规划和设置发现；它们不会替代运行时注册、`register(...)` 或 `setupEntry`。 -首批实时激活使用方现在会使用清单中的命令、渠道和 provider 提示，在更广泛的注册表实体化之前缩小插件加载范围： +可选的清单 `activation` 和 `setup` 块仍然保留在控制平面。它们只是用于激活规划和设置发现的纯元数据描述符；它们不会替代运行时注册、`register(...)` 或 `setupEntry`。 +现在，首批实时激活使用方会利用清单中的命令、渠道和提供商提示，在更广泛的注册表实体化之前先缩小插件加载范围： - CLI 加载会缩小到拥有所请求主命令的插件 - 渠道设置/插件解析会缩小到拥有所请求渠道 id 的插件 -- 显式 provider 设置/运行时解析会缩小到拥有所请求 provider id 的插件 +- 显式提供商设置/运行时解析会缩小到拥有所请求提供商 id 的插件 -激活规划器同时为现有调用方提供仅含 id 的 API，也为新的诊断能力提供 plan API。计划条目会报告插件为何被选中，将显式 `activation.*` 规划器提示与清单所有权回退分开，例如 `providers`、`channels`、`commandAliases`、`setup.providers`、`contracts.tools` 和钩子。这个原因拆分是兼容性边界：现有插件元数据会继续生效，而新代码可以检测宽泛提示或回退行为，而无需改变运行时加载语义。 +激活规划器既为现有调用方暴露仅含 id 的 API，也为新的诊断暴露 plan API。Plan 条目会报告某个插件为何被选中，并将显式 `activation.*` 规划提示与基于清单归属的回退原因分开，例如 `providers`、`channels`、`commandAliases`、`setup.providers`、`contracts.tools` 和 hooks。这种原因拆分是兼容性边界：现有插件元数据仍然有效，而新代码无需改变运行时加载语义，就可以检测宽泛提示或回退行为。 -设置发现现在会优先使用描述符拥有的 id，例如 `setup.providers` 和 `setup.cliBackends`，以便在回退到 `setup-api` 之前先缩小候选插件范围；`setup-api` 用于那些仍然需要设置阶段运行时钩子的插件。provider 设置流程会优先使用清单 `providerAuthChoices`，然后为兼容性回退到运行时向导选项和安装目录选项。显式 `setup.requiresRuntime: false` 是仅描述符层面的截断；省略 `requiresRuntime` 则会为兼容性保留旧版 `setup-api` 回退。如果发现多个插件声称拥有相同的标准化设置 provider 或 CLI backend id，设置查找会拒绝这个有歧义的所有者，而不是依赖发现顺序。当设置运行时确实执行时，注册表诊断会报告 `setup.providers` / `setup.cliBackends` 与由 `setup-api` 注册的 providers 或 CLI backends 之间的偏差，但不会阻止旧版插件。 +设置发现现在优先使用描述符拥有的 id，例如 `setup.providers` 和 `setup.cliBackends`，以便在回退到 `setup-api` 之前先缩小候选插件范围；`setup-api` 仅用于那些仍然需要设置时运行时钩子的插件。提供商设置流程会优先使用清单 `providerAuthChoices`，然后为了兼容性再回退到运行时向导选项和安装目录选项。显式的 `setup.requiresRuntime: false` 是一个仅描述符层面的截止点；省略 `requiresRuntime` 则会为了兼容性保留旧版 `setup-api` 回退。如果发现的多个插件声明了同一个规范化后的设置提供商或 CLI 后端 id，设置查找会拒绝这个存在歧义的归属者，而不是依赖发现顺序。当设置运行时确实执行时，注册表诊断会报告 `setup.providers` / `setup.cliBackends` 与由 `setup-api` 注册的提供商或 CLI 后端之间的漂移，但不会阻止旧版插件。 -### 加载器缓存的内容 +### 加载器会缓存什么 OpenClaw 会保留一些短生命周期的进程内缓存，用于： @@ -67,40 +67,40 @@ OpenClaw 会保留一些短生命周期的进程内缓存，用于： - 清单注册表数据 - 已加载的插件注册表 -这些缓存可减少突发启动开销和重复命令开销。可以安全地将它们视为短期性能缓存，而不是持久化。 +这些缓存可减少突发式启动开销和重复命令开销。可以将它们视为短生命周期的性能缓存，而不是持久化机制。 性能说明： - 设置 `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` 或 `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` 可禁用这些缓存。 -- 使用 `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` 和 `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS` 调整缓存窗口。 +- 可使用 `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` 和 `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS` 调整缓存窗口。 ## 注册表模型 -已加载的插件不会直接修改随意的核心全局状态。它们会注册到一个中央插件注册表中。 +已加载的插件不会直接修改任意核心全局状态。它们会注册到一个中心插件注册表中。 注册表会跟踪： -- 插件记录（标识、来源、源头、状态、诊断） +- 插件记录（身份、来源、起源、状态、诊断） - 工具 - 旧版钩子和类型化钩子 - 渠道 -- providers +- 提供商 - Gateway 网关 RPC 处理器 - HTTP 路由 - CLI 注册器 - 后台服务 - 插件拥有的命令 -然后，核心功能会从该注册表中读取，而不是直接与插件模块通信。这样可以保持单向加载： +随后，核心功能会从这个注册表中读取，而不是直接与插件模块交互。这样可保持单向加载： - 插件模块 -> 注册表注册 - 核心运行时 -> 注册表消费 -这种分离对可维护性很重要。它意味着大多数核心表面只需要一个集成点：“读取注册表”，而不是“对每个插件模块做特殊处理”。 +这种分离对可维护性很重要。它意味着大多数核心表面只需要一个集成点：“读取注册表”，而不是“为每个插件模块做特殊处理”。 -## 会话绑定回调 +## 对话绑定回调 -绑定会话的插件可以在审批结果确定时作出响应。 +绑定对话的插件可以在审批被解决时作出响应。 使用 `api.onConversationBindingResolved(...)` 可在绑定请求被批准或拒绝后接收回调： @@ -110,12 +110,12 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // 现在此插件 + 会话已存在一个绑定。 + // 此插件 + 对话现在已有绑定。 console.log(event.binding?.conversationId); return; } - // 请求被拒绝；清除任何本地待处理状态。 + // 请求被拒绝；清除任何本地挂起状态。 console.log(event.request.conversation.conversationId); }); }, @@ -126,89 +126,89 @@ export default { - `status`：`"approved"` 或 `"denied"` - `decision`：`"allow-once"`、`"allow-always"` 或 `"deny"` -- `binding`：用于已批准请求的已解析绑定 -- `request`：原始请求摘要、分离提示、发送者 id 和会话元数据 +- `binding`：已批准请求的已解析绑定 +- `request`：原始请求摘要、分离提示、发送方 id 和对话元数据 -这个回调仅用于通知。它不会改变谁被允许绑定会话，并且会在核心审批处理完成后运行。 +此回调仅用于通知。它不会改变谁被允许绑定对话，并且会在核心审批处理完成后运行。 -## Provider 运行时钩子 +## 提供商运行时钩子 -Provider 插件有三层： +提供商插件有三层： -- **清单元数据**，用于低成本的运行前查找： - `setup.providers[].envVars`、已弃用的兼容性 `providerAuthEnvVars`、 +- **清单元数据**，用于低成本的运行时前查找： + `setup.providers[].envVars`、已弃用的兼容项 `providerAuthEnvVars`、 `providerAuthAliases`、`providerAuthChoices` 和 `channelEnvVars`。 -- **配置阶段钩子**：`catalog`（旧称 `discovery`）以及 +- **配置时钩子**：`catalog`（旧称 `discovery`）以及 `applyConfigDefaults`。 - **运行时钩子**：40 多个可选钩子，涵盖认证、模型解析、 - 流包装、思考级别、重放策略和用量端点。完整列表见 - [Hook order and usage](#hook-order-and-usage)。 + 流包装、思考级别、重放策略和用量端点。完整列表请参见 + [钩子顺序和用法](#hook-order-and-usage)。 -OpenClaw 仍然拥有通用的 智能体 loop、故障切换、转录处理和工具策略。这些钩子是 provider 特定行为的扩展表面，而不需要整个自定义推理传输层。 +OpenClaw 仍然负责通用智能体循环、故障切换、转录处理和工具策略。这些钩子是提供商特定行为的扩展表面，无需为此实现完整的自定义推理传输。 -当 provider 具有基于环境变量的凭证，并且通用认证/Status/模型选择器路径需要在不加载插件运行时的情况下看到这些凭证时，请使用清单 `setup.providers[].envVars`。已弃用的 `providerAuthEnvVars` 在弃用窗口期间仍会被兼容适配器读取，使用它的非内置插件会收到一条清单诊断信息。当一个 provider id 应复用另一个 provider id 的环境变量、auth 配置文件、配置支持的认证以及 API 密钥新手引导选项时，请使用清单 `providerAuthAliases`。当新手引导/认证选择 CLI 表面需要在不加载 provider 运行时的情况下了解 provider 的 choice id、分组标签和简单的单标志认证接线时，请使用清单 `providerAuthChoices`。将 provider 运行时的 `envVars` 保留给面向操作员的提示，例如新手引导标签或 OAuth client-id/client-secret 设置变量。 +当提供商具有基于环境变量的凭证，并且通用认证/Status/模型选择器路径需要在不加载插件运行时的情况下看到这些凭证时，请使用清单 `setup.providers[].envVars`。已弃用的 `providerAuthEnvVars` 在弃用窗口期间仍会由兼容适配器读取，而使用它的非内置插件会收到清单诊断。当一个提供商 id 需要复用另一个提供商 id 的环境变量、认证配置文件、基于配置的认证以及 API 密钥新手引导选项时，请使用清单 `providerAuthAliases`。当新手引导/认证选项 CLI 表面需要在不加载提供商运行时的情况下了解该提供商的 choice id、分组标签和简单的单标志认证接线时，请使用清单 `providerAuthChoices`。将提供商运行时 `envVars` 保留给面向运维人员的提示，例如新手引导标签或 OAuth client-id/client-secret 设置变量。 -当一个渠道具有由环境变量驱动的认证或设置，并且通用 shell 环境变量回退、配置/Status 检查或设置提示需要在不加载渠道运行时的情况下看到这些信息时，请使用清单 `channelEnvVars`。 +当某个渠道具有由环境变量驱动的认证或设置，并且通用 shell 环境变量回退、配置/Status 检查或设置提示需要在不加载渠道运行时的情况下看到这些内容时，请使用清单 `channelEnvVars`。 ### 钩子顺序和用法 -对于模型/provider 插件，OpenClaw 会按大致如下顺序调用钩子。 +对于模型/提供商插件，OpenClaw 会大致按以下顺序调用钩子。 “何时使用”列是快速决策指南。 | # | 钩子 | 作用 | 何时使用 | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | 在生成 `models.json` 期间，将 provider 配置发布到 `models.providers` 中 | provider 拥有目录或基础 URL 默认值 | -| 2 | `applyConfigDefaults` | 在配置实体化期间应用 provider 拥有的全局配置默认值 | 默认值依赖于认证模式、环境变量或 provider 模型族语义 | -| -- | _(内置模型查找)_ | OpenClaw 会先尝试常规的注册表/目录路径 | _(不是插件钩子)_ | -| 3 | `normalizeModelId` | 在查找前标准化旧版或预览版 model-id 别名 | provider 在规范模型解析前拥有别名清理逻辑 | -| 4 | `normalizeTransport` | 在通用模型组装前，标准化 provider 族的 `api` / `baseUrl` | provider 在同一传输族中为自定义 provider id 拥有传输清理逻辑 | -| 5 | `normalizeConfig` | 在运行时/provider 解析前标准化 `models.providers.` | provider 需要应与插件一起维护的配置清理逻辑；内置的 Google 族辅助逻辑也会为受支持的 Google 配置项提供兜底 | -| 6 | `applyNativeStreamingUsageCompat` | 将原生流式用量兼容性重写应用到配置 providers | provider 需要基于端点的原生流式用量元数据修复 | -| 7 | `resolveConfigApiKey` | 在运行时认证加载前，为配置 providers 解析环境变量标记认证 | provider 拥有自己的环境变量标记 API key 解析逻辑；`amazon-bedrock` 在这里也有一个内置的 AWS 环境变量标记解析器 | -| 8 | `resolveSyntheticAuth` | 在不持久化明文的情况下暴露本地/自托管或配置支持的认证 | provider 可通过合成/本地凭证标记运行 | -| 9 | `resolveExternalAuthProfiles` | 叠加 provider 拥有的外部认证配置文件；默认 `persistence` 为 `runtime-only`，适用于 CLI/应用拥有的凭证 | provider 可复用外部认证凭证，而无需持久化复制的 refresh token；请在清单中声明 `contracts.externalAuthProviders` | -| 10 | `shouldDeferSyntheticProfileAuth` | 将已存储的合成配置文件占位符优先级降到环境变量/配置支持认证之后 | provider 存储了不应获得更高优先级的合成占位配置文件 | -| 11 | `resolveDynamicModel` | 对尚未出现在本地注册表中的 provider 拥有模型 id 进行同步回退 | provider 接受任意上游模型 id | -| 12 | `prepareDynamicModel` | 先执行异步预热，然后再次运行 `resolveDynamicModel` | provider 在解析未知 id 之前需要网络元数据 | -| 13 | `normalizeResolvedModel` | 在嵌入式运行器使用已解析模型前执行最终重写 | provider 需要传输重写，但仍使用核心传输 | -| 14 | `contributeResolvedModelCompat` | 为位于另一兼容传输之后的厂商模型提供兼容性标志 | provider 可在不接管该 provider 的前提下，在代理传输上识别自己的模型 | -| 15 | `capabilities` | 由共享核心逻辑使用的 provider 拥有的转录/工具元数据 | provider 需要转录/provider 族特有差异处理 | -| 16 | `normalizeToolSchemas` | 在嵌入式运行器看到它们之前标准化工具模式 | provider 需要传输族级别的模式清理 | -| 17 | `inspectToolSchemas` | 在标准化后暴露 provider 拥有的模式诊断 | provider 希望提供关键字警告，而不需要教会核心 provider 特定规则 | -| 18 | `resolveReasoningOutputMode` | 选择原生推理输出契约还是带标签的推理输出契约 | provider 需要带标签的推理/最终输出，而不是原生字段 | -| 19 | `prepareExtraParams` | 在通用流选项包装器之前标准化请求参数 | provider 需要默认请求参数或按 provider 清理参数 | -| 20 | `createStreamFn` | 用自定义传输完全替换常规流路径 | provider 需要自定义线协议，而不仅仅是包装器 | -| 21 | `wrapStreamFn` | 在应用通用包装器之后对流函数再做包装 | provider 需要请求头/请求体/模型兼容性包装器，但不需要自定义传输 | -| 22 | `resolveTransportTurnState` | 附加原生的逐轮传输头或元数据 | provider 希望通用传输发送 provider 原生轮次标识 | -| 23 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 头或会话冷却策略 | provider 希望通用 WS 传输调整会话头或回退策略 | -| 24 | `formatApiKey` | 认证配置文件格式化器：将已存储配置文件转换为运行时 `apiKey` 字符串 | provider 存储额外认证元数据，并需要自定义运行时令牌形状 | -| 25 | `refreshOAuth` | 为自定义刷新端点或刷新失败策略覆盖 OAuth 刷新逻辑 | provider 不适用于共享的 `pi-ai` 刷新器 | -| 26 | `buildAuthDoctorHint` | 当 OAuth 刷新失败时附加修复提示 | provider 在刷新失败后需要 provider 自有的认证修复指引 | -| 27 | `matchesContextOverflowError` | provider 自有的上下文窗口溢出匹配器 | provider 存在通用启发式无法识别的原始溢出错误 | -| 28 | `classifyFailoverReason` | provider 自有的故障切换原因分类 | provider 可将原始 API/传输错误映射为限流/过载等原因 | -| 29 | `isCacheTtlEligible` | 面向代理/回传 providers 的提示缓存策略 | provider 需要代理特定的缓存 TTL 门控 | -| 30 | `buildMissingAuthMessage` | 替换通用的缺失认证恢复消息 | provider 需要 provider 特定的缺失认证恢复提示 | -| 31 | `suppressBuiltInModel` | 过时上游模型抑制，并可选提供面向用户的错误提示 | provider 需要隐藏过时的上游条目，或用厂商提示替换它们 | -| 32 | `augmentModelCatalog` | 在发现之后追加合成/最终目录条目 | provider 需要在 `models list` 和选择器中提供合成的前向兼容条目 | -| 33 | `resolveThinkingProfile` | 针对特定模型设置 `/think` 级别、显示标签和默认值 | provider 为选定模型提供自定义思考层级或二元标签 | -| 34 | `isBinaryThinking` | 开/关推理切换兼容性钩子 | provider 只暴露二元的思考开/关 | -| 35 | `supportsXHighThinking` | `xhigh` 推理支持兼容性钩子 | provider 希望仅在部分模型上启用 `xhigh` | -| 36 | `resolveDefaultThinkingLevel` | 默认 `/think` 级别兼容性钩子 | provider 拥有某个模型族的默认 `/think` 策略 | -| 37 | `isModernModelRef` | 用于实时配置文件过滤和 smoke 选择的现代模型匹配器 | provider 拥有实时/smoke 首选模型匹配逻辑 | -| 38 | `prepareRuntimeAuth` | 在推理之前，将已配置凭证交换为实际运行时令牌/key | provider 需要令牌交换或短生命周期请求凭证 | -| 39 | `resolveUsageAuth` | 为 `/usage` 及相关 Status 表面解析用量/计费凭证 | provider 需要自定义用量/配额令牌解析，或使用不同的用量凭证 | -| 40 | `fetchUsageSnapshot` | 在认证解析完成后获取并标准化 provider 特定的用量/配额快照 | provider 需要 provider 特定的用量端点或负载解析器 | -| 41 | `createEmbeddingProvider` | 为 memory/搜索构建 provider 自有的嵌入适配器 | Memory 嵌入行为应归属于 provider 插件 | -| 42 | `buildReplayPolicy` | 返回一个重放策略，用于控制该 provider 的转录处理 | provider 需要自定义转录策略（例如，移除 thinking 块） | -| 43 | `sanitizeReplayHistory` | 在通用转录清理之后重写重放历史 | provider 需要超出共享压缩辅助工具之外的 provider 特定重放重写 | -| 44 | `validateReplayTurns` | 在嵌入式运行器之前对重放轮次进行最终验证或重塑 | provider 传输在通用清理之后需要更严格的轮次验证 | -| 45 | `onModelSelected` | 在模型被选中后运行 provider 自有的后置副作用 | 当模型变为活动状态时，provider 需要遥测或 provider 自有状态 | +| 1 | `catalog` | 在生成 `models.json` 期间，将提供商配置发布到 `models.providers` 中 | 提供商拥有目录或 base URL 默认值 | +| 2 | `applyConfigDefaults` | 在配置实体化期间应用由提供商拥有的全局配置默认值 | 默认值依赖于认证模式、环境变量或提供商模型族语义 | +| -- | _(内置模型查找)_ | OpenClaw 会先尝试正常的注册表/目录路径 | _(不是插件钩子)_ | +| 3 | `normalizeModelId` | 在查找之前规范化旧版或预览版 model-id 别名 | 提供商在规范模型解析之前拥有别名清理逻辑 | +| 4 | `normalizeTransport` | 在通用模型组装之前，规范化提供商族的 `api` / `baseUrl` | 提供商为同一传输族中的自定义提供商 id 拥有传输清理逻辑 | +| 5 | `normalizeConfig` | 在运行时/提供商解析之前规范化 `models.providers.` | 提供商需要应与插件放在一起的配置清理；内置的 Google 族辅助逻辑也会为受支持的 Google 配置项提供兜底 | +| 6 | `applyNativeStreamingUsageCompat` | 将原生流式用量兼容性重写应用到配置提供商 | 提供商需要基于端点驱动的原生流式用量元数据修复 | +| 7 | `resolveConfigApiKey` | 在加载运行时认证之前，为配置提供商解析环境变量标记认证 | 提供商拥有环境变量标记 API 密钥解析逻辑；`amazon-bedrock` 在这里也有一个内置的 AWS 环境变量标记解析器 | +| 8 | `resolveSyntheticAuth` | 在不持久化明文的情况下暴露 local/self-hosted 或基于配置的认证 | 提供商可以使用合成/local 凭证标记运行 | +| 9 | `resolveExternalAuthProfiles` | 叠加由提供商拥有的外部认证配置文件；CLI/应用拥有的凭证默认 `persistence` 为 `runtime-only` | 提供商会复用外部认证凭证，而不持久化复制的刷新令牌；请在清单中声明 `contracts.externalAuthProviders` | +| 10 | `shouldDeferSyntheticProfileAuth` | 将已存储的合成配置文件占位符降级到环境变量/基于配置的认证之后 | 提供商会存储不应获得优先级的合成占位配置文件 | +| 11 | `resolveDynamicModel` | 对尚未进入本地注册表的、由提供商拥有的模型 id 进行同步回退解析 | 提供商接受任意上游模型 id | +| 12 | `prepareDynamicModel` | 先进行异步预热，然后再次运行 `resolveDynamicModel` | 提供商在解析未知 id 之前需要网络元数据 | +| 13 | `normalizeResolvedModel` | 在嵌入式运行器使用已解析模型之前执行最终重写 | 提供商需要传输重写，但仍使用核心传输 | +| 14 | `contributeResolvedModelCompat` | 为位于其他兼容传输之后的供应商模型贡献兼容标记 | 提供商可以在代理传输上识别自己的模型，而无需接管该提供商 | +| 15 | `capabilities` | 由提供商拥有、供共享核心逻辑使用的转录/工具元数据 | 提供商需要转录或提供商族特有的特殊处理 | +| 16 | `normalizeToolSchemas` | 在嵌入式运行器看到工具模式之前先规范化它们 | 提供商需要传输族级别的模式清理 | +| 17 | `inspectToolSchemas` | 在规范化之后暴露由提供商拥有的模式诊断 | 提供商希望给出关键字警告，而无需让核心理解提供商特定规则 | +| 18 | `resolveReasoningOutputMode` | 选择原生推理输出契约还是带标签的推理输出契约 | 提供商需要带标签的推理/最终输出，而不是原生字段 | +| 19 | `prepareExtraParams` | 在通用流选项包装器之前规范化请求参数 | 提供商需要默认请求参数或按提供商进行参数清理 | +| 20 | `createStreamFn` | 用自定义传输完全替换正常的流路径 | 提供商需要自定义线协议，而不仅仅是包装器 | +| 21 | `wrapStreamFn` | 在应用通用包装器之后包装流函数 | 提供商需要请求头/请求体/模型兼容性包装器，而不是自定义传输 | +| 22 | `resolveTransportTurnState` | 附加原生的逐轮传输头或元数据 | 提供商希望通用传输发送提供商原生的轮次标识 | +| 23 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 头或会话冷却策略 | 提供商希望通用 WS 传输调整会话头或回退策略 | +| 24 | `formatApiKey` | 认证配置文件格式化器：已存储配置文件会变成运行时 `apiKey` 字符串 | 提供商会存储额外的认证元数据，并需要自定义运行时令牌形状 | +| 25 | `refreshOAuth` | 为自定义刷新端点或刷新失败策略覆写 OAuth 刷新逻辑 | 提供商不适配共享的 `pi-ai` 刷新器 | +| 26 | `buildAuthDoctorHint` | 当 OAuth 刷新失败时附加修复提示 | 提供商在刷新失败后需要由提供商拥有的认证修复指导 | +| 27 | `matchesContextOverflowError` | 由提供商拥有的上下文窗口溢出匹配器 | 提供商存在通用启发式无法捕获的原始溢出错误 | +| 28 | `classifyFailoverReason` | 由提供商拥有的故障切换原因分类 | 提供商可以将原始 API/传输错误映射为速率限制/过载等 | +| 29 | `isCacheTtlEligible` | 面向代理/回传提供商的提示缓存策略 | 提供商需要代理特定的缓存 TTL 门控 | +| 30 | `buildMissingAuthMessage` | 替换通用的缺失认证恢复消息 | 提供商需要提供商特定的缺失认证恢复提示 | +| 31 | `suppressBuiltInModel` | 过时上游模型抑制，并可附带面向用户的错误提示 | 提供商需要隐藏过时的上游条目，或用供应商提示替换它们 | +| 32 | `augmentModelCatalog` | 在发现之后附加合成/最终目录条目 | 提供商需要在 `models list` 和选择器中加入面向未来兼容的合成条目 | +| 33 | `resolveThinkingProfile` | 为特定模型设置 `/think` 级别、显示标签和默认值 | 提供商为选定模型公开自定义思考阶梯或二元标签 | +| 34 | `isBinaryThinking` | 开/关推理切换兼容性钩子 | 提供商只公开二元的思考开/关 | +| 35 | `supportsXHighThinking` | `xhigh` 推理支持兼容性钩子 | 提供商希望仅在部分模型上启用 `xhigh` | +| 36 | `resolveDefaultThinkingLevel` | 默认 `/think` 级别兼容性钩子 | 提供商拥有某个模型族的默认 `/think` 策略 | +| 37 | `isModernModelRef` | 用于实时配置文件过滤和 smoke 选择的现代模型匹配器 | 提供商拥有实时/smoke 首选模型匹配逻辑 | +| 38 | `prepareRuntimeAuth` | 在推理之前，将已配置凭证交换为实际运行时令牌/密钥 | 提供商需要令牌交换或短生命周期请求凭证 | +| 39 | `resolveUsageAuth` | 为 `/usage` 和相关 Status 表面解析用量/计费凭证 | 提供商需要自定义用量/配额令牌解析，或使用不同的用量凭证 | +| 40 | `fetchUsageSnapshot` | 在认证解析完成后，获取并规范化提供商特定的用量/配额快照 | 提供商需要提供商特定的用量端点或负载解析器 | +| 41 | `createEmbeddingProvider` | 为 Memory Wiki/搜索构建由提供商拥有的嵌入适配器 | Memory Wiki 嵌入行为应归属于提供商插件 | +| 42 | `buildReplayPolicy` | 返回一个重放策略，用于控制该提供商的转录处理 | 提供商需要自定义转录策略（例如剥离 thinking 块） | +| 43 | `sanitizeReplayHistory` | 在通用转录清理之后重写重放历史 | 提供商需要超出共享压缩辅助逻辑之外的提供商特定重放重写 | +| 44 | `validateReplayTurns` | 在嵌入式运行器之前，对重放轮次进行最终验证或重塑 | 提供商传输在通用净化之后需要更严格的轮次验证 | +| 45 | `onModelSelected` | 在模型被选中后运行由提供商拥有的副作用 | 当模型变为活动状态时，提供商需要遥测或由提供商拥有的状态 | -`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查匹配的 provider 插件，然后继续尝试其他具备钩子能力的 provider 插件，直到某个插件实际更改了模型 id 或传输/配置为止。这样可以让别名/兼容 provider shim 正常工作，而无需调用方知道哪个内置插件拥有该重写逻辑。如果没有 provider 钩子重写受支持的 Google 族配置项，内置的 Google 配置标准化器仍会应用该兼容性清理。 +`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查匹配到的提供商插件，然后继续尝试其他具备相应钩子能力的提供商插件，直到有一个实际更改了模型 id 或传输/配置。这样可以让别名/兼容性提供商 shim 正常工作，而无需调用方知道是哪个内置插件拥有该重写逻辑。如果没有任何提供商钩子重写受支持的 Google 族配置项，内置的 Google 配置规范化器仍会应用该兼容性清理。 -如果 provider 需要完全自定义的线协议或自定义请求执行器，那属于另一类扩展。这些钩子适用于仍运行在 OpenClaw 常规推理 loop 上的 provider 行为。 +如果提供商需要完全自定义的线协议或自定义请求执行器，那是另一类扩展。这些钩子适用于仍运行在 OpenClaw 正常推理循环上的提供商行为。 -### Provider 示例 +### 提供商示例 ```ts api.registerProvider({ @@ -264,41 +264,41 @@ api.registerProvider({ ### 内置示例 -内置 provider 插件会组合使用上述钩子，以适配各个厂商的目录、认证、思考、重放和用量需求。权威钩子集合与各个插件一起保存在 `extensions/` 下；本页说明其形状，而不是镜像完整列表。 +内置的提供商插件会组合使用上述钩子，以适配各供应商在目录、认证、思考、重放和用量方面的需求。权威的钩子集合与各插件一起存放在 `extensions/` 下；本页旨在说明这些形状，而不是镜像那份列表。 - - OpenRouter、Kilocode、Z.AI、xAI 注册 `catalog` 以及 - `resolveDynamicModel` / `prepareDynamicModel`，从而可以在 OpenClaw 的静态目录之前暴露上游 - 模型 id。 + + OpenRouter、Kilocode、Z.AI、xAI 会注册 `catalog` 以及 + `resolveDynamicModel` / `prepareDynamicModel`，这样它们就能在 + OpenClaw 的静态目录之前先暴露上游模型 id。 - - GitHub Copilot、Gemini CLI、ChatGPT Codex、MiniMax、Xiaomi、z.ai 将 + + GitHub Copilot、Gemini CLI、ChatGPT Codex、MiniMax、Xiaomi、z.ai 会将 `prepareRuntimeAuth` 或 `formatApiKey` 与 `resolveUsageAuth` + - `fetchUsageSnapshot` 配对使用，以负责令牌交换和 `/usage` 集成。 + `fetchUsageSnapshot` 搭配使用，以掌控令牌交换和 `/usage` 集成。 - - 共享命名族（`google-gemini`、`passthrough-gemini`、 - `anthropic-by-model`、`hybrid-anthropic-openai`）允许 providers 通过 - `buildReplayPolicy` 选择转录策略，而不是让每个插件都重新实现清理逻辑。 + + 共享的命名系列（`google-gemini`、`passthrough-gemini`、 + `anthropic-by-model`、`hybrid-anthropic-openai`）让提供商可以通过 + `buildReplayPolicy` 选择加入转录策略，而不必由每个插件各自重新实现清理逻辑。 - + `byteplus`、`cloudflare-ai-gateway`、`huggingface`、`kimi-coding`、`nvidia`、 `qianfan`、`synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 - `volcengine` 只注册 `catalog`，并使用共享推理 loop。 + `volcengine` 只注册 `catalog`，并使用共享的推理循环。 - - Beta 请求头、`/fast` / `serviceTier` 以及 `context1m` 位于 + + Beta 标头、`/fast` / `serviceTier` 以及 `context1m` 位于 Anthropic 插件公开的 `api.ts` / `contract-api.ts` 接缝中 （`wrapAnthropicProviderStream`、`resolveAnthropicBetas`、 - `resolveAnthropicFastMode`、`resolveAnthropicServiceTier`），而不是放在 + `resolveAnthropicFastMode`、`resolveAnthropicServiceTier`），而不是位于 通用 SDK 中。 ## 运行时辅助工具 -插件可以通过 `api.runtime` 访问选定的核心辅助工具。对于 TTS： +插件可以通过 `api.runtime` 访问部分选定的核心辅助工具。对于 TTS： ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -319,14 +319,14 @@ const voices = await api.runtime.tts.listVoices({ 说明： -- `textToSpeech` 返回用于文件/语音便笺表面的常规核心 TTS 输出负载。 -- 使用核心 `messages.tts` 配置和 provider 选择。 -- 返回 PCM 音频缓冲区 + 采样率。插件必须为 providers 重新采样/编码。 -- `listVoices` 对每个 provider 而言都是可选的。将其用于厂商自有的语音选择器或设置流程。 -- 语音列表可以包含更丰富的元数据，例如区域设置、性别和个性标签，以用于 provider 感知的选择器。 -- 目前 OpenAI 和 ElevenLabs 支持电话场景。Microsoft 不支持。 +- `textToSpeech` 会返回用于文件/语音便笺表面的常规核心 TTS 输出负载。 +- 使用核心 `messages.tts` 配置和提供商选择逻辑。 +- 返回 PCM 音频缓冲区 + 采样率。插件必须为提供商自行重采样/编码。 +- `listVoices` 对每个提供商来说是可选的。可将其用于由供应商拥有的语音选择器或设置流程。 +- 语音列表可包含更丰富的元数据，例如语言区域、性别和个性标签，供具备提供商感知能力的选择器使用。 +- OpenAI 和 ElevenLabs 目前支持电话语音。Microsoft 不支持。 -插件也可以通过 `api.registerSpeechProvider(...)` 注册语音 providers。 +插件也可以通过 `api.registerSpeechProvider(...)` 注册语音提供商。 ```ts api.registerSpeechProvider({ @@ -347,13 +347,11 @@ api.registerSpeechProvider({ 说明： - 将 TTS 策略、回退和回复投递保留在核心中。 -- 将语音 providers 用于厂商自有的合成行为。 -- 旧版 Microsoft `edge` 输入会被标准化为 `microsoft` provider id。 -- 首选的所有权模型是面向公司的：随着 OpenClaw 增加这些 - 能力契约，一个厂商插件可以同时拥有文本、语音、图像以及未来的媒体 providers。 +- 语音提供商用于由供应商拥有的合成行为。 +- 旧版 Microsoft `edge` 输入会被规范化为 `microsoft` 提供商 id。 +- 首选的归属模型是面向公司的：随着 OpenClaw 增加这些能力契约，一个供应商插件可以统一拥有文本、语音、图像以及未来的媒体提供商。 -对于图像/音频/视频理解，插件会注册一个带类型的 -媒体理解 provider，而不是通用的键/值包： +对于图像/音频/视频理解，插件会注册一个类型化的媒体理解提供商，而不是通用的键值袋： ```ts api.registerMediaUnderstandingProvider({ @@ -368,12 +366,11 @@ api.registerMediaUnderstandingProvider({ 说明： - 将编排、回退、配置和渠道接线保留在核心中。 -- 将厂商行为保留在 provider 插件中。 -- 增量扩展应保持类型化：新的可选方法、新的可选 - 结果字段、新的可选能力。 -- 视频生成已经遵循同样的模式： +- 将供应商行为保留在提供商插件中。 +- 增量扩展应保持类型化：新的可选方法、新的可选结果字段、新的可选能力。 +- 视频生成已经遵循相同模式： - 核心拥有能力契约和运行时辅助工具 - - 厂商插件注册 `api.registerVideoGenerationProvider(...)` + - 供应商插件注册 `api.registerVideoGenerationProvider(...)` - 功能/渠道插件使用 `api.runtime.videoGeneration.*` 对于媒体理解运行时辅助工具，插件可以调用： @@ -391,8 +388,7 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -对于音频转录，插件可以使用媒体理解运行时 -或较旧的 STT 别名： +对于音频转写，插件既可以使用媒体理解运行时，也可以使用旧版 STT 别名： ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -406,11 +402,11 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ 说明： - `api.runtime.mediaUnderstanding.*` 是图像/音频/视频理解的首选共享表面。 -- 使用核心媒体理解音频配置（`tools.media.audio`）和 provider 回退顺序。 -- 当未产生转录输出时返回 `{ text: undefined }`（例如输入被跳过/不受支持）。 +- 使用核心媒体理解音频配置（`tools.media.audio`）和提供商回退顺序。 +- 当没有产生转写输出时（例如输入被跳过/不受支持），返回 `{ text: undefined }`。 - `api.runtime.stt.transcribeAudioFile(...)` 仍保留为兼容性别名。 -插件还可以通过 `api.runtime.subagent` 启动后台 subagent 运行： +插件也可以通过 `api.runtime.subagent` 启动后台子智能体运行： ```ts const result = await api.runtime.subagent.run({ @@ -424,14 +420,13 @@ const result = await api.runtime.subagent.run({ 说明： -- `provider` 和 `model` 是每次运行的可选覆盖项，不是持久会话更改。 -- OpenClaw 仅对受信任调用方接受这些覆盖字段。 -- 对于插件自有的回退运行，操作员必须通过 `plugins.entries..subagent.allowModelOverride: true` 显式启用。 -- 使用 `plugins.entries..subagent.allowedModels` 将受信任插件限制为特定的规范 `provider/model` 目标，或设为 `"*"` 以显式允许任何目标。 -- 不受信任插件的 subagent 运行仍然可用，但覆盖请求会被拒绝，而不是静默回退。 +- `provider` 和 `model` 是每次运行可选的覆写项，而不是持久化的会话变更。 +- OpenClaw 仅对受信任调用方接受这些覆写字段。 +- 对于插件拥有的回退运行，运维人员必须通过 `plugins.entries..subagent.allowModelOverride: true` 显式启用。 +- 使用 `plugins.entries..subagent.allowedModels` 可将受信任插件限制为特定的规范 `provider/model` 目标，或者使用 `"*"` 显式允许任意目标。 +- 不受信任插件的子智能体运行仍然可用，但覆写请求会被拒绝，而不是静默回退。 -对于 web 搜索，插件可以使用共享运行时辅助工具，而不是 -直接深入 智能体 工具接线： +对于 web 搜索，插件可以使用共享运行时辅助工具，而不是深入智能体工具接线： ```ts const providers = api.runtime.webSearch.listProviders({ @@ -447,14 +442,13 @@ const result = await api.runtime.webSearch.search({ }); ``` -插件也可以通过 -`api.registerWebSearchProvider(...)` 注册 web 搜索 providers。 +插件也可以通过 `api.registerWebSearchProvider(...)` 注册 web 搜索提供商。 说明： -- 将 provider 选择、凭证解析和共享请求语义保留在核心中。 -- 将 web 搜索 providers 用于厂商特定的搜索传输。 -- `api.runtime.webSearch.*` 是需要搜索行为且不依赖 智能体 工具包装器的功能/渠道插件的首选共享表面。 +- 将提供商选择、凭证解析和共享请求语义保留在核心中。 +- web 搜索提供商用于供应商特定的搜索传输。 +- `api.runtime.webSearch.*` 是功能/渠道插件在需要搜索行为但不依赖智能体工具包装器时的首选共享表面。 ### `api.runtime.imageGeneration` @@ -469,8 +463,8 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`：使用已配置的图像生成 provider 链生成图像。 -- `listProviders(...)`：列出可用的图像生成 providers 及其能力。 +- `generate(...)`：使用已配置的图像生成提供商链生成图像。 +- `listProviders(...)`：列出可用的图像生成提供商及其能力。 ## Gateway 网关 HTTP 路由 @@ -492,23 +486,23 @@ api.registerHttpRoute({ 路由字段： - `path`：Gateway 网关 HTTP 服务器下的路由路径。 -- `auth`：必填。使用 `"gateway"` 表示需要常规 Gateway 网关认证，或使用 `"plugin"` 表示插件管理的认证/webhook 验证。 +- `auth`：必填。使用 `"gateway"` 以要求普通 Gateway 网关认证，或使用 `"plugin"` 以要求插件管理的认证/webhook 验证。 - `match`：可选。`"exact"`（默认）或 `"prefix"`。 -- `replaceExisting`：可选。允许同一插件替换自己现有的路由注册。 +- `replaceExisting`：可选。允许同一插件替换它自己现有的路由注册。 - `handler`：当路由处理了请求时返回 `true`。 说明： -- `api.registerHttpHandler(...)` 已移除，并会导致插件加载错误。请改用 `api.registerHttpRoute(...)`。 +- `api.registerHttpHandler(...)` 已被移除，并会导致插件加载错误。请改用 `api.registerHttpRoute(...)`。 - 插件路由必须显式声明 `auth`。 -- 精确的 `path + match` 冲突会被拒绝，除非设置了 `replaceExisting: true`，且一个插件不能替换另一个插件的路由。 -- 具有不同 `auth` 级别的重叠路由会被拒绝。仅在相同认证级别内保留 `exact`/`prefix` 贯穿链。 -- `auth: "plugin"` 路由**不会**自动收到操作员运行时作用域。它们用于插件管理的 webhook/签名验证，而不是特权 Gateway 网关辅助调用。 -- `auth: "gateway"` 路由在 Gateway 网关请求运行时作用域内运行，但该作用域是有意保守的： - - 共享密钥 bearer 认证（`gateway.auth.mode = "token"` / `"password"`）会将插件路由运行时作用域固定为 `operator.write`，即使调用方发送了 `x-openclaw-scopes` - - 受信任的携带身份 HTTP 模式（例如 `trusted-proxy` 或私有入口上的 `gateway.auth.mode = "none"`）仅在显式存在该请求头时才接受 `x-openclaw-scopes` - - 如果这些携带身份的插件路由请求中缺少 `x-openclaw-scopes`，运行时作用域会回退为 `operator.write` -- 实用规则：不要假设 gateway-auth 插件路由天然就是管理员表面。如果你的路由需要仅管理员可用的行为，请要求使用携带身份的认证模式，并记录显式 `x-openclaw-scopes` 请求头契约。 +- 除非设置 `replaceExisting: true`，否则精确的 `path + match` 冲突会被拒绝，而且一个插件不能替换另一个插件的路由。 +- 具有不同 `auth` 级别的重叠路由会被拒绝。请仅在相同认证级别内保持 `exact`/`prefix` 的贯穿链。 +- `auth: "plugin"` 路由**不会**自动接收运维人员运行时作用域。它们用于插件管理的 webhook/签名验证，而不是有特权的 Gateway 网关辅助调用。 +- `auth: "gateway"` 路由会在 Gateway 网关请求运行时作用域内运行，但该作用域是有意保守的： + - 共享密钥 bearer 认证（`gateway.auth.mode = "token"` / `"password"`）会将插件路由运行时作用域固定为 `operator.write`，即使调用方发送了 `x-openclaw-scopes` 也是如此 + - 受信任、带身份的 HTTP 模式（例如 `trusted-proxy`，或私有入口上的 `gateway.auth.mode = "none"`）只有在显式提供该标头时，才会遵循 `x-openclaw-scopes` + - 如果这些带身份的插件路由请求中缺少 `x-openclaw-scopes`，运行时作用域会回退为 `operator.write` +- 实际规则：不要假设一个经过 gateway 认证的插件路由就是隐式的管理员表面。如果你的路由需要仅管理员可用的行为，请要求带身份的认证模式，并记录显式的 `x-openclaw-scopes` 标头契约。 ## 插件 SDK 导入路径 @@ -521,107 +515,108 @@ api.registerHttpRoute({ | `openclaw/plugin-sdk/core` | 通用共享辅助工具和总括契约 | | `openclaw/plugin-sdk/config-schema` | 根 `openclaw.json` Zod 模式（`OpenClawSchema`） | -渠道插件可从一系列窄接缝中选择——`channel-setup`、 +渠道插件应从一组窄接缝中进行选择——`channel-setup`、 `setup-runtime`、`setup-adapter-runtime`、`setup-tools`、`channel-pairing`、 `channel-contract`、`channel-feedback`、`channel-inbound`、`channel-lifecycle`、 `channel-reply-pipeline`、`command-auth`、`secret-input`、`webhook-ingress`、 -`channel-targets` 和 `channel-actions`。审批行为应统一到单一的 `approvalCapability` 契约上，而不是混杂在无关的插件字段之间。参见 [Channel Plugins](/zh-CN/plugins/sdk-channel-plugins)。 +`channel-targets` 和 `channel-actions`。审批行为应统一到单一的 +`approvalCapability` 契约上，而不是分散混用在不相关的插件字段之间。 +请参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。 运行时和配置辅助工具位于对应的 `*-runtime` 子路径下 （`approval-runtime`、`config-runtime`、`infra-runtime`、`agent-runtime`、 `lazy-runtime`、`directory-runtime`、`text-runtime`、`runtime-store` 等）。 -`openclaw/plugin-sdk/channel-runtime` 已弃用——它是面向旧插件的兼容 shim。新代码应改为导入更窄的通用原语。 +`openclaw/plugin-sdk/channel-runtime` 已弃用——它是为旧版插件保留的兼容性 shim。 +新代码应改为导入更窄的通用原语。 -仓库内部入口点（按每个内置插件软件包根目录划分）： +仓库内部入口点（按每个内置插件包根目录划分）： -- `index.js` — 内置插件入口 -- `api.js` — 辅助工具/类型 barrel -- `runtime-api.js` — 仅运行时 barrel -- `setup-entry.js` — 设置插件入口 +- `index.js` —— 内置插件入口 +- `api.js` —— 辅助工具/类型 barrel +- `runtime-api.js` —— 仅运行时 barrel +- `setup-entry.js` —— 设置插件入口 -外部插件只能导入 `openclaw/plugin-sdk/*` 子路径。绝不要从核心或另一个插件中导入其他插件软件包的 `src/*`。 -Facade 加载的入口点会优先使用当前活动的运行时配置快照；如果不存在，则回退到磁盘上已解析的配置文件。 +外部插件应只导入 `openclaw/plugin-sdk/*` 子路径。绝不要从核心或其他插件中导入另一个插件包的 `src/*`。 +通过 facade 加载的入口点在存在活动运行时配置快照时会优先使用它，否则回退到磁盘上的已解析配置文件。 -诸如 `image-generation`、`media-understanding` 和 `speech` 这样的能力专用子路径之所以存在，是因为内置插件目前正在使用它们。它们并不自动成为长期冻结的外部契约——在依赖它们之前，请查阅相应的 SDK 参考页面。 +诸如 `image-generation`、`media-understanding` 和 `speech` 之类的能力专用子路径之所以存在，是因为内置插件目前正在使用它们。它们并不自动构成长久冻结的外部契约——在依赖它们时，请查阅相应的 SDK 参考页面。 ## 消息工具模式 -对于反应、已读和投票等非消息原语，插件应自行负责特定渠道的 `describeMessageTool(...)` 模式扩展。 -共享发送展示应使用通用 `MessagePresentation` 契约，而不是 provider 原生的按钮、组件、块或卡片字段。 -有关该契约、回退规则、provider 映射和插件作者检查清单，请参阅 [Message Presentation](/zh-CN/plugins/message-presentation)。 +对于反应、已读和投票等非消息原语，插件应拥有渠道特定的 `describeMessageTool(...)` 模式贡献。 +共享发送呈现应使用通用 `MessagePresentation` 契约，而不是提供商原生的按钮、组件、块或卡片字段。 +关于契约、回退规则、提供商映射以及插件作者检查清单，请参见 [消息呈现](/zh-CN/plugins/message-presentation)。 -具备发送能力的插件会通过消息能力声明自己能渲染什么： +具备发送能力的插件通过消息能力声明自己能渲染什么： -- `presentation`，用于语义化展示块（`text`、`context`、`divider`、`buttons`、`select`） -- `delivery-pin`，用于固定投递请求 +- `presentation`，用于语义化呈现块（`text`、`context`、`divider`、`buttons`、`select`） +- `delivery-pin`，用于置顶投递请求 -核心负责决定是原生渲染该展示，还是将其降级为文本。 -不要从通用消息工具中暴露 provider 原生 UI 逃生口。 -面向旧版原生模式的已弃用 SDK 辅助工具仍会为现有第三方插件导出，但新插件不应使用它们。 +核心决定是原生渲染该呈现，还是将其降级为文本。 +不要从通用消息工具中暴露提供商原生 UI 的逃生通道。 +针对旧版原生模式的已弃用 SDK 辅助工具仍然会为现有第三方插件导出，但新插件不应使用它们。 ## 渠道目标解析 -渠道插件应拥有特定渠道的目标语义。保持共享出站主机通用，并使用消息适配器表面处理 provider 规则： +渠道插件应拥有渠道特定的目标语义。请让共享出站宿主保持通用，并使用消息适配器表面处理提供商规则： -- `messaging.inferTargetChatType({ to })` 决定一个标准化目标在目录查找前应被视为 `direct`、`group` 还是 `channel`。 -- `messaging.targetResolver.looksLikeId(raw, normalized)` 告诉核心，某个输入是否应跳过目录搜索，直接进入类似 id 的解析。 -- `messaging.targetResolver.resolveTarget(...)` 是插件的回退路径，当核心在标准化之后或目录未命中之后需要最终由 provider 拥有的解析结果时使用。 -- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后负责 provider 特定的会话路由构造。 +- `messaging.inferTargetChatType({ to })` 决定规范化后的目标在目录查找之前应被视为 `direct`、`group` 还是 `channel`。 +- `messaging.targetResolver.looksLikeId(raw, normalized)` 告诉核心某个输入是否应跳过目录搜索，直接进入类 id 解析。 +- `messaging.targetResolver.resolveTarget(...)` 是当核心在规范化之后或目录未命中之后需要最终由提供商拥有的解析时，插件侧的回退。 +- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后拥有提供商特定的会话路由构建逻辑。 推荐拆分方式： -- 对于应在搜索联系人/群组之前发生的分类决策，使用 `inferTargetChatType`。 -- 对于“将其视为显式/原生目标 id”的检查，使用 `looksLikeId`。 -- 对于 provider 特定的标准化回退，使用 `resolveTarget`，而不是用于广泛的目录搜索。 -- 将 chat id、thread id、JID、handle 和 room id 等 provider 原生 id 保留在 `target` 值或 provider 特定参数中，而不是放入通用 SDK 字段。 +- 对于应在搜索联系人/群组之前进行的类别判断，请使用 `inferTargetChatType`。 +- 对于“把它视为显式/原生目标 id”检查，请使用 `looksLikeId`。 +- 对于提供商特定的规范化回退，请使用 `resolveTarget`，而不要将其用于广泛的目录搜索。 +- 将提供商原生 id，例如 chat id、thread id、JID、handle 和 room id，保留在 `target` 值或提供商特定参数中，而不是放进通用 SDK 字段里。 -## 配置支持的目录 +## 基于配置的目录 -如果插件会从配置派生目录条目，则应将这部分逻辑保留在插件中，并复用 -`openclaw/plugin-sdk/directory-runtime` -提供的共享辅助工具。 +如果插件会从配置派生目录条目，应将该逻辑保留在插件内，并复用 +`openclaw/plugin-sdk/directory-runtime` 中的共享辅助工具。 -当某个渠道需要配置支持的联系人/群组时，请使用这种方式，例如： +当某个渠道需要基于配置的联系人/群组时，请使用这种方式，例如： -- 基于 allowlist 的私信联系人 +- 由 allowlist 驱动的私信联系人 - 已配置的渠道/群组映射 -- 按账户划分的静态目录回退 +- 按账户作用域划分的静态目录回退 `directory-runtime` 中的共享辅助工具只处理通用操作： - 查询过滤 - 限制应用 -- 去重/标准化辅助工具 +- 去重/规范化辅助工具 - 构建 `ChannelDirectoryEntry[]` -特定渠道的账户检查和 id 标准化应保留在插件实现中。 +渠道特定的账户检查和 id 规范化应保留在插件实现中。 -## Provider 目录 +## 提供商目录 -Provider 插件可以通过 +提供商插件可以通过 `registerProvider({ catalog: { run(...) { ... } } })` -定义用于推理的模型目录。 +为推理定义模型目录。 -`catalog.run(...)` 返回与 OpenClaw 写入 -`models.providers` 时相同的形状： +`catalog.run(...)` 返回的形状与 OpenClaw 写入 +`models.providers` 的形状相同： -- `{ provider }`，用于单个 provider 条目 -- `{ providers }`，用于多个 provider 条目 +- `{ provider }`：一个提供商条目 +- `{ providers }`：多个提供商条目 -当插件拥有 provider 特定的模型 id、基础 URL 默认值或受认证控制的模型元数据时，请使用 `catalog`。 +当插件拥有提供商特定的模型 id、base URL 默认值或受认证控制的模型元数据时，请使用 `catalog`。 -`catalog.order` 控制插件目录相对于 OpenClaw -内置隐式 providers 的合并时机： +`catalog.order` 控制插件目录相对于 OpenClaw 内置隐式提供商的合并时机： -- `simple`：普通 API key 或环境变量驱动的 providers -- `profile`：存在 auth 配置文件时出现的 providers -- `paired`：合成多个相关 provider 条目的 providers -- `late`：最后一轮，在其他隐式 providers 之后 +- `simple`：纯 API 密钥或环境变量驱动的提供商 +- `profile`：当存在认证配置文件时出现的提供商 +- `paired`：会合成多个相关提供商条目的提供商 +- `late`：最后一轮，在其他隐式提供商之后 -后出现的 provider 会在键冲突时胜出，因此插件可以有意用相同的 provider id 覆盖内置 provider 条目。 +后出现的提供商会在键冲突时胜出，因此插件可以有意覆写具有相同提供商 id 的内置提供商条目。 兼容性： @@ -630,33 +625,31 @@ Provider 插件可以通过 ## 只读渠道检查 -如果你的插件注册了一个渠道，最好同时实现 +如果你的插件注册了一个渠道，优先同时实现 `plugin.config.inspectAccount(cfg, accountId)` 和 `resolveAccount(...)`。 -原因如下： +原因： -- `resolveAccount(...)` 是运行时路径。它可以假定凭证已经完全实体化，并且在缺少必要 secret 时快速失败。 -- 只读命令路径，例如 `openclaw status`、`openclaw status --all`、 - `openclaw channels status`、`openclaw channels resolve` 以及 doctor/config - 修复流程，不应仅为了描述配置就必须实体化运行时凭证。 +- `resolveAccount(...)` 是运行时路径。它可以假定凭证已被完整实体化，并且在缺少必需密钥时快速失败。 +- `openclaw status`、`openclaw status --all`、`openclaw channels status`、`openclaw channels resolve` 以及 Doctor/配置修复流程等只读命令路径，不应仅为了描述配置就必须实体化运行时凭证。 推荐的 `inspectAccount(...)` 行为： -- 只返回描述性的账户状态。 +- 仅返回描述性的账户状态。 - 保留 `enabled` 和 `configured`。 - 在相关时包含凭证来源/状态字段，例如： - `tokenSource`、`tokenStatus` - `botTokenSource`、`botTokenStatus` - `appTokenSource`、`appTokenStatus` - `signingSecretSource`、`signingSecretStatus` -- 你不需要为了报告只读可用性而返回原始令牌值。对于 status 风格的命令，返回 `tokenStatus: "available"`（以及对应的来源字段）就足够了。 +- 你不需要为了报告只读可用性而返回原始令牌值。返回 `tokenStatus: "available"`（以及匹配的 source 字段）就足够用于 Status 风格命令。 - 当某个凭证通过 SecretRef 配置，但在当前命令路径中不可用时，请使用 `configured_unavailable`。 -这样，只读命令就能报告“已配置，但在该命令路径中不可用”，而不是崩溃或错误地将账户报告为未配置。 +这样一来，只读命令就能报告“已配置，但在此命令路径中不可用”，而不会崩溃或错误地将该账户报告为未配置。 -## 软件包打包 bundles +## 包打包集合 -插件目录可以包含带有 `openclaw.extensions` 的 `package.json`： +一个插件目录可以包含一个带有 `openclaw.extensions` 的 `package.json`： ```json { @@ -668,50 +661,53 @@ Provider 插件可以通过 } ``` -每个条目都会成为一个插件。如果该 pack 列出了多个扩展，插件 id +每个条目都会成为一个插件。如果该打包集合列出了多个扩展，插件 id 将变为 `name/`。 如果你的插件导入了 npm 依赖，请在该目录中安装它们，以便 `node_modules` 可用（`npm install` / `pnpm install`）。 -安全护栏：每个 `openclaw.extensions` 条目在解析符号链接之后都必须保持在插件目录内部。逃逸出软件包目录的条目会被拒绝。 +安全护栏：每个 `openclaw.extensions` 条目在解析符号链接后都必须保持在插件目录内。逃逸出包目录的条目会被拒绝。 安全说明：`openclaw plugins install` 会使用项目本地的 -`npm install --omit=dev --ignore-scripts` 安装插件依赖（无生命周期脚本、运行时无开发依赖），并忽略继承的全局 npm 安装设置。请保持插件依赖树为“纯 JS/TS”，并避免依赖需要 -`postinstall` 构建的软件包。 +`npm install --omit=dev --ignore-scripts` 安装插件依赖 +（无生命周期脚本，运行时无开发依赖），并忽略继承的全局 npm 安装设置。 +请保持插件依赖树为“纯 JS/TS”，并避免使用需要 +`postinstall` 构建的包。 -可选：`openclaw.setupEntry` 可以指向一个轻量级的仅设置模块。 -当 OpenClaw 需要为已禁用的渠道插件提供设置表面，或者 -当某个渠道插件已启用但尚未配置时，它会加载 `setupEntry`，而不是完整的插件入口。这样在你的主插件入口还会接入工具、钩子或其他仅运行时代码时，能让启动和设置过程更轻量。 +可选项：`openclaw.setupEntry` 可以指向一个轻量级的仅设置模块。 +当 OpenClaw 需要为已禁用的渠道插件提供设置表面，或者某个渠道插件已启用但仍未配置时，它会加载 `setupEntry`，而不是完整插件入口。 +当你的主插件入口还会接线工具、钩子或其他仅运行时代码时，这可以让启动和设置更加轻量。 -可选：`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -可让某个渠道插件在 Gateway 网关的监听前启动阶段也选择同样的 `setupEntry` 路径，即使该渠道已经配置完成。 +可选项：`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` +可让一个渠道插件即使在渠道已经配置完成时，也在 Gateway 网关预监听启动阶段进入同样的 `setupEntry` 路径。 -只有当 `setupEntry` 能完整覆盖 Gateway 网关开始监听之前必须存在的启动表面时，才应使用此选项。实际而言，这意味着设置入口 -必须注册启动所依赖的每一项由渠道拥有的能力，例如： +只有在 `setupEntry` 完全覆盖 Gateway 网关开始监听之前必须存在的启动表面时，才应使用此选项。 +在实践中，这意味着设置入口必须注册启动所依赖的每一项渠道自有能力，例如： - 渠道注册本身 -- 任何必须在 Gateway 网关开始监听前可用的 HTTP 路由 -- 任何在同一时间窗口内必须存在的 Gateway 网关方法、工具或服务 +- Gateway 网关开始监听之前必须可用的所有 HTTP 路由 +- 在同一窗口期间必须存在的所有 Gateway 网关方法、工具或服务 -如果你的完整入口仍拥有任何必需的启动能力，请不要启用 -此标志。保持插件采用默认行为，让 OpenClaw 在启动期间加载完整入口。 +如果你的完整入口仍然拥有任何必需的启动能力，请不要启用这个标志。 +请保持插件使用默认行为，并让 OpenClaw 在启动期间加载完整入口。 -内置渠道还可以发布仅设置阶段的契约表面辅助工具，供核心在完整渠道运行时加载前查询。当前的设置提升表面为： +内置渠道也可以发布仅设置用的契约表面辅助工具，以便核心在完整渠道运行时尚未加载之前进行查询。当前的设置提升表面包括： - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` 当核心需要在不加载完整插件入口的情况下，将旧版单账户渠道配置提升到 -`channels..accounts.*` 时，会使用该表面。 -Matrix 是当前的内置示例：当已存在命名账户时，它只会把认证/引导键移动到一个已命名的提升账户中，并且它可以保留一个已配置的非规范默认账户键，而不是总是创建 +`channels..accounts.*` 时，就会使用这组表面。 +Matrix 是当前的内置示例：当具名账户已存在时，它只会把认证/引导键移动到一个具名的提升账户中，并且它可以保留一个已配置的非规范默认账户键，而不是总是创建 `accounts.default`。 -这些设置补丁适配器让内置契约表面发现保持惰性。导入时开销保持轻量；提升表面只会在首次使用时加载，而不会在模块导入时重新进入内置渠道启动流程。 +这些设置补丁适配器让内置契约表面发现保持惰性。导入时保持轻量；只有首次使用时才会加载提升表面，而不是在模块导入时重新进入内置渠道启动流程。 -当这些启动表面包含 Gateway 网关 RPC 方法时，请将它们保留在插件特定前缀下。核心管理命名空间（`config.*`、 -`exec.approvals.*`、`wizard.*`、`update.*`）始终保留，并且总是解析为 `operator.admin`，即使某个插件请求更窄的作用域也是如此。 +当这些启动表面包含 Gateway 网关 RPC 方法时，请将它们保留在插件专用前缀下。核心管理员命名空间（`config.*`、 +`exec.approvals.*`、`wizard.*`、`update.*`）仍然保留，并且始终解析为 +`operator.admin`，即使某个插件请求了更窄的作用域也是如此。 示例： @@ -730,7 +726,7 @@ Matrix 是当前的内置示例：当已存在命名账户时，它只会把认 ### 渠道目录元数据 -渠道插件可以通过 `openclaw.channel` 通告设置/发现元数据，并通过 `openclaw.install` 提供安装提示。这样可以让核心目录保持无数据化。 +渠道插件可以通过 `openclaw.channel` 公布设置/发现元数据，并通过 `openclaw.install` 公布安装提示。这让核心目录保持无数据状态。 示例： @@ -742,10 +738,10 @@ Matrix 是当前的内置示例：当已存在命名账户时，它只会把认 "channel": { "id": "nextcloud-talk", "label": "Nextcloud Talk", - "selectionLabel": "Nextcloud Talk（自托管）", + "selectionLabel": "Nextcloud Talk（self-hosted）", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "通过 Nextcloud Talk webhook 机器人实现自托管聊天。", + "blurb": "通过 Nextcloud Talk webhook bots 提供 self-hosted 聊天。", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -758,45 +754,42 @@ Matrix 是当前的内置示例：当已存在命名账户时，它只会把认 } ``` -除了最小示例之外，其他有用的 `openclaw.channel` 字段还包括： +除最小示例外，其他有用的 `openclaw.channel` 字段包括： -- `detailLabel`：用于更丰富的目录/Status 表面的次级标签 +- `detailLabel`：用于更丰富目录/Status 表面的次级标签 - `docsLabel`：覆盖文档链接的链接文本 -- `preferOver`：此目录条目应优先于的低优先级插件/渠道 id -- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：选择表面文案控制 -- `markdownCapable`：将该渠道标记为支持 markdown，以用于出站格式决策 -- `exposure.configured`：当设为 `false` 时，在已配置渠道列表表面中隐藏该渠道 -- `exposure.setup`：当设为 `false` 时，在交互式设置/配置选择器中隐藏该渠道 -- `exposure.docs`：在文档导航表面中将该渠道标记为内部/私有 -- `showConfigured` / `showInSetup`：仍为兼容性接受的旧别名；优先使用 `exposure` +- `preferOver`：此目录条目应优先于的较低优先级插件/渠道 id +- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：选择表面的文案控制 +- `markdownCapable`：将该渠道标记为支持 Markdown，以用于出站格式决策 +- `exposure.configured`：设为 `false` 时，在已配置渠道列表表面中隐藏该渠道 +- `exposure.setup`：设为 `false` 时，在交互式设置/配置选择器中隐藏该渠道 +- `exposure.docs`：将该渠道标记为内部/私有，以用于文档导航表面 +- `showConfigured` / `showInSetup`：为兼容性仍接受的旧别名；优先使用 `exposure` - `quickstartAllowFrom`：让该渠道选择加入标准快速开始 `allowFrom` 流程 - `forceAccountBinding`：即使只存在一个账户，也要求显式账户绑定 - `preferSessionLookupForAnnounceTarget`：在解析公告目标时优先使用会话查找 -OpenClaw 还可以合并**外部渠道目录**（例如 MPM -注册表导出）。将一个 JSON 文件放到以下任一位置： +OpenClaw 还可以合并**外部渠道目录**（例如 MPM 注册表导出）。将一个 JSON 文件放到以下任一位置： - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向 -一个或多个 JSON 文件（以逗号/分号/`PATH` 分隔）。每个文件应 -包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的旧别名。 +或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（以逗号/分号/`PATH` 分隔）。每个文件应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的旧别名。 -生成的渠道目录条目和 provider 安装目录条目会在原始 `openclaw.install` 块旁边暴露标准化的安装来源事实。标准化事实会标识 npm 规格是否是精确版本或浮动选择器、是否存在预期的完整性元数据，以及本地源路径是否也可用。当目录/软件包标识已知时，标准化事实会在解析得到的 npm 软件包名偏离该标识时发出警告。它们还会在 `defaultChoice` 无效、指向不可用源，或存在 npm 完整性元数据但没有有效 npm 源时发出警告。使用方应将 `installSource` 视为附加的可选字段，这样较旧的手工构建条目和兼容性 shim 就不必合成它。这使新手引导和诊断能够解释源平面状态，而无需导入插件运行时。 +生成的渠道目录条目和提供商安装目录条目会在原始 `openclaw.install` 块旁边暴露规范化后的安装源事实。这些规范化事实会标识 npm 规范是否为精确版本或浮动选择器、是否存在预期的完整性元数据，以及本地源路径是否也可用。当目录/包身份已知时，如果解析出的 npm 包名与该身份发生漂移，这些规范化事实会发出警告。它们也会在 `defaultChoice` 无效、指向不可用源，或者存在 npm 完整性元数据但没有有效 npm 源时发出警告。使用方应将 `installSource` 视为一个增量的可选字段，这样手工构建的条目和目录 shim 就不必合成它。 +这让新手引导和诊断能够解释源平面状态，而无需导入插件运行时。 -官方外部 npm 条目应优先使用精确的 `npmSpec` 加 -`expectedIntegrity`。为兼容性起见，裸软件包名和 dist-tag 仍然可用，但它们会暴露源平面警告，以便目录可以朝着固定版本、带完整性检查的安装方式演进，而不会破坏现有插件。当新手引导从本地目录路径安装时，它会记录一个托管插件安装台账条目，其中包含 `source: "path"`，并在可能时记录相对于工作区的 `sourcePath`。绝对的实际加载路径仍保留在 `plugins.load.paths` 中；安装记录避免将本地工作站路径重复写入长期配置中。这样可让本地开发安装对源平面诊断可见，而不会增加第二个原始文件系统路径暴露表面。旧版 `plugins.installs` 配置条目仍会作为兼容性回退被读取，而状态管理的 `plugins/installs.json` 台账则成为安装来源的事实来源。 -`openclaw doctor --fix` 会将这些旧版配置条目迁移到托管台账中，并在不加载插件运行时模块的情况下刷新冷注册表索引。 +官方外部 npm 条目应优先使用精确的 `npmSpec` 加上 `expectedIntegrity`。裸包名和 dist-tag 仍可出于兼容性继续使用，但它们会暴露源平面警告，从而让目录可以在不破坏现有插件的前提下逐步迁移到固定版本、带完整性校验的安装方式。 +当新手引导从本地目录路径安装时，它会记录一条托管插件索引项，其中 `source: "path"`，并在可能时记录相对于工作区的 `sourcePath`。绝对操作加载路径仍保留在 `plugins.load.paths` 中；安装记录则避免将本地工作站路径重复写入长期配置。这样可以让本地开发安装对源平面诊断保持可见，而无需增加第二个原始文件系统路径暴露表面。持久化的 `plugins/installs.json` 插件索引是安装源的事实来源，并且可以在不加载插件运行时模块的情况下刷新。即使插件清单缺失或无效，它的 `installRecords` 映射仍然是持久的；其 `plugins` 数组则是可重建的清单/缓存视图。 ## 上下文引擎插件 -上下文引擎插件拥有用于摄取、组装和压缩的会话上下文编排。通过 -`api.registerContextEngine(id, factory)` 从你的插件中注册它们，然后使用 +上下文引擎插件负责会话上下文编排，包括摄取、组装和压缩。通过 +`api.registerContextEngine(id, factory)` 在你的插件中注册它们，然后使用 `plugins.slots.contextEngine` 选择活动引擎。 -当你的插件需要替换或扩展默认上下文管线，而不仅仅是添加 memory 搜索或钩子时，请使用此方式。 +当你的插件需要替换或扩展默认上下文流水线，而不仅仅是添加 Memory Wiki 搜索或钩子时，请使用这种方式。 ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -824,8 +817,7 @@ export default function (api) { } ``` -如果你的引擎**不**拥有压缩算法，请保持 `compact()` -已实现，并显式委托它： +如果你的引擎**不**拥有压缩算法，请保持 `compact()` 已实现，并显式委托它： ```ts import { @@ -862,42 +854,39 @@ export default function (api) { ## 添加新能力 -当插件需要当前 API 无法适配的行为时，不要通过私有直连方式绕过 -插件系统。请添加缺失的能力。 +当插件需要当前 API 无法适配的行为时，不要通过私有内部访问来绕过插件系统。应添加缺失的能力。 推荐顺序： 1. 定义核心契约 - 决定核心应拥有哪些共享行为：策略、回退、配置合并、 + 决定哪些共享行为应由核心拥有：策略、回退、配置合并、 生命周期、面向渠道的语义，以及运行时辅助工具形状。 2. 添加类型化的插件注册/运行时表面 - 使用最小且有用的类型化能力表面扩展 `OpenClawPluginApi` 和/或 `api.runtime`。 -3. 连接核心 + 渠道/功能使用方 - 渠道和功能插件应通过核心消费该新能力， - 而不是直接导入某个厂商实现。 -4. 注册厂商实现 - 然后由厂商插件针对该能力注册其后端实现。 + 使用最小但有用的类型化能力表面来扩展 `OpenClawPluginApi` 和/或 `api.runtime`。 +3. 接入核心 + 渠道/功能使用方 + 渠道和功能插件应通过核心使用这个新能力， + 而不是直接导入某个供应商实现。 +4. 注册供应商实现 + 然后由供应商插件针对该能力注册其后端实现。 5. 添加契约覆盖 - 添加测试，以便所有权和注册形状能随时间保持明确。 + 添加测试，使所有权和注册形状在时间推移中保持明确。 -这就是 OpenClaw 保持有主张、同时不被硬编码到某一个 -provider 世界观中的方式。有关具体文件检查清单和完整示例，请参阅 [能力扩展手册](/zh-CN/plugins/architecture)。 +这就是 OpenClaw 如何在保持明确主张的同时，又不会被硬编码到某一家提供商的世界观中。关于具体的文件检查清单和完整示例，请参见 [能力扩展手册](/zh-CN/plugins/architecture)。 ### 能力检查清单 -当你添加新能力时，实现通常应同时涉及以下表面： +当你添加一个新能力时，实现通常应同时涉及以下表面： - `src//types.ts` 中的核心契约类型 - `src//runtime.ts` 中的核心运行器/运行时辅助工具 - `src/plugins/types.ts` 中的插件 API 注册表面 - `src/plugins/registry.ts` 中的插件注册表接线 -- `src/plugins/runtime/*` 中的插件运行时暴露，当功能/渠道 - 插件需要消费它时 +- 当功能/渠道插件需要消费它时，`src/plugins/runtime/*` 中的插件运行时暴露 - `src/test-utils/plugin-registration.ts` 中的捕获/测试辅助工具 - `src/plugins/contracts/registry.ts` 中的所有权/契约断言 -- `docs/` 中面向操作员/插件的文档 +- `docs/` 中的运维人员/插件文档 -如果这些表面中缺少某一个，通常说明该能力尚未完全集成。 +如果其中某个表面缺失，通常意味着该能力尚未完全集成。 ### 能力模板 @@ -933,16 +922,16 @@ const clip = await api.runtime.videoGeneration.generate({ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -这样规则就很简单： +这样可以让规则保持简单： - 核心拥有能力契约 + 编排 -- 厂商插件拥有厂商实现 +- 供应商插件拥有供应商实现 - 功能/渠道插件消费运行时辅助工具 - 契约测试让所有权保持明确 ## 相关内容 -- [插件架构](/zh-CN/plugins/architecture) — 公开能力模型和形状 +- [插件架构](/zh-CN/plugins/architecture) —— 公开能力模型和形状 - [插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths) - [插件 SDK 设置](/zh-CN/plugins/sdk-setup) - [构建插件](/zh-CN/plugins/building-plugins) diff --git a/docs/zh-CN/plugins/community.md b/docs/zh-CN/plugins/community.md index c904a17de..27872937e 100644 --- a/docs/zh-CN/plugins/community.md +++ b/docs/zh-CN/plugins/community.md @@ -5,33 +5,37 @@ read_when: summary: 社区维护的 OpenClaw 插件：浏览、安装并提交你自己的插件 title: 社区插件 x-i18n: - generated_at: "2026-04-23T20:56:57Z" + generated_at: "2026-04-26T00:16:04Z" model: gpt-5.4 provider: openai - source_hash: acce221249df8ceea65436902a33f4906503a1c6f57db3b0ad2058d64c1fb0f7 + source_hash: 3af2f0be5e5e75fe26a58576e6f44bce52a1ff8d597f86cafd8fb893f6c6b8f4 source_path: plugins/community.md workflow: 15 --- -社区插件是第三方软件包，用于为 OpenClaw 扩展新的 -渠道、工具、提供商或其他能力。它们由社区构建和维护，发布在 [ClawHub](/zh-CN/tools/clawhub) 或 npm 上，并且可以通过一条命令安装。 +社区插件是用于扩展 OpenClaw 的第三方软件包，可添加新的 +渠道、工具、提供商或其他能力。它们由社区构建和维护，发布到 [ClawHub](/zh-CN/tools/clawhub) 或 npm，并且 +可通过一条命令安装。 -ClawHub 是社区插件的规范发现界面。不要仅仅为了让插件更容易被发现而提交只改文档的 PR；请将它发布到 ClawHub。 +ClawHub 是社区插件的权威发现入口。不要仅仅为了让你的插件能在这里被发现而提交只改文档的 PR；请改为将它发布到 +ClawHub。 ```bash openclaw plugins install ``` -OpenClaw 会先检查 ClawHub，然后自动回退到 npm。 +OpenClaw 会先检查 ClawHub，并自动回退到 npm。 ## 已列出的插件 ### Apify -使用 20,000+ 个现成爬虫从任意网站抓取数据。让你的智能体只通过提问，就能从 Instagram、Facebook、TikTok、YouTube、Google Maps、Google 搜索、电商网站等提取数据。 +使用 20,000 多个现成爬虫从任意网站抓取数据。只需提出请求，你的智能体 +就能从 Instagram、Facebook、TikTok、YouTube、Google Maps、Google +Search、电商网站等提取数据。 -- **npm：** `@apify/apify-openclaw-plugin` -- **repo：** [github.com/apify/apify-openclaw-plugin](https://github.com/apify/apify-openclaw-plugin) +- **npm:** `@apify/apify-openclaw-plugin` +- **repo:** [github.com/apify/apify-openclaw-plugin](https://github.com/apify/apify-openclaw-plugin) ```bash openclaw plugins install @apify/apify-openclaw-plugin @@ -39,11 +43,11 @@ openclaw plugins install @apify/apify-openclaw-plugin ### Codex App Server Bridge -用于 Codex App Server 对话的独立 OpenClaw bridge。可将聊天绑定到 -Codex 线程，通过纯文本与其交谈，并使用聊天原生命令控制恢复、规划、审查、模型选择、压缩等。 +面向 Codex App Server 对话的独立 OpenClaw 桥接插件。将聊天绑定到 +Codex 线程，使用纯文本与其交流，并通过聊天原生命令控制恢复、规划、审查、模型选择、压缩等功能。 -- **npm：** `openclaw-codex-app-server` -- **repo：** [github.com/pwrdrvr/openclaw-codex-app-server](https://github.com/pwrdrvr/openclaw-codex-app-server) +- **npm:** `openclaw-codex-app-server` +- **repo:** [github.com/pwrdrvr/openclaw-codex-app-server](https://github.com/pwrdrvr/openclaw-codex-app-server) ```bash openclaw plugins install openclaw-codex-app-server @@ -54,8 +58,8 @@ openclaw plugins install openclaw-codex-app-server 使用 Stream 模式的企业机器人集成。支持通过任意 DingTalk 客户端发送文本、图片和 文件消息。 -- **npm：** `@largezhou/ddingtalk` -- **repo：** [github.com/largezhou/openclaw-dingtalk](https://github.com/largezhou/openclaw-dingtalk) +- **npm:** `@largezhou/ddingtalk` +- **repo:** [github.com/largezhou/openclaw-dingtalk](https://github.com/largezhou/openclaw-dingtalk) ```bash openclaw plugins install @largezhou/ddingtalk @@ -63,11 +67,11 @@ openclaw plugins install @largezhou/ddingtalk ### Lossless Claw (LCM) -适用于 OpenClaw 的无损上下文管理插件。基于 DAG 的对话 -摘要，带增量压缩 —— 在降低 token 使用量的同时保留完整上下文保真度。 +面向 OpenClaw 的无损上下文管理插件。基于 DAG 的会话摘要 +和增量压缩——在减少 token 使用量的同时保留完整上下文保真度。 -- **npm：** `@martian-engineering/lossless-claw` -- **repo：** [github.com/Martian-Engineering/lossless-claw](https://github.com/Martian-Engineering/lossless-claw) +- **npm:** `@martian-engineering/lossless-claw` +- **repo:** [github.com/Martian-Engineering/lossless-claw](https://github.com/Martian-Engineering/lossless-claw) ```bash openclaw plugins install @martian-engineering/lossless-claw @@ -75,11 +79,11 @@ openclaw plugins install @martian-engineering/lossless-claw ### Opik -官方插件，可将智能体追踪导出到 Opik。可监控智能体行为、 +将智能体追踪导出到 Opik 的官方插件。可监控智能体行为、 成本、token、错误等。 -- **npm：** `@opik/opik-openclaw` -- **repo：** [github.com/comet-ml/opik-openclaw](https://github.com/comet-ml/opik-openclaw) +- **npm:** `@opik/opik-openclaw` +- **repo:** [github.com/comet-ml/opik-openclaw](https://github.com/comet-ml/opik-openclaw) ```bash openclaw plugins install @opik/opik-openclaw @@ -87,12 +91,12 @@ openclaw plugins install @opik/opik-openclaw ### Prometheus Avatar -为你的 OpenClaw 智能体提供一个带实时口型同步、情绪 -表情和文本转语音的 Live2D 头像。包含用于 AI 资产生成的创作者工具 -以及一键部署到 Prometheus Marketplace。目前处于 alpha 阶段。 +为你的 OpenClaw 智能体提供一个具有实时口型同步、情绪 +表情和文本转语音功能的 Live2D 虚拟形象。包含用于 AI 资产生成的创作者工具， +以及一键部署到 Prometheus Marketplace 的能力。目前处于 alpha 阶段。 -- **npm：** `@prometheusavatar/openclaw-plugin` -- **repo：** [github.com/myths-labs/prometheus-avatar](https://github.com/myths-labs/prometheus-avatar) +- **npm:** `@prometheusavatar/openclaw-plugin` +- **repo:** [github.com/myths-labs/prometheus-avatar](https://github.com/myths-labs/prometheus-avatar) ```bash openclaw plugins install @prometheusavatar/openclaw-plugin @@ -101,11 +105,15 @@ openclaw plugins install @prometheusavatar/openclaw-plugin ### QQbot 通过 QQ Bot API 将 OpenClaw 连接到 QQ。支持私聊、群组 -提及、频道消息，以及语音、图片、视频、 -文件等富媒体。 +提及、渠道消息，以及包括语音、图片、视频 +和文件在内的富媒体。 -- **npm：** `@tencent-connect/openclaw-qqbot` -- **repo：** [github.com/tencent-connect/openclaw-qqbot](https://github.com/tencent-connect/openclaw-qqbot) +当前的 OpenClaw 版本已内置 QQ Bot。正常安装请使用 +[QQ Bot](/zh-CN/channels/qqbot) 中的内置设置；仅当你明确希望使用腾讯维护的独立软件包时， +才安装这个外部插件。 + +- **npm:** `@tencent-connect/openclaw-qqbot` +- **repo:** [github.com/tencent-connect/openclaw-qqbot](https://github.com/tencent-connect/openclaw-qqbot) ```bash openclaw plugins install @tencent-connect/openclaw-qqbot @@ -113,13 +121,13 @@ openclaw plugins install @tencent-connect/openclaw-qqbot ### wecom -由腾讯 WeCom 团队提供的 OpenClaw WeCom 渠道插件。基于 -WeCom Bot WebSocket 长连接，支持私信与群聊、 -流式回复、主动消息、图片/文件处理、Markdown -格式化、内置访问控制，以及文档/会议/消息 Skills。 +由腾讯 WeCom 团队开发的 OpenClaw WeCom 渠道插件。基于 +WeCom Bot WebSocket 持久连接， +支持私信和群聊、流式回复、主动消息发送、图片/文件处理、Markdown +格式化、内置访问控制，以及文档/会议/消息技能。 -- **npm：** `@wecom/wecom-openclaw-plugin` -- **repo：** [github.com/WecomTeam/wecom-openclaw-plugin](https://github.com/WecomTeam/wecom-openclaw-plugin) +- **npm:** `@wecom/wecom-openclaw-plugin` +- **repo:** [github.com/WecomTeam/wecom-openclaw-plugin](https://github.com/WecomTeam/wecom-openclaw-plugin) ```bash openclaw plugins install @wecom/wecom-openclaw-plugin @@ -127,46 +135,46 @@ openclaw plugins install @wecom/wecom-openclaw-plugin ## 提交你的插件 -我们欢迎那些实用、有文档且可安全运行的社区插件。 +我们欢迎实用、有文档并且可安全运行的社区插件。 - 你的插件必须能够通过 `openclaw plugins install \` 安装。 - 请发布到 [ClawHub](/zh-CN/tools/clawhub)（推荐）或 npm。 - 完整指南请参见 [Building Plugins](/zh-CN/plugins/building-plugins)。 + 你的插件必须可通过 `openclaw plugins install \` 安装。 + 发布到 [ClawHub](/zh-CN/tools/clawhub)（推荐）或 npm。 + 完整指南请参见[构建插件](/zh-CN/plugins/building-plugins)。 - 源代码必须位于公开仓库中，并带有设置文档和 issue - 跟踪器。 + 源代码必须位于带有设置文档和 issue + 跟踪器的公开仓库中。 - - 你不需要仅为了让插件更易发现而提交文档 PR。请改为将它发布到 + + 你不需要仅为了让你的插件可被发现而提交文档 PR。请改为将它发布到 ClawHub。 只有当 OpenClaw 的源文档确实需要内容 - 变更时，才提交文档 PR，例如修正安装指南，或添加属于主文档集的跨仓库 - 文档。 + 更改时，才提交文档 PR，例如更正安装指引，或添加属于主文档集的 + 跨仓库文档。 -## 质量标准 +## 质量门槛 | 要求 | 原因 | | --------------------------- | --------------------------------------------- | -| 发布在 ClawHub 或 npm 上 | 用户需要 `openclaw plugins install` 能正常工作 | -| 公开 GitHub 仓库 | 便于源码审查、issue 跟踪和透明性 | -| 设置与使用文档 | 用户需要知道如何配置 | -| 活跃维护 | 最近有更新，或能及时处理 issue | +| 发布到 ClawHub 或 npm | 用户需要 `openclaw plugins install` 能正常工作 | +| 公开的 GitHub 仓库 | 便于审查源码、跟踪 issue，并保证透明度 | +| 设置和使用文档 | 用户需要知道如何配置它 | +| 持续维护 | 有近期更新或能及时响应 issue 处理 | -低投入包装器、归属不明确或无人维护的软件包可能会被拒绝。 +低质量封装、归属不明确或无人维护的软件包可能会被拒绝。 ## 相关内容 -- [Install and Configure Plugins](/zh-CN/tools/plugin) — 如何安装任意插件 -- [Building Plugins](/zh-CN/plugins/building-plugins) — 创建你自己的插件 -- [Plugin Manifest](/zh-CN/plugins/manifest) — manifest schema +- [安装和配置插件](/zh-CN/tools/plugin) — 如何安装任意插件 +- [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件 +- [插件清单](/zh-CN/plugins/manifest) — 清单 schema diff --git a/docs/zh-CN/plugins/manifest.md b/docs/zh-CN/plugins/manifest.md index c0f44fc5e..5dc1d1bde 100644 --- a/docs/zh-CN/plugins/manifest.md +++ b/docs/zh-CN/plugins/manifest.md @@ -1,14 +1,14 @@ --- read_when: - 你正在构建一个 OpenClaw 插件 - - 你需要发布一个插件配置 schema，或调试插件验证错误 -summary: 插件清单 + JSON schema 要求（严格配置验证） + - 你需要发布一个插件配置 schema，或调试插件校验错误 +summary: 插件清单 + JSON schema 要求（严格配置校验） title: 插件清单 x-i18n: - generated_at: "2026-04-25T01:59:28Z" + generated_at: "2026-04-26T00:16:07Z" model: gpt-5.4 provider: openai - source_hash: fa96930c3c9b890194869eb793c65a0af9db43f8f8b1f78d3c3d6ef18b70be6e + source_hash: 47e3d74576a33c98ea58d29e74d3589eed3c69750e53f1acfe164dcc92b0e592 source_path: plugins/manifest.md workflow: 15 --- @@ -23,31 +23,31 @@ x-i18n: - Claude bundle：`.claude-plugin/plugin.json`，或不带清单的默认 Claude 组件布局 - Cursor bundle：`.cursor-plugin/plugin.json` -OpenClaw 也会自动检测这些 bundle 布局，但不会根据此处描述的 `openclaw.plugin.json` schema 对它们进行验证。 +OpenClaw 也会自动检测这些 bundle 布局，但不会根据此处描述的 `openclaw.plugin.json` schema 对它们进行校验。 -对于兼容 bundle，OpenClaw 当前会在布局符合 OpenClaw 运行时预期时，读取 bundle 元数据、声明的 skill 根目录、Claude 命令根目录、Claude bundle `settings.json` 默认值、Claude bundle LSP 默认值，以及受支持的 hook pack。 +对于兼容 bundle，当布局符合 OpenClaw 运行时预期时，OpenClaw 当前会读取 bundle 元数据、声明的 skill 根目录、Claude 命令根目录、Claude bundle 的 `settings.json` 默认值、Claude bundle 的 LSP 默认值，以及受支持的 hook pack。 -每个原生 OpenClaw 插件**都必须**在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单在**不执行插件代码**的情况下验证配置。缺失或无效的清单会被视为插件错误，并阻止配置验证。 +每个原生 OpenClaw 插件**必须**在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单在**不执行插件代码的情况下**校验配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。 请参阅完整的插件系统指南：[插件](/zh-CN/tools/plugin)。 -关于原生能力模型和当前的外部兼容性指引，请参阅： +关于原生能力模型和当前外部兼容性指引，请参阅： [能力模型](/zh-CN/plugins/architecture#public-capability-model)。 ## 此文件的作用 -`openclaw.plugin.json` 是 OpenClaw 在**加载你的插件代码之前**读取的元数据。下面的所有内容都必须足够轻量，能够在不启动插件运行时的情况下进行检查。 +`openclaw.plugin.json` 是 OpenClaw 在**加载你的插件代码之前**读取的元数据。下方所有内容都必须足够轻量，以便在不启动插件运行时的情况下进行检查。 -**用于：** +**将它用于：** -- 插件标识、配置验证和配置 UI 提示 -- 认证、新手引导和设置元数据（别名、自动启用、provider 环境变量、认证选项） +- 插件标识、配置校验，以及配置 UI 提示 +- 凭证、onboarding 和设置元数据（别名、自动启用、提供商环境变量、凭证选项） - 控制平面界面的激活提示 - 简写的模型系列归属 - 静态能力归属快照（`contracts`） - 共享 `openclaw qa` 主机可检查的 QA 运行器元数据 -- 合并到目录和验证界面中的渠道专用配置元数据 +- 合并到目录和校验界面中的渠道专用配置元数据 -**不要用于：** 注册运行时行为、声明代码入口点或 npm 安装元数据。这些内容应放在你的插件代码和 `package.json` 中。 +**不要将它用于：** 注册运行时行为、声明代码入口点，或 npm 安装元数据。这些应放在你的插件代码和 `package.json` 中。 ## 最小示例 @@ -129,66 +129,66 @@ OpenClaw 也会自动检测这些 bundle 布局，但不会根据此处描述的 | 字段 | 必填 | 类型 | 含义 | | ------------------------------------ | -------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | 是 | `string` | 规范的插件 id。这是在 `plugins.entries.` 中使用的 id。 | -| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 | -| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略此字段，或将其设置为任何非 `true` 的值，则该插件默认保持禁用。 | -| `legacyPluginIds` | 否 | `string[]` | 会规范化为此规范插件 id 的旧版 id。 | -| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提到这些 provider id 时，应自动启用此插件。 | -| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明一个供 `plugins.slots.*` 使用的排他性插件类型。 | -| `channels` | 否 | `string[]` | 由此插件拥有的渠道 id。用于设备发现和配置验证。 | -| `providers` | 否 | `string[]` | 由此插件拥有的 provider id。 | -| `providerDiscoveryEntry` | 否 | `string` | 轻量级 provider 设备发现模块路径，相对于插件根目录，用于可在不激活完整插件运行时的情况下加载的、受清单作用域约束的 provider 目录元数据。 | -| `modelSupport` | 否 | `object` | 由清单拥有的简写模型系列元数据，用于在运行时之前自动加载插件。 | -| `modelCatalog` | 否 | `object` | 适用于由此插件拥有的 provider 的声明式模型目录元数据。这是未来只读列表、新手引导、模型选择器、别名和抑制功能的控制平面契约，无需加载插件运行时。 | -| `providerEndpoints` | 否 | `object[]` | 由清单拥有的 endpoint host/baseUrl 元数据，适用于核心必须在 provider 运行时加载前分类的 provider 路由。 | -| `cliBackends` | 否 | `string[]` | 由此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 | -| `syntheticAuthRefs` | 否 | `string[]` | provider 或 CLI 后端引用，其插件拥有的合成认证钩子应在运行时加载前的冷启动模型发现期间进行探测。 | -| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件拥有的占位 API key 值，表示非机密的本地、OAuth 或环境凭证状态。 | -| `commandAliases` | 否 | `object[]` | 由此插件拥有的命令名称，应在运行时加载前生成具备插件感知能力的配置和 CLI 诊断信息。 | -| `providerAuthEnvVars` | 否 | `Record` | 用于 provider 认证/状态查找的已弃用兼容性环境变量元数据。对于新插件，优先使用 `setup.providers[].envVars`；在弃用窗口期内，OpenClaw 仍会读取此字段。 | -| `providerAuthAliases` | 否 | `Record` | 应复用另一个 provider id 进行认证查找的 provider id，例如共享基础 provider API key 和认证配置文件的编码 provider。 | -| `channelEnvVars` | 否 | `Record` | OpenClaw 可在不加载插件代码的情况下检查的轻量级渠道环境变量元数据。将其用于通用启动/配置辅助工具需要识别的、由环境变量驱动的渠道设置或认证界面。 | -| `providerAuthChoices` | 否 | `object[]` | 适用于新手引导选择器、首选 provider 解析和简单 CLI 标志接线的轻量级认证选项元数据。 | -| `activation` | 否 | `object` | 适用于 provider、命令、渠道、路由和能力触发加载的轻量级激活规划元数据。仅为元数据；实际行为仍由插件运行时负责。 | -| `setup` | 否 | `object` | 轻量级设置/新手引导描述符，供发现和设置界面在不加载插件运行时的情况下检查。 | -| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` 主机在插件运行时加载前使用的轻量级 QA 运行器描述符。 | -| `contracts` | 否 | `object` | 外部认证钩子、语音、实时转写、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页抓取、Ollama Web 搜索 和工具归属的静态内置能力快照。 | -| `mediaUnderstandingProviderMetadata` | 否 | `Record` | 为 `contracts.mediaUnderstandingProviders` 中声明的 provider id 提供的轻量级媒体理解默认值。 | -| `channelConfigs` | 否 | `Record` | 在运行时加载前合并到设备发现和验证界面中的、由清单拥有的渠道配置元数据。 | -| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 | -| `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` | 由声明式方式定义的、适用于此插件所拥有提供商的模型目录元数据。这是未来只读列表、onboarding、模型选择器、别名和抑制功能的控制平面契约，并且无需加载插件运行时。 | +| `providerEndpoints` | 否 | `object[]` | 由清单拥有的端点 host/baseUrl 元数据，用于核心在提供商运行时加载之前必须分类的提供商路由。 | +| `cliBackends` | 否 | `string[]` | 此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 | +| `syntheticAuthRefs` | 否 | `string[]` | 在运行时加载之前，于冷启动模型发现期间应探测其插件自有 synthetic auth hook 的提供商或 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[]` | 适用于 onboarding 选择器、首选提供商解析和简单 CLI 标志接线的轻量级凭证选项元数据。 | +| `activation` | 否 | `object` | 适用于提供商、命令、渠道、路由和由能力触发加载的轻量级激活规划器元数据。仅为元数据；实际行为仍由插件运行时负责。 | +| `setup` | 否 | `object` | 设备发现和设置界面可在不加载插件运行时的情况下检查的轻量级设置 / onboarding 描述符。 | +| `qaRunners` | 否 | `object[]` | 由共享 `openclaw qa` 主机在插件运行时加载之前使用的轻量级 QA 运行器描述符。 | +| `contracts` | 否 | `object` | 外部凭证 hook、语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、web-fetch、Web 搜索和工具归属的静态内置能力快照。 | +| `mediaUnderstandingProviderMetadata` | 否 | `Record` | 为 `contracts.mediaUnderstandingProviders` 中声明的提供商 id 提供的轻量级媒体理解默认值。 | +| `channelConfigs` | 否 | `Record` | 由清单拥有的渠道配置元数据，在运行时加载之前合并到设备发现和校验界面中。 | +| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 | +| `name` | 否 | `string` | 人类可读的插件名称。 | +| `description` | 否 | `string` | 显示在插件界面中的简短摘要。 | +| `version` | 否 | `string` | 信息性插件版本。 | +| `uiHints` | 否 | `Record` | 配置字段的 UI 标签、占位符和敏感性提示。 | ## `providerAuthChoices` 参考 -每个 `providerAuthChoices` 条目描述一个新手引导或认证选项。 -OpenClaw 会在 provider 运行时加载前读取这些内容。 -provider 设置流程会优先使用这些清单选项，然后为了兼容性回退到运行时向导元数据和安装目录选项。 +每个 `providerAuthChoices` 条目描述一个 onboarding 或凭证选项。 +OpenClaw 会在提供商运行时加载之前读取这些内容。 +提供商设置流程会优先使用这些清单选项，然后为了兼容性回退到运行时向导元数据和安装目录选项。 | 字段 | 必填 | 类型 | 含义 | | --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `provider` | 是 | `string` | 此选项所属的 provider 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` | 供 onboarding 和 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">` | 此选项应出现于哪些 onboarding 界面中。如省略，默认值为 `["text-inference"]`。 | ## `commandAliases` 参考 -当插件拥有某个运行时命令名称，而用户可能会误将其放入 `plugins.allow`，或尝试将其作为根 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用这些元数据来生成诊断信息，而无需导入插件运行时代码。 +当某个插件拥有一个运行时命令名称，而用户可能误将其放入 `plugins.allow`，或尝试将其作为根级 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用此元数据在不导入插件运行时代码的情况下提供诊断信息。 ```json { @@ -204,19 +204,19 @@ provider 设置流程会优先使用这些清单选项，然后为了兼容性 | 字段 | 必填 | 类型 | 含义 | | ------------ | -------- | ----------------- | ----------------------------------------------------------------------- | -| `name` | 是 | `string` | 属于此插件的命令名称。 | -| `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天斜杠命令，而不是根 CLI 命令。 | -| `cliCommand` | 否 | `string` | 若存在，用于建议 CLI 操作的相关根 CLI 命令。 | +| `name` | 是 | `string` | 属于此插件的命令名称。 | +| `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天斜杠命令，而不是根级 CLI 命令。 | +| `cliCommand` | 否 | `string` | 相关的根级 CLI 命令；如果存在，可在 CLI 操作中作为建议使用。 | ## `activation` 参考 -当插件可以以低成本声明哪些控制平面事件应将其纳入激活/加载计划时，请使用 `activation`。 +当插件能够以低成本声明哪些控制平面事件应将其纳入激活 / 加载计划时，请使用 `activation`。 -此块是规划器元数据，而不是生命周期 API。它不会注册运行时行为，不会替代 `register(...)`，也不保证插件代码已经执行。激活规划器会使用这些字段来缩小候选插件范围，然后再回退到现有的清单归属元数据，例如 `providers`、`channels`、`commandAliases`、`setup.providers`、`contracts.tools` 和 hooks。 +此区块是规划器元数据，而不是生命周期 API。它不会注册运行时行为，不会替代 `register(...)`，也不保证插件代码已经执行。激活规划器使用这些字段在回退到现有清单归属元数据（如 `providers`、`channels`、`commandAliases`、`setup.providers`、`contracts.tools` 和 hooks）之前缩小候选插件范围。 -优先使用已经描述归属关系的最窄元数据。如果这些字段已经表达了关系，请使用 `providers`、`channels`、`commandAliases`、设置描述符或 `contracts`。只有在这些归属字段无法表示额外规划提示时，才使用 `activation`。 +优先使用已能描述归属关系的最窄元数据。当这些字段能够表达该关系时，请使用 `providers`、`channels`、`commandAliases`、设置描述符或 `contracts`。当这些归属字段无法表示额外的规划器提示时，再使用 `activation`。 -此块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时/插件入口点。当前使用方会在更广泛的插件加载之前将其作为缩小范围的提示，因此缺少激活元数据通常只会带来性能成本；在旧版清单归属回退仍然存在时，它不应改变正确性。 +此区块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时 / 插件入口点。当前的使用方会在进行更广泛的插件加载之前，将其作为缩小范围的提示，因此缺少激活元数据通常只会带来性能成本；在旧版清单归属回退机制仍然存在时，它不应改变正确性。 ```json { @@ -232,28 +232,27 @@ provider 设置流程会优先使用这些清单选项，然后为了兼容性 | 字段 | 必填 | 类型 | 含义 | | ---------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `onProviders` | 否 | `string[]` | 应将此插件纳入激活/加载计划的 provider id。 | -| `onCommands` | 否 | `string[]` | 应将此插件纳入激活/加载计划的命令 id。 | -| `onChannels` | 否 | `string[]` | 应将此插件纳入激活/加载计划的渠道 id。 | -| `onRoutes` | 否 | `string[]` | 应将此插件纳入激活/加载计划的路由类型。 | -| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 由控制平面激活规划使用的宽泛能力提示。尽可能优先使用更窄的字段。 | +| `onProviders` | 否 | `string[]` | 应将此插件纳入激活 / 加载计划的提供商 id。 | +| `onCommands` | 否 | `string[]` | 应将此插件纳入激活 / 加载计划的命令 id。 | +| `onChannels` | 否 | `string[]` | 应将此插件纳入激活 / 加载计划的渠道 id。 | +| `onRoutes` | 否 | `string[]` | 应将此插件纳入激活 / 加载计划的路由类型。 | +| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的宽泛能力提示。尽可能优先使用更窄的字段。 | -当前的在线使用方： +当前在线使用方： -- 由命令触发的 CLI 规划会回退到旧版 +- 由命令触发的 CLI 规划会回退到旧版的 `commandAliases[].cliCommand` 或 `commandAliases[].name` -- 由渠道触发的设置/渠道规划会在缺少显式渠道激活元数据时， - 回退到旧版 `channels[]` - 归属 -- 由 provider 触发的设置/运行时规划会在缺少显式 provider - 激活元数据时，回退到旧版 +- 由渠道触发的设置 / 渠道规划在缺少显式渠道激活元数据时， + 会回退到旧版 `channels[]` 归属 +- 由提供商触发的设置 / 运行时规划在缺少显式提供商 + 激活元数据时，会回退到旧版 `providers[]` 和顶层 `cliBackends[]` 归属 -规划器诊断信息可以区分显式激活提示与清单归属回退。例如，`activation-command-hint` 表示匹配了 `activation.onCommands`，而 `manifest-command-alias` 表示规划器改用了 `commandAliases` 归属。这些原因标签用于主机诊断和测试；插件作者应继续声明最能描述归属关系的元数据。 +规划器诊断可以区分显式激活提示与清单归属回退。例如，`activation-command-hint` 表示匹配了 `activation.onCommands`，而 `manifest-command-alias` 表示规划器改用了 `commandAliases` 归属。这些原因标签用于宿主诊断和测试；插件作者应继续声明最能描述归属关系的元数据。 ## `qaRunners` 参考 -当插件在共享的 `openclaw qa` 根命令下提供一个或多个传输运行器时，请使用 `qaRunners`。保持这些元数据轻量且静态；实际的 CLI 注册仍由插件运行时通过导出 `qaRunnerCliRegistrations` 的轻量级 `runtime-api.ts` 界面负责。 +当插件在共享 `openclaw qa` 根命令下提供一个或多个传输运行器时，请使用 `qaRunners`。请保持这些元数据轻量且静态；实际的 CLI 注册仍由插件运行时通过导出 `qaRunnerCliRegistrations` 的轻量级 `runtime-api.ts` 界面负责。 ```json { @@ -268,12 +267,12 @@ provider 设置流程会优先使用这些清单选项，然后为了兼容性 | 字段 | 必填 | 类型 | 含义 | | ------------- | -------- | -------- | ------------------------------------------------------------------ | -| `commandName` | 是 | `string` | 挂载在 `openclaw qa` 下的子命令，例如 `matrix`。 | -| `description` | 否 | `string` | 当共享主机需要一个存根命令时使用的回退帮助文本。 | +| `commandName` | 是 | `string` | 挂载在 `openclaw qa` 下的子命令，例如 `matrix`。 | +| `description` | 否 | `string` | 当共享宿主需要一个占位命令时使用的回退帮助文本。 | ## `setup` 参考 -当设置和新手引导界面在运行时加载前需要插件拥有的轻量级元数据时，请使用 `setup`。 +当设置和 onboarding 界面需要在运行时加载之前获取轻量级、由插件拥有的元数据时，请使用 `setup`。 ```json { @@ -292,40 +291,40 @@ provider 设置流程会优先使用这些清单选项，然后为了兼容性 } ``` -顶层 `cliBackends` 仍然有效，并继续用于描述 CLI 推理后端。`setup.cliBackends` 是面向控制平面/设置流程、应保持仅元数据形式的设置专用描述符界面。 +顶层 `cliBackends` 仍然有效，并继续描述 CLI 推理后端。`setup.cliBackends` 是供控制平面 / 设置流程使用的、应保持为纯元数据的设置专用描述符界面。 -存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现首选的描述符优先查找界面。如果描述符只是缩小候选插件范围，而设置仍需要更丰富的设置时运行时钩子，请设置 `requiresRuntime: true`，并保留 `setup-api` 作为回退执行路径。 +存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现的首选“描述符优先”查找界面。如果描述符仅用于缩小候选插件范围，而设置仍需要更丰富的设置时运行时 hooks，请设置 `requiresRuntime: true`，并保留 `setup-api` 作为回退执行路径。 -OpenClaw 还会将 `setup.providers[].envVars` 纳入通用 provider 认证和环境变量查找中。`providerAuthEnvVars` 在弃用窗口期内仍通过兼容适配器受支持，但仍使用它的非内置插件会收到清单诊断信息。新插件应将设置/状态环境变量元数据放在 `setup.providers[].envVars` 上。 +OpenClaw 还会将 `setup.providers[].envVars` 纳入通用的提供商凭证和环境变量查找。`providerAuthEnvVars` 在弃用窗口期内仍通过兼容适配器受支持，但仍在使用它的非内置插件会收到一条清单诊断。新插件应将设置 / Status 环境变量元数据放在 `setup.providers[].envVars` 上。 -当没有可用的 setup entry 时，或者当 `setup.requiresRuntime: false` 声明设置运行时非必需时，OpenClaw 也可以从 `setup.providers[].authMethods` 派生简单的设置选项。显式的 `providerAuthChoices` 条目仍然是自定义标签、CLI 标志、新手引导范围和助手元数据的首选方式。 +当没有可用的 setup 条目，或 `setup.requiresRuntime: false` 声明设置运行时不是必需时，OpenClaw 还可以从 `setup.providers[].authMethods` 派生简单的设置选项。对于自定义标签、CLI 标志、onboarding 范围和助手元数据，显式的 `providerAuthChoices` 条目仍然是首选。 -只有当这些描述符足以支持设置界面时，才将 `requiresRuntime: false` 设为 `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` 注册了清单描述符未声明的 provider 或 CLI 后端，或者某个描述符没有对应的运行时注册，设置注册表诊断信息会报告描述符漂移。这些诊断信息是附加性的，不会拒绝旧版插件。 +当设置运行时确实执行时，如果 `setup-api` 注册了清单描述符未声明的提供商或 CLI 后端，或者某个描述符没有匹配的运行时注册，设置注册表诊断会报告描述符漂移。这些诊断是附加性的，不会拒绝旧版插件。 ### `setup.providers` 参考 | 字段 | 必填 | 类型 | 含义 | | ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ | -| `id` | 是 | `string` | 在设置或新手引导期间暴露的 provider id。保持规范化 id 在全局范围内唯一。 | -| `authMethods` | 否 | `string[]` | 此 provider 在无需加载完整运行时的情况下支持的设置/认证方法 id。 | -| `envVars` | 否 | `string[]` | 通用设置/状态界面可在插件运行时加载前检查的环境变量。 | +| `id` | 是 | `string` | 在设置或 onboarding 期间暴露的提供商 id。请保持规范化 id 在全局范围内唯一。 | +| `authMethods` | 否 | `string[]` | 此提供商在无需加载完整运行时的情况下支持的设置 / 凭证方法 id。 | +| `envVars` | 否 | `string[]` | 通用设置 / Status 界面可在插件运行时加载前检查的环境变量。 | ### `setup` 字段 | 字段 | 必填 | 类型 | 含义 | | ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- | -| `providers` | 否 | `object[]` | 在设置和新手引导期间暴露的 provider 设置描述符。 | -| `cliBackends` | 否 | `string[]` | 用于描述符优先设置查找的设置时后端 id。保持规范化 id 在全局范围内唯一。 | -| `configMigrations` | 否 | `string[]` | 由此插件的设置界面拥有的配置迁移 id。 | -| `requiresRuntime` | 否 | `boolean` | 在描述符查找之后，设置是否仍需要执行 `setup-api`。 | +| `providers` | 否 | `object[]` | 在设置和 onboarding 期间暴露的提供商设置描述符。 | +| `cliBackends` | 否 | `string[]` | 用于“描述符优先”设置查找的设置时后端 id。请保持规范化 id 在全局范围内唯一。 | +| `configMigrations` | 否 | `string[]` | 属于此插件设置界面的配置迁移 id。 | +| `requiresRuntime` | 否 | `boolean` | 在描述符查找之后，设置是否仍需要执行 `setup-api`。 | ## `uiHints` 参考 -`uiHints` 是从配置字段名称到小型渲染提示的映射。 +`uiHints` 是一个从配置字段名映射到小型渲染提示的映射表。 ```json { @@ -340,20 +339,20 @@ OpenClaw 还会将 `setup.providers[].envVars` 纳入通用 provider 认证和 } ``` -每个字段提示可以包含： +每个字段提示可包含： | 字段 | 类型 | 含义 | | ------------- | ---------- | --------------------------------------- | -| `label` | `string` | 面向用户的字段标签。 | -| `help` | `string` | 简短辅助文本。 | -| `tags` | `string[]` | 可选的 UI 标签。 | -| `advanced` | `boolean` | 将该字段标记为高级字段。 | -| `sensitive` | `boolean` | 将该字段标记为机密或敏感字段。 | -| `placeholder` | `string` | 表单输入的占位文本。 | +| `label` | `string` | 面向用户的字段标签。 | +| `help` | `string` | 简短辅助文本。 | +| `tags` | `string[]` | 可选的 UI 标签。 | +| `advanced` | `boolean` | 将该字段标记为高级项。 | +| `sensitive` | `boolean` | 将该字段标记为秘密或敏感项。 | +| `placeholder` | `string` | 表单输入的占位文本。 | ## `contracts` 参考 -仅当 OpenClaw 可以在不导入插件运行时的情况下读取静态能力归属元数据时，才使用 `contracts`。 +仅当 OpenClaw 能在不导入插件运行时的情况下读取静态能力归属元数据时，才使用 `contracts`。 ```json { @@ -378,36 +377,29 @@ OpenClaw 还会将 `setup.providers[].envVars` 纳入通用 provider 认证和 | 字段 | 类型 | 含义 | | -------------------------------- | ---------- | --------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Codex app-server 扩展工厂 id，目前为 `codex-app-server`。 | -| `agentToolResultMiddleware` | `string[]` | 内置插件可为其注册工具结果中间件的运行时 id。 | -| `externalAuthProviders` | `string[]` | 此插件拥有其外部认证配置文件钩子的 provider id。 | -| `speechProviders` | `string[]` | 此插件拥有的语音 provider id。 | -| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转写 provider id。 | -| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音 provider id。 | -| `memoryEmbeddingProviders` | `string[]` | 此插件拥有的 Memory 嵌入 provider id。 | -| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解 provider id。 | -| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成 provider id。 | -| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成 provider id。 | -| `webFetchProviders` | `string[]` | 此插件拥有的网页抓取 provider id。 | -| `webSearchProviders` | `string[]` | 此插件拥有的 Web 搜索 provider id。 | -| `tools` | `string[]` | 此插件拥有、用于内置契约检查的智能体工具名称。 | +| `embeddedExtensionFactories` | `string[]` | Codex app-server 扩展工厂 id，当前为 `codex-app-server`。 | +| `agentToolResultMiddleware` | `string[]` | 内置插件可为其注册工具结果中间件的运行时 id。 | +| `externalAuthProviders` | `string[]` | 此插件拥有其外部凭证配置文件 hook 的提供商 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-fetch 提供商 id。 | +| `webSearchProviders` | `string[]` | 此插件拥有的 Web 搜索提供商 id。 | +| `tools` | `string[]` | 此插件为内置契约检查所拥有的智能体工具名称。 | -`contracts.embeddedExtensionFactories` 保留用于仅面向内置 Codex -app-server 的扩展工厂。内置工具结果转换应声明 -`contracts.agentToolResultMiddleware`，并通过 -`api.registerAgentToolResultMiddleware(...)` 进行注册。外部插件不能 -注册工具结果中间件，因为该接口能够在模型看到高信任度工具输出之前对其进行改写。 +`contracts.embeddedExtensionFactories` 保留给内置的仅用于 Codex app-server 的扩展工厂。内置工具结果转换器应声明 `contracts.agentToolResultMiddleware`，并通过 `api.registerAgentToolResultMiddleware(...)` 注册。外部插件不能注册工具结果中间件，因为该接口可以在模型看到高信任工具输出之前重写它。 -实现 `resolveExternalAuthProfiles` 的 provider 插件应声明 -`contracts.externalAuthProviders`。未声明该字段的插件仍会通过一个已弃用的兼容性回退路径运行，但该回退更慢，并将在迁移窗口结束后移除。 +实现了 `resolveExternalAuthProfiles` 的提供商插件应声明 `contracts.externalAuthProviders`。未作此声明的插件仍会通过一个已弃用的兼容性回退路径运行，但该回退较慢，并将在迁移窗口结束后移除。 -内置的 Memory 嵌入 provider 应为其公开的每个适配器 id 声明 -`contracts.memoryEmbeddingProviders`，包括诸如 `local` 这样的内置适配器。 -独立 CLI 路径使用此清单契约在完整 Gateway 网关 运行时注册 provider 之前，仅加载拥有该能力的插件。 +内置 Memory 嵌入提供商应为其暴露的每个适配器 id 声明 `contracts.memoryEmbeddingProviders`，包括 `local` 这类内置适配器。独立 CLI 路径使用此清单契约在完整 Gateway 网关运行时注册提供商之前，仅加载对应拥有者插件。 ## `mediaUnderstandingProviderMetadata` 参考 -当媒体理解 provider 在运行时加载前需要让通用核心辅助工具知道默认模型、自动认证回退优先级或原生文档支持时，请使用 `mediaUnderstandingProviderMetadata`。键也必须在 `contracts.mediaUnderstandingProviders` 中声明。 +当媒体理解提供商具有默认模型、自动凭证回退优先级，或运行时加载前通用核心辅助工具所需的原生文档支持时，请使用 `mediaUnderstandingProviderMetadata`。键名也必须在 `contracts.mediaUnderstandingProviders` 中声明。 ```json { @@ -430,25 +422,27 @@ app-server 的扩展工厂。内置工具结果转换应声明 } ``` -每个 provider 条目可以包含： +每个提供商条目可包含： | 字段 | 类型 | 含义 | | ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | 此 provider 提供的媒体能力。 | -| `defaultModels` | `Record` | 当配置未指定模型时使用的能力到模型默认值映射。 | -| `autoPriority` | `Record` | 用于基于凭证的自动 provider 回退时，数字越小排序越靠前。 | -| `nativeDocumentInputs` | `"pdf"[]` | provider 支持的原生文档输入。 | +| `capabilities` | `("image" \| "audio" \| "video")[]` | 此提供商暴露的媒体能力。 | +| `defaultModels` | `Record` | 当配置未指定模型时使用的“能力到模型”默认值。 | +| `autoPriority` | `Record` | 用于基于凭证的自动提供商回退时，数字越小排序越靠前。 | +| `nativeDocumentInputs` | `"pdf"[]` | 提供商支持的原生文档输入。 | ## `channelConfigs` 参考 -当渠道插件在运行时加载前需要低成本的配置元数据时，请使用 `channelConfigs`。当没有可用的 setup entry，或者 `setup.requiresRuntime: false` 声明设置运行时非必需时，只读的渠道设置/状态发现可以直接使用这些元数据来处理已配置的外部渠道。 +当渠道插件在运行时加载前需要轻量级配置元数据时，请使用 `channelConfigs`。对于已配置的外部渠道，如果没有可用的 setup 条目，或者 `setup.requiresRuntime: false` 声明设置运行时并非必需，只读的渠道设置 / Status 发现可以直接使用这些元数据。 + +`channelConfigs` 是插件清单元数据，而不是新的顶层用户配置区段。用户仍然在 `channels.` 下配置渠道实例。OpenClaw 读取清单元数据，以便在插件运行时代码执行之前决定哪个插件拥有该已配置渠道。 对于渠道插件，`configSchema` 和 `channelConfigs` 描述的是不同路径： -- `configSchema` 验证 `plugins.entries..config` -- `channelConfigs..schema` 验证 `channels.` +- `configSchema` 校验 `plugins.entries..config` +- `channelConfigs..schema` 校验 `channels.` -声明了 `channels[]` 的非内置插件也应声明匹配的 `channelConfigs` 条目。缺少它们时，OpenClaw 仍然可以加载该插件，但冷路径配置 schema、设置和控制 UI 界面在插件运行时执行之前将无法知道该渠道拥有的选项结构。 +声明了 `channels[]` 的非内置插件也应声明匹配的 `channelConfigs` 条目。缺少这些条目时，OpenClaw 仍可加载插件，但冷路径配置 schema、设置以及 Control UI 界面在插件运行时执行之前，将无法得知该渠道拥有的选项结构。 ```json { @@ -475,19 +469,46 @@ app-server 的扩展工厂。内置工具结果转换应声明 } ``` -每个渠道条目可以包含： +每个渠道条目可包含： | 字段 | 类型 | 含义 | | ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | -| `schema` | `object` | `channels.` 的 JSON Schema。每个已声明的渠道配置条目都必须提供。 | -| `uiHints` | `Record` | 该渠道配置部分可选的 UI 标签/占位符/敏感性提示。 | -| `label` | `string` | 当运行时元数据尚未就绪时，合并到选择器和检查界面中的渠道标签。 | -| `description` | `string` | 用于检查和目录界面的简短渠道描述。 | -| `preferOver` | `string[]` | 在选择界面中，该渠道应优先于其排序的旧版或低优先级插件 id。 | +| `schema` | `object` | `channels.` 的 JSON Schema。每个已声明的渠道配置条目都必须提供。 | +| `uiHints` | `Record` | 该渠道配置区段的可选 UI 标签 / 占位符 / 敏感性提示。 | +| `label` | `string` | 当运行时元数据尚未就绪时，合并到选择器和检查界面中的渠道标签。 | +| `description` | `string` | 用于检查和目录界面的简短渠道描述。 | +| `preferOver` | `string[]` | 在选择界面中，此渠道应优先于的旧版或较低优先级插件 id。 | + +### 替换另一个渠道插件 + +当你的插件是某个渠道 id 的首选拥有者，而另一个插件也能提供该渠道时，请使用 `preferOver`。常见情况包括：插件 id 已重命名、独立插件取代了内置插件，或维护中的分叉版本为了配置兼容性而保留相同的渠道 id。 + +```json +{ + "id": "acme-chat", + "channels": ["chat"], + "channelConfigs": { + "chat": { + "schema": { + "type": "object", + "additionalProperties": false, + "properties": { + "webhookUrl": { "type": "string" } + } + }, + "preferOver": ["chat"] + } + } +} +``` + +当配置了 `channels.chat` 时，OpenClaw 会同时考虑渠道 id 和首选插件 id。如果低优先级插件仅因为它是内置的或默认启用而被选中，OpenClaw 会在生效的运行时配置中禁用它，以便由一个插件独占该渠道及其工具。显式用户选择仍然优先：如果用户显式启用了两个插件，OpenClaw 会保留该选择，并报告重复渠道 / 工具诊断，而不是静默更改所请求的插件集合。 + +请将 `preferOver` 限定在确实能够提供同一渠道的插件 id 范围内。它不是通用优先级字段，也不会重命名用户配置键。 ## `modelSupport` 参考 -当 OpenClaw 应在插件运行时加载前，根据诸如 `gpt-5.5` 或 `claude-sonnet-4.6` 之类的简写模型 id 推断你的 provider 插件时，请使用 `modelSupport`。 +当 OpenClaw 应在插件运行时加载之前，根据诸如 `gpt-5.5` 或 `claude-sonnet-4.6` 这类简写模型 id 推断出你的提供商插件时，请使用 `modelSupport`。 ```json { @@ -498,23 +519,23 @@ app-server 的扩展工厂。内置工具结果转换应声明 } ``` -OpenClaw 按以下优先级应用： +OpenClaw 应用以下优先级： -- 显式的 `provider/model` 引用使用拥有该模型的 `providers` 清单元数据 -- `modelPatterns` 优先于 `modelPrefixes` -- 如果一个非内置插件和一个内置插件都匹配，则非内置插件胜出 -- 其余歧义会被忽略，直到用户或配置指定 provider +- 显式的 `provider/model` 引用使用拥有该提供商的 `providers` 清单元数据 +- `modelPatterns` 的优先级高于 `modelPrefixes` +- 如果一个非内置插件和一个内置插件同时匹配，则非内置插件胜出 +- 剩余的歧义会被忽略，直到用户或配置明确指定提供商 字段： | 字段 | 类型 | 含义 | | --------------- | ---------- | ------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | 使用 `startsWith` 对简写模型 id 进行匹配的前缀。 | -| `modelPatterns` | `string[]` | 在移除 profile 后缀后，对简写模型 id 进行匹配的正则表达式源码。 | +| `modelPrefixes` | `string[]` | 使用 `startsWith` 针对简写模型 id 进行匹配的前缀。 | +| `modelPatterns` | `string[]` | 在移除 profile 后缀后，针对简写模型 id 进行匹配的正则表达式源码。 | ## `modelCatalog` 参考 -当 OpenClaw 应在加载插件运行时之前获知 provider 模型元数据时，请使用 `modelCatalog`。这是由清单拥有的固定目录条目、provider 别名、抑制规则和发现模式的来源。运行时刷新仍属于 provider 运行时代码，但清单会告诉核心何时需要运行时。 +当 OpenClaw 需要在加载插件运行时之前了解提供商模型元数据时，请使用 `modelCatalog`。这是由清单拥有的固定目录行、提供商别名、抑制规则和发现模式的数据源。运行时刷新仍属于提供商运行时代码，但清单会告诉核心何时需要运行时。 ```json { @@ -567,102 +588,96 @@ OpenClaw 按以下优先级应用： | 字段 | 类型 | 含义 | | -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| `providers` | `Record` | 由此插件拥有的 provider id 的目录条目。键也应出现在顶层 `providers` 中。 | -| `aliases` | `Record` | 应解析为某个拥有的 provider 的 provider 别名，用于目录或抑制规划。 | -| `suppressions` | `object[]` | 出于 provider 专属原因而由此插件抑制的、来自其他来源的模型条目。 | -| `discovery` | `Record` | provider 目录是可从清单元数据读取、可刷新到缓存中，还是需要运行时。 | +| `providers` | `Record` | 由此插件拥有的提供商 id 的目录行。键名也应出现在顶层 `providers` 中。 | +| `aliases` | `Record` | 在目录或抑制规划中，应解析到某个已拥有提供商的提供商别名。 | +| `suppressions` | `object[]` | 此插件因特定提供商原因而抑制的、来自其他来源的模型行。 | +| `discovery` | `Record` | 提供商目录是否可从清单元数据读取、可刷新到缓存，或必须依赖运行时。 | -provider 字段： +提供商字段： | 字段 | 类型 | 含义 | | --------- | ------------------------ | ----------------------------------------------------------------- | -| `baseUrl` | `string` | 此 provider 目录中模型的可选默认 base URL。 | -| `api` | `ModelApi` | 此 provider 目录中模型的可选默认 API 适配器。 | -| `headers` | `Record` | 适用于此 provider 目录的可选静态请求头。 | -| `models` | `object[]` | 必填的模型条目。没有 `id` 的条目会被忽略。 | +| `baseUrl` | `string` | 此提供商目录中模型的可选默认 base URL。 | +| `api` | `ModelApi` | 此提供商目录中模型的可选默认 API 适配器。 | +| `headers` | `Record` | 适用于此提供商目录的可选静态 headers。 | +| `models` | `object[]` | 必填的模型行。没有 `id` 的行会被忽略。 | 模型字段： | 字段 | 类型 | 含义 | | --------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------- | -| `id` | `string` | provider 本地模型 id，不包含 `provider/` 前缀。 | -| `name` | `string` | 可选显示名称。 | -| `api` | `ModelApi` | 可选的按模型设置的 API 覆盖。 | -| `baseUrl` | `string` | 可选的按模型设置的 base URL 覆盖。 | -| `headers` | `Record` | 可选的按模型设置的静态请求头。 | -| `input` | `Array<"text" \| "image" \| "document">` | 该模型接受的模态。 | -| `reasoning` | `boolean` | 该模型是否公开推理行为。 | -| `contextWindow` | `number` | 原生 provider 上下文窗口。 | -| `contextTokens` | `number` | 当与 `contextWindow` 不同时，可选的有效运行时上下文上限。 | -| `maxTokens` | `number` | 已知时的最大输出 token 数。 | -| `cost` | `object` | 可选的每百万 token 美元定价，包括可选的 `tieredPricing`。 | -| `compat` | `object` | 与 OpenClaw 模型配置兼容性相匹配的可选兼容性标志。 | -| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | 列表状态。仅当该条目完全不应显示时才使用 suppression。 | -| `statusReason` | `string` | 与非可用状态一起显示的可选原因。 | -| `replaces` | `string[]` | 该模型取代的较旧 provider 本地模型 id。 | -| `replacedBy` | `string` | 已弃用条目的替代 provider 本地模型 id。 | -| `tags` | `string[]` | 供选择器和过滤器使用的稳定标签。 | +| `id` | `string` | 提供商本地模型 id，不包含 `provider/` 前缀。 | +| `name` | `string` | 可选的显示名称。 | +| `api` | `ModelApi` | 可选的逐模型 API 覆盖。 | +| `baseUrl` | `string` | 可选的逐模型 base URL 覆盖。 | +| `headers` | `Record` | 可选的逐模型静态 headers。 | +| `input` | `Array<"text" \| "image" \| "document">` | 模型接受的模态。 | +| `reasoning` | `boolean` | 模型是否暴露 reasoning 行为。 | +| `contextWindow` | `number` | 提供商原生上下文窗口。 | +| `contextTokens` | `number` | 当与 `contextWindow` 不同时，可选的生效运行时上下文上限。 | +| `maxTokens` | `number` | 已知时的最大输出 token 数。 | +| `cost` | `object` | 可选的每百万 token 的美元定价，包括可选的 `tieredPricing`。 | +| `compat` | `object` | 与 OpenClaw 模型配置兼容性相匹配的可选兼容性标记。 | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | 列表 Status。仅当该行完全不应出现时才使用 suppress。 | +| `statusReason` | `string` | 与非可用 Status 一起显示的可选原因。 | +| `replaces` | `string[]` | 被此模型取代的旧版提供商本地模型 id。 | +| `replacedBy` | `string` | 已弃用行的替代提供商本地模型 id。 | +| `tags` | `string[]` | 供选择器和过滤器使用的稳定标签。 | -不要将仅运行时数据放入 `modelCatalog` 中。如果某个 provider 需要账户状态、API 请求或本地进程发现才能知道完整模型集，请在 `discovery` 中将该 provider 声明为 `refreshable` 或 `runtime`。 +不要在 `modelCatalog` 中放入仅运行时可得的数据。如果某个提供商需要账户状态、API 请求或本地进程发现才能得知完整模型集合，请在 `discovery` 中将该提供商声明为 `refreshable` 或 `runtime`。 -旧版顶层能力键已弃用。使用 `openclaw doctor --fix` 将 -`speechProviders`、`realtimeTranscriptionProviders`、 -`realtimeVoiceProviders`、`mediaUnderstandingProviders`、 -`imageGenerationProviders`、`videoGenerationProviders`、 -`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；普通的 -清单加载不再将这些顶层字段视为能力归属。 +旧版顶层能力键已弃用。使用 `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` | 在新手引导、延迟渠道启动和只读渠道状态/SecretRef 发现期间使用的轻量级仅设置入口点。必须保留在插件包目录内。 | -| `openclaw.runtimeSetupEntry` | 为已安装包声明构建后的 JavaScript 设置入口点。必须保留在插件包目录内。 | -| `openclaw.channel` | 低成本渠道目录元数据，例如标签、文档路径、别名和选择文案。 | -| `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` | 在 onboarding、延迟渠道启动和只读渠道 Status / SecretRef 发现期间使用的轻量级仅设置入口点。必须保持在插件包目录内。 | +| `openclaw.runtimeSetupEntry` | 为已安装包声明构建后的 JavaScript 设置入口点。必须保持在插件包目录内。 | +| `openclaw.channel` | 轻量级渠道目录元数据，例如标签、文档路径、别名和选择文案。 | +| `openclaw.channel.configuredState` | 轻量级 configured-state 检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅环境变量的设置？”。 | +| `openclaw.channel.persistedAuthState` | 轻量级持久化凭证检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何已登录状态？”。 | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 内置插件和外部发布插件的安装 / 更新提示。 | +| `openclaw.install.defaultChoice` | 当有多个安装来源可用时的首选安装路径。 | +| `openclaw.install.minHostVersion` | 最低受支持的 OpenClaw 宿主版本，使用如 `>=2026.3.22` 这样的 semver 下限。 | +| `openclaw.install.expectedIntegrity` | 预期的 npm 分发完整性字符串，例如 `sha512-...`；安装和更新流程会据此校验拉取到的制品。 | +| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一条狭义的内置插件重新安装恢复路径。 | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间先加载仅设置的渠道界面，再加载完整渠道插件。 | -清单元数据决定了在运行时加载前，新手引导中会显示哪些 provider/渠道/设置选项。`package.json#openclaw.install` 则告诉新手引导，当用户选择这些选项之一时，应如何获取或启用该插件。不要将安装提示移到 `openclaw.plugin.json` 中。 +清单元数据决定了在运行时加载之前，哪些提供商 / 渠道 / 设置选项会出现在 onboarding 中。`package.json#openclaw.install` 告诉 onboarding，当用户选择其中某个选项时，应如何获取或启用该插件。不要将安装提示移到 `openclaw.plugin.json` 中。 -`openclaw.install.minHostVersion` 会在安装期间和清单注册表加载期间强制执行。无效值会被拒绝；在较旧主机上，更新但有效的值会跳过该插件。 +`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 制品不再匹配已固定的发布版本时，更新流程能够以安全关闭方式失败。为兼容性起见，交互式 onboarding 仍会提供受信任注册表的 npm spec，包括裸包名和 dist-tag。目录诊断可以区分精确、浮动、带完整性固定、缺少完整性、包名不匹配以及无效默认选项来源。它们还会在存在 `expectedIntegrity` 但没有可用于固定它的有效 npm 来源时发出警告。当存在 `expectedIntegrity` 时，安装 / 更新流程会强制执行它；省略时，注册表解析结果会被记录，但不会带完整性固定。 -当状态、渠道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账户时，渠道插件应提供 `openclaw.setupEntry`。该设置入口应公开渠道元数据以及对设置安全的配置、状态和 secrets 适配器；应将网络客户端、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 { @@ -678,9 +693,9 @@ provider 字段： } ``` -当设置、Doctor 或已配置状态流程需要在完整渠道插件加载前进行低成本的“是/否”认证探测时，请使用它。目标导出应是一个仅读取持久化状态的小函数；不要通过完整渠道运行时 barrel 转发它。 +当设置、Doctor 或 configured-state 流程需要在完整渠道插件加载之前进行廉价的是 / 否凭证探测时，请使用它。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 转发它。 -`openclaw.channel.configuredState` 采用相同的结构，用于低成本的仅环境变量已配置检查： +`openclaw.channel.configuredState` 对廉价的仅环境变量配置检查采用相同结构： ```json { @@ -696,52 +711,52 @@ provider 字段： } ``` -当某个渠道可以根据环境变量或其他微型非运行时输入回答已配置状态时，请使用它。如果检查需要完整配置解析或真实渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState` hook 中。 +当渠道可以仅通过环境变量或其他微小的非运行时输入来判断 configured-state 时，请使用它。如果该检查需要完整配置解析或真实渠道运行时，请将该逻辑保留在插件的 `config.hasConfiguredState` hook 中。 ## 设备发现优先级（重复插件 id） -OpenClaw 会从多个根位置发现插件（内置、全局安装、工作区、配置中显式选定的路径）。如果两个发现结果共享相同的 `id`，则只保留**优先级最高**的清单；较低优先级的重复项会被丢弃，而不是与其并列加载。 +OpenClaw 会从多个根位置发现插件（内置、全局安装、工作区、配置中显式选定的路径）。如果两个发现结果共享同一个 `id`，则只保留**优先级最高**的清单；优先级较低的重复项会被丢弃，而不会与其并行加载。 优先级从高到低如下： -1. **配置选定** — 在 `plugins.entries.` 中显式固定的路径 -2. **内置** — 随 OpenClaw 一起发布的插件 -3. **全局安装** — 安装到全局 OpenClaw 插件根目录中的插件 -4. **工作区** — 相对于当前工作区发现的插件 +1. **配置选定** —— 在 `plugins.entries.` 中显式固定的路径 +2. **内置** —— 随 OpenClaw 一起发布的插件 +3. **全局安装** —— 安装到全局 OpenClaw 插件根目录的插件 +4. **工作区** —— 相对于当前工作区发现的插件 影响： -- 工作区中某个内置插件的 fork 或陈旧副本不会遮蔽内置构建。 -- 如果确实要用本地插件覆盖内置插件，请通过 `plugins.entries.` 固定它，使其凭优先级获胜，而不是依赖工作区发现。 -- 重复项丢弃会被记录，因此 Doctor 和启动诊断可以指向被丢弃的副本。 +- 工作区中某个内置插件的分叉版或陈旧副本不会遮蔽内置构建版本。 +- 若要真正用本地插件覆盖某个内置插件，请通过 `plugins.entries.` 固定它，以便它依靠优先级获胜，而不是依赖工作区发现。 +- 重复项被丢弃时会记录日志，以便 Doctor 和启动诊断能够指出被舍弃的副本。 ## JSON Schema 要求 - **每个插件都必须提供一个 JSON Schema**，即使它不接受任何配置。 -- 可以接受空 schema（例如 `{ "type": "object", "additionalProperties": false }`）。 -- schema 会在配置读取/写入时验证，而不是在运行时验证。 +- 可以使用空 schema（例如 `{ "type": "object", "additionalProperties": false }`）。 +- Schema 会在配置读取 / 写入时校验，而不是在运行时校验。 -## 验证行为 +## 校验行为 -- 未知的 `channels.*` 键会被视为**错误**，除非该渠道 id 已由某个插件清单声明。 +- 未知的 `channels.*` 键是**错误**，除非该渠道 id 由某个插件清单声明。 - `plugins.entries.`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` - 必须引用**可发现的**插件 id。未知 id 会被视为**错误**。 -- 如果插件已安装，但其清单或 schema 缺失或损坏，验证会失败，Doctor 会报告该插件错误。 -- 如果插件配置存在，但插件处于**禁用**状态，则配置会被保留，并且 Doctor + 日志中会显示**警告**。 + 必须引用**可发现**的插件 id。未知 id 属于**错误**。 +- 如果插件已安装，但其清单或 schema 缺失或损坏，校验会失败，Doctor 会报告该插件错误。 +- 如果插件配置存在，但插件已**禁用**，配置会被保留，并且 Doctor + 日志中会显示一条**警告**。 -完整的 `plugins.*` schema 请参阅[配置参考](/zh-CN/gateway/configuration)。 +完整的 `plugins.*` schema，请参阅[配置参考](/zh-CN/gateway/configuration)。 -## 注意事项 +## 说明 -- 对于**原生 OpenClaw 插件**，清单是**必需的**，包括本地文件系统加载。运行时仍会单独加载插件模块；清单仅用于设备发现 + 验证。 -- 原生清单使用 JSON5 解析，因此只要最终值仍是一个对象，就接受注释、尾随逗号和未加引号的键。 -- 清单加载器只会读取文档化的清单字段。避免使用自定义顶层键。 -- 当插件不需要时，`channels`、`providers`、`cliBackends` 和 `skills` 都可以省略。 -- `providerDiscoveryEntry` 必须保持轻量，不应导入宽泛的运行时代码；应将其用于静态 provider 目录元数据或狭义发现描述符，而不是请求时执行。 -- 排他性插件类型通过 `plugins.slots.*` 进行选择：`kind: "memory"` 通过 `plugins.slots.memory` 选择，`kind: "context-engine"` 通过 `plugins.slots.contextEngine` 选择（默认值为 `legacy`）。 -- 环境变量元数据（`setup.providers[].envVars`、已弃用的 `providerAuthEnvVars` 和 `channelEnvVars`）仅为声明式。状态、审计、cron 投递验证以及其他只读界面，在将某个环境变量视为已配置之前，仍会应用插件信任和有效激活策略。 -- 关于需要 provider 代码的运行时向导元数据，请参阅[Provider 运行时钩子](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 -- 如果你的插件依赖原生模块，请记录构建步骤以及所有包管理器允许列表要求（例如 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`）。 +- 环境变量元数据（`setup.providers[].envVars`、已弃用的 `providerAuthEnvVars` 和 `channelEnvVars`）仅为声明式信息。Status、审计、cron 投递校验以及其他只读界面，在将某个环境变量视为已配置之前，仍会应用插件信任和生效激活策略。 +- 关于需要提供商代码的运行时向导元数据，请参阅[提供商运行时钩子](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 +- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器 allowlist 要求（例如 pnpm `allow-build-scripts` + `pnpm rebuild `）。 ## 相关内容 @@ -752,7 +767,7 @@ OpenClaw 会从多个根位置发现插件（内置、全局安装、工作区 内部架构和能力模型。 - + 插件 SDK 参考和子路径导入。 diff --git a/docs/zh-CN/tools/plugin.md b/docs/zh-CN/tools/plugin.md index 2591e41ac..0eb18ef94 100644 --- a/docs/zh-CN/tools/plugin.md +++ b/docs/zh-CN/tools/plugin.md @@ -2,20 +2,20 @@ read_when: - 安装或配置插件 - 了解插件发现和加载规则 - - 使用与 Codex/Claude 兼容的插件包 + - 使用与 Codex / Claude 兼容的插件捆绑包 sidebarTitle: Install and Configure summary: 安装、配置和管理 OpenClaw 插件 title: 插件 x-i18n: - generated_at: "2026-04-25T19:49:10Z" + generated_at: "2026-04-26T00:16:09Z" model: gpt-5.4 provider: openai - source_hash: bbc819fc29f0bf58fce83223e43e2ddba3f199c71c6536e900ac6032f181d770 + source_hash: 553c70416b9787437d46b3bd6f35570e532a3694c6c52d5d70e5014beed4328a source_path: tools/plugin.md workflow: 15 --- -插件通过新增能力来扩展 OpenClaw：渠道、模型提供商、智能体 harness、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是**核心**插件（随 OpenClaw 一起发布），另一些是**外部**插件（由社区发布到 npm）。 +插件通过新增功能来扩展 OpenClaw：渠道、模型提供商、智能体 harness、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等等。有些插件是**核心**插件（随 OpenClaw 一起提供），另一些则是**外部**插件（由社区发布到 npm）。 ## 快速开始 @@ -43,12 +43,12 @@ x-i18n: openclaw gateway restart ``` - 然后在你的配置文件中的 `plugins.entries.\.config` 下进行配置。 + 然后在你的配置文件中通过 `plugins.entries.\.config` 进行配置。 -如果你更喜欢聊天原生控制方式，请启用 `commands.plugins: true`，然后使用： +如果你更喜欢聊天原生控制方式，启用 `commands.plugins: true`，然后使用： ```text /plugin install clawhub:@openclaw/voice-call @@ -56,11 +56,17 @@ x-i18n: /plugin enable voice-call ``` -安装路径使用与 CLI 相同的解析器：本地路径/归档文件、显式 `clawhub:`，或裸包说明符（优先 ClawHub，然后回退到 npm）。 +安装路径使用与 CLI 相同的解析器：本地路径/归档文件、显式 `clawhub:`，或裸包规范（优先 ClawHub，其次回退到 npm）。 -如果配置无效，安装通常会以失败关闭的方式结束，并指引你运行 `openclaw doctor --fix`。唯一的恢复例外是一个范围很窄的内置插件重新安装路径，适用于选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。 +如果配置无效，安装通常会以失败关闭的方式结束，并提示你使用 +`openclaw doctor --fix`。唯一的恢复例外是一条较窄的内置插件重装路径，适用于选择加入 +`openclaw.install.allowInvalidConfigRecovery` +的插件。 -打包后的 OpenClaw 安装不会急切地安装每个内置插件的完整运行时依赖树。当某个 OpenClaw 自有的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于激活状态时，启动流程只会在导入该插件之前修复它声明的运行时依赖。显式禁用仍然优先生效：`plugins.entries..enabled: false`、`plugins.deny`、`plugins.enabled: false` 和 `channels..enabled: false` 都会阻止该插件/渠道自动执行内置运行时依赖修复。外部插件和自定义加载路径仍必须通过 `openclaw plugins install` 安装。 +打包分发的 OpenClaw 安装不会急切安装每个内置插件的全部运行时依赖树。当一个由 OpenClaw 拥有的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于激活状态时，启动修复只会在导入该插件之前修复它所声明的运行时依赖。显式禁用仍然优先：`plugins.entries..enabled: false`、 +`plugins.deny`、`plugins.enabled: false` 和 `channels..enabled: false` +都会阻止该插件/渠道的自动内置运行时依赖修复。外部插件和自定义加载路径仍然必须通过 +`openclaw plugins install` 安装。 ## 插件类型 @@ -69,11 +75,12 @@ OpenClaw 可识别两种插件格式： | 格式 | 工作方式 | 示例 | | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ | | **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 | -| **Bundle** | 与 Codex/Claude/Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` | +| **捆绑包** | 与 Codex / Claude / Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` | -两者都会显示在 `openclaw plugins list` 中。有关 bundle 的详细信息，请参见 [Plugin Bundles](/zh-CN/plugins/bundles)。 +两者都会显示在 `openclaw plugins list` 中。捆绑包详情请参阅 [Plugin Bundles](/zh-CN/plugins/bundles)。 -如果你正在编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins) 和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。 +如果你正在编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins) +和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。 ## 官方插件 @@ -88,33 +95,33 @@ OpenClaw 可识别两种插件格式： | Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) | | Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) | -### 核心（随 OpenClaw 一起发布） +### 核心（随 OpenClaw 提供） - `anthropic`、`byteplus`、`cloudflare-ai-gateway`、`github-copilot`、`google`、 - `huggingface`、`kilocode`、`kimi-coding`、`minimax`、`mistral`、`qwen`、 - `moonshot`、`nvidia`、`openai`、`opencode`、`opencode-go`、`openrouter`、 - `qianfan`、`synthetic`、`together`、`venice`、 - `vercel-ai-gateway`、`volcengine`、`xiaomi`、`zai` + `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`, + `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`, + `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`, + `qianfan`, `synthetic`, `together`, `venice`, + `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai` - - - `memory-core` — 内置内存搜索（通过 `plugins.slots.memory` 默认使用） - - `memory-lancedb` — 按需安装的长期内存，带自动召回/捕获功能（设置 `plugins.slots.memory = "memory-lancedb"`） + + - `memory-core` — 内置 memory 搜索（通过 `plugins.slots.memory` 默认启用） + - `memory-lancedb` — 按需安装的长期 memory，带自动召回/捕获功能（设置 `plugins.slots.memory = "memory-lancedb"`） - `elevenlabs`、`microsoft` + `elevenlabs`, `microsoft` - `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时以及默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用） - - `copilot-proxy` — VS Code Copilot Proxy 桥接器（默认禁用） + - `copilot-proxy` — VS Code Copilot Proxy 桥接插件（默认禁用） -在找第三方插件？请参见 [Community Plugins](/zh-CN/plugins/community)。 +在找第三方插件？请参阅 [社区插件](/zh-CN/plugins/community)。 ## 配置 @@ -132,26 +139,27 @@ OpenClaw 可识别两种插件格式： } ``` -| 字段 | 说明 | +| 字段 | 描述 | | ---------------- | --------------------------------------------------------- | | `enabled` | 主开关（默认：`true`） | | `allow` | 插件允许列表（可选） | | `deny` | 插件拒绝列表（可选；拒绝优先） | | `load.paths` | 额外的插件文件/目录 | -| `slots` | 独占插槽选择器（例如 `memory`、`contextEngine`） | -| `entries.\` | 每个插件的开关和配置 | +| `slots` | 排他性 slot 选择器（例如 `memory`、`contextEngine`） | +| `entries.\` | 按插件分别设置的开关 + 配置 | -配置更改**需要重启 Gateway 网关**。如果 Gateway 网关正在以启用配置监视和进程内重启的方式运行（默认的 `openclaw gateway` 路径），那么在配置写入完成后，通常会在片刻之后自动执行重启。原生插件运行时代码或生命周期钩子没有受支持的热重载路径；在期待更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务或提供商/运行时钩子生效之前，请重启提供实时渠道服务的 Gateway 网关进程。 +配置更改**需要重启网关**。如果 Gateway 网关正以启用配置监听和进程内重启的方式运行（默认的 `openclaw gateway` 路径），那么在配置写入完成后，通常会在稍后自动执行重启。原生插件运行时代码或生命周期钩子没有受支持的热重载路径；在你希望更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务或 provider / 运行时钩子生效之前，请重启正在服务实时渠道的 Gateway 网关进程。 -`openclaw plugins list` 是本地插件注册表/配置快照。其中的 `enabled` 插件表示持久化注册表和当前配置允许该插件参与运行。但这并不能证明一个已经运行的远程 Gateway 网关子进程已经重启并加载了相同的插件代码。在 VPS/容器部署中，如果使用了包装进程，请向实际的 `openclaw gateway run` 进程发送重启信号，或对正在运行的 Gateway 网关使用 `openclaw gateway restart`。 +`openclaw plugins list` 是本地插件注册表/配置快照。其中某个插件显示为 +`enabled`，表示持久化注册表和当前配置允许该插件参与运行。但这并不能证明一个已经在运行的远程 Gateway 网关子进程已经重启并加载了相同的插件代码。在 VPS / 容器部署中，如果使用了包装进程，请将重启信号发送给实际的 `openclaw gateway run` 进程，或者对正在运行的 Gateway 网关使用 `openclaw gateway restart`。 - + - **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。 - - **缺失**：配置引用了某个插件 id，但发现流程没有找到它。 + - **缺失**：配置引用了某个插件 id，但设备发现未找到它。 - **无效**：插件存在，但其配置与声明的 schema 不匹配。 -## 发现顺序和优先级 +## 设备发现和优先级 OpenClaw 按以下顺序扫描插件（先匹配者优先）： @@ -169,8 +177,8 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）： - 随 OpenClaw 一起发布。许多默认启用（模型提供商、语音）。 - 其他则需要显式启用。 + 随 OpenClaw 一起提供。许多插件默认启用（模型提供商、语音）。 + 其他插件则需要显式启用。 @@ -181,9 +189,9 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）： - `plugins.entries.\.enabled: false` 会禁用该插件 - 来自工作区的插件**默认禁用**（必须显式启用） - 内置插件遵循内建的默认启用集合，除非被覆盖 -- 独占插槽可以为该插槽强制启用所选插件 -- 一些选择加入的内置插件会在配置命名了某个插件自有的表面时自动启用，例如提供商模型引用、渠道配置或 harness 运行时 -- OpenAI 系列 Codex 路由保持独立的插件边界： +- 排他性 slot 可以强制启用该 slot 所选中的插件 +- 某些内置的可选加入插件会在配置命名了某个由插件拥有的功能面时自动启用，例如 provider 模型引用、渠道配置或 harness 运行时 +- OpenAI 系列的 Codex 路由保持独立的插件边界： `openai-codex/*` 属于 OpenAI 插件，而内置的 Codex app-server 插件则通过 `embeddedHarness.runtime: "codex"` 或旧版 `codex/*` 模型引用来选择 @@ -192,37 +200,62 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）： 如果某个插件出现在 `plugins list` 中，但 `register(api)` 的副作用或钩子没有在实时聊天流量中运行，请先检查以下内容： -- 运行 `openclaw gateway status --deep --require-rpc`，确认活动的 - Gateway 网关 URL、profile、配置路径和进程就是你正在编辑的那些。 -- 在插件安装/配置/代码更改后重启实时 Gateway 网关。在包装容器中， +- 运行 `openclaw gateway status --deep --require-rpc`，并确认当前活动的 + Gateway 网关 URL、配置文件、配置路径和进程，正是你正在编辑的那些。 +- 在插件安装/配置/代码更改后重启在线 Gateway 网关。在包装容器中， PID 1 可能只是一个 supervisor；请重启或向子进程 `openclaw gateway run` 发送信号。 -- 使用 `openclaw plugins inspect --json` 确认钩子注册和 - 诊断信息。像 `llm_input`、 - `llm_output` 和 `agent_end` 这样的非内置会话钩子需要 +- 使用 `openclaw plugins inspect --json` 确认钩子注册和诊断信息。非内置的会话钩子，例如 `llm_input`、 + `llm_output` 和 `agent_end`，需要 `plugins.entries..hooks.allowConversationAccess=true`。 -- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析之前运行；`llm_output` 只会在某次模型尝试产生助手输出之后运行。 -- 若要证明生效的会话模型，请使用 `openclaw sessions` 或 Gateway 网关的会话/Status 表面；在调试提供商负载时，请使用 `--raw-stream --raw-stream-path ` 启动 Gateway 网关。 +- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体回合的模型解析之前运行；`llm_output` 只会在一次模型尝试生成 assistant 输出后才运行。 +- 要证明有效的会话模型，请使用 `openclaw sessions` 或 + Gateway 网关的 session / Status 功能面；调试 provider 负载时，可使用 + `--raw-stream --raw-stream-path ` 启动 Gateway 网关。 -## 插件插槽（独占类别） +### 重复的渠道或工具归属 -有些类别是独占的（同一时间只能有一个处于活动状态）： +症状： + +- `channel already registered: ()` +- `channel setup already registered: ()` +- `plugin tool name conflict (): ` + +这表示有多个已启用插件正试图拥有同一个渠道、设置流程或工具名称。最常见的原因是，某个外部渠道插件与现已提供相同渠道 id 的内置插件同时安装。 + +调试步骤： + +- 运行 `openclaw plugins list --enabled --verbose` 以查看每个已启用插件及其来源。 +- 对每个可疑插件运行 `openclaw plugins inspect --json`，并比较 `channels`、`channelConfigs`、`tools` 和诊断信息。 +- 在安装或移除插件包后运行 `openclaw plugins registry --refresh`，使持久化元数据反映当前安装状态。 +- 在安装、注册表或配置更改后重启 Gateway 网关。 + +修复选项： + +- 如果一个插件有意替换另一个使用相同渠道 id 的插件，则首选插件应声明 `channelConfigs..preferOver`，其值为较低优先级插件的 id。请参阅 [/plugins/manifest#replacing-another-channel-plugin](/zh-CN/plugins/manifest#replacing-another-channel-plugin)。 +- 如果重复是意外造成的，可通过 + `plugins.entries..enabled: false` 禁用其中一方，或移除过期的插件安装。 +- 如果你显式启用了两个插件，OpenClaw 会保留这一请求并报告冲突。请为该渠道选择一个所有者，或重命名由插件拥有的工具，以确保运行时功能面明确无歧义。 + +## 插件 slots（排他性类别） + +某些类别是排他的（同一时间只能有一个处于激活状态）： ```json5 { plugins: { slots: { memory: "memory-core", // 或使用 "none" 禁用 - contextEngine: "legacy", // 或某个插件 id + contextEngine: "legacy", // 或填写某个插件 id }, }, } ``` -| 插槽 | 控制内容 | 默认值 | +| Slot | 控制内容 | 默认值 | | --------------- | --------------------- | ------------------- | -| `memory` | 当前激活的内存插件 | `memory-core` | -| `contextEngine` | 当前激活的上下文引擎 | `legacy`（内置） | +| `memory` | 活跃的 memory 插件 | `memory-core` | +| `contextEngine` | 活跃的上下文引擎 | `legacy`（内建） | ## CLI 参考 @@ -230,21 +263,21 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）： openclaw plugins list # 精简清单 openclaw plugins list --enabled # 仅显示已启用插件 openclaw plugins list --verbose # 每个插件的详细信息行 -openclaw plugins list --json # 机器可读清单 +openclaw plugins list --json # 机器可读的清单 openclaw plugins inspect # 深度详情 openclaw plugins inspect --json # 机器可读 -openclaw plugins inspect --all # 全局表格 -openclaw plugins info # inspect 别名 +openclaw plugins inspect --all # 全量表格 +openclaw plugins info # inspect 的别名 openclaw plugins doctor # 诊断 -openclaw plugins registry # 检查持久化注册表状态 +openclaw plugins registry # 查看持久化注册表状态 openclaw plugins registry --refresh # 重建持久化注册表 -openclaw doctor --fix # 修复注册表/账本迁移状态 +openclaw doctor --fix # 修复插件注册表状态 -openclaw plugins install # 安装（优先 ClawHub，然后 npm） +openclaw plugins install # 安装（优先 ClawHub，其次 npm） openclaw plugins install clawhub: # 仅从 ClawHub 安装 openclaw plugins install --force # 覆盖现有安装 openclaw plugins install # 从本地路径安装 -openclaw plugins install -l # 链接（不复制），用于开发 +openclaw plugins install -l # 为开发创建链接（不复制） openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// openclaw plugins install --pin # 记录精确解析后的 npm spec @@ -252,7 +285,7 @@ openclaw plugins install --dangerously-force-unsafe-install openclaw plugins update # 更新单个插件 openclaw plugins update --dangerously-force-unsafe-install openclaw plugins update --all # 更新全部 -openclaw plugins uninstall # 移除配置和安装账本记录 +openclaw plugins uninstall # 移除配置和插件索引记录 openclaw plugins uninstall --keep-files openclaw plugins marketplace list openclaw plugins marketplace list --json @@ -261,34 +294,34 @@ openclaw plugins enable openclaw plugins disable ``` -内置插件随 OpenClaw 一起发布。许多默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）。其他内置插件仍然需要执行 `openclaw plugins enable `。 +内置插件随 OpenClaw 一起提供。许多插件默认启用（例如内置模型提供商、内置语音提供商，以及内置浏览器插件）。其他内置插件仍然需要执行 `openclaw plugins enable `。 -`--force` 会原地覆盖已安装的插件或 hook 包。对于已跟踪 npm 插件的常规升级，请使用 `openclaw plugins update `。它不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，而不是复制到受管理的安装目标。 +`--force` 会就地覆盖现有已安装的插件或 hook 包。对于已跟踪 npm +插件的常规升级，请使用 `openclaw plugins update `。它不支持与 `--link` 一起使用，因为后者会复用源路径，而不是复制到受管理的安装目标位置。 -当 `plugins.allow` 已经设置时，`openclaw plugins install` 会先把已安装插件的 id 添加到该允许列表中，然后再启用它，这样重启后安装的插件就能立即被加载。 +当已经设置了 `plugins.allow` 时，`openclaw plugins install` 会在启用插件之前，先将已安装的插件 id 添加到该允许列表中，因此重启后安装内容可立即被加载。 -OpenClaw 会维护一个持久化的本地插件注册表，作为插件清单、贡献归属和启动规划的冷读取模型。安装、更新、卸载、启用和禁用流程会在修改插件状态后刷新该注册表。如果注册表缺失、过期或无效，`openclaw plugins registry --refresh` 会在不加载插件运行时模块的前提下，根据持久安装账本、配置策略以及 manifest/package 元数据重建它。 -如果某台机器的配置中仍保留旧版 `plugins.installs` 记录，请运行 `openclaw doctor --fix`，把它们迁移到受管理的 `plugins/installs.json` 账本中，并移除配置里的副本。 - -`openclaw plugins update ` 适用于已跟踪的安装。传入带 dist-tag 或精确版本的 npm 包 spec 时，会把包名解析回已跟踪的插件记录，并为后续更新记录新的 spec。传入不带版本的包名时，会把一个精确固定版本的安装移回注册表的默认发布线。如果已安装的 npm 插件已经匹配解析后的版本和记录的制品标识，OpenClaw 会跳过更新，不会下载、重新安装或重写配置。 +OpenClaw 会维护一个持久化的本地插件注册表，作为插件清单、贡献归属以及启动规划的冷读取模型。安装、更新、卸载、启用和禁用流程在改变插件状态后都会刷新该注册表。同一个 `plugins/installs.json` 文件会在顶层 `installRecords` 中保存持久安装元数据，并在 `plugins` 中保存可重建的清单元数据。如果注册表缺失、过期或无效，`openclaw plugins registry +--refresh` 会根据安装记录、配置策略以及清单/包元数据重建其清单视图，而无需加载插件运行时模块。`openclaw plugins update ` 适用于已跟踪的安装。传入带 dist-tag 或精确版本的 npm 包 spec 时，会将包名解析回已跟踪的插件记录，并为后续更新记录新的 spec。传入不带版本的包名时，会将已精确 pin 的安装移回注册表的默认发布线。如果已安装的 npm 插件已经匹配解析后的版本和记录的构件身份，OpenClaw 会跳过本次更新，不会下载、重新安装或重写配置。 `--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 源元数据，而不是 npm spec。 -`--dangerously-force-unsafe-install` 是一个“破玻璃”式覆盖选项，用于处理内置危险代码扫描器的误报。它允许插件安装和插件更新在内置 `critical` 发现后继续进行，但仍不会绕过插件 `before_install` 策略拦截或扫描失败拦截。 +`--dangerously-force-unsafe-install` 是用于处理内置危险代码扫描器误报的紧急覆盖开关。它允许插件安装和插件更新在遇到内置 `critical` 发现后继续执行，但仍不会绕过插件 `before_install` 策略拦截，也不会绕过扫描失败阻断。 -这个 CLI 标志仅适用于插件安装/更新流程。基于 Gateway 网关的 Skills 依赖安装则改用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是单独的 ClawHub Skills 下载/安装流程。 +这个 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 Skills 依赖安装则使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖；而 `openclaw skills install` 仍是独立的 ClawHub Skills 下载/安装流程。 -兼容的 bundle 会参与同一套插件 list/inspect/enable/disable 流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和 manifest 声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。 +兼容的捆绑包会参与相同的插件 list / inspect / enable / disable 流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 以及由清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。 -`openclaw plugins inspect ` 还会报告检测到的 bundle 能力，以及由 bundle 支持的或不支持的 MCP 和 LSP 服务器条目。 +`openclaw plugins inspect ` 还会报告检测到的 bundle 能力，以及由 bundle 支持的或不支持的 MCP 和 LSP server 条目。 -Marketplace 源可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保持在克隆得到的 marketplace 仓库内部，并且只能使用相对路径源。 +Marketplace 源可以是来自 +`~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、像 `owner/repo` 这样的 GitHub 简写、GitHub 仓库 URL，或者 git URL。对于远程 marketplace，插件条目必须保持在克隆后的 marketplace 仓库内部，并且只能使用相对路径源。 -完整详情请参见 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。 +完整详情请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。 ## 插件 API 概览 -原生插件会导出一个入口对象，并暴露 `register(api)`。旧版插件仍可能使用 `activate(api)` 作为兼容别名，但新插件应使用 `register`。 +原生插件会导出一个入口对象，其中暴露 `register(api)`。旧版插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。 ```typescript export default definePluginEntry({ @@ -308,19 +341,19 @@ export default definePluginEntry({ }); ``` -OpenClaw 会加载这个入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为旧插件回退到 `activate(api)`，但内置插件和新的外部插件都应将 `register` 视为公开契约。 +OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为旧版插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。 -`api.registrationMode` 会告诉插件，为什么正在加载它的入口： +`api.registrationMode` 会告诉插件其入口为何被加载： | 模式 | 含义 | | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `full` | 运行时激活。注册工具、钩子、服务、命令、路由以及其他实时副作用。 | -| `discovery` | 只读能力发现。注册提供商和元数据；可信插件入口代码可能会被加载，但应跳过实时副作用。 | -| `setup-only` | 通过轻量级 setup 入口加载渠道 setup 元数据。 | -| `setup-runtime` | 加载渠道 setup，同时还需要运行时入口。 | +| `discovery` | 只读能力发现。注册 provider 和元数据；可信的插件入口代码可能会被加载，但应跳过实时副作用。 | +| `setup-only` | 通过轻量级设置入口加载渠道设置元数据。 | +| `setup-runtime` | 加载渠道设置，且同时需要运行时入口。 | | `cli-metadata` | 仅收集 CLI 命令元数据。 | -如果插件入口会打开 socket、数据库、后台 worker 或长生命周期客户端，应使用 `api.registrationMode === "full"` 来保护这些副作用。发现加载与激活加载会分别缓存，且不会替换正在运行的 Gateway 网关注册表。发现流程不会激活，但也不是完全不导入：OpenClaw 可能会执行可信的插件入口或渠道插件模块来构建快照。请保持模块顶层轻量且无副作用，并把网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径之后。 +会打开套接字、数据库、后台工作线程或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 来保护这些副作用。设备发现加载与激活加载分别缓存，且不会替换正在运行的 Gateway 网关注册表。设备发现是非激活式的，但并非免导入：OpenClaw 可能会评估可信的插件入口或渠道插件模块，以构建快照。请保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径之后。 常见注册方法： @@ -337,31 +370,33 @@ OpenClaw 会加载这个入口对象，并在插件激活期间调用 `register( | `registerImageGenerationProvider` | 图像生成 | | `registerMusicGenerationProvider` | 音乐生成 | | `registerVideoGenerationProvider` | 视频生成 | -| `registerWebFetchProvider` | 网页抓取 / 抓取提供商 | +| `registerWebFetchProvider` | 网页抓取 / 提取提供商 | | `registerWebSearchProvider` | 网页搜索 | | `registerHttpRoute` | HTTP 端点 | | `registerCommand` / `registerCli` | CLI 命令 | | `registerContextEngine` | 上下文引擎 | | `registerService` | 后台服务 | -带类型生命周期钩子的钩子保护行为： +类型化生命周期钩子的钩子保护行为： -- `before_tool_call`：`{ block: true }` 为终止结果；会跳过更低优先级的处理器。 -- `before_tool_call`：`{ block: false }` 是无操作，不会清除更早的拦截结果。 -- `before_install`：`{ block: true }` 为终止结果；会跳过更低优先级的处理器。 -- `before_install`：`{ block: false }` 是无操作，不会清除更早的拦截结果。 -- `message_sending`：`{ cancel: true }` 为终止结果；会跳过更低优先级的处理器。 -- `message_sending`：`{ cancel: false }` 是无操作，不会清除更早的取消结果。 +- `before_tool_call`：`{ block: true }` 为终止性结果；会跳过更低优先级的处理器。 +- `before_tool_call`：`{ block: false }` 为无操作，不会清除更早的 block。 +- `before_install`：`{ block: true }` 为终止性结果；会跳过更低优先级的处理器。 +- `before_install`：`{ block: false }` 为无操作，不会清除更早的 block。 +- `message_sending`：`{ cancel: true }` 为终止性结果；会跳过更低优先级的处理器。 +- `message_sending`：`{ cancel: false }` 为无操作，不会清除更早的 cancel。 -原生 Codex app-server 运行时会把 bridge Codex 原生工具事件回传到这个钩子表面。插件可以通过 `before_tool_call` 拦截原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。这个 bridge 目前还不会重写 Codex 原生工具参数。精确的 Codex 运行时支持边界定义在 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract) 中。 +原生 Codex app-server 会将桥接的 Codex 原生工具事件回传到这个钩子功能面。插件可以通过 `before_tool_call` 阻止原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex +`PermissionRequest` 审批。该桥接目前还不会重写 Codex 原生工具参数。确切的 Codex 运行时支持边界定义在 +[Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract) 中。 -有关完整的类型化钩子行为，请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。 +完整的类型化钩子行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。 ## 相关内容 - [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件 -- [Plugin Bundles](/zh-CN/plugins/bundles) — 与 Codex/Claude/Cursor bundle 的兼容性 -- [Plugin manifest](/zh-CN/plugins/manifest) — manifest schema +- [插件捆绑包](/zh-CN/plugins/bundles) — Codex / Claude / Cursor 捆绑包兼容性 +- [插件清单](/zh-CN/plugins/manifest) — 清单 schema - [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具 -- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流水线 -- [Community Plugins](/zh-CN/plugins/community) — 第三方列表 +- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型与加载流水线 +- [社区插件](/zh-CN/plugins/community) — 第三方列表