openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-02 00:40:05 +00:00
parent a9dbb6bc62
commit b00b3ff839
2 changed files with 165 additions and 160 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

160
docs/zh-CN/cli/plugins.md
View File

@ -1,15 +1,15 @@
---
read_when:
- 你想安装或管理 Gateway 网关插件或兼容包
- 你想调试插件加载失败
- 你想安装或管理 Gateway 网关插件或兼容的捆绑包
- 你想调试插件加载失败问题
sidebarTitle: Plugins
summary: '`openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、doctor）'
title: 插件
x-i18n:
generated_at: "2026-05-01T20:36:46Z"
generated_at: "2026-05-02T00:39:04Z"
model: gpt-5.5
provider: openai
source_hash: 3c743beebf7b862f7991f04d3330452b8ff5c447b9eacea72a042f964d7bb0f6
source_hash: 092365bc7c841a6211ae86f15e9103994366d83650fed861f305112fb2ad41b7
source_path: cli/plugins.md
workflow: 16
---
@ -18,13 +18,13 @@ x-i18n:
<CardGroup cols={2}>
<Card title="插件系统" href="/zh-CN/tools/plugin">
面向最终用户的插件安装、启用和故障排除指南。
安装、启用和排查插件问题的最终用户指南。
</Card>
<Card title="插件 bundle" href="/zh-CN/plugins/bundles">
Bundle 兼容性模型。
</Card>
<Card title="插件清单" href="/zh-CN/plugins/manifest">
清单字段和配置架构。
清单字段和配置 schema。
</Card>
<Card title="安全" href="/zh-CN/gateway/security">
插件安装的安全加固。
@ -56,14 +56,14 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
要调查缓慢的安装、检查、卸载或注册表刷新问题，请使用 `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)。
<Note>
内置插件随 OpenClaw 一起提供。其中一些默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）；其他插件需要 `plugins enable`。
内置插件随 OpenClaw 一起发布。有些默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）；其他插件需要使用 `plugins enable`。
原生 OpenClaw 插件必须随附 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空）。兼容 bundle 改用自己的 bundle 清单。
原生 OpenClaw 插件必须随附 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空）。兼容 bundle 则使用它们自己的 bundle 清单。
`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细列表/info 输出还会显示 bundle 子类型（`codex`、`claude` 或 `cursor`）以及检测到的 bundle 能力。
`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细 list/info 输出还会显示 bundle 子类型（`codex`、`claude` 或 `cursor`）以及检测到的 bundle 能力。
</Note>
### 安装
@ -84,91 +84,91 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
```
<Warning>
裸包名会先对照 ClawHub 检查，然后再检查 npm。请像运行代码一样对待插件安装。优先使用固定版本。
裸包名会先通过 ClawHub 检查，然后再检查 npm。请像运行代码一样对待插件安装。优先使用固定版本。
</Warning>
<Note>
ClawHub 是大多数插件的主要分发和发现入口。Npm 仍是受支持的回退和直接安装路径。在迁移到 ClawHub 期间，OpenClaw 仍在 npm 上发布一些 OpenClaw 自有的 `@openclaw/*` 插件包；这些包版本可能会在插件发布列车之间落后于内置源码。如果 npm 将 OpenClaw 自有插件包报告为已弃用，则该已发布版本是旧的外部产物；请使用当前 OpenClaw 内置的插件或本地检出，直到更新的 npm 包发布。
ClawHub 是大多数插件的主要分发和发现入口。Npm 仍然是受支持的回退和直接安装路径。在迁移到 ClawHub 的过程中，OpenClaw 仍会在 npm 上发布一些 OpenClaw 自有的 `@openclaw/*` 插件包；在插件发布批次之间，这些包版本可能会落后于内置源码。如果 npm 将某个 OpenClaw 自有插件包报告为 deprecated，则该已发布版本是旧的外部产物；请使用当前 OpenClaw 内置的插件，或使用本地 checkout，直到发布更新的 npm 包。
</Note>
<AccordionGroup>
<Accordion title="配置包含和无效配置恢复">
如果你的 `plugins` 部分由单文件 `$include` 支持，`plugins install/update/enable/disable/uninstall` 会写入该包含文件，并保持 `openclaw.json` 不变。根包含、包含数组以及带同级覆盖的包含会封闭失败，而不是被展开。有关受支持的形状，请参见[配置包含](/zh-CN/gateway/configuration)。
<Accordion title="配置 include 和无效配置恢复">
如果你的 `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` 的插件。
</Accordion>
<Accordion title="--force 与重新安装和更新">
`--force` 会复用现有安装目标，并就地覆盖已安装的插件或钩子包。当你有意从新的本地路径、归档、ClawHub 包或 npm 产物重新安装同一 id 时使用它。对于已跟踪 npm 插件的常规升级，优先使用 `openclaw plugins update <id-or-npm-spec>`。
<Accordion title="--force 以及重新安装与更新">
`--force` 会复用现有安装目标，并就地覆盖已安装的插件或钩子包。当你有意从新的本地路径、归档、ClawHub 包或 npm 产物重新安装同一 id 时使用它。对于已跟踪 npm 插件的常规升级，请优先使用 `openclaw plugins update <id-or-npm-spec>`。
如果你对一个已安装的插件 id 运行 `plugins install`，OpenClaw 会停止，并指引你使用 `plugins update <id-or-npm-spec>` 进行普通升级，或在你确实想从不同来源覆盖当前安装时使用 `plugins install <package> --force`。
如果你对已安装的插件 id 运行 `plugins install`，OpenClaw 会停止并指引你使用 `plugins update <id-or-npm-spec>` 进行正常升级，或者在你确实想从不同来源覆盖当前安装时使用 `plugins install <package> --force`。
</Accordion>
<Accordion title="--pin 作用范围">
`--pin` 仅适用于 npm 安装。它不支持 `git:` 安装；当你想固定来源时，请使用显式 git ref，例如 `git:github.com/acme/plugin@v1.2.3`。它不支持 `--marketplace`，因为 marketplace 安装会保留 marketplace 来源元数据，而不是 npm spec。
<Accordion title="--pin 范围">
`--pin` 仅适用于 npm 安装。它不支持 `git:` 安装；当你想固定来源时，请使用显式 git ref，例如 `git:github.com/acme/plugin@v1.2.3`。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。
</Accordion>
<Accordion title="--dangerously-force-unsafe-install">
`--dangerously-force-unsafe-install` 是用于内置危险代码扫描器误报的应急选项。即使内置扫描器报告 `critical` 发现，它也允许安装继续，但它**不会**绕过插件 `before_install` 钩子策略阻断，也**不会**绕过扫描失败。
`--dangerously-force-unsafe-install` 是一个用于内置危险代码扫描器误报的破窗选项。即使内置扫描器报告 `critical` 发现项，它也允许安装继续，但它**不会**绕过插件 `before_install` 钩子策略阻断，也**不会**绕过扫描失败。
此 CLI 标志适用于插件安装/更新流程。由 Gateway 网关支持的 Skills 依赖安装使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍是单独的 ClawHub skill 下载/安装流程。
这个 CLI flag 适用于插件安装/更新流程。由 Gateway 网关支持的 skill 依赖安装使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖项，而 `openclaw skills install` 仍是独立的 ClawHub skill 下载/安装流程。
如果你发布到 ClawHub 的插件被注册表扫描阻断，请使用 [ClawHub](/zh-CN/tools/clawhub) 中的发布者步骤。
如果你在 ClawHub 上发布的插件被 registry 扫描阻断，请使用 [ClawHub](/zh-CN/tools/clawhub) 中的发布者步骤。
</Accordion>
<Accordion title="钩子包和 npm spec">
`plugins install` 也是安装在 `package.json` 中暴露 `openclaw.hooks` 的钩子包的入口。使用 `openclaw hooks` 查看筛选后的钩子可见性并启用单个钩子，而不是用于包安装。
<Accordion title="钩子包和 npm specs">
`plugins install` 也是安装在 `package.json` 中公开 `openclaw.hooks` 的钩子包的入口。使用 `openclaw hooks` 查看筛选后的钩子可见性和逐钩子启用状态，而不是用于包安装。
Npm spec **仅限注册表**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。为安全起见，依赖安装会使用 `--ignore-scripts` 在项目本地运行，即使你的 shell 配置了全局 npm 安装设置。
Npm specs **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file specs 和 semver 范围都会被拒绝。出于安全考虑，依赖安装会以项目本地方式运行，并带有 `--ignore-scripts`，即使你的 shell 具有全局 npm 安装设置也是如此。
当你想跳过 ClawHub 查询并直接从 npm 安装时，使用 `npm:<package>`。裸包 spec 仍会优先使用 ClawHub，并且仅在 ClawHub 没有该包或版本时回退到 npm。
当你想跳过 ClawHub 查找并直接从 npm 安装时，请使用 `npm:<package>`。裸包 spec 仍会优先使用 ClawHub，并且仅在 ClawHub 没有该包或版本时回退到 npm。
裸 spec 和 `@latest` 会停留在稳定轨道。如果 npm 将其中任一解析为预发布版本，OpenClaw 会停止，并要求你使用预发布标签（如 `@beta`/`@rc`）或精确预发布版本（如 `@1.2.3-beta.4`）显式选择加入。
裸 spec 和 `@latest` 保持在稳定轨道。如果 npm 将其中任一项解析为预发布版本，OpenClaw 会停止，并要求你使用预发布标签（例如 `@beta`/`@rc`）或精确预发布版本（例如 `@1.2.3-beta.4`）显式选择加入。
如果裸安装 spec 匹配官方插件 id（例如 `diffs`），OpenClaw 会直接安装目录条目。若要安装同名 npm 包，请使用显式 scoped spec（例如 `@scope/diffs`）。
</Accordion>
<Accordion title="Git 仓库">
使用 `git:<repo>` 直接从 git 仓库安装。受支持的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整 `https://`、`ssh://`、`git://`、`file://`，以及 `git@host:owner/repo.git` clone URL。添加 `@<ref>` 或 `#<ref>` 可在安装前检出分支、标签或提交。
使用 `git:<repo>` 直接从 git 仓库安装。支持的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整 `https://`、`ssh://`、`git://`、`file://`，以及 `git@host:owner/repo.git` 克隆 URL。添加 `@<ref>` 或 `#<ref>` 可在安装前 checkout 分支、标签或提交。
Git 安装会克隆到临时目录，在存在请求的 ref 时检出它，然后使用正常的插件目录安装器。这意味着清单验证、危险代码扫描、包管理器安装工作和安装记录的行为都与 npm 安装类似。记录的 git 安装包含来源 URL/ref 以及解析后的提交，因此 `openclaw plugins update` 以后可以重新解析来源。
Git 安装会克隆到临时目录，在存在请求的 ref 时 checkout 该 ref，然后使用正常的插件目录安装器。这意味着清单验证、危险代码扫描、包管理器安装工作以及安装记录的行为都类似 npm 安装。记录的 git 安装会包含来源 URL/ref 以及解析得到的提交，以便 `openclaw plugins update` 后续可以重新解析该来源。
从 git 安装后，使用 `openclaw plugins inspect <id> --runtime --json` 验证运行时注册，例如 gateway 方法和 CLI 命令。如果插件通过 `api.registerCli` 注册了 CLI 根命令，请通过 OpenClaw 根 CLI 直接执行该命令，例如 `openclaw demo-plugin ping`。
从 git 安装后，使用 `openclaw plugins inspect <id> --runtime --json` 验证运行时注册项，例如 gateway 方法和 CLI 命令。如果插件使用 `api.registerCli` 注册了 CLI 根命令，请通过 OpenClaw 根 CLI 直接执行该命令，例如 `openclaw demo-plugin ping`。
</Accordion>
<Accordion title="归档">
支持的归档：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw 插件归档必须在解压后的插件根目录包含有效的 `openclaw.plugin.json`；仅包含 `package.json` 的归档会在 OpenClaw 写入安装记录之前被拒绝。
支持的归档：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw 插件归档必须在解压后的插件根目录包含有效的 `openclaw.plugin.json`；只包含 `package.json` 的归档会在 OpenClaw 写入安装记录之前被拒绝。
也支持 Claude marketplace 安装。
</Accordion>
</AccordionGroup>
ClawHub 安装使用显式 `clawhub:<package>` 定位符：
ClawHub 安装使用显式 `clawhub:<package>` locator：
```bash
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
OpenClaw 现在也会优先对裸 npm 安全插件 spec 使用 ClawHub。只有当 ClawHub 没有该包或版本时，它才会回退到 npm：
OpenClaw 现在也会对裸 npm 安全插件 spec 优先使用 ClawHub。只有在 ClawHub 没有该包或版本时，它才会回退到 npm：
```bash
openclaw plugins install openclaw-codex-app-server
```
使用 `npm:` 强制仅解析 npm，例如当 ClawHub 无法访问，或你知道该包只存在于 npm 上时：
使用 `npm:` 强制仅使用 npm 解析，例如当 ClawHub 无法访问，或你知道该包只存在于 npm 上时：
```bash
openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/plugin-name@1.0.1
```
OpenClaw 会从 ClawHub 下载包归档，检查声明的插件 API / 最低 gateway 兼容性，然后通过正常的归档路径安装。记录的安装会保留其 ClawHub 来源元数据，以供后续更新使用。
未带版本的 ClawHub 安装会保留未带版本的记录 spec，因此 `openclaw plugins update` 可以跟随后续较新的 ClawHub 发布；显式版本或标签选择器（如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）仍会固定到该选择器。
OpenClaw 会在安装前检查声明的插件 API / 最低 gateway 兼容性。当选定的 ClawHub 版本发布了 ClawPack 产物时，OpenClaw 会下载带版本的 ClawPack，验证 ClawHub digest header 和产物 digest，然后通过正常归档路径安装它。没有 ClawPack 元数据的旧 ClawHub 版本仍会通过旧版包归档验证路径安装。记录的安装会保留其 ClawHub 来源元数据和 ClawPack digest 事实，以供后续更新使用。
未指定版本的 ClawHub 安装会保留未指定版本的记录 spec，使 `openclaw plugins update` 可以跟随后续较新的 ClawHub 发布；显式版本或标签选择器（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）仍会固定到该选择器。
#### Marketplace 简写
当 marketplace 名称存在于 Claude 的本地注册表缓存 `~/.claude/plugins/known_marketplaces.json` 中时，使用 `plugin@marketplace` 简写：
当 marketplace 名称存在于 Claude 本地 registry 缓存 `~/.claude/plugins/known_marketplaces.json` 中时，使用 `plugin@marketplace` 简写：
```bash
openclaw plugins marketplace list <marketplace-name>
@ -188,25 +188,25 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
<Tab title="Marketplace 来源">
- 来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称
- 本地 marketplace 根目录或 `marketplace.json` 路径
- GitHub 仓库简写，例如 `owner/repo`
- GitHub 仓库 URL，例如 `https://github.com/owner/repo`
- GitHub repo 简写，例如 `owner/repo`
- GitHub repo URL，例如 `https://github.com/owner/repo`
- git URL
</Tab>
<Tab title="远程 marketplace 规则">
对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保留在克隆的 marketplace 仓库内。OpenClaw 接受来自该仓库的相对路径来源，并拒绝远程清单中的 HTTP(S)、绝对路径、git、GitHub 和其他非路径插件来源。
对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保留在克隆的 marketplace repo 内部。OpenClaw 接受来自该 repo 的相对路径来源，并拒绝远程清单中的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径插件来源。
</Tab>
</Tabs>
对于本地路径和归档，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`）
<Note>
兼容捆绑包会安装到常规插件根目录，并参与同一个 list/info/enable/disable 流程。目前支持捆绑包 Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录；其他检测到的捆绑包能力会显示在 diagnostics/info 中，但尚未接入运行时执行。
兼容包会安装到常规插件根目录，并参与同一套列表/信息/启用/禁用流程。目前支持包内 Skills、Claude 命令 Skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor 命令 Skills，以及兼容的 Codex 钩子目录；其他检测到的包能力会显示在诊断/信息中，但尚未接入运行时执行。
</Note>
### 列表
@ -222,23 +222,23 @@ openclaw plugins list --json
仅显示已启用的插件。
</ParamField>
<ParamField path="--verbose" type="boolean">
从表格视图切换为每个插件一行的详情，包含 source/origin/version/activation 元数据。
从表格视图切换为按插件显示的详情行，其中包含来源/源头/版本/激活元数据。
</ParamField>
<ParamField path="--json" type="boolean">
机器可读的清单以及 registry diagnostics。
机器可读的清单，以及注册表诊断信息。
</ParamField>
<Note>
`plugins list` 会先读取持久化的本地插件注册表；如果注册表缺失或无效，则回退到仅由清单派生的结果。它适用于检查插件是否已安装、已启用，并且对冷启动规划可见，但它不是对已运行 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、钩子策略或 `plugins.load.paths` 后，请先重启为该渠道提供服务的 Gateway 网关，再期望新的 `register(api)` 代码或钩子运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不是只重启包装进程。
`plugins list` 会先读取持久化的本地插件注册表；当注册表缺失或无效时，会回退到仅由清单派生的结果。它适合用来检查插件是否已安装、已启用，以及是否对冷启动规划可见，但它不是对已运行 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、钩子策略或 `plugins.load.paths` 后，请先重启服务该渠道的 Gateway 网关，再期待新的 `register(api)` 代码或钩子运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不只是包装进程。
</Note>
在打包 Docker 镜像内处理内置插件时，请将插件源目录绑定挂载到匹配的打包源路径上，例如 `/app/extensions/synology-chat`。OpenClaw 会先发现该已挂载的源码覆盖层，再发现 `/app/dist/extensions/synology-chat`；普通复制的源码目录仍保持惰性，因此常规打包安装仍会使用编译后的 dist。
在打包的 Docker 镜像内处理内置插件时，请将插件源目录绑定挂载到匹配的打包源路径上，例如 `/app/extensions/synology-chat`。OpenClaw 会先于 `/app/dist/extensions/synology-chat` 发现该挂载的源码覆盖层；普通复制的源目录仍然不会生效，因此常规打包安装仍会使用已编译的 dist。
用于运行时钩子调试：
- `openclaw plugins inspect <id> --runtime --json` 会显示来自一次模块加载检查过程的已注册钩子和诊断信息。运行时检查绝不会安装依赖；请使用 `openclaw doctor --fix` 清理旧版依赖状态，或安装缺失的已配置可下载插件。
- `openclaw plugins inspect <id> --runtime --json` 会显示来自模块加载检查流程的已注册钩子和诊断信息。运行时检查从不安装依赖；请使用 `openclaw doctor --fix` 清理旧依赖状态，或安装缺失的已配置可下载插件。
- `openclaw gateway status --deep --require-rpc` 会确认可访问的 Gateway 网关、服务/进程提示、配置路径和 RPC 健康状态。
- 非内置会话钩子（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
- 非内置的会话钩子（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
使用 `--link` 可避免复制本地目录（会添加到 `plugins.load.paths`）：
@ -247,16 +247,16 @@ openclaw plugins install -l ./my-plugin
```
<Note>
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是覆盖托管安装目标。
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是覆盖受管理的安装目标。
在 npm 安装中使用 `--pin`，可将解析后的精确规格（`name@version`）保存到托管插件索引中，同时保持默认行为为未固定版本。
在 npm 安装中使用 `--pin`，可将解析得到的精确规格（`name@version`）保存到受管理的插件索引中，同时保持默认行为为不固定版本。
</Note>
### 插件索引
插件安装元数据是机器管理的状态，不是用户配置。安装和更新会将它写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。其中顶层 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件清单的记录。`plugins` 数组是从清单派生的冷注册表缓存。该文件包含“请勿编辑”警告，并被 `openclaw plugins update`、卸载、诊断和冷插件注册表使用。
插件安装元数据是机器管理的状态，而不是用户配置。安装和更新会将其写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。其顶层 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件清单的记录。`plugins` 数组是由清单派生的冷注册表缓存。该文件包含不要编辑的警告，并由 `openclaw plugins update`、卸载、诊断和冷插件注册表使用。
当 OpenClaw 在配置中看到已发布的旧版 `plugins.installs` 记录时，会将它们移动到插件索引并移除该配置键；如果任一写入失败，配置记录会被保留，以避免安装元数据丢失。
当 OpenClaw 在配置中看到已发布的旧版 `plugins.installs` 记录时，会将它们移入插件索引并移除该配置键；如果任一写入失败，配置记录会保留，以免安装元数据丢失。
### 卸载
@ -266,7 +266,7 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` 会从 `plugins.entries`、持久化插件索引、插件 allow/deny 列表条目，以及适用时的已链接 `plugins.load.paths` 条目中移除插件记录。除非设置了 `--keep-files`，否则卸载还会移除跟踪到的托管安装目录，前提是该目录位于 OpenClaw 的插件扩展根目录内。对于主动记忆插件，记忆槽会重置为 `memory-core`。
`uninstall` 会从 `plugins.entries`、持久化插件索引、插件允许/拒绝列表条目，以及适用时链接的 `plugins.load.paths` 条目中移除插件记录。除非设置了 `--keep-files`，卸载还会移除跟踪的受管理安装目录，前提是该目录位于 OpenClaw 的插件 extensions 根目录内。对于主动记忆插件，记忆槽会重置为 `memory-core`。
<Note>
`--keep-config` 作为 `--keep-files` 的已弃用别名受支持。
@ -282,25 +282,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` 中跟踪的钩子包安装。
<AccordionGroup>
<Accordion title="Resolving plugin id vs npm spec">
当你传入插件 id 时，OpenClaw 会复用该插件已记录的安装规格。这意味着之前存储的 dist-tag（如 `@beta`）和精确固定版本会在后续 `update <id>` 运行中继续使用。
<Accordion title="解析插件 id 与 npm 规格">
当你传入插件 id 时，OpenClaw 会复用该插件记录的安装规格。这意味着此前存储的 dist-tag（如 `@beta`）和精确固定版本会在之后的 `update <id>` 运行中继续使用。
对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包规格。OpenClaw 会将该包名解析回被跟踪的插件记录，更新该已安装插件，并记录新的 npm 规格用于未来基于 id 的更新。
对于 npm 安装，你也可以传入带 dist-tag 或精确版本的显式 npm 包规格。OpenClaw 会将该包名解析回被跟踪的插件记录，更新该已安装插件，并记录新的 npm 规格以供未来基于 id 的更新使用。
传入不带版本或标签的 npm 包名也会解析回被跟踪的插件记录。当某个插件已固定到精确版本，而你想将它移回注册表默认发布线时，请使用这种方式。
传入不带版本或标签的 npm 包名，也会解析回被跟踪的插件记录。当某个插件曾固定到精确版本，而你想将其移回注册表默认发布线时，请使用这种方式。
</Accordion>
<Accordion title="Version checks and integrity drift">
在实时 npm 更新前，OpenClaw 会根据 npm 注册表元数据检查已安装包版本。如果已安装版本和已记录工件身份已经匹配解析后的目标，则会跳过更新，不下载、不重新安装，也不重写 `openclaw.json`。
<Accordion title="版本检查和完整性漂移">
在实时 npm 更新之前，OpenClaw 会根据 npm 注册表元数据检查已安装包版本。如果已安装版本和记录的构件身份已经与解析目标匹配，则会跳过更新，不会下载、重新安装或重写 `openclaw.json`。
当存在已存储的 integrity hash 且获取到的工件 hash 发生变化时，OpenClaw 会将其视为 npm 工件漂移。交互式 `openclaw plugins update` 命令会打印预期 hash 和实际 hash，并在继续前请求确认。非交互式更新辅助工具会默认关闭失败，除非调用方提供显式继续策略。
当存在已存储的完整性哈希且获取到的构件哈希发生变化时，OpenClaw 会将其视为 npm 构件漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前要求确认。非交互式更新助手会默认关闭失败，除非调用方提供显式的继续策略。
</Accordion>
<Accordion title="--dangerously-force-unsafe-install on update">
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的破窗覆盖开关。它仍不会绕过插件 `before_install` 策略阻断或扫描失败阻断，并且只适用于插件更新，不适用于 hook-pack 更新。
<Accordion title="更新时使用 --dangerously-force-unsafe-install">
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的应急覆盖开关。它仍不会绕过插件 `before_install` 策略阻止或扫描失败阻止，并且只适用于插件更新，不适用于钩子包更新。
</Accordion>
</AccordionGroup>
@ -312,21 +312,21 @@ openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
```
Inspect 默认不会导入插件运行时，会显示身份、加载状态、来源、清单能力、策略标志、诊断、安装元数据、捆绑包能力，以及检测到的任何 MCP 或 LSP server 支持。添加 `--runtime` 可加载插件模块，并包含已注册的钩子、工具、命令、服务、Gateway 网关方法和 HTTP 路由。运行时检查会直接报告缺失的插件依赖；安装和修复仍保留在 `openclaw plugins install`、`openclaw plugins update` 和 `openclaw doctor --fix` 中。
检查会显示身份、加载状态、来源、清单能力、策略标志、诊断、安装元数据、包能力，以及任何检测到的 MCP 或 LSP 服务器支持，默认不会导入插件运行时。添加 `--runtime` 会加载插件模块，并包含已注册的钩子、工具、命令、服务、Gateway 网关方法和 HTTP 路由。运行时检查会直接报告缺失的插件依赖；安装和修复仍位于 `openclaw plugins install`、`openclaw plugins update` 和 `openclaw doctor --fix` 中。
插件拥有的 CLI 命令会安装为根 `openclaw` 命令组。在 `inspect --runtime` 的 `cliCommands` 下看到命令后，请以 `openclaw <command> ...` 运行它；例如，注册了 `demo-git` 的插件可以用 `openclaw demo-git ping` 验证。
插件拥有的 CLI 命令会作为根 `openclaw` 命令组安装。在 `inspect --runtime` 于 `cliCommands` 下显示命令后，请以 `openclaw <command> ...` 运行它；例如，注册了 `demo-git` 的插件可通过 `openclaw demo-git ping` 验证。
每个插件会按其运行时实际注册的内容分类：
每个插件会按其在运行时实际注册的内容分类：
- **plain-capability** — 一种能力类型（例如仅提供商插件）
- **hybrid-capability** — 多种能力类型（例如文本 + 语音 + 图像）
- **hook-only** — 只有钩子，没有能力或表面
- **hook-only** — 只有钩子，没有能力或界面
- **non-capability** — 有工具/命令/服务，但没有能力
有关能力模型的更多信息，请参阅 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。
有关能力模型的更多信息，请参阅[插件形态](/zh-CN/plugins/architecture#plugin-shapes)。
<Note>
`--json` 标志会输出适合脚本和审计的机器可读报告。`inspect --all` 会渲染全局表格，包含 shape、capability kinds、compatibility notices、bundle capabilities 和 hook summary 列。`info` 是 `inspect` 的别名。
`--json` 标志会输出适合脚本和审计的机器可读报告。`inspect --all` 会呈现全局表格，其中包含形态、能力种类、兼容性通知、包能力和钩子摘要列。`info` 是 `inspect` 的别名。
</Note>
### Doctor
@ -335,9 +335,9 @@ Inspect 默认不会导入插件运行时，会显示身份、加载状态、来
openclaw plugins doctor
```
`doctor` 会报告插件加载错误、清单/发现诊断和兼容性提示。一切正常时，它会打印 `No plugin issues detected.`
`doctor` 会报告插件加载错误、清单/发现诊断和兼容性通知。当一切正常时，它会打印 `No plugin issues detected.`
对于模块形态失败，例如缺少 `register`/`activate` 导出，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以便在诊断输出中包含紧凑的导出形态摘要。
对于缺少 `register`/`activate` 导出等模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以便在诊断输出中包含紧凑的导出形态摘要。
### 注册表
@ -347,22 +347,22 @@ openclaw plugins registry --refresh
openclaw plugins registry --json
```
本地插件注册表是 OpenClaw 对已安装插件身份、启用状态、来源元数据和贡献归属的持久化冷读模型。常规启动、提供商归属查找、渠道设置分类和插件清单可以读取它，而无需导入插件运行时模块。
本地插件注册表是 OpenClaw 针对已安装插件身份、启用状态、来源元数据和贡献归属持久化的冷读模型。常规启动、提供商归属查询、渠道设置分类和插件清单都可以读取它，而无需导入插件运行时模块。
使用 `plugins registry` 检查持久化注册表是否存在、是否当前有效或是否过期。使用 `--refresh` 可根据持久化插件索引、配置策略和清单/包元数据重建它。这是修复路径，不是运行时激活路径。
使用 `plugins registry` 检查持久化注册表是否存在、是否当前有效或是否陈旧。使用 `--refresh` 可根据持久化插件索引、配置策略和清单/包元数据重建它。这是修复路径，不是运行时激活路径。
<Warning>
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是一个已弃用的破窗兼容性开关，用于注册表读取失败。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；该环境变量回退只用于迁移推出期间的紧急启动恢复。
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是已弃用的应急兼容性开关，用于处理注册表读取失败。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；环境变量回退只用于迁移推出期间的紧急启动恢复。
</Warning>
### 市场
### 插件市场
```bash
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
Marketplace list 接受本地 marketplace 路径、`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。`--json` 会打印解析后的来源标签，以及已解析的 marketplace 清单和插件条目。
插件市场列表接受本地市场路径、`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL 或 git URL。`--json` 会打印解析后的来源标签，以及已解析的市场清单和插件条目。
## 相关

