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 18:35:05 +00:00
parent cb00e9343e
commit 739bbc31ab
2 changed files with 242 additions and 256 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -4,13 +4,13 @@ read_when:
- 将 Skills 或插件发布到注册表
- 配置 clawhub CLI 或其环境覆盖项
sidebarTitle: ClawHub
summary: ClawHub：用于 OpenClaw Skills 和插件、原生安装流程以及 clawhub CLI 的公共注册表
summary: ClawHub：OpenClaw Skills 和插件的公共注册表、原生安装流程，以及 clawhub CLI
title: ClawHub
x-i18n:
generated_at: "2026-05-02T17:21:54Z"
generated_at: "2026-05-02T18:33:40Z"
model: gpt-5.5
provider: openai
source_hash: 830878acb8c280bdf3bae2f624a6aa1adf20a60c6ee602bf9159395fc1c8acd6
source_hash: 8d1d08edc482837e206f2c0a1b3f4db2658a6a052974aa3c59365455d1f5bddc
source_path: tools/clawhub.md
workflow: 16
---
@ -18,7 +18,7 @@ x-i18n:
ClawHub 是 **OpenClaw Skills 和插件** 的公共注册表。
- 使用原生 `openclaw` 命令搜索、安装和更新 Skills，并从 ClawHub 安装插件。
- 使用单独的 `clawhub` CLI 处理注册表认证、发布、删除/取消删除和同步工作流。
- 使用独立的 `clawhub` CLI 处理注册表认证、发布、删除/恢复删除和同步工作流。
站点：[clawhub.ai](https://clawhub.ai)
@ -36,11 +36,11 @@ ClawHub 是 **OpenClaw Skills 和插件** 的公共注册表。
```
</Step>
<Step title="使用">
启动新的 OpenClaw 会话，它会加载新 Skill。
启动新的 OpenClaw 会话，它会加载新的 skill。
</Step>
<Step title="发布（可选）">
对于需要注册表认证的工作流（发布、同步、管理），请安装
单独的 `clawhub` CLI：
独立的 `clawhub` CLI：
```bash
npm i -g clawhub
@ -62,7 +62,7 @@ ClawHub 是 **OpenClaw Skills 和插件** 的公共注册表。
```
原生 `openclaw` 命令会安装到你的活动工作区，并
持久化源元数据，这样后续 `update` 调用就能继续使用 ClawHub。
持久保存来源元数据，以便后续 `update` 调用可以继续使用 ClawHub。
</Tab>
<Tab title="插件">
@ -73,116 +73,117 @@ ClawHub 是 **OpenClaw Skills 和插件** 的公共注册表。
```
`plugins search` 会查询 ClawHub 插件目录，并打印可直接安装的
包名。裸的 npm 安全插件规范也会先尝试在 ClawHub 中解析，
然后再尝试 npm：
软件包名称。裸 npm 安全插件规范只有在软件包
就绪状态表明该软件包可供 OpenClaw 安装时才使用 ClawHub；否则 OpenClaw
会保留 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` 兼容性，因此不兼容的主机会提前失败关闭，
而不是部分安装该包。当某个包版本发布了 ClawPack 工件时，
插件安装会在归档安装运行之前验证声明的 `pluginApi` 和
`minGatewayVersion` 兼容性，因此
不兼容的主机会提前失败关闭，而不是部分安装
软件包。当某个软件包版本发布 ClawPack 工件时，
OpenClaw 会优先使用精确上传的 npm-pack `.tgz`，验证 ClawHub
摘要标头和下载字节，并记录工件类型、npm
完整性、npm shasum、tarball 名称和 ClawPack 摘要元数据，以供后续
更新使用。没有 ClawPack 元数据的旧包版本仍会使用
旧版包归档验证路径。
摘要标头和下载的字节，并记录工件类型、npm
integrity、npm shasum、tarball 名称和 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 是什么
- OpenClaw Skills 和插件的公共注册表。
- Skill 包及其元数据的版本化存储。
- 用于搜索、标签和使用信号的发现界面。
- skill 包和元数据的版本化存储。
- 面向搜索、标签和使用信号的发现入口。
典型的 Skill 是一个包含以下内容的版本化文件包：
典型的 skill 是一个包含以下内容的版本化文件包：
- 一个包含主要描述和用法的 `SKILL.md` 文件。
- Skill 使用的可选配置、脚本或支持文件。
- skill 使用的可选配置、脚本或支持文件。
- 标签、摘要和安装要求等元数据。
ClawHub 使用元数据来支持发现，并安全公开 Skill
能力。注册表会跟踪使用信号（星标、下载量），以
提升排名和可见性。每次发布都会创建一个新的 semver
ClawHub 使用元数据来驱动发现，并安全地公开 skill
能力。注册表会跟踪使用信号（星标、下载量）以
改进排序和可见性。每次发布都会创建新的 semver
版本，并且注册表会保留版本历史，以便用户审计
变更。
## 工作区和 Skill 加载
## 工作区和 skill 加载
单独的 `clawhub` CLI 也会把 Skills 安装到
当前工作目录下的 `./skills`。如果已配置 OpenClaw 工作区，
独立的 `clawhub` CLI 也会把 Skills 安装到
当前工作目录下的 `./skills`。如果配置了 OpenClaw 工作区，
`clawhub` 会回退到该工作区，除非你覆盖 `--workdir`
（或 `CLAWHUB_WORKDIR`）。OpenClaw 会从
`<workspace>/skills` 加载工作区 Skills，并在**下一个**会话中
加载它们。
（或 `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、changelog 和标签（包括 `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 会被自动隐藏。
<Accordion title="举报">
- 任何已登录用户都可以举报 skill。
- 必须提供举报原因，并会被记录。
- 每个用户同一时间最多可以有 20 个活动举报。
- 默认情况下，收到超过 3 个唯一举报的 Skills 会被自动隐藏。
</Accordion>
<Accordion title="审核">
- 审核员可以查看隐藏的 Skills、取消隐藏、删除它们，或封禁用户。
- 滥用报告功能可能导致账号被封禁。
- 滥用举报功能可能导致账号被封禁。
- 有兴趣成为审核员？请在 OpenClaw Discord 中询问，并联系审核员或维护者。
</Accordion>
@ -190,22 +191,22 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
## ClawHub CLI
只有在需要注册表认证的工作流（例如
发布/同步）中，你才需要它。
只有在发布/同步等需要注册表认证的工作流中
才需要它。
### 全局选项
<ParamField path="--workdir <dir>" type="string">
工作目录。默认：当前目录；回退到 OpenClaw 工作区。
工作目录。默认值：当前目录；回退到 OpenClaw 工作区。
</ParamField>
<ParamField path="--dir <dir>" type="string" default="skills">
Skills 目录，相对于工作目录。
Skills 目录，相对于 workdir。
</ParamField>
<ParamField path="--site <url>" type="string">
站点基础 URL（浏览器登录）。
站点基准 URL（浏览器登录）。
</ParamField>
<ParamField path="--registry <url>" type="string">
注册表 API 基础 URL。
注册表 API 基准 URL。
</ParamField>
<ParamField path="--no-input" type="boolean">
禁用提示（非交互式）。
@ -227,8 +228,8 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
登录选项：
- `--token <token>` — 粘贴 API 令牌。
- `--label <label>` — 为浏览器登录令牌存储的标签（默认：`CLI token`）。
- `--token <token>` — 粘贴 API token。
- `--label <label>` — 为浏览器登录 token 存储的标签（默认：`CLI token`）。
- `--no-browser` — 不打开浏览器（需要 `--token`）。
</Accordion>
@ -237,7 +238,7 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
clawhub search "query"
```
搜索 Skills。对于插件/包发现，请使用 `clawhub package explore`。
搜索 Skills。对于插件/软件包发现，请使用 `clawhub package explore`。
- `--limit <n>` — 最大结果数。
@ -249,15 +250,15 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
clawhub package inspect episodic-claw
```
`package explore` 和 `package inspect` 是 ClawHub CLI 中用于插件/包发现和元数据检查的界面。原生 OpenClaw 安装仍使用 `openclaw plugins install clawhub:<package>`。
`package explore` 和 `package inspect` 是 ClawHub CLI 用于插件/软件包发现和元数据检查的入口。原生 OpenClaw 安装仍使用 `openclaw plugins install clawhub:<package>`。
选项：
- `--family skill|code-plugin|bundle-plugin` — 筛选包系列。
- `--official` — 只显示官方包。
- `--executes-code` — 只显示执行代码的包。
- `--version <version>` / `--tag <tag>` — 检查特定包版本。
- `--versions`, `--files`, `--file <path>` — 检查包历史和文件。
- `--family skill|code-plugin|bundle-plugin` — 筛选软件包系列。
- `--official` — 仅显示官方软件包。
- `--executes-code` — 仅显示执行代码的软件包。
- `--version <version>` / `--tag <tag>` — 检查特定软件包版本。
- `--versions`、`--files`、`--file <path>` — 检查软件包历史和文件。
- `--json` — 机器可读输出。
</Accordion>
@ -271,7 +272,7 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
选项：
- `--version <version>` — 安装或更新到特定版本（在 `update` 上仅限单个 slug）。
- `--version <version>` — 安装或更新到特定版本（在 `update` 上仅支持单个 slug）。
- `--force` — 如果文件夹已存在，或本地文件与任何已发布版本都不匹配，则覆盖。
- `clawhub list` 读取 `.clawhub/lock.json`。
@ -283,10 +284,10 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
选项：
- `--slug <slug>` — Skill slug。
- `--slug <slug>` — skill slug。
- `--name <name>` — 显示名称。
- `--version <version>` — semver 版本。
- `--changelog <text>` — 变更日志文本（可为空）。
- `--changelog <text>` — changelog 文本（可以为空）。
- `--tags <tags>` — 逗号分隔的标签（默认：`latest`）。
</Accordion>
@ -300,9 +301,9 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
选项：
- `--dry-run` — 构建精确的发布计划，不上传任何内容。
- `--dry-run` — 构建精确的发布计划，但不上传任何内容。
- `--json` — 为 CI 输出机器可读内容。
- `--source-repo`, `--source-commit`, `--source-ref` — 自动检测不足时的可选覆盖项。
- `--source-repo`、`--source-commit`、`--source-ref` — 自动检测不足时的可选覆盖项。
</Accordion>
<Accordion title="请求重新扫描">
@ -314,21 +315,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
```
@ -337,11 +338,11 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
- `--root <dir...>` — 额外扫描根目录。
- `--all` — 不提示，上传所有内容。
- `--dry-run` — 显示将上传的内容。
- `--bump <type>` — 用于更新的 `patch|minor|major`（默认：`patch`）。
- `--changelog <text>` — 非交互式更新的变更日志。
- `--dry-run` — 显示将要上传的内容。
- `--bump <type>` — 更新使用的 `patch|minor|major`（默认：`patch`）。
- `--changelog <text>` — 非交互式更新的 changelog。
- `--tags <tags>` — 逗号分隔的标签（默认：`latest`）。
- `--concurrency <n>` — 注册表检查数（默认：`4`）。
- `--concurrency <n>` — 注册表检查并发数（默认：`4`）。
</Accordion>
</AccordionGroup>
@ -371,12 +372,12 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
clawhub update --all
```
</Tab>
<Tab title="发布单个 Skill">
<Tab title="发布单个 skill">
```bash
clawhub skill publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0 --tags latest
```
</Tab>
<Tab title="同步多个 Skills">
<Tab title="同步多个 skills">
```bash
clawhub sync --all
```
@ -393,8 +394,7 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
### 插件包元数据
代码插件必须在
`package.json` 中包含必需的 OpenClaw 元数据：
代码插件必须在 `package.json` 中包含必需的 OpenClaw 元数据：
```json
{
@ -416,32 +416,30 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
}
```
已发布的软件包应随附**构建后的 JavaScript**，并将
`runtimeExtensions` 指向该输出。通过 Git checkout 安装时，如果不存在已构建文件，仍可回退到 TypeScript 源码，但构建后的运行时入口可避免在启动、Doctor 和插件加载路径中进行运行时 TypeScript 编译。
已发布的包应随附**构建后的 JavaScript**，并将 `runtimeExtensions` 指向该输出。通过 Git checkout 安装时，如果不存在构建文件，仍可回退到 TypeScript 源码，但构建后的运行时入口可以避免在启动、doctor 和插件加载路径中进行运行时 TypeScript 编译。
## 版本控制、锁文件和遥测
## 版本控制、lockfile 和遥测
<AccordionGroup>
<Accordion title="版本控制和标签">
- 每次发布都会创建一个新的 **semver** `SkillVersion`。
- 标签（如 `latest`）指向某个版本；移动标签可让你回滚。
- 变更日志按版本附加，在同步或发布更新时可以为空。
- 标签（如 `latest`）指向某个版本；移动标签可以让你回滚。
- Changelogs 按版本附加，在同步或发布更新时可以为空。
</Accordion>
<Accordion title="本地更改与注册表版本">
更新会使用内容哈希，将本地 Skill 内容与注册表版本进行比较。如果本地文件与任何已发布版本都不匹配，CLI 会在覆盖前询问（或在非交互式运行中要求使用 `--force`）。
<Accordion title="本地更改与 registry 版本">
更新会使用内容哈希将本地 skill 内容与 registry 版本进行比较。如果本地文件与任何已发布版本都不匹配，CLI 会在覆盖前询问（或在非交互式运行中要求使用 `--force`）。
</Accordion>
<Accordion title="同步扫描和回退根目录">
`clawhub sync` 会先扫描你当前的工作目录。如果未找到 Skills，它会回退到已知的旧位置（例如
`~/openclaw/skills` 和 `~/.openclaw/skills`）。这样设计是为了无需额外标志即可找到较早的 Skill 安装。
`clawhub sync` 会先扫描你当前的工作目录。如果找不到 skills，它会回退到已知的旧位置（例如 `~/openclaw/skills` 和 `~/.openclaw/skills`）。这是为了在不添加额外标志的情况下找到较早安装的 skills。
</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 会发送最小快照以计算安装计数。你可以完全禁用此功能：
当你在登录状态下运行 `clawhub sync` 时，CLI 会发送一个最小快照来计算安装计数。你可以完全禁用此功能：
```bash
export CLAWHUB_DISABLE_TELEMETRY=1
@ -455,12 +453,12 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
| 变量 | 作用 |
| ----------------------------- | ----------------------------------------------- |
| `CLAWHUB_SITE` | 覆盖站点 URL。 |
| `CLAWHUB_REGISTRY` | 覆盖注册表 API URL。 |
| `CLAWHUB_REGISTRY` | 覆盖 registry API URL。 |
| `CLAWHUB_CONFIG_PATH` | 覆盖 CLI 存储令牌/配置的位置。 |
| `CLAWHUB_WORKDIR` | 覆盖默认工作目录。 |
| `CLAWHUB_DISABLE_TELEMETRY=1` | 在 `sync` 时禁用遥测。 |
## 相关内容
## 相关
- [社区插件](/zh-CN/plugins/community)
- [插件](/zh-CN/tools/plugin)

284
docs/zh-CN/tools/plugin.md
View File

@ -1,21 +1,21 @@
---
read_when:
- 安装或配置插件
- 了解插件发现和加载规则
- 理解插件发现和加载规则
- 使用与 Codex/Claude 兼容的插件包
sidebarTitle: Install and Configure
summary: 安装、配置和管理 OpenClaw 插件
title: 插件
x-i18n:
generated_at: "2026-05-02T13:23:27Z"
generated_at: "2026-05-02T18:33:38Z"
model: gpt-5.5
provider: openai
source_hash: 6aa1819e086c66fd9cb035d17f0dea0ddc7fcd0c0d5490fac09c843fb1d74a39
source_hash: 595552574751bde36eee4b3617afa1c1f10471d6191ae35b5f4b11518cb4b5d4
source_path: tools/plugin.md
workflow: 16
---
插件为 OpenClaw 扩展新能力：渠道、模型提供商、智能体 harness、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、Web 获取、Web 搜索等。有些插件是 **核心** 插件（随 OpenClaw 一起发布），其他是 **外部** 插件。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。npm 仍支持直接安装，也支持一组临时的 OpenClaw 自有插件包，直到该迁移完成。
插件为 OpenClaw 扩展新能力：渠道、模型提供商、智能体 harness、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、Web 抓取、Web 搜索等。有些插件是 **core**（随 OpenClaw 提供），其他是 **external**。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。npm 仍然支持直接安装，也会在迁移完成前临时支持一组 OpenClaw 拥有的插件包。
## 快速开始
@ -57,10 +57,10 @@ x-i18n:
</Step>
<Step title="聊天原生管理">
在正在运行的 Gateway 网关中，仅限所有者使用的 `/plugins enable` 和 `/plugins disable`
会触发 Gateway 网关配置重载器。Gateway 网关会在进程内重载插件运行时
表面，新的智能体轮次会从刷新后的注册表重新构建它们的工具列表。`/plugins install` 会更改插件源代码，因此
Gateway 网关会请求重启，而不是假装当前进程可以安全地重载已经导入的模块。
在运行中的 Gateway 网关里，仅限所有者使用的 `/plugins enable` 和 `/plugins disable`
会触发 Gateway 网关配置重载器。Gateway 网关会在进程内重新加载插件运行时表面，
新的智能体轮次会从刷新后的注册表重建其工具列表。`/plugins install` 会更改插件源代码，
所以 Gateway 网关会请求重启，而不是假装当前进程可以安全地重新加载已经导入的模块。
</Step>
@ -72,13 +72,13 @@ x-i18n:
openclaw <plugin-command> --help
```
当你需要证明已注册的工具、服务、gateway 方法、钩子或插件自有 CLI 命令时，使用 `--runtime`。普通的 `inspect` 是一次冷态
清单/注册表检查，并且有意避免导入插件运行时。
当你需要证明已注册的工具、服务、Gateway 网关方法、钩子或插件拥有的 CLI 命令时，使用 `--runtime`。
普通的 `inspect` 是冷态清单/注册表检查，并且会有意避免导入插件运行时。
</Step>
</Steps>
如果你更喜欢聊天原生控制，请启用 `commands.plugins: true` 并使用：
如果你偏好聊天原生控制，请启用 `commands.plugins: true` 并使用：
```text
/plugin install clawhub:<package>
@ -88,38 +88,33 @@ x-i18n:
安装路径使用与 CLI 相同的解析器：本地路径/归档、显式
`clawhub:<pkg>`、显式 `npm:<pkg>`、显式 `git:<repo>`，或裸包
规范（先 ClawHub，随后回退到 npm）。
spec（先尝试 ClawHub，再回退到 npm）。
如果配置无效，安装通常会失败关闭，并引导你运行
`openclaw doctor --fix`。唯一的恢复例外是一条狭窄的内置插件
重装路径，适用于选择加入
如果配置无效，安装通常会失败关闭，并指向 `openclaw doctor --fix`。
唯一的恢复例外是一条狭窄的内置插件重装路径，适用于选择加入
`openclaw.install.allowInvalidConfigRecovery` 的插件。
在 Gateway 网关启动期间，某个插件的无效配置会被隔离到该插件：
启动日志会记录 `plugins.entries.<id>.config` 问题，在加载期间跳过该插件，
并保持其他插件和渠道在线。运行 `openclaw doctor --fix`
可通过禁用该插件条目并移除其无效配置载荷来隔离有问题的插件配置；正常的配置备份会保留先前的值。
当某个渠道配置引用了不再可发现的插件，但同一个过期插件 ID 仍存在于插件配置或安装记录中时，Gateway 网关启动
会记录警告并跳过该渠道，而不是阻塞所有其他渠道。
运行 `openclaw doctor --fix` 可移除过期的渠道/插件条目；没有过期插件证据的未知
渠道键仍会验证失败，以便拼写错误保持可见。
并让其他插件和渠道保持在线。运行 `openclaw doctor --fix`
可以通过禁用该插件条目并移除其无效配置载荷来隔离损坏的插件配置；常规配置备份会保留之前的值。
当渠道配置引用了不再可发现的插件，但同一个过期插件 id 仍存在于插件配置或安装记录中时，
Gateway 网关启动会记录警告并跳过该渠道，而不是阻塞所有其他渠道。
运行 `openclaw doctor --fix` 可移除过期的渠道/插件条目；没有过期插件证据的未知渠道键仍会导致验证失败，
以便拼写错误保持可见。
如果设置了 `plugins.enabled: false`，过期插件引用会被视为惰性：
Gateway 网关启动会跳过插件发现/加载工作，`openclaw doctor` 会保留
已禁用的插件配置，而不是自动移除它。如果你想移除过期插件 ID，请在运行
doctor 清理前重新启用插件。
Gateway 网关启动会跳过插件发现/加载工作，`openclaw doctor` 会保留已禁用的插件配置，
而不是自动移除它。如果你想移除过期插件 id，请先重新启用插件，再运行 Doctor 清理。
插件依赖安装只会在显式安装/更新或
doctor 修复流程中发生。Gateway 网关启动、配置重载和运行时检查
不会运行包管理器或修复依赖树。本地插件必须已经
安装了依赖，而 npm、git 和 ClawHub 插件会安装到 OpenClaw 的托管插件根目录下。npm 依赖可能会在 OpenClaw 的托管 npm 根目录内提升；安装/更新会先扫描该托管根目录，然后再信任；卸载会通过 npm 移除 npm 托管的包。外部插件
和自定义加载路径仍必须通过 `openclaw plugins install` 安装。
查看 [插件依赖解析](/zh-CN/plugins/dependency-resolution) 了解
安装时生命周期。
插件依赖安装只会发生在显式安装/更新或 Doctor 修复流程中。Gateway 网关启动、配置重载和运行时检查
不会运行包管理器或修复依赖树。本地插件必须已经安装其依赖，而 npm、git 和 ClawHub 插件会安装在
OpenClaw 的托管插件根目录下。npm 依赖可能会在 OpenClaw 的托管 npm 根目录内被提升；
安装/更新会先扫描该托管根目录再建立信任，卸载会通过 npm 移除 npm 托管的包。外部插件和自定义加载路径
仍必须通过 `openclaw plugins install` 安装。参见[插件依赖解析](/zh-CN/plugins/dependency-resolution)
了解安装时生命周期。
源码检出是 pnpm 工作区。如果你克隆 OpenClaw 来修改内置
插件，请运行 `pnpm install`；随后 OpenClaw 会从
`extensions/<id>` 加载内置插件，因此编辑内容和包本地依赖会被直接使用。
普通 npm 根安装用于打包版 OpenClaw，不用于源码检出
开发。
源代码检出是 pnpm 工作区。如果你克隆 OpenClaw 来修改内置插件，请运行 `pnpm install`；
随后 OpenClaw 会从 `extensions/<id>` 加载内置插件，这样编辑内容和包本地依赖会被直接使用。
普通 npm 根目录安装适用于打包后的 OpenClaw，而不是源代码检出开发。
## 插件类型
@ -127,27 +122,24 @@ OpenClaw 识别两种插件格式：
| 格式 | 工作方式 | 示例 |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
| **Bundle** | Codex/Claude/Cursor 兼容布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
| **Native** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
| **Bundle** | Codex/Claude/Cursor 兼容布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
两者都会显示在 `openclaw plugins list` 下。查看 [插件 Bundle](/zh-CN/plugins/bundles) 了解 bundle 详情。
两者都会显示在 `openclaw plugins list` 下。参见[插件包](/zh-CN/plugins/bundles)了解包详情。
如果你在编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins)
和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。
如果你正在编写原生插件，请从[构建插件](/zh-CN/plugins/building-plugins)
和[插件 SDK 概览](/zh-CN/plugins/sdk-overview)开始。
## 包入口点
原生插件 npm 包必须在 `package.json` 中声明 `openclaw.extensions`。
每个条目都必须留在包目录内，并解析到可读的
运行时文件，或者解析到一个 TypeScript 源文件，其内置 JavaScript
对等文件可被推断，例如从 `src/index.ts` 到 `dist/index.js`。
每个条目都必须保留在包目录内，并解析到可读的运行时文件，或解析到带有推断构建后 JavaScript
对等文件的 TypeScript 源文件，例如从 `src/index.ts` 到 `dist/index.js`。
当发布的运行时文件不在与源条目相同的路径时，使用 `openclaw.runtimeExtensions`。
存在时，`runtimeExtensions` 必须为每个 `extensions` 条目包含
正好一个条目。列表不匹配会导致安装和
插件发现失败，而不是静默回退到源路径。如果你还
发布 `openclaw.setupEntry`，请为其内置
JavaScript 对等文件使用 `openclaw.runtimeSetupEntry`；声明后该文件是必需的。
当发布的运行时文件与源条目不在相同路径时，使用 `openclaw.runtimeExtensions`。
存在时，`runtimeExtensions` 必须为每个 `extensions` 条目正好包含一个条目。不匹配的列表会导致安装和插件发现失败，
而不是静默回退到源路径。如果你还发布 `openclaw.setupEntry`，请为其构建后的 JavaScript
对等文件使用 `openclaw.runtimeSetupEntry`；声明后该文件就是必需的。
```json
{
@ -161,17 +153,14 @@ JavaScript 对等文件使用 `openclaw.runtimeSetupEntry`；声明后该文件
## 官方插件
### 迁移期间的 OpenClaw 自有 npm 包
### 迁移期间 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 包。
| 插件 | 包 | 文档 |
| --------------- | -------------------------- | ------------------------------------------ |
@ -189,7 +178,7 @@ npm 上发布一些 `@openclaw/*` 插件包，用于较旧/自定义安装和直
| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) |
### 核心（随 OpenClaw 一起发布）
### Core（随 OpenClaw 提供）
<AccordionGroup>
<Accordion title="模型提供商（默认启用）">
@ -202,10 +191,10 @@ npm 上发布一些 `@openclaw/*` 插件包，用于较旧/自定义安装和直
<Accordion title="记忆插件">
- `memory-core` — 内置记忆搜索（默认通过 `plugins.slots.memory`）
- `memory-lancedb` — 由 LanceDB 支持、具备自动召回/捕获能力的长期记忆（设置 `plugins.slots.memory = "memory-lancedb"`）
- `memory-lancedb` — 由 LanceDB 支持、带自动召回/捕获的长期记忆（设置 `plugins.slots.memory = "memory-lancedb"`）
查看 [Memory LanceDB](/zh-CN/plugins/memory-lancedb) 了解 OpenAI 兼容的
嵌入设置、Ollama 示例、召回限制和故障排除。
参见 [Memory LanceDB](/zh-CN/plugins/memory-lancedb) 了解 OpenAI 兼容的
embedding 设置、Ollama 示例、召回限制和故障排除。
</Accordion>
@ -214,13 +203,13 @@ npm 上发布一些 `@openclaw/*` 插件包，用于较旧/自定义安装和直
</Accordion>
<Accordion title="其他">
- `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` gateway 方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；在替换它之前请先禁用）
- `copilot-proxy` — VS Code Copilot Proxy 桥接（默认禁用）
- `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用它）
- `copilot-proxy` — VS Code Copilot Proxy 桥接器（默认禁用）
</Accordion>
</AccordionGroup>
在寻找第三方插件？查看 [社区插件](/zh-CN/plugins/community)。
在寻找第三方插件？参见[社区插件](/zh-CN/plugins/community)。
## 配置
@ -244,79 +233,78 @@ npm 上发布一些 `@openclaw/*` 插件包，用于较旧/自定义安装和直
| `allow` | 插件允许列表（可选） |
| `deny` | 插件拒绝列表（可选；拒绝优先） |
| `load.paths` | 额外插件文件/目录 |
| `slots` | 独占插槽选择器（例如 `memory`、`contextEngine`） |
| `slots` | 独占 slot 选择器（例如 `memory`、`contextEngine`） |
| `entries.\<id\>` | 单插件开关 + 配置 |
`plugins.allow` 是独占的。当它非空时，只有列出的插件可以加载
或暴露工具，即使 `tools.allow` 包含 `"*"` 或某个插件自有的
工具名称也是如此。如果工具允许列表引用了插件工具，请将所属插件 ID
添加到 `plugins.allow`，或移除 `plugins.allow`；`openclaw doctor` 会对此
形态发出警告。
`plugins.allow` 是排他的。当它非空时，只有列出的插件可以加载或暴露工具，
即使 `tools.allow` 包含 `"*"` 或某个插件拥有的具体工具名称也是如此。如果工具允许列表引用插件工具，
请将所属插件 id 添加到 `plugins.allow`，或移除 `plugins.allow`；`openclaw doctor` 会对此形态发出警告。
通过 `/plugins enable` 或 `/plugins disable` 进行的配置更改会触发进程内 Gateway 网关插件重新加载。新的智能体轮次会从刷新的插件注册表重建其工具列表。安装、更新和卸载等会更改源码的操作仍会重启 Gateway 网关进程，因为已经导入的插件模块无法安全地就地替换。
通过 `/plugins enable` 或 `/plugins disable` 做出的配置更改会触发一次进程内 Gateway 网关插件重新加载。新的智能体轮次会从刷新后的插件注册表重建其工具列表。安装、更新和卸载等会改变来源的操作仍会重启 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`。
<Accordion title="Plugin states: disabled vs missing vs invalid">
<Accordion title="插件状态：已禁用与缺失与无效">
- **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。
- **缺失**：配置引用了设备发现未找到的插件 ID。
- **无效**：插件存在，但其配置与声明的架构不匹配。Gateway 网关启动时只会跳过该插件；`openclaw doctor --fix` 可以通过禁用无效条目并移除其配置负载来隔离该条目。
- **缺失**：配置引用了一个设备发现未找到的插件 ID。
- **无效**：插件存在，但其配置与声明的架构不匹配。Gateway 网关启动时只会跳过该插件；`openclaw doctor --fix` 可以通过禁用它并移除其配置载荷，将无效条目隔离。
</Accordion>
## 设备发现和优先级
OpenClaw 按以下顺序扫描插件（先匹配者优先）：
OpenClaw 会按以下顺序扫描插件（第一个匹配项生效）：
<Steps>
<Step title="Config paths">
`plugins.load.paths` — 显式文件或目录路径。指回 OpenClaw 自己打包的内置插件目录的路径会被忽略；
<Step title="配置路径">
`plugins.load.paths` —— 显式文件或目录路径。指回 OpenClaw 自身打包的内置插件目录的路径会被忽略；
运行 `openclaw doctor --fix` 可移除这些过时别名。
</Step>
<Step title="Workspace plugins">
<Step title="工作区插件">
`\<workspace\>/.openclaw/<plugin-root>/*.ts` 和 `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`。
</Step>
<Step title="Global plugins">
<Step title="全局插件">
`~/.openclaw/<plugin-root>/*.ts` 和 `~/.openclaw/<plugin-root>/*/index.ts`。
</Step>
<Step title="Bundled plugins">
随 OpenClaw 一起发布。许多默认启用（模型提供商、语音）。其他插件需要显式启用。
<Step title="内置插件">
随 OpenClaw 一起发布。许多插件默认启用（模型提供商、语音）。
其他插件需要显式启用。
</Step>
</Steps>
打包安装和 Docker 镜像通常会从已编译的 `dist/extensions` 树解析内置插件。如果某个内置插件源码目录被绑定挂载到匹配的打包源码路径上，例如 `/app/extensions/synology-chat`，OpenClaw 会将该挂载的源码目录视为内置源码覆盖层，并在打包的 `/app/dist/extensions/synology-chat` bundle 之前发现它。这样可以让维护者容器循环正常工作，而无需将每个内置插件都切回 TypeScript 源码。设置 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可强制使用打包的 dist bundle，即使存在源码覆盖挂载也是如此。
打包安装和 Docker 镜像通常会从编译后的 `dist/extensions` 树解析内置插件。如果某个内置插件源码目录被 bind mount 到匹配的打包源码路径上，例如 `/app/extensions/synology-chat`，OpenClaw 会将该挂载的源码目录视为内置源码覆盖层，并在打包的 `/app/dist/extensions/synology-chat` bundle 之前发现它。这样可以保持维护者容器循环正常工作，而不需要把每个内置插件都切回 TypeScript 源码。设置 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可强制使用打包的 dist bundle，即使存在源码覆盖挂载也是如此。
### 启用规则
- `plugins.enabled: false` 会禁用所有插件并跳过插件发现/加载工作
- `plugins.enabled: false` 会禁用所有插件，并跳过插件设备发现/加载工作
- `plugins.deny` 始终优先于 allow
- `plugins.entries.\<id\>.enabled: false` 会禁用该插件
- 工作区来源的插件**默认禁用**（必须显式启用）
- 内置插件遵循内建的默认开启集合，除非被覆盖
- 独占槽位可以强制启用该槽位选中的插件
- 当配置命名某个插件拥有的表面（例如提供商模型引用、渠道配置或 harness 运行时）时，一些内置的可选启用插件会自动启用
- 当 `plugins.enabled: false` 处于活动状态时，过时插件配置会被保留；如果你希望移除过时 ID，请在运行 Doctor 清理之前重新启用插件
- OpenAI 系列 Codex 路由保持独立的插件边界：
`openai-codex/*` 属于 OpenAI 插件，而内置 Codex
- 内置插件遵循内建的默认启用集合，除非被覆盖
- 独占槽位可以强制启用该槽位所选的插件
- 当配置命名了插件拥有的表面时，某些内置的选择启用插件会自动启用，例如提供商模型引用、渠道配置或 harness 运行时
- 当 `plugins.enabled: false` 处于活动状态时，过时插件配置会被保留；如果你希望移除过时 ID，请先重新启用插件再运行 Doctor 清理
- OpenAI 系 Codex 路由保持单独的插件边界：
`openai-codex/*` 属于 OpenAI 插件，而内置的 Codex
app-server 插件由 `agentRuntime.id: "codex"` 或旧版
`codex/*` 模型引用选择
## 运行时钩子的故障排除
## 排查运行时钩子
如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或钩子没有在实时聊天流量中运行，请先检查以下内容：
如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或钩子没有在实时聊天流量中运行，请先检查这些项：
- 运行 `openclaw gateway status --deep --require-rpc`，并确认活动的 Gateway 网关 URL、profile、配置路径和进程正是你正在编辑的对象。
- 在插件安装/配置/代码更改后重启实时 Gateway 网关。在包装容器中，PID 1 可能只是 supervisor；请重启子 `openclaw gateway run` 进程或向其发送信号。
- 使用 `openclaw plugins inspect <id> --runtime --json` 确认钩子注册和诊断信息。非内置会话钩子（如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`）需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析之前运行；`llm_output` 只会在一次模型尝试产生助手输出之后运行。
- 若要证明有效会话模型，请使用 `openclaw sessions` 或 Gateway 网关会话/Status 表面；调试提供商负载时，请用 `--raw-stream --raw-stream-path <path>` 启动 Gateway 网关。
- 运行 `openclaw gateway status --deep --require-rpc`，并确认活动的 Gateway 网关 URL、profile、配置路径和进程就是你正在编辑的那些。
- 在插件安装/配置/代码更改后重启实时 Gateway 网关。在包装容器中，PID 1 可能只是一个 supervisor；请重启子 `openclaw gateway run` 进程或向其发送信号。
- 使用 `openclaw plugins inspect <id> --runtime --json` 确认钩子注册和诊断。非内置对话钩子（如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`）需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析前运行；`llm_output` 只会在一次模型尝试产生助手输出后运行。
- 要证明有效会话模型，请使用 `openclaw sessions` 或 Gateway 网关会话/Status 表面；调试提供商载荷时，请使用 `--raw-stream --raw-stream-path <path>` 启动 Gateway 网关。
### 插件工具设置缓慢
如果智能体轮次似乎在准备工具时停滞，请启用 trace 日志并检查插件工具 factory 的计时行：
如果智能体轮次看起来在准备工具时停滞，请启用 trace 日志并检查插件工具工厂计时行：
```bash
openclaw config set logging.level trace
@ -329,19 +317,19 @@ openclaw logs --follow
[trace:plugin-tools] factory timings ...
```
摘要会列出总 factory 时间和最慢的插件工具 factory，包括插件 ID、声明的工具名称、结果形状以及该工具是否为可选。当单个 factory 至少耗时 1 秒或插件工具 factory 准备总耗时至少 5 秒时，慢速行会提升为警告。
摘要会列出总工厂耗时和最慢的插件工具工厂，包括插件 ID、声明的工具名称、结果形态，以及该工具是否为可选。当单个工厂耗时至少 1 秒，或插件工具工厂准备总耗时至少 5 秒时，慢速行会提升为警告。
OpenClaw 会缓存成功的插件工具 factory 结果，以便在相同有效请求上下文的重复解析中复用。缓存键包含有效运行时配置、工作区、智能体/会话 ID、沙箱策略、浏览器设置、交付上下文、请求者身份和所有权状态，因此依赖这些可信字段的 factory 会在上下文变化时重新运行。
OpenClaw 会为具有相同有效请求上下文的重复解析缓存成功的插件工具工厂结果。缓存键包含有效运行时配置、工作区、智能体/会话 ID、沙箱策略、浏览器设置、交付上下文、请求者身份和所有权状态，因此依赖这些可信字段的工厂会在上下文变化时重新运行。
如果某个插件占用了主要耗时，请检查其运行时注册：
如果某一个插件占据了主要耗时，请检查其运行时注册：
```bash
openclaw plugins inspect <plugin-id> --runtime --json
```
然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载移到工具执行路径之后，而不是在工具 factory 中完成。
然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载移动到工具执行路径之后，而不是在工具工厂内部完成。
### 重复的渠道或工具所有权
### 渠道或工具所有权重复
症状：
@ -349,24 +337,24 @@ openclaw plugins inspect <plugin-id> --runtime --json
- `channel setup already registered: <channel-id> (<plugin-id>)`
- `plugin tool name conflict (<plugin-id>): <tool-name>`
这些表示多个已启用插件试图拥有同一个渠道、设置流程或工具名称。最常见的原因是外部渠道插件与现在提供相同渠道 ID 的内置插件同时安装。
这些表示不止一个已启用插件正尝试拥有同一个渠道、设置流程或工具名称。最常见原因是一个外部渠道插件安装在某个现在也提供相同渠道 ID 的内置插件旁边。
调试步骤：
- 运行 `openclaw plugins list --enabled --verbose` 查看每个已启用插件及其来源。
- 对每个可疑插件运行 `openclaw plugins inspect <id> --runtime --json`，并比较 `channels`、`channelConfigs`、`tools` 和诊断信息。
- 在安装或移除插件包后运行 `openclaw plugins registry --refresh`，以便持久化元数据反映当前安装。
- 对每个疑似插件运行 `openclaw plugins inspect <id> --runtime --json`，并比较 `channels`、`channelConfigs`、`tools` 和诊断。
- 在安装或移除插件包后运行 `openclaw plugins registry --refresh`，让持久化元数据反映当前安装。
- 在安装、注册表或配置更改后重启 Gateway 网关。
修复选项：
- 如果一个插件有意替换同一渠道 ID 的另一个插件，首选插件应声明 `channelConfigs.<channel-id>.preferOver`，并填入较低优先级的插件 ID。请参阅 [/plugins/manifest#replacing-another-channel-plugin](/zh-CN/plugins/manifest#replacing-another-channel-plugin)。
- 如果重复是意外造成的，请用 `plugins.entries.<plugin-id>.enabled: false` 禁用其中一方，或移除过时的插件安装。
- 如果你显式启用了两个插件，OpenClaw 会保留该请求并报告冲突。请为该渠道选择一个所有者，或重命名插件拥有的工具，使运行时表面明确无歧义。
- 如果某个插件有意为同一渠道 ID 替换另一个插件，首选插件应声明 `channelConfigs.<channel-id>.preferOver`，并填入较低优先级的插件 ID。参见 [/plugins/manifest#replacing-another-channel-plugin](/zh-CN/plugins/manifest#replacing-another-channel-plugin)。
- 如果重复是意外造成的，请用 `plugins.entries.<plugin-id>.enabled: false` 禁用一侧，或移除过时的插件安装。
- 如果你显式启用了两个插件，OpenClaw 会保留该请求并报告冲突。为该渠道选择一个所有者，或重命名插件拥有的工具，使运行时表面没有歧义。
## 插件槽位（独占类别）
某些类别是独占的（同一时间只能有一个活动项）：
某些类别是独占的（同一时间只能有一个处于活动状态）：
```json5
{
@ -379,10 +367,10 @@ openclaw plugins inspect <plugin-id> --runtime --json
}
```
| 槽位 | 控制内容 | 默认值 |
| 槽位 | 控制内容 | 默认值 |
| --------------- | --------------------- | ------------------- |
| `memory` | 主动记忆插件 | `memory-core` |
| `contextEngine` | 活动上下文引擎 | `legacy`（内置） |
| `memory` | 主动记忆插件 | `memory-core` |
| `contextEngine` | 活动上下文引擎 | `legacy`（内建） |
## CLI 参考
@ -402,7 +390,7 @@ openclaw plugins registry # inspect persisted registry state
openclaw plugins registry --refresh # rebuild persisted registry
openclaw doctor --fix # repair plugin registry state
openclaw plugins install <package> # install (ClawHub first, then npm)
openclaw plugins install <package> # install (readiness-gated ClawHub, then npm)
openclaw plugins install clawhub:<pkg> # install from ClawHub only
openclaw plugins install npm:<pkg> # install from npm only
openclaw plugins install git:<repo> # install from git
@ -432,34 +420,34 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
内置插件随 OpenClaw 一起发布。许多默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）。其他内置插件仍需要 `openclaw plugins enable <id>`。
内置插件随 OpenClaw 一起发布。许多插件默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）。其他内置插件仍然需要 `openclaw plugins enable <id>`。
`--force` 会就地覆盖现有已安装插件或钩子包。对于已跟踪 npm 插件的常规升级，请使用 `openclaw plugins update <id-or-npm-spec>`。它不支持与 `--link` 一起使用，因为 `--link` 会复用源码路径，而不是复制到托管安装目标上。
`--force` 会就地覆盖现有已安装插件或钩子包。对已跟踪 npm 插件的常规升级，请使用 `openclaw plugins update <id-or-npm-spec>`。它不支持与 `--link` 一起使用，因为 `--link` 会复用源码路径，而不是复制到托管安装目标上。
当已经设置 `plugins.allow` 时，`openclaw plugins install` 会先将已安装插件 ID 添加到该允许列表，然后再启用它。如果同一个插件 ID 存在于 `plugins.deny` 中，安装会移除该过时的 deny 条目，使显式安装在重启后立即可加载。
当 `plugins.allow` 已设置时，`openclaw plugins install` 会在启用已安装插件前，将该插件 ID 添加到允许列表。如果同一插件 ID 存在于 `plugins.deny` 中，install 会移除该过时 deny 条目，以便显式安装在重启后立即可加载。
OpenClaw 会将本地插件注册表持久化，作为插件清单、贡献归属和启动规划的冷读取模型。安装、更新、卸载、启用和停用流程会在更改插件状态后刷新该注册表。同一个 `plugins/installs.json` 文件会在顶层 `installRecords` 中保存持久安装元数据，并在 `plugins` 中保存可重建的清单元数据。如果注册表缺失、过期或无效，`openclaw plugins registry --refresh` 会从安装记录、配置策略以及清单/包元数据重建其清单视图，而不加载插件运行时模块。
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入带 dist-tag 或精确版本的 npm 包规格时，会将包名解析回已跟踪的插件记录，并记录新的规格供未来更新使用。传入不带版本的包名会将精确固定的安装移回注册表的默认发布线。如果已安装的 npm 插件已经匹配解析到的版本和记录的制品身份，OpenClaw 会跳过更新，不下载、不重新安装，也不重写配置。
OpenClaw 会保留一个持久化的本地插件注册表，作为插件清单、贡献归属和启动规划的冷读模型。安装、更新、卸载、启用和禁用流程会在更改插件状态后刷新该注册表。同一个 `plugins/installs.json` 文件会在顶层 `installRecords` 中保存持久安装元数据，并在 `plugins` 中保存可重建的清单元数据。如果注册表缺失、过期或无效，`openclaw plugins registry --refresh` 会从安装记录、配置策略以及清单/包元数据重建其清单视图，而不会加载插件运行时模块。
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入带有 dist-tag 或精确版本的 npm 包规格时，会将包名解析回已跟踪的插件记录，并记录新规格以供后续更新使用。传入不带版本的包名会将精确固定的安装移回注册表的默认发布线。如果已安装的 npm 插件已经匹配解析出的版本和已记录的工件身份，OpenClaw 会跳过更新，不会下载、重新安装或重写配置。
`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 源元数据，而不是 npm 规格。
`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm 规格。
`--dangerously-force-unsafe-install` 是用于内置危险代码扫描器误报的应急覆盖开关。它允许插件安装和插件更新在内置 `critical` 发现项后继续执行，但仍不会绕过插件 `before_install` 策略阻止或扫描失败阻止。安装扫描会忽略常见测试文件和目录，例如 `tests/`、`__tests__/`、`*.test.*` 和 `*.spec.*`，以避免阻止打包的测试 mock；声明的插件运行时入口点即使使用这些名称之一，仍会被扫描。
`--dangerously-force-unsafe-install` 是用于处理内置危险代码扫描器误报的紧急覆盖开关。它允许插件安装和插件更新在内置 `critical` 发现项之后继续进行，但仍然不会绕过插件 `before_install` 策略阻断或扫描失败阻断。安装扫描会忽略常见测试文件和目录，例如 `tests/`、`__tests__/`、`*.test.*` 和 `*.spec.*`，以避免阻断已打包的测试 mock；声明的插件运行时入口点即使使用了这些名称之一，仍会被扫描。
此 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 Skills 依赖安装改用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍是独立的 ClawHub skill 下载/安装流程。
这个 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 Skills 依赖安装改用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是独立的 ClawHub skill 下载/安装流程。
如果你发布到 ClawHub 的插件被扫描隐藏或阻止，请打开 ClawHub 仪表板，或运行 `clawhub package rescan <name>` 请求 ClawHub 再次检查。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描插件，也不会让被阻止的发布公开。
如果你发布到 ClawHub 的插件因扫描而被隐藏或阻断，请打开 ClawHub 控制台，或运行 `clawhub package rescan <name>` 请求 ClawHub 再次检查它。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描插件，也不会让被阻断的版本公开。
兼容 bundle 会参与同一套插件列表/检查/启用/停用流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
兼容 bundle 会参与同一个插件列表/检查/启用/禁用流程。当前运行时支持包括 bundle skills、Claude 命令 skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor 命令 skills，以及兼容的 Codex 钩子目录。
`openclaw plugins inspect <id>` 还会报告检测到的 bundle 能力，以及由 bundle 支持的插件中受支持或不受支持的 MCP 和 LSP 服务器条目。
Marketplace 源可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保留在克隆的 marketplace 仓库内，并且只能使用相对路径源。
Marketplace 来源可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须留在克隆的 marketplace 仓库内，并且只能使用相对路径来源。
了解详情，请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。
请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins) 了解详情。
## 插件 API 概览
原生插件会导出一个暴露 `register(api)` 的入口对象。旧版插件仍可使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。
原生插件会导出一个入口对象，该对象公开 `register(api)`。旧插件仍可使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。
```typescript
export default definePluginEntry({
@ -479,27 +467,27 @@ export default definePluginEntry({
});
```
OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`。加载器仍会回退到旧版插件的 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。
OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。
`api.registrationMode` 会告知插件其入口为何被加载：
`api.registrationMode` 会告诉插件为什么正在加载其入口：
| 模式 | 含义 |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `full` | 运行时激活。注册工具、钩子、服务、命令、路由和其他实时副作用。 |
| `discovery` | 只读能力发现。注册提供商和元数据；可信插件入口代码可能会加载，但应跳过实时副作用。 |
| `discovery` | 只读能力发现。注册提供商和元数据；可信插件入口代码可以加载，但应跳过实时副作用。 |
| `setup-only` | 通过轻量级设置入口加载渠道设置元数据。 |
| `setup-runtime` | 同时需要运行时入口的渠道设置加载。 |
| `setup-runtime` | 渠道设置加载，同时也需要运行时入口。 |
| `cli-metadata` | 仅收集 CLI 命令元数据。 |
会打开 socket、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 防护这些副作用。发现加载会与激活加载分开缓存，且不会替换正在运行的 Gateway 网关注册表。发现是非激活的，但并非免导入：OpenClaw 可能会执行可信插件入口或渠道插件模块来构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径之后。
会打开套接字、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 保护这些副作用。发现加载会与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。发现是非激活的，但并非无导入：OpenClaw 可能会求值受信任的插件入口或渠道插件模块，以构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径之后。
常用注册方法：
常见注册方法：
| 方法 | 注册内容 |
| --------------------------------------- | --------------------------- |
| `registerProvider` | 模型提供商（LLM） |
| `registerChannel` | 聊天渠道 |
| `registerTool` | 智能体工具 |
| `registerTool` | Agent 工具 |
| `registerHook` / `on(...)` | 生命周期钩子 |
| `registerSpeechProvider` | 文本转语音 / STT |
| `registerRealtimeTranscriptionProvider` | 流式 STT |
@ -515,24 +503,24 @@ OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`
| `registerContextEngine` | 上下文引擎 |
| `registerService` | 后台服务 |
类型化生命周期钩子的防护行为：
类型化生命周期钩子的守卫行为：
- `before_tool_call`：`{ block: true }` 是终止性的；较低优先级处理器会被跳过。
- `before_tool_call`：`{ block: false }` 是无操作，不会清除先前的阻止。
- `before_install`：`{ block: true }` 是终止性的；较低优先级处理器会被跳过。
- `before_install`：`{ block: false }` 是无操作，不会清除先前的阻止。
- `message_sending`：`{ cancel: true }` 是终止性的；较低优先级处理器会被跳过。
- `message_sending`：`{ cancel: false }` 是无操作，不会清除先前的取消。
- `before_tool_call`：`{ block: true }` 是终止性的；较低优先级的处理器会被跳过。
- `before_tool_call`：`{ block: false }` 是空操作，并且不会清除先前的阻断。
- `before_install`：`{ block: true }` 是终止性的；较低优先级的处理器会被跳过。
- `before_install`：`{ block: false }` 是空操作，并且不会清除先前的阻断。
- `message_sending`：`{ cancel: true }` 是终止性的；较低优先级的处理器会被跳过。
- `message_sending`：`{ cancel: false }` 是空操作，并且不会清除先前的取消。
原生 Codex app-server 运行会将 Codex-native 工具事件桥接回此钩子表面。插件可以通过 `before_tool_call` 阻止原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。该桥接目前还不会重写 Codex-native 工具参数。确切的 Codex 运行时支持边界位于 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)。
原生 Codex 应用服务器会将 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) — 创建你自己的插件
- [插件 bundle](/zh-CN/plugins/bundles) — Codex/Claude/Cursor bundle 兼容性
- [插件清单](/zh-CN/plugins/manifest) — 清单 schema
- [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具
- [插件清单](/zh-CN/plugins/manifest) — 清单架构
- [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加 Agent 工具
- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流水线
- [社区插件](/zh-CN/plugins/community) — 第三方列表