diff --git a/docs/zh-CN/cli/plugins.md b/docs/zh-CN/cli/plugins.md index 383282794..ff3aaff47 100644 --- a/docs/zh-CN/cli/plugins.md +++ b/docs/zh-CN/cli/plugins.md @@ -1,32 +1,32 @@ --- read_when: - - 你想安装或管理 Gateway 网关插件或兼容包 - - 你想调试插件加载失败问题 + - 你想安装或管理 Gateway 网关插件或兼容的捆绑包 + - 你想调试插件加载失败 sidebarTitle: Plugins summary: '`openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、deps、doctor）' title: 插件 x-i18n: - generated_at: "2026-05-01T07:53:07Z" + generated_at: "2026-05-01T10:03:18Z" model: gpt-5.5 provider: openai - source_hash: cc4b2b753b541dd143e9c2f7e8a2153711a18e15773c65f91756d2729ca3d6fb + source_hash: 3a7aebe4ee647d7821b881cdb9d5af01d70508c38b36462ff7b57fb44769dc2f source_path: cli/plugins.md workflow: 16 --- -管理 Gateway 网关插件、钩子包和兼容捆绑包。 +管理 Gateway 网关插件、钩子包和兼容包。 面向最终用户的插件安装、启用和故障排除指南。 - - 捆绑包兼容性模型。 + + 包兼容性模型。 清单字段和配置 schema。 - + 插件安装的安全加固。 @@ -60,14 +60,14 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -如果需要排查安装、检查、卸载或 registry 刷新缓慢的问题，请在运行命令时带上 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`。该跟踪会将各阶段耗时写入 stderr，并保持 JSON 输出可解析。请参阅 [调试](/zh-CN/help/debugging#plugin-lifecycle-trace)。 +如果要调查安装、检查、卸载或 registry 刷新速度慢的问题，请使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 运行该命令。trace 会将阶段耗时写入 stderr，并保持 JSON 输出可解析。参见[调试](/zh-CN/help/debugging#plugin-lifecycle-trace)。 -内置插件随 OpenClaw 一起发布。部分插件默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）；其他插件需要使用 `plugins enable`。 +内置插件随 OpenClaw 一起发布。有些默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）；其他插件需要使用 `plugins enable`。 -原生 OpenClaw 插件必须随附 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空也需要）。兼容捆绑包则使用自己的捆绑包清单。 +原生 OpenClaw 插件必须随附 `openclaw.plugin.json`，其中包含内联 JSON Schema（`configSchema`，即使为空也需要）。兼容包则使用自己的包清单。 -`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细列表/info 输出还会显示捆绑包子类型（`codex`、`claude` 或 `cursor`）以及检测到的捆绑包能力。 +`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细 list/info 输出还会显示包子类型（`codex`、`claude` 或 `cursor`）以及检测到的包能力。 ### 安装 @@ -76,6 +76,8 @@ openclaw plugins marketplace list --json openclaw plugins install # ClawHub first, then npm openclaw plugins install clawhub: # ClawHub only openclaw plugins install npm: # npm only +openclaw plugins install git:github.com// # git repo +openclaw plugins install git:github.com//@ openclaw plugins install --force # overwrite existing install openclaw plugins install --pin # pin version openclaw plugins install --dangerously-force-unsafe-install @@ -86,79 +88,87 @@ openclaw plugins install --marketplace https://github.com// -裸包名会先在 ClawHub 中检查，然后再检查 npm。请像运行代码一样对待插件安装。优先使用固定版本。 +裸包名会先在 ClawHub 中检查，然后再检查 npm。请像运行代码一样看待插件安装。优先使用固定版本。 -ClawHub 是大多数插件的主要分发和设备发现入口。npm 仍然是受支持的回退和直接安装路径。在迁移到 ClawHub 期间，OpenClaw 仍会在 npm 上发布一些 OpenClaw 拥有的 `@openclaw/*` 插件包；在不同插件发布列车之间，这些包版本可能落后于内置源代码。如果 npm 将某个 OpenClaw 拥有的插件包报告为已弃用，该已发布版本就是旧的外部产物；请使用当前 OpenClaw 内置的插件或本地 checkout，直到发布更新的 npm 包。 +ClawHub 是大多数插件的主要分发和发现界面。Npm 仍然是受支持的兜底方案和直接安装路径。在迁移到 ClawHub 期间，OpenClaw 仍会在 npm 上发布一些 OpenClaw 自有的 `@openclaw/*` 插件包；在不同插件发布批次之间，这些包版本可能落后于内置源码。如果 npm 将某个 OpenClaw 自有插件包报告为已弃用，则该已发布版本是旧的外部制品；请使用当前 OpenClaw 内置的插件或本地 checkout，直到发布更新的 npm 包。 - 如果你的 `plugins` 区段由单文件 `$include` 支持，`plugins install/update/enable/disable/uninstall` 会写入该被包含的文件，并保持 `openclaw.json` 不变。根级 include、include 数组以及带有同级覆盖项的 include 会失败关闭，而不是被展平。有关支持的形态，请参阅 [配置 include](/zh-CN/gateway/configuration)。 + 如果你的 `plugins` 段由单文件 `$include` 支持，`plugins install/update/enable/disable/uninstall` 会写入该 include 文件，并保持 `openclaw.json` 不变。根 include、include 数组以及带有同级覆盖项的 include 会封闭失败，而不是展开。有关支持的形状，请参见[配置 include](/zh-CN/gateway/configuration)。 - 如果安装期间配置无效，`plugins install` 通常会失败关闭，并提示你先运行 `openclaw doctor --fix`。在 Gateway 网关启动期间，某个插件的无效配置会被隔离到该插件，使其他渠道和插件可以继续运行；`openclaw doctor --fix` 可以隔离该无效插件条目。唯一有文档说明的安装时例外，是一个窄范围的内置插件恢复路径，适用于明确选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。 + 如果安装期间配置无效，`plugins install` 通常会封闭失败，并提示你先运行 `openclaw doctor --fix`。在 Gateway 网关启动期间，某个插件的无效配置会隔离到该插件，因此其他渠道和插件可以继续运行；`openclaw doctor --fix` 可以隔离无效的插件条目。唯一有文档说明的安装时例外，是一个针对明确选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件的窄范围内置插件恢复路径。 - - `--force` 会复用现有安装目标，并就地覆盖已经安装的插件或钩子包。当你有意从新的本地路径、归档、ClawHub 包或 npm 产物重新安装同一个 id 时使用它。对于已跟踪 npm 插件的常规升级，请优先使用 `openclaw plugins update `。 + + `--force` 会复用现有安装目标，并就地覆盖已安装的插件或钩子包。当你有意从新的本地路径、归档、ClawHub 包或 npm 制品重新安装同一 id 时使用它。对于已跟踪 npm 插件的常规升级，优先使用 `openclaw plugins update `。 - 如果你对已经安装的插件 id 运行 `plugins install`，OpenClaw 会停止，并提示你使用 `plugins update ` 进行正常升级，或者在你确实想从不同来源覆盖当前安装时使用 `plugins install --force`。 + 如果你对已经安装的插件 id 运行 `plugins install`，OpenClaw 会停止，并提示你使用 `plugins update ` 执行正常升级；如果你确实想从不同来源覆盖当前安装，则使用 `plugins install --force`。 - `--pin` 仅适用于 npm 安装。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。 + `--pin` 仅适用于 npm 安装。它不支持 `git:` 安装；当你需要固定源码时，请使用显式 git ref，例如 `git:github.com/acme/plugin@v1.2.3`。它不支持 `--marketplace`，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。 - `--dangerously-force-unsafe-install` 是一个应急选项，用于内置危险代码扫描器误报的情况。即使内置扫描器报告 `critical` 发现，它也允许安装继续，但它**不会**绕过插件 `before_install` 钩子策略阻断，也**不会**绕过扫描失败。 + `--dangerously-force-unsafe-install` 是用于内置危险代码扫描器误报的破窗选项。即使内置扫描器报告 `critical` 发现项，它也允许安装继续，但它**不会**绕过插件 `before_install` 钩子策略拦截，也**不会**绕过扫描失败。 - 此 CLI 标志适用于插件 install/update 流程。由 Gateway 网关支持的 skill 依赖安装使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖项，而 `openclaw skills install` 仍然是独立的 ClawHub skill 下载/安装流程。 + 此 CLI 标志适用于插件 install/update 流程。由 Gateway 网关支持的 skill 依赖安装使用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是独立的 ClawHub skill 下载/安装流程。 - 如果你发布到 ClawHub 的插件被 registry 扫描阻断，请使用 [ClawHub](/zh-CN/tools/clawhub) 中的发布者步骤。 + 如果你发布在 ClawHub 上的插件被 registry 扫描拦截，请使用 [ClawHub](/zh-CN/tools/clawhub) 中的发布者步骤。 - - `plugins install` 也是安装钩子包的入口，这类钩子包会在 `package.json` 中暴露 `openclaw.hooks`。请使用 `openclaw hooks` 查看过滤后的钩子可见性和按钩子启用状态，而不是用于包安装。 + + `plugins install` 也是安装在 `package.json` 中暴露 `openclaw.hooks` 的钩子包的界面。请使用 `openclaw hooks` 查看筛选后的钩子可见性和按钩子启用，而不是用于包安装。 - npm specs **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file specs 和 semver ranges 会被拒绝。为了安全，即使你的 shell 有全局 npm 安装设置，依赖安装也会在项目本地以 `--ignore-scripts` 运行。 + Npm spec **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。为安全起见，即使你的 shell 有全局 npm 安装设置，依赖安装也会在项目本地使用 `--ignore-scripts` 运行。 - 当你想跳过 ClawHub 查找并直接从 npm 安装时，请使用 `npm:`。裸包 specs 仍会优先使用 ClawHub，只有在 ClawHub 没有该包或版本时才回退到 npm。 + 当你想跳过 ClawHub 查找并直接从 npm 安装时，请使用 `npm:`。裸包 spec 仍会优先使用 ClawHub，并且只有在 ClawHub 没有该包或版本时才回退到 npm。 - 裸 specs 和 `@latest` 会停留在稳定轨道。如果 npm 将其中任一项解析为预发布版本，OpenClaw 会停止并要求你使用预发布标签（如 `@beta`/`@rc`）或精确预发布版本（如 `@1.2.3-beta.4`）显式选择加入。 + 裸 spec 和 `@latest` 保持在稳定轨道。如果 npm 将两者之一解析为预发布版本，OpenClaw 会停止，并要求你使用预发布标签（例如 `@beta`/`@rc`）或精确的预发布版本（例如 `@1.2.3-beta.4`）显式选择加入。 - 如果裸安装 spec 匹配内置插件 id（例如 `diffs`），OpenClaw 会直接安装内置插件。若要安装同名 npm 包，请使用显式 scoped spec（例如 `@scope/diffs`）。 + 如果裸安装 spec 匹配内置插件 id（例如 `diffs`），OpenClaw 会直接安装内置插件。要安装同名 npm 包，请使用显式 scoped spec（例如 `@scope/diffs`）。 + + + + 使用 `git:` 可直接从 git 仓库安装。支持的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整的 `https://`、`ssh://`、`git://`、`file://`，以及 `git@host:owner/repo.git` clone URL。添加 `@` 或 `#` 可在安装前 checkout 分支、标签或 commit。 + + Git 安装会 clone 到临时目录，在存在请求的 ref 时将其 checkout，然后使用常规插件目录安装器。这意味着清单校验、危险代码扫描、运行时依赖 staging 和安装记录的行为都与本地路径安装一致。记录的 git 安装包含来源 URL/ref 以及解析后的 commit，因此 `openclaw plugins update` 稍后可以重新解析来源。 + + 从 git 安装后，请使用 `openclaw plugins inspect --runtime --json` 验证运行时注册，例如 gateway 方法和 CLI 命令。如果插件通过 `api.registerCli` 注册了 CLI 根，请直接通过 OpenClaw 根 CLI 执行该命令，例如 `openclaw demo-plugin ping`。 支持的归档：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw 插件归档必须在解压后的插件根目录包含有效的 `openclaw.plugin.json`；只包含 `package.json` 的归档会在 OpenClaw 写入安装记录前被拒绝。 - 也支持 Claude marketplace 安装。 + 同时支持 Claude marketplace 安装。 -ClawHub 安装使用显式 `clawhub:` 定位符： +ClawHub 安装使用显式 `clawhub:` 定位器： ```bash openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -OpenClaw 现在也会优先为裸 npm 安全插件 specs 使用 ClawHub。只有在 ClawHub 没有该包或版本时，它才回退到 npm： +OpenClaw 现在也会优先为裸 npm 安全插件 spec 使用 ClawHub。只有在 ClawHub 没有该包或版本时，才会回退到 npm： ```bash openclaw plugins install openclaw-codex-app-server ``` -使用 `npm:` 可强制仅使用 npm 解析，例如当 ClawHub 无法访问，或你知道该包只存在于 npm 上时： +使用 `npm:` 可强制仅通过 npm 解析，例如当 ClawHub 不可访问，或你知道该包只存在于 npm 上时： ```bash openclaw plugins install npm:openclaw-codex-app-server openclaw plugins install npm:@scope/plugin-name@1.0.1 ``` -OpenClaw 会从 ClawHub 下载包归档，检查声明的插件 API / 最低 gateway 兼容性，然后通过正常归档路径安装。记录的安装会保留其 ClawHub 来源元数据，以供以后更新。 -未指定版本的 ClawHub 安装会保留未指定版本的记录 spec，因此 `openclaw plugins update` 可以跟随后续较新的 ClawHub 发布；显式版本或标签选择器（如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）仍会固定到该选择器。 +OpenClaw 会从 ClawHub 下载包归档，检查其声明的插件 API / 最低 gateway 兼容性，然后通过常规归档路径安装。记录的安装会保留其 ClawHub 来源元数据，以供后续更新使用。 +未指定版本的 ClawHub 安装会保留未指定版本的记录 spec，因此 `openclaw plugins update` 可以跟随后续的 ClawHub 新版本；显式版本或标签选择器（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）仍固定到该选择器。 #### Marketplace 简写 @@ -180,27 +190,27 @@ openclaw plugins install --marketplace ./my-marketplace - - 来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude known-marketplace 名称 + - 来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称 - 本地 marketplace 根目录或 `marketplace.json` 路径 - - GitHub repo 简写，例如 `owner/repo` - - GitHub repo URL，例如 `https://github.com/owner/repo` + - GitHub 仓库简写，例如 `owner/repo` + - GitHub 仓库 URL，例如 `https://github.com/owner/repo` - git URL - 对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保留在克隆的 marketplace repo 内。OpenClaw 接受来自该 repo 的相对路径来源，并拒绝来自远程清单的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径插件来源。 + 对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保留在 clone 的 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` / 清单声明的 `lspServers` 默认值、Cursor command-skills 以及兼容的 Codex 钩子目录；其他检测到的捆绑包能力会显示在诊断/info 中，但尚未接入运行时执行。 +兼容包会安装到普通插件根目录，并参与同一套列表/信息/启用/禁用流程。目前支持包内 Skills、Claude 命令 Skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor 命令 Skills，以及兼容的 Codex 钩子目录；其他检测到的包能力会显示在诊断/信息中，但尚未接入运行时执行。 ### 列表 @@ -216,45 +226,41 @@ openclaw plugins list --json 仅显示已启用的插件。 - 从表格视图切换为逐插件详情行，显示来源/origin/版本/激活元数据。 + 从表格视图切换为每个插件一行的详细信息，包含来源/源头/版本/激活元数据。 - 机器可读的 inventory 以及 registry 诊断。 + 机器可读的清单加注册表诊断信息。 -`plugins list` 会先读取持久化的本地插件注册表；当注册表缺失或无效时，会使用仅由 manifest 派生的回退结果。它适合用于检查插件是否已安装、已启用，并且对冷启动规划可见，但它不是对已在运行的 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、钩子策略或 `plugins.load.paths` 后，请先重启为该渠道提供服务的 Gateway 网关，再期待新的 `register(api)` 代码或钩子运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不只是包装器进程。 +`plugins list` 会先读取持久化的本地插件注册表；当注册表缺失或无效时，使用仅基于清单派生的回退。它适合检查插件是否已安装、已启用，并且对冷启动规划可见，但它不是对已经运行的 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、钩子策略或 `plugins.load.paths` 后，请重启为该渠道提供服务的 Gateway 网关，再期待新的 `register(api)` 代码或钩子运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不只是包装进程。 -对于打包 Docker 镜像内的内置插件工作，请将插件 -源码目录 bind-mount 到匹配的打包源码路径上，例如 -`/app/extensions/synology-chat`。OpenClaw 会先于 `/app/dist/extensions/synology-chat` 发现该挂载的源码 -覆盖层；普通复制的源码 -目录仍不会生效，因此正常打包安装仍会使用已编译的 dist。 +在打包的 Docker 镜像内处理内置插件时，将插件源目录绑定挂载到匹配的打包源路径上，例如 `/app/extensions/synology-chat`。OpenClaw 会先发现这个挂载的源码覆盖层，再发现 `/app/dist/extensions/synology-chat`；单纯复制进去的源码目录会保持不生效，因此普通打包安装仍会使用编译后的 dist。 -对于运行时钩子调试： +用于运行时钩子调试： -- `openclaw plugins inspect --runtime --json` 会显示来自一次模块加载检查过程的已注册钩子和诊断信息。运行时检查绝不会下载缺失的内置运行时依赖；需要修复时请使用 `openclaw plugins deps --repair`。 -- `openclaw gateway status --deep --require-rpc` 会确认可访问的 Gateway 网关、服务/进程提示、配置路径和 RPC 健康状态。 +- `openclaw plugins inspect --runtime --json` 会显示来自一次模块加载检查过程的已注册钩子和诊断信息。运行时检查绝不会下载缺失的内置运行时依赖；需要修复时使用 `openclaw plugins deps --repair`。 +- `openclaw gateway status --deep --require-rpc` 会确认可访问的 Gateway 网关、服务/进程提示、配置路径以及 RPC 健康状态。 - 非内置会话钩子（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）需要 `plugins.entries..hooks.allowConversationAccess=true`。 -使用 `--link` 避免复制本地目录（会添加到 `plugins.load.paths`）： +使用 `--link` 可避免复制本地目录（会添加到 `plugins.load.paths`）： ```bash openclaw plugins install -l ./my-plugin ``` -`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源码路径，而不是覆盖托管安装目标。 +`--force` 不支持与 `--link` 一起使用，因为链接式安装会复用源路径，而不是覆盖托管安装目标。 -在 npm 安装时使用 `--pin`，可将解析出的精确 spec（`name@version`）保存到托管插件索引，同时保持默认行为为不固定版本。 +在 npm 安装中使用 `--pin`，可以将解析后的精确规格（`name@version`）保存到托管插件索引中，同时保持默认行为为不固定版本。 ### 插件索引 -插件安装元数据是机器管理的状态，而不是用户配置。安装和更新会将它写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。其顶层 `installRecords` map 是安装元数据的持久来源，包括损坏或缺失插件 manifest 的记录。`plugins` 数组是由 manifest 派生的冷注册表缓存。该文件包含“请勿编辑”警告，并由 `openclaw plugins update`、卸载、诊断以及冷插件注册表使用。 +插件安装元数据是机器管理的状态，而不是用户配置。安装和更新会将其写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。其顶层 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件清单的记录。`plugins` 数组是从清单派生的冷注册表缓存。该文件包含请勿编辑警告，并被 `openclaw plugins update`、卸载、诊断和冷插件注册表使用。 -当 OpenClaw 在配置中看到已发布的旧版 `plugins.installs` 记录时，会将它们移动到插件索引，并移除该配置键；如果任一写入失败，则会保留配置记录，确保安装元数据不会丢失。 +当 OpenClaw 在配置中看到已发布的旧版 `plugins.installs` 记录时，会将它们移动到插件索引，并移除该配置键；如果任一写入失败，配置记录会被保留，以免安装元数据丢失。 ### 运行时依赖 @@ -265,11 +271,11 @@ openclaw plugins deps --prune openclaw plugins deps --json ``` -`plugins deps` 会检查由插件配置、已启用/已配置渠道、已配置模型提供商或内置 manifest 默认值所选中的 OpenClaw 自有内置插件的打包运行时依赖阶段。它不是第三方 npm 或 ClawHub 插件的安装/更新路径。 +`plugins deps` 会检查由插件配置、已启用/已配置渠道、已配置模型提供商或内置清单默认值选中的 OpenClaw 自有内置插件的打包运行时依赖阶段。它不是第三方 npm 或 ClawHub 插件的安装/更新路径。 -当打包安装在 Gateway 网关启动或 `plugins doctor` 期间报告缺失内置运行时依赖时，请使用 `--repair`。修复只会在禁用生命周期脚本的情况下安装缺失的已启用内置插件依赖。使用 `--prune` 可移除旧版打包布局遗留的陈旧未知外部运行时依赖根目录。 +当打包安装在 Gateway 网关启动或 `plugins doctor` 期间报告缺失内置运行时依赖时，使用 `--repair`。修复只会在禁用生命周期脚本的情况下安装缺失的已启用内置插件依赖。使用 `--prune` 可移除旧版打包布局遗留的陈旧未知外部运行时依赖根目录。 -完整的计划、暂存和修复生命周期见[插件依赖解析](/zh-CN/plugins/dependency-resolution)。 +有关完整计划、暂存和修复生命周期，请参阅 [插件依赖解析](/zh-CN/plugins/dependency-resolution)。 ### 卸载 @@ -279,10 +285,10 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` 会从 `plugins.entries`、持久化插件索引、插件 allow/deny 列表条目，以及适用时的已链接 `plugins.load.paths` 条目中移除插件记录。除非设置了 `--keep-files`，否则卸载还会在受跟踪的托管安装目录位于 OpenClaw 插件扩展根目录内时移除该目录。对于主动记忆插件，记忆槽位会重置为 `memory-core`。 +`uninstall` 会在适用时从 `plugins.entries`、持久化插件索引、插件允许/拒绝列表条目以及链接的 `plugins.load.paths` 条目中移除插件记录。除非设置了 `--keep-files`，否则卸载还会在被跟踪的托管安装目录位于 OpenClaw 插件扩展根目录内时移除该目录。对于主动记忆插件，记忆槽会重置为 `memory-core`。 -`--keep-config` 作为已弃用的 `--keep-files` 别名受支持。 +`--keep-config` 作为 `--keep-files` 的已弃用别名受支持。 ### 更新 @@ -295,25 +301,25 @@ openclaw plugins update @openclaw/voice-call@beta openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -更新适用于托管插件索引中受跟踪的插件安装，以及 `hooks.internal.installs` 中受跟踪的 hook-pack 安装。 +更新会应用于托管插件索引中被跟踪的插件安装，以及 `hooks.internal.installs` 中被跟踪的钩子包安装。 - - 当你传入插件 id 时，OpenClaw 会复用该插件记录的安装 spec。这意味着先前存储的 dist-tag（例如 `@beta`）和精确固定版本会在之后的 `update ` 运行中继续使用。 + + 当你传入插件 id 时，OpenClaw 会复用该插件记录的安装规格。这意味着之前存储的 dist-tags（例如 `@beta`）和精确固定版本，会在后续 `update ` 运行中继续使用。 - 对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会将该包名解析回受跟踪的插件记录，更新已安装的插件，并记录新的 npm spec 以供未来基于 id 的更新使用。 + 对于 npm 安装，你也可以传入带 dist-tag 或精确版本的显式 npm 包规格。OpenClaw 会将该包名解析回被跟踪的插件记录，更新该已安装插件，并记录新的 npm 规格，供以后基于 id 的更新使用。 - 传入不带版本或标签的 npm 包名也会解析回受跟踪的插件记录。当某个插件被固定到精确版本，而你想将其移回注册表默认发布线时，请使用这种方式。 + 传入不带版本或标签的 npm 包名，也会解析回被跟踪的插件记录。当某个插件已固定到精确版本，而你想把它移回注册表默认发布线时，请使用这种方式。 - - 在实时 npm 更新之前，OpenClaw 会根据 npm 注册表元数据检查已安装的包版本。如果已安装版本和记录的 artifact 身份已经与解析出的目标匹配，则会跳过更新，不下载、不重新安装，也不重写 `openclaw.json`。 + + 在实时 npm 更新之前，OpenClaw 会根据 npm 注册表元数据检查已安装包版本。如果已安装版本和记录的工件身份已经匹配解析后的目标，更新会被跳过，不会下载、重新安装或重写 `openclaw.json`。 - 当存在已存储的完整性哈希且获取到的 artifact 哈希发生变化时，OpenClaw 会将其视为 npm artifact 漂移。交互式 `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` 策略阻断或扫描失败阻断，并且它只适用于插件更新，不适用于钩子包更新。 @@ -325,19 +331,21 @@ openclaw plugins inspect --runtime openclaw plugins inspect --json ``` -默认情况下，检查会显示身份、加载状态、来源、manifest 能力、策略标志、诊断信息、安装元数据、bundle 能力，以及任何检测到的 MCP 或 LSP 服务器支持，而不会导入插件运行时。添加 `--runtime` 可加载插件模块，并包含已注册钩子、工具、命令、服务、Gateway 网关方法和 HTTP 路由。当内置运行时依赖缺失时，运行时检查会失败并给出修复提示；请使用 `openclaw plugins deps --repair` 显式修复它们。 +默认情况下，检查会显示身份、加载状态、来源、清单能力、策略标志、诊断、安装元数据、包能力，以及任何检测到的 MCP 或 LSP 服务器支持，而不会导入插件运行时。添加 `--runtime` 可加载插件模块，并包含已注册钩子、工具、命令、服务、Gateway 网关方法和 HTTP 路由。当缺少内置运行时依赖时，运行时检查会失败并给出修复提示；使用 `openclaw plugins deps --repair` 可显式修复它们。 -每个插件会根据其在运行时实际注册的内容分类： +插件拥有的 CLI 命令会作为根级 `openclaw` 命令组安装。当 `inspect --runtime` 在 `cliCommands` 下显示某个命令后，将其作为 `openclaw ...` 运行；例如，注册了 `demo-git` 的插件可以用 `openclaw demo-git ping` 验证。 -- **plain-capability** — 一种能力类型（例如仅 provider 的插件） +每个插件都会按其在运行时实际注册的内容分类： + +- **plain-capability** — 一种能力类型（例如仅提供商插件） - **hybrid-capability** — 多种能力类型（例如文本 + 语音 + 图像） -- **hook-only** — 只有钩子，没有能力或表面 +- **hook-only** — 只有钩子，没有能力或界面 - **non-capability** — 有工具/命令/服务，但没有能力 -有关能力模型的更多信息，请参阅[插件形态](/zh-CN/plugins/architecture#plugin-shapes)。 +有关能力模型的更多信息，请参阅 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。 -`--json` 标志会输出适合脚本和审计的机器可读报告。`inspect --all` 会渲染一个全局表格，其中包含形态、能力类型、兼容性通知、bundle 能力和钩子摘要列。`info` 是 `inspect` 的别名。 +`--json` 标志会输出适合脚本和审计的机器可读报告。`inspect --all` 会渲染一个全量表格，其中包含形态、能力种类、兼容性通知、包能力和钩子摘要列。`info` 是 `inspect` 的别名。 ### Doctor @@ -346,9 +354,9 @@ 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` 重新运行，以便在诊断输出中包含紧凑的导出形态摘要。 ### 注册表 @@ -358,24 +366,24 @@ openclaw plugins registry --refresh openclaw plugins registry --json ``` -本地插件注册表是 OpenClaw 的持久化冷读取模型，用于已安装插件身份、启用状态、来源元数据和贡献归属。正常启动、provider 所有者查找、渠道设置分类和插件清单都可以在不导入插件运行时模块的情况下读取它。 +本地插件注册表是 OpenClaw 为已安装插件身份、启用状态、来源元数据和贡献归属持久化的冷读取模型。普通启动、提供商所有者查找、渠道设置分类和插件清单都可以读取它，而无需导入插件运行时模块。 -使用 `plugins registry` 检查持久化注册表是否存在、是否当前有效或是否陈旧。使用 `--refresh` 可根据持久化插件索引、配置策略和 manifest/package 元数据重建它。这是修复路径，不是运行时激活路径。 +使用 `plugins registry` 检查持久化注册表是否存在、是否最新或是否陈旧。使用 `--refresh` 可基于持久化插件索引、配置策略以及清单/包元数据重建它。这是修复路径，而不是运行时激活路径。 -`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是已弃用的应急兼容性开关，用于注册表读取失败。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；该环境变量回退只用于迁移推出期间的紧急启动恢复。 +`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是已弃用的破窗兼容开关，用于注册表读取失败。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；该环境变量回退仅用于迁移推出期间的紧急启动恢复。 -### 市场 +### 插件市场 ```bash openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -市场列表接受本地市场路径、`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL 或 git URL。`--json` 会打印解析后的来源标签，以及解析出的市场 manifest 和插件条目。 +插件市场列表接受本地插件市场路径、`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。`--json` 会打印解析后的来源标签，以及解析出的插件市场清单和插件条目。 -## 相关 +## 相关内容 - [构建插件](/zh-CN/plugins/building-plugins) - [CLI 参考](/zh-CN/cli) diff --git a/docs/zh-CN/plugins/building-plugins.md b/docs/zh-CN/plugins/building-plugins.md index 4591309d6..50d6e6a7e 100644 --- a/docs/zh-CN/plugins/building-plugins.md +++ b/docs/zh-CN/plugins/building-plugins.md @@ -7,21 +7,21 @@ sidebarTitle: Getting Started summary: 几分钟内创建你的第一个 OpenClaw 插件 title: 构建插件 x-i18n: - generated_at: "2026-04-29T05:40:27Z" + generated_at: "2026-05-01T10:03:21Z" model: gpt-5.5 provider: openai - source_hash: 321f8870d0ce3be8dece21b07815eda6859dcb00941d9181d913b95f3d74d230 + source_hash: 5c80b831161c93b0a7f65baf1ccea705ccc27b8226180c0fd0ef15fbbefa3d83 source_path: plugins/building-plugins.md workflow: 16 --- -插件通过新能力扩展 OpenClaw：渠道、模型提供商、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页获取、Web 搜索、智能体工具，或任意组合。 +插件通过新功能扩展 OpenClaw：渠道、模型提供商、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索、智能体工具，或任意组合。 -你不需要把你的插件添加到 OpenClaw 仓库。发布到 -[ClawHub](/zh-CN/tools/clawhub)，用户通过 -`openclaw plugins install ` 安装。OpenClaw 会先尝试 ClawHub，并对仍使用 npm 分发的软件包自动回退到 npm。 +你无需将你的插件添加到 OpenClaw 仓库。发布到 +[ClawHub](/zh-CN/tools/clawhub)，用户即可使用 +`openclaw plugins install ` 安装。OpenClaw 会先尝试 ClawHub，并会对仍使用 npm 分发的软件包自动回退到 npm。 -## 前置条件 +## 前提条件 - Node >= 22 和一个包管理器（npm 或 pnpm） - 熟悉 TypeScript（ESM） @@ -41,13 +41,13 @@ x-i18n: -对于不能保证在新手引导/设置运行时已安装的渠道插件，请使用 -`openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。 -它会生成一个设置适配器 + 向导组合，用于提示安装要求，并在插件安装之前对真实配置写入采取失败关闭策略。 +对于不能保证在新手引导/设置运行时已安装的渠道插件，请使用来自 +`openclaw/plugin-sdk/channel-setup` 的 `createOptionalChannelSetupSurface(...)`。它会生成一组设置适配器 + 向导， +用于提示安装要求，并在插件安装前对真实配置写入采用失败关闭策略。 ## 快速开始：工具插件 -本演练会创建一个注册智能体工具的最小插件。渠道插件和提供商插件有上方链接中的专门指南。 +本演练会创建一个注册智能体工具的最小插件。渠道插件和提供商插件有上方链接的专门指南。 @@ -87,11 +87,10 @@ x-i18n: ``` - 每个插件都需要清单，即使没有配置；每个插件也都应有意声明 - `activation.onStartup`。运行时注册的工具需要启动时导入，所以此示例将其设为 - `true`。完整 schema 请参阅 - [清单](/zh-CN/plugins/manifest)。规范的 ClawHub 发布片段位于 - `docs/snippets/plugin-publish/`。 + 每个插件都需要清单，即使没有配置也一样；每个插件也应有意声明 + `activation.onStartup`。运行时注册的工具需要启动时导入，因此本示例将它设为 `true`。请参阅 + [清单](/zh-CN/plugins/manifest) 了解完整 schema。规范的 ClawHub + 发布片段位于 `docs/snippets/plugin-publish/`。 @@ -120,14 +119,14 @@ x-i18n: ``` `definePluginEntry` 用于非渠道插件。对于渠道，请使用 - `defineChannelPluginEntry` — 参阅 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。 + `defineChannelPluginEntry` — 参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。 如需完整入口点选项，请参阅 [入口点](/zh-CN/plugins/sdk-entrypoints)。 - **外部插件：**使用 ClawHub 验证并发布，然后安装： + **外部插件：** 使用 ClawHub 验证并发布，然后安装： ```bash clawhub package publish your-org/your-plugin --dry-run @@ -135,9 +134,9 @@ x-i18n: openclaw plugins install clawhub:@myorg/openclaw-my-plugin ``` - 对于像 `@myorg/openclaw-my-plugin` 这样的裸包规格，OpenClaw 也会先检查 ClawHub，再检查 npm；对于尚未迁移到 ClawHub 的软件包，npm 仍是回退选项。 + 对于像 `@myorg/openclaw-my-plugin` 这样的裸包规格，OpenClaw 也会先检查 ClawHub 再检查 npm；对于尚未迁移到 ClawHub 的软件包，npm 仍是回退选项。 - **仓库内插件：**放在内置插件工作区树下 — 会被自动发现。 + **仓库内插件：** 放在内置插件工作区树下 — 会自动发现。 ```bash pnpm test -- /my-plugin/ @@ -156,14 +155,14 @@ x-i18n: | CLI 推理后端 | `api.registerCliBackend(...)` | [CLI 后端](/zh-CN/gateway/cli-backends) | | 渠道 / 消息 | `api.registerChannel(...)` | [渠道插件](/zh-CN/plugins/sdk-channel-plugins) | | 语音（TTS/STT） | `api.registerSpeechProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| 实时转写 | `api.registerRealtimeTranscriptionProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| 实时转录 | `api.registerRealtimeTranscriptionProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 实时语音 | `api.registerRealtimeVoiceProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 图像生成 | `api.registerImageGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 音乐生成 | `api.registerMusicGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 视频生成 | `api.registerVideoGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| 网页获取 | `api.registerWebFetchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Web 搜索 | `api.registerWebSearchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| 网页抓取 | `api.registerWebFetchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| 网页搜索 | `api.registerWebSearchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 工具结果中间件 | `api.registerAgentToolResultMiddleware(...)` | [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api) | | 智能体工具 | `api.registerTool(...)` | 下文 | | 自定义命令 | `api.registerCommand(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) | @@ -174,38 +173,34 @@ x-i18n: 如需完整注册 API，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api)。 -当内置插件需要在模型看到输出之前异步重写工具结果时，可以使用 -`api.registerAgentToolResultMiddleware(...)`。请在 -`contracts.agentToolResultMiddleware` 中声明目标运行时，例如 -`["pi", "codex"]`。这是一个可信的内置插件接口；除非 OpenClaw 为此能力扩展出明确的信任策略，否则外部插件应优先使用常规 OpenClaw 插件钩子。 +内置插件在需要模型看到输出前进行异步工具结果重写时，可以使用 `api.registerAgentToolResultMiddleware(...)`。请在 `contracts.agentToolResultMiddleware` 中声明目标运行时，例如 +`["pi", "codex"]`。这是受信任的内置插件 seam；外部插件应优先使用常规 OpenClaw 插件钩子，除非 OpenClaw 为此能力发展出明确的信任策略。 -如果你的插件注册自定义 Gateway 网关 RPC 方法，请把它们保留在 -插件专属前缀下。核心管理命名空间（`config.*`、 -`exec.approvals.*`、`wizard.*`、`update.*`）保持保留，并且始终解析到 -`operator.admin`，即使插件请求更窄的作用域也是如此。 +如果你的插件注册自定义 Gateway 网关 RPC 方法，请将它们放在插件特定前缀下。核心管理命名空间（`config.*`、 +`exec.approvals.*`、`wizard.*`、`update.*`）保持保留，并始终解析为 +`operator.admin`，即使插件请求更窄的范围也是如此。 -需要记住的钩子保护语义： +需要牢记的钩子保护语义： -- `before_tool_call`：`{ block: true }` 是终止决策，会停止优先级更低的处理程序。 -- `before_tool_call`：`{ block: false }` 会被视为未作出决策。 +- `before_tool_call`：`{ block: true }` 是终止性决定，会停止较低优先级处理器。 +- `before_tool_call`：`{ block: false }` 会被视为无决定。 - `before_tool_call`：`{ requireApproval: true }` 会暂停智能体执行，并通过 exec 审批覆盖层、Telegram 按钮、Discord 交互，或任意渠道上的 `/approve` 命令提示用户审批。 -- `before_install`：`{ block: true }` 是终止决策，会停止优先级更低的处理程序。 -- `before_install`：`{ block: false }` 会被视为未作出决策。 -- `message_sending`：`{ cancel: true }` 是终止决策，会停止优先级更低的处理程序。 -- `message_sending`：`{ cancel: false }` 会被视为未作出决策。 -- `message_received`：当你需要入站 thread/topic 路由时，优先使用带类型的 `threadId` 字段。将 `metadata` 保留给渠道专属附加项。 -- `message_sending`：优先使用带类型的 `replyToId` / `threadId` 路由字段，而不是渠道专属 metadata 键。 +- `before_install`：`{ block: true }` 是终止性决定，会停止较低优先级处理器。 +- `before_install`：`{ block: false }` 会被视为无决定。 +- `message_sending`：`{ cancel: true }` 是终止性决定，会停止较低优先级处理器。 +- `message_sending`：`{ cancel: false }` 会被视为无决定。 +- `message_received`：当你需要入站线程/话题路由时，优先使用类型化的 `threadId` 字段。将 `metadata` 保留用于渠道特定的额外信息。 +- `message_sending`：优先使用类型化的 `replyToId` / `threadId` 路由字段，而不是渠道特定的 metadata 键。 -`/approve` 命令会通过有界回退同时处理 exec 和插件审批：当找不到 exec 审批 id 时，OpenClaw 会用同一个 id 通过插件审批重试。插件审批转发可以通过配置中的 `approvals.plugin` 独立配置。 +`/approve` 命令通过有界回退同时处理 exec 和插件审批：当找不到 exec 审批 id 时，OpenClaw 会用同一 id 通过插件审批重试。插件审批转发可在配置中通过 `approvals.plugin` 独立配置。 -如果自定义审批管道需要检测同一个有界回退情况，请优先使用 -`openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，而不是手动匹配审批过期字符串。 +如果自定义审批 plumbing 需要检测同一个有界回退场景，请优先使用来自 `openclaw/plugin-sdk/error-runtime` 的 `isApprovalNotFoundError`，而不是手动匹配审批过期字符串。 -示例和钩子参考请参阅 [插件钩子](/zh-CN/plugins/hooks)。 +请参阅 [插件钩子](/zh-CN/plugins/hooks) 获取示例和钩子参考。 ## 注册智能体工具 -工具是 LLM 可以调用的带类型函数。它们可以是必需的（始终可用），也可以是可选的（用户选择启用）： +工具是 LLM 可以调用的类型化函数。它们可以是必需的（始终可用）或可选的（用户选择启用）： ```typescript register(api) { @@ -243,10 +238,50 @@ register(api) { ``` - 工具名称不得与核心工具冲突（冲突项会被跳过） -- 注册对象格式错误的工具，包括缺少 `parameters` 的工具，会被跳过并在插件诊断中报告，而不是破坏智能体运行 -- 对于有副作用或额外二进制要求的工具，请使用 `optional: true` +- 包含缺失 `parameters` 在内，注册对象格式错误的工具会被跳过并在插件诊断中报告，而不会中断智能体运行 +- 对有副作用或额外二进制要求的工具使用 `optional: true` - 用户可以通过将插件 id 添加到 `tools.allow` 来启用某个插件的所有工具 +## 注册 CLI 命令 + +插件可以使用 `api.registerCli` 添加根 `openclaw` 命令组。请为每个顶层命令根提供 +`descriptors`，这样 OpenClaw 就能显示并路由命令，而无需急切加载每个插件运行时。 + +```typescript +register(api) { + api.registerCli( + ({ program }) => { + const demo = program + .command("demo-plugin") + .description("Run demo plugin commands"); + + demo + .command("ping") + .description("Check that the plugin CLI is executable") + .action(() => { + console.log("demo-plugin:pong"); + }); + }, + { + descriptors: [ + { + name: "demo-plugin", + description: "Run demo plugin commands", + hasSubcommands: true, + }, + ], + }, + ); +} +``` + +安装后，验证运行时注册并执行命令： + +```bash +openclaw plugins inspect demo-plugin --runtime --json +openclaw demo-plugin ping +``` + ## 导入约定 始终从聚焦的 `openclaw/plugin-sdk/` 路径导入： @@ -259,28 +294,23 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { ... } from "openclaw/plugin-sdk"; ``` -完整子路径参考请参见 [SDK 概览](/zh-CN/plugins/sdk-overview)。 +完整的子路径参考见 [SDK 概览](/zh-CN/plugins/sdk-overview)。 -在你的插件内，使用本地 barrel 文件（`api.ts`、`runtime-api.ts`）进行 -内部导入，不要通过其 SDK 路径导入你自己的插件。 +在你的插件内，使用本地桶文件（`api.ts`、`runtime-api.ts`）进行内部导入，不要通过它的 SDK 路径导入你自己的插件。 -对于提供商插件，除非接缝确实是通用的，否则将提供商特定的辅助工具保留在这些包根 -barrel 中。当前内置示例： +对于提供商插件，除非接口确实是通用的，否则应将提供商专用 helper 保留在这些包根桶文件中。当前内置示例： -- Anthropic：Claude 流包装器以及 `service_tier` / beta 辅助工具 -- OpenAI：提供商构建器、默认模型辅助工具、实时提供商 -- OpenRouter：提供商构建器以及新手引导/配置辅助工具 +- Anthropic：Claude 流包装器和 `service_tier` / beta helper +- OpenAI：提供商构建器、默认模型 helper、实时提供商 +- OpenRouter：提供商构建器以及新手引导/配置 helper -如果某个辅助工具只在一个内置提供商包内有用，请将其保留在该 -包根接缝上，而不是提升到 `openclaw/plugin-sdk/*` 中。 +如果某个 helper 只在一个内置提供商包内部有用，请将它保留在该包根接口上，而不是提升到 `openclaw/plugin-sdk/*` 中。 -一些生成的 `openclaw/plugin-sdk/` 辅助接缝仍然存在，用于 -内置插件维护，前提是它们有已跟踪的所有者用法。请将这些视为 -保留表面，而不是新第三方插件的默认模式。 +一些生成的 `openclaw/plugin-sdk/` helper 接口仍然存在，用于在有已跟踪的所有者使用时维护内置插件。请将这些视为保留表面，而不是新第三方插件的默认模式。 ## 提交前检查清单 -**package.json** 具有正确的 `openclaw` 元数据 +**package.json** 有正确的 `openclaw` 元数据 **openclaw.plugin.json** 清单存在且有效 入口点使用 `defineChannelPluginEntry` 或 `definePluginEntry` 所有导入都使用聚焦的 `plugin-sdk/` 路径 @@ -290,12 +320,12 @@ barrel 中。当前内置示例： ## Beta 版本测试 -1. 关注 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub 发布标签，并通过 `Watch` > `Releases` 订阅。Beta 标签类似于 `v2026.3.N-beta.1`。你也可以为官方 OpenClaw X 账号 [@openclaw](https://x.com/openclaw) 开启通知，以接收发布公告。 +1. 关注 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub 发布标签，并通过 `Watch` > `Releases` 订阅。Beta 标签类似 `v2026.3.N-beta.1`。你也可以开启官方 OpenClaw X 账号 [@openclaw](https://x.com/openclaw) 的通知，以接收发布公告。 2. Beta 标签一出现，就用它测试你的插件。稳定版发布前的窗口通常只有几个小时。 -3. 测试后，在 `plugin-forum` Discord 渠道中你的插件讨论串里发布 `all good` 或说明哪里出问题。如果你还没有讨论串，请创建一个。 -4. 如果出现问题，请打开或更新一个标题为 `Beta blocker: - ` 的 issue，并应用 `beta-blocker` 标签。将 issue 链接放入你的讨论串。 -5. 打开一个指向 `main` 的 PR，标题为 `fix(): beta blocker - `，并在 PR 和你的 Discord 讨论串中都链接该 issue。贡献者无法给 PR 加标签，因此标题是给维护者和自动化使用的 PR 侧信号。有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题可能仍会随版本发布。维护者会在 Beta 测试期间关注这些讨论串。 -6. 沉默意味着绿色。如果你错过窗口，你的修复很可能会进入下一个周期。 +3. 测试后，在 `plugin-forum` Discord 渠道中你的插件主题帖里发布 `all good` 或说明损坏的内容。如果还没有主题帖，请创建一个。 +4. 如果有内容损坏，请打开或更新标题为 `Beta blocker: - ` 的 issue，并添加 `beta-blocker` 标签。将 issue 链接放到你的主题帖中。 +5. 打开一个指向 `main` 的 PR，标题为 `fix(): beta blocker - `，并在 PR 和你的 Discord 主题帖中都链接该 issue。贡献者不能给 PR 加标签，因此标题是面向维护者和自动化的 PR 侧信号。有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题可能仍会随版本发布。维护者会在 Beta 测试期间关注这些主题帖。 +6. 沉默表示绿色。如果错过窗口，你的修复很可能会进入下一个周期。 ## 后续步骤 @@ -309,8 +339,8 @@ barrel 中。当前内置示例： 导入映射和注册 API 参考 - - 通过 api.runtime 使用 TTS、搜索、子智能体 + + TTS、搜索、通过 api.runtime 使用子智能体 测试工具和模式 @@ -322,7 +352,7 @@ barrel 中。当前内置示例： ## 相关内容 -- [插件架构](/zh-CN/plugins/architecture) — 内部架构深入解析 +- [插件架构](/zh-CN/plugins/architecture) — 内部架构深度解析 - [SDK 概览](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考 - [清单](/zh-CN/plugins/manifest) — 插件清单格式 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件 diff --git a/docs/zh-CN/tools/plugin.md b/docs/zh-CN/tools/plugin.md index cdf433449..a80897047 100644 --- a/docs/zh-CN/tools/plugin.md +++ b/docs/zh-CN/tools/plugin.md @@ -2,35 +2,44 @@ read_when: - 安装或配置插件 - 了解插件发现和加载规则 - - 使用与 Codex/Claude 兼容的插件包 + - 使用兼容 Codex/Claude 的插件包 sidebarTitle: Install and Configure -summary: 安装、配置并管理 OpenClaw 插件 +summary: 安装、配置和管理 OpenClaw 插件 title: 插件 x-i18n: - generated_at: "2026-05-01T07:53:38Z" + generated_at: "2026-05-01T10:03:25Z" model: gpt-5.5 provider: openai - source_hash: 2df8aca086aafbd8f268820f1ccc2425079c69f1a673a4c2ea163aba1358ff51 + source_hash: 1efa91ac4d78c6707a1e9e5cd5a5958642128a61b5873e169f66c7c2b954adb9 source_path: tools/plugin.md workflow: 16 --- -插件通过新能力扩展 OpenClaw：渠道、模型提供商、agent harness、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页获取、网页搜索等。一些插件是 **core**（随 OpenClaw 一起提供），另一些是 **external**。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。Npm 仍支持直接安装，也暂时用于一组 OpenClaw 自有插件包，直到迁移完成。 +插件为 OpenClaw 扩展新能力：渠道、模型提供商、 +agent harnesses、工具、Skills、语音、实时转写、实时 +语音、媒体理解、图像生成、视频生成、网页获取、网页 +搜索等。有些插件是**核心**插件（随 OpenClaw 一起发布），其他 +是**外部**插件。大多数外部插件通过 +[ClawHub](/zh-CN/tools/clawhub) 发布和发现。Npm 仍然支持直接安装，也支持 +一组临时的 OpenClaw 自有插件包，直到该迁移完成。 ## 快速开始 - + ```bash openclaw plugins list ``` - + ```bash # From npm openclaw plugins install npm:@acme/openclaw-plugin + # From git + openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0 + # From a local directory or archive openclaw plugins install ./my-plugin openclaw plugins install ./my-plugin.tgz @@ -38,7 +47,7 @@ x-i18n: - + ```bash openclaw gateway restart ``` @@ -46,6 +55,20 @@ x-i18n: 然后在你的配置文件中的 `plugins.entries.\.config` 下配置。 + + + ```bash + openclaw plugins inspect --runtime --json + + # If the plugin registered a CLI root, run one command from that root. + openclaw --help + ``` + + 当你需要证明已注册的工具、服务、Gateway 网关 + 方法、钩子，或插件自有的 CLI 命令时，请使用 `--runtime`。普通的 + `inspect` 是冷态清单/注册表检查，并且会有意避免导入插件运行时。 + + 如果你偏好聊天原生控制，请启用 `commands.plugins: true` 并使用： @@ -56,19 +79,45 @@ x-i18n: /plugin enable ``` -安装路径使用与 CLI 相同的解析器：本地路径/归档、显式 `clawhub:`、显式 `npm:`，或裸包规范（先 ClawHub，再 npm 回退）。 +安装路径使用与 CLI 相同的解析器：本地路径/归档、显式 +`clawhub:`、显式 `npm:`、显式 `git:`，或裸包 +规范（先 ClawHub，再回退到 npm）。 -如果配置无效，安装通常会关闭失败，并提示你运行 `openclaw doctor --fix`。唯一的恢复例外是一条很窄的内置插件重装路径，仅适用于选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。 -在 Gateway 网关启动期间，某个插件的无效配置会被隔离到该插件：启动日志会记录 `plugins.entries..config` 问题，在加载时跳过该插件，并保持其他插件和渠道在线。运行 `openclaw doctor --fix` 可通过禁用该插件条目并移除其无效配置载荷，隔离有问题的插件配置；正常的配置备份会保留先前的值。 -当某个渠道配置引用了不再可发现的插件，但同一个陈旧插件 ID 仍保留在插件配置或安装记录中时，Gateway 网关启动会记录警告并跳过该渠道，而不是阻塞其他所有渠道。运行 `openclaw doctor --fix` 可移除陈旧的渠道/插件条目；没有陈旧插件证据的未知渠道键仍会导致验证失败，以便拼写错误保持可见。 -如果设置了 `plugins.enabled: false`，陈旧插件引用会被视为惰性：Gateway 网关启动会跳过插件发现/加载工作，`openclaw doctor` 会保留已禁用的插件配置，而不是自动移除它。如果你想移除陈旧插件 ID，请先重新启用插件，再运行 doctor 清理。 +如果配置无效，安装通常会失败关闭，并指向 +`openclaw doctor --fix`。唯一的恢复例外是一个狭窄的内置插件 +重装路径，适用于选择加入 +`openclaw.install.allowInvalidConfigRecovery` 的插件。 +在 Gateway 网关启动期间，某个插件的无效配置会被隔离到该插件： +启动会记录 `plugins.entries..config` 问题，在加载期间跳过该插件， +并让其他插件和渠道保持在线。运行 `openclaw doctor --fix` +可通过禁用该插件条目并移除其无效配置载荷来隔离损坏的插件配置； +常规配置备份会保留先前的值。 +当某个渠道配置引用了一个不再可发现的插件，但同一个过期插件 id +仍留在插件配置或安装记录中时，Gateway 网关启动会记录警告并跳过该渠道， +而不是阻塞所有其他渠道。运行 `openclaw doctor --fix` +以移除过期的渠道/插件条目；没有过期插件证据的未知渠道键仍会验证失败， +因此拼写错误仍然可见。 +如果设置了 `plugins.enabled: false`，过期插件引用会被视为惰性： +Gateway 网关启动会跳过插件发现/加载工作，并且 `openclaw doctor` +会保留已禁用的插件配置，而不是自动移除它。如果你想移除过期插件 id， +请先重新启用插件再运行 Doctor 清理。 -打包版 OpenClaw 安装不会急切安装每个内置插件的运行时依赖树。当 OpenClaw 自有内置插件通过插件配置、旧版渠道配置或默认启用的 manifest 处于活跃状态时，启动只会在导入该插件前修复该插件声明的运行时依赖。 -仅持久化的渠道认证状态不会为 Gateway 网关启动运行时依赖修复激活内置渠道。 -显式禁用仍然优先：`plugins.entries..enabled: false`、`plugins.deny`、`plugins.enabled: false` 和 `channels..enabled: false` 会阻止该插件/渠道的自动内置运行时依赖修复。 -非空的 `plugins.allow` 也会限定默认启用的内置运行时依赖修复；显式启用内置渠道（`channels..enabled: true`）仍可修复该渠道的插件依赖。 -外部插件和自定义加载路径仍必须通过 `openclaw plugins install` 安装。 -有关完整的规划和暂存生命周期，请参阅[插件依赖解析](/zh-CN/plugins/dependency-resolution)。 +打包的 OpenClaw 安装不会急切安装每个内置插件的 +运行时依赖树。当一个 OpenClaw 自有的内置插件因 +插件配置、旧版渠道配置，或默认启用的清单而处于活动状态时，启动 +只会在导入该插件前修复该插件声明的运行时依赖。 +仅有持久化的渠道认证状态不会为 Gateway 网关启动运行时依赖修复 +激活内置渠道。 +显式禁用仍然优先：`plugins.entries..enabled: false`、 +`plugins.deny`、`plugins.enabled: false` 和 `channels..enabled: false` +会阻止该插件/渠道的自动内置运行时依赖修复。 +非空的 `plugins.allow` 也会限制默认启用的内置运行时依赖 +修复；显式的内置渠道启用（`channels..enabled: true`）仍可 +修复该渠道的插件依赖。 +外部插件和自定义加载路径仍必须通过 +`openclaw plugins install` 安装。 +参见[插件依赖解析](/zh-CN/plugins/dependency-resolution)，了解完整的 +规划和暂存生命周期。 ## 插件类型 @@ -79,15 +128,22 @@ OpenClaw 识别两种插件格式： | **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 | | **Bundle** | Codex/Claude/Cursor 兼容布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` | -两者都会显示在 `openclaw plugins list` 下。有关 bundle 详情，请参阅[插件 Bundle](/zh-CN/plugins/bundles)。 +二者都会显示在 `openclaw plugins list` 下。参见 [Plugin Bundles](/zh-CN/plugins/bundles) 了解 Bundle 详情。 -如果你正在编写原生插件，请从[构建插件](/zh-CN/plugins/building-plugins)和[插件 SDK 概览](/zh-CN/plugins/sdk-overview)开始。 +如果你正在编写原生插件，请从[构建插件](/zh-CN/plugins/building-plugins) +和[插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。 ## 包入口点 -原生插件 npm 包必须在 `package.json` 中声明 `openclaw.extensions`。每个条目都必须保持在包目录内，并解析到可读的运行时文件，或解析到一个带有推断出的已构建 JavaScript 对等文件的 TypeScript 源文件，例如从 `src/index.ts` 到 `dist/index.js`。 +原生插件 npm 包必须在 `package.json` 中声明 `openclaw.extensions`。 +每个条目都必须位于包目录内，并解析到可读取的 +运行时文件，或解析到一个 TypeScript 源文件，该源文件具有可推断的已构建 JavaScript +对应文件，例如从 `src/index.ts` 到 `dist/index.js`。 -当已发布的运行时文件与源条目不在相同路径时，请使用 `openclaw.runtimeExtensions`。存在时，`runtimeExtensions` 必须为每个 `extensions` 条目精确包含一个条目。列表不匹配会导致安装和插件发现失败，而不是静默回退到源路径。 +当发布的运行时文件与源条目路径不相同时，请使用 `openclaw.runtimeExtensions`。 +存在时，`runtimeExtensions` 必须为每个 `extensions` 条目包含 +恰好一个条目。不匹配的列表会导致安装和 +插件发现失败，而不是静默回退到源路径。 ```json { @@ -103,9 +159,15 @@ OpenClaw 识别两种插件格式： ### 迁移期间 OpenClaw 自有的 npm 包 -ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版本已经内置许多官方插件，因此在正常设置中它们不需要单独 npm 安装。在每个 OpenClaw 自有插件都迁移到 ClawHub 之前，OpenClaw 仍会在 npm 上发布一些 `@openclaw/*` 插件包，用于较旧/自定义安装和直接 npm 工作流。 +ClawHub 是大多数插件的主要分发路径。当前打包的 +OpenClaw 版本已经内置许多官方插件，因此在正常设置中这些插件不需要 +单独 npm 安装。在每个 OpenClaw 自有插件都 +迁移到 ClawHub 之前，OpenClaw 仍会在 +npm 上发布一些 `@openclaw/*` 插件包，用于较旧/自定义安装和直接 npm 工作流。 -如果 npm 报告某个 `@openclaw/*` 插件包已弃用，该包版本来自较旧的外部包发布线。请使用当前 OpenClaw 中的内置插件或本地检出，直到发布更新的 npm 包。 +如果 npm 将某个 `@openclaw/*` 插件包报告为已弃用，则该包 +版本来自较旧的外部包序列。请使用当前 OpenClaw 中的内置插件， +或使用本地检出，直到发布更新的 npm 包。 | 插件 | 包 | 文档 | | --------------- | -------------------------- | ------------------------------------------ | @@ -123,37 +185,38 @@ ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版 | Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) | | Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) | -### Core（随 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` — 内置记忆搜索（默认通过 `plugins.slots.memory`） + - `memory-lancedb` — 按需安装的长期记忆，支持自动回忆/捕获（设置 `plugins.slots.memory = "memory-lancedb"`） - 有关 OpenAI 兼容的嵌入设置、Ollama 示例、召回限制和故障排除，请参阅 [Memory LanceDB](/zh-CN/plugins/memory-lancedb)。 + 参见 [Memory LanceDB](/zh-CN/plugins/memory-lancedb)，了解 OpenAI 兼容的 + 嵌入设置、Ollama 示例、回忆限制和故障排除。 - - `elevenlabs`, `microsoft` + + `elevenlabs`、`microsoft` - - - `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` gateway 方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；替换它之前请先禁用） + + - `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时，以及默认浏览器控制服务的内置浏览器插件（默认启用；替换前请禁用） - `copilot-proxy` — VS Code Copilot Proxy 桥接（默认禁用） -在寻找第三方插件？请参阅[社区插件](/zh-CN/plugins/community)。 +正在寻找第三方插件？参见[社区插件](/zh-CN/plugins/community)。 ## 配置 @@ -176,31 +239,46 @@ ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版 | `enabled` | 主开关（默认：`true`） | | `allow` | 插件允许列表（可选） | | `deny` | 插件拒绝列表（可选；拒绝优先） | -| `load.paths` | 额外插件文件/目录 | +| `load.paths` | 额外的插件文件/目录 | | `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） | | `entries.\` | 每个插件的开关 + 配置 | -`plugins.allow` 是排他的。当它非空时，只有列出的插件可以加载或暴露工具，即使 `tools.allow` 包含 `"*"` 或特定插件拥有的工具名称也是如此。如果工具允许列表引用了插件工具，请将所属插件 ID 添加到 `plugins.allow`，或移除 `plugins.allow`；`openclaw doctor` 会对此形态发出警告。 +`plugins.allow` 是排他的。当它非空时，只有列出的插件才能加载 +或暴露工具，即使 `tools.allow` 包含 `"*"` 或特定插件自有的 +工具名称。如果工具允许列表引用插件工具，请将所属插件 id +加入 `plugins.allow`，或移除 `plugins.allow`；`openclaw doctor` 会对此 +形态发出警告。 -配置变更**需要重启 gateway**。如果 Gateway 网关运行时启用了配置监视 + 进程内重启（默认 `openclaw gateway` 路径），该重启通常会在配置写入落地后片刻自动执行。原生插件运行时代码或生命周期钩子没有受支持的热重载路径；在期望更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务或 provider/runtime 钩子运行之前，请重启正在服务实时渠道的 Gateway 网关进程。 +配置更改**需要重启 Gateway 网关**。如果 Gateway 网关正在以配置 +监听 + 进程内重启启用的方式运行（默认的 `openclaw gateway` 路径），那么 +该重启通常会在配置写入落地后片刻自动执行。 +原生插件运行时代码或生命周期 +钩子没有受支持的热重载路径；在期望更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务，或 +提供商/运行时钩子运行之前，请重启正在服务实时渠道的 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。 - - **无效**：插件存在，但其配置与声明的 schema 不匹配。Gateway 网关启动只会跳过该插件；`openclaw doctor --fix` 可以通过禁用该条目并移除其配置载荷来隔离无效条目。 + + - **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。 + - **缺失**：配置引用了设备发现未找到的插件 id。 + - **无效**：插件存在，但其配置与声明的架构不匹配。Gateway 网关启动时只会跳过该插件；`openclaw doctor --fix` 可以通过禁用它并移除其配置载荷来隔离该无效条目。 -## 发现和优先级 +## 设备发现和优先级 -OpenClaw 按以下顺序扫描插件（第一个匹配项胜出）： +OpenClaw 按以下顺序扫描插件（首个匹配项生效）： - `plugins.load.paths` — 显式文件或目录路径。指回 OpenClaw 自身打包内置插件目录的路径会被忽略； - 运行 `openclaw doctor --fix` 可移除这些陈旧别名。 + `plugins.load.paths` — 显式文件或目录路径。指向 + OpenClaw 自身打包内置插件目录的路径会被忽略； + 运行 `openclaw doctor --fix` 可移除这些过期别名。 @@ -217,29 +295,29 @@ OpenClaw 按以下顺序扫描插件（第一个匹配项胜出）： -打包安装和 Docker 镜像通常会从编译后的 `dist/extensions` 树解析内置插件。如果内置插件源目录 -被绑定挂载到匹配的打包源路径上，例如 -`/app/extensions/synology-chat`，OpenClaw 会将该挂载的源目录 -视为内置源覆盖层，并在打包的 +打包安装和 Docker 镜像通常会从已编译的 `dist/extensions` 树中解析内置插件。如果内置插件源码目录被 +bind-mounted 到匹配的打包源码路径上，例如 +`/app/extensions/synology-chat`，OpenClaw 会将该挂载的源码目录 +视为内置源码覆盖层，并在打包的 `/app/dist/extensions/synology-chat` bundle 之前发现它。这样可以让维护者容器 -循环继续工作，而无需把每个内置插件都切回 TypeScript 源码。 +循环继续工作，而无需把每个内置插件切回 TypeScript 源码。 设置 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可强制使用打包的 dist bundles， -即使存在源覆盖挂载也是如此。 +即使存在源码覆盖挂载也是如此。 ### 启用规则 -- `plugins.enabled: false` 会禁用所有插件，并跳过插件发现/加载工作 +- `plugins.enabled: false` 会禁用所有插件，并跳过插件设备发现/加载工作 - `plugins.deny` 始终优先于 allow - `plugins.entries.\.enabled: false` 会禁用该插件 - 工作区来源的插件**默认禁用**（必须显式启用） -- 内置插件遵循内建的默认启用集合，除非被覆盖 +- 内置插件遵循内置的默认开启集合，除非被覆盖 - 独占槽位可以强制启用该槽位选中的插件 -- 当配置命名了某个插件拥有的表面时，某些内置的选择启用插件会自动启用， - 例如提供商模型引用、渠道配置或 harness +- 某些需要选择加入的内置插件会在配置命名某个 + 插件拥有的表面时自动启用，例如提供商模型引用、渠道配置或 harness 运行时 -- 当 `plugins.enabled: false` 处于活动状态时，会保留陈旧插件配置； - 如果你希望移除陈旧 id，请先重新启用插件再运行 Doctor 清理 -- OpenAI 系列 Codex 路由保持独立的插件边界： +- 当 `plugins.enabled: false` 处于活动状态时，过期插件配置会被保留； + 如果你想移除过期 id，请先重新启用插件再运行 Doctor 清理 +- OpenAI 系列 Codex 路由保持单独的插件边界： `openai-codex/*` 属于 OpenAI 插件，而内置 Codex app-server 插件由 `agentRuntime.id: "codex"` 或旧版 `codex/*` 模型引用选择 @@ -247,22 +325,22 @@ OpenClaw 按以下顺序扫描插件（第一个匹配项胜出）： ## 运行时钩子故障排除 如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或钩子 -没有在实时聊天流量中运行，请先检查这些事项： +没有在实时聊天流量中运行，请先检查这些项： -- 运行 `openclaw gateway status --deep --require-rpc`，并确认活动 - Gateway 网关 URL、配置文件、配置路径和进程就是你正在编辑的那些。 -- 在插件安装/配置/代码更改后重启实时 Gateway 网关。在包装器 - 容器中，PID 1 可能只是一个 supervisor；请重启或向子 +- 运行 `openclaw gateway status --deep --require-rpc`，并确认活动的 + Gateway 网关 URL、profile、配置路径和进程就是你正在编辑的对象。 +- 在插件安装/配置/代码更改后重启实时 Gateway 网关。在 wrapper + 容器中，PID 1 可能只是 supervisor；请重启或向子 `openclaw gateway run` 进程发送信号。 - 使用 `openclaw plugins inspect --runtime --json` 确认钩子注册和 - 诊断。非内置会话钩子（例如 `llm_input`、 - `llm_output`、`before_agent_finalize` 和 `agent_end`）需要 + 诊断信息。非内置会话钩子，例如 `llm_input`、 + `llm_output`、`before_agent_finalize` 和 `agent_end`，需要 `plugins.entries..hooks.allowConversationAccess=true`。 - 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型 解析之前运行；`llm_output` 只会在一次模型尝试 - 产出 assistant 输出之后运行。 + 生成 assistant 输出后运行。 - 要证明有效的会话模型，请使用 `openclaw sessions` 或 - Gateway 网关会话/Status 表面；调试提供商 payload 时，请使用 + Gateway 网关会话/Status 表面；调试提供商载荷时，请使用 `--raw-stream --raw-stream-path ` 启动 Gateway 网关。 @@ -274,35 +352,35 @@ OpenClaw 按以下顺序扫描插件（第一个匹配项胜出）： - `channel setup already registered: ()` - `plugin tool name conflict (): ` -这些表示不止一个已启用插件试图拥有同一个渠道、 +这些表示超过一个已启用插件正在尝试拥有同一个渠道、 设置流程或工具名称。最常见的原因是外部渠道插件 -安装在一个现在提供相同渠道 id 的内置插件旁边。 +与现在提供相同渠道 id 的内置插件并排安装。 调试步骤： - 运行 `openclaw plugins list --enabled --verbose` 查看每个已启用插件 及其来源。 -- 对每个可疑插件运行 `openclaw plugins inspect --runtime --json`，并 - 比较 `channels`、`channelConfigs`、`tools` 和诊断。 -- 在安装或移除 - 插件包后运行 `openclaw plugins registry --refresh`，使持久化元数据反映当前安装。 -- 在安装、注册表或配置更改后重启 Gateway 网关。 +- 对每个疑似插件运行 `openclaw plugins inspect --runtime --json`， + 并比较 `channels`、`channelConfigs`、`tools` 和诊断信息。 +- 安装或移除 + 插件包后，运行 `openclaw plugins registry --refresh`，让持久化元数据反映当前安装。 +- 在安装、registry 或配置更改后重启 Gateway 网关。 修复选项： -- 如果一个插件有意替换另一个具有相同渠道 id 的插件， +- 如果一个插件有意替换另一个使用相同渠道 id 的插件， 首选插件应声明 `channelConfigs..preferOver`，并填入 - 优先级较低的插件 id。参见 [/plugins/manifest#replacing-another-channel-plugin](/zh-CN/plugins/manifest#replacing-another-channel-plugin)。 -- 如果重复是意外的，请用 - `plugins.entries..enabled: false` 禁用其中一方，或移除陈旧插件 + 较低优先级的插件 id。参见 [/plugins/manifest#replacing-another-channel-plugin](/zh-CN/plugins/manifest#replacing-another-channel-plugin)。 +- 如果重复是意外的，请使用 + `plugins.entries..enabled: false` 禁用一侧，或移除过期的插件 安装。 -- 如果你显式启用了这两个插件，OpenClaw 会保留该请求并 - 报告冲突。请为该渠道选择一个所有者，或重命名插件拥有的 +- 如果你显式启用了两个插件，OpenClaw 会保留该请求并 + 报告冲突。为该渠道选择一个所有者，或重命名插件拥有的 工具，使运行时表面明确无歧义。 ## 插件槽位（独占类别） -某些类别是独占的（同一时间只能有一个处于活动状态）： +某些类别是独占的（同一时间只有一个处于活动状态）： ```json5 { @@ -318,7 +396,7 @@ OpenClaw 按以下顺序扫描插件（第一个匹配项胜出）： | 槽位 | 控制内容 | 默认值 | | --------------- | --------------------- | ------------------- | | `memory` | 主动记忆插件 | `memory-core` | -| `contextEngine` | 活动上下文引擎 | `legacy`（内置） | +| `contextEngine` | 活动上下文引擎 | `legacy` (built-in) | ## CLI 参考 @@ -328,7 +406,7 @@ openclaw plugins list --enabled # only enabled plugins openclaw plugins list --verbose # per-plugin detail lines openclaw plugins list --json # machine-readable inventory openclaw plugins inspect # static detail -openclaw plugins inspect --runtime # registered hooks/tools/diagnostics +openclaw plugins inspect --runtime # registered hooks/tools/CLI/gateway methods openclaw plugins inspect --json # machine-readable openclaw plugins inspect --all # fleet-wide table openclaw plugins info # inspect alias @@ -340,6 +418,8 @@ openclaw doctor --fix # repair plugin registry state openclaw plugins install # install (ClawHub first, then npm) openclaw plugins install clawhub: # install from ClawHub only openclaw plugins install npm: # install from npm only +openclaw plugins install git: # install from git +openclaw plugins install git:@ # install from git ref openclaw plugins install --force # overwrite existing install openclaw plugins install # install from local path openclaw plugins install -l # link (no copy) for dev @@ -355,6 +435,12 @@ openclaw plugins uninstall --keep-files openclaw plugins marketplace list openclaw plugins marketplace list --json +# Verify runtime registrations after install. +openclaw plugins inspect --runtime --json + +# Run plugin-owned CLI commands directly from the OpenClaw root CLI. +openclaw --help + openclaw plugins enable openclaw plugins disable ``` @@ -363,76 +449,66 @@ openclaw plugins disable 内置模型提供商、内置语音提供商和内置浏览器 插件）。其他内置插件仍然需要 `openclaw plugins enable `。 -`--force` 会就地覆盖现有已安装插件或 hook pack。对于跟踪中的 npm -插件的常规升级，请使用 -`openclaw plugins update `。它不支持与 `--link` 一起使用，因为后者会复用源路径， -而不是复制到托管安装目标上。 +`--force` 会原地覆盖现有已安装插件或 hook pack。对已跟踪的 npm +插件进行常规升级时，请使用 +`openclaw plugins update `。它不支持与 `--link` 一起使用，后者会复用源码路径，而不是 +复制到托管安装目标上。 -当 `plugins.allow` 已经设置时，`openclaw plugins install` 会在启用插件之前 -把已安装插件 id 添加到该 allowlist。如果相同插件 id -存在于 `plugins.deny` 中，安装会移除该陈旧 deny 条目，使显式安装 -在重启后可立即加载。 +当 `plugins.allow` 已设置时，`openclaw plugins install` 会先把 +已安装的插件 id 添加到该 allowlist，然后再启用它。如果同一插件 id +存在于 `plugins.deny` 中，install 会移除该过期 deny 条目，使 +显式安装在重启后立即可加载。 -OpenClaw 会保留一个持久化的本地插件注册表，作为插件清单、 -贡献所有权和启动规划的冷读取模型。安装、更新、 -卸载、启用和禁用流程会在更改插件 -状态后刷新该注册表。相同的 `plugins/installs.json` 文件会在 -顶层 `installRecords` 中保存持久安装元数据，并在 `plugins` 中保存可重建的 manifest 元数据。如果 -注册表缺失、陈旧或无效，`openclaw plugins registry +OpenClaw 会保留一个持久化的本地插件 registry，作为插件清单、 +贡献所有权和启动规划的冷读取模型。install、update、 +uninstall、enable 和 disable 流程会在更改插件状态后刷新该 registry。 +同一个 `plugins/installs.json` 文件会在顶层 `installRecords` 中保存持久安装元数据， +并在 `plugins` 中保存可重建的 manifest 元数据。如果 +registry 缺失、过期或无效，`openclaw plugins registry --refresh` 会从安装记录、配置策略和 -manifest/package 元数据重建其 manifest 视图，而不加载插件运行时模块。 -`openclaw plugins update ` 适用于跟踪中的安装。传入 -带 dist-tag 或精确版本的 npm 包 spec，会将包名解析 -回跟踪中的插件记录，并记录新的 spec 以供未来更新。 -传入不带版本的包名，会把精确固定的安装切回 -注册表的默认发布线。如果已安装的 npm 插件已经匹配 -解析出的版本和记录的 artifact identity，OpenClaw 会跳过更新， -不下载、不重新安装，也不重写配置。 +manifest/package 元数据重建其 manifest 视图，而不会加载插件运行时模块。 +`openclaw plugins update ` 适用于已跟踪安装。传入 +带 dist-tag 或精确版本的 npm package spec 会将包名 +解析回已跟踪插件记录，并记录新的 spec 以供未来更新。 +传入不带版本的包名会把精确 pinned 安装移回 +registry 的默认发布线。如果已安装的 npm 插件已经匹配 +解析出的版本和记录的 artifact 标识，OpenClaw 会跳过更新， +不会下载、重新安装或重写配置。 `--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 -marketplace 安装会持久化 marketplace 源元数据，而不是 npm spec。 +marketplace 安装会持久化 marketplace source 元数据，而不是 npm spec。 -`--dangerously-force-unsafe-install` 是用于处理内置危险代码扫描器误报的 -破窗覆盖项。它允许插件安装 -和插件更新越过内置的 `critical` findings 继续进行，但仍然 -不会绕过插件 `before_install` 策略阻断或扫描失败阻断。 +`--dangerously-force-unsafe-install` 是用于处理内置危险代码扫描器 +误报的应急覆盖。它允许插件安装 +和插件更新在遇到内置 `critical` 发现后继续，但仍然 +不会绕过插件 `before_install` 策略阻止或扫描失败阻止。 安装扫描会忽略常见测试文件和目录，例如 `tests/`、 -`__tests__/`、`*.test.*` 和 `*.spec.*`，以避免阻断打包的测试 mock； -声明的插件运行时入口点仍然会被扫描，即使它们使用了这些名称之一。 +`__tests__/`、`*.test.*` 和 `*.spec.*`，以避免阻止打包的测试 mock； +声明的插件运行时入口点仍会被扫描，即使它们使用这些 +名称之一。 -此 CLI 标志仅适用于插件安装/更新流程。Gateway 网关支持的 skill -依赖安装则使用匹配的 `dangerouslyForceUnsafeInstall` 请求 -覆盖项，而 `openclaw skills install` 仍然是独立的 ClawHub +此 CLI 标志仅适用于插件 install/update 流程。Gateway 网关支持的 skill +依赖安装会改用匹配的 `dangerouslyForceUnsafeInstall` 请求 +覆盖，而 `openclaw skills install` 仍是单独的 ClawHub skill 下载/安装流程。 -如果你在 ClawHub 上发布的插件被扫描隐藏或阻断，请打开 -ClawHub dashboard，或运行 `clawhub package rescan ` 请求 ClawHub 再次 -检查它。`--dangerously-force-unsafe-install` 只影响你自己 -机器上的安装；它不会请求 ClawHub 重新扫描插件，也不会让被阻断的发布 +如果你发布到 ClawHub 的插件因扫描而被隐藏或阻止，请打开 +ClawHub dashboard，或运行 `clawhub package rescan ` 请求 ClawHub 再次检查 +它。`--dangerously-force-unsafe-install` 只影响你自己 +机器上的安装；它不会要求 ClawHub 重新扫描插件，也不会让被阻止的发布 公开。 -兼容 bundles 参与相同的插件 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 流程。当前运行时支持包括捆绑包 Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和 manifest 声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。 -`openclaw plugins inspect ` 还会报告检测到的 bundle 能力，以及 -bundle 支持的插件的受支持或不受支持 MCP 和 LSP 服务器条目。 +`openclaw plugins inspect ` 还会报告检测到的捆绑包能力，以及由捆绑包支持的插件中受支持或不受支持的 MCP 和 LSP 服务器条目。 -Marketplace 源可以是来自 -`~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 -`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub repo -URL，或 git URL。对于远程 marketplaces，插件条目必须留在 -克隆的 marketplace repo 内，并且只能使用相对路径源。 +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({ @@ -452,31 +528,21 @@ export default definePluginEntry({ }); ``` -OpenClaw 会加载入口对象，并在插件 -激活期间调用 `register(api)`。加载器仍会回退到为旧插件使用 -`activate(api)`，但内置插件和新的外部插件应将 `register` 视为 -公共契约。 +OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`。加载器仍会回退到为较旧插件调用 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公开契约。 `api.registrationMode` 会告诉插件其入口为什么被加载： | 模式 | 含义 | | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `full` | 运行时激活。注册工具、钩子、服务、命令、路由以及其他实时副作用。 | -| `discovery` | 只读能力发现。注册提供商和元数据；受信任的插件入口代码可能会加载，但会跳过实时副作用。 | +| `full` | 运行时激活。注册工具、钩子、服务、命令、路由和其他实时副作用。 | +| `discovery` | 只读能力发现。注册提供商和元数据；可信插件入口代码可以加载，但应跳过实时副作用。 | | `setup-only` | 通过轻量级设置入口加载渠道设置元数据。 | -| `setup-runtime` | 渠道设置加载，同时也需要运行时入口。 | +| `setup-runtime` | 也需要运行时入口的渠道设置加载。 | | `cli-metadata` | 仅收集 CLI 命令元数据。 | -会打开套接字、数据库、后台工作进程或长期存在的 -客户端的插件入口，应使用 `api.registrationMode === "full"` 保护这些副作用。 -设备发现加载会与激活加载分开缓存，并且不会替换 -正在运行的 Gateway 网关注册表。设备发现是非激活的，但不是免导入的： -OpenClaw 可能会求值受信任的插件入口或渠道插件模块，以构建 -快照。保持模块顶层轻量且无副作用，并将 -网络客户端、子进程、监听器、凭证读取和服务启动 -放到完整运行时路径之后。 +会打开套接字、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 保护这些副作用。发现加载会与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。发现是非激活式的，但不是免导入的：OpenClaw 可能会执行可信插件入口或渠道插件模块来构建快照。让模块顶层保持轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径之后。 -常见注册方法： +常用注册方法： | 方法 | 注册内容 | | --------------------------------------- | --------------------------- | @@ -491,7 +557,7 @@ OpenClaw 可能会求值受信任的插件入口或渠道插件模块，以构 | `registerImageGenerationProvider` | 图像生成 | | `registerMusicGenerationProvider` | 音乐生成 | | `registerVideoGenerationProvider` | 视频生成 | -| `registerWebFetchProvider` | Web 获取 / 抓取提供商 | +| `registerWebFetchProvider` | Web fetch / scrape 提供商 | | `registerWebSearchProvider` | Web 搜索 | | `registerHttpRoute` | HTTP 端点 | | `registerCommand` / `registerCli` | CLI 命令 | @@ -500,27 +566,22 @@ OpenClaw 可能会求值受信任的插件入口或渠道插件模块，以构 类型化生命周期钩子的钩子保护行为： -- `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 }` 是无操作，并且不会清除更早的取消。 -原生 Codex 应用服务器会将 Codex 原生工具事件桥接回这个 -钩子表面。插件可以通过 `before_tool_call` 拦截原生 Codex 工具， -通过 `after_tool_call` 观察结果，并参与 Codex -`PermissionRequest` 审批。该桥接尚不会重写 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) — 创建你自己的插件 -- [插件包](/zh-CN/plugins/bundles) — Codex/Claude/Cursor 包兼容性 -- [插件清单](/zh-CN/plugins/manifest) — 清单 schema +- [插件捆绑包](/zh-CN/plugins/bundles) — Codex/Claude/Cursor 捆绑包兼容性 +- [插件 manifest](/zh-CN/plugins/manifest) — manifest schema - [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具 - [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流水线 - [社区插件](/zh-CN/plugins/community) — 第三方列表 diff --git a/docs/zh-CN/tools/slash-commands.md b/docs/zh-CN/tools/slash-commands.md index c31bb1ca7..f311daf81 100644 --- a/docs/zh-CN/tools/slash-commands.md +++ b/docs/zh-CN/tools/slash-commands.md @@ -6,17 +6,17 @@ sidebarTitle: Slash commands summary: 斜杠命令：文本与原生、配置和支持的命令 title: 斜杠命令 x-i18n: - generated_at: "2026-04-30T00:29:44Z" + generated_at: "2026-05-01T10:03:13Z" model: gpt-5.5 provider: openai - source_hash: d87471982fd03fb35bcb44ae62c9f9e40ec38ad17059c88a1e990194a296fbbd + source_hash: cfa4c8e294080e824b15f0b54842718f7913cf6d42b7edd4ca9695c3d4113924 source_path: tools/slash-commands.md workflow: 16 --- -命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机可用的 bash 聊天命令使用 `! `（`/bash ` 是其别名）。 +命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机 bash 聊天命令使用 `! `（`/bash ` 是别名）。 -当某个对话或线程绑定到 ACP 会话时，普通的后续文本会路由到该 ACP 运行框架。Gateway 网关管理命令仍然保持本地处理：`/acp ...` 始终到达 OpenClaw ACP 命令处理器，并且只要该界面启用了命令处理，`/status` 和 `/unfocus` 就会保持本地处理。 +当对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍保留在本地：`/acp ...` 始终到达 OpenClaw ACP 命令处理器，并且只要该界面启用了命令处理，`/status` 和 `/unfocus` 就会保留在本地。 有两个相关系统： @@ -25,18 +25,18 @@ x-i18n: 独立的 `/...` 消息。 - `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`. + `/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。 - - 指令会在模型看到消息之前从消息中剥离。 - - 在普通聊天消息中（不是纯指令消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。 - - 在纯指令消息中（消息只包含指令），它们会持久化到会话，并回复确认。 - - 指令只会对**已授权发送者**应用。如果设置了 `commands.allowFrom`，它就是唯一使用的允许名单；否则授权来自渠道允许名单/配对以及 `commands.useAccessGroups`。未授权发送者的指令会被当作纯文本处理。 + - 指令会在模型看到消息之前从消息中移除。 + - 在普通聊天消息中（不是仅包含指令的消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。 + - 在仅包含指令的消息中（消息只包含指令），它们会持久化到会话，并回复确认信息。 + - 指令只会应用于**已授权的发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的 allowlist；否则授权来自渠道 allowlist/配对以及 `commands.useAccessGroups`。未授权的发送者会看到指令被当作普通文本处理。 - - 仅限允许名单内/已授权的发送者：`/help`, `/commands`, `/status`, `/whoami` (`/id`)。 + + 仅限 allowlist/已授权的发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 - 它们会立即运行，在模型看到消息之前被剥离，剩余文本则继续按正常流程处理。 + 它们会立即运行，在模型看到消息之前被移除，剩余文本继续走正常流程。 @@ -69,19 +69,19 @@ x-i18n: ``` - 启用在聊天消息中解析 `/...`。在没有原生命令的界面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你将它设为 `false`，文本命令仍然可用。 + 在聊天消息中启用 `/...` 解析。在没有原生命令的界面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你将它设为 `false`，文本命令仍然有效。 - 注册原生命令。自动模式：对 Discord/Telegram 启用；对 Slack 禁用（直到你添加斜杠命令）；对没有原生支持的提供商会被忽略。设置 `channels.discord.commands.native`, `channels.telegram.commands.native`, 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。`false` 会在启动时清除 Discord/Telegram 上先前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。 + 注册原生命令。Auto：对 Discord/Telegram 启用；对 Slack 关闭（直到你添加斜杠命令）；对没有原生支持的提供商会被忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。`false` 会在启动时清除 Discord/Telegram 上先前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。 - 在受支持时原生注册**技能**命令。自动模式：对 Discord/Telegram 启用；对 Slack 禁用（Slack 要求为每个技能创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills`, 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。 + 在支持时以原生方式注册 **skill** 命令。Auto：对 Discord/Telegram 启用；对 Slack 关闭（Slack 需要为每个 skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。 - 启用 `! ` 来运行主机 shell 命令（`/bash ` 是别名；需要 `tools.elevated` 允许名单）。 + 启用 `! ` 来运行主机 shell 命令（`/bash ` 是别名；需要 `tools.elevated` allowlist）。 - 控制 bash 在切换到后台模式之前等待多长时间（`0` 表示立即转入后台）。 + 控制 bash 等待多久后切换到后台模式（`0` 表示立即转到后台）。 启用 `/config`（读取/写入 `openclaw.json`）。 @@ -90,31 +90,31 @@ x-i18n: 启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。 - 启用 `/plugins`（插件发现/状态，以及安装 + 启用/禁用控制）。 + 启用 `/plugins`（插件发现/Status，以及安装 + 启用/禁用控制）。 - 启用 `/debug`（仅运行时覆盖项）。 + 启用 `/debug`（仅运行时覆盖）。 - 启用 `/restart` 以及 Gateway 网关重启工具操作。 + 启用 `/restart` 以及 gateway 网关重启工具操作。 - 设置仅所有者命令/工具界面的显式所有者允许名单。这是可以批准危险操作并运行 `/diagnostics`, `/export-trajectory`, 和 `/config` 等命令的人类操作员账号。它独立于 `commands.allowFrom`，也独立于私信配对访问权限。 + 为仅所有者可用的命令/工具界面设置显式所有者 allowlist。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账号。它与 `commands.allowFrom` 以及私信配对访问是分开的。 - 按渠道：让仅所有者命令在该界面运行时需要**所有者身份**。当为 `true` 时，发送者必须匹配已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上拥有内部 `operator.admin` 范围。渠道 `allowFrom` 中的通配符条目，或者空的/未解析的所有者候选列表，都**不足以通过**，该渠道上的仅所有者命令会按关闭策略失败。如果你希望仅所有者命令只由 `ownerAllowFrom` 和标准命令允许名单进行门控，请保持关闭。 + 按渠道设置：要求仅所有者命令在该界面上必须以**所有者身份**运行。当为 `true` 时，发送者必须匹配已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上持有内部 `operator.admin` scope。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足要求 —— 仅所有者命令会在该渠道上默认拒绝。如果你希望仅所有者命令只由 `ownerAllowFrom` 和标准命令 allowlist 守卫，请保持关闭。 - 控制所有者 ID 在系统提示中的显示方式。 + 控制所有者 id 在系统提示中的显示方式。 - 可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。 + 可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC secret。 - 按提供商设置命令授权允许名单。配置后，它是命令和指令的唯一授权来源（渠道允许名单/配对和 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。 + 命令授权的按提供商 allowlist。配置后，它就是命令和指令的唯一授权来源（渠道 allowlist/配对和 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；特定提供商键会覆盖它。 - 当未设置 `commands.allowFrom` 时，对命令强制执行允许名单/策略。 + 当未设置 `commands.allowFrom` 时，对命令强制执行 allowlist/策略。 ## 命令列表 @@ -122,73 +122,73 @@ x-i18n: 当前事实来源： - 核心内置命令来自 `src/auto-reply/commands-registry.shared.ts` -- 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts` -- 插件命令来自插件的 `registerCommand()` 调用 -- 在你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道界面以及已安装/已启用的插件 +- 生成的停靠命令来自 `src/auto-reply/commands-registry.data.ts` +- 插件命令来自插件 `registerCommand()` 调用 +- 你的 gateway 网关上的实际可用性仍取决于配置标志、渠道界面，以及已安装/已启用的插件 ### 核心内置命令 - - `/new [model]` 启动一个新会话；`/reset` 是重置别名。 - - `/reset soft [message]` 保留当前对话记录，丢弃复用的 CLI 后端会话 ID，并就地重新运行启动/系统提示加载。 - - `/compact [instructions]` 压缩会话上下文。参见 [压缩](/zh-CN/concepts/compaction)。 + - `/new [model]` 启动新会话；`/reset` 是重置别名。 + - `/reset soft [message]` 保留当前 transcript，丢弃复用的 CLI 后端会话 id，并在原地重新运行启动/系统提示加载。 + - `/compact [instructions]` 压缩会话上下文。参见[压缩](/zh-CN/concepts/compaction)。 - `/stop` 中止当前运行。 - `/session idle ` 和 `/session max-age ` 管理线程绑定过期时间。 - `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。 - - `/export-trajectory [path]` 请求执行批准，然后为当前会话导出 JSONL [轨迹包](/zh-CN/tools/trajectory)。当你需要某个 OpenClaw 会话的提示、工具和对话记录时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。 + - `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出 JSONL [轨迹包](/zh-CN/tools/trajectory)。当你需要一个 OpenClaw 会话的提示、工具和 transcript 时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。 - - `/think ` 设置思考级别。选项来自当前模型的提供商配置文件；常见级别包括 `off`, `minimal`, `low`, `medium`, 和 `high`，自定义级别如 `xhigh`, `adaptive`, `max`，或二值 `on` 仅在受支持处可用。别名：`/thinking`, `/t`。 + - `/think ` 设置 thinking 级别。选项来自活动模型的提供商 profile；常见级别是 `off`、`minimal`、`low`、`medium` 和 `high`，只有受支持的地方才有 `xhigh`、`adaptive`、`max` 等自定义级别，或二元 `on`。别名：`/thinking`、`/t`。 - `/verbose on|off|full` 切换详细输出。别名：`/v`。 - - `/trace on|off` 切换当前会话的插件跟踪输出。 - - `/fast [status|on|off]` 显示或设置快速模式。 - - `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。 - - `/elevated [on|off|ask|full]` 切换提权模式。别名：`/elev`。 - - `/exec host= security= ask= node=` 显示或设置执行默认值。 + - `/trace on|off` 切换当前会话的插件 trace 输出。 + - `/fast [status|on|off]` 显示或设置 fast 模式。 + - `/reasoning [on|off|stream]` 切换 reasoning 可见性。别名：`/reason`。 + - `/elevated [on|off|ask|full]` 切换 elevated 模式。别名：`/elev`。 + - `/exec host= security= ask= node=` 显示或设置 exec 默认值。 - `/model [name|#|status]` 显示或设置模型。 - `/models [provider] [page] [limit=|size=|all]` 列出已配置/有可用凭证的提供商，或列出某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。 - - `/queue ` 管理队列行为（`steer`, 旧版 `queue`, `followup`, `collect`, `steer-backlog`, `interrupt`）以及 `debounce:0.5s cap:25 drop:summarize` 等选项；`/queue default` 或 `/queue reset` 会清除会话覆盖。参见 [命令队列](/zh-CN/concepts/queue) 和 [Steering queue](/zh-CN/concepts/queue-steering)。 + - `/queue ` 管理队列行为（`steer`、旧版 `queue`、`followup`、`collect`、`steer-backlog`、`interrupt`），以及 `debounce:0.5s cap:25 drop:summarize` 等选项；`/queue default` 或 `/queue reset` 会清除会话覆盖。参见[命令队列](/zh-CN/concepts/queue)和 [Steering queue](/zh-CN/concepts/queue-steering)。 - + - `/help` 显示简短帮助摘要。 - `/commands` 显示生成的命令目录。 - - `/tools [compact|verbose]` 显示当前智能体现在可用的工具。 - - `/status` 显示执行/运行时状态，包括 `Execution`/`Runtime` 标签，以及可用时的提供商用量/配额。 - - `/diagnostics [note]` 是针对 Gateway 网关错误和 Codex harness 运行的仅所有者支持报告流程。它每次都会在运行 `openclaw gateway diagnostics export --json` 前请求显式执行批准；不要用允许全部规则批准诊断。批准后，它会发送一份可粘贴的报告，其中包含本地包路径、清单摘要、隐私说明和相关会话 ID。在群聊中，批准提示和报告会私下发送给所有者。当活动会话使用 OpenAI Codex harness 时，同一批准还会将相关 Codex 反馈发送到 OpenAI 服务器，完成后的回复会列出 OpenClaw 会话 ID、Codex 线程 ID 和 `codex resume ` 命令。参见 [诊断导出](/zh-CN/gateway/diagnostics)。 + - `/tools [compact|verbose]` 显示当前智能体现在可以使用什么。 + - `/status` 显示执行/运行时 Status，包括 `Execution`/`Runtime` 标签以及可用时的提供商用量/配额。 + - `/diagnostics [note]` 是针对 Gateway 网关 bug 和 Codex harness 运行的仅所有者支持报告流程。它每次都会在运行 `openclaw gateway diagnostics export --json` 之前请求明确的 exec 批准；不要用允许全部的规则批准诊断。批准后，它会发送一份可粘贴的报告，其中包含本地包路径、manifest 摘要、隐私说明和相关会话 id。在群聊中，批准提示和报告会私下发送给所有者。当活动会话使用 OpenAI Codex harness 时，同一批准也会将相关 Codex 反馈发送到 OpenAI 服务器，并且完成后的回复会列出 OpenClaw 会话 id、Codex thread id 和 `codex resume ` 命令。参见[诊断导出](/zh-CN/gateway/diagnostics)。 - `/crestodian ` 从所有者私信运行 Crestodian 设置和修复助手。 - `/tasks` 列出当前会话的活动/近期后台任务。 - - `/context [list|detail|json]` 说明上下文是如何组装的。 - - `/whoami` 显示你的发送者 ID。别名：`/id`。 - - `/usage off|tokens|full|cost` 控制每次响应的用量页脚，或打印本地成本摘要。 + - `/context [list|detail|json]` 解释上下文如何组装。 + - `/whoami` 显示你的发送者 id。别名：`/id`。 + - `/usage off|tokens|full|cost` 控制每条回复的用量页脚，或打印本地成本摘要。 - - - `/skill [input]` 按名称运行一个技能。 - - `/allowlist [list|add|remove] ...` 管理允许名单条目。仅限文本。 - - `/approve ` 处理执行批准提示。 - - `/btw ` 提出一个旁支问题，而不改变未来的会话上下文。参见 [BTW](/zh-CN/tools/btw)。 + + - `/skill [input]` 按名称运行一个 skill。 + - `/allowlist [list|add|remove] ...` 管理 allowlist 条目。仅文本。 + - `/approve ` 解决 exec 批准提示。 + - `/btw ` 提出一个旁支问题，不改变未来会话上下文。参见 [BTW](/zh-CN/tools/btw)。 - - - `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。 + + - `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的 sub-agent 运行。 - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。 - `/focus ` 将当前 Discord 线程或 Telegram 话题/对话绑定到会话目标。 - `/unfocus` 移除当前绑定。 - - `/agents` 列出当前会话中绑定到线程的智能体。 - - `/kill ` 中止一个或所有正在运行的子智能体。 - - `/steer ` 向正在运行的子智能体发送引导。别名：`/tell`。 + - `/agents` 列出当前会话的线程绑定智能体。 + - `/kill ` 中止一个或所有正在运行的 sub-agent。 + - `/steer ` 向正在运行的 sub-agent 发送 steering。别名：`/tell`。 - - - `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅所有者可用。需要 `commands.config: true`。 - - `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅所有者可用。需要 `commands.mcp: true`。 - - `/plugins list|inspect|show|get|install|enable|disable` 检查或变更插件状态。`/plugin` 是别名。写入仅所有者可用。需要 `commands.plugins: true`。 - - `/debug show|set|unset|reset` 管理仅运行时生效的配置覆盖。仅所有者可用。需要 `commands.debug: true`。 - - `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用它。 - - `/send on|off|inherit` 设置发送策略。仅所有者可用。 + + - `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅限所有者。需要 `commands.config: true`。 + - `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅限所有者。需要 `commands.mcp: true`。 + - `/plugins list|inspect|show|get|install|enable|disable` 检查或变更插件状态。`/plugin` 是别名。写入仅限所有者。需要 `commands.plugins: true`。 + - `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅限所有者。需要 `commands.debug: true`。 + - `/restart` 在启用时重启 OpenClaw。默认：已启用；设置 `commands.restart: false` 可将其禁用。 + - `/send on|off|inherit` 设置发送策略。仅限所有者。 @@ -201,101 +201,101 @@ x-i18n: -### 生成的停靠命令 +### 生成的 dock 命令 -停靠命令会把当前会话的回复路由切换到另一个已关联的 -渠道。设置、示例和故障排除见[渠道停靠](/zh-CN/concepts/channel-docking)。 +Dock 命令会将当前会话的回复路由切换到另一个已链接的 +渠道。设置、示例和故障排除请参见 [渠道 docking](/zh-CN/concepts/channel-docking)。 -停靠命令由支持原生命令的渠道插件生成。当前内置集合： +Dock 命令由支持原生命令的渠道插件生成。当前内置集合： - `/dock-discord`（别名：`/dock_discord`） - `/dock-mattermost`（别名：`/dock_mattermost`） - `/dock-slack`（别名：`/dock_slack`） - `/dock-telegram`（别名：`/dock_telegram`） -在直接聊天中使用停靠命令，可将当前会话的回复路由切换到另一个已关联的渠道。智能体会保留相同的会话上下文，但该会话后续回复会发送给所选渠道对端。 +在直接聊天中使用 dock 命令，将当前会话的回复路由切换到另一个已链接的渠道。智能体会保留同一个会话上下文，但该会话之后的回复会发送到选定的渠道对端。 -停靠命令需要 `session.identityLinks`。来源发送者和目标对端必须位于同一个身份组，例如 `["telegram:123", "discord:456"]`。如果 id 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活动会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未关联到 Discord 对端，该命令会回复设置提示，而不是继续落入普通聊天。 +Dock 命令需要 `session.identityLinks`。来源发送者和目标对端必须位于同一个身份组中，例如 `["telegram:123", "discord:456"]`。如果 ID 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活动会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未链接到 Discord 对端，该命令会回复设置提示，而不是落入普通聊天。 -停靠只会更改活动会话路由。它不会创建渠道账户、授予访问权限、绕过渠道允许列表，或把转录历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一个生成的停靠命令，可再次切换路由。 +Docking 只会更改活动会话路由。它不会创建渠道账户、授予访问权限、绕过渠道允许列表，也不会把转录历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一个生成的 dock 命令再次切换路由。 ### 内置插件命令 -内置插件可以添加更多斜杠命令。本仓库当前内置命令： +内置插件可以添加更多斜杠命令。此仓库中当前的内置命令： - `/dreaming [on|off|status|help]` 切换记忆 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。 -- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见[配对](/zh-CN/channels/pairing)。 -- `/phone status|arm [duration]|disarm` 临时启用高风险手机节点命令。 +- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见 [配对](/zh-CN/channels/pairing)。 +- `/phone status|arm [duration]|disarm` 临时授权高风险手机节点命令。 - `/voice status|list [limit]|set ` 管理 Talk 语音配置。在 Discord 上，原生命令名称是 `/talkvoice`。 - `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。 - `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` 检查并控制内置 Codex 应用服务器 harness。参见 [Codex harness](/zh-CN/plugins/codex-harness)。 -- 仅 QQBot 的命令： +- 仅 QQBot 命令： - `/bot-ping` - `/bot-version` - `/bot-help` - `/bot-upgrade` - `/bot-logs` -### 动态 Skills 命令 +### 动态 skill 命令 -用户可调用的 Skills 也会公开为斜杠命令： +用户可调用的 Skills 也会作为斜杠命令暴露： - `/skill [input]` 始终可作为通用入口点使用。 -- 当 skill/插件注册了直接命令时，Skills 也可能显示为 `/prose` 这样的直接命令。 -- 原生 Skills 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 +- 当 skill/插件注册时，skills 也可能以 `/prose` 这样的直接命令形式出现。 +- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 - - 命令和参数之间可选接受 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 - - `/new ` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，文本会被视为消息正文。 - - 如需完整提供商使用量细分，请使用 `openclaw status --usage`。 + - 命令接受命令和参数之间可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 + - `/new ` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配，文本会被视为消息正文。 + - 如需完整的提供商使用情况明细，请使用 `openclaw status --usage`。 - `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。 - 在多账户渠道中，面向配置目标的 `/allowlist --account ` 和 `/config set channels..accounts....` 也会遵循目标账户的 `configWrites`。 - - `/usage` 控制每条回复的使用量页脚；`/usage cost` 会从 OpenClaw 会话日志打印本地成本摘要。 - - `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。 - - `/plugins install ` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包，或 `clawhub:`。 - - `/plugins enable|disable` 更新插件配置，并且可能提示重启。 + - `/usage` 控制每条回复的用量页脚；`/usage cost` 从 OpenClaw 会话日志打印本地成本摘要。 + - `/restart` 默认启用；设置 `commands.restart: false` 可将其禁用。 + - `/plugins install ` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包、`git:` 或 `clawhub:`。 + - `/plugins enable|disable` 会更新插件配置，并可能提示重启。 - - 仅 Discord 的原生命令：`/vc join|leave|status` 控制语音频道（不能作为文本使用）。`join` 需要一个服务器和选定的语音/舞台频道。需要 `channels.discord.voice` 和原生命令。 + - 仅 Discord 原生命令：`/vc join|leave|status` 控制语音渠道（不可作为文本使用）。`join` 需要 guild 和已选择的语音/舞台渠道。需要 `channels.discord.voice` 和原生命令。 - Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要启用有效线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。 - - ACP 命令参考和运行时行为：[ACP agents](/zh-CN/tools/acp-agents)。 + - ACP 命令参考和运行时行为：[ACP 智能体](/zh-CN/tools/acp-agents)。 - + - `/verbose` 用于调试和提供额外可见性；正常使用时保持**关闭**。 - - `/trace` 比 `/verbose` 范围更窄：它只显示插件拥有的 trace/debug 行，并保持普通 verbose 工具噪声关闭。 - - `/fast on|off` 会持久化会话覆盖。使用 Sessions UI 的 `inherit` 选项可清除它并回退到配置默认值。 - - `/fast` 与提供商相关：OpenAI/OpenAI Codex 在原生 Responses 端点上会映射为 `service_tier=priority`，而直接公共 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，会映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。 - - 工具失败摘要在相关时仍会显示，但详细失败文本仅在 `/verbose` 为 `on` 或 `full` 时包含。 - - `/reasoning`、`/verbose` 和 `/trace` 在群组场景中有风险：它们可能泄露你不打算公开的内部推理、工具输出或插件诊断。建议保持关闭，尤其是在群聊中。 + - `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通 verbose 工具噪声关闭。 + - `/fast on|off` 会持久化会话覆盖。使用会话 UI 的 `inherit` 选项清除它，并回退到配置默认值。 + - `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射到 `service_tier=priority`，而直接的公共 Anthropic 请求（包括发送到 `api.anthropic.com` 的 OAuth 认证流量）会将其映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。 + - 相关时仍会显示工具失败摘要，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。 + - `/reasoning`、`/verbose` 和 `/trace` 在群组设置中有风险：它们可能暴露你无意公开的内部推理、工具输出或插件诊断信息。建议保持关闭，尤其是在群聊中。 - `/model` 会立即持久化新的会话模型。 - 如果智能体处于空闲状态，下一次运行会立即使用它。 - - 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并只会在干净的重试点重启到新模型。 - - 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续重试机会或下一次用户轮次。 - - 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回到 Crestodian。这与消息渠道救援模式不同，也不会授予远程配置权限。 + - 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并只会在干净的重试点重启到新模型。 + - 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续重试机会或下一次用户回合。 + - 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回 Crestodian。这独立于消息渠道救援模式，并且不会授予远程配置权限。 - - **快速路径：**允许列表发送者发出的仅命令消息会被立即处理（绕过队列 + 模型）。 - - **群组提及门控：**允许列表发送者发出的仅命令消息会绕过提及要求。 - - **内联快捷方式（仅允许列表发送者）：**某些命令嵌入普通消息时也能生效，并且会在模型看到剩余文本前被剥离。 - - 示例：`hey /status` 会触发 Status 回复，剩余文本继续走普通流程。 - - 当前包括：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 - - 未授权的仅命令消息会被静默忽略，内联 `/...` 标记会被视为纯文本。 + - **快速路径：** 来自允许列表发送者的仅命令消息会立即处理（绕过队列 + 模型）。 + - **群组提及门控：** 来自允许列表发送者的仅命令消息会绕过提及要求。 + - **内联快捷方式（仅限允许列表发送者）：** 某些命令嵌入普通消息时也能工作，并会在模型看到剩余文本前被剥离。 + - 示例：`hey /status` 触发 Status 回复，剩余文本继续走普通流程。 + - 当前：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 + - 未授权的仅命令消息会被静默忽略，内联 `/...` token 会被视为纯文本。 - - - **Skills 命令：**`user-invocable` Skills 会公开为斜杠命令。名称会清理为 `a-z0-9_`（最多 32 个字符）；冲突会获得数字后缀（例如 `_2`）。 - - `/skill [input]` 按名称运行 Skills（当原生命令限制阻止按 Skills 生成命令时很有用）。 - - 默认情况下，Skills 命令会作为普通请求转发给模型。 + + - **Skill 命令：** `user-invocable` Skills 会作为斜杠命令暴露。名称会清理为 `a-z0-9_`（最多 32 个字符）；冲突会获得数字后缀（例如 `_2`）。 + - `/skill [input]` 按名称运行 skill（当原生命令限制阻止为每个 skill 创建命令时很有用）。 + - 默认情况下，skill 命令会作为普通请求转发给模型。 - Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性，无模型）。 - 示例：`/prose`（OpenProse 插件）— 参见 [OpenProse](/zh-CN/prose)。 - - **原生命令参数：**Discord 对动态选项使用自动补全（当你省略必需参数时使用按钮菜单）。当命令支持选项且你省略参数时，Telegram 和 Slack 会显示按钮菜单。动态选项会针对目标会话模型解析，因此 `/think` 级别等模型特定选项会跟随该会话的 `/model` 覆盖。 + - **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必需参数时使用按钮菜单）。Telegram 和 Slack 会在命令支持选项且你省略参数时显示按钮菜单。动态选项会针对目标会话模型解析，因此模型特定选项（例如 `/think` 级别）会跟随该会话的 `/model` 覆盖。 @@ -304,25 +304,25 @@ x-i18n: `/tools` 回答的是运行时问题，而不是配置问题：**这个智能体现在在此对话中可以使用什么**。 -- 默认 `/tools` 紧凑，并针对快速浏览优化。 -- `/tools verbose` 会添加简短描述。 -- 支持参数的原生命令界面会公开同样的模式切换：`compact|verbose`。 -- 结果按会话作用域划分，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。 -- `/tools` 包含运行时实际可访问的工具，包括核心工具、已连接的插件工具和渠道拥有的工具。 +- 默认 `/tools` 很紧凑，并针对快速浏览优化。 +- `/tools verbose` 添加简短描述。 +- 支持参数的原生命令界面暴露同样的模式开关：`compact|verbose`。 +- 结果限定于会话范围，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。 +- `/tools` 包含运行时实际可达的工具，包括核心工具、已连接的插件工具和渠道拥有的工具。 -如需编辑配置文件和覆盖项，请使用 Control UI 工具面板或配置/目录界面，而不是把 `/tools` 当作静态目录。 +如需编辑配置文件和覆盖，请使用 Control UI Tools 面板或配置/目录界面，而不是将 `/tools` 视为静态目录。 -## 使用量界面（哪里显示什么） +## 用量界面（何处显示什么） -- **提供商使用量/配额**（示例：“Claude 剩余 80%”）在启用使用量跟踪时，会显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口规范化为“剩余百分比”；对于 MiniMax，仅剩余百分比字段会在显示前反转，并且 `model_remains` 响应优先使用聊天模型条目以及带模型标签的套餐标签。 -- `/status` 中的 **token/cache 行**可在实时会话快照稀疏时回退到最新转录使用量条目。现有非零实时值仍然优先，转录回退也可以恢复活动运行时模型标签，以及在已存储总量缺失或更小时恢复更大的面向提示词的总量。 -- **执行与运行时：**`/status` 会为有效沙箱路径报告 `Execution`，并为实际运行会话的主体报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。 -- **每条回复的 token/成本**由 `/usage off|tokens|full` 控制（追加到普通回复）。 -- `/model status` 关注的是**模型/认证/端点**，不是使用量。 +- **提供商用量/配额**（示例：“Claude 剩余 80%”）在启用用量跟踪时会出现在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口规范化为“剩余百分比”；对于 MiniMax，只返回剩余量的百分比字段会在显示前取反，而 `model_remains` 响应会优先使用聊天模型条目和带模型标签的计划标签。 +- **Token/缓存行** 在 `/status` 中可能会在实时会话快照稀疏时回退到最新的转录用量条目。现有非零实时值仍然优先，转录回退还可以恢复活动运行时模型标签，以及在存储总量缺失或较小时恢复更大的面向提示词的总量。 +- **执行与运行时：** `/status` 对有效沙箱路径报告 `Execution`，并对实际运行会话的主体报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。 +- **每条回复的 token/成本** 由 `/usage off|tokens|full` 控制（追加到普通回复）。 +- `/model status` 关注的是**模型/凭证/端点**，不是用量。 ## 模型选择（`/model`） -`/model` 实现为一条指令。 +`/model` 作为指令实现。 示例： @@ -337,14 +337,14 @@ x-i18n: 说明： -- `/model` 和 `/model list` 会显示紧凑的编号选择器（模型系列 + 可用提供商）。 -- 在 Discord 上，`/model` 和 `/models` 会打开带有提供商和模型下拉框以及提交步骤的交互式选择器。 +- `/model` 和 `/model list` 显示紧凑的编号选择器（模型家族 + 可用提供商）。 +- 在 Discord 上，`/model` 和 `/models` 会打开带有提供商和模型下拉菜单以及 Submit 步骤的交互式选择器。 - `/model <#>` 从该选择器中选择（并在可能时优先使用当前提供商）。 -- `/model status` 显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`，如果可用）。 +- `/model status` 显示详细视图，包括可用时已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。 -## 调试覆盖 +## Debug 覆盖 -`/debug` 允许你设置**仅运行时**配置覆盖项（保存在内存中，而不是磁盘上）。仅限所有者使用。默认禁用；可通过 `commands.debug: true` 启用。 +`/debug` 允许你设置**仅运行时**的配置覆盖（内存中，不写入磁盘）。仅限所有者使用。默认禁用；使用 `commands.debug: true` 启用。 示例： @@ -357,12 +357,12 @@ x-i18n: ``` -覆盖项会立即应用于新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖项并恢复为磁盘上的配置。 +覆盖会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖并返回磁盘上的配置。 -## 插件跟踪输出 +## 插件 trace 输出 -`/trace` 允许你切换**会话范围的插件跟踪/调试行**，而不必开启完整详细模式。 +`/trace` 允许你切换**会话范围的插件 trace/debug 行**，而不启用完整详细模式。 示例： @@ -372,18 +372,18 @@ x-i18n: /trace off ``` -注意事项： +注意： -- 不带参数的 `/trace` 会显示当前会话的跟踪状态。 -- `/trace on` 会为当前会话启用插件跟踪行。 +- 不带参数的 `/trace` 会显示当前会话的 trace 状态。 +- `/trace on` 为当前会话启用插件 trace 行。 - `/trace off` 会再次禁用它们。 -- 插件跟踪行可能出现在 `/status` 中，也可能在正常助手回复后作为后续诊断消息出现。 -- `/trace` 不会替代 `/debug`；`/debug` 仍用于管理仅运行时配置覆盖项。 -- `/trace` 不会替代 `/verbose`；常规的详细工具/Status 输出仍属于 `/verbose`。 +- 插件 trace 行可以出现在 `/status` 中，也可以在正常的助手回复后作为后续诊断消息出现。 +- `/trace` 不会替代 `/debug`；`/debug` 仍然管理仅运行时的配置覆盖。 +- `/trace` 不会替代 `/verbose`；正常的详细工具/Status 输出仍然属于 `/verbose`。 ## 配置更新 -`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限所有者使用。默认禁用；可通过 `commands.config: true` 启用。 +`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限所有者使用。默认禁用；使用 `commands.config: true` 启用。 示例： @@ -401,7 +401,7 @@ x-i18n: ## MCP 更新 -`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限所有者使用。默认禁用；可通过 `commands.mcp: true` 启用。 +`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限所有者使用。默认禁用；使用 `commands.mcp: true` 启用。 示例： @@ -413,12 +413,12 @@ x-i18n: ``` -`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 所拥有的项目设置中。运行时适配器会决定哪些传输协议实际可执行。 +`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。运行时适配器决定哪些传输协议实际可执行。 ## 插件更新 -`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；可通过 `commands.plugins: true` 启用。 +`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。 示例： @@ -431,28 +431,28 @@ x-i18n: ``` -- `/plugins list` 和 `/plugins show` 会基于当前工作区加磁盘配置执行真实的插件发现。 -- `/plugins enable|disable` 只会更新插件配置；它不会安装或卸载插件。 -- 启用/禁用更改后，请重启 Gateway 网关以应用这些更改。 +- `/plugins list` 和 `/plugins show` 会基于当前工作区和磁盘配置执行真实的插件发现。 +- `/plugins enable|disable` 只更新插件配置；它不会安装或卸载插件。 +- 启用/禁用更改后，请重启 Gateway 网关以应用它们。 ## 界面说明 - - - **文本命令**在普通聊天会话中运行（私信共享 `main`，群组有自己的会话）。 + + - **文本命令**在正常聊天会话中运行（私信共享 `main`，群组有自己的会话）。 - **原生命令**使用隔离会话： - Discord：`agent::discord:slash:` - Slack：`agent::slack:slash:`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置） - - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 以聊天会话为目标） - - **`/stop`** 以当前活动聊天会话为目标，因此它可以中止当前运行。 + - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 定位到聊天会话） + - **`/stop`** 定位到活动聊天会话，以便它可以中止当前运行。 - - 对于单个 `/openclaw` 风格命令，仍支持 `channels.slack.slashCommand`。如果你启用 `commands.native`，必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮形式交付。 + + 对于单个 `/openclaw` 风格命令，仍然支持 `channels.slack.slashCommand`。如果启用 `commands.native`，你必须为每个内置命令创建一个 Slack slash command（名称与 `/help` 相同）。Slack 的命令参数菜单以临时 Block Kit 按钮形式发送。 - Slack 原生命令例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍可使用。 + Slack 原生例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然可用。 @@ -461,15 +461,15 @@ x-i18n: `/btw` 是关于当前会话的快速**附带问题**。 -与普通聊天不同： +不同于普通聊天： - 它使用当前会话作为背景上下文， -- 它作为一个单独的**无工具**一次性调用运行， +- 它作为单独的**无工具**一次性调用运行， - 它不会改变未来的会话上下文， -- 它不会写入对话记录历史， -- 它会作为实时附带结果交付，而不是普通助手消息。 +- 它不会写入转录历史， +- 它会作为实时附带结果发送，而不是普通的助手消息。 -当你希望在主任务继续进行时临时澄清一点内容，`/btw` 会很有用。 +当你希望在主任务继续进行时获得临时澄清，`/btw` 会很有用。 示例： @@ -477,7 +477,7 @@ x-i18n: /btw what are we doing right now? ``` -有关完整行为和客户端 UX 详情，请参阅 [BTW 附带问题](/zh-CN/tools/btw)。 +参见 [BTW 附带问题](/zh-CN/tools/btw) 了解完整行为和客户端 UX 细节。 ## 相关