165
docs/zh-CN/tools/clawhub.md
View File

@ -7,18 +7,18 @@ sidebarTitle: ClawHub
summary: ClawHub：OpenClaw Skills 和插件的公共注册表、原生安装流程，以及 clawhub CLI
title: ClawHub
x-i18n:
generated_at: "2026-04-28T23:40:23Z"
generated_at: "2026-05-02T00:39:07Z"
model: gpt-5.5
provider: openai
source_hash: 9ec09a3c76820137eb1f7ca829a184fc1ed6392d3b32a327ecbda4d2cad7a78d
source_hash: b23214ee75ddf0d0c741a43cb3b40cbcd433b9288038184b7126ab9d4daad228
source_path: tools/clawhub.md
workflow: 16
---
ClawHub 是用于 **OpenClaw Skills 和插件** 的公共注册表。
ClawHub 是 **OpenClaw Skills 和插件** 的公共注册表。
- 使用原生 `openclaw` 命令搜索、安装和更新 Skills，并从 ClawHub 安装插件。
- 使用单独的 `clawhub` CLI 执行注册表凭证、发布、删除/取消删除和同步工作流。
- 使用单独的 `clawhub` CLI 完成注册表认证、发布、删除/恢复删除以及同步工作流。
站点：[clawhub.ai](https://clawhub.ai)
@ -39,7 +39,7 @@ ClawHub 是用于 **OpenClaw Skills 和插件** 的公共注册表。
启动新的 OpenClaw 会话，它会加载新的 Skill。
</Step>
<Step title="发布（可选）">
对于需要注册表凭证的工作流（发布、同步、管理），请安装
对于需要注册表认证的工作流（发布、同步、管理），请安装
单独的 `clawhub` CLI：
```bash
@ -51,7 +51,7 @@ ClawHub 是用于 **OpenClaw Skills 和插件** 的公共注册表。
</Step>
</Steps>
## 原生 OpenClaw 工作流
## 原生 OpenClaw 流程
<Tabs>
<Tab title="Skills">
@ -61,8 +61,8 @@ ClawHub 是用于 **OpenClaw Skills 和插件** 的公共注册表。
openclaw skills update --all
```
原生 `openclaw` 命令会安装到你的活动工作区，并
持久保存来源元数据，因此后续 `update` 调用可以继续使用 ClawHub。
原生 `openclaw` 命令会安装到你的当前工作区，并
持久化来源元数据，因此后续 `update` 调用可以继续使用 ClawHub。
</Tab>
<Tab title="插件">
@ -71,34 +71,38 @@ ClawHub 是用于 **OpenClaw Skills 和插件** 的公共注册表。
openclaw plugins update --all
```
裸 npm 安全插件规格也会先尝试在 ClawHub 中解析，然后再尝试 npm：
裸 npm 安全插件规格也会先尝试在 ClawHub 中解析，再回退到 npm：
```bash
openclaw plugins install openclaw-codex-app-server
```
如果你只想通过 npm 解析而不查询
ClawHub，请使用 `npm:<package>`：
当你只想使用 npm 解析而不进行
ClawHub 查找时，请使用 `npm:<package>`：
```bash
openclaw plugins install npm:openclaw-codex-app-server
```
插件安装会在归档安装运行前验证声明的 `pluginApi` 和
`minGatewayVersion` 兼容性，因此不兼容的主机会提前关闭失败，而不是
部分安装该包。
插件安装会在运行归档安装之前验证声明的 `pluginApi` 和
`minGatewayVersion` 兼容性，因此不兼容的主机会尽早以关闭方式失败，
而不是部分安装该包。当某个包版本发布 ClawPack 工件时，
OpenClaw 会优先使用该工件，验证 ClawHub 摘要标头和
下载的字节，并记录 ClawPack 摘要元数据供后续
更新使用。没有 ClawPack 元数据的较旧包版本仍使用
旧版包归档验证路径。
</Tab>
</Tabs>
<Note>
`openclaw plugins install clawhub:...` 只接受可安装的插件
系列。如果 ClawHub 包实际上是 Skill，OpenClaw 会停止，并
改为引导你使用 `openclaw skills install <slug>`。
系列。如果某个 ClawHub 包实际上是 Skill，OpenClaw 会停止并
指向 `openclaw skills install <slug>`。
匿名 ClawHub 插件安装也会对私有包关闭失败。
匿名 ClawHub 插件安装对于私有包也会以关闭方式失败。
社区或其他非官方渠道仍可安装，但 OpenClaw
会发出警告，以便操作员在启用前检查来源和验证。
会发出警告，以便操作者在启用前检查来源和验证结果。
</Note>
## ClawHub 是什么
@ -107,72 +111,72 @@ ClawHub 是用于 **OpenClaw Skills 和插件** 的公共注册表。
- Skill 包和元数据的版本化存储。
- 用于搜索、标签和使用信号的发现界面。
典型 Skill 是一个版本化文件包，其中包括：
典型的 Skill 是一组版本化文件包，其中包括：
- 包含主要描述和用法的 `SKILL.md` 文件。
- 一个包含主要描述和用法的 `SKILL.md` 文件。
- Skill 使用的可选配置、脚本或支持文件。
- 标签、摘要和安装要求等元数据。
ClawHub 使用元数据来支持发现，并安全地暴露 Skill
能力。注册表会跟踪使用信号（星标、下载量）以
改进排序和可见性。每次发布都会创建新的 semver
版本，注册表会保留版本历史，便于用户审计
ClawHub 使用元数据来支持发现，并安全地公开 Skill
能力。注册表会跟踪使用信号（星标、下载量），以
改进排序和可见性。每次发布都会创建一个新的 semver
版本，注册表会保留版本历史，以便用户审计
变更。
## 工作区和 Skill 加载
单独的 `clawhub` CLI 也会将 Skills 安装到
当前工作目录下的 `./skills`。如果已配置 OpenClaw 工作区，
当前工作目录下的 `./skills`。如果配置了 OpenClaw 工作区，
`clawhub` 会回退到该工作区，除非你覆盖 `--workdir`
（或 `CLAWHUB_WORKDIR`）。OpenClaw 会从
`<workspace>/skills` 加载工作区 Skills，并在**下一次**会话中加载它们。
如果你已经使用 `~/.openclaw/skills` 或内置 Skills，工作区
Skills 优先级更高。有关 Skills 如何加载、
共享和受控的更多详情，请参阅 [Skills](/zh-CN/tools/skills)。
Skills 会优先生效。有关 Skills 如何加载、
共享和受控的更多细节，请参阅 [Skills](/zh-CN/tools/skills)。
## 服务功能
| 功能 | 说明 |
| 功能 | 说明 |
| ------------------------ | ------------------------------------------------------------------- |
| 公开浏览 | Skills 及其 `SKILL.md` 内容可公开查看。 |
| 搜索 | 由嵌入驱动（向量搜索），不只是关键字。 |
| 版本控制 | Semver、更新日志和标签（包括 `latest`）。 |
| 下载 | 每个版本一个 Zip。 |
| 星标和评论 | 社区反馈。 |
| 安全扫描摘要 | 详情页会在安装或下载前显示最新扫描状态。 |
| 扫描器详情页 | VirusTotal、ClawScan 和静态分析结果都有深层链接。 |
| 所有者恢复仪表板 | 发布者可以从 `/dashboard` 查看因扫描而保留的自有内容。 |
| 所有者请求重新扫描 | 所有者可以为误报恢复请求有限次数的重新扫描。 |
| 内容审核 | 审批和审计。 |
| CLI 友好的 API | 适合自动化和脚本。 |
| 公开浏览 | Skills 及其 `SKILL.md` 内容可公开查看。 |
| 搜索 | 由嵌入驱动（向量搜索），不仅仅是关键词。 |
| 版本管理 | Semver、变更日志和标签（包括 `latest`）。 |
| 下载 | 每个版本一个 zip。 |
| 星标和评论 | 社区反馈。 |
| 安全扫描摘要 | 详情页会在安装或下载前显示最新扫描状态。 |
| 扫描器详情页 | VirusTotal、ClawScan 和静态分析结果有深层链接。 |
| 所有者恢复仪表盘 | 发布者可以从 `/dashboard` 查看被扫描保留的自有内容。 |
| 所有者请求的重新扫描 | 所有者可以请求有限次数的重新扫描，用于误报恢复。 |
| 审核 | 批准和审计。 |
| CLI 友好的 API | 适合自动化和脚本编写。 |
## 安全和内容审核
## 安全与审核
ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
账号必须**至少创建一周**才能发布。这可以减缓
滥用，而不会阻挡合法贡献者。
账号必须**至少创建一周**才可以发布。这会减缓
滥用，同时不阻碍合法贡献者。
<AccordionGroup>
<Accordion title="安全扫描">
ClawHub 会对已发布的 Skills 和插件
版本运行自动安全检查。公开详情页会汇总当前结果，扫描器
发布版本运行自动安全检查。公开详情页会摘要当前结果，扫描器
行会链接到 VirusTotal、ClawScan 和静态
分析的专用详情页。
因扫描而保留或阻止的版本可能无法出现在公开目录和
安装界面中，但其所有者仍可在 `/dashboard` 中看到。
被扫描保留或被阻止的发布版本可能无法在公开目录和
安装界面中使用，但其所有者仍可在 `/dashboard` 中看到。
</Accordion>
<Accordion title="报告">
- 任何已登录用户都可以报告 Skill。
- 必须提供并记录报告原因。
- 每个用户同一时间最多可以有 20 个活动报告。
- 默认情况下，拥有超过 3 个唯一报告的 Skills 会自动隐藏。
- 必须提供报告原因，并且会被记录。
- 每个用户同一时间最多可以有 20 个活跃报告。
- 拥有超过 3 个唯一报告的 Skills 默认会被自动隐藏。
</Accordion>
<Accordion title="内容审核">
- 审核员可以查看隐藏的 Skills、取消隐藏、删除它们或封禁用户。
<Accordion title="审核">
- 审核员可以查看隐藏的 Skills、取消隐藏、删除，或封禁用户。
- 滥用报告功能可能导致账号被封禁。
- 有兴趣成为审核员？请在 OpenClaw Discord 中询问，并联系审核员或维护者。
@ -181,7 +185,8 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
## ClawHub CLI
只有在发布/同步等需要注册表凭证的工作流中才需要它。
只有在发布/同步等需要注册表认证的工作流中，
你才需要使用它。
### 全局选项
@ -189,7 +194,7 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
工作目录。默认：当前目录；回退到 OpenClaw 工作区。
</ParamField>
<ParamField path="--dir <dir>" type="string" default="skills">
Skills 目录，相对于 workdir。
Skills 目录，相对于工作目录。
</ParamField>
<ParamField path="--site <url>" type="string">
站点基础 URL（浏览器登录）。
@ -207,7 +212,7 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
### 命令
<AccordionGroup>
<Accordion title="凭证（login / logout / whoami）">
<Accordion title="认证（登录 / 登出 / whoami）">
```bash
clawhub login # browser flow
clawhub login --token <token>
@ -217,8 +222,8 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
登录选项：
- `--token <token>` — 粘贴 API 令牌。
- `--label <label>` — 为浏览器登录令牌存储的标签（默认：`CLI token`）。
- `--token <token>` — 粘贴 API token。
- `--label <label>` — 为浏览器登录 token 存储的标签（默认：`CLI token`）。
- `--no-browser` — 不打开浏览器（需要 `--token`）。
</Accordion>
@ -245,9 +250,9 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
- `--family skill|code-plugin|bundle-plugin` — 筛选包系列。
- `--official` — 仅显示官方包。
- `--executes-code` — 仅显示执行代码的包。
- `--executes-code` — 仅显示会执行代码的包。
- `--version <version>` / `--tag <tag>` — 检查特定包版本。
- `--versions`, `--files`, `--file <path>` — 检查包历史和文件。
- `--versions`、`--files`、`--file <path>` — 检查包历史和文件。
- `--json` — 机器可读输出。
</Accordion>
@ -261,7 +266,7 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
选项：
- `--version <version>` — 安装或更新到特定版本（`update` 中仅限单个 slug）。
- `--version <version>` — 安装或更新到特定版本（`update` 上仅限单个 slug）。
- `--force` — 如果文件夹已存在，或本地文件与任何已发布版本都不匹配，则覆盖。
- `clawhub list` 读取 `.clawhub/lock.json`。
@ -276,7 +281,7 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
- `--slug <slug>` — Skill slug。
- `--name <name>` — 显示名称。
- `--version <version>` — semver 版本。
- `--changelog <text>` — 更新日志文本（可为空）。
- `--changelog <text>` — 变更日志文本（可以为空）。
- `--tags <tags>` — 逗号分隔的标签（默认：`latest`）。
</Accordion>
@ -285,13 +290,13 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
clawhub package publish <source>
```
`<source>` 可以是本地文件夹、`owner/repo`、`owner/repo@ref` 或
`<source>` 可以是本地文件夹、`owner/repo`、`owner/repo@ref`，或
GitHub URL。
选项：
- `--dry-run` — 构建精确的发布计划，但不上传任何内容。
- `--json` — 为 CI 发出机器可读输出。
- `--dry-run` — 构建精确的发布计划，不上传任何内容。
- `--json` — 为 CI 输出机器可读内容。
- `--source-repo`、`--source-commit`、`--source-ref` — 当自动检测不足时使用的可选覆盖项。
</Accordion>
@ -304,21 +309,21 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
clawhub package rescan <name> --yes --json
```
重新扫描命令需要已登录的所有者令牌，并以最新
已发布的 Skill 版本或插件版本为目标。在非交互式运行中，请传入
重新扫描命令需要已登录的所有者 token，并以最新的
已发布 Skill 版本或插件发布版本为目标。在非交互式运行中，请传入
`--yes`。
JSON 响应包括目标类型、名称、版本、重新扫描状态，以及
该版本或发布剩余/最大请求次数。
该版本或发布版本的剩余/最大请求次数。
</Accordion>
<Accordion title="删除 / 取消删除（所有者或管理员）">
<Accordion title="删除 / 恢复删除（所有者或管理员）">
```bash
clawhub delete <slug> --yes
clawhub undelete <slug> --yes
```
</Accordion>
<Accordion title="同步（扫描本地 + 发布新的或已更新的内容）">
<Accordion title="同步（扫描本地 + 发布新增或更新内容）">
```bash
clawhub sync
```
@ -326,10 +331,10 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
选项：
- `--root <dir...>` — 额外扫描根目录。
- `--all` — 无提示上传所有内容。
- `--all` — 不提示，上传所有内容。
- `--dry-run` — 显示将要上传的内容。
- `--bump <type>` — 更新使用 `patch|minor|major`（默认：`patch`）。
- `--changelog <text>` — 非交互式更新的更新日志。
- `--changelog <text>` — 非交互式更新的变更日志。
- `--tags <tags>` — 逗号分隔的标签（默认：`latest`）。
- `--concurrency <n>` — 注册表检查（默认：`4`）。
@ -405,9 +410,9 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
}
```
已发布的包应包含**构建后的 JavaScript**，并让 `runtimeExtensions` 指向该输出。Git checkout 安装在没有构建文件时仍可回退到 TypeScript 源码，但构建后的运行时入口可以避免在启动、Doctor 和插件加载路径中进行运行时 TypeScript 编译。
已发布的包应随附**构建后的 JavaScript**，并让 `runtimeExtensions` 指向该输出。Git 检出安装在没有构建文件时仍可回退到 TypeScript 源码，但构建后的运行时入口可避免在启动、Doctor 和插件加载路径中进行运行时 TypeScript 编译。
## 版本控制、锁文件和遥测
## 版本控制、lockfile 和遥测
<AccordionGroup>
<Accordion title="版本控制和标签">
@ -417,18 +422,18 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
</Accordion>
<Accordion title="本地更改与注册表版本">
更新会使用内容哈希将本地 Skill 内容与注册表版本进行比较。如果本地文件不匹配任何已发布版本，CLI 会在覆盖前询问（或在非交互式运行中要求使用 `--force`）。
更新会使用内容哈希比较本地 Skill 内容与注册表版本。如果本地文件与任何已发布版本都不匹配，CLI 会在覆盖前询问（或在非交互式运行中要求使用 `--force`）。
</Accordion>
<Accordion title="同步扫描和回退根目录">
`clawhub sync` 会先扫描你当前的工作目录。如果没有找到 Skills，它会回退到已知的旧版位置（例如 `~/openclaw/skills` 和 `~/.openclaw/skills`）。这用于在无需额外标志的情况下找到较旧的 Skill 安装。
`clawhub sync` 会先扫描你当前的工作目录。如果未找到 Skills，它会回退到已知的旧版位置（例如 `~/openclaw/skills` 和 `~/.openclaw/skills`）。这旨在无需额外标志即可找到较旧的 Skill 安装。
</Accordion>
<Accordion title="存储和锁文件">
- 已安装的 Skills 会记录在你工作目录下的 `.clawhub/lock.json` 中。
- 凭证令牌存储在 ClawHub CLI 配置文件中（可通过 `CLAWHUB_CONFIG_PATH` 覆盖）。
<Accordion title="存储和 lockfile">
- 已安装的 Skills 记录在你的工作目录下的 `.clawhub/lock.json` 中。
- 认证令牌存储在 ClawHub CLI 配置文件中（可通过 `CLAWHUB_CONFIG_PATH` 覆盖）。
</Accordion>
<Accordion title="遥测（安装计数）">
当你在已登录状态下运行 `clawhub sync` 时，CLI 会发送一个最小快照来计算安装计数。你可以完全禁用它：
<Accordion title="遥测（安装次数）">
当你在已登录状态下运行 `clawhub sync` 时，CLI 会发送一个最小快照来计算安装次数。你可以完全禁用此功能：
```bash
export CLAWHUB_DISABLE_TELEMETRY=1
@ -445,9 +450,9 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
| `CLAWHUB_REGISTRY` | 覆盖注册表 API URL。 |
| `CLAWHUB_CONFIG_PATH` | 覆盖 CLI 存储令牌/配置的位置。 |
| `CLAWHUB_WORKDIR` | 覆盖默认工作目录。 |
| `CLAWHUB_DISABLE_TELEMETRY=1` | 在 `sync` 上禁用遥测。 |
| `CLAWHUB_DISABLE_TELEMETRY=1` | 在 `sync` 时禁用遥测。 |
## 相关
## 相关内容
- [社区插件](/zh-CN/plugins/community)
- [插件](/zh-CN/tools/plugin)