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 19:12:01 +00:00
parent 5c9364129a
commit b84b7fc83d
8 changed files with 769 additions and 634 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
docs/zh-CN/cli/hooks.md
View File

@ -1,25 +1,25 @@
---
read_when:
- 你想要管理智能体钩子
- 你想要检查钩子的可用性，或启用工作区钩子
summary: '`openclaw hooks`（智能体钩子）的 CLI 参考'
- 你想管理智能体钩子
- 你想检查钩子可用性或启用工作区钩子
summary: '`openclaw hooks` 的 CLI 参考（智能体钩子）'
title: 钩子
x-i18n:
generated_at: "2026-04-27T09:29:04Z"
model: gpt-5.4
generated_at: "2026-05-02T19:10:28Z"
model: gpt-5.5
provider: openai
source_hash: 63ab6b014923dd4776767a6a0333129b85f51d008c63bb9fbdff06228d4c2f4b
source_hash: 3b02c176b4a310adba3fa1fde3758f6c8a19d454aeec58e919458b3f1a66c87d
source_path: cli/hooks.md
workflow: 15
workflow: 16
---
# `openclaw hooks`
管理智能体钩子（适用于 `/new`、`/reset` 和 Gateway 网关启动等命令的事件驱动自动化）。
管理智能体钩子（用于 `/new`、`/reset` 和 Gateway 网关启动等命令的事件驱动自动化）。
在没有子命令的情况下运行 `openclaw hooks`，等同于 `openclaw hooks list`。
不带子命令运行 `openclaw hooks` 等同于 `openclaw hooks list`。
相关内容：
相关：
- 钩子：[钩子](/zh-CN/automation/hooks)
- 插件钩子：[插件钩子](/zh-CN/plugins/hooks)
@ -31,12 +31,12 @@ openclaw hooks list
```
列出从工作区、托管、额外和内置目录中发现的所有钩子。
在至少配置了一个内部钩子之前，Gateway 网关启动时不会加载内部钩子处理程序。
除非至少配置了一个内部钩子，否则 Gateway 网关启动时不会加载内部钩子处理器。
**选项：**
- `--eligible`：仅显示符合条件的钩子（要求已满足）
- `--json`：以 JSON 格式输出
- `--eligible`：仅显示符合条件的钩子（满足要求）
- `--json`：以 JSON 输出
- `-v, --verbose`：显示详细信息，包括缺失的要求
**示例输出：**
@ -57,7 +57,7 @@ Ready:
openclaw hooks list --verbose
```
显示不符合条件的钩子缺失了哪些要求。
显示不符合条件的钩子缺失的要求。
**示例（JSON）：**
@ -65,7 +65,7 @@ openclaw hooks list --verbose
openclaw hooks list --json
```
返回结构化 JSON，供程序化使用。
返回结构化 JSON，供程序使用。
## 获取钩子信息
@ -77,11 +77,11 @@ openclaw hooks info <name>
**参数：**
- `<name>`：钩子名称或钩子键名（例如 `session-memory`）
- `<name>`：钩子名称或钩子键（例如 `session-memory`）
**选项：**
- `--json`：以 JSON 格式输出
- `--json`：以 JSON 输出
**示例：**
@ -107,17 +107,17 @@ Requirements:
Config: ✓ workspace.dir
```
## 检查钩子可用性
## 检查钩子资格
```bash
openclaw hooks check
```
显示钩子可用性状态的摘要（有多少已就绪，多少未就绪）。
显示钩子资格状态摘要（多少已就绪，多少未就绪）。
**选项：**
- `--json`：以 JSON 格式输出
- `--json`：以 JSON 输出
**示例输出：**
@ -135,9 +135,9 @@ Not ready: 0
openclaw hooks enable <name>
```
通过将特定钩子添加到你的配置中来启用它（默认为 `~/.openclaw/openclaw.json`）。
通过将特定钩子添加到你的配置中来启用它（默认是 `~/.openclaw/openclaw.json`）。
**注意：** 工作区钩子默认禁用，需在此处或配置中启用。由插件管理的钩子会在 `openclaw hooks list` 中显示 `plugin:<id>`，并且不能在这里启用或禁用。请改为启用或禁用相应插件。
**注意：** 工作区钩子默认处于禁用状态，直到在这里或配置中启用。由插件管理的钩子会在 `openclaw hooks list` 中显示 `plugin:<id>`，并且不能在这里启用或禁用。请改为启用或禁用对应插件。
**参数：**
@ -155,17 +155,17 @@ openclaw hooks enable session-memory
✓ Enabled hook: 💾 session-memory
```
**它会执行以下操作：**
**它会做什么：**
- 检查钩子是否存在且符合条件
- 在你的配置中更新 `hooks.internal.entries.<name>.enabled = true`
- 将配置保存到磁盘
如果该钩子来自 `<workspace>/hooks/`，则必须执行此选择启用步骤，Gateway 网关才会加载它。
如果钩子来自 `<workspace>/hooks/`，则在 Gateway 网关加载它之前，必须完成这个选择启用步骤。
**启用后：**
- 重启 Gateway 网关以重新加载钩子（macOS 上重启菜单栏应用，或在开发环境中重启你的 gateway 进程）。
- 重启 Gateway 网关以重新加载钩子（macOS 上重启菜单栏应用，或在开发环境中重启你的 Gateway 网关进程）。
## 禁用钩子
@ -198,26 +198,26 @@ openclaw hooks disable command-logger
## 说明
- `openclaw hooks list --json`、`info --json` 和 `check --json` 会将结构化 JSON 直接写入 stdout。
- 由插件管理的钩子不能在这里启用或禁用；请改为启用或禁用其所属插件。
- 插件管理的钩子不能在这里启用或禁用；请改为启用或禁用拥有它的插件。
## 安装钩子包
```bash
openclaw plugins install <package> # 优先使用 ClawHub，然后是 npm
openclaw plugins install npm:<package> # 仅使用 npm
openclaw plugins install <package> --pin # 固定版本
openclaw plugins install <path> # 本地路径
openclaw plugins install <package> # npm by default
openclaw plugins install npm:<package> # npm only
openclaw plugins install <package> --pin # pin version
openclaw plugins install <path> # local path
```
通过统一的插件安装器安装钩子包。
`openclaw hooks install` 仍然可用，作为兼容性别名，但它会打印弃用警告并转发到 `openclaw plugins install`。
`openclaw hooks install` 仍然作为兼容别名可用，但它会打印弃用警告并转发到 `openclaw plugins install`。
Npm 规格**仅限注册表**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/文件规格和 semver 范围会被拒绝。为了安全，即使你的 shell 设置了全局 npm 安装选项，依赖安装也会在项目本地使用 `--ignore-scripts` 运行。
Npm 规范是**仅注册表**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/文件规范和 semver 范围会被拒绝。为了安全，即使你的 shell 有全局 npm 安装设置，依赖安装也会以项目本地方式运行，并带上 `--ignore-scripts`。
裸规格和 `@latest` 会保持在稳定版本轨道上。如果 npm 将其中任一解析为预发布版本，OpenClaw 会停止并要求你显式选择加入，例如使用 `@beta`/`@rc` 这样的预发布标签，或精确的预发布版本。
裸规范和 `@latest` 会保持在稳定通道。如果 npm 将其中任意一种解析为预发布版本，OpenClaw 会停止并要求你使用预发布标签（如 `@beta`/`@rc`）或精确的预发布版本显式选择启用。
**它会执行以下操作：**
**它会做什么：**
- 将钩子包复制到 `~/.openclaw/hooks/<id>`
- 在 `hooks.internal.entries.*` 中启用已安装的钩子
@ -225,28 +225,28 @@ Npm 规格**仅限注册表**（包名 + 可选的**精确版本**或 **dist-tag
**选项：**
- `-l, --link`：链接本地目录而不是复制（将其添加到 `hooks.internal.load.extraDirs`）
- `--pin`：将 npm 安装记录为 `hooks.internal.installs` 中精确解析后的 `name@version`
- `-l, --link`：链接本地目录而不是复制（将它添加到 `hooks.internal.load.extraDirs`）
- `--pin`：将 npm 安装记录为 `hooks.internal.installs` 中精确解析出的 `name@version`
**支持的归档格式：** `.zip`、`.tgz`、`.tar.gz`、`.tar`
**示例：**
```bash
# 本地目录
# Local directory
openclaw plugins install ./my-hook-pack
# 本地归档文件
# Local archive
openclaw plugins install ./my-hook-pack.zip
# NPM 包
# NPM package
openclaw plugins install @openclaw/my-hook-pack
# 链接本地目录而不复制
# Link a local directory without copying
openclaw plugins install -l ./my-hook-pack
```
已链接的钩子包会被视为来自运维人员配置目录的托管钩子，而不是工作区钩子。
链接的钩子包会被视为来自运维人员配置目录的托管钩子，而不是工作区钩子。
## 更新钩子包
@ -255,22 +255,22 @@ openclaw plugins update <id>
openclaw plugins update --all
```
通过统一的插件更新器更新受跟踪的基于 npm 的钩子包。
通过统一的插件更新器更新已跟踪的基于 npm 的钩子包。
`openclaw hooks update` 仍然可用，作为兼容性别名，但它会打印弃用警告并转发到 `openclaw plugins update`。
`openclaw hooks update` 仍然作为兼容别名可用，但它会打印弃用警告并转发到 `openclaw plugins update`。
**选项：**
- `--all`：更新所有受跟踪的钩子包
- `--dry-run`：显示将要更改的内容，但不写入
- `--all`：更新所有已跟踪的钩子包
- `--dry-run`：显示将会发生的变更，但不写入
当存在已存储的完整性哈希，且获取到的构件哈希发生变化时，OpenClaw 会打印警告并在继续前请求确认。在 CI/非交互式运行中，可使用全局 `--yes` 跳过提示。
当存在已存储的完整性哈希，并且获取到的制品哈希发生变化时，OpenClaw 会打印警告，并在继续前请求确认。在 CI/非交互式运行中使用全局 `--yes` 可绕过提示。
## 内置钩子
### session-memory
当你发出 `/new` 或 `/reset` 时，将会话上下文保存到 memory。
当你发出 `/new` 或 `/reset` 时，将会话上下文保存到记忆中。
**启用：**
@ -284,7 +284,7 @@ openclaw hooks enable session-memory
### bootstrap-extra-files
在 `agent:bootstrap` 期间注入额外的引导文件（例如 monorepo 本地的 `AGENTS.md` / `TOOLS.md`）。
在 `agent:bootstrap` 期间注入额外的 bootstrap 文件（例如 monorepo 本地的 `AGENTS.md` / `TOOLS.md`）。
**启用：**
@ -296,7 +296,7 @@ openclaw hooks enable bootstrap-extra-files
### command-logger
将所有命令事件记录到一个集中的审计文件中。
将所有命令事件记录到集中式审计文件中。
**启用：**
@ -309,13 +309,13 @@ openclaw hooks enable command-logger
**查看日志：**
```bash
# 最近的命令
# Recent commands
tail -n 20 ~/.openclaw/logs/commands.log
# 美化打印
# Pretty-print
cat ~/.openclaw/logs/commands.log | jq .
# 按操作筛选
# Filter by action
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
```
@ -323,7 +323,7 @@ grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
### boot-md
在 Gateway 网关启动时运行 `BOOT.md`（在渠道启动之后）。
当 Gateway 网关启动时运行 `BOOT.md`（在渠道启动之后）。
**事件**：`gateway:startup`
@ -335,7 +335,7 @@ openclaw hooks enable boot-md
**参见：** [boot-md 文档](/zh-CN/automation/hooks#boot-md)
## 相关内容
## 相关
- [CLI 参考](/zh-CN/cli)
- [自动化钩子](/zh-CN/automation/hooks)

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

@ -1,30 +1,33 @@
---
read_when:
- 你想安装或管理 Gateway 网关插件或兼容捆绑包
- 你想调试插件加载失败问题
- 你想调试插件加载失败
sidebarTitle: Plugins
summary: '`openclaw plugins` 的 CLI 参考 (list, install, marketplace, uninstall, enable/disable, doctor)'
summary: '`openclaw plugins` 的 CLI 参考（列出、安装、插件市场、卸载、启用/禁用、Doctor）'
title: 插件
x-i18n:
generated_at: "2026-05-02T19:02:48Z"
generated_at: "2026-05-02T19:10:30Z"
model: gpt-5.5
provider: openai
source_hash: 162dac7c3e082d7de3bb4d97573761e824f30f6b0a5a806038ee9fb4f116ee4a
source_hash: c708f1f9d06bd07ba87ec0d88c98dacccca28422ea1097f98e07b4ee03697508
source_path: cli/plugins.md
workflow: 16
---
管理 Gateway 网关插件、钩子包和兼容 bundle。
管理 Gateway 网关插件、钩子包和兼容捆绑包。
<CardGroup cols={2}>
<Card title="插件系统" href="/zh-CN/tools/plugin">
面向最终用户的插件安装、启用和故障排除指南。
</Card>
<Card title="插件 bundle" href="/zh-CN/plugins/bundles">
Bundle 兼容性模型。
<Card title="管理插件" href="/zh-CN/plugins/manage-plugins">
安装、列表、更新、卸载和发布的快速示例。
</Card>
<Card title="插件 manifest" href="/zh-CN/plugins/manifest">
Manifest 字段和配置 schema。
<Card title="插件捆绑包" href="/zh-CN/plugins/bundles">
捆绑包兼容性模型。
</Card>
<Card title="插件清单" href="/zh-CN/plugins/manifest">
清单字段和配置架构。
</Card>
<Card title="安全" href="/zh-CN/gateway/security">
插件安装的安全加固。
@ -59,21 +62,21 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
如需调查安装、检查、卸载或 registry 刷新缓慢的问题，请使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 运行命令。该跟踪会将阶段耗时写入 stderr，并保持 JSON 输出可解析。请参阅[调试](/zh-CN/help/debugging#plugin-lifecycle-trace)。
要调查缓慢的安装、检查、卸载或注册表刷新，请使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 运行该命令。跟踪会将阶段耗时写入 stderr，并保持 JSON 输出可解析。请参阅[调试](/zh-CN/help/debugging#plugin-lifecycle-trace)。
<Note>
内置插件随 OpenClaw 一起发布。有些默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）；其他插件需要使用 `plugins enable`。
原生 OpenClaw 插件必须随附 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空也需要）。兼容 bundle 则改用自己的 bundle manifest。
原生 OpenClaw 插件必须随附 `openclaw.plugin.json`，其中包含内联 JSON Schema（`configSchema`，即使为空）。兼容捆绑包则使用自己的捆绑包清单。
`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细 list/info 输出还会显示 bundle 子类型（`codex`、`claude` 或 `cursor`）以及检测到的 bundle 能力。
`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细列表/信息输出还会显示捆绑包子类型（`codex`、`claude` 或 `cursor`）以及检测到的捆绑包能力。
</Note>
### 安装
```bash
openclaw plugins search "calendar" # search ClawHub plugins
openclaw plugins install <package> # ClawHub first, then npm
openclaw plugins install <package> # npm by default
openclaw plugins install clawhub:<package> # ClawHub only
openclaw plugins install npm:<package> # npm only
openclaw plugins install git:github.com/<owner>/<repo> # git repo
@ -88,57 +91,57 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
```
<Warning>
裸包名会先对照 ClawHub 检查，然后再检查 npm。请像运行代码一样对待插件安装。优先使用固定版本。
在发布切换期间，裸包名默认从 npm 安装。对 ClawHub 请使用 `clawhub:<package>`。应像运行代码一样看待插件安装。优先使用固定版本。
</Warning>
`plugins search` 会查询 ClawHub 中可安装的插件包，并打印可直接安装的包名。它会搜索 code-plugin 和 bundle-plugin 包，而不是 Skills。请使用 `openclaw skills search` 搜索 ClawHub Skills。
`plugins search` 会查询 ClawHub 中可安装的插件包，并打印可直接用于安装的包名。它会搜索代码插件和捆绑插件包，而不是 Skills。请使用 `openclaw skills search` 搜索 ClawHub Skills。
<Note>
ClawHub 是大多数插件的主要分发和发现入口。Npm 仍作为受支持的回退和直接安装路径。在迁移到 ClawHub 期间，OpenClaw 仍会在 npm 上发布一些 OpenClaw 自有的 `@openclaw/*` 插件包；在不同插件发布列车之间，这些包版本可能落后于内置源码。如果 npm 报告某个 OpenClaw 自有插件包已弃用，该已发布版本就是旧的外部产物；请使用当前 OpenClaw 内置的插件或本地 checkout，直到发布更新的 npm 包。
ClawHub 是大多数插件的主要分发和发现入口。Npm 仍然是受支持的备用路径和直接安装路径。在迁移到 ClawHub 期间，OpenClaw 仍会在 npm 上发布一些 OpenClaw 所有的 `@openclaw/*` 插件包；在插件发布批次之间，这些包版本可能落后于内置源码。如果 npm 将某个 OpenClaw 所有的插件包报告为已弃用，则该发布版本是旧的外部构件；请使用当前 OpenClaw 内置的插件，或使用本地检出，直到发布更新的 npm 包。
</Note>
<AccordionGroup>
<Accordion title="配置 include 和无效配置恢复">
如果你的 `plugins` 部分由单文件 `$include` 支撑，`plugins install/update/enable/disable/uninstall` 会写入该被 include 的文件，并保持 `openclaw.json` 不变。Root include、include 数组以及带有同级覆盖项的 include 会封闭失败，而不是被展平。请参阅[配置 include](/zh-CN/gateway/configuration) 了解受支持的形态。
<Accordion title="配置包含与无效配置恢复">
如果你的 `plugins` 部分由单文件 `$include` 支持，`plugins install/update/enable/disable/uninstall` 会写入该被包含文件，并保持 `openclaw.json` 不变。根包含、包含数组以及带同级覆盖的包含会以关闭方式失败，而不会被展平。支持的形态请参阅[配置包含](/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 网关支撑的 skill 依赖安装使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖项，而 `openclaw skills install` 仍是独立的 ClawHub skill 下载/安装流程。
此 CLI 标志适用于插件安装/更新流程。由 Gateway 网关支持的 skill 依赖安装使用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是单独的 ClawHub skill 下载/安装流程。
如果你在 ClawHub 上发布的插件被 registry 扫描阻断，请使用 [ClawHub](/zh-CN/tools/clawhub) 中的发布者步骤。
如果你在 ClawHub 发布的插件被注册表扫描阻止，请使用 [ClawHub](/zh-CN/tools/clawhub) 中的发布者步骤。
</Accordion>
<Accordion title="钩子包和 npm spec">
`plugins install` 也是安装在 `package.json` 中暴露 `openclaw.hooks` 的钩子包的入口。请使用 `openclaw hooks` 查看过滤后的钩子可见性和逐钩子启用，而不是用于包安装。
`plugins install` 也是用于安装在 `package.json` 中暴露 `openclaw.hooks` 的钩子包的入口。请使用 `openclaw hooks` 查看经过过滤的钩子可见性和按钩子启用，而不是用于包安装。
Npm spec **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。为安全起见，依赖安装会在项目本地使用 `--ignore-scripts` 运行，即使你的 shell 配置了全局 npm 安装设置也是如此。
Npm spec **仅限注册表**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。为安全起见，依赖安装会以项目本地方式运行并带上 `--ignore-scripts`，即使你的 shell 中有全局 npm 安装设置。
当你想跳过 ClawHub 查找并直接从 npm 安装时，请使用 `npm:<package>`。裸包 spec 仍优先使用 ClawHub，只有当 ClawHub 没有该包或版本时才回退到 npm。
当你想让 npm 解析显式化时，请使用 `npm:<package>`。在发布切换期间，裸包 spec 也会直接从 npm 安装。
裸 spec 和 `@latest` 会停留在稳定轨道。如果 npm 将其中任何一个解析到 prerelease，OpenClaw 会停止，并要求你使用 prerelease 标签（例如 `@beta`/`@rc`）或精确 prerelease 版本（例如 `@1.2.3-beta.4`）显式选择加入。
裸 spec 和 `@latest` 会留在稳定轨道上。如果 npm 将其中任一项解析到预发布版本，OpenClaw 会停止，并要求你通过预发布标签（例如 `@beta`/`@rc`）或精确预发布版本（例如 `@1.2.3-beta.4`）显式选择加入。
如果裸安装 spec 匹配官方插件 id（例如 `diffs`），OpenClaw 会直接安装 catalog 条目。若要安装同名 npm 包，请使用显式 scoped spec（例如 `@scope/diffs`）。
如果裸安装 spec 匹配官方插件 id（例如 `diffs`），OpenClaw 会直接安装目录条目。要安装同名 npm 包，请使用显式作用域 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>` 可在安装前 checkout 分支、标签或提交。
使用 `git:<repo>` 可直接从 git 仓库安装。支持的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整 `https://`、`ssh://`、`git://`、`file://` 和 `git@host:owner/repo.git` 克隆 URL。添加 `@<ref>` 或 `#<ref>` 可在安装前检出分支、标签或提交。
Git 安装会 clone 到临时目录，在存在请求的 ref 时将其 checkout，然后使用正常的插件目录安装器。这意味着 manifest 校验、危险代码扫描、包管理器安装工作和安装记录的行为都类似 npm 安装。记录的 git 安装会包含来源 URL/ref 以及解析出的提交，以便 `openclaw plugins update` 之后可以重新解析来源。
Git 安装会克隆到临时目录，在存在请求的 ref 时将其检出，然后使用普通插件目录安装器。这意味着清单校验、危险代码扫描、包管理器安装工作和安装记录的行为都类似 npm 安装。记录的 git 安装包含源 URL/ref 以及解析出的提交，以便 `openclaw plugins update` 之后可以重新解析来源。
从 git 安装后，请使用 `openclaw plugins inspect <id> --runtime --json` 验证运行时注册，例如 gateway 方法和 CLI 命令。如果插件使用 `api.registerCli` 注册了 CLI root，请直接通过 OpenClaw root 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="归档">
@ -149,32 +152,32 @@ ClawHub 是大多数插件的主要分发和发现入口。Npm 仍作为受支
</Accordion>
</AccordionGroup>
ClawHub 安装使用显式 `clawhub:<package>` 定位器：
ClawHub 安装使用显式的 `clawhub:<package>` 定位符：
```bash
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
OpenClaw 现在也会优先使用 ClawHub 解析裸 npm-safe 插件 spec。只有当 ClawHub 没有该包或版本时，它才会回退到 npm：
在发布切换期间，裸 npm 安全插件 spec 默认从 npm 安装：
```bash
openclaw plugins install openclaw-codex-app-server
```
使用 `npm:` 可强制仅通过 npm 解析，例如当 ClawHub 不可访问，或你知道该包只存在于 npm 上时：
使用 `npm:` 让仅 npm 解析显式化：
```bash
openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/plugin-name@1.0.1
```
OpenClaw 会在安装前检查公布的插件 API / 最低 gateway 兼容性。当选中的 ClawHub 版本发布了 ClawPack 产物时，OpenClaw 会下载带版本的 npm-pack `.tgz`，校验 ClawHub digest header 和产物 digest，然后通过正常归档路径安装。没有 ClawPack 元数据的旧版 ClawHub 版本仍会通过旧版包归档校验路径安装。记录的安装会保留其 ClawHub 来源元数据、产物类型、npm integrity、npm shasum、tarball 名称和 ClawPack digest 信息，以供后续更新使用。
未带版本的 ClawHub 安装会保留未带版本的记录 spec，使 `openclaw plugins update` 可以跟随更新的 ClawHub 发布；显式版本或标签选择器（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）仍固定到该选择器。
OpenClaw 会在安装前检查发布的插件 API / 最低 gateway 兼容性。当选定的 ClawHub 版本发布 ClawPack 构件时，OpenClaw 会下载带版本的 npm-pack `.tgz`，验证 ClawHub 摘要标头和构件摘要，然后通过普通归档路径安装。没有 ClawPack 元数据的旧 ClawHub 版本仍会通过旧版包归档验证路径安装。记录的安装会保留其 ClawHub 源元数据、构件类型、npm integrity、npm shasum、tarball 名称和 ClawPack 摘要事实，以供后续更新使用。
未带版本的 ClawHub 安装会保留未带版本的记录 spec，以便 `openclaw plugins update` 可以跟随更新的 ClawHub 发布；显式版本或标签选择器（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）则会保持固定到该选择器。
#### Marketplace 简写
当 marketplace 名称存在于 Claude 的本地 registry 缓存 `~/.claude/plugins/known_marketplaces.json` 中时，请使用 `plugin@marketplace` 简写：
当 marketplace 名称存在于 Claude 的本地注册表缓存 `~/.claude/plugins/known_marketplaces.json` 中时，请使用 `plugin@marketplace` 简写：
```bash
openclaw plugins marketplace list <marketplace-name>
@ -200,22 +203,22 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
</Tab>
<Tab title="远程市场规则">
对于从 GitHub 或 git 加载的远程市场，插件条目必须保留在克隆的市场仓库内。OpenClaw 接受该仓库中的相对路径源，并拒绝来自远程清单的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径插件源。
对于从 GitHub 或 git 加载的远程市场，插件条目必须保留在克隆的市场仓库内。OpenClaw 接受来自该仓库的相对路径源，并拒绝来自远程清单的 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>
兼容包会安装到普通插件根目录，并参与相同的列表/信息/启用/禁用流程。目前支持包 Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex 钩子目录；其他检测到的包能力会显示在诊断/信息中，但尚未接入运行时执行。
兼容包会安装到普通插件根目录，并参与相同的列出/信息/启用/禁用流程。目前支持包 Skills、Claude 命令 Skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor 命令 Skills，以及兼容 Codex 钩子目录；其他检测到的包能力会显示在诊断/信息中，但尚未接入运行时执行。
</Note>
### 列表
### 列出
```bash
openclaw plugins list
@ -231,40 +234,40 @@ openclaw plugins search <query> --json
仅显示已启用的插件。
</ParamField>
<ParamField path="--verbose" type="boolean">
从表格视图切换到每个插件的详情行，包含源/来源/版本/激活元数据。
从表格视图切换为每个插件的详细行，包含源/来源/版本/激活元数据。
</ParamField>
<ParamField path="--json" type="boolean">
机器可读的清单，加上注册表诊断和包依赖安装状态。
</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` 子进程，而不仅是包装器进程。
`plugins list --json` 会包含每个插件来自 `package.json`
`dependencies` 和 `optionalDependencies` 的 `dependencyStatus`。OpenClaw 会检查这些包
名称是否存在于插件常规 Node `node_modules` 查找路径上；它
不会导入插件运行时代码、运行包管理器，或修复缺失的
名称是否存在于插件正常 Node `node_modules` 查找路径上；它
不会导入插件运行时代码、运行包管理器或修复缺失的
依赖。
</Note>
`plugins search` 是远程 ClawHub 目录查询。它不会检查本地
状态、修改配置、安装包或加载插件运行时代码。搜索
结果包含 ClawHub 包名、系列、渠道、版本、摘要，以及
类似 `openclaw plugins install clawhub:<package>` 的安装提示。
结果包含 ClawHub 包名称、系列、渠道、版本、摘要，以及
安装提示，例如 `openclaw plugins install clawhub:<package>`。
对于打包 Docker 镜像内的内置插件工作，请将插件
源目录绑定挂载到匹配的打包源路径上，例如
`/app/extensions/synology-chat`。OpenClaw 会先发现该已挂载的源
`/app/extensions/synology-chat`。OpenClaw 会先发现该挂载的源
覆盖层，再发现 `/app/dist/extensions/synology-chat`；普通复制的源
目录保持不生效，因此常规打包安装仍会使用已编译的 dist。
目录仍不会生效，因此正常打包安装仍会使用编译后的 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`）：
使用 `--link` 可以避免复制本地目录（会添加到 `plugins.load.paths`）：
```bash
openclaw plugins install -l ./my-plugin
@ -273,14 +276,14 @@ openclaw plugins install -l ./my-plugin
<Note>
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是覆盖托管安装目标。
在 npm 安装上使用 `--pin` 可将解析出的精确规格（`name@version`）保存到托管插件索引中，同时保持默认行为为不固定版本。
在 npm 安装中使用 `--pin` 可以将解析后的精确 spec（`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` 记录时，会将其移入插件索引并移除该配置键；如果任一写入失败，配置记录会保留，以免安装元数据丢失。
### 卸载
@ -290,10 +293,10 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` 会在适用时从 `plugins.entries`、持久化插件索引、插件允许/拒绝列表条目，以及已链接的 `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` 的已弃用别名受到支持。
`--keep-config` 作为 `--keep-files` 的弃用别名受到支持。
</Note>
### 更新
@ -306,25 +309,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="解析插件 id 与 npm 规格">
当你传入插件 id 时，OpenClaw 会复用该插件记录的安装规格。这意味着之前存储的 dist-tags（例如 `@beta`）和精确固定版本会在之后的 `update <id>` 运行中继续使用。
<Accordion title="解析插件 id 与 npm spec">
当你传入插件 id 时，OpenClaw 会复用为该插件记录的安装 spec。这意味着之前存储的 dist-tag（如 `@beta`）和精确固定版本会在后续 `update <id>` 运行中继续使用。
对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包规格。OpenClaw 会将该包名解析回被跟踪的插件记录，更新该已安装插件，并记录新的 npm 规格，以便未来基于 id 的更新使用。
对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会将该包名解析回已跟踪的插件记录，更新该已安装插件，并记录新的 npm spec 以供未来基于 id 的更新使用。
传入不带版本或标签的 npm 包名也会解析回被跟踪的插件记录。当插件被固定到精确版本，而你想将它移回注册表默认发布线时，请使用这种方式。
传入不带版本或标签的 npm 包名也会解析回已跟踪的插件记录。当某个插件被固定到精确版本，而你想将其移回注册表默认发布线时，请使用这种方式。
</Accordion>
<Accordion title="版本检查和完整性漂移">
在实时 npm 更新之前，OpenClaw 会根据 npm 注册表元数据检查已安装包版本。如果已安装版本和记录的构件身份已经匹配解析出的目标，则会跳过更新，不下载、不重新安装，也不重写 `openclaw.json`。
在实时 npm 更新之前，OpenClaw 会根据 npm 注册表元数据检查已安装包版本。如果已安装版本和记录的构件身份已经匹配解析后的目标，更新会跳过，不下载、不重新安装，也不重写 `openclaw.json`。
当存在已存储的完整性哈希，并且获取到的构件哈希发生变化时，OpenClaw 会将其视为 npm 构件漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。除非调用方提供显式继续策略，否则非交互式更新辅助程序会以失败关闭方式处理。
当存在已存储的完整性哈希且获取到的构件哈希发生变化时，OpenClaw 会将其视为 npm 构件漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新助手会默认关闭失败，除非调用方提供显式继续策略。
</Accordion>
<Accordion title="更新时使用 --dangerously-force-unsafe-install">
`--dangerously-force-unsafe-install` 也可在 `plugins update` 上使用，作为插件更新期间内置危险代码扫描误报的紧急覆盖。它仍然不会绕过插件 `before_install` 策略阻断或扫描失败阻断，并且只适用于插件更新，不适用于 hook-pack 更新。
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的应急覆盖。它仍不会绕过插件 `before_install` 策略阻止或扫描失败阻止，并且只适用于插件更新，不适用于钩子包更新。
</Accordion>
</AccordionGroup>
@ -336,21 +339,21 @@ openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
```
默认情况下，检查会显示身份、加载状态、源、清单能力、策略标志、诊断、安装元数据、包能力，以及检测到的任何 MCP 或 LSP 服务器支持，而不会导入插件运行时。添加 `--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` 会渲染全量表格，包含形态、能力类型、兼容性通知、包能力和钩子摘要列。`info` 是 `inspect` 的别名。
`--json` 标志会输出适合脚本和审计的机器可读报告。`inspect --all` 会渲染全量表格，包含形态、能力种类、兼容性通知、包能力和钩子摘要列。`info` 是 `inspect` 的别名。
</Note>
### Doctor
@ -361,7 +364,7 @@ openclaw plugins doctor
`doctor` 会报告插件加载错误、清单/发现诊断和兼容性通知。当一切正常时，它会打印 `No plugin issues detected.`
对于缺失 `register`/`activate` 导出等模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以在诊断输出中包含紧凑的导出形态摘要。
对于缺少 `register`/`activate` 导出等模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以在诊断输出中包含紧凑的导出形态摘要。
### 注册表
@ -371,12 +374,12 @@ 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>
### 市场
@ -386,7 +389,7 @@ openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
市场列表接受本地市场路径、`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。`--json` 会打印解析后的源标签，以及解析后的市场清单和插件条目。
市场列表接受本地市场路径、`marketplace.json` 路径、GitHub 简写（如 `owner/repo`）、GitHub 仓库 URL 或 git URL。`--json` 会打印解析后的源标签，以及解析后的市场清单和插件条目。
## 相关

131
docs/zh-CN/plugins/building-plugins.md
View File

@ -1,31 +1,31 @@
---
read_when:
- 你想创建一个新的 OpenClaw 插件
- 你需要一份用于插件开发的快速开始指南
- 你需要一份插件开发快速开始指南
- 你正在向 OpenClaw 添加新的渠道、提供商、工具或其他能力
sidebarTitle: Getting Started
summary: 几分钟内创建你的第一个 OpenClaw 插件
title: 构建插件
x-i18n:
generated_at: "2026-05-02T13:56:38Z"
generated_at: "2026-05-02T19:10:40Z"
model: gpt-5.5
provider: openai
source_hash: f4f810d831db26d1e4efecf691590980b3ba1d958c4b4af3cc6a7ca9ea155a36
source_hash: b42170b40094f89a63b1497c08ec31e397931dd536bd6faeeb8bc3c123ae45d1
source_path: plugins/building-plugins.md
workflow: 16
---
插件用新能力扩展 OpenClaw：渠道、模型提供商、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、Web 获取、Web 搜索、智能体工具，或它们的任意组合。
插件为 OpenClaw 扩展新能力：渠道、模型提供商、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页获取、Web 搜索、智能体工具，或它们的任意组合。
你不需要把插件添加到 OpenClaw 仓库。发布到 [ClawHub](/zh-CN/tools/clawhub)，用户用 `openclaw plugins install <package-name>` 安装。OpenClaw 会先尝试 ClawHub，并对仍使用 npm 分发的软件包自动回退到 npm。
你不需要把你的插件添加到 OpenClaw 仓库。发布到 [ClawHub](/zh-CN/tools/clawhub)，用户可通过 `openclaw plugins install clawhub:<package-name>` 安装。在发布切换期间，裸包规格仍会从 npm 安装。
## 前提条件
- Node >= 22 和一个包管理器（npm 或 pnpm）
- 熟悉 TypeScript（ESM）
- 对于仓库内插件：已克隆仓库并完成 `pnpm install`。源代码检出方式的插件开发仅支持 pnpm，因为 OpenClaw 会从 `extensions/*` 工作区软件包加载内置插件。
- 对于仓库内插件：已克隆仓库并完成 `pnpm install`。源码检出插件开发仅支持 pnpm，因为 OpenClaw 会从 `extensions/*` 工作区包加载内置插件。
## 什么类型的插件？
## 哪种插件？
<CardGroup cols={3}>
<Card title="渠道插件" icon="messages-square" href="/zh-CN/plugins/sdk-channel-plugins">
@ -39,14 +39,14 @@ x-i18n:
</Card>
</CardGroup>
对于不能保证在新手引导/设置运行时已安装的渠道插件，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。它会生成一个设置适配器 + 向导组合，用于提示安装要求，并在插件安装前对真实配置写入保持失败关闭状态。
对于无法保证在新手引导/设置运行时已安装的渠道插件，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。它会生成一组设置适配器 + 向导，说明安装要求，并且在插件安装前对真实配置写入采取失败关闭策略。
## 快速开始：工具插件
本演练会创建一个注册智能体工具的最小插件。渠道和提供商插件有上方链接的专门指南。
本演练会创建一个注册智能体工具的最小插件。渠道和提供商插件有上面链接的专门指南。
<Steps>
<Step title="创建软件包和清单">
<Step title="创建包和清单">
<CodeGroup>
```json package.json
{
@ -86,7 +86,7 @@ x-i18n:
```
</CodeGroup>
每个插件都需要一个清单，即使没有配置也是如此。运行时注册的工具必须列在 `contracts.tools` 中，这样 OpenClaw 才能在不加载每个插件运行时的情况下发现拥有该工具的插件。插件还应有意声明 `activation.onStartup`。此示例将其设置为 `true`。完整 schema 请参阅 [Manifest](/zh-CN/plugins/manifest)。规范的 ClawHub 发布片段位于 `docs/snippets/plugin-publish/`。
每个插件都需要清单，即使没有配置也是如此。运行时注册的工具必须列在 `contracts.tools` 中，这样 OpenClaw 才能在不加载每个插件运行时的情况下发现所属插件。插件还应有意声明 `activation.onStartup`。此示例将其设为 `true`。完整架构请参阅 [清单](/zh-CN/plugins/manifest)。规范的 ClawHub 发布片段位于 `docs/snippets/plugin-publish/`。
</Step>
@ -120,7 +120,7 @@ x-i18n:
<Step title="测试并发布">
**外部插件：**使用 ClawHub 验证并发布，然后安装：
**外部插件：** 使用 ClawHub 验证并发布，然后安装：
```bash
clawhub package publish your-org/your-plugin --dry-run
@ -128,9 +128,9 @@ x-i18n:
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
```
对于像 `@myorg/openclaw-my-plugin` 这样的裸包规格，OpenClaw 也会先检查 ClawHub，再检查 npm；对于尚未迁移到 ClawHub 的软件包，npm 仍作为回退。
在发布切换期间，像 `@myorg/openclaw-my-plugin` 这样的裸包规格会从 npm 安装。当你希望使用 ClawHub 解析时，请使用 `clawhub:`。
**仓库内插件：**放在内置插件工作区树下 — 会被自动发现。
**仓库内插件：** 放在内置插件工作区树下 — 会自动发现。
```bash
pnpm test -- <bundled-plugin-root>/my-plugin/
@ -149,13 +149,13 @@ 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) |
| Web 获取 | `api.registerWebFetchProvider(...)` | [提供商插件](/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.registerAgentToolResultMiddleware(...)` | [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api) |
| 智能体工具 | `api.registerTool(...)` | 下文 |
@ -167,31 +167,31 @@ 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"]`。这是受信任的内置插件接口；外部插件应优先使用常规 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`：`{ requireApproval: true }` 会暂停智能体执行，并通过 exec 批准浮层、Telegram 按钮、Discord 交互，或任意渠道上的 `/approve` 命令提示用户批准。
- `before_install`：`{ block: true }` 是终止性的，并会停止较低优先级的处理程序。
- `before_install`：`{ block: false }` 被视为未做决定。
- `message_sending`：`{ cancel: true }` 是终止性的，并会停止较低优先级的处理程序。
- `message_sending`：`{ cancel: false }` 被视为未做决定。
- `message_received`：当你需要入站线程/话题路由时，优先使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道特定的额外信息。
- `before_tool_call`：`{ block: true }` 是终止性的，并会停止较低优先级的处理器。
- `before_tool_call`：`{ block: false }` 会被视为没有决策。
- `before_tool_call`：`{ requireApproval: true }` 会暂停智能体执行，并通过执行审批叠层、Telegram 按钮、Discord 交互，或任何渠道上的 `/approve` 命令提示用户审批。
- `before_install`：`{ block: true }` 是终止性的，并会停止较低优先级的处理器。
- `before_install`：`{ block: false }` 会被视为没有决策。
- `message_sending`：`{ cancel: true }` 是终止性的，并会停止较低优先级的处理器。
- `message_sending`：`{ cancel: false }` 会被视为没有决策。
- `message_received`：当你需要入站会话串/主题路由时，优先使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道特定的额外信息。
- `message_sending`：优先使用类型化的 `replyToId` / `threadId` 路由字段，而不是渠道特定的元数据键。
`/approve` 命令会用有界回退处理 exec 和插件批准：找不到 exec 批准 ID 时，OpenClaw 会用同一个 ID 重试插件批准。插件批准转发可以通过配置中的 `approvals.plugin` 独立配置。
`/approve` 命令通过有界回退同时处理执行审批和插件审批：当找不到执行审批 ID 时，OpenClaw 会用同一 ID 通过插件审批重试。插件审批转发可以通过配置中的 `approvals.plugin` 独立配置。
如果自定义批准管线需要检测同一个有界回退情况，请优先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，而不是手动匹配批准过期字符串。
如果自定义审批管线需要检测同一个有界回退场景，请优先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，而不是手动匹配审批过期字符串。
示例和钩子参考请参阅 [插件钩子](/zh-CN/plugins/hooks)。
## 注册智能体工具
工具是 LLM 可以调用的类型化函数。它们可以是必需的（始终可用）或可选的（用户选择启用）：
工具是 LLM 可以调用的类型化函数。它们可以是必需的（始终可用），也可以是可选的（用户选择启用）：
```typescript
register(api) {
@ -230,9 +230,9 @@ register(api) {
}
```
OpenClaw 会从已注册工具捕获并缓存经过验证的描述符，因此插件不需要在清单中重复 `description` 或 schema 数据。清单契约只声明所有权和发现；执行仍会调用实时注册的工具实现。
OpenClaw 会从已注册工具捕获并缓存经过验证的描述符，因此插件不需要在清单中重复 `description` 或架构数据。清单契约只声明所有权和发现；执行仍会调用实时注册的工具实现。
用户在配置中启用可选工具：
用户可在配置中启用可选工具：
```json5
{
@ -240,15 +240,16 @@ OpenClaw 会从已注册工具捕获并缓存经过验证的描述符，因此
}
```
- 工具名称不得与核心工具冲突（冲突项会被跳过）
- 工具名称不得与核心工具冲突（存在冲突的会被跳过）
- 注册对象格式错误的工具（包括缺少 `parameters`）会被跳过并在插件诊断中报告，而不是中断智能体运行
- 对有副作用或需要额外二进制文件的工具使用 `optional: true`
- 用户可以通过将插件 id 添加到 `tools.allow` 来启用插件中的所有工具
- 对有副作用或额外二进制要求的工具使用 `optional: true`
- 用户可以通过将插件 id 添加到 `tools.allow` 来启用某个插件的所有工具
## 注册 CLI 命令
插件可以通过 `api.registerCli` 添加根级 `openclaw` 命令组。为每个顶层命令根提供
`descriptors`，这样 OpenClaw 就可以展示并路由该命令，而无需急切加载每个插件运行时。
插件可以使用 `api.registerCli` 添加根级 `openclaw` 命令组。为每个顶层命令根提供
`descriptors`，这样 OpenClaw 就可以显示和路由
该命令，而无需预先加载每个插件运行时。
```typescript
register(api) {
@ -278,7 +279,7 @@ register(api) {
}
```
安装后，验证运行时注册并执行命令：
安装后，验证运行时注册并执行该命令：
```bash
openclaw plugins inspect demo-plugin --runtime --json
@ -297,59 +298,63 @@ 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 路径导入你自己的插件。
在你的插件内，对内部导入使用本地 barrel 文件（`api.ts`、`runtime-api.ts`）——绝不要通过插件自己的 SDK 路径导入它本身。
对于提供商插件，请将提供商专用辅助函数保留在这些 package 根级 barrel 中，除非该接缝确实是通用的。当前内置示例：
对于提供商插件，请将提供商特定的辅助工具保留在这些包根级
barrel 中，除非该接口确实是通用的。当前内置示例：
- Anthropic：Claude 流包装器以及 `service_tier` / beta 辅助函数
- OpenAI：提供商构建器、默认模型辅助函数、实时提供商
- OpenRouter：提供商构建器以及新手引导/配置辅助函数
- Anthropic：Claude 流包装器以及 `service_tier` / beta 辅助工具
- OpenAI：提供商构建器、默认模型辅助工具、实时提供商
- OpenRouter：提供商构建器以及新手引导/配置辅助工具
如果某个辅助函数只在一个内置提供商包内部有用，请将它保留在该 package 根级接缝上，而不是提升到 `openclaw/plugin-sdk/*` 中。
如果某个辅助工具只在一个内置提供商包内有用，请将它保留在该
包根级接口上，而不是提升到 `openclaw/plugin-sdk/*` 中。
一些生成的 `openclaw/plugin-sdk/<bundled-id>` 辅助接缝仍然存在，用于在存在已跟踪 owner 用法时维护内置插件。将这些视为保留表面，而不是新第三方插件的默认模式。
一些生成的 `openclaw/plugin-sdk/<bundled-id>` 辅助接口仍然存在，
用于在有跟踪到的所有者使用情况时维护内置插件。请将这些视为
保留接口，而不是新第三方插件的默认模式。
## 提交前检查清单
<Check>**package.json** 具有正确的 `openclaw` 元数据</Check>
<Check>**openclaw.plugin.json** 清单存在且有效</Check>
<Check>**package.json** 包含正确的 `openclaw` 元数据</Check>
<Check>**openclaw.plugin.json** 插件清单存在且有效</Check>
<Check>入口点使用 `defineChannelPluginEntry` 或 `definePluginEntry`</Check>
<Check>所有导入都使用聚焦的 `plugin-sdk/<subpath>` 路径</Check>
<Check>内部导入使用本地模块，而不是 SDK 自导入</Check>
<Check>测试通过（`pnpm test -- <bundled-plugin-root>/my-plugin/`）</Check>
<Check>`pnpm check` 通过（仓库内插件）</Check>
## Beta 版本发布测试
## 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) 开启通知，以接收发布公告。
2. Beta 标签一出现，就针对该 beta 标签测试你的插件。稳定版发布前的窗口通常只有几个小时。
3. 测试后，在 `plugin-forum` Discord 渠道中你的插件线程里发布 `all good` 或说明损坏内容。如果你还没有线程，请创建一个。
4. 如果有内容损坏，请打开或更新标题为 `Beta blocker: <plugin-name> - <summary>` 的 issue，并应用 `beta-blocker` 标签。将 issue 链接放入你的线程。
5. 向 `main` 打开一个标题为 `fix(<plugin-id>): beta blocker - <summary>` 的 PR，并在 PR 和你的 Discord 线程中链接该 issue。贡献者无法给 PR 打标签，因此标题是给维护者和自动化系统的 PR 侧信号。有 PR 的阻断问题会被合并；没有 PR 的阻断问题仍可能随版本发布。维护者会在 beta 测试期间关注这些线程。
6. 沉默即表示通过。如果你错过窗口，你的修复很可能会进入下一个周期。
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: <plugin-name> - <summary>` 的 issue，并应用 `beta-blocker` 标签。将 issue 链接放到你的线程中。
5. 打开一个指向 `main` 的 PR，标题为 `fix(<plugin-id>): beta blocker - <summary>`，并在 PR 和你的 Discord 线程中都链接该 issue。贡献者无法给 PR 打标签，因此标题是给维护者和自动化的 PR 侧信号。有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题可能仍会随版本发布。维护者会在 beta 测试期间关注这些线程。
6. 沉默即表示绿色通过。如果你错过窗口，你的修复很可能会进入下一个周期。
## 后续步骤
<CardGroup cols={2}>
<Card title="Channel Plugins" icon="messages-square" href="/zh-CN/plugins/sdk-channel-plugins">
<Card title="渠道插件" icon="messages-square" href="/zh-CN/plugins/sdk-channel-plugins">
构建消息渠道插件
</Card>
<Card title="Provider Plugins" icon="cpu" href="/zh-CN/plugins/sdk-provider-plugins">
<Card title="提供商插件" icon="cpu" href="/zh-CN/plugins/sdk-provider-plugins">
构建模型提供商插件
</Card>
<Card title="SDK Overview" icon="book-open" href="/zh-CN/plugins/sdk-overview">
<Card title="SDK 概览" icon="book-open" href="/zh-CN/plugins/sdk-overview">
导入映射和注册 API 参考
</Card>
<Card title="Runtime Helpers" icon="settings" href="/zh-CN/plugins/sdk-runtime">
<Card title="运行时辅助工具" icon="settings" href="/zh-CN/plugins/sdk-runtime">
通过 api.runtime 使用 TTS、搜索、子智能体
</Card>
<Card title="Testing" icon="test-tubes" href="/zh-CN/plugins/sdk-testing">
测试实用工具和模式
<Card title="测试" icon="test-tubes" href="/zh-CN/plugins/sdk-testing">
测试工具和模式
</Card>
<Card title="Plugin Manifest" icon="file-json" href="/zh-CN/plugins/manifest">
完整清单 schema 参考
<Card title="插件清单" icon="file-json" href="/zh-CN/plugins/manifest">
完整清单架构参考
</Card>
</CardGroup>

90
docs/zh-CN/plugins/community.md
View File

@ -5,32 +5,32 @@ read_when:
summary: 社区维护的 OpenClaw 插件：浏览、安装并提交你自己的插件
title: 社区插件
x-i18n:
generated_at: "2026-04-30T08:06:32Z"
generated_at: "2026-05-02T19:10:30Z"
model: gpt-5.5
provider: openai
source_hash: 9685aaf141b739a2a745a6184201ac86689e4284bec6eb068ffbd0d53fb4ecf1
source_hash: 3a58fbc153c837f5ac79ee70406a5611e8a9a273c18c0c5642763531fbe10dca
source_path: plugins/community.md
workflow: 16
---
社区插件是扩展 OpenClaw 的第三方包，可为 OpenClaw 增加新的渠道、工具、提供商或其他能力。它们由社区构建和维护，通常发布在 [ClawHub](/zh-CN/tools/clawhub) 上，并且可以通过一条命令安装。对于尚未迁移到 ClawHub 的包，npm 仍然是受支持的备用方式。
社区插件是第三方软件包，可为 OpenClaw 扩展新的渠道、工具、提供商或其他能力。它们由社区构建和维护，通常发布在 [ClawHub](/zh-CN/tools/clawhub)，并可通过单条命令安装。在 ClawHub 打包安装逐步推出期间，npm 仍是裸包规范的默认启动方式。
ClawHub 是社区插件的规范发现入口。不要仅为了让你的插件在这里可被发现而提交仅文档的 PR；请改为将其发布到 ClawHub。
ClawHub 是社区插件的权威发现入口。不要只是为了让你的插件在这里可被发现而提交纯文档 PR；请改为将其发布到 ClawHub。
```bash
openclaw plugins install <package-name>
openclaw plugins install clawhub:<package-name>
```
OpenClaw 会先检查 ClawHub，并在需要时自动回退到 npm。
对托管在 npm 上的软件包，请使用 `openclaw plugins install <package-name>`。
## 已列出的插件
### Apify
使用 20,000 多个现成爬虫从任意网站抓取数据。让你的智能体只需提出请求，就能从 Instagram、Facebook、TikTok、YouTube、Google Maps、Google Search、电子商务网站等提取数据。
使用 20,000 多个现成爬虫从任意网站抓取数据。只需提出请求，就能让你的智能体从 Instagram、Facebook、TikTok、YouTube、Google Maps、Google Search、电子商务网站等提取数据。
- **npm:** `@apify/apify-openclaw-plugin`
- **仓库:** [github.com/apify/apify-openclaw-plugin](https://github.com/apify/apify-openclaw-plugin)
- **npm：** `@apify/apify-openclaw-plugin`
- **仓库：** [github.com/apify/apify-openclaw-plugin](https://github.com/apify/apify-openclaw-plugin)
```bash
openclaw plugins install @apify/apify-openclaw-plugin
@ -38,10 +38,10 @@ openclaw plugins install @apify/apify-openclaw-plugin
### Codex App Server Bridge
用于 Codex App Server 对话的独立 OpenClaw 桥接器。将聊天绑定到 Codex 线程，用纯文本与其交流，并通过聊天原生命令控制恢复、规划、评审、模型选择、压缩等功能。
用于 Codex App Server 对话的独立 OpenClaw 桥接器。将聊天绑定到 Codex 线程，用纯文本与它对话，并通过聊天原生命令控制恢复、规划、审查、模型选择、压缩等功能。
- **npm:** `openclaw-codex-app-server`
- **仓库:** [github.com/pwrdrvr/openclaw-codex-app-server](https://github.com/pwrdrvr/openclaw-codex-app-server)
- **npm：** `openclaw-codex-app-server`
- **仓库：** [github.com/pwrdrvr/openclaw-codex-app-server](https://github.com/pwrdrvr/openclaw-codex-app-server)
```bash
openclaw plugins install openclaw-codex-app-server
@ -51,8 +51,8 @@ openclaw plugins install openclaw-codex-app-server
使用 Stream 模式的企业机器人集成。支持通过任意 DingTalk 客户端发送文本、图片和文件消息。
- **npm:** `@largezhou/ddingtalk`
- **仓库:** [github.com/largezhou/openclaw-dingtalk](https://github.com/largezhou/openclaw-dingtalk)
- **npm：** `@largezhou/ddingtalk`
- **仓库：** [github.com/largezhou/openclaw-dingtalk](https://github.com/largezhou/openclaw-dingtalk)
```bash
openclaw plugins install @largezhou/ddingtalk
@ -60,10 +60,10 @@ openclaw plugins install @largezhou/ddingtalk
### Lossless Claw (LCM)
用于 OpenClaw 的无损上下文管理插件。基于 DAG 的对话摘要，支持增量压缩，在降低 token 使用量的同时保留完整上下文保真度。
面向 OpenClaw 的无损上下文管理插件。基于 DAG 的对话摘要与增量压缩，可在减少令牌用量的同时保留完整的上下文保真度。
- **npm:** `@martian-engineering/lossless-claw`
- **仓库:** [github.com/Martian-Engineering/lossless-claw](https://github.com/Martian-Engineering/lossless-claw)
- **npm：** `@martian-engineering/lossless-claw`
- **仓库：** [github.com/Martian-Engineering/lossless-claw](https://github.com/Martian-Engineering/lossless-claw)
```bash
openclaw plugins install @martian-engineering/lossless-claw
@ -71,10 +71,10 @@ openclaw plugins install @martian-engineering/lossless-claw
### Opik
官方插件，可将智能体轨迹导出到 Opik。监控智能体行为、成本、token、错误等。
将智能体跟踪导出到 Opik 的官方插件。监控智能体行为、成本、令牌、错误等。
- **npm:** `@opik/opik-openclaw`
- **仓库:** [github.com/comet-ml/opik-openclaw](https://github.com/comet-ml/opik-openclaw)
- **npm：** `@opik/opik-openclaw`
- **仓库：** [github.com/comet-ml/opik-openclaw](https://github.com/comet-ml/opik-openclaw)
```bash
openclaw plugins install @opik/opik-openclaw
@ -82,10 +82,10 @@ openclaw plugins install @opik/opik-openclaw
### Prometheus Avatar
为你的 OpenClaw 智能体添加 Live2D 头像，支持实时唇形同步、情绪表情和文本转语音。包含用于 AI 资产生成的创作者工具，以及一键部署到 Prometheus Marketplace 的能力。目前处于 alpha 阶段。
为你的 OpenClaw 智能体配备 Live2D 头像，支持实时口型同步、情绪表情和文本转语音。包含用于 AI 资产生成的创作者工具，并可一键部署到 Prometheus Marketplace。目前处于 alpha 阶段。
- **npm:** `@prometheusavatar/openclaw-plugin`
- **仓库:** [github.com/myths-labs/prometheus-avatar](https://github.com/myths-labs/prometheus-avatar)
- **npm：** `@prometheusavatar/openclaw-plugin`
- **仓库：** [github.com/myths-labs/prometheus-avatar](https://github.com/myths-labs/prometheus-avatar)
```bash
openclaw plugins install @prometheusavatar/openclaw-plugin
@ -93,12 +93,12 @@ openclaw plugins install @prometheusavatar/openclaw-plugin
### QQbot
通过 QQ Bot API 将 OpenClaw 连接到 QQ。支持私聊、群提及、频道消息，以及包括语音、图片、视频和文件在内的富媒体。
通过 QQ Bot API 将 OpenClaw 连接到 QQ。支持私聊、群组提及、频道消息，以及语音、图片、视频和文件等富媒体。
当前 OpenClaw 版本内置 QQ Bot。正常安装请使用 [QQ Bot](/zh-CN/channels/qqbot) 中的内置设置；仅当你明确需要 Tencent 维护的独立包时，才安装此外部插件。
当前 OpenClaw 版本已内置 QQ Bot。常规安装请使用 [QQ Bot](/zh-CN/channels/qqbot) 中的内置设置；仅当你明确想要 Tencent 维护的独立软件包时，才安装此外部插件。
- **npm:** `@tencent-connect/openclaw-qqbot`
- **仓库:** [github.com/tencent-connect/openclaw-qqbot](https://github.com/tencent-connect/openclaw-qqbot)
- **npm：** `@tencent-connect/openclaw-qqbot`
- **仓库：** [github.com/tencent-connect/openclaw-qqbot](https://github.com/tencent-connect/openclaw-qqbot)
```bash
openclaw plugins install @tencent-connect/openclaw-qqbot
@ -106,10 +106,10 @@ openclaw plugins install @tencent-connect/openclaw-qqbot
### wecom
Tencent WeCom 团队为 OpenClaw 提供的 WeCom 渠道插件。它由 WeCom Bot WebSocket 持久连接驱动，支持私信与群聊、流式回复、主动消息、图片/文件处理、Markdown 格式化、内置访问控制，以及文档/会议/消息 Skills。
Tencent WeCom 团队为 OpenClaw 提供的 WeCom 渠道插件。它由 WeCom Bot WebSocket 持久连接驱动，支持私信和群聊、流式回复、主动消息、图片/文件处理、Markdown 格式化、内置访问控制，以及文档/会议/消息 Skills。
- **npm:** `@wecom/wecom-openclaw-plugin`
- **仓库:** [github.com/WecomTeam/wecom-openclaw-plugin](https://github.com/WecomTeam/wecom-openclaw-plugin)
- **npm：** `@wecom/wecom-openclaw-plugin`
- **仓库：** [github.com/WecomTeam/wecom-openclaw-plugin](https://github.com/WecomTeam/wecom-openclaw-plugin)
```bash
openclaw plugins install @wecom/wecom-openclaw-plugin
@ -117,10 +117,10 @@ openclaw plugins install @wecom/wecom-openclaw-plugin
### 腾讯元宝
Tencent 腾讯元宝团队为 OpenClaw 提供的腾讯元宝渠道插件。它由 WebSocket 持久连接驱动，支持私信与群聊、流式回复、主动消息、图片/文件/音频/视频处理、Markdown 格式化、内置访问控制，以及斜杠菜单。
腾讯元宝团队为 OpenClaw 提供的腾讯元宝渠道插件。它由 WebSocket 持久连接驱动，支持私信和群聊、流式回复、主动消息、图片/文件/音频/视频处理、Markdown 格式化、内置访问控制，以及斜杠菜单。
- **npm:** `openclaw-plugin-yuanbao`
- **仓库:** [github.com/YuanbaoTeam/yuanbao-openclaw-plugin](https://github.com/YuanbaoTeam/yuanbao-openclaw-plugin)
- **npm：** `openclaw-plugin-yuanbao`
- **仓库：** [github.com/YuanbaoTeam/yuanbao-openclaw-plugin](https://github.com/YuanbaoTeam/yuanbao-openclaw-plugin)
```bash
openclaw plugins install openclaw-plugin-yuanbao
@ -132,23 +132,21 @@ openclaw plugins install openclaw-plugin-yuanbao
<Steps>
<Step title="发布到 ClawHub 或 npm">
你的插件必须能通过 `openclaw plugins install \<package-name\>` 安装。
除非你确实需要仅通过 npm 分发，否则请发布到 [ClawHub](/zh-CN/tools/clawhub)。
完整指南请参阅 [构建插件](/zh-CN/plugins/building-plugins)。
你的插件必须能够通过 `openclaw plugins install \<package-name\>` 安装。
除非你明确需要仅通过 npm 分发，否则请发布到 [ClawHub](/zh-CN/tools/clawhub)。
完整指南请参见 [构建插件](/zh-CN/plugins/building-plugins)。
</Step>
<Step title="托管在 GitHub 上">
源代码必须位于公开仓库中，并包含设置文档和 issue
跟踪器。
源代码必须位于公共仓库中，并包含设置文档和问题跟踪器。
</Step>
<Step title="仅将文档 PR 用于源文档变更">
你不需要仅为了让插件可被发现而提交文档 PR。请改为将其发布到
ClawHub。
你不需要仅为了让插件可被发现而提交文档 PR。请改为将其发布到 ClawHub。
仅当 OpenClaw 的源文档需要实际内容变更时，才提交文档 PR，例如修正安装指导，或添加属于主文档集的跨仓库文档。
仅当 OpenClaw 的源文档确实需要内容变更时才打开文档 PR，例如更正安装指导，或添加属于主文档集的跨仓库文档。
</Step>
</Steps>
@ -157,15 +155,15 @@ openclaw plugins install openclaw-plugin-yuanbao
| 要求 | 原因 |
| --------------------------- | --------------------------------------------- |
| 发布在 ClawHub 或 npm 上 | 用户需要 `openclaw plugins install` 能正常工作 |
| 公开 GitHub 仓库 | 源码审查、issue 跟踪、透明度 |
| 发布在 ClawHub 或 npm | 用户需要 `openclaw plugins install` 能正常工作 |
| 公共 GitHub 仓库 | 源代码审查、问题跟踪、透明度 |
| 设置和使用文档 | 用户需要知道如何配置它 |
| 活跃维护 | 近期有更新或能响应 issue 处理 |
| 积极维护 | 近期更新或及时响应问题处理 |
低投入封装、所有权不清或无人维护的包可能会被拒绝。
低投入封装、所有权不清晰或无人维护的软件包可能会被拒绝。
## 相关内容
- [安装和配置插件](/zh-CN/tools/plugin) — 如何安装任意插件
- [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件
- [插件清单](/zh-CN/plugins/manifest) — 清单 schema
- [插件清单](/zh-CN/plugins/manifest) — 清单架构

172
docs/zh-CN/plugins/manage-plugins.md Normal file
View File

@ -0,0 +1,172 @@
---
read_when:
- 你想查看快速的插件安装、列出、更新或卸载示例
- 你想在 ClawHub 和 npm 插件分发之间做选择
- 你正在发布一个插件包
sidebarTitle: Manage plugins
summary: 用于安装、列出、卸载、更新和发布 OpenClaw 插件的快速示例
title: 管理插件
x-i18n:
generated_at: "2026-05-02T19:10:39Z"
model: gpt-5.5
provider: openai
source_hash: bd40c0e9f57c38bf65d68855cdb36919bc926a9808ef09aad89ed32e0fc0f060
source_path: plugins/manage-plugins.md
workflow: 16
---
大多数插件工作流只需几个命令：搜索、安装、重启 Gateway 网关、
验证，并在你不再需要该插件时卸载。
## 列出插件
```bash
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
```
对脚本使用 `--json`。当插件包声明 `dependencies` 或
`optionalDependencies` 时，它会包含注册表诊断信息以及每个插件的静态
`dependencyStatus`。
```bash
openclaw plugins list --json \
| jq '.plugins[] | {id, enabled, format, source, dependencyStatus}'
```
`plugins list` 是冷库存检查。它显示 OpenClaw 可以从配置、清单和插件注册表中发现什么；它并不证明已经运行中的 Gateway 网关进程导入了插件运行时。
## 安装插件
```bash
# Search ClawHub for plugin packages.
openclaw plugins search "calendar"
# Bare package specs try ClawHub first, then npm fallback.
openclaw plugins install <package>
# Force one source.
openclaw plugins install clawhub:<package>
openclaw plugins install npm:<package>
# Install a specific version or dist-tag.
openclaw plugins install clawhub:<package>@1.2.3
openclaw plugins install clawhub:<package>@beta
openclaw plugins install npm:@scope/openclaw-plugin@1.2.3
openclaw plugins install npm:@openclaw/codex@beta
# Install from git or a local development checkout.
openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin
```
安装插件代码后，重启为你的渠道提供服务的 Gateway 网关：
```bash
openclaw gateway restart
openclaw plugins inspect <plugin-id> --runtime --json
```
当你需要证明插件注册了运行时表面（例如工具、钩子、服务、Gateway 网关方法或插件拥有的 CLI 命令）时，请使用 `inspect --runtime`。
## 更新插件
```bash
openclaw plugins update <plugin-id>
openclaw plugins update <npm-package-or-spec>
openclaw plugins update --all
```
如果插件是从 npm dist-tag（例如 `@beta`）安装的，后续
`update <plugin-id>` 调用会复用已记录的标签。传入显式 npm 规范会将跟踪的安装切换到该规范，用于未来更新。
```bash
openclaw plugins update @scope/openclaw-plugin@beta
openclaw plugins update @scope/openclaw-plugin
```
当插件之前固定到精确版本或标签时，第二个命令会将插件移回注册表的默认发布线。
## 卸载插件
```bash
openclaw plugins uninstall <plugin-id> --dry-run
openclaw plugins uninstall <plugin-id>
openclaw plugins uninstall <plugin-id> --keep-files
openclaw gateway restart
```
卸载会移除该插件的配置项、插件索引记录、允许/拒绝列表条目，以及适用时的链接加载路径。除非传入 `--keep-files`，否则会移除托管安装目录。
## 发布插件
你可以将外部插件发布到 [ClawHub](https://clawhub.ai)、npmjs.com，或二者都发布。
### 发布到 ClawHub
ClawHub 是 OpenClaw 插件的主要公共发现表面。它在安装前为用户提供可搜索的元数据、版本历史记录和注册表扫描结果。
```bash
npm i -g clawhub
clawhub login
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
clawhub package publish your-org/your-plugin@v1.0.0
```
用户使用以下命令从 ClawHub 安装：
```bash
openclaw plugins install clawhub:<package>
openclaw plugins install <package>
```
裸格式仍会先检查 ClawHub。
### 发布到 npmjs.com
原生 npm 插件必须包含插件清单和 `package.json` OpenClaw
入口点元数据。
```json package.json
{
"name": "@acme/openclaw-plugin",
"version": "1.0.0",
"type": "module",
"openclaw": {
"extensions": ["./dist/index.js"]
}
}
```
```bash
npm publish --access public
```
用户使用以下命令安装仅 npm 可用的插件：
```bash
openclaw plugins install npm:@acme/openclaw-plugin
openclaw plugins install npm:@acme/openclaw-plugin@beta
openclaw plugins install npm:@acme/openclaw-plugin@1.0.0
```
如果同一个包也可在 ClawHub 上获得，`npm:` 会跳过 ClawHub 查找并强制使用 npm 解析。
## 来源选择
- **ClawHub**：当你想要 OpenClaw 原生发现、扫描摘要、版本和安装提示时使用。
- **npmjs.com**：当你已经发布 JavaScript 包，或需要 npm dist-tags/私有注册表工作流时使用。
- **Git**：当你想直接从分支、标签或提交安装时使用。
- **本地路径**：当你正在同一台机器上开发或测试插件时使用。
## 相关
- [插件](/zh-CN/tools/plugin) - 概览和故障排除
- [`openclaw plugins`](/zh-CN/cli/plugins) - 完整 CLI 参考
- [ClawHub](/zh-CN/tools/clawhub) - 发布和注册表操作
- [构建插件](/zh-CN/plugins/building-plugins) - 创建插件包
- [插件清单](/zh-CN/plugins/manifest) - 清单和包元数据

194
docs/zh-CN/plugins/sdk-setup.md
View File

@ -1,21 +1,21 @@
---
read_when:
- 你正在为插件添加设置向导
- 你正在向插件添加设置向导
- 你需要理解 setup-entry.ts 与 index.ts 的区别
- 你正在定义插件配置模式或 package.json 中的 openclaw 元数据
- 你正在定义插件配置 schema 或 package.json openclaw 元数据
sidebarTitle: Setup and config
summary: 设置向导、setup-entry.ts、配置 schema 和 package.json 元数据
summary: 设置向导、setup-entry.ts、配置架构和 package.json 元数据
title: 插件设置和配置
x-i18n:
generated_at: "2026-05-02T15:20:32Z"
generated_at: "2026-05-02T19:10:44Z"
model: gpt-5.5
provider: openai
source_hash: 3975be167ef48e4840fa1abc2a0412f0fc5ab569898742ebc11a1c52f89871c9
source_hash: 0a89e113952b1809bc19b0535d0895b1f0e13ee7c57446a9f27817c03a8e6000
source_path: plugins/sdk-setup.md
workflow: 16
---
插件打包（`package.json` 元数据）、清单（`openclaw.plugin.json`）、设置条目和配置架构的参考。
打包插件（`package.json` 元数据）、清单（`openclaw.plugin.json`）、设置入口和配置 schema 的参考。
<Tip>
**想看演练？** 操作指南会结合上下文介绍打包：[渠道插件](/zh-CN/plugins/sdk-channel-plugins#step-1-package-and-manifest) 和 [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-1-package-and-manifest)。
@ -23,7 +23,7 @@ x-i18n:
## 包元数据
你的 `package.json` 需要一个 `openclaw` 字段，用来告诉插件系统你的插件提供什么：
你的 `package.json` 需要一个 `openclaw` 字段，用来告诉插件系统你的插件提供了什么：
<Tabs>
<Tab title="Channel plugin">
@ -76,7 +76,7 @@ x-i18n:
入口点文件（相对于包根目录）。
</ParamField>
<ParamField path="setupEntry" type="string">
轻量级、仅用于设置的入口（可选）。
轻量的仅设置入口（可选）。
</ParamField>
<ParamField path="channel" type="object">
用于设置、选择器、快速开始和 Status 界面的渠道目录元数据。
@ -93,29 +93,29 @@ x-i18n:
### `openclaw.channel`
`openclaw.channel` 是廉价的包元数据，用于在运行时加载前提供渠道设备发现和设置界面。
`openclaw.channel` 是用于在运行时加载前进行渠道发现和设置界面的低成本包元数据。
| 字段 | 类型 | 含义 |
| -------------------------------------- | ---------- | ----------------------------------------------------------------------------- |
| `id` | `string` | 规范渠道 ID。 |
| `label` | `string` | 主要渠道标签。 |
| `selectionLabel` | `string` | 当需要不同于 `label` 时使用的选择器/设置标签。 |
| `detailLabel` | `string` | 用于更丰富的渠道目录和 Status 界面的次级详情标签。 |
| `docsPath` | `string` | 用于设置和选择链接的文档路径。 |
| `docsLabel` | `string` | 当需要不同于渠道 ID 时，用于文档链接的覆盖标签。 |
| `blurb` | `string` | 简短的新手引导/目录描述。 |
| `order` | `number` | 渠道目录中的排序顺序。 |
| `aliases` | `string[]` | 用于渠道选择的额外查找别名。 |
| `preferOver` | `string[]` | 此渠道应优先于其上的低优先级插件/渠道 ID。 |
| `systemImage` | `string` | 用于渠道 UI 目录的可选图标/系统图像名称。 |
| `selectionDocsPrefix` | `string` | 选择界面中文档链接前的前缀文本。 |
| `selectionDocsOmitLabel` | `boolean` | 在选择文案中直接显示文档路径，而不是带标签的文档链接。 |
| `selectionExtras` | `string[]` | 附加到选择文案中的额外短字符串。 |
| `markdownCapable` | `boolean` | 将渠道标记为支持 Markdown，以用于出站格式化决策。 |
| `exposure` | `object` | 控制渠道在设置、已配置列表和文档界面中的可见性。 |
| `quickstartAllowFrom` | `boolean` | 让此渠道加入标准快速开始 `allowFrom` 设置流程。 |
| `forceAccountBinding` | `boolean` | 即使只有一个账号，也要求显式绑定账号。 |
| `preferSessionLookupForAnnounceTarget` | `boolean` | 为此渠道解析公告目标时优先使用会话查找。 |
| `id` | `string` | 规范渠道 ID。 |
| `label` | `string` | 主渠道标签。 |
| `selectionLabel` | `string` | 当需要不同于 `label` 时使用的选择器/设置标签。 |
| `detailLabel` | `string` | 用于更丰富渠道目录和 Status 界面的次要详情标签。 |
| `docsPath` | `string` | 用于设置和选择链接的文档路径。 |
| `docsLabel` | `string` | 当需要不同于渠道 ID 时，用于文档链接的覆盖标签。 |
| `blurb` | `string` | 简短的新手引导/目录描述。 |
| `order` | `number` | 渠道目录中的排序顺序。 |
| `aliases` | `string[]` | 用于渠道选择的额外查找别名。 |
| `preferOver` | `string[]` | 此渠道应优先于的较低优先级插件/渠道 ID。 |
| `systemImage` | `string` | 用于渠道 UI 目录的可选图标/系统图像名称。 |
| `selectionDocsPrefix` | `string` | 选择界面中文档链接前的前缀文本。 |
| `selectionDocsOmitLabel` | `boolean` | 在选择文案中直接显示文档路径，而不是带标签的文档链接。 |
| `selectionExtras` | `string[]` | 追加到选择文案中的额外短字符串。 |
| `markdownCapable` | `boolean` | 将该渠道标记为支持 markdown，以用于出站格式化决策。 |
| `exposure` | `object` | 用于设置、已配置列表和文档界面的渠道可见性控制。 |
| `quickstartAllowFrom` | `boolean` | 让此渠道加入标准快速开始 `allowFrom` 设置流程。 |
| `forceAccountBinding` | `boolean` | 即使只存在一个账号，也要求显式绑定账号。 |
| `preferSessionLookupForAnnounceTarget` | `boolean` | 为此渠道解析公告目标时优先使用会话查找。 |
示例：
@ -149,7 +149,7 @@ x-i18n:
`exposure` 支持：
- `configured`：在已配置/Status 风格的列表界面中包含该渠道
- `configured`：在已配置/Status 样式的列表界面中包含该渠道
- `setup`：在交互式设置/配置选择器中包含该渠道
- `docs`：在文档/导航界面中将该渠道标记为面向公众
@ -161,25 +161,25 @@ x-i18n:
`openclaw.install` 是包元数据，不是清单元数据。
| 字段 | 类型 | 含义 |
| ---------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------- |
| `clawhubSpec` | `string` | 用于安装/更新和新手引导按需安装流程的规范 ClawHub 规格。 |
| `npmSpec` | `string` | 用于安装/更新回退流程的规范 npm 规格。 |
| `localPath` | `string` | 本地开发或内置安装路径。 |
| `defaultChoice` | `"clawhub"` \| `"npm"` \| `"local"` | 当有多个来源可用时的首选安装来源。 |
| `minHostVersion` | `string` | 支持的最低 OpenClaw 版本，格式为 `>=x.y.z` 或 `>=x.y.z-prerelease`。 |
| `expectedIntegrity` | `string` | 预期的 npm dist 完整性字符串，通常为 `sha512-...`，用于固定版本安装。 |
| `allowInvalidConfigRecovery` | `boolean` | 允许内置插件重装流程从特定的过期配置故障中恢复。 |
| 字段 | 类型 | 含义 |
| ---------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------- |
| `clawhubSpec` | `string` | 用于安装/更新和新手引导按需安装流程的规范 ClawHub 规范。 |
| `npmSpec` | `string` | 用于安装/更新回退流程的规范 npm 规范。 |
| `localPath` | `string` | 本地开发或内置安装路径。 |
| `defaultChoice` | `"clawhub"` \| `"npm"` \| `"local"` | 当多个来源可用时的首选安装来源。 |
| `minHostVersion` | `string` | 支持的最低 OpenClaw 版本，格式为 `>=x.y.z` 或 `>=x.y.z-prerelease`。 |
| `expectedIntegrity` | `string` | 用于固定安装的预期 npm 分发完整性字符串，通常为 `sha512-...`。 |
| `allowInvalidConfigRecovery` | `boolean` | 允许内置插件重新安装流程从特定的陈旧配置失败中恢复。 |
<AccordionGroup>
<Accordion title="Onboarding behavior">
交互式新手引导也会将 `openclaw.install` 用于按需安装界面。如果你的插件在运行时加载前公开提供商认证选项或渠道设置/目录元数据，新手引导可以显示该选项，提示选择 ClawHub、npm 或本地安装，安装或启用插件，然后继续所选流程。ClawHub 新手引导选项使用 `clawhubSpec`，并且在存在时优先使用；npm 选项需要带有注册表 `npmSpec` 的可信目录元数据；精确版本和 `expectedIntegrity` 是可选的 npm 固定项。如果存在 `expectedIntegrity`，安装/更新流程会对 npm 强制校验它。将“显示什么”的元数据放在 `openclaw.plugin.json` 中，将“如何安装它”的元数据放在 `package.json` 中。
交互式新手引导也会将 `openclaw.install` 用于按需安装界面。如果你的插件在运行时加载前暴露提供商凭证选项或渠道设置/目录元数据，新手引导可以显示该选项，提示选择 ClawHub、npm 或本地安装，安装或启用插件，然后继续所选流程。ClawHub 新手引导选项使用 `clawhubSpec`，并在存在时优先使用；npm 选项需要带有注册表 `npmSpec` 的受信任目录元数据；精确版本和 `expectedIntegrity` 是可选的 npm 固定项。如果存在 `expectedIntegrity`，安装/更新流程会对 npm 强制执行它。将“要显示什么”的元数据放在 `openclaw.plugin.json` 中，将“如何安装它”的元数据放在 `package.json` 中。
</Accordion>
<Accordion title="minHostVersion enforcement">
如果设置了 `minHostVersion`，安装和非内置的清单注册表加载都会强制执行它。较旧的主机会跳过外部插件；无效的版本字符串会被拒绝。内置源码插件会被假定与主机检出版本同版本。
如果设置了 `minHostVersion`，安装和非内置清单注册表加载都会强制执行它。较旧的宿主会跳过外部插件；无效的版本字符串会被拒绝。内置源码插件被假定与宿主检出版本一致。
</Accordion>
<Accordion title="Pinned npm installs">
对于固定版本的 npm 安装，将精确版本保留在 `npmSpec` 中，并添加预期制品完整性：
对于固定的 npm 安装，请在 `npmSpec` 中保留精确版本，并添加预期的构件完整性：
```json
{
@ -195,13 +195,13 @@ x-i18n:
</Accordion>
<Accordion title="allowInvalidConfigRecovery scope">
`allowInvalidConfigRecovery` 不是损坏配置的通用绕过机制。它只用于狭窄的内置插件恢复场景，因此重装/设置可以修复已知的升级遗留问题，例如缺少内置插件路径，或同一插件存在过期的 `channels.<id>` 条目。如果配置因无关原因损坏，安装仍会失败关闭，并提示操作员运行 `openclaw doctor --fix`。
`allowInvalidConfigRecovery` 不是针对损坏配置的通用绕过。它只用于狭窄的内置插件恢复场景，因此重新安装/设置可以修复已知升级遗留问题，例如缺失的内置插件路径，或同一插件的陈旧 `channels.<id>` 条目。如果配置因无关原因损坏，安装仍会安全失败，并提示操作员运行 `openclaw doctor --fix`。
</Accordion>
</AccordionGroup>
### 延迟完整加载
渠道插件可以通过以下方式选择延迟加载：
渠道插件可以通过以下配置选择延迟加载：
```json
{
@ -215,17 +215,17 @@ x-i18n:
}
```
启用后，即使对已经配置的渠道，OpenClaw 在监听前启动阶段也只加载 `setupEntry`。完整入口会在 Gateway 网关开始监听后加载。
启用后，即使对于已配置的渠道，OpenClaw 在预监听启动阶段也只加载 `setupEntry`。完整入口会在 Gateway 网关开始监听后加载。
<Warning>
只有当你的 `setupEntry` 在 Gateway 网关开始监听前注册了它所需的一切（渠道注册、HTTP 路由、Gateway 网关方法）时，才启用延迟加载。如果必需的启动能力由完整入口负责，请保留默认行为。
</Warning>
如果你的设置/完整入口注册 Gateway 网关 RPC 方法，请将它们放在插件特定的前缀下。保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍由核心拥有，并且始终解析到 `operator.admin`。
如果你的设置/完整入口注册 Gateway 网关 RPC 方法，请将它们放在插件专属前缀下。保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍归核心所有，并且始终解析到 `operator.admin`。
## 插件清单
每个原生插件都必须在包根目录提供一个 `openclaw.plugin.json`。OpenClaw 使用它在不执行插件代码的情况下验证配置。
每个原生插件都必须在包根目录附带 `openclaw.plugin.json`。OpenClaw 使用它在不执行插件代码的情况下验证配置。
```json
{
@ -260,7 +260,7 @@ x-i18n:
}
```
即使插件没有配置，也必须提供架构。空架构是有效的：
即使没有配置的插件也必须附带 schema。空 schema 是有效的：
```json
{
@ -272,11 +272,11 @@ x-i18n:
}
```
完整架构参考见 [插件清单](/zh-CN/plugins/manifest)。
完整 schema 参考见 [插件清单](/zh-CN/plugins/manifest)。
## ClawHub 发布
对于插件包，请使用包专用的 ClawHub 命令：
对于插件包，使用包专属的 ClawHub 命令：
```bash
clawhub package publish your-org/your-plugin --dry-run
@ -284,12 +284,12 @@ clawhub package publish your-org/your-plugin
```
<Note>
旧版仅 Skills 发布别名面向 Skills。插件包应始终使用 `clawhub package publish`。
旧版仅 Skills 发布别名用于 Skills。插件包应始终使用 `clawhub package publish`。
</Note>
## 设置入口
`setup-entry.ts` 文件是 `index.ts` 的轻量替代方案，OpenClaw 会在只需要设置界面（新手引导、配置修复、已禁用渠道检查）时加载它。
`setup-entry.ts` 文件是 `index.ts` 的轻量替代方案，OpenClaw 仅需要设置表面（新手引导、配置修复、已禁用渠道检查）时会加载它。
```typescript
// setup-entry.ts
@ -299,18 +299,18 @@ import { myChannelPlugin } from "./src/channel.js";
export default defineSetupPluginEntry(myChannelPlugin);
```
这避免在设置流程期间加载繁重的运行时代码（加密库、CLI 注册、后台服务）。
这样可以避免在设置流程中加载较重的运行时代码（加密库、CLI 注册、后台服务）。
在 sidecar 模块中保留设置安全导出的内置工作区渠道，可以使用来自 `openclaw/plugin-sdk/channel-entry-contract` 的 `defineBundledChannelSetupEntry(...)`，而不是 `defineSetupPluginEntry(...)`。该内置契约还支持可选的 `runtime` 导出，因此设置时的运行时接线可以保持轻量且明确。
将设置安全导出保存在旁路模块中的内置工作区渠道，可以使用来自 `openclaw/plugin-sdk/channel-entry-contract` 的 `defineBundledChannelSetupEntry(...)`，而不是 `defineSetupPluginEntry(...)`。该内置契约还支持可选的 `runtime` 导出，因此设置时的运行时接线可以保持轻量且显式。
<AccordionGroup>
<Accordion title="When OpenClaw uses setupEntry instead of the full entry">
- 渠道已禁用，但需要设置/新手引导界面。
- 渠道已启用，但未配置。
<Accordion title="OpenClaw 何时使用 setupEntry 而不是完整入口">
- 渠道已禁用，但需要设置/新手引导表面。
- 渠道已启用，但尚未配置。
- 已启用延迟加载（`deferConfiguredChannelFullLoadUntilAfterListen`）。
</Accordion>
<Accordion title="What setupEntry must register">
<Accordion title="setupEntry 必须注册什么">
- 渠道插件对象（通过 `defineSetupPluginEntry`）。
- Gateway 网关监听前所需的任何 HTTP 路由。
- 启动期间所需的任何 Gateway 网关方法。
@ -318,18 +318,18 @@ export default defineSetupPluginEntry(myChannelPlugin);
这些启动 Gateway 网关方法仍应避免使用保留的核心管理命名空间，例如 `config.*` 或 `update.*`。
</Accordion>
<Accordion title="What setupEntry should NOT include">
<Accordion title="setupEntry 不应包含什么">
- CLI 注册。
- 后台服务。
- 繁重的运行时导入（加密、SDK）。
- 仅在启动后需要的 Gateway 网关方法。
- 较重的运行时导入（加密、SDK）。
- 仅在启动后才需要的 Gateway 网关方法。
</Accordion>
</AccordionGroup>
### 精简设置辅助导入
### 窄范围设置辅助导入
对于热路径的仅设置流程，如果你只需要设置界面的一部分，请优先使用精简的设置辅助接口，而不是更宽泛的 `plugin-sdk/setup` 汇总入口：
对于热路径的仅设置路径，如果你只需要设置表面的一部分，请优先使用窄范围设置辅助接缝，而不是更宽泛的 `plugin-sdk/setup` 总入口：
| 导入路径 | 用途 | 关键导出 |
| ---------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -337,22 +337,22 @@ export default defineSetupPluginEntry(myChannelPlugin);
| `plugin-sdk/setup-adapter-runtime` | 感知环境的账号设置适配器 | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | 设置/安装 CLI/归档/文档辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
当你需要完整的共享设置工具箱，包括 `moveSingleAccountChannelSectionToDefaultAccount(...)` 等配置补丁辅助工具时，请使用更宽泛的 `plugin-sdk/setup` 接口。
当你想要完整的共享设置工具箱（包括 `moveSingleAccountChannelSectionToDefaultAccount(...)` 等配置补丁辅助工具）时，请使用更宽泛的 `plugin-sdk/setup` 接缝。
设置补丁适配器在导入时保持热路径安全。它们内置的单账号提升契约界面查找是惰性的，因此导入 `plugin-sdk/setup-runtime` 不会在适配器实际使用前提前加载内置契约界面发现逻辑。
设置补丁适配器在导入时保持热路径安全。其内置单账号提升契约表面查找是惰性的，因此导入 `plugin-sdk/setup-runtime` 不会在适配器实际使用前急切加载内置契约表面发现。
### 渠道拥有的单账号提升
当渠道从单账号顶层配置升级到 `channels.<id>.accounts.*` 时，默认共享行为是将被提升的账号作用域值移动到 `accounts.default`。
当某个渠道从单账号顶层配置升级到 `channels.<id>.accounts.*` 时，默认共享行为会将提升后的账号范围值移动到 `accounts.default`。
内置渠道可以通过其设置契约界面缩小或覆盖该提升行为：
内置渠道可以通过它们的设置契约表面缩小或覆盖该提升：
- `singleAccountKeysToMove`：应移动到被提升账号中的额外顶层键
- `namedAccountPromotionKeys`：当命名账号已存在时，只有这些键会移动到被提升的账号；共享策略/投递键保留在渠道根级
- `resolveSingleAccountPromotionTarget(...)`：选择哪个现有账号接收被提升的值
- `singleAccountKeysToMove`：应移动到提升账号中的额外顶层键
- `namedAccountPromotionKeys`：当具名账号已存在时，只有这些键会移动到提升账号中；共享策略/投递键保留在渠道根部
- `resolveSingleAccountPromotionTarget(...)`：选择哪个现有账号接收提升值
<Note>
Matrix 是当前的内置示例。如果已经恰好存在一个命名 Matrix 账号，或者 `defaultAccount` 指向现有的非规范键（例如 `Ops`），提升会保留该账号，而不是创建新的 `accounts.default` 条目。
Matrix 是当前的内置示例。如果已经恰好存在一个具名 Matrix 账号，或者如果 `defaultAccount` 指向 `Ops` 等现有非规范键，则提升会保留该账号，而不是创建新的 `accounts.default` 条目。
</Note>
## 配置架构
@ -373,9 +373,9 @@ Matrix 是当前的内置示例。如果已经恰好存在一个命名 Matrix
}
```
你的插件会在注册期间以 `api.pluginConfig` 的形式接收此配置。
你的插件会在注册期间以 `api.pluginConfig` 接收此配置。
对于特定于渠道的配置，请改用渠道配置部分：
对于渠道特定配置，请改用渠道配置部分：
```json5
{
@ -390,7 +390,7 @@ Matrix 是当前的内置示例。如果已经恰好存在一个命名 Matrix
### 构建渠道配置架构
使用 `buildChannelConfigSchema` 将 Zod 架构转换为插件拥有的配置产物所使用的 `ChannelConfigSchema` 包装器：
使用 `buildChannelConfigSchema` 将 Zod 架构转换为插件拥有的配置工件使用的 `ChannelConfigSchema` 包装器：
```typescript
import { z } from "zod";
@ -420,7 +420,7 @@ const configSchema = buildJsonChannelConfigSchema(
);
```
对于第三方插件，冷路径契约仍然是插件清单：将生成的 JSON Schema 镜像到 `openclaw.plugin.json#channelConfigs`，这样配置架构、设置和 UI 界面无需加载运行时代码即可检查 `channels.<id>`。
对于第三方插件，冷路径契约仍然是插件清单：将生成的 JSON Schema 镜像到 `openclaw.plugin.json#channelConfigs`，这样配置架构、设置和 UI 表面无需加载运行时代码即可检查 `channels.<id>`。
## 设置向导
@ -460,14 +460,14 @@ const setupWizard: ChannelSetupWizard = {
`ChannelSetupWizard` 类型支持 `credentials`、`textInputs`、`dmPolicy`、`allowFrom`、`groupAccess`、`prepare`、`finalize` 等。完整示例请参阅内置插件包（例如 Discord 插件的 `src/channel.setup.ts`）。
<AccordionGroup>
<Accordion title="Shared allowFrom prompts">
<Accordion title="共享 allowFrom 提示">
对于只需要标准 `note -> prompt -> parse -> merge -> patch` 流程的私信允许列表提示，请优先使用来自 `openclaw/plugin-sdk/setup` 的共享设置辅助工具：`createPromptParsedAllowFromForAccount(...)`、`createTopLevelChannelParsedAllowFromPrompt(...)` 和 `createNestedChannelParsedAllowFromPrompt(...)`。
</Accordion>
<Accordion title="Standard channel setup status">
对于仅因标签、分数和可选额外行而变化的渠道设置 Status 块，请优先使用来自 `openclaw/plugin-sdk/setup` 的 `createStandardChannelSetupStatus(...)`，而不是在每个插件中手写相同的 `status` 对象。
<Accordion title="标准渠道设置状态">
对于仅因标签、分数和可选额外行而不同的渠道设置状态块，请优先使用来自 `openclaw/plugin-sdk/setup` 的 `createStandardChannelSetupStatus(...)`，而不是在每个插件中手写相同的 `status` 对象。
</Accordion>
<Accordion title="Optional channel setup surface">
对于只应在特定上下文中出现的可选设置界面，请使用来自 `openclaw/plugin-sdk/channel-setup` 的 `createOptionalChannelSetupSurface`：
<Accordion title="可选渠道设置表面">
对于只应在特定上下文中显示的可选设置表面，请使用来自 `openclaw/plugin-sdk/channel-setup` 的 `createOptionalChannelSetupSurface`：
```typescript
import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup";
@ -481,17 +481,17 @@ const setupWizard: ChannelSetupWizard = {
// Returns { setupAdapter, setupWizard }
```
当你只需要该可选安装界面的一半时，`plugin-sdk/channel-setup` 还公开了更底层的 `createOptionalChannelSetupAdapter(...)` 和 `createOptionalChannelSetupWizard(...)` 构建器。
当你只需要该可选安装表面的一半时，`plugin-sdk/channel-setup` 还公开了更底层的 `createOptionalChannelSetupAdapter(...)` 和 `createOptionalChannelSetupWizard(...)` 构建器。
生成的可选适配器/向导会对真实配置写入失败关闭。它们在 `validateInput`、`applyAccountConfig` 和 `finalize` 中复用同一条需要安装的消息，并在设置了 `docsPath` 时追加文档链接。
生成的可选适配器/向导会对真实配置写入采取失败关闭策略。它们在 `validateInput`、`applyAccountConfig` 和 `finalize` 中复用同一条需要安装的消息，并在设置了 `docsPath` 时追加文档链接。
</Accordion>
<Accordion title="Binary-backed setup helpers">
对于由二进制文件支撑的设置 UI，请优先使用共享的委托辅助工具，而不是将相同的二进制/Status 胶水代码复制到每个渠道中：
<Accordion title="二进制支持的设置辅助工具">
对于二进制支持的设置 UI，请优先使用共享委托辅助工具，而不是将相同的二进制/状态粘合代码复制到每个渠道中：
- `createDetectedBinaryStatus(...)` 用于仅因标签、提示、分数和二进制检测而变化的 Status 块
- `createCliPathTextInput(...)` 用于由路径支撑的文本输入
- 当 `setupEntry` 需要惰性转发到更重的完整向导时，使用 `createDelegatedSetupWizardStatusResolvers(...)`、`createDelegatedPrepare(...)`、`createDelegatedFinalize(...)` 和 `createDelegatedResolveConfigured(...)`
- `createDetectedBinaryStatus(...)` 用于只因标签、提示、分数和二进制检测而变化的状态块
- `createCliPathTextInput(...)` 用于路径支持的文本输入
- 当 `setupEntry` 需要惰性转发到较重的完整向导时，使用 `createDelegatedSetupWizardStatusResolvers(...)`、`createDelegatedPrepare(...)`、`createDelegatedFinalize(...)` 和 `createDelegatedResolveConfigured(...)`
- 当 `setupEntry` 只需要委托 `textInputs[*].shouldPrompt` 决策时，使用 `createDelegatedTextInputShouldPrompt(...)`
</Accordion>
@ -502,21 +502,21 @@ const setupWizard: ChannelSetupWizard = {
**外部插件：**发布到 [ClawHub](/zh-CN/tools/clawhub)，然后安装：
<Tabs>
<Tab title="Auto (ClawHub then npm)">
<Tab title="npm">
```bash
openclaw plugins install @myorg/openclaw-my-plugin
```
OpenClaw 会先尝试 ClawHub，并在失败时自动回退到 npm。
在启动切换期间，裸包规格会从 npm 安装。
</Tab>
<Tab title="ClawHub only">
<Tab title="仅 ClawHub">
```bash
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
```
</Tab>
<Tab title="npm package spec">
当包尚未迁移到 ClawHub，或者你在迁移期间需要直接的 npm 安装路径时，请使用 npm：
<Tab title="npm 包规格">
当某个包尚未迁移到 ClawHub，或你在迁移期间需要直接的 npm 安装路径时，请使用 npm：
```bash
openclaw plugins install npm:@myorg/openclaw-my-plugin
@ -525,7 +525,7 @@ const setupWizard: ChannelSetupWizard = {
</Tab>
</Tabs>
**仓库内插件：**放在内置插件工作区树下，它们会在构建期间自动发现。
**仓库内插件：** 放在内置插件工作区树下，它们会在构建期间自动被发现。
**用户可以安装：**
@ -534,17 +534,17 @@ openclaw plugins install <package-name>
```
<Info>
对于来自 npm 的安装，`openclaw plugins install` 会在禁用生命周期脚本的情况下，将包安装到 `~/.openclaw/npm` 下。请保持插件依赖树为纯 JS/TS，并避免使用需要 `postinstall` 构建的包。
对于来自 npm 的安装，`openclaw plugins install` 会在禁用生命周期脚本的情况下把包安装到 `~/.openclaw/npm` 下。保持插件依赖树为纯 JS/TS，并避免使用需要 `postinstall` 构建的包。
</Info>
<Note>
Gateway 网关启动不会安装插件依赖项。npm/git/ClawHub 安装流程负责依赖收敛；本地插件必须已经安装好自己的依赖项。
Gateway 网关启动不会安装插件依赖。npm/git/ClawHub 安装流程负责依赖收敛；本地插件必须已经安装好自身依赖。
</Note>
内置包元数据是显式的，而不是在 Gateway 网关启动时从构建后的 JavaScript 推断出来的。运行时依赖项应放在拥有它们的插件包中；打包版 OpenClaw 启动流程绝不会修复或镜像插件依赖项。
内置包元数据是显式的，不会在 Gateway 网关启动时从已构建的 JavaScript 中推断。运行时依赖应放在拥有它们的插件包中；打包版 OpenClaw 启动时绝不会修复或镜像插件依赖。
## 相关内容
- [构建插件](/zh-CN/plugins/building-plugins) — 分步入门指南
- [插件清单](/zh-CN/plugins/manifest) — 完整清单架构参考
- [构建插件](/zh-CN/plugins/building-plugins) — 分步式入门指南
- [插件清单](/zh-CN/plugins/manifest) — 完整清单 schema 参考
- [SDK 入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 和 `defineChannelPluginEntry`

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

@ -7,10 +7,10 @@ sidebarTitle: ClawHub
summary: ClawHub：OpenClaw Skills 和插件的公共注册表、原生安装流程，以及 clawhub CLI
title: ClawHub
x-i18n:
generated_at: "2026-05-02T18:33:40Z"
generated_at: "2026-05-02T19:10:45Z"
model: gpt-5.5
provider: openai
source_hash: 8d1d08edc482837e206f2c0a1b3f4db2658a6a052974aa3c59365455d1f5bddc
source_hash: cd422cb3e7e53fcc6d2b8a557ebc569debb0b470d5fcf141d90499c03fb4d7b3
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 会话，它会加载新技能。
</Step>
<Step title="发布（可选）">
对于需要注册表认证的工作流（发布、同步、管理），请安装
独立的 `clawhub` CLI：
单独的 `clawhub` CLI：
```bash
npm i -g clawhub
@ -61,8 +61,8 @@ ClawHub 是 **OpenClaw Skills 和插件** 的公共注册表。
openclaw skills update --all
```
原生 `openclaw` 命令会安装到你的活动工作区，并
持久保存来源元数据，以便后续 `update` 调用可以继续使用 ClawHub。
原生 `openclaw` 命令会安装到你的当前工作区，并
持久化来源元数据，以便后续 `update` 调用可以继续使用 ClawHub。
</Tab>
<Tab title="插件">
@ -72,112 +72,107 @@ ClawHub 是 **OpenClaw Skills 和插件** 的公共注册表。
openclaw plugins update --all
```
`plugins search` 会查询 ClawHub 插件目录，并打印可直接安装的
软件包名称。裸 npm 安全插件规范只有在软件包
就绪状态表明该软件包可供 OpenClaw 安装时才使用 ClawHub；否则 OpenClaw
会保留 npm 回退：
`plugins search` 会查询 ClawHub 插件目录并输出可直接安装的
包名称。当你想使用 ClawHub 解析时，请使用 `clawhub:<package>`。
在发布切换期间，裸 npm 安全插件规格会从 npm 安装：
```bash
openclaw plugins install openclaw-codex-app-server
```
如果你希望仅使用 npm 解析而不进行
ClawHub 查询，请使用 `npm:<package>`：
`npm:<package>` 也仅使用 npm，当某个规格可能存在歧义时很有用：
```bash
openclaw plugins install npm:openclaw-codex-app-server
```
插件安装会在归档安装运行之前验证声明的 `pluginApi` 和
`minGatewayVersion` 兼容性，因此
不兼容的主机会提前失败关闭，而不是部分安装
软件包。当某个软件包版本发布 ClawPack 工件时，
插件安装会在归档安装运行前验证声明的 `pluginApi` 和
`minGatewayVersion` 兼容性，因此不兼容的主机会提前失败关闭，
而不是部分安装该包。当某个包版本发布 ClawPack 构件时，
OpenClaw 会优先使用精确上传的 npm-pack `.tgz`，验证 ClawHub
摘要标头和下载的字节，并记录工件类型、npm
integrity、npm shasum、tarball 名称和 ClawPack 摘要元数据，以供后续
更新使用。没有 ClawPack 元数据的旧软件包版本仍使用
旧版软件包归档验证路径。
摘要标头和下载字节，并记录构件类型、npm 完整性、
npm shasum、tarball 名称和 ClawPack 摘要元数据，以供后续
更新使用。没有 ClawPack 元数据的旧包版本仍会使用
旧版包归档验证路径。
</Tab>
</Tabs>
<Note>
`openclaw plugins install clawhub:...` 只接受可安装的插件
系列。如果某个 ClawHub 软件包实际上是 skill，OpenClaw 会停止并
指向 `openclaw skills install <slug>`。
系列。如果某个 ClawHub 包实际是技能，OpenClaw 会停止并
指引你改用 `openclaw skills install <slug>`。
匿名 ClawHub 插件安装也会对私有软件包失败关闭。
匿名 ClawHub 插件安装也会对私有包失败关闭。
社区或其他非官方渠道仍可安装，但 OpenClaw
会发出警告，以便操作员在启用之前审查来源和验证情况。
会发出警告，以便操作员在启用前审查来源和验证结果。
</Note>
## ClawHub 是什么
- OpenClaw Skills 和插件的公共注册表。
- skill 包和元数据的版本化存储。
- 面向搜索、标签和使用信号的发现入口。
- 技能包和元数据的版本化存储。
- 用于搜索、标签和使用信号的发现界面。
典型的 skill 是一个包含以下内容的版本化文件包：
一个典型技能是包含以下内容的版本化文件包：
- 一个包含主要描述和用法的 `SKILL.md` 文件。
- skill 使用的可选配置、脚本或支持文件。
- 一个 `SKILL.md` 文件，包含主要描述和用法。
- 技能使用的可选配置、脚本或支持文件。
- 标签、摘要和安装要求等元数据。
ClawHub 使用元数据来驱动发现，并安全地公开 skill
能力。注册表会跟踪使用信号（星标、下载量）以
ClawHub 使用元数据来支持发现，并安全地暴露技能
能力。注册表会跟踪使用信号（星标、下载量）来
改进排序和可见性。每次发布都会创建新的 semver
版本，并且注册表会保留版本历史，以便用户审计
版本，注册表会保留版本历史，以便用户审计
变更。
## 工作区和 skill 加载
## 工作区和技能加载
独立的 `clawhub` CLI 也会把 Skills 安装到
当前工作目录下的 `./skills`。如果配置了 OpenClaw 工作区，
`clawhub` 会回退到该工作区，除非你覆盖 `--workdir`
（或 `CLAWHUB_WORKDIR`）。OpenClaw 从
`<workspace>/skills` 加载工作区 Skills，并在**下一个**会话中加载它们。
单独的 `clawhub` CLI 也会把技能安装到当前工作目录下的 `./skills`。
如果已配置 OpenClaw 工作区，`clawhub` 会回退到该工作区，
除非你覆盖 `--workdir`（或 `CLAWHUB_WORKDIR`）。OpenClaw 会从
`<workspace>/skills` 加载工作区技能，并在**下一个**会话中加载它们。
如果你已经使用 `~/.openclaw/skills` 或内置 Skills，工作区
Skills 会优先。关于 Skills 如何加载、
共享和受门控控制的更多细节，请参见 [Skills](/zh-CN/tools/skills)。
如果你已经使用 `~/.openclaw/skills` 或内置技能，工作区
技能会优先。有关技能如何加载、共享和门控的更多细节，
请参阅 [Skills](/zh-CN/tools/skills)。
## 服务功能
| 功能 | 说明 |
| 功能 | 说明 |
| ------------------------ | ------------------------------------------------------------------- |
| 公开浏览 | Skills 及其 `SKILL.md` 内容可公开查看。 |
| 搜索 | 由嵌入驱动（向量搜索），不只是关键词。 |
| 版本管理 | Semver、changelog 和标签（包括 `latest`）。 |
| 下载 | 每个版本一个 zip。 |
| 星标和评论 | 社区反馈。 |
| 安全扫描摘要 | 详情页会在安装或下载前显示最新扫描状态。 |
| 扫描器详情页 | VirusTotal、ClawScan 和静态分析结果有深度链接。 |
| 所有者恢复仪表板 | 发布者可以从 `/dashboard` 查看被扫描保留的自有内容。 |
| 所有者请求重新扫描 | 所有者可以请求有限次数的重新扫描，用于误报恢复。 |
| 审核 | 批准和审计。 |
| CLI 友好的 API | 适合自动化和脚本编写。 |
| 公共浏览 | Skills 及其 `SKILL.md` 内容可公开查看。 |
| 搜索 | 由嵌入驱动（向量搜索），而不仅是关键词。 |
| 版本管理 | Semver、变更日志和标签（包括 `latest`）。 |
| 下载 | 每个版本一个 zip。 |
| 星标和评论 | 社区反馈。 |
| 安全扫描摘要 | 详情页面会在安装或下载前显示最新扫描状态。 |
| 扫描器详情页面 | VirusTotal、ClawScan 和静态分析结果有深层链接。 |
| 所有者恢复仪表板 | 发布者可以从 `/dashboard` 查看因扫描保留的自有内容。 |
| 所有者请求重新扫描 | 所有者可以请求有限的重新扫描，以恢复误报。 |
| 审核 | 审批和审计。 |
| CLI 友好 API | 适合自动化和脚本。 |
## 安全和审核
ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
账号必须**至少存在一周**才能发布。这能减缓
ClawHub 默认开放，任何人都可以上传技能，但 GitHub
账号必须**至少注册一周**才能发布。这样可以减缓
滥用，同时不阻止合法贡献者。
<AccordionGroup>
<Accordion title="安全扫描">
ClawHub 会对已发布的 Skills 和插件
发布版本运行自动化安全检查。公开详情页会汇总当前结果，扫描器
行会链接到 VirusTotal、ClawScan 和静态
分析的专用详情页。
ClawHub 会对已发布的技能和插件版本运行自动安全检查。
公共详情页面会汇总当前结果，扫描器行会链接到
VirusTotal、ClawScan 和静态分析的专用详情页面。
被扫描保留或阻止的发布版本可能不会出现在公共目录和
安装入口中，但其所有者仍可在 `/dashboard` 中看到。
被扫描保留或阻止的版本可能无法在公共目录和
安装界面中使用，但其所有者仍可在 `/dashboard` 中看到。
</Accordion>
<Accordion title="举报">
- 任何已登录用户都可以举报 skill。
- 必须提供举报原因，并会被记录。
- 每个用户同一时间最多可以有 20 个活动举报。
- 任何已登录用户都可以举报技能。
- 举报原因是必填项并会被记录。
- 每个用户最多可同时拥有 20 条活跃举报。
- 默认情况下，收到超过 3 个唯一举报的 Skills 会被自动隐藏。
</Accordion>
@ -191,25 +186,24 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
## ClawHub CLI
只有在发布/同步等需要注册表认证的工作流中
才需要它。
你只有在发布/同步等需要注册表认证的工作流中才需要它。
### 全局选项
<ParamField path="--workdir <dir>" type="string">
工作目录。默认值：当前目录；回退到 OpenClaw 工作区。
工作目录。默认：当前目录；回退到 OpenClaw 工作区。
</ParamField>
<ParamField path="--dir <dir>" type="string" default="skills">
Skills 目录，相对于 workdir。
Skills 目录，相对于工作目录。
</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">
禁用提示（非交互式）。
禁用提示（非交互）。
</ParamField>
<ParamField path="-V, --cli-version" type="boolean">
打印 CLI 版本。
@ -218,7 +212,7 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
### 命令
<AccordionGroup>
<Accordion title="认证（登录 / 登出 / whoami）">
<Accordion title="认证（登录 / 退出 / 我是谁）">
```bash
clawhub login # browser flow
clawhub login --token <token>
@ -228,8 +222,8 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
登录选项：
- `--token <token>` — 粘贴 API token。
- `--label <label>` — 为浏览器登录 token 存储的标签（默认：`CLI token`）。
- `--token <token>` — 粘贴 API 令牌。
- `--label <label>` — 为浏览器登录令牌存储的标签（默认：`CLI token`）。
- `--no-browser` — 不打开浏览器（需要 `--token`）。
</Accordion>
@ -238,7 +232,7 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
clawhub search "query"
```
搜索 Skills。对于插件/软件包发现，请使用 `clawhub package explore`。
搜索 Skills。对于插件/包发现，请使用 `clawhub package explore`。
- `--limit <n>` — 最大结果数。
@ -250,15 +244,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>
@ -272,8 +266,8 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
选项：
- `--version <version>` — 安装或更新到特定版本（在 `update` 上仅支持单个 slug）。
- `--force` — 如果文件夹已存在，或本地文件与任何已发布版本都不匹配，则覆盖。
- `--version <version>` — 安装或更新到特定版本（在 `update` 上仅限单个 slug）。
- `--force` — 如果文件夹已存在，或本地文件与任何已发布版本不匹配，则覆盖。
- `clawhub list` 读取 `.clawhub/lock.json`。
</Accordion>
@ -284,10 +278,10 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
选项：
- `--slug <slug>` — skill slug。
- `--slug <slug>` — 技能 slug。
- `--name <name>` — 显示名称。
- `--version <version>` — semver 版本。
- `--changelog <text>` — changelog 文本（可以为空）。
- `--changelog <text>` — 变更日志文本（可为空）。
- `--tags <tags>` — 逗号分隔的标签（默认：`latest`）。
</Accordion>
@ -301,9 +295,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="请求重新扫描">
@ -315,8 +309,8 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
clawhub package rescan <name> --yes --json
```
重新扫描命令需要已登录的所有者 token，并以最新
已发布的 skill 版本或插件发布版本为目标。在非交互式运行中，请传入
重新扫描命令需要已登录的所有者令牌，并以最新
已发布技能版本或插件版本为目标。在非交互运行中，传入
`--yes`。
JSON 响应包含目标类型、名称、版本、重新扫描状态，以及
@ -338,9 +332,9 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
- `--root <dir...>` — 额外扫描根目录。
- `--all` — 不提示，上传所有内容。
- `--dry-run` — 显示将要上传的内容。
- `--bump <type>` — 更新使用的 `patch|minor|major`（默认：`patch`）。
- `--changelog <text>` — 非交互式更新的 changelog。
- `--dry-run` — 显示将上传的内容。
- `--bump <type>` — 更新时使用 `patch|minor|major`（默认：`patch`）。
- `--changelog <text>` — 非交互更新的变更日志。
- `--tags <tags>` — 逗号分隔的标签（默认：`latest`）。
- `--concurrency <n>` — 注册表检查并发数（默认：`4`）。
@ -394,7 +388,8 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
### 插件包元数据
代码插件必须在 `package.json` 中包含必需的 OpenClaw 元数据：
代码插件必须在
`package.json` 中包含所需的 OpenClaw 元数据：
```json
{
@ -416,30 +411,31 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
}
```
已发布的包应随附**构建后的 JavaScript**，并将 `runtimeExtensions` 指向该输出。通过 Git checkout 安装时，如果不存在构建文件，仍可回退到 TypeScript 源码，但构建后的运行时入口可以避免在启动、doctor 和插件加载路径中进行运行时 TypeScript 编译。
已发布的包应附带**已构建的 JavaScript**，并将
`runtimeExtensions` 指向该输出。Git 检出安装在没有已构建文件时仍可回退到 TypeScript 源码，但已构建的运行时入口可避免在启动、doctor 和插件加载路径中进行运行时 TypeScript 编译。
## 版本控制、lockfile 和遥测
## 版本控制、锁文件和遥测
<AccordionGroup>
<Accordion title="版本控制和标签">
- 每次发布都会创建一个新的 **semver** `SkillVersion`。
- 标签（如 `latest`）指向某个版本；移动标签可以让你回滚。
- Changelogs 按版本附加，在同步或发布更新时可以为空。
- 标签（如 `latest`）指向某个版本；移动标签可让你回滚。
- 变更日志按版本附加，在同步或发布更新时可以为空。
</Accordion>
<Accordion title="本地更改与 registry 版本">
更新会使用内容哈希将本地 skill 内容与 registry 版本进行比较。如果本地文件与任何已发布版本都不匹配，CLI 会在覆盖前询问（或在非交互式运行中要求使用 `--force`）。
<Accordion title="本地更改与注册表版本">
更新会使用内容哈希将本地 skill 内容与注册表版本进行比较。如果本地文件与任何已发布版本都不匹配，CLI 会在覆盖前询问（或在非交互式运行中要求使用 `--force`）。
</Accordion>
<Accordion title="同步扫描和回退根目录">
`clawhub sync` 会先扫描你当前的工作目录。如果找不到 skills，它会回退到已知的旧位置（例如 `~/openclaw/skills` 和 `~/.openclaw/skills`）。这是为了在不添加额外标志的情况下找到较早安装的 skills。
`clawhub sync` 会先扫描你的当前工作目录。如果没有找到 skills，它会回退到已知的旧版位置（例如 `~/openclaw/skills` 和 `~/.openclaw/skills`）。这旨在无需额外标志即可找到较旧的 skill 安装。
</Accordion>
<Accordion title="存储和 lockfile">
- 已安装的 skills 会记录在你的工作目录下的 `.clawhub/lock.json` 中。
<Accordion title="存储和锁文件">
- 已安装的 skills 会记录在你工作目录下的 `.clawhub/lock.json` 中。
- 认证令牌存储在 ClawHub CLI 配置文件中（可通过 `CLAWHUB_CONFIG_PATH` 覆盖）。
</Accordion>
<Accordion title="遥测（安装计数）">
当你在登录状态下运行 `clawhub sync` 时，CLI 会发送一个最小快照来计算安装计数。你可以完全禁用此功能：
当你在登录状态下运行 `clawhub sync` 时，CLI 会发送一个最小快照来计算安装计数。你可以完全禁用它：
```bash
export CLAWHUB_DISABLE_TELEMETRY=1
@ -453,7 +449,7 @@ ClawHub 默认开放，任何人都可以上传 Skills，但 GitHub
| 变量 | 作用 |
| ----------------------------- | ----------------------------------------------- |
| `CLAWHUB_SITE` | 覆盖站点 URL。 |
| `CLAWHUB_REGISTRY` | 覆盖 registry API URL。 |
| `CLAWHUB_REGISTRY` | 覆盖注册表 API URL。 |
| `CLAWHUB_CONFIG_PATH` | 覆盖 CLI 存储令牌/配置的位置。 |
| `CLAWHUB_WORKDIR` | 覆盖默认工作目录。 |
| `CLAWHUB_DISABLE_TELEMETRY=1` | 在 `sync` 时禁用遥测。 |

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

@ -2,29 +2,25 @@
read_when:
- 安装或配置插件
- 了解插件发现和加载规则
- 使用兼容 Codex/Claude 的插件包
- 使用与 Codex/Claude 兼容的插件包
sidebarTitle: Install and Configure
summary: 安装、配置和管理 OpenClaw 插件
title: 插件
x-i18n:
generated_at: "2026-05-02T19:02:49Z"
generated_at: "2026-05-02T19:10:36Z"
model: gpt-5.5
provider: openai
source_hash: 378ce95601d5b97a30bc046b8f987d17d0a40c1e48ecb3f66e02a1810b20e027
source_hash: eb4c15f9d38dcd1d3f868a20dc2b703064fc874e8e92505dc039f44df2a42ef9
source_path: tools/plugin.md
workflow: 16
---
插件通过新能力扩展 OpenClaw：渠道、模型提供商、
智能体运行框架、工具、Skills、语音、实时转写、实时
语音、媒体理解、图像生成、视频生成、网页获取、网页
搜索等等。有些插件是 **核心**（随 OpenClaw 一起发布），其他
则是 **外部** 插件。大多数外部插件通过
[ClawHub](/zh-CN/tools/clawhub) 发布和发现。Npm 仍支持直接安装，也会在迁移完成前，
临时支持一组 OpenClaw 所有的插件包。
插件为 OpenClaw 扩展新能力：渠道、模型提供商、智能体 harness、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、Web 获取、Web 搜索等。有些插件是 **core**（随 OpenClaw 一起发布），另一些是 **external**。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。npm 仍支持直接安装，也会在迁移完成前暂时支持一组 OpenClaw 自有插件包。
## 快速开始
如需可直接复制粘贴的安装、列出、卸载、更新和发布示例，请参阅[管理插件](/zh-CN/plugins/manage-plugins)。
<Steps>
<Step title="查看已加载内容">
```bash
@ -65,9 +61,9 @@ x-i18n:
<Step title="聊天原生管理">
在运行中的 Gateway 网关里，仅限所有者使用的 `/plugins enable` 和 `/plugins disable`
会触发 Gateway 网关配置重载器。Gateway 网关会在进程内重新加载插件运行时
暴露面，而新的智能体回合会从刷新后的注册表重建其工具列表。`/plugins install`
会更改插件源代码，因此 Gateway 网关会请求重启，而不是假装当前进程可以
安全地重新加载已导入的模块。
surface，新的智能体轮次会从刷新后的注册表重新构建其工具列表。`/plugins install`
会更改插件源代码，因此 Gateway 网关会请求重启，而不是假装当前进程可以安全地
重新加载已导入的模块。
</Step>
@ -79,14 +75,13 @@ x-i18n:
openclaw <plugin-command> --help
```
当你需要证明已注册的工具、服务、gateway
方法、钩子或插件自有 CLI 命令时，请使用 `--runtime`。普通的 `inspect` 是冷态
manifest/注册表检查，并且会刻意避免导入插件运行时。
当你需要证明已注册的工具、服务、Gateway 网关方法、钩子或插件自有 CLI 命令时，请使用
`--runtime`。普通的 `inspect` 是冷态清单/注册表检查，并且会有意避免导入插件运行时。
</Step>
</Steps>
如果你更偏好聊天原生控制，请启用 `commands.plugins: true` 并使用：
如果你更喜欢聊天原生控制，请启用 `commands.plugins: true` 并使用：
```text
/plugin install clawhub:<package>
@ -95,53 +90,49 @@ x-i18n:
```
安装路径使用与 CLI 相同的解析器：本地路径/归档、显式
`clawhub:<pkg>`、显式 `npm:<pkg>`、显式 `git:<repo>`，或裸包
规格（先查 ClawHub，然后回退到 npm）。
`clawhub:<pkg>`、显式 `npm:<pkg>`、显式 `git:<repo>`，或通过 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` 安装。
使用 `openclaw plugins list --json` 可查看每个可见插件的静态 `dependencyStatus`，
不会导入运行时代码或修复依赖。
有关安装时生命周期，请参阅[插件依赖解析](/zh-CN/plugins/dependency-resolution)。
插件依赖安装只会在显式安装/更新或 Doctor 修复流程中发生。Gateway 网关启动、
配置重载和运行时检查不会运行包管理器或修复依赖树。本地插件必须已经安装其依赖，
而 npm、git 和 ClawHub 插件会安装到 OpenClaw 管理的插件根目录下。
npm 依赖可能会在 OpenClaw 管理的 npm 根目录内被提升；安装/更新会在信任前扫描该托管根目录，
卸载则会通过 npm 移除 npm 管理的包。外部插件和自定义加载路径仍必须通过
`openclaw plugins install` 安装。使用 `openclaw plugins list --json`
可以查看每个可见插件的静态 `dependencyStatus`，无需导入运行时代码或修复依赖。
请参阅[插件依赖解析](/zh-CN/plugins/dependency-resolution)了解安装时生命周期。
源代码检出是 pnpm 工作区。如果你克隆 OpenClaw 来修改内置
插件，请运行 `pnpm install`；随后 OpenClaw 会从
`extensions/<id>` 加载内置插件，因此会直接使用编辑内容和包本地依赖。
普通 npm 根安装适用于打包版 OpenClaw，而不是源代码检出
开发。
源码 checkout 是 pnpm 工作区。如果你克隆 OpenClaw 来修改内置插件，
请运行 `pnpm install`；随后 OpenClaw 会从 `extensions/<id>` 加载内置插件，
因此会直接使用你的编辑和包本地依赖。普通 npm 根安装适用于打包版 OpenClaw，
不适用于源码 checkout 开发。
## 插件类型
OpenClaw 识别两种插件格式：
| 格式 | 工作方式 | 示例 |
| 格式 | 工作方式 | 示例 |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
| **Bundle** | Codex/Claude/Cursor 兼容布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
| **Bundle** | Codex/Claude/Cursor 兼容布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
二者都会显示在 `openclaw plugins list` 下。有关 Bundle 详情，请参阅[插件 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)开始。
@ -149,16 +140,15 @@ OpenClaw 识别两种插件格式：
## 包入口点
原生插件 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`；声明后该文件就是必需的。
存在时，`runtimeExtensions` 必须为每个 `extensions` 条目正好包含一个条目。
列表不匹配会导致安装和插件发现失败，而不是静默回退到源路径。如果你还发布
`openclaw.setupEntry`，请为其构建后的 JavaScript 对等文件使用
`openclaw.runtimeSetupEntry`；声明后该文件为必需。
```json
{
@ -172,19 +162,17 @@ JavaScript 同级文件使用 `openclaw.runtimeSetupEntry`；声明后该文件
## 官方插件
### 迁移期间 OpenClaw 所有的 npm 包
### 迁移期间由 OpenClaw 拥有的 npm 包
ClawHub 是大多数插件的主要分发路径。当前打包版
OpenClaw 发行版已经内置许多官方插件，因此在常规设置中不需要
单独 npm 安装。在每个 OpenClaw 所有的插件都
迁移到 ClawHub 之前，OpenClaw 仍会在 npm 上发布一些 `@openclaw/*` 插件包，
ClawHub 是大多数插件的主要分发路径。当前打包版 OpenClaw 发布已内置许多官方插件，
因此在正常设置中这些插件不需要单独进行 npm 安装。在每个 OpenClaw 自有插件都迁移到
ClawHub 之前，OpenClaw 仍会在 npm 上发布一些 `@openclaw/*` 插件包，
用于较旧/自定义安装和直接 npm 工作流。
如果 npm 将某个 `@openclaw/*` 插件包报告为 deprecated，则该包
版本来自较旧的外部包序列。请使用当前 OpenClaw 中的内置插件
或本地检出，直到发布更新的 npm 包。
如果 npm 报告某个 `@openclaw/*` 插件包已废弃，则该包版本来自较旧的外部包发布线。
请使用当前 OpenClaw 的内置插件或本地 checkout，直到发布更新的 npm 包。
| 插件 | 包 | 文档 |
| 插件 | 包 | 文档 |
| --------------- | -------------------------- | ------------------------------------------ |
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/zh-CN/channels/bluebubbles) |
| Discord | `@openclaw/discord` | [Discord](/zh-CN/channels/discord) |
@ -200,7 +188,7 @@ 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="模型提供商（默认启用）">
@ -213,10 +201,10 @@ OpenClaw 发行版已经内置许多官方插件，因此在常规设置中不
<Accordion title="记忆插件">
- `memory-core` — 内置记忆搜索（默认通过 `plugins.slots.memory`）
- `memory-lancedb` — 基于 LanceDB 的长期记忆，支持自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`）
- `memory-lancedb` — 基于 LanceDB 的长期记忆，支持自动回忆/捕获（设置 `plugins.slots.memory = "memory-lancedb"`）
有关 OpenAI 兼容的 embedding 设置、Ollama 示例、召回限制和故障排除，
请参阅 [Memory LanceDB](/zh-CN/plugins/memory-lancedb)。
请参阅 [Memory LanceDB](/zh-CN/plugins/memory-lancedb)，了解 OpenAI 兼容的
embedding 设置、Ollama 示例、回忆限制和故障排除。
</Accordion>
@ -225,13 +213,13 @@ OpenClaw 发行版已经内置许多官方插件，因此在常规设置中不
</Accordion>
<Accordion title="其他">
- `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` gateway 方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用它）
- `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用）
- `copilot-proxy` — VS Code Copilot Proxy 桥接（默认禁用）
</Accordion>
</AccordionGroup>
在寻找第三方插件？请参阅[社区插件](/zh-CN/plugins/community)。
在找第三方插件？请参阅 [Community Plugins](/zh-CN/plugins/community)。
## 配置
@ -249,98 +237,80 @@ OpenClaw 发行版已经内置许多官方插件，因此在常规设置中不
}
```
| 字段 | 描述 |
| 字段 | 说明 |
| ---------------- | --------------------------------------------------------- |
| `enabled` | 主开关（默认：`true`） |
| `allow` | 插件 allowlist（可选） |
| `deny` | 插件 denylist（可选；deny 优先） |
| `load.paths` | 额外插件文件/目录 |
| `slots` | 独占 slot 选择器（例如 `memory`、`contextEngine`） |
| `entries.\<id\>` | 每插件开关 + 配置 |
| `enabled` | 主开关（默认值：`true`） |
| `allow` | 插件允许列表（可选） |
| `deny` | 插件拒绝列表（可选；deny 优先） |
| `load.paths` | 额外插件文件/目录 |
| `slots` | 独占 slot 选择器（例如 `memory`、`contextEngine`） |
| `entries.\<id\>` | 每插件开关 + 配置 |
`plugins.allow` 是排他的。当它非空时，只有列出的插件可以加载
或暴露工具，即使 `tools.allow` 包含 `"*"` 或某个插件自有
工具名也是如此。如果某个工具 allowlist 引用了插件工具，请将所属插件 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="插件状态：已禁用、缺失与无效">
<Accordion title="Plugin states: disabled vs missing vs invalid">
- **已禁用**：插件存在，但启用规则将其关闭。配置会保留。
- **缺失**：配置引用了设备发现未找到的插件 ID。
- **无效**：插件存在，但其配置与声明的 schema 不匹配。Gateway 网关启动时只会跳过该插件；`openclaw doctor --fix` 可以通过禁用该无效条目并移除其配置载荷来隔离它。
- **无效**：插件存在，但它的配置与声明的 schema 不匹配。Gateway 网关启动时只跳过该插件；`openclaw doctor --fix` 可以通过禁用该插件并移除其配置负载来隔离无效条目。
</Accordion>
## 设备发现和优先级
OpenClaw 按以下顺序扫描插件（第一个匹配项生效）：
OpenClaw 会按以下顺序扫描插件（第一个匹配项生效）：
<Steps>
<Step title="配置路径">
`plugins.load.paths` — 显式文件或目录路径。指向
OpenClaw 自身打包的内置插件目录的路径会被忽略；
运行 `openclaw doctor --fix` 可移除这些过期别名。
<Step title="Config paths">
`plugins.load.paths` — 显式文件或目录路径。指向 OpenClaw 自身打包内置插件目录的路径会被忽略；运行 `openclaw doctor --fix` 可移除这些过时别名。
</Step>
<Step title="工作区插件">
<Step title="Workspace plugins">
`\<workspace\>/.openclaw/<plugin-root>/*.ts` 和 `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`。
</Step>
<Step title="全局插件">
<Step title="Global plugins">
`~/.openclaw/<plugin-root>/*.ts` 和 `~/.openclaw/<plugin-root>/*/index.ts`。
</Step>
<Step title="内置插件">
随 OpenClaw 一起发布。许多默认启用（模型提供商、语音）。
其他插件需要显式启用。
<Step title="Bundled plugins">
随 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` 树解析内置插件。如果内置插件源目录被绑定挂载到匹配的打包源路径上，例如 `/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` 会禁用该插件
- 工作区来源的插件**默认禁用**（必须显式启用）
- 内置插件遵循内建的默认开启集合，除非被覆盖
- 独占 slot 可以强制启用为该 slot 选择的插件
- 某些内置的选择启用插件会在配置命名插件拥有的表面时自动启用，
例如提供商模型引用、渠道配置或 harness
运行时
- 当 `plugins.enabled: false` 处于活动状态时，过期插件配置会保留；
如果你想移除过期 ID，请先重新启用插件，再运行 Doctor 清理
- OpenAI 系列 Codex 路由会保持独立的插件边界：
`openai-codex/*` 属于 OpenAI 插件，而内置 Codex
app-server 插件由 `agentRuntime.id: "codex"` 或旧版
`codex/*` 模型引用选择
- 独占插槽可以强制启用为该插槽选中的插件
- 当配置命名了插件拥有的表面时，某些内置选择加入插件会自动启用，例如提供商模型引用、渠道配置或 harness 运行时
- 当 `plugins.enabled: false` 处于活动状态时，过时的插件配置会保留；如果你想移除过时 ID，请先重新启用插件，再运行 Doctor 清理
- OpenAI 系列 Codex 路由保持独立的插件边界：`openai-codex/*` 属于 OpenAI 插件，而内置 Codex 应用服务器插件由 `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 日志记录并检查插件工具工厂计时行：
如果智能体轮次在准备工具时似乎停滞，请启用 trace 日志，并检查插件工具工厂计时行：
```bash
openclaw config set logging.level trace
@ -353,19 +323,19 @@ openclaw logs --follow
[trace:plugin-tools] factory timings ...
```
摘要会列出总工厂时间和最慢的插件工具工厂，包括插件 ID、声明的工具名称、结果形状，以及该工具是否可选。当单个工厂至少耗时 1 秒，或总插件工具工厂准备耗时至少 5 秒时，慢速行会提升为警告。
摘要会列出总工厂时间和最慢的插件工具工厂，包括插件 ID、声明的工具名称、结果形状，以及该工具是否可选。当单个工厂耗时至少 1 秒，或插件工具工厂准备总耗时至少 5 秒时，慢速行会提升为警告。
OpenClaw 会为相同有效请求上下文下的重复解析缓存成功的插件工具工厂结果。缓存键包含有效运行时配置、工作区、智能体/会话 ID、沙箱策略、浏览器设置、投递上下文、请求者身份和所有权状态，因此依赖这些可信字段的工厂会在上下文变化时重新运行。
OpenClaw 会为具有相同有效请求上下文的重复解析缓存成功的插件工具工厂结果。缓存键包含有效运行时配置、工作区、智能体/会话 ID、沙箱策略、浏览器设置、投递上下文、请求者身份和所有权状态，因此依赖这些可信字段的工厂会在上下文变化时重新运行。
如果某个插件占据了主要耗时，请检查其运行时注册：
如果某个插件主导计时，请检查它的运行时注册：
```bash
openclaw plugins inspect <plugin-id> --runtime --json
```
然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载移到工具执行路径之后，而不是在工具工厂内部执行。
然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载移到工具执行路径之后，而不是在工具工厂中执行。
### 重复的渠道或工具所有权
### 重复渠道或工具所有权
症状：
@ -373,30 +343,22 @@ 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`，
让持久化元数据反映当前安装。
- 在安装、注册表或配置更改后重启 Gateway 网关。
- 运行 `openclaw plugins list --enabled --verbose` 查看每个已启用插件及其来源。
- 对每个可疑插件运行 `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 会保留该请求并报告冲突。为该渠道选择一个所有者，或重命名插件拥有的工具，使运行时表面明确无歧义。
## 插件 slot（独占类别）
## 插件插槽（独占类别）
某些类别是独占的（一次只能有一个处于活动状态）：
@ -411,10 +373,10 @@ openclaw plugins inspect <plugin-id> --runtime --json
}
```
| Slot | 控制内容 | 默认值 |
| 插槽 | 控制内容 | 默认值 |
| --------------- | --------------------- | ------------------- |
| `memory` | 主动记忆插件 | `memory-core` |
| `contextEngine` | 活动上下文引擎 | `legacy`（内置） |
| `memory` | 主动记忆插件 | `memory-core` |
| `contextEngine` | 活动上下文引擎 | `legacy`（内置） |
## CLI 参考
@ -434,7 +396,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 (readiness-gated ClawHub, then npm)
openclaw plugins install <package> # install from npm by default
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
@ -464,35 +426,34 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
内置插件随 OpenClaw 一起发布。许多默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）。其他内置插件仍需要 `openclaw plugins enable <id>`。
内置插件随 OpenClaw 一起发布。许多插件默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）。其他内置插件仍需要 `openclaw plugins enable <id>`。
`--force` 会在原位置覆盖已安装的现有插件或 hook pack。对已跟踪的 npm 插件进行常规升级时，请使用 `openclaw plugins update <id-or-npm-spec>`。它不支持与 `--link` 一起使用，因为 `--link` 会复用源码路径，而不是复制到受管安装目标。
`--force` 会原地覆盖现有已安装插件或 hook pack。对已跟踪 npm 插件的常规升级，请使用 `openclaw plugins update <id-or-npm-spec>`。它不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，而不是复制到受管理的安装目标上。
当 `plugins.allow` 已设置时，`openclaw plugins install` 会先将已安装插件 ID 添加到该 allowlist，然后再启用它。如果同一插件 ID 存在于 `plugins.deny` 中，install 会移除该过期 deny 条目，使显式安装在重启后立即可加载。
当 `plugins.allow` 已经设置时，`openclaw plugins install` 会先将已安装的插件 ID 添加到该 allowlist，然后再启用它。如果同一个插件 ID 出现在 `plugins.deny` 中，安装会移除该过时 deny 条目，使显式安装在重启后立即可加载。
OpenClaw 将持久化的本地插件注册表用作插件清单、贡献归属和启动规划的冷读模型。安装、更新、卸载、启用和停用流程会在更改插件状态后刷新该注册表。同一个 `plugins/installs.json` 文件在顶层 `installRecords` 中保存持久安装元数据，并在 `plugins` 中保存可重建的 manifest 元数据。如果注册表缺失、过期或无效，`openclaw plugins registry --refresh` 会根据安装记录、配置策略以及 manifest/package 元数据重建其 manifest 视图，而不会加载插件运行时模块。
OpenClaw 会将本地持久化插件注册表作为插件清单、贡献归属和启动规划的冷读取模型。安装、更新、卸载、启用和禁用流程会在更改插件状态后刷新该注册表。同一个 `plugins/installs.json` 文件会在顶层 `installRecords` 中保存持久安装元数据，并在 `plugins` 中保存可重建的清单元数据。如果注册表缺失、过时或无效，`openclaw plugins registry --refresh` 会基于安装记录、配置策略以及清单/包元数据重建其清单视图，而不会加载插件运行时模块。
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入带 dist-tag 或精确版本的 npm 包规范时，会将包名解析回已跟踪的插件记录，并记录新规范以供后续更新使用。传入不带版本的包名时，会将精确固定版本的安装移回注册表的默认发布线。如果已安装的 npm 插件已经匹配解析后的版本和记录的构件身份，OpenClaw 会跳过更新，不下载、不重新安装，也不重写配置。
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入带有 dist-tag 或精确版本的 npm package spec 会将包名解析回已跟踪的插件记录，并记录新的 spec 供后续更新使用。传入不带版本的包名会将精确固定的安装移回注册表的默认发布线。如果已安装的 npm 插件已经匹配解析出的版本和已记录的 artifact identity，OpenClaw 会跳过更新，不会下载、重新安装或重写配置。
`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm 规范。
`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace source metadata，而不是 npm spec。
`--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 网关支持的 skill 依赖安装改用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍是独立的 ClawHub skill 下载/安装流程。
此 CLI 标志仅适用于插件安装/更新流程。Gateway 网关支持的 skill 依赖安装改用匹配的 `dangerouslyForceUnsafeInstall` request override，而 `openclaw skills install` 仍是独立的 ClawHub skill 下载/安装流程。
如果你在 ClawHub 发布的插件被扫描隐藏或阻断，请打开 ClawHub 仪表板，或运行 `clawhub package rescan <name>` 请求 ClawHub 再次检查。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描插件，也不会让被阻断的发布公开。
如果你在 ClawHub 上发布的插件被扫描隐藏或阻止，请打开 ClawHub dashboard，或运行 `clawhub package rescan <name>` 请求 ClawHub 再次检查。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描该插件，也不会让被阻止的 release 公开。
兼容 bundle 会参与同一个插件列表/检查/启用/禁用流程。当前运行时支持包括 bundle skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
兼容的 bundle 会参与同一套插件列出/检查/启用/停用流程。当前运行时支持包括 bundle skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和 manifest 声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
`openclaw plugins inspect <id>` 还会报告检测到的 bundle 能力，以及 bundle 支持的插件中受支持或不受支持的 MCP 和 LSP 服务器条目。
`openclaw plugins inspect <id>` 还会报告检测到的 bundle 能力，以及 bundle 支持的插件中受支持或不受支持的 MCP 和 LSP server 条目。
Marketplace 来源可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保留在克隆的 marketplace 仓库内，并且只能使用相对路径来源。
Marketplace source 可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace root 或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub repo URL，或 git URL。对于远程 marketplace，插件条目必须保留在克隆的 marketplace repo 内，并且只能使用相对路径 source。
了解详情，请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。
请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins) 了解详情。
## 插件 API 概览
原生插件导出一个暴露 `register(api)` 的 entry object。较旧的插件可能仍使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。
原生插件会导出一个暴露 `register(api)` 的入口对象。较旧的插件可能仍将 `activate(api)` 用作旧版别名，但新插件应使用 `register`。
```typescript
export default definePluginEntry({
@ -512,21 +473,21 @@ export default definePluginEntry({
});
```
OpenClaw 会加载 entry object，并在插件激活期间调用 `register(api)`。loader 仍会回退到 `activate(api)` 以支持较旧的插件，但内置插件和新的外部插件应将 `register` 视为公共契约。
OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为较旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。
`api.registrationMode` 会告诉插件其 entry 被加载的原因：
`api.registrationMode` 会告诉插件其入口为何被加载：
| 模式 | 含义 |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `full` | 运行时激活。注册工具、钩子、服务、命令、路由和其他实时副作用。 |
| `discovery` | 只读能力发现。注册提供商和元数据；受信任的插件入口代码可以加载，但应跳过实时副作用。 |
| `setup-only` | 通过轻量级 setup entry 加载渠道设置元数据。 |
| `setup-runtime` | 需要运行时 entry 的渠道设置加载。 |
| `discovery` | 只读能力发现。注册提供商和元数据；可信插件入口代码可能会加载，但应跳过实时副作用。 |
| `setup-only` | 通过轻量级设置入口加载渠道设置元数据。 |
| `setup-runtime` | 还需要运行时入口的渠道设置加载。 |
| `cli-metadata` | 仅收集 CLI 命令元数据。 |
会打开 socket、数据库、后台 worker 或长生命周期 client 的插件 entry，应使用 `api.registrationMode === "full"` 保护这些副作用。发现加载会与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。发现是非激活的，但不是免 import 的：OpenClaw 可能会执行受信任的插件 entry 或渠道插件模块来构建 snapshot。保持模块顶层轻量且无副作用，并将网络 client、子进程、listener、凭证读取和服务启动移到完整运行时路径之后。
会打开套接字、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 保护这些副作用。发现加载会与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。发现是非激活的，但不是免导入的：OpenClaw 可能会求值可信插件入口或渠道插件模块来构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭据读取和服务启动移到完整运行时路径之后。
常用注册方法：
常见注册方法：
| 方法 | 注册内容 |
| --------------------------------------- | --------------------------- |
@ -536,28 +497,28 @@ OpenClaw 会加载 entry object，并在插件激活期间调用 `register(api)`
| `registerHook` / `on(...)` | 生命周期钩子 |
| `registerSpeechProvider` | 文本转语音 / STT |
| `registerRealtimeTranscriptionProvider` | 流式 STT |
| `registerRealtimeVoiceProvider` | 双工实时语音 |
| `registerRealtimeVoiceProvider` | 双向实时语音 |
| `registerMediaUnderstandingProvider` | 图像/音频分析 |
| `registerImageGenerationProvider` | 图像生成 |
| `registerMusicGenerationProvider` | 音乐生成 |
| `registerVideoGenerationProvider` | 视频生成 |
| `registerWebFetchProvider` | Web fetch / scrape 提供商 |
| `registerWebFetchProvider` | Web 抓取 / 抓取提供商 |
| `registerWebSearchProvider` | Web 搜索 |
| `registerHttpRoute` | HTTP 端点 |
| `registerCommand` / `registerCli` | CLI 命令 |
| `registerContextEngine` | 上下文引擎 |
| `registerService` | 后台服务 |
类型化生命周期钩子的 guard 行为：
类型化生命周期钩子的守卫行为：
- `before_tool_call`：`{ block: true }` 是终止性的；较低优先级的 handler 会被跳过。
- `before_tool_call`：`{ block: false }` 是 no-op，不会清除更早的 block。
- `before_install`：`{ block: true }` 是终止性的；较低优先级的 handler 会被跳过。
- `before_install`：`{ block: false }` 是 no-op，不会清除更早的 block。
- `message_sending`：`{ cancel: true }` 是终止性的；较低优先级的 handler 会被跳过。
- `message_sending`：`{ cancel: false }` 是 no-op，不会清除更早的 cancel。
- `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 原生工具事件桥接回此钩子表面。插件可以通过 `before_tool_call` 阻止原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。该 bridge 尚不会重写 Codex 原生工具参数。确切的 Codex 运行时支持边界位于 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)。
原生 Codex app-server 运行会把 Codex 原生工具事件桥接回这个钩子表面。插件可以通过 `before_tool_call` 阻断原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。该桥接目前还不会重写 Codex 原生工具参数。准确的 Codex 运行时支持边界位于 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)。
有关完整的类型化钩子行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
@ -565,7 +526,7 @@ OpenClaw 会加载 entry object，并在插件激活期间调用 `register(api)`
- [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件
- [插件 bundle](/zh-CN/plugins/bundles) — Codex/Claude/Cursor bundle 兼容性
- [插件 manifest](/zh-CN/plugins/manifest) — manifest schema
- [插件清单](/zh-CN/plugins/manifest) — 清单 schema
- [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具
- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载管线
- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流水线
- [社区插件](/zh-CN/plugins/community) — 第三方列表