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-01 21:01:06 +00:00
parent bea62e6dce
commit 1df4de242c
1 changed files with 137 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,21 +1,21 @@
---
read_when:
- 安装或配置插件
- 了解插件发现和加载规则
- 使用与 Codex/Claude 兼容的插件包
- 了解插件发现与加载规则
- 使用兼容 Codex/Claude 的插件包
sidebarTitle: Install and Configure
summary: 安装、配置和管理 OpenClaw 插件
title: 插件
x-i18n:
generated_at: "2026-05-01T20:42:02Z"
generated_at: "2026-05-01T20:59:46Z"
model: gpt-5.5
provider: openai
source_hash: 0991eac5bc54f7f5e0446747c7f9b81cce0a279e30412af53ce7b66539952708
source_hash: 32e89479c899f05756ba2853728ff9428e1b0ef866d336bba721a962f5546a8b
source_path: tools/plugin.md
workflow: 16
---
插件通过新能力扩展 OpenClaw：渠道、模型提供商、智能体 harness、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是 **核心**（随 OpenClaw 发布），其他是 **外部** 插件。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。npm 仍支持直接安装，以及在迁移完成前临时保留的一组 OpenClaw 自有插件包。
插件为 OpenClaw 扩展新能力：渠道、模型提供商、Agent harnesses、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页获取、Web 搜索等。一些插件是**核心**插件（随 OpenClaw 一起提供），其他则是**外部**插件。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。Npm 仍支持直接安装，也会在迁移完成前临时支持一组由 OpenClaw 拥有的插件包。
## 快速开始
@ -58,7 +58,7 @@ x-i18n:
openclaw <plugin-command> --help
```
当你需要证明已注册的工具、服务、gateway 方法、钩子或插件自有 CLI 命令时，请使用 `--runtime`。普通 `inspect` 是冷态清单/注册表检查，并且会有意避免导入插件运行时。
当你需要证明已注册的工具、服务、Gateway 网关方法、钩子或插件拥有的 CLI 命令时，请使用 `--runtime`。普通的 `inspect` 是冷态清单/注册表检查，并且会有意避免导入插件运行时。
</Step>
</Steps>
@ -71,30 +71,34 @@ x-i18n:
/plugin enable <plugin-id>
```
安装路径使用与 CLI 相同的解析器：本地路径/归档、显式 `clawhub:<pkg>`、显式 `npm:<pkg>`、显式 `git:<repo>`，或裸包规范（先查 ClawHub，然后回退到 npm）。
安装路径使用与 CLI 相同的解析器：本地路径/归档、显式 `clawhub:<pkg>`、显式 `npm:<pkg>`、显式 `git:<repo>`，或裸包规格（先 ClawHub，随后回退到 npm）。
如果配置无效，安装通常会失败关闭，并指向 `openclaw doctor --fix`。唯一的恢复例外是一个狭窄的内置插件重装路径，适用于选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。Gateway 网关启动期间，某个插件的无效配置会被隔离到该插件：启动会记录 `plugins.entries.<id>.config` 问题，在加载期间跳过该插件，并保持其他插件和渠道在线。运行 `openclaw doctor --fix` 可通过禁用该插件条目并移除其无效配置载荷来隔离错误的插件配置；常规配置备份会保留之前的值。当某个渠道配置引用了一个不再可发现的插件，但同一个陈旧插件 ID 仍保留在插件配置或安装记录中时，Gateway 网关启动会记录警告并跳过该渠道，而不是阻塞所有其他渠道。运行 `openclaw doctor --fix` 可移除陈旧的渠道/插件条目；没有陈旧插件证据的未知渠道键仍会导致验证失败，以便拼写错误保持可见。如果设置了 `plugins.enabled: false`，陈旧插件引用会被视为惰性：Gateway 网关启动会跳过插件发现/加载工作，且 `openclaw doctor` 会保留已禁用的插件配置，而不是自动移除它。如果你想移除陈旧插件 ID，请先重新启用插件，再运行 Doctor 清理。
如果配置无效，安装通常会失败关闭，并指向 `openclaw doctor --fix`。唯一的恢复例外是一条狭窄的内置插件重装路径，适用于选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。
Gateway 网关启动期间，单个插件的无效配置会被隔离到该插件：启动会记录 `plugins.entries.<id>.config` 问题，在加载期间跳过该插件，并保持其他插件和渠道在线。运行 `openclaw doctor --fix` 可通过禁用该插件条目并移除其无效配置载荷，来隔离有问题的插件配置；正常的配置备份会保留先前的值。
当渠道配置引用了一个不再可发现的插件，但同一个陈旧插件 id 仍存在于插件配置或安装记录中时，Gateway 网关启动会记录警告并跳过该渠道，而不是阻塞所有其他渠道。运行 `openclaw doctor --fix` 可移除陈旧的渠道/插件条目；没有陈旧插件证据的未知渠道键仍会导致验证失败，以便让拼写错误保持可见。
如果设置了 `plugins.enabled: false`，陈旧插件引用会被视为惰性：Gateway 网关启动会跳过插件发现/加载工作，并且 `openclaw doctor` 会保留已禁用的插件配置，而不是自动移除它。如果你想移除陈旧插件 id，请在运行 Doctor 清理前重新启用插件。
插件依赖安装只会在显式安装/更新或 Doctor 修复流程期间发生。Gateway 网关启动、配置重载和运行时检查不会运行包管理器，也不会修复依赖树。本地插件必须已安装其依赖，而 npm、git 和 ClawHub 插件会安装在 OpenClaw 管理的插件根目录下，并带有包本地依赖。外部插件和自定义加载路径仍必须通过 `openclaw plugins install` 安装。请参阅 [插件依赖解析](/zh-CN/plugins/dependency-resolution) 了解安装时生命周期。
插件依赖安装只会发生在显式安装/更新或 Doctor 修复流程中。Gateway 网关启动、配置重新加载和运行时检查不会运行包管理器，也不会修复依赖树。本地插件必须已经安装其依赖，而 npm、git 和 ClawHub 插件会安装在 OpenClaw 托管的插件根目录下，并带有包本地依赖。外部插件和自定义加载路径仍必须通过 `openclaw plugins install` 安装。
有关安装时生命周期，请参阅[插件依赖解析](/zh-CN/plugins/dependency-resolution)。
## 插件类型
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](/zh-CN/plugins/bundles) 了解 bundle 详情。
两者都会显示在 `openclaw plugins list` 下。有关 bundle 详情，请参阅[插件 Bundles](/zh-CN/plugins/bundles)。
如果你正在编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins) 和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。
如果你正在编写原生插件，请从[构建插件](/zh-CN/plugins/building-plugins)和[插件 SDK 概览](/zh-CN/plugins/sdk-overview)开始。
## 包入口点
原生插件 npm 包必须在 `package.json` 中声明 `openclaw.extensions`。每个条目都必须保留在包目录内，并解析为可读取的运行时文件，或者解析为带有可推断已构建 JavaScript 对应文件的 TypeScript 源文件，例如从 `src/index.ts` 到 `dist/index.js`。
原生插件 npm 包必须在 `package.json` 中声明 `openclaw.extensions`。每个条目都必须保留在包目录内，并解析到可读取的运行时文件，或解析到 TypeScript 源文件，并带有可推断的已构建 JavaScript 对等文件，例如从 `src/index.ts` 到 `dist/index.js`。
当已发布的运行时文件与源条目不在相同路径时，请使用 `openclaw.runtimeExtensions`。如果存在，`runtimeExtensions` 必须为每个 `extensions` 条目恰好包含一个条目。列表不匹配会导致安装和插件发现失败，而不是静默回退到源路径。
当发布的运行时文件不位于与源条目相同的路径时，请使用 `openclaw.runtimeExtensions`。如果存在，`runtimeExtensions` 必须为每个 `extensions` 条目精确包含一个条目。列表不匹配会导致安装和插件发现失败，而不是静默回退到源路径。
```json
{
@ -108,13 +112,13 @@ OpenClaw 识别两种插件格式：
## 官方插件
### 迁移期间 OpenClaw 自有的 npm 包
### 迁移期间由 OpenClaw 拥有的 npm 包
ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版本已经内置许多官方插件，因此这些插件在常规设置中不需要单独安装 npm。在所有 OpenClaw 自有插件迁移到 ClawHub 之前，OpenClaw 仍会在 npm 上发布一些 `@openclaw/*` 插件包，用于旧版/自定义安装和直接 npm 工作流。
ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版本已经内置许多官方插件，因此在正常设置中这些插件不需要单独的 npm 安装。在每个由 OpenClaw 拥有的插件都迁移到 ClawHub 之前，OpenClaw 仍会在 npm 上发布一些 `@openclaw/*` 插件包，用于较旧/自定义安装和直接 npm 工作流。
如果 npm 报告某个 `@openclaw/*` 插件包已弃用，该包版本来自较旧的外部包发布线。请使用当前 OpenClaw 中的内置插件或本地检出，直到发布更新的 npm 包。
如果 npm 报告某个 `@openclaw/*` 插件包已弃用，该包版本来自较旧的外部包序列。请使用当前 OpenClaw 的内置插件或本地检出，直到发布更新的 npm 包。
| 插件 | 包 | 文档 |
| 插件 | 包 | 文档 |
| --------------- | -------------------------- | ------------------------------------------ |
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/zh-CN/channels/bluebubbles) |
| Discord | `@openclaw/discord` | [Discord](/zh-CN/channels/discord) |
@ -130,7 +134,7 @@ ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版
| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) |
### 核心（随 OpenClaw 发布）
### 核心（随 OpenClaw 一起提供）
<AccordionGroup>
<Accordion title="模型提供商（默认启用）">
@ -142,10 +146,10 @@ ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版
</Accordion>
<Accordion title="记忆插件">
- `memory-core` — 内置记忆搜索（默认通过 `plugins.slots.memory`）
- `memory-lancedb` — 按需安装的长期记忆，支持自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`）
- `memory-core` — 内置记忆搜索（默认通过 `plugins.slots.memory` 使用）
- `memory-lancedb` — 由 LanceDB 支持的长期记忆，带自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`）
请参阅 [Memory LanceDB](/zh-CN/plugins/memory-lancedb)，了解 OpenAI 兼容的嵌入设置、Ollama 示例、召回限制和故障排除。
有关 OpenAI 兼容的 embedding 设置、Ollama 示例、召回限制和故障排除，请参阅 [Memory LanceDB](/zh-CN/plugins/memory-lancedb)。
</Accordion>
@ -154,13 +158,13 @@ ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版
</Accordion>
<Accordion title="其他">
- `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` gateway 方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用）
- `copilot-proxy` — VS Code Copilot Proxy 桥接（默认禁用）
- `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；请在替换它之前禁用）
- `copilot-proxy` — VS Code Copilot Proxy 桥接器（默认禁用）
</Accordion>
</AccordionGroup>
想找第三方插件？请参阅 [社区插件](/zh-CN/plugins/community)。
想找第三方插件？请参阅[社区插件](/zh-CN/plugins/community)。
## 配置
@ -178,36 +182,35 @@ ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版
}
```
| 字段 | 描述 |
| 字段 | 描述 |
| ---------------- | --------------------------------------------------------- |
| `enabled` | 主开关（默认：`true`） |
| `allow` | 插件允许列表（可选） |
| `deny` | 插件拒绝列表（可选；拒绝优先） |
| `load.paths` | 额外插件文件/目录 |
| `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） |
| `entries.\<id\>` | 每个插件的开关 + 配置 |
| `enabled` | 主开关（默认：`true`） |
| `allow` | 插件允许列表（可选） |
| `deny` | 插件拒绝列表（可选；拒绝优先） |
| `load.paths` | 额外插件文件/目录 |
| `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） |
| `entries.\<id\>` | 单插件开关 + 配置 |
`plugins.allow` 是排他的。当它非空时，只有列出的插件可以加载或暴露工具，即使 `tools.allow` 包含 `"*"` 或特定插件自有工具名也是如此。如果工具允许列表引用插件工具，请将所属插件 ID 添加到 `plugins.allow`，或移除 `plugins.allow`；`openclaw doctor` 会对此形态发出警告。
`plugins.allow` 是排他的。当它非空时，只有列出的插件可以加载或暴露工具，即使 `tools.allow` 包含 `"*"` 或特定插件拥有的工具名称也是如此。如果工具允许列表引用了插件工具，请将拥有这些工具的插件 id 添加到 `plugins.allow`，或移除 `plugins.allow`；`openclaw doctor` 会对此形态发出警告。
配置更改 **需要重启 Gateway 网关**。如果 Gateway 网关正在以启用配置监听 + 进程内重启的方式运行（默认 `openclaw gateway` 路径），该重启通常会在配置写入落地后片刻自动执行。原生插件运行时代码或生命周期钩子没有受支持的热重载路径；在期待更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务或提供商/运行时钩子运行之前，请重启正在服务实时渠道的 Gateway 网关进程。
配置更改**需要重启 Gateway 网关**。如果 Gateway 网关正在运行且启用了配置监听 + 进程内重启（默认 `openclaw gateway` 路径），该重启通常会在配置写入落地后的片刻自动执行。原生插件运行时代码或生命周期钩子没有受支持的热重载路径；在期待更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务或提供商/运行时钩子运行前，请重启正在服务实时渠道的 Gateway 网关进程。
`openclaw plugins list` 是本地插件注册表/配置快照。其中的 `enabled` 插件表示持久化注册表和当前配置允许该插件参与。它并不证明已运行的远程 Gateway 网关子进程已经重启到相同的插件代码。在带有包装进程的 VPS/容器设置中，请将重启发送到实际的 `openclaw gateway run` 进程，或针对正在运行的 Gateway 网关使用 `openclaw gateway restart`。
`openclaw plugins list` 是本地插件注册表/配置快照。那里的 `enabled` 插件表示持久化注册表和当前配置允许该插件参与。它并不能证明已经运行的远程 Gateway 网关子进程已重启到相同的插件代码。在 VPS/容器设置中，如果有包装进程，请将重启发送给实际的 `openclaw gateway run` 进程，或对正在运行的 Gateway 网关使用 `openclaw gateway restart`。
<Accordion title="插件状态：已禁用、缺失、无效">
<Accordion title="插件状态：已禁用 vs 缺失 vs 无效">
- **已禁用**：插件存在，但启用规则将其关闭。配置会保留。
- **缺失**：配置引用了发现过程没有找到的插件 ID。
- **缺失**：配置引用了一个发现过程未找到的插件 id。
- **无效**：插件存在，但其配置与声明的 schema 不匹配。Gateway 网关启动只会跳过该插件；`openclaw doctor --fix` 可以通过禁用无效条目并移除其配置载荷来隔离它。
</Accordion>
## 发现和优先级
## 设备发现和优先级
OpenClaw 按以下顺序扫描插件（第一个匹配项获胜）：
OpenClaw 会按以下顺序扫描插件（第一个匹配项胜出）：
<Steps>
<Step title="配置路径">
`plugins.load.paths` — 显式文件或目录路径。指向
OpenClaw 自身打包的内置插件目录的路径会被忽略；
`plugins.load.paths` — 显式文件或目录路径。指向 OpenClaw 自身打包的内置插件目录的路径会被忽略；
运行 `openclaw doctor --fix` 以移除这些过时别名。
</Step>
@ -225,7 +228,12 @@ OpenClaw 按以下顺序扫描插件（第一个匹配项获胜）：
</Step>
</Steps>
打包安装和 Docker 镜像通常从已编译的 `dist/extensions` 树解析内置插件。如果某个内置插件源目录被绑定挂载到匹配的打包源路径上，例如 `/app/extensions/synology-chat`，OpenClaw 会将该挂载的源目录视为内置源码覆盖层，并在打包的 `/app/dist/extensions/synology-chat` 包之前发现它。这样可以让维护者容器循环继续工作，而无需把每个内置插件都切回 TypeScript 源码。设置 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可强制使用打包的 dist 包，即使存在源码覆盖层挂载也是如此。
打包安装和 Docker 镜像通常会从已编译的 `dist/extensions` 树解析内置插件。如果某个内置插件源目录被
bind-mounted 到匹配的打包源路径上，例如
`/app/extensions/synology-chat`，OpenClaw 会将该挂载的源目录视为内置源覆盖层，并在打包的
`/app/dist/extensions/synology-chat` bundle 之前发现它。这样可以让维护者容器循环继续工作，而不必将每个内置插件都切回 TypeScript 源。
设置 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可强制使用打包的 dist bundles，
即使存在源覆盖挂载也是如此。
### 启用规则
@ -234,31 +242,37 @@ OpenClaw 按以下顺序扫描插件（第一个匹配项获胜）：
- `plugins.entries.\<id\>.enabled: false` 会禁用该插件
- 工作区来源的插件**默认禁用**（必须显式启用）
- 内置插件遵循内建的默认启用集合，除非被覆盖
- 独占槽位可以强制启用该槽位选中的插件
- 当配置命名某个插件拥有的表面时，一些内置的选择启用插件会自动启用，例如提供商模型引用、渠道配置或 harness 运行时
- 当 `plugins.enabled: false` 处于活动状态时，过时插件配置会被保留；如果你想移除过时 id，请先重新启用插件，再运行 Doctor 清理
- OpenAI 系列 Codex 路由保持独立的插件边界：
- 独占 slot 可以强制启用为该 slot 选择的插件
- 当配置命名了插件拥有的表面时，例如提供商模型引用、渠道配置或 harness
运行时，一些需要选择启用的内置插件会自动启用
- 当 `plugins.enabled: false` 生效时，过时的插件配置会被保留；
如果你希望移除过时 id，请先重新启用插件再运行 Doctor 清理
- OpenAI 系 Codex 路由保留独立的插件边界：
`openai-codex/*` 属于 OpenAI 插件，而内置 Codex
app-server 插件由 `agentRuntime.id: "codex"` 或旧版
`codex/*` 模型引用选择
## 排查运行时钩子
## 运行时钩子故障排除
如果插件出现在 `plugins list` 中，但 `register(api)` 副作用或钩子没有在实时聊天流量中运行，请先检查这些项：
如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或钩子没有在实时聊天流量中运行，请先检查这些项：
- 运行 `openclaw gateway status --deep --require-rpc`，并确认活动的
Gateway 网关 URL、profile、配置路径和进程就是你正在编辑的对象。
- 在插件安装/配置/代码变更后重启实时 Gateway 网关。在包装器容器中，
PID 1 可能只是一个 supervisor；请重启或向子
- 运行 `openclaw gateway status --deep --require-rpc`，并确认当前
Gateway 网关 URL、配置文件、配置路径和进程就是你正在编辑的那些。
- 在插件安装/配置/代码变更后重启实时 Gateway 网关。在 wrapper
容器中，PID 1 可能只是 supervisor；请重启或向子级
`openclaw gateway run` 进程发送信号。
- 使用 `openclaw plugins inspect <id> --runtime --json` 确认钩子注册和诊断信息。非内置对话钩子，例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`，需要
- 使用 `openclaw plugins inspect <id> --runtime --json` 确认钩子注册和
diagnostics。非内置会话钩子，例如 `llm_input`、
`llm_output`、`before_agent_finalize` 和 `agent_end`，需要
`plugins.entries.<id>.hooks.allowConversationAccess=true`。
- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析之前运行；`llm_output` 只会在一次模型尝试产出助手输出后运行。
- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体 turn 的模型解析之前运行；
`llm_output` 只会在一次模型尝试生成 assistant 输出之后运行。
- 要证明有效的会话模型，请使用 `openclaw sessions` 或
Gateway 网关会话/Status 表面；调试提供商 payload 时，使用
`--raw-stream --raw-stream-path <path>` 启动 Gateway 网关。
`--raw-stream --raw-stream-path <path>` 启动
Gateway 网关。
### 重复的渠道或工具归属
### 重复的渠道或工具所有权
症状：
@ -266,23 +280,27 @@ OpenClaw 按以下顺序扫描插件（第一个匹配项获胜）：
- `channel setup already registered: <channel-id> (<plugin-id>)`
- `plugin tool name conflict (<plugin-id>): <tool-name>`
这些表示不止一个已启用插件正在尝试拥有同一个渠道、设置流程或工具名称。最常见原因是，一个外部渠道插件安装在某个内置插件旁边，而该内置插件现在提供相同的渠道 id。
这些表示不止一个已启用插件正在尝试拥有同一个渠道、
设置流程或工具名称。最常见的原因是外部渠道插件与现在提供相同渠道 id 的内置插件一起安装。
调试步骤：
- 运行 `openclaw plugins list --enabled --verbose` 查看每个已启用插件及其来源。
- 对每个可疑插件运行 `openclaw plugins inspect <id> --runtime --json`，并比较 `channels`、`channelConfigs`、`tools` 和诊断信息。
- 安装或移除插件包后，运行 `openclaw plugins registry --refresh`，让持久化元数据反映当前安装。
- 对每个可疑插件运行 `openclaw plugins inspect <id> --runtime --json`，
并比较 `channels`、`channelConfigs`、`tools` 和 diagnostics。
- 安装或移除插件包后，运行 `openclaw plugins registry --refresh`，
使持久化元数据反映当前安装。
- 在安装、registry 或配置变更后重启 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 会保留该请求并报告冲突。为该渠道选择一个所有者，或重命名插件拥有的工具，使运行时表面没有歧义。
## 插件槽位（独占类别）
## 插件 slots（独占类别）
某些类别是独占的（同一时间只能有一个处于活动状态）：
@ -297,7 +315,7 @@ OpenClaw 按以下顺序扫描插件（第一个匹配项获胜）：
}
```
| 槽位 | 控制内容 | 默认值 |
| Slot | 控制内容 | 默认值 |
| --------------- | --------------------- | ------------------- |
| `memory` | 主动记忆插件 | `memory-core` |
| `contextEngine` | 活动上下文引擎 | `legacy`（内建） |
@ -349,35 +367,48 @@ 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` 中，安装会移除那个过时的 deny 条目，以便显式安装的插件在重启后立即可加载。
当 `plugins.allow` 已设置时，`openclaw plugins install` 会先将已安装插件 id
添加到该 allowlist，然后启用它。如果同一个插件 id 出现在 `plugins.deny` 中，安装会移除该过时 deny 条目，以便显式安装在重启后立即可加载。
OpenClaw 会保留一个持久化的本地插件 registry，作为插件清单、贡献归属和启动规划的冷读模型。安装、更新、卸载、启用和禁用流程在更改插件状态后都会刷新该 registry。同一个 `plugins/installs.json` 文件在顶层 `installRecords` 中保留持久安装元数据，并在 `plugins` 中保留可重建的 manifest 元数据。如果 registry 缺失、过时或无效，`openclaw plugins registry
--refresh` 会从安装记录、配置策略以及 manifest/package 元数据重建其 manifest 视图，而不会加载插件运行时模块。
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入带有 dist-tag 或精确版本的 npm 包 spec 时，会将包名解析回已跟踪的插件记录，并记录新的 spec 以供未来更新使用。传入不带版本的包名，会把精确固定的安装移回 registry 的默认发布线。如果已安装的 npm 插件已经匹配已解析版本和已记录的 artifact identity，OpenClaw 会跳过更新，不下载、不重新安装，也不重写配置。
OpenClaw 会保留一个持久化的本地插件 registry，作为插件清单、贡献所有权和启动规划的冷读模型。安装、更新、卸载、启用和禁用流程在更改插件状态后会刷新该 registry。同一个 `plugins/installs.json` 文件会在顶层 `installRecords` 中保存持久安装元数据，并在 `plugins` 中保存可重建的 manifest 元数据。如果 registry 缺失、过时或无效，`openclaw plugins registry
--refresh` 会从安装记录、配置策略和 manifest/package 元数据重建其 manifest 视图，而不加载插件运行时模块。
`openclaw plugins update <id-or-npm-spec>` 适用于受跟踪的安装。传入带 dist-tag 或精确版本的 npm 包 spec 会将包名解析回受跟踪的插件记录，并记录新的 spec 以用于后续更新。传入不带版本的包名会将精确 pin 的安装移回 registry 的默认发布线。如果已安装的 npm 插件已经匹配解析出的版本和记录的 artifact identity，OpenClaw 会跳过更新，不下载、不重新安装，也不重写配置。
`--pin` 仅适用于 npm。它不支持与 `--marketplace` 搭配使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。
`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 源元数据，而不是 npm spec。
`--dangerously-force-unsafe-install` 是用于处理内置危险代码扫描器误报的应急覆盖项。它允许插件安装和插件更新越过内置 `critical` findings 继续执行，但仍不会绕过插件 `before_install` policy blocks 或 scan-failure blocking。安装扫描会忽略常见测试文件和目录，例如 `tests/`、`__tests__/`、`*.test.*` 和 `*.spec.*`，以避免阻止打包的测试 mocks；声明的插件运行时入口点即使使用这些名称之一，仍会被扫描。
`--dangerously-force-unsafe-install` 是用于处理内建危险代码扫描器误报的 break-glass override。它允许插件安装和插件更新越过内建的 `critical` 发现继续执行，但仍不会绕过插件 `before_install` 策略阻断或扫描失败阻断。安装扫描会忽略常见测试文件和目录，例如 `tests/`、
`__tests__/`、`*.test.*` 和 `*.spec.*`，以避免阻断打包的测试 mock；
声明的插件运行时入口点即使使用这些名称之一，仍会被扫描。
此 CLI 标志仅适用于插件安装/更新流程。Gateway 网关支持的 skill 依赖安装改用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖项，而 `openclaw skills install` 仍是单独的 ClawHub skill 下载/安装流程。
该 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 skill
依赖安装改用匹配的 `dangerouslyForceUnsafeInstall` 请求 override，而
`openclaw skills install` 仍是单独的 ClawHub skill 下载/安装流程。
如果你发布在 ClawHub 上的插件被扫描隐藏或阻止，请打开 ClawHub dashboard，或运行 `clawhub package rescan <name>` 请求 ClawHub 再次检查它。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描插件，也不会让被阻止的 release 公开。
如果你发布到 ClawHub 的插件因扫描而被隐藏或阻断，请打开
ClawHub dashboard，或运行 `clawhub package rescan <name>` 请求 ClawHub 重新检查它。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描该插件，也不会使被阻断的发布公开。
兼容包参与同一套插件 list/inspect/enable/disable 流程。当前运行时支持包括 bundle skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和 manifest 声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
兼容 bundles 会参与同一个插件 list/inspect/enable/disable 流程。当前运行时支持包括 bundle skills、Claude command-skills、Claude `settings.json` defaults、Claude `.lsp.json` 和 manifest 声明的
`lspServers` defaults、Cursor command-skills，以及兼容的 Codex hook
目录。
`openclaw plugins inspect <id>` 还会报告检测到的 bundle 能力，以及 bundle-backed 插件支持或不支持的 MCP 和 LSP server 条目。
`openclaw plugins inspect <id>` 还会报告检测到的 bundle capabilities，以及 bundle-backed 插件支持或不支持的 MCP 和 LSP server 条目。
市场源可以是 `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知市场名称、本地市场根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程市场，插件条目必须保留在克隆的市场仓库内部，并且只能使用相对路径源。
Marketplace 源可以是 `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知 marketplace 名称、本地 marketplace 根目录或
`marketplace.json` 路径、像 `owner/repo` 这样的 GitHub 简写、GitHub 仓库
URL，或 git URL。对于远程 marketplace，插件条目必须保留在克隆的 marketplace 仓库内，并且只使用相对路径源。
了解详情，请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。
## 插件 API 概览
原生插件导出一个入口对象，该对象公开 `register(api)`。较旧的插件可能仍使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。
原生插件会导出一个公开 `register(api)` 的入口对象。较旧的插件仍可将
`activate(api)` 用作旧版别名，但新插件应使用 `register`。
```typescript
export default definePluginEntry({
@ -397,19 +428,22 @@ export default definePluginEntry({
});
```
OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为较旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。
OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为较旧插件回退到 `activate(api)`，
但内置插件和新的外部插件应将 `register` 视为公共契约。
`api.registrationMode` 会告诉插件其入口为何被加载：
`api.registrationMode` 会告诉插件其入口为什么被加载：
| 模式 | 含义 |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `full` | 运行时激活。注册工具、钩子、服务、命令、路由和其他实时副作用。 |
| `discovery` | 只读能力发现。注册提供商和元数据；受信任的插件入口代码可以加载，但跳过实时副作用。 |
| `discovery` | 只读能力发现。注册提供商和元数据；可信插件入口代码可以加载，但应跳过实时副作用。 |
| `setup-only` | 通过轻量级设置入口加载渠道设置元数据。 |
| `setup-runtime` | 渠道设置加载，同时还需要运行时入口。 |
| `setup-runtime` | 还需要运行时入口的渠道设置加载。 |
| `cli-metadata` | 仅收集 CLI 命令元数据。 |
会打开套接字、数据库、后台工作线程或长期存活客户端的插件入口，应使用 `api.registrationMode === "full"` 保护这些副作用。发现加载与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。发现是非激活的，但并非免导入：OpenClaw 可能会求值受信任的插件入口或渠道插件模块来构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径之后。
会打开 socket、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 来保护这些副作用。
设备发现加载与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。设备发现是非激活式的，但不是免导入的：
OpenClaw 可能会求值可信插件入口或渠道插件模块来构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径之后。
常见注册方法：
@ -426,8 +460,8 @@ OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`
| `registerImageGenerationProvider` | 图像生成 |
| `registerMusicGenerationProvider` | 音乐生成 |
| `registerVideoGenerationProvider` | 视频生成 |
| `registerWebFetchProvider` | Web 抓取 / 抓取提供商 |
| `registerWebSearchProvider` | Web 搜索 |
| `registerWebFetchProvider` | 网页获取 / 抓取提供商 |
| `registerWebSearchProvider` | 网页搜索 |
| `registerHttpRoute` | HTTP 端点 |
| `registerCommand` / `registerCli` | CLI 命令 |
| `registerContextEngine` | 上下文引擎 |
@ -435,22 +469,26 @@ OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`
类型化生命周期钩子的钩子保护行为：
- `before_tool_call`：`{ block: true }` 是终止性的；会跳过较低优先级的处理器。
- `before_tool_call`：`{ block: false }` 是无操作，并且不会清除先前的阻止。
- `before_install`：`{ block: true }` 是终止性的；会跳过较低优先级的处理器。
- `before_install`：`{ block: false }` 是无操作，并且不会清除先前的阻止。
- `message_sending`：`{ cancel: true }` 是终止性的；会跳过较低优先级的处理器。
- `message_sending`：`{ cancel: false }` 是无操作，并且不会清除先前的取消。
- `before_tool_call`：`{ block: true }` 是终止性的；较低优先级的处理程序会被跳过。
- `before_tool_call`：`{ block: false }` 是无操作，且不会清除之前的拦截。
- `before_install`：`{ block: true }` 是终止性的；较低优先级的处理程序会被跳过。
- `before_install`：`{ block: false }` 是无操作，且不会清除之前的拦截。
- `message_sending`：`{ cancel: true }` 是终止性的；较低优先级的处理程序会被跳过。
- `message_sending`：`{ cancel: false }` 是无操作，且不会清除之前的取消。
原生 Codex 应用服务器会将 Codex 原生工具事件桥接回这个钩子表面。插件可以通过 `before_tool_call` 阻止原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。该桥接目前尚不会重写 Codex 原生工具参数。确切的 Codex 运行时支持边界位于 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)。
原生 Codex app-server 会把 bridge Codex 原生工具事件送回这个钩子表面。
插件可以通过 `before_tool_call` 拦截原生 Codex 工具，
通过 `after_tool_call` 观察结果，并参与 Codex
`PermissionRequest` 批准。bridge 目前还不会重写 Codex 原生工具参数。确切的 Codex 运行时支持边界位于
[Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)。
关于完整的类型化钩子行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
完整的类型化钩子行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
## 相关内容
## 相关
- [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件
- [插件包](/zh-CN/plugins/bundles) — Codex/Claude/Cursor 包兼容性
- [插件清单](/zh-CN/plugins/manifest) — 清单架构
- [插件清单](/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) — 第三方列表