From 2374d3b0885c9eb0630b7fc77ee8a7e87665aedf Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 17:40:49 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/cli/plugins.md | 138 ++++---- docs/zh-CN/gateway/doctor.md | 484 ++++++++++++++-------------- docs/zh-CN/plugins/compatibility.md | 53 +-- docs/zh-CN/tools/plugin.md | 335 ++++++++----------- 4 files changed, 486 insertions(+), 524 deletions(-) diff --git a/docs/zh-CN/cli/plugins.md b/docs/zh-CN/cli/plugins.md index 5c8e426bd..9e1a1173b 100644 --- a/docs/zh-CN/cli/plugins.md +++ b/docs/zh-CN/cli/plugins.md @@ -1,14 +1,14 @@ --- read_when: - - 你想安装或管理 Gateway 网关插件或兼容的捆绑包 - - 你想调试插件加载失败问题 + - 你想要安装或管理 Gateway 网关插件或兼容的捆绑包 + - 你想要调试插件加载失败问题 summary: '`openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、doctor）' title: 插件 x-i18n: - generated_at: "2026-04-24T14:42:51Z" + generated_at: "2026-04-25T17:39:04Z" model: gpt-5.4 provider: openai - source_hash: bc693d5e3bc49057e1a108ba65a4dcb3bb662c00229e6fa38a0335afba8240e5 + source_hash: 2ae8f71873fb90dc7acde2ac522228cc60603ba34322e5b6d031e8de7545684e source_path: cli/plugins.md workflow: 15 --- @@ -38,6 +38,8 @@ openclaw plugins inspect --all openclaw plugins info openclaw plugins enable openclaw plugins disable +openclaw plugins registry +openclaw plugins registry --refresh openclaw plugins uninstall openclaw plugins doctor openclaw plugins update @@ -46,49 +48,49 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -内置插件随 OpenClaw 一起提供。其中一些默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）；其他则需要使用 `plugins enable`。 +内置插件会随 OpenClaw 一起提供。其中一些默认启用（例如内置模型提供商、内置语音提供商，以及内置浏览器插件）；另一些则需要运行 `plugins enable`。 -原生 OpenClaw 插件必须提供 `openclaw.plugin.json`，并内联 JSON Schema（`configSchema`，即使为空也需要）。兼容的捆绑包则使用它们自己的捆绑包清单。 +原生 OpenClaw 插件必须提供 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空也需要）。兼容捆绑包则改为使用它们自己的 bundle manifest。 -`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细的 list/info 输出还会显示捆绑包子类型（`codex`、`claude` 或 `cursor`）以及检测到的捆绑包能力。 +`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细 list/info 输出还会显示捆绑包子类型（`codex`、`claude` 或 `cursor`）以及检测到的捆绑包能力。 ### 安装 ```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 openclaw plugins install # 本地路径 openclaw plugins install @ # marketplace -openclaw plugins install --marketplace # marketplace（显式） +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 会以失败关闭的方式处理，而不会被扁平化。支持的形态见 [配置 includes](/zh-CN/gateway/configuration)。 +如果你的 `plugins` 部分由单文件 `$include` 提供支持，那么 `plugins install/update/enable/disable/uninstall` 会直接写入该被包含文件，而不会修改 `openclaw.json`。根级 include、include 数组，以及带有同级覆盖项的 include 都会以失败关闭的方式处理，而不会被展平。支持的形式见 [配置 includes](/zh-CN/gateway/configuration)。 -如果配置无效，`plugins install` 通常会以失败关闭的方式终止，并提示你先运行 `openclaw doctor --fix`。唯一有文档记录的例外是一个狭窄的内置插件恢复路径，仅适用于显式选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。 +如果配置无效，`plugins install` 通常会以失败关闭的方式终止，并提示你先运行 `openclaw doctor --fix`。唯一有文档说明的例外，是一条针对明确选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件的狭义内置插件恢复路径。 -`--force` 会复用现有安装目标，并就地覆盖已安装的插件或 hook 包。当你有意从新的本地路径、归档、ClawHub 包或 npm 构件重新安装同一 id 时，请使用它。对于已经被跟踪的 npm 插件的常规升级，优先使用 `openclaw plugins update `。 +`--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。 -`--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 标志适用于插件 install/update 流程。由 Gateway 网关支持的 Skills 依赖安装会使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖项，而 `openclaw skills install` 仍然是单独的 ClawHub Skills 下载/安装流程。 -`plugins install` 也是安装暴露了 `openclaw.hooks` 的 hook 包的安装入口，前提是它们在 `package.json` 中声明。使用 `openclaw hooks` 来查看经过筛选的 hook 可见性以及逐个 hook 启用情况，而不是用于安装包。 +`plugins install` 也是暴露 `openclaw.hooks` 于 `package.json` 中的 hook 包的安装入口。请使用 `openclaw hooks` 查看经过筛选的 hook 可见性以及按 hook 启用，而不是用于包安装。 -Npm spec **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。出于安全考虑，依赖安装使用 `--ignore-scripts` 运行。 +npm spec **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围都会被拒绝。出于安全考虑，依赖安装会使用 `--ignore-scripts` 运行。 -裸 spec 和 `@latest` 会保持在稳定通道。如果 npm 将其中任意一种解析为预发布版本，OpenClaw 会停止，并要求你显式选择加入，例如使用 `@beta`/`@rc` 这样的预发布标签，或使用 `@1.2.3-beta.4` 这样的精确预发布版本。 +裸 spec 和 `@latest` 会停留在稳定发布轨道上。如果 npm 将这两者中的任一解析为预发布版本，OpenClaw 会停止并要求你显式选择加入，例如使用 `@beta`/`@rc` 这样的预发布标签，或 `@1.2.3-beta.4` 这样的精确预发布版本。 -如果一个裸安装 spec 与内置插件 id 匹配（例如 `diffs`），OpenClaw 会直接安装该内置插件。若要安装同名的 npm 包，请使用显式的带作用域 spec（例如 `@scope/diffs`）。 +如果一个裸安装 spec 与某个内置插件 id 匹配（例如 `diffs`），OpenClaw 会直接安装该内置插件。若要安装同名 npm 包，请使用显式的带作用域 spec（例如 `@scope/diffs`）。 支持的归档格式：`.zip`、`.tgz`、`.tar.gz`、`.tar`。 @@ -101,22 +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 安全要求的裸插件 spec 也会优先使用 ClawHub。只有当 ClawHub 中没有该包或该版本时，它才会回退到 npm： ```bash openclaw plugins install openclaw-codex-app-server ``` -OpenClaw 会从 ClawHub 下载包归档，检查其声明的插件 API / 最低 Gateway 网关兼容性，然后通过常规归档路径完成安装。已记录的安装会保留其 ClawHub 来源元数据，以便后续更新。 +OpenClaw 会从 ClawHub 下载包归档，检查已声明的插件 API / 最低 Gateway 网关兼容性，然后通过常规归档路径安装。记录下来的安装会保留其 ClawHub 来源元数据，供后续更新使用。 -当 marketplace 名称存在于 Claude 的本地注册表缓存 `~/.claude/plugins/known_marketplaces.json` 中时，使用 `plugin@marketplace` 简写： +当 marketplace 名称存在于 Claude 的本地 registry 缓存 `~/.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,20 +131,20 @@ Marketplace 来源可以是： - `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知 marketplace 名称 - 本地 marketplace 根目录或 `marketplace.json` 路径 -- 类似 `owner/repo` 的 GitHub 仓库简写 -- 类似 `https://github.com/owner/repo` 的 GitHub 仓库 URL +- 形如 `owner/repo` 的 GitHub 仓库简写 +- 形如 `https://github.com/owner/repo` 的 GitHub 仓库 URL - git URL -对于通过 GitHub 或 git 加载的远程 marketplace，插件条目必须保留在克隆后的 marketplace 仓库内部。OpenClaw 接受来自该仓库的相对路径来源，并拒绝远程清单中的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径插件来源。 +对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保持在克隆得到的 marketplace 仓库内部。OpenClaw 接受来自该仓库的相对路径来源，并拒绝远程 manifest 中的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径类插件来源。 -对于本地路径和归档，OpenClaw 会自动检测： +对于本地路径和归档文件，OpenClaw 会自动检测： - 原生 OpenClaw 插件（`openclaw.plugin.json`） -- Codex 兼容捆绑包（`.codex-plugin/plugin.json`） -- Claude 兼容捆绑包（`.claude-plugin/plugin.json` 或默认 Claude 组件布局） -- Cursor 兼容捆绑包（`.cursor-plugin/plugin.json`） +- 与 Codex 兼容的捆绑包（`.codex-plugin/plugin.json`） +- 与 Claude 兼容的捆绑包（`.claude-plugin/plugin.json` 或默认的 Claude 组件布局） +- 与 Cursor 兼容的捆绑包（`.cursor-plugin/plugin.json`） -兼容的捆绑包会安装到常规插件根目录中，并参与相同的 list/info/enable/disable 流程。目前，支持捆绑包 Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录；其他检测到的捆绑包能力会显示在 diagnostics/info 中，但尚未接入运行时执行。 +兼容捆绑包会安装到常规插件根目录中，并参与相同的 list/info/enable/disable 流程。目前已支持 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / manifest 声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录；其他已检测到的捆绑包能力会显示在 diagnostics/info 中，但尚未接入运行时执行。 ### 列表 @@ -153,15 +155,15 @@ openclaw plugins list --verbose openclaw plugins list --json ``` -使用 `--enabled` 仅显示已加载的插件。使用 `--verbose` 可从表格视图切换为按插件显示的详细行，其中包含 source/origin/version/activation 元数据。使用 `--json` 可获取机器可读的清单和 registry diagnostics。 +使用 `--enabled` 仅显示已启用的插件。使用 `--verbose` 可从表格视图切换为逐插件详细信息行，展示 source/origin/version/activation 元数据。使用 `--json` 获取机器可读的清单以及 registry diagnostics。 -`plugins list` 会基于当前 CLI 环境和配置运行设备发现。它适合用于检查某个插件是否已启用/可加载，但它不是对已运行 Gateway 网关进程的实时运行时探测。在修改插件代码、启用状态、hook 策略或 `plugins.load.paths` 后，请重启为该渠道提供服务的 Gateway 网关，然后再期望新的 `register(api)` 代码或 hook 开始运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不仅仅是包装进程。 +`plugins list` 会先读取持久化的本地插件 registry；如果 registry 缺失或无效，则回退为仅基于 manifest 推导的结果。它适合用于检查某个插件是否已安装、已启用，以及在冷启动规划中是否可见，但它并不是对已运行 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、hook 策略或 `plugins.load.paths` 后，在期望新的 `register(api)` 代码或 hook 开始生效之前，请重启为该渠道提供服务的 Gateway 网关。对于远程/容器部署，请确认你重启的是真正的 `openclaw gateway run` 子进程，而不只是一个包装进程。 对于运行时 hook 调试： -- `openclaw plugins inspect --json` 会显示在模块加载检查过程中注册的 hook 和 diagnostics。 -- `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 和 diagnostics +- `openclaw gateway status --deep --require-rpc` 会确认可访问的 Gateway 网关、service/process 提示、配置路径和 RPC 健康状态 +- 非内置的对话 hook（`llm_input`、`llm_output`、`agent_end`）要求设置 `plugins.entries..hooks.allowConversationAccess=true` 使用 `--link` 可避免复制本地目录（会添加到 `plugins.load.paths`）： @@ -169,9 +171,9 @@ openclaw plugins list --json openclaw plugins install -l ./my-plugin ``` -`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是覆盖受管的安装目标。 +`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是复制到受管理的安装目标上。 -在 npm 安装时使用 `--pin`，可将解析后的精确 spec（`name@version`）保存到 `plugins.installs` 中，同时保留默认的不固定行为。 +在 npm 安装中使用 `--pin`，可将解析出的精确 spec（`name@version`）保存到 `plugins.installs`，同时保留默认行为的不固定版本模式。 ### 卸载 @@ -181,11 +183,11 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` 会从 `plugins.entries`、`plugins.installs`、插件 allowlist，以及适用时的已链接 `plugins.load.paths` 条目中移除插件记录。对于处于活动状态的 memory 插件，memory 槽位会重置为 `memory-core`。 +`uninstall` 会从 `plugins.entries`、`plugins.installs`、插件 allowlist，以及相关的已链接 `plugins.load.paths` 条目中删除插件记录。对于处于激活状态的 memory 插件，memory 插槽会重置为 `memory-core`。 -默认情况下，卸载还会删除活动 state-dir 插件根目录下的插件安装目录。使用 `--keep-files` 可以将文件保留在磁盘上。 +默认情况下，卸载还会删除活动 state-dir 插件根目录下的插件安装目录。使用 `--keep-files` 可保留磁盘上的文件。 -`--keep-config` 作为 `--keep-files` 的已弃用别名仍受支持。 +`--keep-config` 仍受支持，但作为 `--keep-files` 的已弃用别名。 ### 更新 @@ -197,19 +199,19 @@ openclaw plugins update @openclaw/voice-call@beta openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -更新适用于 `plugins.installs` 中被跟踪的安装，以及 `hooks.internal.installs` 中被跟踪的 hook 包安装。 +更新会应用于 `plugins.installs` 中已跟踪的安装，以及 `hooks.internal.installs` 中已跟踪的 hook 包安装。 -当你传入插件 id 时，OpenClaw 会复用该插件记录的安装 spec。这意味着之前保存的 dist-tag（如 `@beta`）和固定的精确版本，在后续 `update ` 运行时会继续被使用。 +当你传入插件 id 时，OpenClaw 会复用该插件记录下来的安装 spec。这意味着先前保存的 dist-tag（例如 `@beta`）和精确固定版本，在后续运行 `update ` 时仍会继续使用。 -对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会将该包名解析回被跟踪的插件记录，更新该已安装插件，并记录新的 npm spec，供未来基于 id 的更新使用。 +对于 npm 安装，你也可以传入带 dist-tag 或精确版本的显式 npm package spec。OpenClaw 会将该包名重新解析回已跟踪的插件记录，更新对应已安装插件，并为将来基于 id 的更新记录新的 npm spec。 -仅传入 npm 包名而不附带版本或标签，也会解析回被跟踪的插件记录。当某个插件被固定到精确版本，而你希望让它回到 registry 的默认发布线时，请使用这种方式。 +传入不带版本或标签的 npm 包名，也会重新解析回已跟踪的插件记录。当某个插件被固定到精确版本，而你想将其切回 registry 默认发布线时，可使用这种方式。 -在执行实际的 npm 更新之前，OpenClaw 会根据 npm registry 元数据检查已安装的包版本。如果已安装版本和已记录的构件标识已经与解析出的目标一致，则会跳过更新，不会下载、重新安装，也不会重写 `openclaw.json`。 +在执行实际 npm 更新之前，OpenClaw 会根据 npm registry 元数据检查已安装包版本。如果已安装版本和已记录的构件标识与解析出的目标已经一致，则会跳过更新，不会下载、重新安装，也不会改写 `openclaw.json`。 -当存在已存储的完整性哈希，而获取到的构件哈希发生变化时，OpenClaw 会将其视为 npm 构件漂移。交互式的 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新辅助工具会以失败关闭的方式终止，除非调用方提供显式的继续策略。 +当存在已存储的完整性哈希，而获取到的构件哈希发生变化时，OpenClaw 会将其视为 npm 构件漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续之前请求确认。非交互式更新辅助工具会以失败关闭的方式终止，除非调用方提供了显式的继续策略。 -`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的应急覆盖选项。它仍然不会绕过插件 `before_install` 策略拦截或扫描失败拦截，并且它仅适用于插件更新，不适用于 hook 包更新。 +`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为在插件更新期间应对内置危险代码扫描误报的破窗覆盖项。它仍然不会绕过插件 `before_install` 策略阻止或扫描失败阻止，并且它仅适用于插件更新，不适用于 hook 包更新。 ### 检查 @@ -218,20 +220,20 @@ openclaw plugins inspect openclaw plugins inspect --json ``` -针对单个插件的深度内省。会显示身份信息、加载状态、来源、已注册能力、hook、工具、命令、服务、Gateway 网关方法、HTTP 路由、策略标志、diagnostics、安装元数据、捆绑包能力，以及任何检测到的 MCP 或 LSP 服务器支持。 +针对单个插件的深度检查。会显示身份、加载状态、来源、已注册能力、hooks、工具、命令、服务、gateway 方法、HTTP 路由、策略标志、diagnostics、安装元数据、捆绑包能力，以及任何检测到的 MCP 或 LSP 服务器支持。 每个插件都会根据其在运行时实际注册的内容进行分类： -- **plain-capability** —— 一种能力类型（例如仅提供 provider 的插件） -- **hybrid-capability** —— 多种能力类型（例如文本 + 语音 + 图像） -- **hook-only** —— 只有 hook，没有能力或界面 -- **non-capability** —— 有工具/命令/服务，但没有能力 +- **plain-capability** — 一种能力类型（例如仅 provider 的插件） +- **hybrid-capability** — 多种能力类型（例如文本 + 语音 + 图像） +- **hook-only** — 只有 hooks，没有能力或其他 surface +- **non-capability** — 有工具/命令/服务，但没有能力 -有关能力模型的更多信息，请参见[插件形态](/zh-CN/plugins/architecture#plugin-shapes)。 +有关能力模型的更多信息，请参见 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。 -`--json` 标志会输出适合脚本和审计使用的机器可读报告。 +`--json` 标志会输出适合脚本处理和审计的机器可读报告。 -`inspect --all` 会渲染一个全局表格，其中包含 shape、capability kinds、兼容性提示、捆绑包能力和 hook 摘要列。 +`inspect --all` 会渲染一个面向整个插件集合的表格，其中包含 shape、capability kinds、兼容性提示、捆绑包能力和 hook 摘要列。 `info` 是 `inspect` 的别名。 @@ -241,9 +243,23 @@ openclaw plugins inspect --json openclaw plugins doctor ``` -`doctor` 会报告插件加载错误、清单/设备发现 diagnostics，以及兼容性提示。当一切正常时，它会打印 `No plugin issues detected.`。 +`doctor` 会报告插件加载错误、manifest/设备发现 diagnostics，以及兼容性提示。当一切正常时，它会打印 `No plugin issues detected.`。 -对于诸如缺少 `register`/`activate` 导出之类的模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以在诊断输出中包含紧凑的导出形态摘要。 +对于缺少 `register`/`activate` 导出之类的模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以便在诊断输出中包含紧凑的导出形态摘要。 + +### Registry + +```bash +openclaw plugins registry +openclaw plugins registry --refresh +openclaw plugins registry --json +``` + +本地插件 registry 是 OpenClaw 针对已安装插件身份、启用状态、来源元数据和贡献归属关系的持久化冷读取模型。正常启动、provider 所有者查找、渠道设置分类以及插件清单都可以在不导入插件运行时模块的情况下读取它。 + +使用 `plugins registry` 可检查持久化 registry 是否存在、是否为最新，或是否已过期。使用 `--refresh` 可根据持久化安装账本、配置策略以及 manifest/package 元数据重建它。这是一条修复路径，而不是运行时激活路径。 + +`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是一个已弃用的破窗兼容性开关，用于处理 registry 读取失败。更推荐使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；这个环境变量回退仅用于迁移发布期间的紧急启动恢复。 ### Marketplace @@ -252,7 +268,7 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Marketplace list 接受本地 marketplace 路径、`marketplace.json` 路径、像 `owner/repo` 这样的 GitHub 简写、GitHub 仓库 URL 或 git URL。`--json` 会打印已解析的来源标签，以及解析后的 marketplace 清单和插件条目。 +Marketplace list 接受本地 marketplace 路径、`marketplace.json` 路径、形如 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL 或 git URL。`--json` 会打印解析后的来源标签，以及已解析的 marketplace manifest 和插件条目。 ## 相关内容 diff --git a/docs/zh-CN/gateway/doctor.md b/docs/zh-CN/gateway/doctor.md index 3fc0c1262..5bc9d2bc0 100644 --- a/docs/zh-CN/gateway/doctor.md +++ b/docs/zh-CN/gateway/doctor.md @@ -1,19 +1,19 @@ --- read_when: - - 添加或修改 doctor 迁移 + - 添加或修改 Doctor 迁移 - 引入破坏性配置更改 -summary: Doctor 命令：健康检查、配置迁移和修复步骤 +summary: Doctor 命令：运行状况检查、配置迁移和修复步骤 title: Doctor x-i18n: - generated_at: "2026-04-25T05:01:40Z" + generated_at: "2026-04-25T17:39:05Z" model: gpt-5.4 provider: openai - source_hash: 05063983a5ffd9dc117a8135f76519941c28d30778d6ecbaa3f276a5fd4fce46 + source_hash: 13204a57facd19459fc812a8daa0fe629b6725bdabb014f59f871fa64c22e71d source_path: gateway/doctor.md workflow: 15 --- -`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复陈旧的配置/状态，检查健康状况，并提供可执行的修复步骤。 +`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过期的配置/状态，检查运行状况，并提供可执行的修复步骤。 ## 快速开始 @@ -21,19 +21,19 @@ x-i18n: openclaw doctor ``` -### 无头模式 / 自动化 +### 无头 / 自动化 ```bash openclaw doctor --yes ``` -接受默认值而不提示（包括在适用时的重启/服务/沙箱修复步骤）。 +接受默认值而不进行提示（包括在适用时的重启/服务/沙箱修复步骤）。 ```bash openclaw doctor --repair ``` -无需提示即可应用建议的修复（在安全情况下执行修复 + 重启）。 +应用建议的修复而不提示（在安全情况下执行修复 + 重启）。 ```bash openclaw doctor --repair --force @@ -45,8 +45,8 @@ openclaw doctor --repair --force openclaw doctor --non-interactive ``` -在无提示的情况下运行，并且只应用安全迁移（配置规范化 + 磁盘上的状态移动）。跳过需要人工确认的重启/服务/沙箱操作。 -检测到旧版状态迁移时会自动运行。 +在不提示的情况下运行，并且只应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。 +检测到旧状态迁移时会自动运行。 ```bash openclaw doctor --deep @@ -54,97 +54,96 @@ openclaw doctor --deep 扫描系统服务以查找额外的 Gateway 网关安装（`launchd`/`systemd`/`schtasks`）。 -如果你想在写入前先查看更改，请先打开配置文件： +如果你想在写入之前先查看更改，请先打开配置文件： ```bash cat ~/.openclaw/openclaw.json ``` -## 它会做什么（摘要） +## 它会执行什么（摘要） - 针对 git 安装的可选飞行前更新（仅交互模式）。 -- UI 协议新鲜度检查（当协议 schema 更新时重新构建 Control UI）。 -- 健康检查 + 重启提示。 -- Skills 状态摘要（符合条件/缺失/被阻止）和插件状态。 -- 针对旧版值的配置规范化。 -- 将旧版扁平 `talk.*` 字段迁移为 `talk.provider` + `talk.providers.` 的 Talk 配置迁移。 +- UI 协议新鲜度检查（当协议 schema 更新时重建 Control UI）。 +- 运行状况检查 + 重启提示。 +- Skills 状态摘要（可用/缺失/受阻）和插件状态。 +- 针对旧值的配置规范化。 +- 将旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.` 的 Talk 配置迁移。 - 针对旧版 Chrome 扩展配置和 Chrome MCP 就绪情况的浏览器迁移检查。 - OpenCode 提供商覆盖警告（`models.providers.opencode` / `models.providers.opencode-go`）。 -- Codex OAuth 屏蔽警告（`models.providers.openai-codex`）。 -- 针对 OpenAI Codex OAuth 配置文件的 OAuth TLS 前置条件检查。 +- Codex OAuth 遮蔽警告（`models.providers.openai-codex`）。 +- OpenAI Codex OAuth 配置文件的 OAuth TLS 前置条件检查。 - 旧版磁盘状态迁移（会话/智能体目录/WhatsApp 认证）。 -- 旧版插件 manifest 合同键迁移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。 -- 旧版 cron 存储迁移（`jobId`、`schedule.cron`、顶层 delivery/payload 字段、payload `provider`、简单的 `notify: true` webhook 回退任务）。 -- 会话锁文件检查和陈旧锁清理。 +- 旧版插件清单契约键迁移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。 +- 旧版 cron 存储迁移（`jobId`、`schedule.cron`、顶层 `delivery`/`payload` 字段、`payload.provider`、简单的 `notify: true` webhook 回退任务）。 +- 会话锁文件检查和过期锁清理。 - 状态完整性和权限检查（会话、转录记录、状态目录）。 -- 在本地运行时检查配置文件权限（`chmod 600`）。 -- 模型认证健康检查：检查 OAuth 过期情况，可刷新即将过期的令牌，并报告认证配置文件的冷却/禁用状态。 +- 本地运行时的配置文件权限检查（`chmod 600`）。 +- 模型认证运行状况：检查 OAuth 过期情况，可刷新即将过期的令牌，并报告 auth-profile 冷却/禁用状态。 - 额外工作区目录检测（`~/openclaw`）。 -- 在启用沙箱隔离时执行沙箱镜像修复。 +- 启用沙箱隔离时的沙箱镜像修复。 - 旧版服务迁移和额外 Gateway 网关检测。 -- Matrix 渠道旧版状态迁移（在 `--fix` / `--repair` 模式下）。 -- Gateway 网关运行时检查（服务已安装但未运行；缓存的 `launchd` 标签）。 -- 渠道状态警告（从运行中的 Gateway 网关探测）。 -- supervisor 配置审计（`launchd`/`systemd`/`schtasks`），可选修复。 +- Matrix 渠道旧状态迁移（在 `--fix` / `--repair` 模式下）。 +- Gateway 网关运行时检查（已安装服务但未运行；缓存的 `launchd` 标签）。 +- 渠道状态警告（从正在运行的 Gateway 网关探测）。 +- supervisor 配置审计（`launchd`/`systemd`/`schtasks`），可选择修复。 - Gateway 网关运行时最佳实践检查（Node 与 Bun、版本管理器路径）。 - Gateway 网关端口冲突诊断（默认 `18789`）。 -- 针对开放私信策略的安全警告。 -- 针对本地令牌模式的 Gateway 网关认证检查（当不存在令牌来源时提供令牌生成功能；不会覆盖令牌 `SecretRef` 配置）。 -- 设备配对问题检测（首次配对请求待处理、角色/作用域升级待处理、陈旧的本地 device-token 缓存漂移，以及已配对记录的认证漂移）。 +- 面向开放私信策略的安全警告。 +- 本地令牌模式的 Gateway 网关认证检查（在没有令牌来源时提供生成令牌；不会覆盖令牌 `SecretRef` 配置）。 +- 设备配对问题检测（首次配对请求待处理、角色/作用域升级待处理、过期的本地设备令牌缓存漂移，以及已配对记录的认证漂移）。 - Linux 上的 `systemd linger` 检查。 -- 工作区 bootstrap 文件大小检查（针对上下文文件的截断/接近上限警告）。 -- shell 补全状态检查和自动安装/升级。 -- Memory 搜索嵌入提供商就绪检查（本地模型、远程 API 密钥或 QMD 二进制文件）。 -- 源码安装检查（`pnpm` 工作区不匹配、缺失的 UI 资源、缺失的 `tsx` 二进制文件）。 +- 工作区引导文件大小检查（针对上下文文件的截断/接近限制警告）。 +- Shell 自动补全状态检查以及自动安装/升级。 +- Memory 搜索嵌入提供商就绪情况检查（本地模型、远程 API 密钥或 QMD 二进制文件）。 +- 源码安装检查（`pnpm` 工作区不匹配、缺失 UI 资源、缺失 `tsx` 二进制文件）。 - 写入更新后的配置 + 向导元数据。 ## Dreams UI 回填和重置 Control UI 的 Dreams 场景包含 **Backfill**、**Reset** 和 **Clear Grounded** -操作，用于 grounded dreaming 工作流。这些操作使用 Gateway 网关 -的 doctor 风格 RPC 方法，但它们**不是** `openclaw doctor` CLI +操作，用于 grounded dreaming 工作流。这些操作使用 Gateway 网关风格的 +doctor RPC 方法，但它们**不是** `openclaw doctor` CLI 修复/迁移的一部分。 它们的作用： -- **Backfill** 会扫描活动工作区中的历史 `memory/YYYY-MM-DD.md` 文件， - 运行 grounded REM diary 流程，并将可逆的回填条目写入 `DREAMS.md`。 -- **Reset** 仅从 `DREAMS.md` 中移除那些带标记的回填 diary 条目。 -- **Clear Grounded** 仅移除那些来自历史回放、且尚未积累实时召回或每日支持的 - staged grounded-only 短期条目。 +- **Backfill** 会扫描当前工作区中的历史 `memory/YYYY-MM-DD.md` 文件， + 运行 grounded REM 日记流程，并将可逆的回填条目写入 `DREAMS.md`。 +- **Reset** 仅从 `DREAMS.md` 中删除这些已标记的回填日记条目。 +- **Clear Grounded** 仅删除那些来自历史回放、且尚未累积实时 recall 或每日 + supporting 的 staged grounded-only 短期条目。 -它们**不会**自行执行的操作： +它们**不会**自行执行的事情： -- 不会编辑 `MEMORY.md` -- 不会运行完整的 doctor 迁移 -- 不会自动将 grounded 候选项暂存到实时短期提升存储中， - 除非你先显式运行 staged CLI 路径 +- 它们不会编辑 `MEMORY.md` +- 它们不会运行完整的 Doctor 迁移 +- 除非你先显式运行 staged CLI 路径，否则它们不会自动将 grounded 候选项 + 放入实时短期提升存储中 -如果你希望 grounded 历史回放影响正常的深度提升 -通道，请改用 CLI 流程： +如果你希望 grounded 历史回放影响正常的深度提升通道，请改用 CLI 流程： ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -这会将 grounded 的持久候选项暂存到短期 dreaming 存储中，同时 -保留 `DREAMS.md` 作为审查界面。 +这会将 grounded 持久候选项放入短期 dreaming 存储中，同时把 `DREAMS.md` +保留为审查界面。 -## 详细行为和原理 +## 详细行为和原因说明 ### 0）可选更新（git 安装） -如果这是一个 git 检出，并且 doctor 以交互模式运行，它会在运行 doctor 之前 -提供更新（fetch/rebase/build）的选项。 +如果这是一个 git 检出，并且 Doctor 以交互模式运行，它会先提供 +更新（fetch/rebase/build），然后再运行 Doctor。 ### 1）配置规范化 如果配置包含旧版值结构（例如 `messages.ackReaction` -没有特定于渠道的覆盖），doctor 会将它们规范化为当前 +没有渠道特定覆盖），Doctor 会将其规范化为当前 schema。 这也包括旧版 Talk 扁平字段。当前公开的 Talk 配置是 -`talk.provider` + `talk.providers.`。Doctor 会将旧的 +`talk.provider` + `talk.providers.`。Doctor 会把旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 结构重写到 provider 映射中。 @@ -153,14 +152,14 @@ schema。 当配置包含已弃用的键时，其他命令会拒绝运行，并要求 你运行 `openclaw doctor`。 -Doctor 将会： +Doctor 会： -- 解释发现了哪些旧版键。 -- 显示它应用的迁移。 +- 说明找到了哪些旧版键。 +- 展示它应用的迁移。 - 使用更新后的 schema 重写 `~/.openclaw/openclaw.json`。 -当 Gateway 网关在启动时检测到旧版配置格式，也会自动运行 doctor -迁移，因此陈旧配置无需人工干预即可修复。 +Gateway 网关在启动时如果检测到旧版配置格式，也会自动运行 Doctor 迁移， +因此过期配置无需手动干预即可修复。 Cron 任务存储迁移由 `openclaw doctor --fix` 处理。 当前迁移包括： @@ -187,85 +186,84 @@ Cron 任务存储迁移由 `openclaw doctor --fix` 处理。 - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` -- 对于具有命名 `accounts`、但仍残留单账户顶层渠道值的渠道， - 将这些账户作用域的值移动到为该渠道选定的提升账户中（大多数渠道使用 `accounts.default`； - Matrix 可以保留现有匹配的命名/默认目标） +- 对于配置了具名 `accounts` 但仍保留单账户顶层渠道值的渠道，将这些账户范围的值移动到为该渠道选定的提升账户中（大多数渠道使用 `accounts.default`；Matrix 可以保留现有匹配的具名/默认目标） - `identity` → `agents.list[].identity` -- `agent.*` → `agents.defaults` + `tools.*`（tools/elevated/exec/sandbox/subagents） +- `agent.*` → `agents.defaults` + `tools.*`（`tools`/`elevated`/`exec`/`sandbox`/`subagents`） - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` -- 删除 `browser.relayBindHost`（旧版扩展 relay 设置） +- 移除 `browser.relayBindHost`（旧版扩展 relay 设置） -Doctor 警告还包括针对多账户渠道的账户默认值指导： +Doctor 警告还包括针对多账户渠道的账户默认值指引： -- 如果配置了两个或更多 `channels..accounts` 条目，但没有 `channels..defaultAccount` 或 `accounts.default`，doctor 会警告回退路由可能会选择意外的账户。 -- 如果 `channels..defaultAccount` 被设置为未知账户 ID，doctor 会发出警告并列出已配置的账户 ID。 +- 如果配置了两个或更多 `channels..accounts` 条目，但没有设置 `channels..defaultAccount` 或 `accounts.default`，Doctor 会警告回退路由可能会选中意料之外的账户。 +- 如果 `channels..defaultAccount` 被设置为未知账户 ID，Doctor 会发出警告并列出已配置的账户 ID。 ### 2b）OpenCode 提供商覆盖 如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`， 它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。 -这可能会把模型强制路由到错误的 API，或者把成本清零。Doctor 会发出警告， -以便你移除该覆盖并恢复按模型路由 API + 成本。 +这可能会把模型强制路由到错误的 API，或者让成本变成 0。Doctor 会发出警告， +以便你移除该覆盖并恢复按模型的 API 路由 + 成本。 ### 2c）浏览器迁移和 Chrome MCP 就绪情况 -如果你的浏览器配置仍然指向已移除的 Chrome 扩展路径，doctor 会 +如果你的浏览器配置仍指向已移除的 Chrome 扩展路径，Doctor 会 将其规范化为当前的主机本地 Chrome MCP 附加模型： -- `browser.profiles.*.driver: "extension"` 变为 `"existing-session"` -- 删除 `browser.relayBindHost` +- `browser.profiles.*.driver: "extension"` 会变为 `"existing-session"` +- `browser.relayBindHost` 会被移除 当你使用 `defaultProfile: "user"` 或已配置的 `existing-session` 配置文件时， -doctor 还会审计主机本地 Chrome MCP 路径： +Doctor 还会审计主机本地 Chrome MCP 路径： -- 检查同一主机上是否安装了 Google Chrome，以支持默认 +- 检查 Google Chrome 是否安装在同一主机上，用于默认 自动连接配置文件 -- 检查检测到的 Chrome 版本，并在低于 Chrome 144 时发出警告 +- 检查检测到的 Chrome 版本，并在其低于 Chrome 144 时发出警告 - 提醒你在浏览器 inspect 页面中启用远程调试（例如 - `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging`， + `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging` 或 `edge://inspect/#remote-debugging`） Doctor 不能替你启用 Chrome 侧设置。主机本地 Chrome MCP -仍然需要： +仍然要求： -- Gateway 网关/节点主机上存在 Chromium 内核浏览器 144+ +- Gateway 网关/节点主机上安装 Chromium 内核浏览器 144+ - 浏览器在本地运行 - 在该浏览器中启用远程调试 - 在浏览器中批准首次附加同意提示 这里的就绪情况仅涉及本地附加前置条件。`existing-session` 会保留 -当前 Chrome MCP 路由限制；像 `responsebody`、PDF 导出、下载拦截以及批量操作等高级路由， -仍然需要托管浏览器或原始 CDP 配置文件。 +当前 Chrome MCP 路由限制；像 `responsebody`、PDF 导出、 +下载拦截和批量操作这类高级路由，仍然需要托管浏览器 +或原始 CDP 配置文件。 -此检查**不**适用于 Docker、沙箱、remote-browser 或其他无头流程。 -这些流程仍然使用原始 CDP。 +此检查**不**适用于 Docker、沙箱、remote-browser 或其他 +无头流程。那些流程会继续使用原始 CDP。 ### 2d）OAuth TLS 前置条件 -当配置了 OpenAI Codex OAuth 配置文件时，doctor 会探测 OpenAI -授权端点，以验证本地 Node/OpenSSL TLS 堆栈能否 +当配置了 OpenAI Codex OAuth 配置文件时，Doctor 会探测 OpenAI +授权端点，以验证本地 Node/OpenSSL TLS 栈是否能够 校验证书链。如果探测因证书错误而失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书）， -doctor 会输出特定于平台的修复指导。在 macOS 上使用 Homebrew 安装的 Node 时， -修复通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 -Gateway 网关健康，该探测也会运行。 +Doctor 会打印针对平台的修复指引。在 macOS 上使用 Homebrew 安装的 Node 时， +修复方式通常是 `brew postinstall ca-certificates`。使用 `--deep` 时， +即使 Gateway 网关处于健康状态，此探测也会运行。 ### 2c）Codex OAuth 提供商覆盖 如果你之前在 -`models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会屏蔽 -较新版本自动使用的内置 Codex OAuth -提供商路径。当 doctor 看到这些旧传输设置与 Codex OAuth 同时存在时，会发出警告， -以便你删除或重写陈旧的传输覆盖， -并恢复内置的路由/回退行为。自定义代理和仅 header 的覆盖仍受支持， +`models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置， +它们可能会遮蔽较新版本自动使用的内置 Codex OAuth +提供商路径。Doctor 在看到这些旧传输设置与 Codex OAuth +同时存在时会发出警告，这样你就可以删除或重写过期的传输覆盖， +并恢复内置的路由/回退行为。自定义代理和仅 header 的覆盖仍然受支持， 不会触发此警告。 ### 3）旧版状态迁移（磁盘布局） -Doctor 可以将旧的磁盘布局迁移到当前结构： +Doctor 可以将旧版磁盘布局迁移到当前结构： - 会话存储 + 转录记录： - 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents//sessions/` @@ -275,62 +273,61 @@ Doctor 可以将旧的磁盘布局迁移到当前结构： - 从旧版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外） - 到 `~/.openclaw/credentials/whatsapp//...`（默认账户 ID：`default`） -这些迁移采用尽力而为且幂等的方式；当 -仍保留任何旧版文件夹作为备份时，doctor 会发出警告。Gateway 网关/CLI 也会在启动时自动迁移 -旧版会话 + 智能体目录，因此历史记录/认证/模型会落到 -每个智能体的路径中，而无需手动运行 doctor。WhatsApp 认证则特意仅通过 +这些迁移会尽力而为且具备幂等性；如果留下任何旧版文件夹作为备份， +Doctor 会发出警告。Gateway 网关/CLI 在启动时也会自动迁移 +旧版会话 + 智能体目录，因此历史记录/认证/模型会进入 +按智能体划分的路径，而无需手动运行 Doctor。WhatsApp 认证则有意只通过 `openclaw doctor` 迁移。Talk provider/provider-map 规范化现在 -通过结构相等性进行比较，因此仅键顺序不同不再触发重复的无操作 -`doctor --fix` 更改。 +按结构相等性比较，因此仅键顺序不同的差异不再触发重复的无操作 +`doctor --fix` 变更。 -### 3a）旧版插件 manifest 迁移 +### 3a）旧版插件清单迁移 -Doctor 会扫描所有已安装插件的 manifest，查找已弃用的顶层能力 +Doctor 会扫描所有已安装插件清单中已弃用的顶层能力 键（`speechProviders`、`realtimeTranscriptionProviders`、 `realtimeVoiceProviders`、`mediaUnderstandingProviders`、 `imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、 -`webSearchProviders`）。发现后，它会提供将其移动到 `contracts` -对象并原地重写 manifest 文件的选项。此迁移是幂等的； +`webSearchProviders`）。找到后，它会提供将它们移动到 `contracts` +对象中并原地重写清单文件的选项。此迁移具备幂等性； 如果 `contracts` 键已经包含相同的值，则会移除旧版键， 而不会重复数据。 ### 3b）旧版 cron 存储迁移 Doctor 还会检查 cron 任务存储（默认是 `~/.openclaw/cron/jobs.json`， -或者在覆盖时使用 `cron.store`）中调度器仍为兼容性 -接受的旧任务结构。 +或者在覆盖时使用 `cron.store`）中调度器仍为兼容性而接受的旧任务结构。 -当前 cron 清理包括： +当前的 cron 清理包括： - `jobId` → `id` - `schedule.cron` → `schedule.expr` - 顶层 payload 字段（`message`、`model`、`thinking`、...）→ `payload` - 顶层 delivery 字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery` - payload `provider` delivery 别名 → 显式 `delivery.channel` -- 简单旧版 `notify: true` webhook 回退任务 → 显式 `delivery.mode="webhook"` 并设置 `delivery.to=cron.webhook` +- 简单旧版 `notify: true` webhook 回退任务 → 显式 `delivery.mode="webhook"`，并设置 `delivery.to=cron.webhook` -Doctor 仅会在能够做到 -不改变行为时，自动迁移 `notify: true` 任务。如果某个任务将旧版 notify 回退与现有 -非 webhook delivery 模式组合使用，doctor 会发出警告，并将该任务留待人工审查。 +Doctor 只会在能够做到而不改变行为时，自动迁移 `notify: true` +任务。如果某个任务将旧版通知回退与现有 +非 webhook 传递模式组合在一起，Doctor 会发出警告，并将该任务留给人工审查。 ### 3c）会话锁清理 -Doctor 会扫描每个智能体会话目录中的陈旧写锁文件——即会话异常退出后 -遗留下来的文件。对于找到的每个锁文件，它会报告： -路径、PID、该 PID 是否仍存活、锁年龄，以及它是否 -被视为陈旧（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` -模式下，它会自动移除陈旧锁文件；否则它会输出说明，并 -指示你使用 `--fix` 重新运行。 +Doctor 会扫描每个智能体会话目录中的过期写锁文件——这些文件是会话异常退出时 +留下的。对于找到的每个锁文件，它会报告： +路径、PID、该 PID 是否仍然存活、锁年龄，以及它是否 +被视为过期（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` +模式下，它会自动删除过期锁文件；否则它会打印说明， +并指示你使用 `--fix` 重新运行。 -### 4）状态完整性检查（会话持久化、路由和安全性） +### 4）状态完整性检查（会话持久化、路由和安全） -状态目录是运行层面的核心。如果它消失了，你会丢失 -会话、凭证、日志和配置（除非你在其他地方有备份）。 +状态目录是运行层面的中枢。如果它消失了，你会失去 +会话、凭证、日志和配置（除非你在别处有备份）。 Doctor 会检查： - **状态目录缺失**：警告灾难性的状态丢失，提示重新创建 - 该目录，并提醒你它无法恢复缺失的数据。 + 目录，并提醒你它无法恢复缺失的数据。 - **状态目录权限**：验证可写性；提供修复权限的选项 （并在检测到所有者/组不匹配时给出 `chown` 提示）。 - **macOS 云同步状态目录**：当状态路径解析到 iCloud Drive @@ -338,254 +335,255 @@ Doctor 会检查： `~/Library/CloudStorage/...` 下时发出警告，因为基于同步的路径可能导致更慢的 I/O 以及锁/同步竞争。 - **Linux SD 或 eMMC 状态目录**：当状态路径解析到 `mmcblk*` - 挂载源时发出警告，因为基于 SD 或 eMMC 的随机 I/O 在会话和凭证写入场景下 - 可能更慢且磨损更快。 + 挂载源时发出警告，因为基于 SD 或 eMMC 的随机 I/O 在会话和凭证写入场景下可能更慢， + 且磨损更快。 - **会话目录缺失**：`sessions/` 和会话存储目录 是持久化历史记录并避免 `ENOENT` 崩溃所必需的。 -- **转录记录不匹配**：当最近的会话条目缺少 +- **转录记录不匹配**：当最近的会话条目存在缺失的 转录文件时发出警告。 -- **主会话“单行 JSONL”**：当主转录记录只有一行时标记 - （说明历史记录未在累积）。 -- **多个状态目录**：当多个 `~/.openclaw` 文件夹存在于不同 - 主目录中，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告 - （历史记录可能在多个安装之间分裂）。 -- **远程模式提醒**：如果 `gateway.mode=remote`，doctor 会提醒你在 +- **主会话“单行 JSONL”**：当主转录文件只有一行时发出标记 + （历史记录没有累积）。 +- **多个状态目录**：当不同 home 目录下存在多个 `~/.openclaw` + 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告 + （历史记录可能在不同安装之间分裂）。 +- **远程模式提醒**：如果 `gateway.mode=remote`，Doctor 会提醒你在 远程主机上运行它（状态存储在那里）。 - **配置文件权限**：如果 `~/.openclaw/openclaw.json` 对 - 组/其他用户可读，则发出警告，并提供收紧到 `600` 的选项。 + 组/全体用户可读，则发出警告，并提供收紧到 `600` 的选项。 -### 5）模型认证健康状况（OAuth 过期） +### 5）模型认证运行状况（OAuth 过期） -Doctor 会检查认证存储中的 OAuth 配置文件，在令牌 -即将过期/已过期时发出警告，并在安全时进行刷新。如果 Anthropic +Doctor 会检查 auth 存储中的 OAuth 配置文件，在令牌 +即将过期/已过期时发出警告，并在安全时执行刷新。如果 Anthropic OAuth/令牌配置文件已过期，它会建议使用 Anthropic API 密钥或 Anthropic setup-token 路径。 -刷新提示仅在交互模式（TTY）下出现；`--non-interactive` +只有在交互模式（TTY）下运行时才会出现刷新提示；`--non-interactive` 会跳过刷新尝试。 当 OAuth 刷新永久失败时（例如 `refresh_token_reused`、 -`invalid_grant`，或者提供商要求你重新登录），doctor 会报告 -需要重新认证，并输出确切的 `openclaw models auth login --provider ...` -命令供你运行。 +`invalid_grant`，或提供商要求你重新登录），Doctor 会报告 +需要重新认证，并打印需要运行的精确 +`openclaw models auth login --provider ...` +命令。 -Doctor 还会报告由于以下原因而暂时不可用的认证配置文件： +Doctor 还会报告因以下原因而暂时不可用的 auth 配置文件： -- 短时冷却（限流/超时/认证失败） -- 较长时间的禁用（账单/额度失败） +- 短暂冷却（速率限制/超时/认证失败） +- 更长时间的禁用（计费/额度失败） ### 6）Hooks 模型验证 -如果设置了 `hooks.gmail.model`，doctor 会根据目录和 allowlist -验证模型引用，并在模型无法解析或不被允许时发出警告。 +如果设置了 `hooks.gmail.model`，Doctor 会根据 +目录和 allowlist 验证该模型引用，并在其无法解析或不被允许时发出警告。 ### 7）沙箱镜像修复 -启用沙箱隔离时，doctor 会检查 Docker 镜像，并在当前镜像缺失时 +启用沙箱隔离时，Doctor 会检查 Docker 镜像，并在当前镜像缺失时 提供构建或切换到旧版名称的选项。 ### 7b）内置插件运行时依赖 -Doctor 仅会为当前配置中激活的、 -或由其内置 manifest 默认启用的内置插件验证运行时依赖，例如 +Doctor 仅验证当前配置中处于激活状态，或由其内置清单默认启用的 +内置插件的运行时依赖，例如 `plugins.entries.discord.enabled: true`、旧版 `channels.discord.enabled: true`，或默认启用的内置提供商。如果有任何依赖缺失， -doctor 会报告相关包，并在 +Doctor 会报告这些包，并在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下安装它们。外部插件仍然 -使用 `openclaw plugins install` / `openclaw plugins update`；doctor 不会 +使用 `openclaw plugins install` / `openclaw plugins update`；Doctor 不会 为任意插件路径安装依赖。 -Gateway 网关和本地 CLI 还可以在导入内置插件之前， -按需修复激活的内置插件运行时依赖。这些安装 -限定在插件运行时安装根目录中，安装时禁用 scripts，不写入 -package lock，并且受安装根锁保护，因此并发的 CLI +Gateway 网关和本地 CLI 也可以在导入某个内置插件之前， +按需修复处于激活状态的内置插件运行时依赖。这些安装 +限定在插件运行时安装根目录内，运行时禁用脚本，不会 +写入 package lock，并且受安装根锁保护，因此并发的 CLI 或 Gateway 网关启动不会同时修改同一棵 `node_modules` 树。 ### 8）Gateway 网关服务迁移和清理提示 Doctor 会检测旧版 Gateway 网关服务（`launchd`/`systemd`/`schtasks`），并 -提供移除它们、并使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。 -它还可以扫描额外的类 Gateway 网关服务，并输出清理提示。 -带 profile 名称的 OpenClaw Gateway 网关服务被视为一等支持对象，不会 -被标记为“额外”服务。 +提供移除它们和使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。 +它还可以扫描额外的类似 Gateway 网关服务，并打印清理提示。 +带有配置文件名称的 OpenClaw Gateway 网关服务被视为一等公民，不会 +被标记为“额外”。 ### 8b）启动 Matrix 迁移 -当 Matrix 渠道账户存在待处理或可执行的旧版状态迁移时， -doctor（在 `--fix` / `--repair` 模式下）会先创建迁移前快照，然后 +当某个 Matrix 渠道账户存在待处理或可执行的旧版状态迁移时， +Doctor（在 `--fix` / `--repair` 模式下）会先创建迁移前快照，然后 运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版 -加密状态准备。这两个步骤都是非致命的；错误会被记录，启动仍会继续。 +加密状态准备。这两个步骤都不是致命的；错误会被记录，且启动会继续。 在只读模式下（不带 `--fix` 的 `openclaw doctor`），此检查 会被完全跳过。 ### 8c）设备配对和认证漂移 -Doctor 现在会把设备配对状态作为正常健康检查的一部分进行检查。 +Doctor 现在会在常规运行状况检查中检查设备配对状态。 -它会报告： +它会报告的内容： -- 首次配对请求待处理 -- 已配对设备的角色升级待处理 -- 已配对设备的作用域升级待处理 -- 公钥不匹配修复：设备 ID 仍匹配，但设备 - 身份不再与已批准记录匹配 -- 已配对记录缺少适用于已批准角色的活动令牌 +- 待处理的首次配对请求 +- 已配对设备的待处理角色升级 +- 已配对设备的待处理作用域升级 +- 公钥不匹配修复：设备 ID 仍然匹配，但设备 + 身份已不再与已批准记录匹配 +- 已配对记录中缺少已批准角色的活动令牌 - 已配对令牌的作用域漂移到已批准配对基线之外 -- 当前机器的本地缓存 device-token 条目早于 - Gateway 网关侧令牌轮换，或携带陈旧的作用域元数据 +- 当前机器上的本地缓存设备令牌条目，若其早于 + Gateway 网关侧令牌轮换，或带有过期作用域元数据 Doctor 不会自动批准配对请求，也不会自动轮换设备令牌。它 -会直接输出准确的下一步： +只会打印精确的下一步操作： - 使用 `openclaw devices list` 检查待处理请求 -- 使用 `openclaw devices approve ` 批准确切请求 +- 使用 `openclaw devices approve ` 批准准确的请求 - 使用 `openclaw devices rotate --device --role ` 轮换新令牌 -- 使用 `openclaw devices remove ` 删除并重新批准陈旧记录 +- 使用 `openclaw devices remove ` 删除并重新批准过期记录 -这解决了常见的“明明已配对却仍提示需要配对” -漏洞：doctor 现在可以区分首次配对、待处理的角色/作用域 -升级，以及陈旧令牌/设备身份漂移。 +这填补了常见的“已经配对，但仍然收到需要配对提示” +漏洞：Doctor 现在能够区分首次配对、待处理的角色/作用域 +升级，以及过期令牌/设备身份漂移。 ### 9）安全警告 -当某个提供商对私信开放但没有 allowlist，或者 -策略配置方式存在危险时，doctor 会发出警告。 +当某个提供商对私信开放但没有 allowlist，或 +某项策略配置得很危险时，Doctor 会发出警告。 ### 10）`systemd linger`（Linux） -如果以 `systemd` 用户服务运行，doctor 会确保已启用 lingering，以便 -Gateway 网关在注销后仍保持运行。 +如果作为 `systemd` 用户服务运行，Doctor 会确保已启用 lingering，这样 +Gateway 网关在注销后仍能保持运行。 ### 11）工作区状态（Skills、插件和旧版目录） -Doctor 会输出默认智能体的工作区状态摘要： +Doctor 会打印默认智能体的工作区状态摘要： -- **Skills 状态**：统计符合条件、缺少要求以及被 allowlist 阻止的 Skills 数量。 +- **Skills 状态**：统计可用、缺少要求、以及被 allowlist 阻止的 Skills 数量。 - **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录 与当前工作区并存时发出警告。 -- **插件状态**：统计已加载/已禁用/出错的插件数量；列出发生 - 错误的插件 ID；报告内置插件能力。 +- **插件状态**：统计已启用/已禁用/出错的插件数量；列出任何 + 出错插件的插件 ID；报告内置插件能力。 - **插件兼容性警告**：标记与 当前运行时存在兼容性问题的插件。 -- **插件诊断**：展示插件注册表在加载时输出的任何警告或错误。 +- **插件诊断**：显示插件注册表在 + 加载时发出的任何警告或错误。 -### 11b）bootstrap 文件大小 +### 11b）引导文件大小 -Doctor 会检查工作区 bootstrap 文件（例如 `AGENTS.md`、 -`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过已配置的 -字符预算。它会报告每个文件的原始字符数与注入后的字符数、截断 +Doctor 会检查工作区引导文件（例如 `AGENTS.md`、 +`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的 +字符预算。它会报告每个文件的原始字符数与注入字符数、截断 百分比、截断原因（`max/file` 或 `max/total`），以及总注入 字符数占总预算的比例。当文件被截断或接近限制时， -doctor 会输出关于如何调整 `agents.defaults.bootstrapMaxChars` +Doctor 会打印关于调整 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的建议。 -### 11c）shell 补全 +### 11c）Shell 自动补全 -Doctor 会检查当前 shell 是否已安装 tab 补全 -（zsh、bash、fish 或 PowerShell）： +Doctor 会检查当前 shell +（zsh、bash、fish 或 PowerShell）是否已安装 Tab 自动补全： -- 如果 shell 配置文件使用较慢的动态补全模式 - （`source <(openclaw completion ...)`），doctor 会将其升级为更快的 +- 如果 shell 配置文件使用较慢的动态自动补全模式 + （`source <(openclaw completion ...)`），Doctor 会将其升级为速度更快的 缓存文件变体。 -- 如果配置文件中已配置补全，但缓存文件缺失， - doctor 会自动重新生成缓存。 -- 如果完全未配置补全，doctor 会提示你安装它 +- 如果配置文件中已配置自动补全，但缓存文件缺失， + Doctor 会自动重新生成缓存。 +- 如果完全没有配置自动补全，Doctor 会提示你安装它 （仅交互模式；使用 `--non-interactive` 时跳过）。 运行 `openclaw completion --write-state` 可手动重新生成缓存。 ### 12）Gateway 网关认证检查（本地令牌） -Doctor 会检查本地 Gateway 网关令牌认证的就绪状态。 +Doctor 会检查本地 Gateway 网关令牌认证的就绪情况。 -- 如果令牌模式需要令牌且不存在令牌来源，doctor 会提供生成令牌的选项。 -- 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，doctor 会发出警告，且不会用明文覆盖它。 +- 如果令牌模式需要令牌且没有任何令牌来源，Doctor 会提供生成令牌的选项。 +- 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，Doctor 会发出警告，并且不会用明文覆盖它。 - `openclaw doctor --generate-gateway-token` 仅会在未配置令牌 SecretRef 时强制生成令牌。 ### 12b）只读的 SecretRef 感知修复 -某些修复流程需要检查已配置的凭证，同时不能削弱运行时快速失败行为。 +某些修复流程需要检查已配置的凭证，而不能削弱运行时的快速失败行为。 - `openclaw doctor --fix` 现在使用与 Status 系列命令相同的只读 SecretRef 摘要模型来执行有针对性的配置修复。 -- 示例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的机器人凭证。 -- 如果 Telegram 机器人令牌通过 SecretRef 配置，但在当前命令路径中不可用，doctor 会报告该凭证为“已配置但不可用”，并跳过自动解析，而不是崩溃或误报令牌缺失。 +- 例如：Telegram `allowFrom` / `groupAllowFrom` 的 `@username` 修复会在可用时尝试使用已配置的 bot 凭证。 +- 如果 Telegram bot 令牌通过 SecretRef 配置，但在当前命令路径中不可用，Doctor 会报告该凭证“已配置但不可用”，并跳过自动解析，而不是崩溃或误报令牌缺失。 -### 13）Gateway 网关健康检查 + 重启 +### 13）Gateway 网关运行状况检查 + 重启 -Doctor 会运行健康检查，并在 Gateway 网关看起来 +Doctor 会执行运行状况检查，并在 Gateway 网关看起来 不健康时提供重启选项。 -### 13b）Memory 搜索就绪状态 +### 13b）Memory 搜索就绪情况 Doctor 会检查为默认智能体配置的 Memory 搜索嵌入提供商是否已就绪。 -其行为取决于所配置的后端和提供商： +其行为取决于已配置的后端和提供商： - **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。 - 如果不可用，会输出修复指导，包括 npm 包和手动二进制路径选项。 -- **显式本地提供商**：检查本地模型文件或可识别的 - 远程/可下载模型 URL 是否存在。如果缺失，则建议切换到远程提供商。 -- **显式远程提供商**（`openai`、`voyage` 等）：验证 API 密钥是否 - 存在于环境变量或认证存储中。如果缺失，会输出可执行的修复提示。 + 如果不可用，会打印修复指引，包括 npm 包和手动二进制路径选项。 +- **显式本地提供商**：检查本地模型文件或已识别的 + 远程/可下载模型 URL 是否存在。如果缺失，会建议切换到远程提供商。 +- **显式远程提供商**（`openai`、`voyage` 等）：验证环境变量 + 或 auth 存储中是否存在 API 密钥。如果缺失，会打印可执行的修复提示。 - **自动提供商**：先检查本地模型可用性，然后按自动选择顺序尝试每个远程 提供商。 -当 Gateway 网关探测结果可用时（检查期间 Gateway 网关是健康的）， -doctor 会将其结果与 CLI 可见配置进行交叉比对，并指出 +当 Gateway 网关探测结果可用时（检查时 Gateway 网关处于健康状态）， +Doctor 会将其结果与 CLI 可见配置进行交叉比对，并指出 任何差异。 -使用 `openclaw memory status --deep` 可在运行时验证嵌入就绪状态。 +使用 `openclaw memory status --deep` 可验证运行时嵌入就绪情况。 ### 14）渠道状态警告 -如果 Gateway 网关健康，doctor 会运行渠道状态探测，并报告 -带有建议修复方案的警告。 +如果 Gateway 网关处于健康状态，Doctor 会执行渠道状态探测，并报告 +警告以及建议的修复方法。 ### 15）supervisor 配置审计 + 修复 Doctor 会检查已安装的 supervisor 配置（`launchd`/`systemd`/`schtasks`）中 -是否缺少或使用了过时的默认值（例如 `systemd` 的 `network-online` 依赖和 +是否缺少默认值或默认值已过期（例如 `systemd` 的 `network-online` 依赖和 重启延迟）。当发现不匹配时，它会建议更新，并且可以 将服务文件/任务重写为当前默认值。 -注意： +说明： -- `openclaw doctor` 会在重写 supervisor 配置前提示。 +- `openclaw doctor` 会在重写 supervisor 配置前进行提示。 - `openclaw doctor --yes` 会接受默认修复提示。 -- `openclaw doctor --repair` 会在无提示的情况下应用建议修复。 +- `openclaw doctor --repair` 会在不提示的情况下应用建议修复。 - `openclaw doctor --repair --force` 会覆盖自定义 supervisor 配置。 -- 如果令牌认证需要令牌且 `gateway.auth.token` 由 SecretRef 管理，doctor 的服务安装/修复会验证该 SecretRef，但不会把解析出的明文令牌值持久化到 supervisor 服务环境元数据中。 -- 如果令牌认证需要令牌且已配置的令牌 SecretRef 无法解析，doctor 会阻止安装/修复路径，并给出可执行的指导。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但未设置 `gateway.auth.mode`，doctor 会阻止安装/修复，直到显式设置模式。 -- 对于 Linux user-systemd 单元，doctor 的令牌漂移检查现在会在比较服务认证元数据时同时包含 `Environment=` 和 `EnvironmentFile=` 来源。 +- 如果令牌认证需要令牌，而 `gateway.auth.token` 由 SecretRef 管理，Doctor 在服务安装/修复时会验证该 SecretRef，但不会将解析后的明文令牌值持久化到 supervisor 服务环境元数据中。 +- 如果令牌认证需要令牌，而已配置的令牌 SecretRef 无法解析，Doctor 会阻止安装/修复路径，并提供可执行的指引。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但未设置 `gateway.auth.mode`，Doctor 会阻止安装/修复，直到显式设置模式。 +- 对于 Linux user-systemd 单元，Doctor 的令牌漂移检查现在在比较服务认证元数据时会同时包含 `Environment=` 和 `EnvironmentFile=` 来源。 - 你始终可以通过 `openclaw gateway install --force` 强制执行完整重写。 ### 16）Gateway 网关运行时 + 端口诊断 -Doctor 会检查服务运行时信息（PID、最近退出状态），并在 -服务已安装但实际上未运行时发出警告。它还会检查 Gateway 网关端口 -（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、 +Doctor 会检查服务运行时（PID、上次退出状态），并在 +服务已安装但实际上未运行时发出警告。它还会检查 Gateway 网关端口上的端口冲突 +（默认 `18789`），并报告可能原因（Gateway 网关已在运行、 SSH 隧道）。 ### 17）Gateway 网关运行时最佳实践 -当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径上时， -doctor 会发出警告 -（`nvm`、`fnm`、`volta`、`asdf` 等）。WhatsApp + Telegram 渠道需要 Node， -而版本管理器路径在升级后可能失效，因为服务不会 -加载你的 shell 初始化。Doctor 会在系统 Node 安装可用时， -提供迁移到系统 Node 安装的选项（Homebrew/apt/choco）。 +当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径 +（`nvm`、`fnm`、`volta`、`asdf` 等）上时，Doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node， +而版本管理器路径可能会在升级后失效，因为服务不会 +加载你的 shell 初始化。Doctor 会在系统 Node 安装可用时，提供迁移到 +系统 Node 安装的选项（Homebrew/apt/choco）。 ### 18）配置写入 + 向导元数据 -Doctor 会持久化所有配置更改，并写入向导元数据以记录此次 -doctor 运行。 +Doctor 会持久化所有配置更改，并写入向导元数据以记录 +本次 Doctor 运行。 -### 19）工作区提示（备份 + memory 系统） +### 19）工作区提示（备份 + Memory 系统） -当工作区缺少 memory 系统时，doctor 会建议添加一个；如果工作区 -尚未由 git 管理，它还会输出备份提示。 +当工作区缺少 Memory 系统时，Doctor 会提出建议；如果工作区尚未纳入 git， +它还会打印备份提示。 -有关工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南，请参阅 -[/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)。 +参见 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)，获取关于 +工作区结构和 git 备份的完整指南（推荐使用私有 GitHub 或 GitLab）。 ## 相关内容 diff --git a/docs/zh-CN/plugins/compatibility.md b/docs/zh-CN/plugins/compatibility.md index b1a50fd73..8fb3fcca3 100644 --- a/docs/zh-CN/plugins/compatibility.md +++ b/docs/zh-CN/plugins/compatibility.md @@ -1,39 +1,39 @@ --- read_when: - 你维护一个 OpenClaw 插件 - - 你看到一个插件兼容性警告 + - 你看到一条插件兼容性警告 - 你正在规划插件 SDK 或清单迁移 summary: 插件兼容性契约、弃用元数据和迁移预期 title: 插件兼容性 x-i18n: - generated_at: "2026-04-25T05:55:10Z" + generated_at: "2026-04-25T17:39:04Z" model: gpt-5.4 provider: openai - source_hash: 02e0cdbc763eed5a38b303fc44202ddd36e58bce43dc29b6348db3f5fea66f26 + source_hash: 511bd12cff1e72a93091cbb1ac7d75377b0b9d2f016b55f4cdc77293f6172a00 source_path: plugins/compatibility.md workflow: 15 --- -OpenClaw 在移除旧版插件契约之前，会先通过具名兼容性适配器保持这些旧契约继续可用。这样可以在 SDK、清单、设置、配置和 Agent Runtimes 契约演进的同时，保护现有的内置插件和外部插件。 +OpenClaw 会在移除旧版插件契约之前，通过具名兼容适配器继续接线支持这些旧契约。这可以在 SDK、清单、设置、配置和智能体运行时契约演进期间，保护现有的内置插件和外部插件。 ## 兼容性注册表 -插件兼容性契约会在核心注册表 `src/plugins/compat/registry.ts` 中跟踪。 +插件兼容性契约会在核心注册表 `src/plugins/compat/registry.ts` 中进行跟踪。 每条记录包含： - 稳定的兼容性代码 - 状态：`active`、`deprecated`、`removal-pending` 或 `removed` -- 归属方：SDK、配置、设置、渠道、提供商、插件执行、Agent Runtimes 或核心 +- 所有者：SDK、配置、设置、渠道、提供商、插件执行、智能体运行时或核心 - 适用时的引入日期和弃用日期 -- 替代指引 -- 覆盖旧行为和新行为的文档、诊断和测试 +- 替代方案指引 +- 覆盖旧行为和新行为的文档、诊断信息和测试 -该注册表是维护者规划和未来插件检查器校验的依据。如果面向插件的行为发生变化，请在添加适配器的同一次变更中添加或更新兼容性记录。 +该注册表是维护者规划和未来插件检查器检查的来源。如果面向插件的行为发生变化，请在添加适配器的同一项变更中新增或更新兼容性记录。 ## 插件检查器包 -插件检查器应位于核心 OpenClaw 仓库之外，作为一个由版本化兼容性契约和清单契约支持的独立包/仓库。 +插件检查器应位于核心 OpenClaw 仓库之外，作为一个独立的软件包/仓库，并基于带版本的兼容性契约和清单契约构建。 首日 CLI 应为： @@ -43,44 +43,45 @@ openclaw-plugin-inspector ./my-plugin 它应输出： -- 清单 / schema 校验 +- 清单/模式验证 - 正在检查的契约兼容性版本 -- install / source 元数据检查 +- 安装/来源元数据检查 - 冷路径导入检查 - 弃用和兼容性警告 -在 CI 注解中使用 `--json` 以获得稳定的机器可读输出。OpenClaw 核心应公开检查器可消费的契约和夹具，但不应从主 `openclaw` 包发布检查器二进制文件。 +在 CI 注释中使用 `--json` 获取稳定的机器可读输出。OpenClaw 核心应暴露检查器可使用的契约和夹具，但不应从主 `openclaw` 包发布该检查器二进制文件。 ## 弃用策略 -OpenClaw 不应在引入替代方案的同一版本中移除已文档化的插件契约。 +OpenClaw 不应在引入某个已记录插件契约替代方案的同一版本中移除该契约。 迁移顺序如下： 1. 添加新契约。 -2. 通过具名兼容性适配器保留旧行为继续可用。 -3. 在插件作者可以采取行动时发出诊断或警告。 +2. 通过具名兼容适配器继续接线保留旧行为。 +3. 当插件作者可以采取行动时，发出诊断信息或警告。 4. 记录替代方案和时间线。 -5. 同时测试旧路径和新路径。 +5. 测试旧路径和新路径。 6. 等待已公布的迁移窗口结束。 -7. 只有在获得显式破坏性版本批准后才移除。 +7. 仅在获得明确的破坏性发布批准后移除。 -弃用记录必须包含警告开始日期、替代方案、文档链接，以及在已知情况下的目标移除日期。 +已弃用记录必须包含警告开始日期、替代方案、文档链接，以及在已知时的目标移除日期。 -## 当前兼容性范围 +## 当前兼容性领域 当前兼容性记录包括： - 旧版宽泛 SDK 导入，例如 `openclaw/plugin-sdk/compat` - 旧版仅钩子插件形态和 `before_agent_start` -- 内置插件 allowlist 和启用行为 -- 旧版 provider / channel 环境变量清单元数据 +- 内置插件允许列表和启用行为 +- 旧版 provider/渠道环境变量清单元数据 - 正在由清单贡献所有权替代的激活提示 -- 当公共命名转向 `agentRuntime` 时，`embeddedHarness` 和 `agent-harness` 命名别名 -- 当注册表优先的 `channelConfigs` 元数据落地时，生成的内置渠道配置元数据回退 +- `embeddedHarness` 和 `agent-harness` 命名别名，在公共命名向 `agentRuntime` 迁移期间继续保留 +- 在以注册表优先的 `channelConfigs` 元数据落地期间，生成的内置渠道配置元数据回退 +- 持久化的插件注册表禁用环境变量，同时修复流程会将运维人员迁移到 `openclaw plugins registry --refresh` 和 `openclaw doctor --fix` -新插件代码应优先使用注册表和具体迁移指南中列出的替代方案。现有插件可以继续使用兼容路径，直到文档、诊断和发布说明公布移除窗口。 +新插件代码应优先使用注册表和特定迁移指南中列出的替代方案。现有插件可以继续使用兼容路径，直到文档、诊断信息和发布说明公布移除窗口。 ## 发布说明 -发布说明应包含即将到来的插件弃用信息，并附带目标日期和迁移文档链接。这类预警必须在兼容路径转为 `removal-pending` 或 `removed` 之前发出。 +发布说明应包含即将到来的插件弃用事项，并附上目标日期和迁移文档链接。这类警告必须在某个兼容路径转为 `removal-pending` 或 `removed` 之前发出。 diff --git a/docs/zh-CN/tools/plugin.md b/docs/zh-CN/tools/plugin.md index ab17ecedd..0ff492e3a 100644 --- a/docs/zh-CN/tools/plugin.md +++ b/docs/zh-CN/tools/plugin.md @@ -1,30 +1,26 @@ --- read_when: - 安装或配置插件 - - 了解插件发现和加载规则 + - 了解插件发现与加载规则 - 使用与 Codex/Claude 兼容的插件包 sidebarTitle: Install and Configure summary: 安装、配置和管理 OpenClaw 插件 title: 插件 x-i18n: - generated_at: "2026-04-25T05:57:05Z" + generated_at: "2026-04-25T17:39:05Z" model: gpt-5.4 provider: openai - source_hash: 54a902eabd90e54e769429770cd56e1d89a8bb50aff4b9ed8a9f68d6685b77a8 + source_hash: 82e272b1b59006b1f40b4acc3f21a8bca8ecacc1a8b7fb577ad3d874b9a8e326 source_path: tools/plugin.md workflow: 15 --- -插件通过新增能力来扩展 OpenClaw：渠道、模型提供商、 -Agent harnesses、工具、Skills、语音、实时转写、实时 -语音、媒体理解、图像生成、视频生成、web 抓取、web -搜索等等。有些插件是**核心**插件（随 OpenClaw 一起提供），另一些 -是**外部**插件（由社区发布到 npm）。 +插件通过新增功能来扩展 OpenClaw：渠道、模型提供商、智能体 harness、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是 **核心** 插件（随 OpenClaw 一起提供），另一些则是 **外部** 插件（由社区发布到 npm）。 ## 快速开始 - + ```bash openclaw plugins list ``` @@ -32,10 +28,10 @@ Agent harnesses、工具、Skills、语音、实时转写、实时 ```bash - # 从 npm + # 来自 npm openclaw plugins install @openclaw/voice-call - # 从本地目录或归档文件 + # 来自本地目录或归档文件 openclaw plugins install ./my-plugin openclaw plugins install ./my-plugin.tgz ``` @@ -47,12 +43,12 @@ Agent harnesses、工具、Skills、语音、实时转写、实时 openclaw gateway restart ``` - 然后在你的配置文件中于 `plugins.entries.\.config` 下进行配置。 + 然后在你的配置文件中的 `plugins.entries.\.config` 下进行配置。 -如果你更喜欢原生聊天控制，请启用 `commands.plugins: true` 并使用： +如果你更喜欢聊天原生控制，启用 `commands.plugins: true` 并使用： ```text /plugin install clawhub:@openclaw/voice-call @@ -60,73 +56,67 @@ Agent harnesses、工具、Skills、语音、实时转写、实时 /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`、 +打包后的 OpenClaw 安装不会急切安装每个内置插件的运行时依赖树。当某个 OpenClaw 自带的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于活跃状态时，启动过程只会在导入它之前修复该插件声明的运行时依赖。显式禁用仍然优先：`plugins.entries..enabled: false`、 `plugins.deny`、`plugins.enabled: false` 和 `channels..enabled: false` -都会阻止该插件/渠道的自动内置运行时依赖修复。 -外部插件和自定义加载路径仍然必须通过 +都会阻止对该插件/渠道自动执行内置运行时依赖修复。外部插件和自定义加载路径仍必须通过 `openclaw plugins install` 安装。 ## 插件类型 OpenClaw 可识别两种插件格式： -| 格式 | 工作方式 | 示例 | -| ---------- | ---------------------------------------------------------- | ------------------------------------------------------ | -| **Native** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 | -| **Bundle** | 与 Codex/Claude/Cursor 兼容的布局；映射为 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` | +| 格式 | 工作方式 | 示例 | +| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ | +| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 | +| **Bundle** | 与 Codex/Claude/Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` | -两者都会显示在 `openclaw plugins list` 中。有关 bundle 详情，请参见 [Plugin Bundles](/zh-CN/plugins/bundles)。 +两者都会显示在 `openclaw plugins list` 中。关于 bundle 的详细信息，请参见 [插件包](/zh-CN/plugins/bundles)。 -如果你要编写 Native 插件，请从 [构建插件](/zh-CN/plugins/building-plugins) +如果你正在编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins) 和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。 ## 官方插件 ### 可安装（npm） -| 插件 | 包 | 文档 | +| 插件 | 包 | 文档 | | --------------- | ---------------------- | ------------------------------------ | -| Matrix | `@openclaw/matrix` | [Matrix](/zh-CN/channels/matrix) | -| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/zh-CN/channels/msteams) | -| Nostr | `@openclaw/nostr` | [Nostr](/zh-CN/channels/nostr) | -| Voice Call | `@openclaw/voice-call` | [Voice Call](/zh-CN/plugins/voice-call) | -| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) | -| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) | +| Matrix | `@openclaw/matrix` | [Matrix](/zh-CN/channels/matrix) | +| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/zh-CN/channels/msteams) | +| Nostr | `@openclaw/nostr` | [Nostr](/zh-CN/channels/nostr) | +| Voice Call | `@openclaw/voice-call` | [Voice Call](/zh-CN/plugins/voice-call) | +| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) | +| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) | ### 核心（随 OpenClaw 一起提供） - `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` — 内置 memory 搜索（通过 `plugins.slots.memory` 默认启用） - - `memory-lancedb` — 按需安装的长期 memory，带自动 recall/capture（设置 `plugins.slots.memory = "memory-lancedb"`） + - `memory-core` — 内置的内存搜索（默认通过 `plugins.slots.memory` 启用） + - `memory-lancedb` — 按需安装的长期记忆，带自动召回/捕获功能（设置 `plugins.slots.memory = "memory-lancedb"`） - `elevenlabs`、`microsoft` + `elevenlabs`, `microsoft` - - `browser` — browser 工具、`openclaw browser` CLI、`browser.request` gateway 方法、browser 运行时以及默认 browser 控制服务的内置 browser 插件（默认启用；替换前请先禁用） - - `copilot-proxy` — VS Code Copilot Proxy bridge（默认禁用） + - `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时以及默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用） + - `copilot-proxy` — VS Code Copilot Proxy 桥接（默认禁用） @@ -148,37 +138,29 @@ OpenClaw 可识别两种插件格式： } ``` -| 字段 | 描述 | -| ---------------- | -------------------------------------------------- | -| `enabled` | 主开关（默认：`true`） | -| `allow` | 插件允许名单（可选） | -| `deny` | 插件拒绝名单（可选；拒绝优先） | -| `load.paths` | 额外的插件文件/目录 | -| `slots` | 独占插槽选择器（例如 `memory`、`contextEngine`） | -| `entries.\` | 每个插件的开关 + 配置 | +| 字段 | 说明 | +| ---------------- | --------------------------------------------------------- | +| `enabled` | 主开关（默认：`true`） | +| `allow` | 插件允许列表（可选） | +| `deny` | 插件拒绝列表（可选；拒绝优先） | +| `load.paths` | 额外的插件文件/目录 | +| `slots` | 排他性插槽选择器（例如 `memory`、`contextEngine`） | +| `entries.\` | 按插件划分的开关 + 配置 | -配置更改**需要重启网关**。如果 Gateway 网关以配置监视 + 进程内重启启用方式运行（默认的 `openclaw gateway` 路径），该 -重启通常会在配置写入完成后不久自动执行。 -对于 Native 插件运行时代码或生命周期 -钩子，没有受支持的热重载路径；请重启正在为实时渠道提供服务的 Gateway 网关进程，然后再期待更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务或 -provider/运行时钩子生效。 +配置更改 **需要重启网关**。如果 Gateway 网关在启用了配置监听和进程内重启的情况下运行（默认的 `openclaw gateway` 路径），那么在配置写入完成后，通常会自动稍后执行该重启。目前不支持对原生插件运行时代码或生命周期钩子的热重载；在期望更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务或提供商/运行时钩子生效之前，请重启为实时渠道提供服务的 Gateway 网关进程。 -`openclaw plugins list` 是本地 CLI/配置快照。其中某个插件显示为 -`loaded`，意味着从该次 CLI 调用所见的配置/文件来看，该插件是可发现且可加载的。 -这并不能证明一个已经运行中的远程 Gateway 网关子进程 -已经重启并加载到了相同的插件代码。在 VPS/容器设置中，请将重启信号发送给实际的 -`openclaw gateway run` 进程，或对正在运行的 Gateway 网关使用 -`openclaw gateway restart`。 +`openclaw plugins list` 是本地插件注册表/配置快照。那里显示为 +`enabled` 的插件表示持久化注册表和当前配置允许该插件参与运行。这并不能证明一个已经运行中的远程 Gateway 网关子进程已经重启并加载了相同的插件代码。在 VPS/容器部署中，如果存在包装进程，请把重启信号发给实际的 `openclaw gateway run` 进程，或针对正在运行的 Gateway 网关使用 `openclaw gateway restart`。 - - - **Disabled**：插件存在，但启用规则将其关闭。配置会被保留。 - - **Missing**：配置引用了一个插件 id，但设备发现未找到该插件。 - - **Invalid**：插件存在，但其配置不匹配已声明的 schema。 + + - **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。 + - **缺失**：配置引用了某个插件 id，但设备发现未找到它。 + - **无效**：插件存在，但其配置与声明的 schema 不匹配。 -## 发现和优先级 +## 发现顺序和优先级 -OpenClaw 按以下顺序扫描插件（先匹配者优先）： +OpenClaw 按以下顺序扫描插件（先匹配者生效）： @@ -204,39 +186,35 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）： - `plugins.enabled: false` 会禁用所有插件 - `plugins.deny` 始终优先于 allow - `plugins.entries.\.enabled: false` 会禁用该插件 -- 工作区来源的插件**默认禁用**（必须显式启用） +- 来源于工作区的插件 **默认禁用**（必须显式启用） - 内置插件遵循内建的默认启用集合，除非被覆盖 -- 独占插槽可以强制启用为该插槽选中的插件 -- 某些内置的选择加入型插件会在配置命名了 - 插件自有 surface 时自动启用，例如 provider 模型引用、渠道配置或 harness - 运行时 -- OpenAI 系列 Codex 路由保持独立插件边界： - `openai-codex/*` 属于 OpenAI 插件，而内置 Codex +- 排他性插槽可以强制启用为该插槽选定的插件 +- 某些选择加入的内置插件会在配置命名了某个插件拥有的表面时自动启用，例如提供商模型引用、渠道配置或 harness 运行时 +- OpenAI 系列的 Codex 路由保持独立的插件边界： + `openai-codex/*` 属于 OpenAI 插件，而内置的 Codex app-server 插件则通过 `embeddedHarness.runtime: "codex"` 或旧版 `codex/*` 模型引用来选择 ## 运行时钩子故障排除 -如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或钩子 -在实时聊天流量中没有运行，请先检查以下内容： +如果某个插件出现在 `plugins list` 中，但 `register(api)` 的副作用或钩子在实时聊天流量中没有运行，请先检查以下内容： -- 运行 `openclaw gateway status --deep --require-rpc` 并确认活动中的 - Gateway 网关 URL、profile、配置路径和进程就是你正在编辑的那些。 -- 在插件安装/配置/代码更改后重启实时 Gateway 网关。在包装器 - 容器中，PID 1 可能只是一个 supervisor；请重启或向子 - `openclaw gateway run` 进程发送信号。 -- 使用 `openclaw plugins inspect --json` 确认钩子注册和 - 诊断信息。非内置的对话钩子，例如 `llm_input`、 - `llm_output` 和 `agent_end`，需要设置 +- 运行 `openclaw gateway status --deep --require-rpc`，确认当前活跃的 + Gateway 网关 URL、配置文件、配置路径和进程，正是你正在编辑的那些。 +- 在插件安装/配置/代码更改后重启实时 Gateway 网关。在包装容器中， + PID 1 可能只是一个监督进程；请重启或发送信号给子进程 + `openclaw gateway run`。 +- 使用 `openclaw plugins inspect --json` 确认钩子注册情况和诊断信息。非内置的会话钩子，如 `llm_input`、 + `llm_output` 和 `agent_end`，需要 `plugins.entries..hooks.allowConversationAccess=true`。 -- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析之前运行；`llm_output` 只有在某次模型尝试产生助手输出后才会运行。 -- 如需证明会话的实际模型，请使用 `openclaw sessions` 或 - Gateway 网关会话/Status surface；在调试 provider 负载时，请使用 +- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析之前运行；而 `llm_output` 仅在一次模型尝试产生助手输出后才运行。 +- 要证明生效中的会话模型，请使用 `openclaw sessions` 或 + Gateway 网关的会话/状态表面；在调试提供商负载时，请使用 `--raw-stream --raw-stream-path ` 启动 Gateway 网关。 -## 插件插槽（独占类别） +## 插件插槽（排他性类别） -某些类别是独占的（同一时间只能有一个处于活动状态）： +某些类别是排他的（一次只能有一个处于活跃状态）： ```json5 { @@ -249,29 +227,31 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）： } ``` -| 插槽 | 控制内容 | 默认值 | -| ---------------- | ---------------------- | ------------------- | -| `memory` | 活动中的 memory 插件 | `memory-core` | -| `contextEngine` | 活动中的上下文引擎 | `legacy`（内置） | +| 插槽 | 它控制的内容 | 默认值 | +| --------------- | --------------------- | ------------------- | +| `memory` | 活跃的内存插件 | `memory-core` | +| `contextEngine` | 活跃的上下文引擎 | `legacy`（内建） | ## CLI 参考 ```bash -openclaw plugins list # 紧凑清单 -openclaw plugins list --enabled # 仅显示已加载插件 -openclaw plugins list --verbose # 每个插件的详细行 +openclaw plugins list # 精简清单 +openclaw plugins list --enabled # 仅显示已启用插件 +openclaw plugins list --verbose # 每个插件的详细信息行 openclaw plugins list --json # 机器可读清单 openclaw plugins inspect # 深度详情 openclaw plugins inspect --json # 机器可读 openclaw plugins inspect --all # 全局表格 openclaw plugins info # inspect 别名 openclaw plugins doctor # 诊断 +openclaw plugins registry # 查看持久化注册表状态 +openclaw plugins registry --refresh # 重建持久化注册表 -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 # link（不复制），用于开发 +openclaw plugins install -l # 链接（不复制），用于开发 openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// openclaw plugins install --pin # 记录精确解析后的 npm spec @@ -279,7 +259,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 @@ -288,61 +268,39 @@ openclaw plugins enable openclaw plugins disable ``` -内置插件随 OpenClaw 一起提供。许多默认启用（例如 -内置模型提供商、内置语音提供商，以及内置 browser -插件）。其他内置插件仍然需要 `openclaw plugins enable `。 +内置插件随 OpenClaw 一起提供。许多默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）。其他内置插件仍然需要使用 `openclaw plugins enable `。 -`--force` 会原地覆盖现有已安装插件或 hook pack。对于已跟踪的 npm +`--force` 会就地覆盖现有已安装的插件或 hook 包。对于已跟踪的 npm 插件的常规升级，请使用 `openclaw plugins update `。 -它不支持与 `--link` 一起使用，因为后者会复用源路径， -而不是复制到受管理的安装目标中。 +它不支持与 `--link` 一起使用，因为后者会复用源路径，而不是复制到受管理的安装目标。 -当已经设置了 `plugins.allow` 时，`openclaw plugins install` 会先将 -已安装插件 id 添加到该允许名单中，然后再启用它，这样插件在重启后 -即可立即加载。 +当 `plugins.allow` 已经设置时，`openclaw plugins install` 会在启用插件之前，将已安装插件的 id 添加到该允许列表中，因此重启后可立即加载。 -`openclaw plugins update ` 适用于已跟踪安装。传入 -带 dist-tag 或精确版本的 npm 包 spec 时，会将包名解析回 -已跟踪的插件记录，并记录新的 spec 以供后续更新。 -传入不带版本的包名时，会将一个精确固定版本的安装切回 -注册表的默认发布线。如果已安装的 npm 插件已经匹配 -解析后的版本和记录的工件身份，OpenClaw 会跳过更新，不会下载、 -重新安装或重写配置。 +OpenClaw 会维护一个持久化的本地插件注册表，将其作为插件清单、贡献归属和启动规划的冷读取模型。安装、更新、卸载、启用和禁用流程会在更改插件状态后刷新该注册表。如果注册表缺失、过期或无效，`openclaw plugins registry --refresh` +会根据持久安装账本、配置策略以及清单/包元数据重建它，而不会加载插件运行时模块。 -`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 -marketplace 安装会持久化 marketplace 源元数据，而不是 npm spec。 +`openclaw plugins update ` 适用于已跟踪的安装。传入带有 dist-tag 或精确版本的 npm 包 spec 时，会将包名解析回已跟踪的插件记录，并为后续更新记录新的 spec。传入不带版本的包名时，会将一个精确固定版本的安装切回注册表的默认发布线。如果已安装的 npm 插件已经匹配解析后的版本和记录的构件标识，OpenClaw 会跳过更新，而不会下载、重新安装或重写配置。 -`--dangerously-force-unsafe-install` 是用于处理内置危险代码扫描器 -误报的紧急覆盖开关。它允许插件安装 -和插件更新在遇到内置 `critical` 发现后继续执行，但仍然 -不会绕过插件 `before_install` 策略阻止或扫描失败阻止。 +`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 源元数据，而不是 npm spec。 -这个 CLI 标志仅适用于插件安装/更新流程。Gateway 网关支持的 Skills -依赖安装则使用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖， -而 `openclaw skills install` 仍然是单独的 ClawHub Skills 下载/安装流程。 +`--dangerously-force-unsafe-install` 是一个用于紧急破局的覆盖选项，用于处理内置危险代码扫描器的误报。它允许插件安装和插件更新在内置 `critical` 发现后继续执行，但仍不会绕过插件 +`before_install` 策略拦截或扫描失败拦截。 -兼容的 bundle 也参与相同的插件 list/inspect/enable/disable 流程。 -当前运行时支持包括 bundle Skills、Claude command-Skills、 -Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 -`lspServers` 默认值、Cursor command-Skills，以及兼容的 Codex hook -目录。 +这个 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关驱动的 Skills 依赖安装则使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载/安装流程。 -`openclaw plugins inspect ` 还会报告已检测到的 bundle 能力，以及 -由 bundle 支持的插件中的受支持或不受支持的 MCP 和 LSP server 条目。 +兼容的 bundle 会参与相同的插件 list/inspect/enable/disable 流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。 -Marketplace 源可以是来自 -`~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 -`marketplace.json` 路径、像 `owner/repo` 这样的 GitHub 简写、GitHub 仓库 -URL，或 git URL。对于远程 marketplaces，插件条目必须保持在 -克隆的 marketplace 仓库内部，并且只能使用相对路径源。 +`openclaw plugins inspect ` 还会报告检测到的 bundle 能力，以及由 bundle 支持的或不支持的 MCP 和 LSP 服务器条目。 + +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)。 ## 插件 API 概览 -Native 插件会导出一个暴露 `register(api)` 的入口对象。较旧的 -插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应当 -使用 `register`。 +原生插件会导出一个入口对象，并暴露 `register(api)`。较旧的插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。 ```typescript export default definePluginEntry({ @@ -362,72 +320,61 @@ export default definePluginEntry({ }); ``` -OpenClaw 会加载该入口对象，并在插件 -激活期间调用 `register(api)`。加载器仍会为旧插件回退到 `activate(api)`， -但内置插件和新的外部插件应将 `register` 视为 -公开契约。 +OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公开契约。 `api.registrationMode` 会告诉插件其入口为何被加载： -| 模式 | 含义 | +| 模式 | 含义 | | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `full` | 运行时激活。注册工具、钩子、服务、命令、路由及其他实时副作用。 | -| `discovery` | 只读能力发现。注册提供商和元数据；可信插件入口代码可能会被加载，但要跳过实时副作用。 | -| `setup-only` | 通过轻量级设置入口加载渠道设置元数据。 | -| `setup-runtime` | 加载渠道设置，同时也需要运行时入口。 | -| `cli-metadata` | 仅收集 CLI 命令元数据。 | +| `full` | 运行时激活。注册工具、钩子、服务、命令、路由以及其他实时副作用。 | +| `discovery` | 只读能力发现。注册提供商和元数据；可信插件入口代码可能会被加载，但应跳过实时副作用。 | +| `setup-only` | 通过轻量级 setup 入口加载渠道设置元数据。 | +| `setup-runtime` | 加载渠道设置，同时也需要运行时入口。 | +| `cli-metadata` | 仅收集 CLI 命令元数据。 | -那些会打开 socket、数据库、后台 worker 或长生命周期 -客户端的插件入口，应当使用 `api.registrationMode === "full"` 保护这些副作用。 -设备发现加载会与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。 -设备发现是非激活的，而不是免导入的：OpenClaw 可能会执行可信的插件入口或渠道插件模块以构建 -快照。请保持模块顶层轻量且无副作用，并将 -网络客户端、子进程、监听器、凭证读取和服务启动移动到完整运行时路径之后。 +那些会打开套接字、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 来保护这些副作用。发现加载与激活加载会分别缓存，并且不会替换正在运行的 Gateway 网关注册表。发现过程不会激活，但也不是完全不导入：OpenClaw 可能会执行可信插件入口或渠道插件模块，以构建快照。请保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径之后。 常见注册方法： -| 方法 | 注册内容 | -| ------------------------------------- | --------------------------- | -| `registerProvider` | 模型提供商（LLM） | -| `registerChannel` | 聊天渠道 | -| `registerTool` | 智能体工具 | -| `registerHook` / `on(...)` | 生命周期钩子 | -| `registerSpeechProvider` | 文本转语音 / STT | -| `registerRealtimeTranscriptionProvider` | 实时分块流式 STT | -| `registerRealtimeVoiceProvider` | 双工实时语音 | -| `registerMediaUnderstandingProvider` | 图像/音频分析 | -| `registerImageGenerationProvider` | 图像生成 | -| `registerMusicGenerationProvider` | 音乐生成 | -| `registerVideoGenerationProvider` | 视频生成 | -| `registerWebFetchProvider` | Web 抓取 / 抓取提供商 | -| `registerWebSearchProvider` | Web 搜索 | -| `registerHttpRoute` | HTTP 端点 | -| `registerCommand` / `registerCli` | CLI 命令 | -| `registerContextEngine` | 上下文引擎 | -| `registerService` | 后台服务 | +| 方法 | 注册内容 | +| --------------------------------------- | --------------------------- | +| `registerProvider` | 模型提供商（LLM） | +| `registerChannel` | 聊天渠道 | +| `registerTool` | 智能体工具 | +| `registerHook` / `on(...)` | 生命周期钩子 | +| `registerSpeechProvider` | 文本转语音 / STT | +| `registerRealtimeTranscriptionProvider` | 流式 STT | +| `registerRealtimeVoiceProvider` | 双工实时语音 | +| `registerMediaUnderstandingProvider` | 图像/音频分析 | +| `registerImageGenerationProvider` | 图像生成 | +| `registerMusicGenerationProvider` | 音乐生成 | +| `registerVideoGenerationProvider` | 视频生成 | +| `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 }` 是空操作，不会清除更早的拦截。 +- `before_install`：`{ block: true }` 是终止性的；更低优先级的处理器会被跳过。 +- `before_install`：`{ block: false }` 是空操作，不会清除更早的拦截。 +- `message_sending`：`{ cancel: true }` 是终止性的；更低优先级的处理器会被跳过。 +- `message_sending`：`{ cancel: false }` 是空操作，不会清除更早的取消。 -Native Codex app-server 运行时会将桥接的 Codex 原生工具事件回传到这个 -钩子 surface。插件可以通过 `before_tool_call` 阻止原生 Codex 工具， -通过 `after_tool_call` 观察结果，并参与 Codex -`PermissionRequest` 批准。该桥目前还不会重写 Codex 原生工具 -参数。精确的 Codex 运行时支持边界位于 +原生 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 兼容性 +- [插件包](/zh-CN/plugins/bundles) — Codex/Claude/Cursor bundle 兼容性 - [插件清单](/zh-CN/plugins/manifest) — 清单 schema - [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具 - [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流水线