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-04-22 07:02:49 +00:00
parent f636046fd0
commit 32c63dc3f2
3 changed files with 435 additions and 427 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,33 +1,33 @@
---
read_when:
- 你想创建一个新的 OpenClaw 插件
- 你需要一个插件开发的快速开始指南
- 你正在为 OpenClaw 添加新的渠道、提供商、工具或其他能力
- 你需要一个用于插件开发的快速开始指南
- 你正在为 OpenClaw 添加一个新的渠道、提供商、工具或其他能力
sidebarTitle: Getting Started
summary: 在几分钟内创建你的第一个 OpenClaw 插件
title: 构建插件
x-i18n:
generated_at: "2026-04-06T12:43:29Z"
generated_at: "2026-04-22T07:00:34Z"
model: gpt-5.4
provider: openai
source_hash: 509c1f5abe1a0a74966054ed79b71a1a7ee637a43b1214c424acfe62ddf48eef
source_hash: 67368be311537f984f14bea9239b88c3eccf72a76c9dd1347bb041e02697ae24
source_path: plugins/building-plugins.md
workflow: 15
---
# 构建插件
插件可为 OpenClaw 扩展新能力：渠道、模型提供商、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索、智能体工具，或这些能力的任意组合。
插件通过新能力扩展 OpenClaw：渠道、模型提供商、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索、智能体工具，或这些能力的任意组合。
你不需要将你的插件添加到 OpenClaw 仓库中。发布到 [ClawHub](/zh-CN/tools/clawhub) 或 npm，用户即可通过 `openclaw plugins install <package-name>` 安装。OpenClaw 会优先尝试 ClawHub，并在需要时自动回退到 npm。
你不需要将你的插件添加到 OpenClaw 仓库中。发布到 [ClawHub](/zh-CN/tools/clawhub) 或 npm，用户即可使用 `openclaw plugins install <package-name>` 安装。OpenClaw 会先尝试 ClawHub，然后自动回退到 npm。
## 前置条件
## 先决条件
- Node >= 22，以及一个包管理器（npm 或 pnpm）
- Node >= 22 和一个包管理器（npm 或 pnpm）
- 熟悉 TypeScript（ESM）
- 对于仓库内插件：已克隆仓库并完成 `pnpm install`
- 对于仓库内插件：已克隆仓库并执行 `pnpm install`
## 你要构建哪种插件？
## 这是什么类型的插件？
<CardGroup cols={3}>
<Card title="渠道插件" icon="messages-square" href="/zh-CN/plugins/sdk-channel-plugins">
@ -37,15 +37,15 @@ x-i18n:
添加一个模型提供商（LLM、代理或自定义端点）
</Card>
<Card title="工具 / hook 插件" icon="wrench">
注册智能体工具、事件 hook 或服务 —— 继续阅读下文
注册智能体工具、事件 hooks 或服务——继续阅读下文
</Card>
</CardGroup>
如果某个渠道插件是可选的，并且在新手引导/设置运行时可能尚未安装，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。它会生成一个设置适配器 + 向导组合，用于提示安装要求，并在插件安装完成前对真实配置写入进行失败关闭保护。
如果某个渠道插件是可选的，并且在新手引导 / 设置运行时可能尚未安装，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。它会生成一个设置适配器 + 向导组合，用于提示安装要求，并在插件安装之前，对真实配置写入执行封闭失败保护。
## 快速开始：工具插件
本教程将创建一个用于注册智能体工具的最小插件。渠道插件和提供商插件有各自的专用指南，见上方链接。
本演练将创建一个用于注册智能体工具的最小插件。渠道插件和提供商插件有上方链接的专门指南。
<Steps>
<Step title="创建包和清单">
@ -82,9 +82,8 @@ x-i18n:
```
</CodeGroup>
每个插件都需要一个清单，即使没有配置也是如此。完整 schema 请参见
[Manifest](/zh-CN/plugins/manifest)。规范的 ClawHub
发布片段位于 `docs/snippets/plugin-publish/`。
每个插件都需要一个清单，即使没有配置也是如此。完整模式请参见
[Manifest](/zh-CN/plugins/manifest)。ClawHub 发布的规范代码片段位于 `docs/snippets/plugin-publish/`。
</Step>
@ -113,14 +112,14 @@ x-i18n:
```
`definePluginEntry` 用于非渠道插件。对于渠道，请使用
`defineChannelPluginEntry` —— 参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。
如需了解完整的入口点选项，请参见 [入口点](/zh-CN/plugins/sdk-entrypoints)。
`defineChannelPluginEntry`——参见 [Channel Plugins](/zh-CN/plugins/sdk-channel-plugins)。
完整的入口点选项请参见 [Entry Points](/zh-CN/plugins/sdk-entrypoints)。
</Step>
<Step title="测试并发布">
**外部插件：** 通过 ClawHub 验证并发布，然后安装：
**外部插件：** 使用 ClawHub 验证并发布，然后安装：
```bash
clawhub package publish your-org/your-plugin --dry-run
@ -128,9 +127,9 @@ x-i18n:
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
```
对于像 `@myorg/openclaw-my-plugin` 这样的裸包规范，OpenClaw 也会在 npm 之前先检查 ClawHub。
对于像 `@myorg/openclaw-my-plugin` 这样的裸包说明符，OpenClaw 也会在 npm 之前先检查 ClawHub。
**仓库内插件：** 放在内置插件工作区树下 —— 会自动发现。
**仓库内插件：** 放在内置插件工作区树下——会被自动发现。
```bash
pnpm test -- <bundled-plugin-root>/my-plugin/
@ -145,51 +144,54 @@ x-i18n:
| 能力 | 注册方法 | 详细指南 |
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
| 文本推理（LLM） | `api.registerProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins) |
| CLI 推理后端 | `api.registerCliBackend(...)` | [CLI 后端](/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.registerRealtimeVoiceProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 图像生成 | `api.registerImageGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 音乐生成 | `api.registerMusicGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 视频生成 | `api.registerVideoGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 网页抓取 | `api.registerWebFetchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 网页搜索 | `api.registerWebSearchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 文本推理（LLM） | `api.registerProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins) |
| CLI 推理后端 | `api.registerCliBackend(...)` | [CLI Backends](/zh-CN/gateway/cli-backends) |
| 渠道 / 消息 | `api.registerChannel(...)` | [Channel Plugins](/zh-CN/plugins/sdk-channel-plugins) |
| 语音（TTS/STT） | `api.registerSpeechProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 实时转写 | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 图像生成 | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 音乐生成 | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 视频生成 | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 网页抓取 | `api.registerWebFetchProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 网页搜索 | `api.registerWebSearchProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 内嵌 Pi 扩展 | `api.registerEmbeddedExtensionFactory(...)` | [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api) |
| 智能体工具 | `api.registerTool(...)` | 下文 |
| 自定义命令 | `api.registerCommand(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) |
| 事件 hook | `api.registerHook(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) |
| HTTP 路由 | `api.registerHttpRoute(...)` | [内部机制](/zh-CN/plugins/architecture#gateway-http-routes) |
| CLI 子命令 | `api.registerCli(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) |
| 自定义命令 | `api.registerCommand(...)` | [Entry Points](/zh-CN/plugins/sdk-entrypoints) |
| 事件 hooks | `api.registerHook(...)` | [Entry Points](/zh-CN/plugins/sdk-entrypoints) |
| HTTP 路由 | `api.registerHttpRoute(...)` | [Internals](/zh-CN/plugins/architecture#gateway-http-routes) |
| CLI 子命令 | `api.registerCli(...)` | [Entry Points](/zh-CN/plugins/sdk-entrypoints) |
完整注册 API 请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api)。
完整注册 API，请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api)。
如果你的插件注册了自定义 Gateway 网关 RPC 方法，请为它们使用插件专属前缀。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）保持保留状态，并且始终解析到 `operator.admin`，即使插件请求了更窄的作用域也是如此。
当插件需要 Pi 原生的嵌入式运行器 hooks 时，请使用 `api.registerEmbeddedExtensionFactory(...)`，例如在最终工具结果消息发出之前，异步重写 `tool_result`。如果工作不需要 Pi 扩展时序，应优先使用常规 OpenClaw 插件 hooks。
如果你的插件注册自定义 Gateway 网关 RPC 方法，请将它们放在插件专属前缀下。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保留，并且总是解析为 `operator.admin`，即使插件请求更窄的作用域也是如此。
需要注意的 hook 守卫语义：
- `before_tool_call`：`{ block: true }` 为终止结果，并会阻止更低优先级的处理器继续执行。
- `before_tool_call`：`{ block: true }` 为终止性决定，并会停止更低优先级的处理器。
- `before_tool_call`：`{ block: false }` 会被视为未作决定。
- `before_tool_call`：`{ requireApproval: true }` 会暂停智能体执行，并通过 exec 审批覆盖层、Telegram 按钮、Discord 交互，或任意渠道上的 `/approve` 命令提示用户批准。
- `before_install`：`{ block: true }` 为终止结果，并会阻止更低优先级的处理器继续执行。
- `before_tool_call`：`{ requireApproval: true }` 会暂停智能体执行，并通过 exec 审批覆盖层、Telegram 按钮、Discord 交互，或任意渠道上的 `/approve` 命令提示用户审批。
- `before_install`：`{ block: true }` 为终止性决定，并会停止更低优先级的处理器。
- `before_install`：`{ block: false }` 会被视为未作决定。
- `message_sending`：`{ cancel: true }` 为终止结果，并会阻止更低优先级的处理器继续执行。
- `message_sending`：`{ cancel: true }` 为终止性决定，并会停止更低优先级的处理器。
- `message_sending`：`{ cancel: false }` 会被视为未作决定。
`/approve` 命令会同时处理 exec 审批和插件审批，并带有有界回退：当找不到某个 exec 审批 ID 时，OpenClaw 会用同一个 ID 通过插件审批再次尝试。插件审批转发可通过配置中的 `approvals.plugin` 独立设置。
`/approve` 命令会同时处理 exec 审批和插件审批，并带有有界回退：当找不到 exec 审批 id 时，OpenClaw 会使用相同 id 通过插件审批重试。插件审批转发可通过配置中的 `approvals.plugin` 独立设置。
如果自定义审批流程需要检测这一相同的有界回退场景，优先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，而不要手动匹配审批过期字符串。
如果自定义审批流程需要检测这个相同的有界回退场景，优先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，而不是手动匹配审批过期字符串。
详情请参见 [SDK 概览中的 hook 决策语义](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
详见 [SDK 概览 hook 决策语义](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
## 注册智能体工具
工具是 LLM 可调用的类型化函数。它们可以是必需的（始终可用），也可以是可选的（用户主动启用）：
工具是 LLM 可以调用的类型化函数。它们可以是必需的（始终可用），也可以是可选的（用户选择启用）：
```typescript
register(api) {
// 必需工具 —— 始终可用
// 必需工具——始终可用
api.registerTool({
name: "my_tool",
description: "Do a thing",
@ -199,7 +201,7 @@ register(api) {
},
});
// 可选工具 —— 用户必须添加到 allowlist
// 可选工具——用户必须添加到 allowlist
api.registerTool(
{
name: "workflow_tool",
@ -223,8 +225,8 @@ register(api) {
```
- 工具名称不得与核心工具冲突（冲突项会被跳过）
- 对于具有副作用或需要额外二进制依赖的工具，请使用 `optional: true`
- 用户可通过将插件 ID 添加到 `tools.allow` 来启用某个插件的所有工具
- 对于有副作用或有额外二进制依赖要求的工具，请使用 `optional: true`
- 用户可以通过将插件 id 添加到 `tools.allow` 来启用某个插件的所有工具
## 导入约定
@ -238,19 +240,19 @@ 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 路径导入你自己的插件。
对于提供商插件，除非该扩展点确实具有通用性，否则请将提供商特定的辅助函数保留在这些包根级 barrel 中。当前内置示例包括：
对于提供商插件，除非该抽象接口确实是通用的，否则应将提供商专用辅助函数保留在这些包根 barrel 中。当前内置示例包括：
- Anthropic：Claude 流包装器以及 `service_tier` / beta 辅助函数
- Anthropic：Claude 流包装器，以及 `service_tier` / beta 辅助函数
- OpenAI：提供商构建器、默认模型辅助函数、实时提供商
- OpenRouter：提供商构建器以及新手引导/配置辅助函数
- OpenRouter：提供商构建器以及新手引导 / 配置辅助函数
如果某个辅助函数只在一个内置提供商包内部有用，请将其保留在该包根级扩展点上，而不是将其提升到 `openclaw/plugin-sdk/*` 中。
如果某个辅助函数只在一个内置提供商包内部有用，请将其保留在该包根抽象接口上，而不是提升到 `openclaw/plugin-sdk/*` 中。
一些生成的 `openclaw/plugin-sdk/<bundled-id>` 辅助扩展点仍然存在，用于内置插件维护和兼容性，例如 `plugin-sdk/feishu-setup` 或 `plugin-sdk/zalo-setup`。请将这些视为保留接口，而不是新第三方插件的默认模式。
一些生成的 `openclaw/plugin-sdk/<bundled-id>` 辅助抽象接口仍然存在，用于内置插件维护和兼容性，例如 `plugin-sdk/feishu-setup` 或 `plugin-sdk/zalo-setup`。应将这些视为保留接口，而不是新第三方插件的默认模式。
## 提交前检查清单
@ -258,20 +260,20 @@ import { ... } from "openclaw/plugin-sdk";
<Check>**openclaw.plugin.json** 清单存在且有效</Check>
<Check>入口点使用 `defineChannelPluginEntry` 或 `definePluginEntry`</Check>
<Check>所有导入都使用聚焦的 `plugin-sdk/<subpath>` 路径</Check>
<Check>内部导入使用本地模块，而不是 SDK 自导入</Check>
<Check>内部导入使用本地模块，而不是通过 SDK 自导入</Check>
<Check>测试通过（`pnpm test -- <bundled-plugin-root>/my-plugin/`）</Check>
<Check>`pnpm check` 通过（仓库内插件）</Check>
## 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 标签一出现，就尽快用它测试你的插件。稳定版发布前的窗口通常只有几个小时。
3. 测试后，在 Discord 的 `plugin-forum` 渠道中你插件对应的线程里发布 `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 的 blocker 会被合并；没有 PR 的 blocker 也可能照样发布。维护者会在 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 标签出现，立即针对该 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. 没有消息就表示一切正常。如果你错过了这个窗口，你的修复很可能会进入下一个周期。
## 下一步
## 后续步骤
<CardGroup cols={2}>
<Card title="渠道插件" icon="messages-square" href="/zh-CN/plugins/sdk-channel-plugins">
@ -290,14 +292,14 @@ import { ... } from "openclaw/plugin-sdk";
测试工具和模式
</Card>
<Card title="插件清单" icon="file-json" href="/zh-CN/plugins/manifest">
完整清单 schema 参考
完整的清单模式参考
</Card>
</CardGroup>
## 相关内容
- [插件架构](/zh-CN/plugins/architecture) — 内部架构深度解析
- [插件架构](/zh-CN/plugins/architecture) — 内部架构深入解析
- [SDK 概览](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考
- [Manifest](/zh-CN/plugins/manifest) — 插件清单格式
- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件
- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件
- [Channel Plugins](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件
- [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件

307
docs/zh-CN/plugins/manifest.md
View File

@ -5,19 +5,19 @@ read_when:
summary: 插件清单 + JSON schema 要求（严格配置校验）
title: 插件清单
x-i18n:
generated_at: "2026-04-22T05:13:44Z"
generated_at: "2026-04-22T07:00:33Z"
model: gpt-5.4
provider: openai
source_hash: b80735690799682939e8c8c27b6a364caa3ceadcf6319155ddeb20eb0538c313
source_hash: 085c1baccb96b8e6bd4033ad11bdd5f79bdb0daec470e977fce723c3ae38cc99
source_path: plugins/manifest.md
workflow: 15
---
# 插件清单（`openclaw.plugin.json`）
本页仅介绍**原生 OpenClaw 插件清单**。
本页仅适用于**原生 OpenClaw 插件清单**。
有关兼容的 bundle 布局，请参见 [插件包](/zh-CN/plugins/bundles)。
如需了解兼容的 bundle 布局，请参阅 [插件 bundles](/zh-CN/plugins/bundles)。
兼容的 bundle 格式使用不同的清单文件：
@ -25,34 +25,35 @@ x-i18n:
- Claude bundle：`.claude-plugin/plugin.json`，或不带清单的默认 Claude 组件布局
- Cursor bundle：`.cursor-plugin/plugin.json`
OpenClaw 也会自动检测这些 bundle 布局，但不会根据此处描述的 `openclaw.plugin.json` schema 对它们进行校验。
OpenClaw 也会自动检测这些 bundle 布局，但它们不会根据此处介绍的 `openclaw.plugin.json` schema 进行校验。
对于兼容 bundle，当布局符合 OpenClaw 运行时预期时，OpenClaw 当前会读取 bundle 元数据，以及声明的 skill 根目录、Claude 命令根目录、Claude bundle `settings.json` 默认值、Claude bundle LSP 默认值和受支持的 hook 包。
对于兼容 bundle，如果其布局符合 OpenClaw 运行时预期，OpenClaw 当前会读取 bundle 元数据，以及声明的 skill 根目录、Claude 命令根目录、Claude bundle 的 `settings.json` 默认值、Claude bundle 的 LSP 默认值，以及受支持的 hook packs。
每个原生 OpenClaw 插件**必须**在**插件根目录**提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用这个清单在**不执行插件代码**的情况下校验配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。
每个原生 OpenClaw 插件**必须**在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单在**不执行插件代码**的情况下校验配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。
请参见完整的插件系统指南：[插件](/zh-CN/tools/plugin)。
有关原生能力模型和当前外部兼容性指南，请参见：[能力模型](/zh-CN/plugins/architecture#public-capability-model)。
完整的插件系统指南请参阅：[插件](/zh-CN/tools/plugin)。
如需了解原生能力模型及当前外部兼容性指南，请参阅：
[能力模型](/zh-CN/plugins/architecture#public-capability-model)。
## 这个文件的作用
## 此文件的作用
`openclaw.plugin.json` 是 OpenClaw 在加载你的插件代码之前读取的元数据。
用于：
将它用于：
- 插件标识
- 配置校验
- 无需启动插件运行时即可获取的认证和新手引导元数据
- 供控制平面界面在运行时加载前检查的低成本激活提示
- 供设置 / 新手引导界面在运行时加载前检查的低成本设置描述符
- 应在插件运行时加载前解析的别名和自动启用元数据
- 应在运行时加载前自动激活插件的简写模型家族归属元数据
- 用于内置兼容接线和契约覆盖的静态能力归属快照
- 共享 `openclaw qa` 主机可在插件运行时加载前检查的低成本 QA 运行器元数据
- 无需加载运行时即可合并到目录和校验界面的渠道专用配置元数据
- 无需启动插件运行时即可获取的认证与新手引导元数据
- 控制平面界面可在运行时加载前检查的轻量激活提示
- 设置 / 新手引导界面可在运行时加载前检查的轻量设置描述符
- 应在插件运行时加载前解析的别名与自动启用元数据
- 应在插件运行时加载前自动激活插件的简写模型家族归属元数据
- 用于内置兼容接线与契约覆盖的静态能力归属快照
- 共享 `openclaw qa` 主机可在插件运行时加载前检查的轻量 QA 运行器元数据
- 应合并到目录与校验界面、且无需加载运行时的渠道专属配置元数据
- 配置 UI 提示
不要用于：
不要将它用于：
- 注册运行时行为
- 声明代码入口点
@ -140,30 +141,30 @@ OpenClaw 也会自动检测这些 bundle 布局，但不会根据此处描述的
| 字段 | 必填 | 类型 | 含义 |
| ------------------------------------ | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | 是 | `string` | 规范插件 ID。这是在 `plugins.entries.<id>` 中使用的 ID。 |
| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 |
| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略它，或设置为任何非 `true` 的值，则插件默认保持禁用。 |
| `legacyPluginIds` | 否 | `string[]` | 会规范化为此标准插件 ID 的旧版 ID。 |
| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提到这些提供商 ID 时，应自动启用此插件。 |
| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明一个由 `plugins.slots.*` 使用的独占插件类型。 |
| `channels` | 否 | `string[]` | 由此插件拥有的渠道 ID。用于发现和配置校验。 |
| `providers` | 否 | `string[]` | 由此插件拥有的提供商 ID。 |
| `id` | 是 | `string` | 规范插件 id。这是 `plugins.entries.<id>` 中使用的 id。 |
| `configSchema` | 是 | `object` | 该插件配置的内联 JSON Schema。 |
| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略该字段，或将其设为任何非 `true` 的值，可使插件默认保持禁用。 |
| `legacyPluginIds` | 否 | `string[]` | 会规范化到该规范插件 id 的旧版 id。 |
| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提到这些提供商 id 时，应自动启用此插件。 |
| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明用于 `plugins.slots.*` 的互斥插件类型。 |
| `channels` | 否 | `string[]` | 此插件拥有的渠道 id。用于设备发现和配置校验。 |
| `providers` | 否 | `string[]` | 此插件拥有的提供商 id。 |
| `modelSupport` | 否 | `object` | 由清单持有的简写模型家族元数据，用于在运行时之前自动加载插件。 |
| `providerEndpoints` | 否 | `object[]` | 由清单持有的提供商路由端点 host / `baseUrl` 元数据，供核心在提供商运行时加载前进行分类。 |
| `cliBackends` | 否 | `string[]` | 由此插件拥有的 CLI 推理后端 ID。用于根据显式配置引用在启动时自动激活。 |
| `syntheticAuthRefs` | 否 | `string[]` | 在运行时加载前的冷启动模型发现期间，应探测其插件自有合成认证钩子的提供商或 CLI 后端引用。 |
| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件拥有的占位 API key 值，表示非机密的本地、OAuth 或环境凭证状态。 |
| `commandAliases` | 否 | `object[]` | 由此插件拥有的命令名，应在运行时加载前生成带插件感知的配置和 CLI 诊断信息。 |
| `providerEndpoints` | 否 | `object[]` | 由清单持有的端点主机 / `baseUrl` 元数据，用于 core 在提供商运行时加载前对提供商路由进行分类。 |
| `cliBackends` | 否 | `string[]` | 此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 |
| `syntheticAuthRefs` | 否 | `string[]` | 提供商或 CLI 后端引用；在运行时加载前的冷启动模型发现期间，应探测其由插件持有的 synthetic auth hook。 |
| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件持有的占位 API key 值，表示非机密的本地、OAuth 或环境凭证状态。 |
| `commandAliases` | 否 | `object[]` | 此插件拥有的命令名称；在运行时加载前，它们应生成带有插件感知的配置和 CLI 诊断信息。 |
| `providerAuthEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 无需加载插件代码即可检查的轻量提供商认证环境变量元数据。 |
| `providerAuthAliases` | 否 | `Record<string, string>` | 应复用另一个提供商 ID 进行认证查找的提供商 ID，例如与基础提供商共享 API key 和认证配置文件的编码提供商。 |
| `channelEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 无需加载插件代码即可检查的轻量渠道环境变量元数据。将其用于通用启动 / 配置辅助工具需要看到的、由环境变量驱动的渠道设置或认证界面。 |
| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI 标志接线的轻量认证选项元数据。 |
| `activation` | 否 | `object` | 针对提供商、命令、渠道、路由和能力触发加载的轻量激活提示。仅为元数据；实际行为仍由插件运行时负责。 |
| `setup` | 否 | `object` | 供发现和设置界面在不加载插件运行时的情况下检查的轻量设置 / 新手引导描述符。 |
| `providerAuthAliases` | 否 | `Record<string, string>` | 应复用另一个提供商 id 进行认证查找的提供商 id，例如与基础提供商 API key 和认证配置文件共享的 coding 提供商。 |
| `channelEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 无需加载插件代码即可检查的轻量渠道环境变量元数据。将其用于由环境变量驱动的渠道设置或认证界面，以便通用启动 / 配置辅助工具能够识别。 |
| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI 标志接线的轻量认证选择元数据。 |
| `activation` | 否 | `object` | 面向提供商、命令、渠道、路由和能力触发加载的轻量激活提示。仅为元数据；实际行为仍由插件运行时负责。 |
| `setup` | 否 | `object` | 设备发现和设置界面可在不加载插件运行时的情况下检查的轻量设置 / 新手引导描述符。 |
| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` 主机在插件运行时加载前使用的轻量 QA 运行器描述符。 |
| `contracts` | 否 | `object` | 用于语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页抓取、网页搜索和工具归属的静态内置能力快照。 |
| `mediaUnderstandingProviderMetadata` | 否 | `Record<string, object>` | 为 `contracts.mediaUnderstandingProviders` 中声明的提供商 ID 提供的轻量媒体理解默认值。 |
| `channelConfigs` | 否 | `Record<string, object>` | 由清单持有的渠道配置元数据，在运行时加载前合并到发现和校验界面中。 |
| `mediaUnderstandingProviderMetadata` | 否 | `Record<string, object>` | 为 `contracts.mediaUnderstandingProviders` 中声明的提供商 id 提供的轻量媒体理解默认值。 |
| `channelConfigs` | 否 | `Record<string, object>` | 由清单持有的渠道配置元数据，在运行时加载前合并到设备发现和校验界面中。 |
| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 |
| `name` | 否 | `string` | 人类可读的插件名称。 |
| `description` | 否 | `string` | 显示在插件界面中的简短摘要。 |
@ -177,26 +178,26 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
| 字段 | 必填 | 类型 | 含义 |
| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `provider` | 是 | `string` | 此选项所属的提供商 ID。 |
| `method` | 是 | `string` | 要分发到的认证方法 ID。 |
| `choiceId` | 是 | `string` | 由新手引导和 CLI 流程使用的稳定认证选项 ID。 |
| `provider` | 是 | `string` | 此选项所属的提供商 id。 |
| `method` | 是 | `string` | 要分发到的认证方式 id。 |
| `choiceId` | 是 | `string` | 由新手引导和 CLI 流程使用的稳定认证选项 id。 |
| `choiceLabel` | 否 | `string` | 面向用户的标签。如省略，OpenClaw 会回退到 `choiceId`。 |
| `choiceHint` | 否 | `string` | 选择器的简短辅助文本。 |
| `choiceHint` | 否 | `string` | 选择器中显示的简短辅助文本。 |
| `assistantPriority` | 否 | `number` | 在由助手驱动的交互式选择器中，值越小排序越靠前。 |
| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在助手选择器中隐藏该选项，但仍允许通过手动 CLI 选择。 |
| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选项的旧版选项 ID。 |
| `groupId` | 否 | `string` | 用于对相关选项进行分组的可选分组 ID。 |
| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在助手选择器中隐藏该选项，但仍允许手动通过 CLI 选择。 |
| `deprecatedChoiceIds` | 否 | `string[]` | 旧版选项 id；应将用户重定向到当前替代选项。 |
| `groupId` | 否 | `string` | 用于对相关选项分组的可选分组 id。 |
| `groupLabel` | 否 | `string` | 该分组面向用户的标签。 |
| `groupHint` | 否 | `string` | 该分组的简短辅助文本。 |
| `optionKey` | 否 | `string` | 用于简单单标志认证流程的内部选项键。 |
| `cliFlag` | 否 | `string` | CLI 标志名，例如 `--openrouter-api-key`。 |
| `cliFlag` | 否 | `string` | CLI 标志名称，例如 `--openrouter-api-key`。 |
| `cliOption` | 否 | `string` | 完整的 CLI 选项形式，例如 `--openrouter-api-key <key>`。 |
| `cliDescription` | 否 | `string` | CLI 帮助中使用的说明。 |
| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 该选项应显示在哪些新手引导界面中。如省略，默认值为 `["text-inference"]`。 |
| `cliDescription` | 否 | `string` | 用于 CLI 帮助信息中的说明。 |
| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 该选项应出现在哪些新手引导界面中。如省略，默认值为 `["text-inference"]`。 |
## `commandAliases` 参考
当插件拥有一个运行时命令名，而用户可能会误将其放入 `plugins.allow`，或尝试将其作为根级 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用此元数据进行诊断，而无需导入插件运行时代码。
当插件拥有某个运行时命令名称，而用户可能错误地将它放入 `plugins.allow` 中，或尝试将其作为根级 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用这些元数据生成诊断信息，而无需导入插件运行时代码。
```json
{
@ -214,7 +215,7 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
| ------------ | -------- | ----------------- | ----------------------------------------------------------------------- |
| `name` | 是 | `string` | 属于此插件的命令名称。 |
| `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天斜杠命令，而不是根级 CLI 命令。 |
| `cliCommand` | 否 | `string` | 若存在，用于建议 CLI 操作的相关根级 CLI 命令。 |
| `cliCommand` | 否 | `string` | 若存在，用于 CLI 操作时建议的相关根级 CLI 命令。 |
## `activation` 参考
@ -238,9 +239,9 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
| 字段 | 必填 | 类型 | 含义 |
| ------------- | -------- | -------- | ------------------------------------------------------------------ |
| `commandName` | 是 | `string` | 挂载在 `openclaw qa` 下的子命令，例如 `matrix`。 |
| `description` | 否 | `string` | 当共享主机需要一个桩命令时使用的后备帮助文本。 |
| `description` | 否 | `string` | 当共享主机需要一个 stub 命令时使用的回退帮助文本。 |
此块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时 / 插件入口点。当前使用方会在更广泛的插件加载之前将其用作缩小范围的提示，因此缺少激活元数据通常只会带来性能损失；在旧版清单归属回退机制仍存在时，它不应改变正确性。
此区块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时 / 插件入口点。当前使用方会在更广泛的插件加载前将其用作缩小范围的提示，因此缺少激活元数据通常只会带来性能成本；在旧版清单归属回退机制仍存在时，它不应改变正确性。
```json
{
@ -256,21 +257,21 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
| 字段 | 必填 | 类型 | 含义 |
| ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
| `onProviders` | 否 | `string[]` | 请求这些提供商 ID 时应激活此插件。 |
| `onCommands` | 否 | `string[]` | 应激活此插件的命令 ID。 |
| `onChannels` | 否 | `string[]` | 应激活此插件的渠道 ID。 |
| `onProviders` | 否 | `string[]` | 请求这些提供商 id 时，应激活此插件。 |
| `onCommands` | 否 | `string[]` | 应激活此插件的命令 id。 |
| `onChannels` | 否 | `string[]` | 应激活此插件的渠道 id。 |
| `onRoutes` | 否 | `string[]` | 应激活此插件的路由类型。 |
| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的宽泛能力提示。 |
| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划所用的宽泛能力提示。 |
当前在线使用方：
- 由命令触发的 CLI 规划会回退到旧版的 `commandAliases[].cliCommand` 或 `commandAliases[].name`
- 由命令触发的 CLI 规划会回退到旧版 `commandAliases[].cliCommand` 或 `commandAliases[].name`
- 当缺少显式渠道激活元数据时，渠道触发的设置 / 渠道规划会回退到旧版 `channels[]` 归属
- 当缺少显式提供商激活元数据时，提供商触发的设置 / 运行时规划会回退到旧版的 `providers[]` 和顶层 `cliBackends[]` 归属
- 当缺少显式提供商激活元数据时，提供商触发的设置 / 运行时规划会回退到旧版 `providers[]` 和顶层 `cliBackends[]` 归属
## `setup` 参考
当设置和新手引导界面需要在运行时加载前获取由插件拥有的轻量元数据时，请使用 `setup`。
当设置和新手引导界面需要在运行时加载前获取由插件持有的轻量元数据时，请使用 `setup`。
```json
{
@ -289,32 +290,32 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
}
```
顶层 `cliBackends` 仍然有效，并继续描述 CLI 推理后端。`setup.cliBackends` 是面向控制平面 / 设置流程的、仅元数据的设置专用描述符界面。
顶层 `cliBackends` 依然有效，并继续描述 CLI 推理后端。`setup.cliBackends` 是设置专用的描述符界面，供应保持为纯元数据的控制平面 / 设置流程使用。
存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现时优先使用的“描述符优先”查找界面。如果该描述符只能缩小候选插件范围，而设置仍需要更丰富的设置期运行时钩子，请设置 `requiresRuntime: true`，并保留 `setup-api` 作为后备执行路径。
当存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现的首选“描述符优先”查找界面。如果描述符只能缩小候选插件范围，而设置仍需要更丰富的设置期运行时 hook，请设置 `requiresRuntime: true`，并保留 `setup-api` 作为回退执行路径。
由于设置查找可能会执行由插件拥有的 `setup-api` 代码，规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值在所有已发现插件之间必须保持唯一。归属不明确时会采用失败即关闭的方式，而不是按照发现顺序选择一个“胜出者”。
由于设置查找可能执行插件持有的 `setup-api` 代码，因此规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在已发现插件之间保持唯一。若归属存在歧义，系统会以保守方式失败，而不是按发现顺序挑选一个赢家。
### `setup.providers` 参考
| 字段 | 必填 | 类型 | 含义 |
| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ |
| `id` | 是 | `string` | 在设置或新手引导期间暴露的提供商 ID。请保持规范化 ID 在全局范围内唯一。 |
| `authMethods` | 否 | `string[]` | 该提供商在无需加载完整运行时的情况下支持的设置 / 认证方法 ID。 |
| `id` | 是 | `string` | 在设置或新手引导期间公开的提供商 id。请保持规范化 id 在全局范围内唯一。 |
| `authMethods` | 否 | `string[]` | 此提供商在无需加载完整运行时的情况下支持的设置 / 认证方式 id。 |
| `envVars` | 否 | `string[]` | 通用设置 / 状态界面可在插件运行时加载前检查的环境变量。 |
### `setup` 字段
| 字段 | 必填 | 类型 | 含义 |
| ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- |
| `providers` | 否 | `object[]` | 在设置和新手引导期间暴露的提供商设置描述符。 |
| `cliBackends` | 否 | `string[]` | 用于“描述符优先”设置查找的设置期后端 ID。请保持规范化 ID 在全局范围内唯一。 |
| `configMigrations` | 否 | `string[]` | 属于此插件设置界面的配置迁移 ID。 |
| `requiresRuntime` | 否 | `boolean` | 描述符查找后，设置是否仍需要执行 `setup-api`。 |
| `providers` | 否 | `object[]` | 在设置和新手引导期间公开的提供商设置描述符。 |
| `cliBackends` | 否 | `string[]` | 用于“描述符优先”设置查找的设置期后端 id。请保持规范化 id 在全局范围内唯一。 |
| `configMigrations` | 否 | `string[]` | 由该插件设置界面持有的配置迁移 id。 |
| `requiresRuntime` | 否 | `boolean` | 在描述符查找之后，设置是否仍需要执行 `setup-api`。 |
## `uiHints` 参考
`uiHints` 是从配置字段名到小型渲染提示的映射。
`uiHints` 是一个从配置字段名映射到小型渲染提示的映射表。
```json
{
@ -335,18 +336,19 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
| ------------- | ---------- | --------------------------------------- |
| `label` | `string` | 面向用户的字段标签。 |
| `help` | `string` | 简短辅助文本。 |
| `tags` | `string[]` | 可选 UI 标签。 |
| `advanced` | `boolean` | 将该字段标记为高级项。 |
| `tags` | `string[]` | 可选的 UI 标签。 |
| `advanced` | `boolean` | 将该字段标记为高级选项。 |
| `sensitive` | `boolean` | 将该字段标记为机密或敏感。 |
| `placeholder` | `string` | 表单输入的占位文本。 |
## `contracts` 参考
仅将 `contracts` 用于 OpenClaw 无需导入插件运行时即可读取的静态能力归属元数据。
仅在 OpenClaw 无需导入插件运行时即可读取的静态能力归属元数据场景中使用 `contracts`。
```json
{
"contracts": {
"embeddedExtensionFactories": ["pi"],
"speechProviders": ["openai"],
"realtimeTranscriptionProviders": ["openai"],
"realtimeVoiceProviders": ["openai"],
@ -363,20 +365,21 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
每个列表都是可选的：
| 字段 | 类型 | 含义 |
| -------------------------------- | ---------- | -------------------------------------------------------------- |
| `speechProviders` | `string[]` | 此插件拥有的语音提供商 ID。 |
| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转录提供商 ID。 |
| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音提供商 ID。 |
| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解提供商 ID。 |
| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成提供商 ID。 |
| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成提供商 ID。 |
| `webFetchProviders` | `string[]` | 此插件拥有的网页抓取提供商 ID。 |
| `webSearchProviders` | `string[]` | 此插件拥有的网页搜索提供商 ID。 |
| `tools` | `string[]` | 此插件拥有的智能体工具名称，用于内置契约检查。 |
| -------------------------------- | ---------- | ----------------------------------------------------------------- |
| `embeddedExtensionFactories` | `string[]` | 内置插件可为其注册工厂的嵌入式运行时 id。 |
| `speechProviders` | `string[]` | 此插件拥有的语音提供商 id。 |
| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转录提供商 id。 |
| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音提供商 id。 |
| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解提供商 id。 |
| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成提供商 id。 |
| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成提供商 id。 |
| `webFetchProviders` | `string[]` | 此插件拥有的 Web 抓取提供商 id。 |
| `webSearchProviders` | `string[]` | 此插件拥有的 Web 搜索提供商 id。 |
| `tools` | `string[]` | 在内置契约检查中，此插件拥有的智能体工具名称。 |
## `mediaUnderstandingProviderMetadata` 参考
当媒体理解提供商具有默认模型、自动认证回退优先级，或 generic core helpers 在运行时加载前需要的原生文档支持时，请使用 `mediaUnderstandingProviderMetadata`。键也必须在 `contracts.mediaUnderstandingProviders` 中声明。
当媒体理解提供商具有默认模型、自动认证回退优先级，或 generic core 辅助工具在运行时加载前所需的原生文档支持时，请使用 `mediaUnderstandingProviderMetadata`。键名也必须在 `contracts.mediaUnderstandingProviders` 中声明。
```json
{
@ -403,14 +406,14 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
| 字段 | 类型 | 含义 |
| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- |
| `capabilities` | `("image" \| "audio" \| "video")[]` | 此提供商暴露的媒体能力。 |
| `defaultModels` | `Record<string, string>` | 当配置未指定模型时使用的“能力到模型”默认值。 |
| `autoPriority` | `Record<string, number>` | 用于基于凭证自动回退提供商时，数字越小排序越靠前。 |
| `nativeDocumentInputs` | `"pdf"[]` | 提供商支持的原生文档输入。 |
| `capabilities` | `("image" \| "audio" \| "video")[]` | 此提供商公开的媒体能力。 |
| `defaultModels` | `Record<string, string>` | 当配置未指定模型时使用的“能力到模型”默认映射。 |
| `autoPriority` | `Record<string, number>` | 用于基于凭证的自动提供商回退时，数值越小排序越靠前。 |
| `nativeDocumentInputs` | `"pdf"[]` | 该提供商支持的原生文档输入。 |
## `channelConfigs` 参考
当渠道插件需要在运行时加载前提供轻量配置元数据时，请使用 `channelConfigs`。
当渠道插件在运行时加载前需要轻量配置元数据时，请使用 `channelConfigs`。
```json
{
@ -441,15 +444,15 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
| 字段 | 类型 | 含义 |
| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
| `schema` | `object` | `channels.<id>` 的 JSON Schema。每个声明的渠道配置条目都必须提供。 |
| `uiHints` | `Record<string, object>` | 该渠道配置部分可选的 UI 标签 / 占位符 / 敏感性提示。 |
| `schema` | `object` | `channels.<id>` 的 JSON Schema。对每个已声明的渠道配置条目来说都是必填。 |
| `uiHints` | `Record<string, object>` | 该渠道配置区块可选的 UI 标签 / 占位符 / 敏感性提示。 |
| `label` | `string` | 当运行时元数据尚未就绪时，合并到选择器和检查界面中的渠道标签。 |
| `description` | `string` | 用于检查和目录界面的简短渠道说明。 |
| `preferOver` | `string[]` | 在选择界面中应优先于其显示的旧版或低优先级插件 ID。 |
| `description` | `string` | 用于检查和目录界面的简短渠道描述。 |
| `preferOver` | `string[]` | 在选择界面中，此渠道应优先于的旧版或较低优先级插件 id。 |
## `modelSupport` 参考
当 OpenClaw 应在插件运行时加载前，根据 `gpt-5.4` 或 `claude-sonnet-4.6` 这类简写模型 ID 推断你的提供商插件时，请使用 `modelSupport`。
当 OpenClaw 应在插件运行时加载前，根据诸如 `gpt-5.4` 或 `claude-sonnet-4.6` 之类的简写模型 id 推断你的提供商插件时，请使用 `modelSupport`。
```json
{
@ -471,55 +474,55 @@ OpenClaw 采用以下优先级：
| 字段 | 类型 | 含义 |
| --------------- | ---------- | ------------------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | 对简写模型 ID 使用 `startsWith` 进行匹配的前缀。 |
| `modelPatterns` | `string[]` | 在移除 profile 后缀后，对简写模型 ID 进行匹配的正则表达式源码。 |
| `modelPrefixes` | `string[]` | 使用 `startsWith` 对简写模型 id 进行匹配的前缀。 |
| `modelPatterns` | `string[]` | 在移除配置文件后缀后，对简写模型 id 进行匹配的正则表达式源码。 |
旧版顶层能力键已弃用。请使用 `openclaw doctor --fix` 将 `speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；正常的清单加载已不再将这些顶层字段视为能力归属。
旧版顶层能力字段已弃用。请使用 `openclaw doctor --fix` 将 `speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；正常清单加载已不再将这些顶层字段视为能力归属。
## 清单与 package.json 的区别
## 清单与 `package.json` 的区别
这两个文件负责不同的工作：
这两个文件承担不同职责：
| 文件 | 用途 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | 发现、配置校验、认证选项元数据，以及必须在插件代码运行前存在的 UI 提示 |
| `openclaw.plugin.json` | 设备发现、配置校验、认证选项元数据，以及在插件代码运行前必须存在的 UI 提示 |
| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 配置块 |
如果你不确定某项元数据应放在哪里，请使用以下规则：
如果你不确定某条元数据应放在哪里，请使用以下规则：
- 如果 OpenClaw 必须在加载插件代码之前知道它，就放在 `openclaw.plugin.json` 中
- 如果它与打包、入口文件或 npm 安装行为有关，就放在 `package.json` 中
- 如果 OpenClaw 必须在加载插件代码前知道它，就放入 `openclaw.plugin.json`
- 如果它与打包、入口文件或 npm 安装行为有关，就放入 `package.json`
### 影响发现的 `package.json` 字段
### 会影响设备发现的 `package.json` 字段
一些运行时前的插件元数据刻意放在 `package.json` 的 `openclaw` 配置块下，而不是 `openclaw.plugin.json` 中。
某些运行时前插件元数据被有意放在 `package.json` 的 `openclaw` 配置块下，而不是 `openclaw.plugin.json` 中。
重要示例：
| 字段 | 含义 |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `openclaw.extensions` | 声明原生插件入口点。必须保留在插件包目录内。 |
| `openclaw.runtimeExtensions` | 为已安装包声明已构建的 JavaScript 运行时入口点。必须保留在插件包目录内。 |
| `openclaw.setupEntry` | 在新手引导、延迟渠道启动和只读渠道状态 / SecretRef 发现期间使用的轻量、仅设置入口点。必须保留在插件包目录内。 |
| `openclaw.runtimeSetupEntry` | 为已安装包声明已构建的 JavaScript 设置入口点。必须保留在插件包目录内。 |
| `openclaw.channel` | 轻量渠道目录元数据，例如标签、文档路径、别名和选择说明文本。 |
| `openclaw.channel.configuredState` | 轻量配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅环境变量驱动的设置？”。 |
| `openclaw.channel.persistedAuthState` | 轻量持久化认证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何账号登录？”。 |
| `openclaw.extensions` | 声明原生插件入口点。必须保持在插件包目录内。 |
| `openclaw.runtimeExtensions` | 为已安装包声明构建后的 JavaScript 运行时入口点。必须保持在插件包目录内。 |
| `openclaw.setupEntry` | 在新手引导、延迟渠道启动以及只读渠道状态 / SecretRef 发现期间使用的轻量仅设置入口点。必须保持在插件包目录内。 |
| `openclaw.runtimeSetupEntry` | 为已安装包声明构建后的 JavaScript 设置入口点。必须保持在插件包目录内。 |
| `openclaw.channel` | 轻量渠道目录元数据，例如标签、文档路径、别名和选择文案。 |
| `openclaw.channel.configuredState` | 轻量已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅基于环境变量的设置？”。 |
| `openclaw.channel.persistedAuthState` | 轻量持久化认证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何内容处于已登录状态？”。 |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 内置插件和外部发布插件的安装 / 更新提示。 |
| `openclaw.install.defaultChoice` | 存在多个安装来源时的首选安装路径。 |
| `openclaw.install.minHostVersion` | 支持的最低 OpenClaw host 版本，使用诸如 `>=2026.3.22` 这样的 semver 下限。 |
| `openclaw.install.defaultChoice` | 当有多个安装来源可用时的首选安装路径。 |
| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用类似 `>=2026.3.22` 的 semver 下限。 |
| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许使用一条受限的内置插件重新安装恢复路径。 |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间先加载仅设置的渠道界面，再加载完整渠道插件。 |
`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。无效值会被拒绝；值若有效但要求版本更新，则在旧 host 上跳过该插件。
`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。无效值会被拒绝；在较旧主机上，较新但有效的值会导致跳过该插件。
当状态、渠道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账号时，渠道插件应提供 `openclaw.setupEntry`。设置入口点应暴露渠道元数据，以及对设置安全的配置、状态和 secrets 适配器；网络客户端、Gateway 网关监听器和传输运行时应保留在主扩展入口点中。
渠道插件应提供 `openclaw.setupEntry`，以便在状态、渠道列表或 SecretRef 扫描需要识别已配置账户时，无需加载完整运行时。设置入口点应公开渠道元数据，以及适用于设置阶段的安全配置、状态和密钥适配器；网络客户端、Gateway 网关监听器和传输运行时应保留在主扩展入口点中。
运行时入口点字段不会覆盖源码入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能让一个越界的 `openclaw.extensions` 路径变得可加载。
运行时入口点字段不会绕过源码入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能让一个越界的 `openclaw.extensions` 路径变得可加载。
`openclaw.install.allowInvalidConfigRecovery` 的设计本身就是受限的。它不会让任意损坏的配置变得可安装。当前它只允许安装流程从特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，或该内置插件对应的陈旧 `channels.<id>` 条目。无关的配置错误仍会阻止安装，并将操作人员引导到 `openclaw doctor --fix`。
`openclaw.install.allowInvalidConfigRecovery` 的设计刻意保持为窄范围。它不会让任意损坏的配置都变得可安装。当前它仅允许安装流程从某些特定的陈旧内置插件升级故障中恢复，例如缺失的内置插件路径，或同一个内置插件对应的陈旧 `channels.<id>` 条目。无关的配置错误仍会阻止安装，并将操作人员引导到 `openclaw doctor --fix`。
`openclaw.channel.persistedAuthState` 是一个指向微型检查器模块的包元数据：
`openclaw.channel.persistedAuthState` 是针对一个微型检查模块的包元数据：
```json
{
@ -535,9 +538,9 @@ OpenClaw 采用以下优先级：
}
```
当设置、Doctor 或配置状态流程需要在完整渠道插件加载前进行轻量的“是 / 否”认证探测时，请使用它。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 来转发它。
当设置、Doctor 或已配置状态流程需要在完整渠道插件加载前进行一个低成本的“是 / 否”认证探测时，请使用它。目标导出应是一个仅读取持久化状态的小函数；不要通过完整渠道运行时 barrel 转发它。
`openclaw.channel.configuredState` 对轻量的、仅环境变量驱动的配置状态检查使用相同的结构：
`openclaw.channel.configuredState` 也采用相同结构，用于低成本的仅环境变量已配置检查：
```json
{
@ -553,57 +556,57 @@ OpenClaw 采用以下优先级：
}
```
当渠道可以从环境变量或其他微型的非运行时输入回答配置状态时，请使用它。如果检查需要完整的配置解析或真实的渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState` hook 中。
当一个渠道可以仅通过环境变量或其他微型非运行时输入来回答已配置状态时，请使用它。如果检查需要完整配置解析或真实的渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState` hook 中。
## 发现优先级（重复的插件 ID）
## 设备发现优先级（重复插件 id）
OpenClaw 会从多个根目录发现插件（内置、全局安装、工作区、配置中显式选择的路径）。如果两个发现结果共享相同的 `id`，则只保留**优先级最高**的清单；较低优先级的重复项会被丢弃，而不是与其并行加载。
OpenClaw 会从多个根目录发现插件（内置、全局安装、工作区、配置中显式选择的路径）。如果两次发现共享同一个 `id`，则只保留**优先级最高**的清单；较低优先级的重复项会被丢弃，而不是与其并行加载。
优先级从高到低如下：
1. **配置中选择的** —— 在 `plugins.entries.<id>` 中显式固定的路径
2. **内置** —— 随 OpenClaw 一起分发的插件
3. **全局安装** —— 安装到全局 OpenClaw 插件根目录的插件
1. **配置选定** —— 在 `plugins.entries.<id>` 中显式固定的路径
2. **内置** —— 随 OpenClaw 一同发布的插件
3. **全局安装** —— 安装到全局 OpenClaw 插件根目录中的插件
4. **工作区** —— 相对于当前工作区发现的插件
影响：
- 工作区中某个内置插件的 fork 或陈旧副本，不会覆盖内置版本。
- 如果你确实要用本地插件覆盖内置插件，请通过 `plugins.entries.<id>` 固定它的路径，让它依靠优先级胜出，而不是依赖工作区发现。
- 被丢弃的重复项会记录日志，这样 Doctor 和启动诊断就可以指出被舍弃的副本。
- 工作区中某个内置插件的 fork 或陈旧副本不会遮蔽内置构建。
- 如果你确实要用本地插件覆盖内置插件，请通过 `plugins.entries.<id>` 固定它，使其凭借优先级获胜，而不是依赖工作区发现。
- 重复项被丢弃会记录日志，以便 Doctor 和启动诊断可以指出被舍弃的副本。
## JSON Schema 要求
- **每个插件都必须提供一个 JSON Schema**，即使它不接受任何配置。
- 可以接受空 schema（例如 `{ "type": "object", "additionalProperties": false }`）。
- 空 schema 也是允许的（例如 `{ "type": "object", "additionalProperties": false }`）。
- Schema 会在配置读写时校验，而不是在运行时校验。
## 校验行为
- 未知的 `channels.*` 键会被视为**错误**，除非该渠道 ID 已由某个插件清单声明。
- `plugins.entries.<id>`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现的**插件 ID。未知 ID 会被视为**错误**。
- 如果插件已安装，但其清单或 schema 缺失或损坏，则校验会失败，Doctor 会报告该插件错误。
- 如果插件配置存在，但插件处于**禁用**状态，则配置会被保留，并在 Doctor 和日志中显示**警告**。
- 未知的 `channels.*` 键是**错误**，除非该渠道 id 已由某个插件清单声明。
- `plugins.entries.<id>`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现的**插件 id。未知 id 属于**错误**。
- 如果某个插件已安装，但其清单或 schema 缺失或损坏，校验会失败，Doctor 会报告该插件错误。
- 如果插件配置存在，但插件处于**禁用**状态，则配置会被保留，并且 Doctor 与日志中会显示一条**警告**。
完整的 `plugins.*` schema 请参见[配置参考](/zh-CN/gateway/configuration)。
完整的 `plugins.*` schema 请参阅[配置参考](/zh-CN/gateway/configuration)。
## 说明
## 注意事项
- 对于原生 OpenClaw 插件，包括本地文件系统加载，清单都是**必需的**。
- 运行时仍会单独加载插件模块；清单仅用于发现和校验。
- 原生清单使用 JSON5 解析，因此注释、尾随逗号和未加引号的键都是可接受的，只要最终值仍然是对象。
- 清单加载器只会读取文档中说明的清单字段。避免在这里添加自定义顶层键。
- `providerAuthEnvVars` 是用于认证探测、环境变量标记校验，以及其他类似提供商认证界面的轻量元数据路径；这些场景不应仅仅为了检查环境变量名称而启动插件运行时。
- `providerAuthAliases` 允许提供商变体复用另一个提供商的认证环境变量、认证配置文件、基于配置的认证，以及 API key 新手引导选项，而无需在核心中硬编码这种关系。
- `providerEndpoints` 允许提供商插件拥有简单的端点 host / `baseUrl` 匹配元数据。仅在核心已支持的端点类别中使用它；实际运行时行为仍由插件负责。
- `syntheticAuthRefs` 是用于提供商自有合成认证 hook 的轻量元数据路径，这些 hook 必须在运行时注册表存在之前就对冷启动模型发现可见。只列出那些其运行时提供商或 CLI 后端实际实现了 `resolveSyntheticAuth` 的引用。
- `nonSecretAuthMarkers` 是用于由内置插件拥有的占位 API key 的轻量元数据路径，例如本地、OAuth 或环境凭证标记。核心会将这些值视为非机密，用于认证显示和密钥审计，而无需硬编码所属提供商。
- `channelEnvVars` 是用于 shell 环境变量回退、设置提示，以及类似渠道界面的轻量元数据路径；这些场景不应仅仅为了检查环境变量名称而启动插件运行时。环境变量名称只是元数据，本身并不构成激活：状态、审计、cron 投递校验以及其他只读界面，在将某个环境变量视为已配置渠道之前，仍会应用插件信任和有效激活策略。
- `providerAuthChoices` 是在提供商运行时加载前，用于认证选项选择器、`--auth-choice` 解析、首选提供商映射，以及简单新手引导 CLI 标志注册的轻量元数据路径。有关需要提供商代码的运行时向导元数据，请参见[提供商运行时 hook](/zh-CN/plugins/architecture#provider-runtime-hooks)。
- 独占插件类型通过 `plugins.slots.*` 选择。
- 清单对于**原生 OpenClaw 插件**是**必需的**，包括本地文件系统加载。
- 运行时仍会单独加载插件模块；清单仅用于设备发现 + 校验。
- 原生清单使用 JSON5 解析，因此只要最终值仍是一个对象，就接受注释、尾随逗号和未加引号的键。
- 清单加载器只读取已文档化的清单字段。避免在此添加自定义顶层键。
- `providerAuthEnvVars` 是用于认证探测、环境变量标记校验，以及类似提供商认证界面的轻量元数据路径；这些场景不应仅为了检查环境变量名称而启动插件运行时。
- `providerAuthAliases` 允许提供商变体复用另一个提供商的认证环境变量、认证配置文件、基于配置的认证以及 API key 新手引导选项，而无需在 core 中硬编码这种关系。
- `providerEndpoints` 允许提供商插件持有简单的端点主机 / `baseUrl` 匹配元数据。仅将其用于 core 已支持的端点类别；实际运行时行为仍由插件负责。
- `syntheticAuthRefs` 是用于提供商持有的 synthetic auth hook 的轻量元数据路径；这些 hook 必须在运行时注册表存在之前，对冷启动模型发现可见。只列出那些其运行时提供商或 CLI 后端实际实现了 `resolveSyntheticAuth` 的引用。
- `nonSecretAuthMarkers` 是用于内置插件持有的占位 API key 的轻量元数据路径，例如本地、OAuth 或环境凭证标记。Core 会将这些值视为非机密，用于认证显示和密钥审计，而无需硬编码其所属提供商。
- `channelEnvVars` 是用于 shell 环境变量回退、设置提示以及类似渠道界面的轻量元数据路径；这些场景不应仅为了检查环境变量名称而启动插件运行时。环境变量名称只是元数据，本身不构成激活：状态、审计、定时任务投递校验以及其他只读界面，在将某个环境变量视为已配置渠道前，仍会应用插件信任与有效激活策略。
- `providerAuthChoices` 是用于认证选项选择器、`--auth-choice` 解析、首选提供商映射，以及在提供商运行时加载前注册简单新手引导 CLI 标志的轻量元数据路径。对于需要提供商代码的运行时向导元数据，请参阅[提供商运行时 hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。
- 互斥插件类型通过 `plugins.slots.*` 选择。
- `kind: "memory"` 通过 `plugins.slots.memory` 选择。
- `kind: "context-engine"` 通过 `plugins.slots.contextEngine` 选择（默认：内置 `legacy`）。
- 当插件不需要时，可以省略 `channels`、`providers`、`cliBackends` 和 `skills`。
- `kind: "context-engine"` 通过 `plugins.slots.contextEngine` 选择（默认值：内置 `legacy`）。
- 当插件不需要 `channels`、`providers`、`cliBackends` 和 `skills` 时，可以省略这些字段。
- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器允许列表要求（例如 pnpm `allow-build-scripts`
- `pnpm rebuild <package>`）。

413
docs/zh-CN/plugins/sdk-overview.md
View File

@ -1,60 +1,60 @@
---
read_when:
- 你需要知道应从哪个 SDK 子路径导入
- 你想查看 OpenClawPluginApi 上所有注册方法的参考资料
- 你正在查找某个特定的 SDK 导出项
- 你想查看 OpenClawPluginApi 上所有注册方法的参考文档
- 你正在查找某个特定的 SDK 导出内容
sidebarTitle: SDK Overview
summary: Import map、注册 API 参考和 SDK 架构
title: 插件 SDK 概览
x-i18n:
generated_at: "2026-04-22T01:34:41Z"
generated_at: "2026-04-22T07:00:33Z"
model: gpt-5.4
provider: openai
source_hash: 8045c11976bbda6afe3303a0aab08caf0d0a86ebcf1aaaf927943b90cc517673
source_hash: e57019e6f9a7fed7842ac575e025b6db41d125f5fa9d0d1de03923fdb1f6bcc3
source_path: plugins/sdk-overview.md
workflow: 15
---
# 插件 SDK 概览
插件 SDK 是插件与核心之间的类型化契约。本页是关于**应导入什么**以及**你可以注册什么**的参考资料。
插件 SDK 是插件与核心之间的类型化契约。本页是关于**导入什么**以及**你可以注册什么**的参考文档。
<Tip>
**在找操作指南吗？**
- 第一个插件？从 [入门指南](/zh-CN/plugins/building-plugins) 开始
- 渠道插件？参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)
- 提供商插件？参见 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)
**在找操作指南？**
- 第一个插件？从[入门指南](/zh-CN/plugins/building-plugins)开始
- 渠道插件？参见[渠道插件](/zh-CN/plugins/sdk-channel-plugins)
- 提供商插件？参见[提供商插件](/zh-CN/plugins/sdk-provider-plugins)
</Tip>
## 导入约定
始终从特定的子路径导入：
始终从特定子路径导入：
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
每个子路径都是一个小型、独立的模块。这样可以保持快速启动，并防止循环依赖问题。对于特定于渠道的入口/构建辅助工具，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总括性表面和共享辅助工具，例如 `buildChannelConfigSchema`。
每个子路径都是一个小型、自包含的模块。这样可以保持快速启动，并防止循环依赖问题。对于渠道专用的入口/构建辅助工具，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总括性表面和共享辅助工具，例如 `buildChannelConfigSchema`。
不要添加或依赖带有提供商名称的便捷接缝，例如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或带有渠道品牌的辅助工具接缝。内置插件应在其自身的 `api.ts` 或 `runtime-api.ts` barrel 中组合通用 SDK 子路径，而核心则应使用这些插件本地 barrel，或者在需求确实跨渠道时添加一个狭义的通用 SDK 契约。
不要添加或依赖带提供商名称的便捷接缝，例如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或带渠道品牌的辅助接缝。内置插件应在它们自己的 `api.ts` 或 `runtime-api.ts` barrel 中组合通用 SDK 子路径；而核心要么应使用这些插件本地的 barrel，要么应在需求确实跨渠道时添加一个狭义的通用 SDK 契约。
生成的导出映射仍然包含一小部分内置插件辅助工具接缝，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些子路径仅为内置插件维护和兼容性而存在；它们有意未包含在下面的通用表格中，也不是新第三方插件的推荐导入路径。
生成的导出映射仍然包含一小部分内置插件辅助接缝，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些子路径仅用于内置插件维护和兼容性；它们在下面的通用表格中被有意省略，也不是新第三方插件推荐的导入路径。
## 子路径参考
最常用的子路径，按用途分组。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json` 中。
最常用的子路径，按用途分组。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`。
保留的内置插件辅助工具子路径仍会出现在该生成列表中。除非某个文档页面明确将其推广为公共接口，否则应将其视为实现细节/兼容性表面。
保留的内置插件辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其提升为公开接口，否则应将其视为实现细节/兼容性表面。
### 插件入口
| 子路径 | 关键导出 |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| 子路径 | 关键导出 |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
<AccordionGroup>
<Accordion title="渠道子路径">
@ -67,20 +67,20 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | 多账户 config/action-gate 辅助工具、默认账户回退辅助工具 |
| `plugin-sdk/account-core` | 多账户配置/操作门控辅助工具、默认账户回退辅助工具 |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助工具 |
| `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助工具 |
| `plugin-sdk/account-helpers` | 狭义的账户列表/账户操作辅助工具 |
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | 渠道 config schema 类型 |
| `plugin-sdk/telegram-command-config` | 带有内置契约回退的 Telegram 自定义命令规范化/验证辅助工具 |
| `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 |
| `plugin-sdk/telegram-command-config` | 带内置契约回退的 Telegram 自定义命令规范化/校验辅助工具 |
| `plugin-sdk/command-gating` | 狭义的命令授权门控辅助工具 |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/最终化辅助工具 |
| `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建器辅助工具 |
| `plugin-sdk/inbound-reply-dispatch` | 共享入站记录并分发辅助工具 |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/完成辅助工具 |
| `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助工具 |
| `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助工具 |
| `plugin-sdk/messaging-targets` | 目标解析/匹配辅助工具 |
| `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 |
| `plugin-sdk/outbound-runtime` | 出站身份、发送委托和负载规划辅助工具 |
@ -88,26 +88,26 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
| `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助工具 |
| `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 |
| `plugin-sdk/conversation-runtime` | 会话/线程绑定、配对和已配置绑定辅助工具 |
| `plugin-sdk/runtime-config-snapshot` | 运行时 config 快照辅助工具 |
| `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 |
| `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 |
| `plugin-sdk/channel-status` | 共享渠道状态快照/摘要辅助工具 |
| `plugin-sdk/channel-config-primitives` | 狭义的渠道 config-schema 原语 |
| `plugin-sdk/channel-config-writes` | 渠道 config 写入授权辅助工具 |
| `plugin-sdk/channel-config-primitives` | 狭义的渠道配置 schema 基元 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 |
| `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 |
| `plugin-sdk/allowlist-config-edit` | allowlist config 编辑/读取辅助工具 |
| `plugin-sdk/group-access` | 共享群组访问决策辅助工具 |
| `plugin-sdk/direct-dm` | 共享直接私信授权/守卫辅助工具 |
| `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递和旧版交互式回复辅助工具。参见 [消息呈现](/zh-CN/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | 用于入站防抖、提及匹配、提及策略辅助工具和 envelope 辅助工具的兼容性 barrel |
| `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取辅助工具 |
| `plugin-sdk/group-access` | 共享群组访问判定辅助工具 |
| `plugin-sdk/direct-dm` | 共享直接私信认证/保护辅助工具 |
| `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递和旧版交互式回复辅助工具。参见[消息呈现](/zh-CN/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | 入站去抖、提及匹配、提及策略辅助工具和 envelope 辅助工具的兼容性 barrel |
| `plugin-sdk/channel-mention-gating` | 不含更广泛入站运行时表面的狭义提及策略辅助工具 |
| `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助工具 |
| `plugin-sdk/channel-logging` | 用于入站丢弃和 typing/ack 失败的渠道日志辅助工具 |
| `plugin-sdk/channel-logging` | 用于入站丢弃和输入中/确认失败的渠道日志辅助工具 |
| `plugin-sdk/channel-send-result` | 回复结果类型 |
| `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生 schema 辅助工具 |
| `plugin-sdk/channel-targets` | 目标解析/匹配辅助工具 |
| `plugin-sdk/channel-contract` | 渠道契约类型 |
| `plugin-sdk/channel-feedback` | 反馈/reaction 接线 |
| `plugin-sdk/channel-secret-runtime` | 狭义的密钥契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和 secret target 类型 |
| `plugin-sdk/channel-feedback` | 反馈/反应接线 |
| `plugin-sdk/channel-secret-runtime` | 狭义的密钥契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和密钥目标类型 |
</Accordion>
<Accordion title="提供商子路径">
@ -118,138 +118,138 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
| `plugin-sdk/self-hosted-provider-setup` | 专注于 OpenAI 兼容自托管提供商的设置辅助工具 |
| `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 |
| `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API key 解析辅助工具 |
| `plugin-sdk/provider-auth-api-key` | API key 新手引导/profile-write 辅助工具，例如 `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-api-key` | API key 新手引导/配置文件写入辅助工具，例如 `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | 标准 OAuth auth-result 构建器 |
| `plugin-sdk/provider-auth-login` | 提供商插件的共享交互式登录辅助工具 |
| `plugin-sdk/provider-env-vars` | 提供商凭证环境变量查找辅助工具 |
| `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具，以及如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助工具 |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具，以及模型 ID 规范化辅助工具，例如 `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | 通用提供商 HTTP/endpoint 能力辅助工具 |
| `plugin-sdk/provider-web-fetch-contract` | 狭义的 web-fetch config/selection 契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册/缓存辅助工具 |
| `plugin-sdk/provider-web-search-config-contract` | 适用于不需要插件启用接线的提供商的狭义 web-search config/credential 辅助工具 |
| `plugin-sdk/provider-web-search-contract` | 狭义的 web-search config/credential 契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 和作用域化 credential setter/getter |
| `plugin-sdk/provider-web-search` | web-search 提供商注册/缓存/运行时辅助工具 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + diagnostics，以及 xAI 兼容性辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 等 |
| `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助工具 |
| `plugin-sdk/provider-web-fetch-contract` | 狭义的 web-fetch 配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Web-fetch 提供商注册/缓存辅助工具 |
| `plugin-sdk/provider-web-search-config-contract` | 适用于不需要插件启用接线的提供商的狭义 web-search 配置/凭证辅助工具 |
| `plugin-sdk/provider-web-search-contract` | 狭义的 web-search 配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及有作用域的凭证 setter/getter |
| `plugin-sdk/provider-web-search` | Web 搜索提供商注册/缓存/运行时辅助工具 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似功能 |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 |
| `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受保护的 fetch、传输消息变换和可写传输事件流 |
| `plugin-sdk/provider-onboard` | 新手引导 config patch 辅助工具 |
| `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受保护的 fetch、传输消息转换和可写传输事件流 |
| `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 |
| `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助工具 |
</Accordion>
<Accordion title="凭证和安全子路径">
<Accordion title="认证与安全子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送者授权辅助工具 |
| `plugin-sdk/command-status` | 命令/帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天 action-auth 辅助工具 |
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile/filter 辅助工具 |
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天操作认证辅助工具 |
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件/过滤器辅助工具 |
| `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 |
| `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 |
| `plugin-sdk/approval-handler-adapter-runtime` | 用于热渠道入口点的轻量级原生审批适配器加载辅助工具 |
| `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；在适用时优先使用更狭义的 adapter/gateway 接缝 |
| `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；如果更狭义的 adapter/gateway 接缝已足够，优先使用它们 |
| `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 |
| `plugin-sdk/approval-reply-runtime` | exec/plugin 审批回复负载辅助工具 |
| `plugin-sdk/command-auth-native` | 原生命令凭证 + 原生会话目标辅助工具 |
| `plugin-sdk/approval-reply-runtime` | exec/插件审批回复负载辅助工具 |
| `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助工具 |
| `plugin-sdk/command-detection` | 共享命令检测辅助工具 |
| `plugin-sdk/command-surface` | 命令体规范化和命令表面辅助工具 |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | 用于渠道/插件密钥表面的狭义 secret-contract 收集辅助工具 |
| `plugin-sdk/secret-ref-runtime` | 用于 secret-contract/config 解析的狭义 `coerceSecretRef` 和 SecretRef 类型辅助工具 |
| `plugin-sdk/channel-secret-runtime` | 面向渠道/插件密钥表面的狭义密钥契约收集辅助工具 |
| `plugin-sdk/secret-ref-runtime` | 用于密钥契约/配置解析的狭义 `coerceSecretRef` 和 SecretRef 类型辅助工具 |
| `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和密钥收集辅助工具 |
| `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 |
| `plugin-sdk/ssrf-dispatcher` | 不含广泛基础设施运行时表面的狭义 pinned-dispatcher 辅助工具 |
| `plugin-sdk/ssrf-dispatcher` | 不带广泛基础设施运行时表面的狭义 pinned-dispatcher 辅助工具 |
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch 和 SSRF 策略辅助工具 |
| `plugin-sdk/secret-input` | 密钥输入解析辅助工具 |
| `plugin-sdk/webhook-ingress` | Webhook 请求/目标辅助工具 |
| `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助工具 |
</Accordion>
<Accordion title="运行时和存储子路径">
<Accordion title="运行时与存储子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/runtime` | 广泛的运行时/日志/备份/插件安装辅助工具 |
| `plugin-sdk/runtime-env` | 狭义的运行时 env、logger、timeout、retry 和 backoff 辅助工具 |
| `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助工具 |
| `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助工具 |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | 共享插件命令/hook/http/interactive 辅助工具 |
| `plugin-sdk/plugin-runtime` | 共享插件命令/hook/http/交互式辅助工具 |
| `plugin-sdk/hook-runtime` | 共享 webhook/内部 hook 管道辅助工具 |
| `plugin-sdk/lazy-runtime` | 延迟运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
| `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | 进程 exec 辅助工具 |
| `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助工具 |
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态 patch 辅助工具 |
| `plugin-sdk/config-runtime` | config 加载/写入辅助工具 |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约表面不可用时也可使用 |
| `plugin-sdk/text-autolink-runtime` | 不含广泛 text-runtime barrel 的文件引用自动链接检测 |
| `plugin-sdk/approval-runtime` | exec/plugin 审批辅助工具、审批能力构建器、凭证/profile 辅助工具、原生路由/运行时辅助工具 |
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助工具 |
| `plugin-sdk/config-runtime` | 配置加载/写入辅助工具 |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化和重复/冲突检查，即使内置 Telegram 契约表面不可用时也适用 |
| `plugin-sdk/text-autolink-runtime` | 不带广泛 text-runtime barrel 的文件引用自动链接检测 |
| `plugin-sdk/approval-runtime` | exec/插件审批辅助工具、审批能力构建器、认证/配置文件辅助工具、原生路由/运行时辅助工具 |
| `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块、分发、heartbeat、回复规划器 |
| `plugin-sdk/reply-dispatch-runtime` | 狭义的回复分发/最终化辅助工具 |
| `plugin-sdk/reply-history` | 共享短窗口回复历史辅助工具，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-dispatch-runtime` | 狭义的回复分发/完成辅助工具 |
| `plugin-sdk/reply-history` | 共享短时间窗口回复历史辅助工具，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | 狭义的文本/Markdown 分块辅助工具 |
| `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助工具 |
| `plugin-sdk/state-paths` | State/OAuth 目录路径辅助工具 |
| `plugin-sdk/state-paths` | state/OAuth 目录路径辅助工具 |
| `plugin-sdk/routing` | 路由/会话键/账户绑定辅助工具，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | 共享渠道/账户状态摘要辅助工具、运行时状态默认值和问题元数据辅助工具 |
| `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助工具 |
| `plugin-sdk/string-normalization-runtime` | slug/字符串规范化辅助工具 |
| `plugin-sdk/request-url` | 从 fetch/request 类输入中提取字符串 URL |
| `plugin-sdk/run-command` | 带计时的命令运行器，带规范化的 stdout/stderr 结果 |
| `plugin-sdk/run-command` | 带计时功能的命令运行器，输出经规范化的 stdout/stderr 结果 |
| `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 |
| `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化负载 |
| `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 |
| `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 |
| `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助工具 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助工具 |
| `plugin-sdk/json-store` | 小型 JSON state 读写辅助工具 |
| `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 |
| `plugin-sdk/file-lock` | 可重入文件锁辅助工具 |
| `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 |
| `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助工具 |
| `plugin-sdk/acp-binding-resolve-runtime` | 不含生命周期启动导入的只读 ACP 绑定解析 |
| `plugin-sdk/agent-config-primitives` | 狭义的智能体运行时 config-schema 原语 |
| `plugin-sdk/acp-binding-resolve-runtime` | 不带生命周期启动导入的只读 ACP 绑定解析 |
| `plugin-sdk/agent-config-primitives` | 狭义的智能体运行时配置 schema 基元 |
| `plugin-sdk/boolean-param` | 宽松布尔参数读取器 |
| `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 |
| `plugin-sdk/device-bootstrap` | 设备 bootstrap 和配对令牌辅助工具 |
| `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助原语 |
| `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 |
| `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助基元 |
| `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 |
| `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助工具 |
| `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 |
| `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助工具 |
| `plugin-sdk/agent-harness` | 面向低级智能体 harness 的实验性可信插件表面：harness 类型、活动运行 steer/abort 辅助工具、OpenClaw 工具桥接辅助工具和尝试结果实用工具 |
| `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助工具 |
| `plugin-sdk/agent-harness` | 面向受信任插件的实验性低层智能体 harness 表面：harness 类型、活动运行 steer/abort 辅助工具、OpenClaw 工具桥接辅助工具以及尝试结果实用工具 |
| `plugin-sdk/provider-zai-endpoint` | Z.A.I 端点检测辅助工具 |
| `plugin-sdk/infra-runtime` | 系统事件/heartbeat 辅助工具 |
| `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 |
| `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 |
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | 包装的 fetch、代理和 pinned 查找辅助工具 |
| `plugin-sdk/runtime-fetch` | 不含 proxy/guarded-fetch 导入的 dispatcher-aware 运行时 fetch |
| `plugin-sdk/response-limit-runtime` | 不含广泛 media runtime 表面的有界响应体读取器 |
| `plugin-sdk/session-binding-runtime` | 不含已配置绑定路由或配对存储的当前会话绑定状态 |
| `plugin-sdk/session-store-runtime` | 不含广泛 config 写入/维护导入的会话存储读取辅助工具 |
| `plugin-sdk/context-visibility-runtime` | 不含广泛 config/security 导入的上下文可见性解析和补充上下文过滤 |
| `plugin-sdk/string-coerce-runtime` | 不含 Markdown/logging 导入的狭义原始记录/字符串强制转换和规范化辅助工具 |
| `plugin-sdk/fetch-runtime` | 包装后的 fetch、proxy 和 pinned lookup 辅助工具 |
| `plugin-sdk/runtime-fetch` | 不带 proxy/guarded-fetch 导入的 dispatcher 感知型运行时 fetch |
| `plugin-sdk/response-limit-runtime` | 不带广泛 media 运行时表面的有界响应体读取器 |
| `plugin-sdk/session-binding-runtime` | 不带已配置绑定路由或配对存储的当前会话绑定状态 |
| `plugin-sdk/session-store-runtime` | 不带广泛配置写入/维护导入的会话存储读取辅助工具 |
| `plugin-sdk/context-visibility-runtime` | 不带广泛配置/安全导入的上下文可见性解析和补充上下文过滤 |
| `plugin-sdk/string-coerce-runtime` | 不带 Markdown/日志导入的狭义原始记录/字符串强制转换和规范化辅助工具 |
| `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 |
| `plugin-sdk/retry-runtime` | 重试 config 和重试运行器辅助工具 |
| `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 |
| `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助工具 |
| `plugin-sdk/directory-runtime` | 基于 config 的目录查询/去重 |
| `plugin-sdk/directory-runtime` | 基于配置的目录查询/去重 |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="能力和测试子路径">
<Accordion title="能力与测试子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具以及媒体负载构建器 |
| `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具，以及媒体负载构建器 |
| `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选项选择和缺失模型消息 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助导出 |
| `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如面向助手可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本实用工具 |
| `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如面向 assistant 可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本实用工具 |
| `plugin-sdk/text-chunking` | 出站文本分块辅助工具 |
| `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和验证辅助工具 |
| `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助工具 |
| `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和规范化辅助工具 |
| `plugin-sdk/realtime-transcription` | 实时转录提供商类型和注册表辅助工具 |
| `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 |
| `plugin-sdk/image-generation` | 图像生成提供商类型 |
| `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、凭证和注册表辅助工具 |
| `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助工具 |
| `plugin-sdk/music-generation` | 音乐生成提供商/请求/结果类型 |
| `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 |
| `plugin-sdk/video-generation` | 视频生成提供商/请求/结果类型 |
@ -258,18 +258,18 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
| `plugin-sdk/webhook-path` | Webhook 路径规范化辅助工具 |
| `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助工具 |
| `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`、`shouldAckReaction` |
</Accordion>
<Accordion title="Memory 子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/memory-core` | 内置的 memory-core 辅助工具表面，用于 manager/config/file/CLI 辅助工具 |
| `plugin-sdk/memory-core` | 内置 memory-core 辅助表面，用于 manager/config/file/CLI 辅助工具 |
| `plugin-sdk/memory-core-engine-runtime` | Memory 索引/搜索运行时外观 |
| `plugin-sdk/memory-core-host-engine-foundation` | Memory host 基础引擎导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商，以及通用 batch/remote 辅助工具 |
| `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD 引擎导出 |
| `plugin-sdk/memory-core-host-engine-storage` | Memory host 存储引擎导出 |
| `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商以及通用批处理/远程辅助工具 |
| `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出 |
| `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine 导出 |
| `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助工具 |
| `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 |
| `plugin-sdk/memory-core-host-secret` | Memory host 密钥辅助工具 |
@ -278,79 +278,82 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
| `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件/运行时辅助工具 |
| `plugin-sdk/memory-host-core` | 面向供应商中立的别名，用于 memory host 核心运行时辅助工具 |
| `plugin-sdk/memory-host-events` | 面向供应商中立的别名，用于 memory host 事件日志辅助工具 |
| `plugin-sdk/memory-host-files` | 面向供应商中立的别名，用于 memory host 文件/运行时辅助工具 |
| `plugin-sdk/memory-host-markdown` | 用于 memory 相邻插件的共享托管 Markdown 辅助工具 |
| `plugin-sdk/memory-host-core` | 面向厂商中立的 Memory host 核心运行时辅助工具别名 |
| `plugin-sdk/memory-host-events` | 面向厂商中立的 Memory host 事件日志辅助工具别名 |
| `plugin-sdk/memory-host-files` | 面向厂商中立的 Memory host 文件/运行时辅助工具别名 |
| `plugin-sdk/memory-host-markdown` | 用于与 memory 相邻插件的共享托管 Markdown 辅助工具 |
| `plugin-sdk/memory-host-search` | 用于 search-manager 访问的活动 Memory 运行时外观 |
| `plugin-sdk/memory-host-status` | 面向供应商中立的别名，用于 memory host 状态辅助工具 |
| `plugin-sdk/memory-lancedb` | 内置的 memory-lancedb 辅助工具表面 |
| `plugin-sdk/memory-host-status` | 面向厂商中立的 Memory host 状态辅助工具别名 |
| `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助表面 |
</Accordion>
<Accordion title="保留的内置辅助工具子路径">
| 系列 | 当前子路径 | 预期用途 |
<Accordion title="保留的内置辅助子路径">
| 家族 | 当前子路径 | 预期用途 |
| --- | --- | --- |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 Browser 插件支持辅助工具（`browser-support` 仍是兼容性 barrel） |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助工具/运行时表面 |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助工具/运行时表面 |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助工具表面 |
| 渠道特定辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性/辅助工具接缝 |
| 凭证/插件特定辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助工具接缝；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 browser 插件支持辅助工具（`browser-support` 仍是兼容性 barrel） |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时表面 |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助/运行时表面 |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助表面 |
| 渠道专用辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性/辅助接缝 |
| 认证/插件专用辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助接缝；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
## 注册 API
`register(api)` 回调会接收一个 `OpenClawPluginApi` 对象，其中包含这些方法：
`register(api)` 回调会接收一个带有以下方法的 `OpenClawPluginApi` 对象：
### 能力注册
| 方法 | 注册内容 |
| ------------------------------------------------ | ------------------------------- |
| `api.registerProvider(...)` | 文本推理（LLM） |
| `api.registerAgentHarness(...)` | 实验性的低级智能体执行器 |
| `api.registerCliBackend(...)` | 本地 CLI 推理后端 |
| `api.registerChannel(...)` | 消息渠道 |
| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 |
| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 |
| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 |
| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 |
| `api.registerImageGenerationProvider(...)` | 图像生成 |
| `api.registerMusicGenerationProvider(...)` | 音乐生成 |
| `api.registerVideoGenerationProvider(...)` | 视频生成 |
| `api.registerWebFetchProvider(...)` | Web 获取 / 抓取提供商 |
| `api.registerWebSearchProvider(...)` | Web 搜索 |
| 方法 | 注册内容 |
| ------------------------------------------------ | ------------------------------------- |
| `api.registerProvider(...)` | 文本推理（LLM） |
| `api.registerAgentHarness(...)` | 实验性的低层智能体执行器 |
| `api.registerCliBackend(...)` | 本地 CLI 推理后端 |
| `api.registerChannel(...)` | 消息渠道 |
| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 |
| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 |
| `api.registerRealtimeVoiceProvider(...)` | 双向实时语音会话 |
| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 |
| `api.registerImageGenerationProvider(...)` | 图像生成 |
| `api.registerMusicGenerationProvider(...)` | 音乐生成 |
| `api.registerVideoGenerationProvider(...)` | 视频生成 |
| `api.registerWebFetchProvider(...)` | Web 抓取 / 抓取提供商 |
| `api.registerWebSearchProvider(...)` | Web 搜索 |
### 工具和命令
| 方法 | 注册内容 |
| 方法 | 注册内容 |
| ------------------------------- | --------------------------------------------- |
| `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） |
| `api.registerCommand(def)` | 自定义命令（绕过 LLM） |
| `api.registerTool(tool, opts?)` | 智能体工具（必需，或 `{ optional: true }`） |
| `api.registerCommand(def)` | 自定义命令（绕过 LLM） |
### 基础设施
| 方法 | 注册内容 |
| ---------------------------------------------- | ------------------------------- |
| `api.registerHook(events, handler, opts?)` | 事件 hook |
| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 |
| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 |
| `api.registerCli(registrar, opts?)` | CLI 子命令 |
| `api.registerService(service)` | 后台服务 |
| `api.registerInteractiveHandler(registration)` | 交互式处理器 |
| `api.registerMemoryPromptSupplement(builder)` | 附加的 memory 相邻提示部分 |
| `api.registerMemoryCorpusSupplement(adapter)` | 附加的 memory 搜索/读取语料库 |
| 方法 | 注册内容 |
| ----------------------------------------------- | --------------------------------------- |
| `api.registerHook(events, handler, opts?)` | 事件 hook |
| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 |
| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 |
| `api.registerCli(registrar, opts?)` | CLI 子命令 |
| `api.registerService(service)` | 后台服务 |
| `api.registerInteractiveHandler(registration)` | 交互式处理器 |
| `api.registerEmbeddedExtensionFactory(factory)` | Pi 内嵌运行器扩展工厂 |
| `api.registerMemoryPromptSupplement(builder)` | 可叠加的 memory 相邻提示区段 |
| `api.registerMemoryCorpusSupplement(adapter)` | 可叠加的 memory 搜索/读取语料库 |
保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试为其分配更窄的 Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用插件特定前缀。
保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件拥有的方法，优先使用插件专属前缀。
当插件在 OpenClaw 内嵌运行期间需要 Pi 原生事件时序时，请使用 `api.registerEmbeddedExtensionFactory(...)`，例如必须在最终工具结果消息发出之前完成的异步 `tool_result` 重写。这目前是一个内置插件接缝：只有内置插件可以注册它，并且它们必须在 `openclaw.plugin.json` 中声明 `contracts.embeddedExtensionFactories: ["pi"]`。对于不需要该更底层接缝的所有情况，继续使用普通 OpenClaw 插件 hooks。
### CLI 注册元数据
`api.registerCli(registrar, opts?)` 接受两类顶层元数据：
- `commands`：由 registrar 拥有的显式命令根
- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析期命令描述符
- `descriptors`：用于根 CLI 帮助、路由和惰性插件 CLI 注册的解析时命令描述符
如果你希望插件命令在正常的根 CLI 路径中保持延迟加载，请提供 `descriptors`，覆盖该 registrar 暴露的每一个顶层命令根。
如果你希望插件命令在正常的根 CLI 路径中保持惰性加载，请提供 `descriptors`，覆盖该 registrar 暴露的每个顶层命令根。
```typescript
api.registerCli(
@ -362,7 +365,7 @@ api.registerCli(
descriptors: [
{
name: "matrix",
description: "管理 Matrix 账户、验证、设备和 profile 状态",
description: "管理 Matrix 账户、验证、设备和配置文件状态",
hasSubcommands: true,
},
],
@ -370,72 +373,72 @@ api.registerCli(
);
```
仅当你不需要延迟根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍然受支持，但它不会为解析期延迟加载安装基于 descriptor 的占位符。
只有在你不需要惰性根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍受支持，但它不会为解析时惰性加载安装基于 descriptor 的占位符。
### CLI 后端注册
`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（例如 `codex-cli`）的默认 config。
`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（例如 `codex-cli`）的默认配置。
- 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。
- 后端 `config` 使用与 `agents.defaults.cliBackends.<id>` 相同的结构。
- 用户 config 仍然优先生效。OpenClaw 会在运行 CLI 之前，将 `agents.defaults.cliBackends.<id>` 合并到插件默认值之上。
- 当后端在合并后需要兼容性重写时，使用 `normalizeConfig`（例如规范化旧的 flag 结构）。
- 用户配置仍然优先。OpenClaw 会在运行 CLI 之前，将 `agents.defaults.cliBackends.<id>` 合并到插件默认值之上。
- 当后端在合并后需要兼容性重写时，请使用 `normalizeConfig`（例如规范化旧版 flag 结构）。
### 独占槽位
| 方法 | 注册内容 |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | 上下文引擎（一次仅一个活动）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便引擎能够定制提示附加内容。 |
| `api.registerMemoryCapability(capability)` | 统一 Memory 能力 |
| `api.registerMemoryPromptSection(builder)` | Memory 提示部分构建器 |
| `api.registerMemoryFlushPlan(resolver)` | Memory 刷新计划解析器 |
| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 |
| 方法 | 注册内容 |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | 上下文引擎（一次只激活一个）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便引擎可以定制提示补充内容。 |
| `api.registerMemoryCapability(capability)` | 统一 Memory 能力 |
| `api.registerMemoryPromptSection(builder)` | Memory 提示区段构建器 |
| `api.registerMemoryFlushPlan(resolver)` | Memory flush plan 解析器 |
| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 |
### Memory embedding 适配器
| 方法 | 注册内容 |
| ---------------------------------------------- | ---------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 Memory embedding 适配器 |
| 方法 | 注册内容 |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 Memory embedding 适配器 |
- `registerMemoryCapability` 是首选的独占 memory 插件 API。
- `registerMemoryCapability` 也可以暴露 `publicArtifacts.listArtifacts(...)`，这样配套插件就可以通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的 memory 工件，而不是深入特定 memory 插件的私有布局。
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占 memory 插件 API。
- `registerMemoryEmbeddingProvider` 允许活动 memory 插件注册一个或多个 embedding 适配器 id（例如 `openai`、`gemini` 或插件自定义 id）。
- 用户 config（例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）会针对这些已注册的适配器 id 进行解析。
- `registerMemoryCapability` 是首选的独占 Memory 插件 API。
- `registerMemoryCapability` 还可以暴露 `publicArtifacts.listArtifacts(...)`，这样配套插件就可以通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的 Memory 工件，而不是深入某个特定 Memory 插件的私有布局。
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占 Memory 插件 API。
- `registerMemoryEmbeddingProvider` 允许活动 Memory 插件注册一个或多个 embedding 适配器 ID（例如 `openai`、`gemini` 或插件自定义的 ID）。
- 用户配置（例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）会针对这些已注册的适配器 ID 进行解析。
### 事件和生命周期
### 事件与生命周期
| 方法 | 作用 |
| -------------------------------------------- | ----------------------- |
| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook |
| `api.onConversationBindingResolved(handler)` | 会话绑定回调 |
| 方法 | 作用 |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook |
| `api.onConversationBindingResolved(handler)` | 会话绑定回调 |
### Hook 决策语义
- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置它，就会跳过更低优先级的处理器。
- `before_tool_call`：返回 `{ block: false }` 会被视为未作出决定（与省略 `block` 相同），而不是作为覆盖。
- `before_install`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置它，就会跳过更低优先级的处理器。
- `before_install`：返回 `{ block: false }` 会被视为未作出决定（与省略 `block` 相同），而不是作为覆盖。
- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦任意处理器声明已分发，就会跳过更低优先级的处理器以及默认的模型分发路径。
- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦任意处理器设置它，就会跳过更低优先级的处理器。
- `message_sending`：返回 `{ cancel: false }` 会被视为未作出决定（与省略 `cancel` 相同），而不是作为覆盖。
- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦任一处理器设置了它，就会跳过较低优先级的处理器。
- `before_tool_call`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。
- `before_install`：返回 `{ block: true }` 是终止性的。一旦任一处理器设置了它，就会跳过较低优先级的处理器。
- `before_install`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。
- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦任一处理器声明接管分发，就会跳过较低优先级的处理器和默认模型分发路径。
- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦任一处理器设置了它，就会跳过较低优先级的处理器。
- `message_sending`：返回 `{ cancel: false }` 会被视为未作决定（与省略 `cancel` 相同），而不是覆盖。
### API 对象字段
| 字段 | 类型 | 描述 |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------ |
| `api.id` | `string` | 插件 id |
| `api.name` | `string` | 显示名称 |
| `api.version` | `string?` | 插件版本（可选） |
| `api.description` | `string?` | 插件描述（可选） |
| `api.source` | `string` | 插件源路径 |
| `api.rootDir` | `string?` | 插件根目录（可选） |
| `api.config` | `OpenClawConfig` | 当前 config 快照（可用时为活动的内存中运行时快照） |
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件专属 config |
| `api.runtime` | `PluginRuntime` | [运行时辅助工具](/zh-CN/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | 作用域化 logger（`debug`、`info`、`warn`、`error`） |
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置之前的轻量级预启动/设置窗口 |
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
| 字段 | 类型 | 描述 |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | 插件 ID |
| `api.name` | `string` | 显示名称 |
| `api.version` | `string?` | 插件版本（可选） |
| `api.description` | `string?` | 插件描述（可选） |
| `api.source` | `string` | 插件源路径 |
| `api.rootDir` | `string?` | 插件根目录（可选） |
| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动内存运行时快照） |
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件专属配置 |
| `api.runtime` | `PluginRuntime` | [运行时辅助工具](/zh-CN/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | 有作用域的 logger（`debug`、`info`、`warn`、`error`） |
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置前的轻量窗口 |
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
## 内部模块约定
@ -443,41 +446,41 @@ api.registerCli(
```
my-plugin/
api.ts # 面向外部使用者的公共导出
api.ts # 面向外部使用者的公开导出
runtime-api.ts # 仅供内部使用的运行时导出
index.ts # 插件入口点
setup-entry.ts # 仅设置用的轻量入口（可选）
```
<Warning>
绝不要在生产代码中通过 `openclaw/plugin-sdk/<your-plugin>`
导入你自己的插件。应通过 `./api.ts` 或
不要在生产代码中通过 `openclaw/plugin-sdk/<your-plugin>`
导入你自己的插件。请通过 `./api.ts` 或
`./runtime-api.ts` 路由内部导入。SDK 路径仅是外部契约。
</Warning>
由 facade 加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）现在在 OpenClaw 已经运行时会优先使用活动运行时 config 快照。如果运行时快照尚不存在，它们会回退到磁盘上已解析的 config 文件。
通过 facade 加载的内置插件公开表面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公开入口文件）现在会在 OpenClaw 已经运行时优先使用活动运行时配置快照。如果运行时快照尚不存在，则会回退到磁盘上已解析的配置文件。
当某个辅助工具是有意保持提供商专属、且暂时还不适合放入通用 SDK 子路径时，提供商插件也可以暴露一个狭义的插件本地契约 barrel。当前的内置示例：Anthropic 提供商将其 Claude 流辅助工具保留在自己的公共 `api.ts` / `contract-api.ts` 接缝中，而不是把 Anthropic beta-header 和 `service_tier` 逻辑提升到通用的 `plugin-sdk/*` 契约中。
当某个辅助工具是有意保持提供商专属、且暂时还不适合放入通用 SDK 子路径时，提供商插件也可以暴露一个狭义的插件本地契约 barrel。当前内置示例：Anthropic 提供商将其 Claude 流辅助工具保留在自己的公开 `api.ts` / `contract-api.ts` 接缝中，而不是将 Anthropic beta-header 和 `service_tier` 逻辑提升到通用 `plugin-sdk/*` 契约中。
其他当前的内置示例：
其他当前内置示例：
- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、
默认模型辅助工具，以及实时提供商构建器
默认模型辅助工具以及实时提供商构建器
- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及
新手引导/config 辅助工具
新手引导/配置辅助工具
<Warning>
扩展生产代码也应避免导入 `openclaw/plugin-sdk/<other-plugin>`。
如果某个辅助工具确实需要共享，应将其提升到一个中立的 SDK 子路径，
如果某个辅助工具确实需要共享，请将它提升到中立的 SDK 子路径，
例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或其他
面向能力的表面，而不是将两个插件耦合在一起。
面向能力的表面，而不是把两个插件耦合在一起。
</Warning>
## 相关内容
- [入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 和 `defineChannelPluginEntry` 选项
- [运行时辅助工具](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考
- [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、manifest、config schema
- [测试](/zh-CN/plugins/sdk-testing) — 测试工具和 lint 规则
- [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、清单、配置 schema
- [测试](/zh-CN/plugins/sdk-testing) — 测试实用工具和 lint 规则
- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用表面迁移
- [插件内部机制](/zh-CN/plugins/architecture) — 深入的架构和能力模型
- [插件内部机制](/zh-CN/plugins/architecture) — 深入架构和能力模型