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-07 20:11:24 +00:00
parent 61ab907171
commit 66dd652e7d
4 changed files with 941 additions and 891 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

958
docs/zh-CN/plugins/architecture.md
View File

File diff suppressed because it is too large Load Diff

229
docs/zh-CN/plugins/sdk-channel-plugins.md
View File

@ -1,160 +1,160 @@
---
read_when:
- 你正在构建一个新的消息渠道插件
- 你想将 OpenClaw 连接到一个消息平台
- 你需要理解 ChannelPlugin 适配器接口
- 你想要将 OpenClaw 连接到某个消息平台
- 你需要理解 `ChannelPlugin` 适配器表面
sidebarTitle: Channel Plugins
summary: 构建 OpenClaw 消息渠道插件的分步指南
title: 构建渠道插件
x-i18n:
generated_at: "2026-04-07T18:43:13Z"
generated_at: "2026-04-07T20:09:06Z"
model: gpt-5.4
provider: openai
source_hash: b709fda7527fcf437b119c4668172804f2f9c9a46f5e39a2161467a4f5f1e42f
source_hash: d23365b6d92006b30e671f9f0afdba40a2b88c845c5d2299d71c52a52985672f
source_path: plugins/sdk-channel-plugins.md
workflow: 15
---
# 构建渠道插件
本指南将带你逐步构建一个将 OpenClaw 连接到消息平台的渠道插件。完成后，你将拥有一个可用的渠道，支持私信安全、配对、回复线程和出站消息。
本指南将带你完成一个渠道插件的构建，该插件用于将 OpenClaw 连接到某个消息平台。完成后，你将拥有一个可正常工作的渠道，具备私信安全、配对、回复线程和出站消息能力。
<Info>
如果你之前还没有构建过任何 OpenClaw 插件，请先阅读
[入门指南](/zh-CN/plugins/building-plugins) 以了解基础的软件包结构和清单设置。
[入门指南](/zh-CN/plugins/building-plugins) 以了解基础包结构和清单设置。
</Info>
## 渠道插件如何工作
渠道插件不需要自己的发送/编辑/反应工具。OpenClaw 在核心中保留了一个共享的 `message` 工具。你的插件负责：
- **配置** — 账户解析和设置向导
- **配置** — 账号解析和设置向导
- **安全** — 私信策略和允许列表
- **配对** — 私信批准流程
- **会话语法** — 提供商特定的会话 id 如何映射到基础聊天、线程 id 和父级回退
- **出站** — 向平台发送文本、媒体和投票
- **线程** — 回复如何串入线程
- **线程** — 回复如何在线程中组织
核心负责共享的消息工具、提示词接线、外层会话键形状、通用的 `:thread:` 记录以及分发。
核心负责共享消息工具、提示词接线、外层会话键形状、通用的 `:thread:` 记录，以及分发。
如果你的平台在会话 id 中存储了额外作用域，请将该解析逻辑保留在插件中，并使用 `messaging.resolveSessionConversation(...)`。这是将 `rawId` 映射为基础会话 id、可选线程 id、显式 `baseConversationId` 以及任意 `parentConversationCandidates` 的规范钩子。
当你返回 `parentConversationCandidates` 时，请按从最窄父级到最宽/基础会话的顺序排列。
如果你的平台会在会话 id 中存储额外的作用域，请将该解析逻辑保留在插件中，使用 `messaging.resolveSessionConversation(...)`。这是将 `rawId` 映射到基础会话 id、可选线程 id、显式 `baseConversationId` 和任何 `parentConversationCandidates` 的规范钩子。
当你返回 `parentConversationCandidates` 时，请保持它们按从最窄父级到最宽/基础会话的顺序排列。
需要在渠道注册表启动前进行相同解析的内置插件，也可以暴露一个顶层 `session-key-api.ts` 文件，并导出匹配的 `resolveSessionConversation(...)`。只有在运行时插件注册表尚不可用时，核心才会使用这个对引导安全的接口。
需要在渠道注册表启动前执行相同解析的内置插件，也可以公开一个顶层 `session-key-api.ts` 文件，并导出匹配的 `resolveSessionConversation(...)`。只有当运行时插件注册表尚不可用时，核心才会使用这个可安全引导的表面。
当插件只需要在通用/原始 id 之上提供父级回退时，`messaging.resolveParentConversationCandidates(...)` 仍可作为旧版兼容回退使用。如果两个钩子都存在，核心会优先使用 `resolveSessionConversation(...).parentConversationCandidates`，仅当该规范钩子未提供这些值时，才回退到 `resolveParentConversationCandidates(...)`。
当插件只需要在通用/原始 id 之上提供父级回退时，`messaging.resolveParentConversationCandidates(...)` 仍可作为旧版兼容回退使用。如果两个钩子都存在，核心会先使用
`resolveSessionConversation(...).parentConversationCandidates`，只有当规范钩子省略它们时，才会回退到 `resolveParentConversationCandidates(...)`。
## 批准和渠道能力
大多数渠道插件不需要批准专用代码。
大多数渠道插件不需要编写与批准特定相关的代码。
- 核心负责同一聊天中的 `/approve`、共享的批准按钮负载，以及通用回退投递。
- 当渠道需要批准专用行为时，优先在渠道插件上使用单个 `approvalCapability` 对象。
- `ChannelPlugin.approvals` 已被移除。请将批准投递/原生/渲染/认证相关信息放到 `approvalCapability` 上。
- `plugin.auth` 仅用于登录/登出；核心不再从该对象中读取批准认证钩子。
- `approvalCapability.authorizeActorAction` 和 `approvalCapability.getActionAvailabilityState` 是规范的批准认证接口。
- 对于同一聊天中的批准认证可用性，请使用 `approvalCapability.getActionAvailabilityState`。
- 如果你的渠道暴露原生 exec 批准，当其与同一聊天批准认证不同时，请使用 `approvalCapability.getExecInitiatingSurfaceState` 来表示发起界面/原生客户端状态。核心使用这个 exec 专用钩子来区分 `enabled` 与 `disabled`、判断发起渠道是否支持原生 exec 批准，并在原生客户端回退指引中包含该渠道。`createApproverRestrictedNativeApprovalCapability(...)` 可为常见场景补齐这一点。
- 对于渠道专用的负载生命周期行为，例如隐藏重复的本地批准提示或在投递前发送输入中指示，请使用 `outbound.shouldSuppressLocalPayloadPrompt` 或 `outbound.beforeDeliverPayload`。
- 核心负责同聊天内的 `/approve`、共享批准按钮负载，以及通用回退投递。
- 当渠道需要与批准相关的特定行为时，优先在渠道插件上使用一个 `approvalCapability` 对象。
- `ChannelPlugin.approvals` 已移除。将批准投递/原生/渲染/授权相关信息放到 `approvalCapability` 上。
- `plugin.auth` 仅用于登录/登出；核心不再从该对象读取批准授权钩子。
- `approvalCapability.authorizeActorAction` 和 `approvalCapability.getActionAvailabilityState` 是规范的批准授权扩展点。
- 对于同聊天批准授权可用性，使用 `approvalCapability.getActionAvailabilityState`。
- 如果你的渠道公开原生 exec 批准，请在其与同聊天批准授权不同时，使用 `approvalCapability.getExecInitiatingSurfaceState` 表示发起表面/原生客户端状态。核心会使用这个 exec 专用钩子来区分 `enabled` 与 `disabled`，判断发起渠道是否支持原生 exec 批准，并在原生客户端回退指引中包含该渠道。`createApproverRestrictedNativeApprovalCapability(...)` 为常见场景填充了这一点。
- 对于渠道特定的负载生命周期行为，例如隐藏重复的本地批准提示或在投递前发送输入中指示，请使用 `outbound.shouldSuppressLocalPayloadPrompt` 或 `outbound.beforeDeliverPayload`。
- 仅将 `approvalCapability.delivery` 用于原生批准路由或回退抑制。
- 对于由渠道持有的原生批准信息，请使用 `approvalCapability.nativeRuntime`。在热门渠道入口点上，请通过 `createLazyChannelApprovalNativeRuntimeAdapter(...)` 保持其惰性加载，它可以按需导入你的运行时模块，同时仍让核心组装批准生命周期。
- 仅当渠道确实需要自定义批准负载而不是共享渲染器时，才使用 `approvalCapability.render`。
- 当渠道希望禁用路径回复解释启用原生 exec 批准所需的确切配置项时，请使用 `approvalCapability.describeExecApprovalSetup`。该钩子接收 `{ channel, channelLabel, accountId }`；具名账户渠道应渲染带账户作用域的路径，例如 `channels.<channel>.accounts.<id>.execApprovals.*`，而不是顶层默认值。
- 如果渠道可以从现有配置中推断出稳定的类所有者私信身份，请使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createResolvedApproverActionAuthAdapter` 来限制同一聊天中的 `/approve`，而无需添加批准专用的核心逻辑。
- 如果渠道需要原生批准投递，请让渠道代码专注于目标规范化以及传输/呈现相关事实。请使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver` 和 `createApproverRestrictedNativeApprovalCapability`。将渠道特定事实放到 `approvalCapability.nativeRuntime` 后面，最好通过 `createChannelApprovalNativeRuntimeAdapter(...)` 或 `createLazyChannelApprovalNativeRuntimeAdapter(...)`，这样核心就可以组装处理器，并负责请求过滤、路由、去重、过期、Gateway 网关订阅以及“已在其他位置路由”的通知。`nativeRuntime` 被拆分为几个更小的接口：
- `availability` — 账户是否已配置，以及某个请求是否应被处理
- `presentation` — 将共享的批准视图模型映射为待处理/已解决/已过期的原生负载或最终动作
- `transport` — 准备目标，并发送/更新/删除原生批准消息
- `interactions` — 原生按钮或反应的可选 bind/unbind/clear-action 钩子
- 将 `approvalCapability.nativeRuntime` 用于渠道自有的原生批准信息。对于高频渠道入口点，请通过 `createLazyChannelApprovalNativeRuntimeAdapter(...)` 保持其惰性加载，这样它可以按需导入你的运行时模块，同时仍让核心组装批准生命周期。
- 仅在渠道确实需要自定义批准负载而不是共享渲染器时，才使用 `approvalCapability.render`。
- 当渠道希望禁用路径回复解释启用原生 exec 批准所需的确切配置项时，使用 `approvalCapability.describeExecApprovalSetup`。该钩子接收 `{ channel, channelLabel, accountId }`；命名账号渠道应渲染账号作用域路径，例如 `channels.<channel>.accounts.<id>.execApprovals.*`，而不是顶层默认值。
- 如果某个渠道可以从现有配置中推断出稳定的类似所有者的私信身份，请使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createResolvedApproverActionAuthAdapter` 来限制同聊天 `/approve`，而无需添加批准特定的核心逻辑。
- 如果某个渠道需要原生批准投递，请让渠道代码专注于目标规范化以及传输/展示事实。使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver` 和 `createApproverRestrictedNativeApprovalCapability`。将渠道特定信息放在 `approvalCapability.nativeRuntime` 后面，理想情况下通过 `createChannelApprovalNativeRuntimeAdapter(...)` 或 `createLazyChannelApprovalNativeRuntimeAdapter(...)`，这样核心就可以组装处理器并负责请求过滤、路由、去重、过期、Gateway 网关订阅以及“已路由到其他地方”的通知。`nativeRuntime` 被拆分为几个更小的扩展点：
- `availability` — 账号是否已配置，以及请求是否应被处理
- `presentation` — 将共享批准视图模型映射为待处理/已解决/已过期的原生负载或最终动作
- `transport` — 准备目标并发送/更新/删除原生批准消息
- `interactions` — 原生按钮或反应的可选绑定/解绑/清除动作钩子
- `observe` — 可选的投递诊断钩子
- 如果渠道需要由运行时持有的对象，例如客户端、令牌、Bolt 应用或 webhook 接收器，请通过 `openclaw/plugin-sdk/channel-runtime-context` 进行注册。通用的运行时上下文注册表让核心能够从渠道启动状态引导基于能力的处理器，而无需添加批准专用的包装胶水代码。
- 只有当基于能力的接口仍不足以表达你的需求时，才使用更底层的 `createChannelApprovalHandler` 或 `createChannelNativeApprovalRuntime`。
- 原生批准渠道必须通过这些辅助工具同时传递 `accountId` 和 `approvalKind`。`accountId` 可使多账户批准策略限定在正确的机器人账户范围内，而 `approvalKind` 则使 exec 与插件批准行为可供渠道使用，而无需在核心中编写硬编码分支。
- 核心现在也负责批准重路由通知。渠道插件不应再从 `createChannelNativeApprovalRuntime` 发送自己的“批准已发送到私信/另一个渠道”后续消息；相反，应通过共享的批准能力辅助工具暴露准确的来源 + 批准者私信路由，并让核心在向发起聊天回发任何通知前聚合实际投递结果。
- 在端到端流程中保留已投递批准 id 的类型。原生客户端不应根据渠道本地状态猜测或重写 exec 与插件批准的路由。
- 不同的批准类型可以有意暴露不同的原生界面。
当前内置示例：
- 如果渠道需要运行时自有对象，例如客户端、令牌、Bolt 应用或 webhook 接收器，请通过 `openclaw/plugin-sdk/channel-runtime-context` 注册它们。通用 runtime-context 注册表让核心能够从渠道启动状态引导由能力驱动的处理器，而无需添加批准特定的包装胶水代码。
- 只有当能力驱动的扩展点仍不够表达需求时，才使用更底层的 `createChannelApprovalHandler` 或 `createChannelNativeApprovalRuntime`。
- 原生批准渠道必须通过这些辅助工具同时传递 `accountId` 和 `approvalKind`。`accountId` 可使多账号批准策略限定在正确的机器人账号范围内，而 `approvalKind` 可让渠道在无需核心中硬编码分支的情况下区分 exec 与插件批准行为。
- 核心现在也负责批准改道路由通知。渠道插件不应再从 `createChannelNativeApprovalRuntime` 发送它们自己的“批准已发送到私信/另一个渠道”后续消息；请改为通过共享批准能力辅助工具公开准确的源头 + approver 私信路由，让核心在向发起聊天发送任何通知前聚合实际投递结果。
- 在端到端流程中保留已投递批准 id 的种类。原生客户端不应根据渠道本地状态去猜测或重写 exec 与插件批准路由。
- 不同批准种类可以有意公开不同的原生表面。
当前的内置示例：
- Slack 对 exec 和插件 id 都保留原生批准路由能力。
- Matrix 对 exec 和插件批准保持相同的原生私信/渠道路由和反应 UX，同时仍允许批准类型之间的认证不同。
- `createApproverRestrictedNativeApprovalAdapter` 仍作为兼容性包装器存在，但新代码应优先使用能力构建器，并在插件上暴露 `approvalCapability`。
- Matrix 对 exec 和插件批准保留相同的原生私信/渠道路由和反应 UX，同时仍允许授权随批准种类而不同。
- `createApproverRestrictedNativeApprovalAdapter` 仍然作为兼容性包装器存在，但新代码应优先使用能力构建器，并在插件上公开 `approvalCapability`。
对于热门渠道入口点，当你只需要这一族中的某一部分时，优先使用更窄的运行时子路径：
对于高频渠道入口点，如果你只需要其中一个部分，请优先使用这一系列更窄的运行时子路径：
- `openclaw/plugin-sdk/approval-auth-runtime`
- `openclaw/plugin-sdk/approval-client-runtime`
- `openclaw/plugin-sdk/approval-delivery-runtime`
- `openclaw/plugin-sdk/approval-gateway-runtime`
- `openclaw/plugin-sdk/approval-handler-adapter-runtime`
- `openclaw/plugin-sdk/approval-handler-runtime`
- `openclaw/plugin-sdk/approval-native-runtime`
- `openclaw/plugin-sdk/approval-reply-runtime`
- `openclaw/plugin-sdk/channel-runtime-context`
同样地，当你不需要更宽泛的总入口接口时，请优先使用 `openclaw/plugin-sdk/setup-runtime`、`openclaw/plugin-sdk/setup-adapter-runtime`、`openclaw/plugin-sdk/reply-runtime`、`openclaw/plugin-sdk/reply-dispatch-runtime`、`openclaw/plugin-sdk/reply-reference` 和 `openclaw/plugin-sdk/reply-chunking`。
同样地，当你不需要更宽泛的总表面时，请优先使用 `openclaw/plugin-sdk/setup-runtime`、
`openclaw/plugin-sdk/setup-adapter-runtime`、
`openclaw/plugin-sdk/reply-runtime`、
`openclaw/plugin-sdk/reply-dispatch-runtime`、
`openclaw/plugin-sdk/reply-reference` 和
`openclaw/plugin-sdk/reply-chunking`。
对于设置，具体来说：
对于设置，具体如下：
- `openclaw/plugin-sdk/setup-runtime` 覆盖运行时安全的设置辅助工具：
- `openclaw/plugin-sdk/setup-runtime` 包含运行时安全的设置辅助工具：
可安全导入的设置补丁适配器（`createPatchedAccountSetupAdapter`、
`createEnvPatchedAccountSetupAdapter`、
`createSetupInputPresenceValidator`）、查找说明输出、
`promptResolvedAllowFrom`、`splitSetupEntries` 和委托式
设置代理构建器
- `openclaw/plugin-sdk/setup-adapter-runtime` 是面向环境变量的窄适配器接口，
用于 `createEnvPatchedAccountSetupAdapter`
- `openclaw/plugin-sdk/channel-setup` 覆盖可选安装设置构建器以及一些设置安全原语：
`promptResolvedAllowFrom`、`splitSetupEntries` 以及委托式
setup-proxy 构建器
- `openclaw/plugin-sdk/setup-adapter-runtime` 是用于 `createEnvPatchedAccountSetupAdapter` 的窄型环境感知适配器扩展点
- `openclaw/plugin-sdk/channel-setup` 涵盖可选安装设置构建器以及少量设置安全原语：
`createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、
如果你的渠道支持由环境变量驱动的设置或认证，并且通用启动/配置流程需要在运行时加载之前知道这些环境变量名，请在插件清单中通过 `channelEnvVars` 声明它们。将渠道运行时 `envVars` 或本地常量仅用于面向操作员的文案。
如果你的渠道支持由环境变量驱动的设置或授权，并且通用启动/配置流程需要在运行时加载前知道这些环境变量名称，请在插件清单中通过 `channelEnvVars` 声明它们。将渠道运行时 `envVars` 或本地常量仅用于面向操作员的文案。
`createOptionalChannelSetupWizard`、`DEFAULT_ACCOUNT_ID`、
`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled` 和
`splitSetupEntries`
- 仅当你还需要更重的共享设置/配置辅助工具时，才使用更宽泛的 `openclaw/plugin-sdk/setup` 接口，例如
- 仅当你还需要更重的共享设置/配置辅助工具时，才使用更宽泛的 `openclaw/plugin-sdk/setup` 扩展点，例如
`moveSingleAccountChannelSectionToDefaultAccount(...)`
如果你的渠道只想在设置界面中提示“请先安装此插件”，请优先使用 `createOptionalChannelSetupSurface(...)`。生成的适配器/向导会在配置写入和最终确定时默认关闭，并在校验、finalize 和文档链接文案中复用同一条“需要安装”的消息。
如果你的渠道只想在设置表面中提示“先安装这个插件”，请优先使用 `createOptionalChannelSetupSurface(...)`。生成的适配器/向导会在配置写入和最终化时采用默认拒绝行为，并在验证、完成和文档链接文案中复用相同的“需要安装”消息。
对于其他热门渠道路径，请优先使用窄辅助工具，而不是更宽泛的旧版接口：
对于其他高频渠道路径，请优先使用窄型辅助工具，而不是更宽泛的旧版表面：
- `openclaw/plugin-sdk/account-core`、
`openclaw/plugin-sdk/account-id`、
`openclaw/plugin-sdk/account-resolution` 和
`openclaw/plugin-sdk/account-helpers` 用于多账户配置和
默认账户回退
`openclaw/plugin-sdk/account-helpers` 用于多账号配置和默认账号回退
- `openclaw/plugin-sdk/inbound-envelope` 和
`openclaw/plugin-sdk/inbound-reply-dispatch` 用于入站路由/信封以及
记录并分发的接线
`openclaw/plugin-sdk/inbound-reply-dispatch` 用于入站路由/封装以及记录与分发接线
- `openclaw/plugin-sdk/messaging-targets` 用于目标解析/匹配
- `openclaw/plugin-sdk/outbound-media` 和
`openclaw/plugin-sdk/outbound-runtime` 用于媒体加载以及出站
身份/发送委托
- `openclaw/plugin-sdk/thread-bindings-runtime` 用于线程绑定生命周期
和适配器注册
- 仅当仍需要旧版智能体/媒体负载字段布局时，
才使用 `openclaw/plugin-sdk/agent-media-payload`
- `openclaw/plugin-sdk/telegram-command-config` 用于 Telegram 自定义命令
规范化、重复/冲突校验，以及稳定回退的命令
配置契约
`openclaw/plugin-sdk/outbound-runtime` 用于媒体加载以及出站身份/发送委托
- `openclaw/plugin-sdk/thread-bindings-runtime` 用于线程绑定生命周期和适配器注册
- 仅当仍需要旧版智能体/媒体负载字段布局时，才使用 `openclaw/plugin-sdk/agent-media-payload`
- `openclaw/plugin-sdk/telegram-command-config` 用于 Telegram 自定义命令规范化、重复/冲突校验，以及一个可稳定回退的命令配置契约
仅认证渠道通常可以止步于默认路径：核心处理批准，而插件只暴露出站/认证能力。像 Matrix、Slack、Telegram 和自定义聊天传输这类原生批准渠道，应使用共享的原生辅助工具，而不是自行实现批准生命周期。
仅授权渠道通常只需走默认路径：核心处理批准，插件只暴露出站/授权能力。像 Matrix、Slack、Telegram 和自定义聊天传输这类原生批准渠道，应使用共享的原生辅助工具，而不是自行实现批准生命周期。
## 入站提及策略
请将入站提及处理拆分为两层：
- 插件负责的证据收集
- 共享的策略评估
- 插件自有的证据收集
- 共享策略评估
共享层请使用 `openclaw/plugin-sdk/channel-inbound`。
适合插件本地逻辑的内容：
适合放在插件本地逻辑中的内容：
- 回复机器人检测
- 引用机器人检测
- 线程参与检查
- 服务/系统消息排除
- 用于证明机器人参与的平台原生缓存
- 证明机器人参与所需的平台原生缓存
适合共享辅助工具的内容：
适合放在共享辅助工具中的内容：
- `requireMention`
- 显式提及结果
@ -205,7 +205,7 @@ const decision = resolveInboundMentionDecision({
if (decision.shouldSkip) return;
```
`api.runtime.channel.mentions` 为已经依赖运行时注入的内置渠道插件暴露了相同的共享提及辅助工具：
对于已依赖运行时注入的内置渠道插件，`api.runtime.channel.mentions` 公开了相同的共享提及辅助工具：
- `buildMentionRegexes`
- `matchesMentionPatterns`
@ -214,16 +214,16 @@ if (decision.shouldSkip) return;
- `resolveInboundMentionDecision`
较旧的 `resolveMentionGating*` 辅助工具仍保留在
`openclaw/plugin-sdk/channel-inbound` 中，但仅作为兼容性导出。新代码
应使用 `resolveInboundMentionDecision({ facts, policy })`。
`openclaw/plugin-sdk/channel-inbound` 中，但仅作为兼容性导出。新代码应使用
`resolveInboundMentionDecision({ facts, policy })`。
## 演练
<Steps>
<a id="step-1-package-and-manifest"></a>
<Step title="软件包和清单">
<Step title="包和清单">
创建标准插件文件。`package.json` 中的 `channel` 字段
用于将其标记为渠道插件。有关完整的软件包元数据接口，
使其成为一个渠道插件。有关完整的包元数据表面，
请参见 [插件设置和配置](/zh-CN/plugins/sdk-setup#openclawchannel)：
<CodeGroup>
@ -274,8 +274,7 @@ if (decision.shouldSkip) return;
</Step>
<Step title="构建渠道插件对象">
`ChannelPlugin` 接口有许多可选适配器接口。先从最小集合开始
—— `id` 和 `setup` —— 然后按需添加适配器。
`ChannelPlugin` 接口有许多可选适配器表面。先从最小集合开始——`id` 和 `setup`——然后按需添加适配器。
创建 `src/channel.ts`：
@ -370,18 +369,17 @@ if (decision.shouldSkip) return;
});
```
<Accordion title="createChatChannelPlugin 为你做了什么">
你无需手动实现底层适配器接口，只需传入声明式选项，
构建器就会将它们组合起来：
<Accordion title="`createChatChannelPlugin` 为你做了什么">
你无需手动实现底层适配器接口，而是传入声明式选项，由构建器负责组合：
| 选项 | 它接线的内容 |
| 选项 | 接线内容 |
| --- | --- |
| `security.dm` | 从配置字段解析带作用域的私信安全策略 |
| `pairing.text` | 通过验证码交换实现基于文本的私信配对流程 |
| `threading` | reply-to 模式解析器（固定、账户作用域或自定义） |
| `outbound.attachedResults` | 返回结果元数据（消息 ID）的发送函数 |
| `security.dm` | 基于配置字段的作用域私信安全解析器 |
| `pairing.text` | 基于文本和验证码交换的私信配对流程 |
| `threading` | 回复模式解析器（固定、账号作用域或自定义） |
| `outbound.attachedResults` | 返回结果元数据（消息 id）的发送函数 |
如果你需要完全控制，也可以直接传入原始适配器对象，而不是声明式选项。
如果你需要完全控制，也可以传入原始适配器对象，而不是这些声明式选项。
</Accordion>
</Step>
@ -422,21 +420,16 @@ if (decision.shouldSkip) return;
});
```
将渠道自有的 CLI 描述符放在 `registerCliMetadata(...)` 中，这样 OpenClaw
就能在不激活完整渠道运行时的情况下，在根帮助中显示它们；
同时，正常的完整加载也会拾取这些相同的描述符，用于真正的命令注册。
将 `registerFull(...)` 保留给仅运行时的工作。
如果 `registerFull(...)` 注册 Gateway 网关 RPC 方法，请使用
插件专属前缀。核心管理命名空间（`config.*`、
`exec.approvals.*`、`wizard.*`、`update.*`）仍为保留项，并始终
解析到 `operator.admin`。
`defineChannelPluginEntry` 会自动处理注册模式拆分。有关全部
选项，请参见 [入口点](/zh-CN/plugins/sdk-entrypoints#definechannelpluginentry)。
将渠道自有的 CLI 描述符放在 `registerCliMetadata(...)` 中，这样 OpenClaw 就能在不激活完整渠道运行时的情况下，在根帮助中显示它们；而普通完整加载仍会拾取相同的描述符以进行真实命令注册。将 `registerFull(...)` 保留给仅运行时工作。
如果 `registerFull(...)` 注册 Gateway 网关 RPC 方法，请使用插件特定前缀。核心管理命名空间（`config.*`、
`exec.approvals.*`、`wizard.*`、`update.*`）保持保留，并始终解析到 `operator.admin`。
`defineChannelPluginEntry` 会自动处理注册模式拆分。有关全部选项，请参见
[入口点](/zh-CN/plugins/sdk-entrypoints#definechannelpluginentry)。
</Step>
<Step title="添加设置入口">
创建 `setup-entry.ts`，以便在新手引导期间进行轻量加载：
创建 `setup-entry.ts`，用于在新手引导期间轻量加载：
```typescript setup-entry.ts
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
@ -445,15 +438,14 @@ if (decision.shouldSkip) return;
export default defineSetupPluginEntry(acmeChatPlugin);
```
当渠道被禁用或未配置时，OpenClaw 会加载这个入口，而不是完整入口。
当渠道被禁用或尚未配置时，OpenClaw 会加载它，而不是完整入口。
这样可以避免在设置流程中拉入沉重的运行时代码。
详情请参见 [设置和配置](/zh-CN/plugins/sdk-setup#setup-entry)。
</Step>
<Step title="处理入站消息">
你的插件需要从平台接收消息并将其转发给 OpenClaw。典型模式是
一个 webhook：验证请求，然后通过你渠道的入站处理器进行分发：
你的插件需要从平台接收消息并将其转发给 OpenClaw。典型模式是一个 webhook：验证请求后，通过你渠道的入站处理器进行分发。
```typescript
registerFull(api) {
@ -477,8 +469,7 @@ if (decision.shouldSkip) return;
```
<Note>
入站消息处理是渠道特定的。每个渠道插件都拥有
自己的入站处理流水线。请查看内置渠道插件
入站消息处理是渠道特定的。每个渠道插件都拥有自己的入站处理管线。请查看内置渠道插件
（例如 Microsoft Teams 或 Google Chat 插件包）以了解真实模式。
</Note>
@ -524,7 +515,7 @@ if (decision.shouldSkip) return;
pnpm test -- <bundled-plugin-root>/acme-chat/
```
有关共享测试辅助工具，请参见 [测试](/zh-CN/plugins/sdk-testing)。
关于共享测试辅助工具，请参见 [测试](/zh-CN/plugins/sdk-testing)。
</Step>
</Steps>
@ -533,41 +524,39 @@ if (decision.shouldSkip) return;
```
<bundled-plugin-root>/acme-chat/
├── package.json # openclaw.channel metadata
├── openclaw.plugin.json # Manifest with config schema
├── package.json # openclaw.channel 元数据
├── openclaw.plugin.json # 带有配置 schema 的清单
├── index.ts # defineChannelPluginEntry
├── setup-entry.ts # defineSetupPluginEntry
├── api.ts # Public exports (optional)
├── runtime-api.ts # Internal runtime exports (optional)
├── api.ts # 公共导出（可选）
├── runtime-api.ts # 内部运行时导出（可选）
└── src/
├── channel.ts # ChannelPlugin via createChatChannelPlugin
├── channel.test.ts # Tests
├── client.ts # Platform API client
└── runtime.ts # Runtime store (if needed)
├── channel.ts # 通过 createChatChannelPlugin 创建的 ChannelPlugin
├── channel.test.ts # 测试
├── client.ts # 平台 API 客户端
└── runtime.ts # 运行时存储（如需要）
```
## 高级主题
<CardGroup cols={2}>
<Card title="线程选项" icon="git-branch" href="/zh-CN/plugins/sdk-entrypoints#registration-mode">
固定、账户作用域或自定义回复模式
固定、账号作用域或自定义回复模式
</Card>
<Card title="message 工具集成" icon="puzzle" href="/zh-CN/plugins/architecture#channel-plugins-and-the-shared-message-tool">
<Card title="消息工具集成" icon="puzzle" href="/zh-CN/plugins/architecture#channel-plugins-and-the-shared-message-tool">
describeMessageTool 和动作发现
</Card>
<Card title="目标解析" icon="crosshair" href="/zh-CN/plugins/architecture#channel-target-resolution">
inferTargetChatType、looksLikeId、resolveTarget
</Card>
<Card title="运行时辅助工具" icon="settings" href="/zh-CN/plugins/sdk-runtime">
TTS、STT、媒体、通过 api.runtime 使用的子智能体
通过 api.runtime 使用 TTS、STT、媒体、子智能体
</Card>
</CardGroup>
<Note>
一些内置辅助工具接口仍然存在，用于内置插件维护和
兼容性。对于新的渠道插件，它们不是推荐模式；
除非你正在直接维护该内置插件家族，否则请优先使用通用 SDK
接口中的 channel/setup/reply/runtime 子路径。
某些内置辅助扩展点仍保留，用于内置插件维护和兼容性。它们并不是新渠道插件的推荐模式；
除非你正在直接维护该内置插件家族，否则应优先使用公共 SDK 表面中的通用渠道/设置/回复/运行时子路径。
</Note>
## 后续步骤

320
docs/zh-CN/plugins/sdk-migration.md
View File

@ -1,56 +1,56 @@
---
read_when:
- 你看到 `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` 警告
- 你看到 `OPENCLAW_EXTENSION_API_DEPRECATED` 警告
- 你看到了 OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED 警告
- 你看到了 OPENCLAW_EXTENSION_API_DEPRECATED 警告
- 你正在将一个插件更新到现代插件架构
- 你在维护一个外部 OpenClaw 插件
- 你维护一个外部 OpenClaw 插件
sidebarTitle: Migrate to SDK
summary: 从旧版向后兼容层迁移到现代插件 SDK
title: 插件 SDK 迁移
x-i18n:
generated_at: "2026-04-07T18:43:21Z"
generated_at: "2026-04-07T20:09:26Z"
model: gpt-5.4
provider: openai
source_hash: 509699c3432191a1b2e4214c66d6d620e8d13a064cb2e7b9b38460c7ea45a20d
source_hash: 155a8b14bc345319c8516ebdb8a0ccdea2c5f7fa07dad343442996daee21ecad
source_path: plugins/sdk-migration.md
workflow: 15
---
# 插件 SDK 迁移
OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚焦且有文档说明的导入方式。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。
OpenClaw 已从一个宽泛的向后兼容层迁移到一个现代插件架构，采用聚焦且文档完善的导入路径。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。
## 正在发生什么变化
旧插件系统提供了两个完全开放的接口，让插件可以从单一入口点导入所需的任何内容：
旧插件系统提供了两个高度开放的接口，让插件可以从单一入口点导入它们所需的任何内容：
- **`openclaw/plugin-sdk/compat`** — 一个会重新导出数十个辅助工具的单一导入入口。它的引入是为了在构建新插件架构期间，让较旧的基于 hook 的插件继续工作。
- **`openclaw/extension-api`** — 一个桥接层，让插件可以直接访问宿主端辅助工具，例如内嵌智能体运行器。
- **`openclaw/plugin-sdk/compat`** — 一个单一导入路径，重新导出了数十个辅助工具。它的引入是为了在新插件架构构建期间，让较旧的基于 hook 的插件继续工作。
- **`openclaw/extension-api`** — 一个桥接层，使插件能够直接访问主机侧辅助工具，例如嵌入式智能体运行器。
这两个接口现在都已**弃用**。它们在运行时仍然可用，但新插件不得使用它们，现有插件也应在下一个主要版本移除它们之前完成迁移。
这两个接口现在都已被**弃用**。它们在运行时仍然可用，但新插件不得使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。
<Warning>
向后兼容层将在未来的一个主要版本中移除。
到那时，仍然从这些接口导入内容的插件将会失效。
向后兼容层将在未来的一个主版本中被移除。
仍然从这些接口导入的插件届时将会中断。
</Warning>
## 为什么会有这个变化
## 为什么会发生这个变化
旧方案带来了这些问题：
旧方法带来了这些问题：
- **启动缓慢** — 导入一个辅助工具会加载数十个无关模块
- **循环依赖** — 宽泛的重新导出很容易产生导入循环
- **启动缓慢** — 导入一个辅助工具会加载几十个无关模块
- **循环依赖** — 宽泛的重新导出使得导入循环很容易产生
- **API 接口不清晰** — 无法判断哪些导出是稳定的，哪些是内部实现
现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\<subpath\>`）都是一个小型、自包含的模块，具有清晰的用途和有文档说明的契约。
现代插件 SDK 修复了这些问题：每个导入路径（`openclaw/plugin-sdk/\<subpath\>`）都是一个小型、自包含的模块，具有明确用途和文档化契约。
面向内置渠道的旧版 provider 便捷接口也已移除。类似 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、带渠道品牌的辅助接口，以及 `openclaw/plugin-sdk/telegram-core` 这样的导入，都是私有 mono-repo 快捷方式，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区内部，应将 provider 自有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。
面向内置渠道的旧版提供商便捷接口也已移除。诸如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、带渠道品牌的辅助接口，以及 `openclaw/plugin-sdk/telegram-core` 这类导入路径，都是私有 mono-repo 快捷方式，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区内，请将提供商自有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。
当前内置 provider 示例：
当前内置提供商示例：
- Anthropic 将 Claude 专用的流式辅助工具保留在它自己的 `api.ts` / `contract-api.ts` 接口中
- OpenAI 将 provider builder、默认模型辅助工具以及实时 provider builder 保留在它自己的 `api.ts` 中
- OpenRouter 将 provider builder 以及新手引导 / 配置辅助工具保留在它自己的 `api.ts` 中
- Anthropic 将 Claude 专用的流式传输辅助工具保留在其自己的 `api.ts` / `contract-api.ts` 接口中
- OpenAI 将提供商构建器、默认模型辅助工具以及实时提供商构建器保留在其自己的 `api.ts` 中
- OpenRouter 将提供商构建器以及新手引导/配置辅助工具保留在其自己的 `api.ts` 中
## 如何迁移
@ -61,20 +61,20 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚
关键变化：
- 将 `approvalCapability.handler.loadRuntime(...)` 替换为 `approvalCapability.nativeRuntime`
- 将审批专用的认证 / 投递从旧版 `plugin.auth` /
- 将审批专用的认证/投递从旧版 `plugin.auth` /
`plugin.approvals` 线路迁移到 `approvalCapability`
- `ChannelPlugin.approvals` 已从公开的渠道插件契约中移除；请将 delivery / native / render 字段迁移到 `approvalCapability`
- `plugin.auth` 仅保留给渠道登录 / 登出流程使用；其中的审批认证 hook 不再被 core 读取
- 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道自有的运行时对象，例如客户端、令牌或 Bolt 应用
- 不要从原生审批处理器发送插件自有的改道通知；core 现在会根据实际投递结果来处理“已路由到其他地方”的通知
- 将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 接口。部分 stub 将被拒绝。
- `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；请将 delivery/native/render 字段迁移到 `approvalCapability`
- `plugin.auth` 仅保留用于渠道登录/登出流程；其中的审批认证 hook 不再被核心读取
- 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道自有运行时对象，例如客户端、令牌或 Bolt 应用
- 不要从原生审批处理器发送插件自有的“已重定向到其他地方”通知；核心现在会根据实际投递结果统一处理这类通知
- 当你将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供一个真实的 `createPluginRuntime().channel` 接口。部分 stub 将被拒绝。
当前审批能力布局请参见 `/plugins/sdk-channel-plugins`。
</Step>
<Step title="审查 Windows 包装器回退行为">
如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，现在当 Windows 的 `.cmd` / `.bat` 包装器无法解析时，默认会以关闭方式失败，除非你显式传入 `allowShellFallback: true`。
如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，现在无法解析的 Windows `.cmd`/`.bat` 包装器会默认失败关闭，除非你显式传入 `allowShellFallback: true`。
```typescript
// Before
@ -83,17 +83,18 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚
// After
const program = applyWindowsSpawnProgramPolicy({
candidate,
// 仅对受信任且明确接受 shell 中介回退的兼容性调用方设置此项。
// 仅为受信任的兼容性调用方设置此项，这些调用方有意接受
// 经过 shell 中介的回退行为。
allowShellFallback: true,
});
```
如果你的调用方并不有意依赖 shell 回退，就不要设置 `allowShellFallback`，而应改为处理抛出的错误。
如果你的调用方并非有意依赖 shell 回退，请不要设置 `allowShellFallback`，而应改为处理抛出的错误。
</Step>
<Step title="查找已弃用的导入">
在你的插件中搜索来自任一已弃用接口的导入：
在你的插件中搜索来自这两个已弃用接口的导入：
```bash
grep -r "plugin-sdk/compat" my-plugin/
@ -103,7 +104,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚
</Step>
<Step title="替换为聚焦导入">
旧接口中的每个导出都映射到一个明确的现代导入路径：
旧接口中的每个导出都映射到一个特定的现代导入路径：
```typescript
// Before (deprecated backwards-compatibility layer)
@ -119,7 +120,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
```
对于宿主端辅助工具，请改用注入的插件运行时，而不是直接导入：
对于主机侧辅助工具，请使用注入的插件运行时，而不是直接导入：
```typescript
// Before (deprecated extension-api bridge)
@ -132,7 +133,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚
同样的模式也适用于其他旧版桥接辅助工具：
| 旧导入 | 现代等价项 |
| 旧导入 | 现代等效项 |
| --- | --- |
| `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` |
| `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` |
@ -158,172 +159,170 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚
| 导入路径 | 用途 | 关键导出 |
| --- | --- | --- |
| `plugin-sdk/plugin-entry` | 规范插件入口辅助工具 | `definePluginEntry` |
| `plugin-sdk/core` | 用于渠道入口定义 / builder 的旧版总括重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/core` | 用于渠道入口定义/构建器的旧版总括重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | 单 provider 入口辅助工具 | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | 聚焦的渠道入口定义和 builder | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | 共享设置向导辅助工具 | Allowlist 提示、设置状态 builder |
| `plugin-sdk/setup-runtime` | 设置时运行时辅助工具 | 可安全导入的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 |
| `plugin-sdk/provider-entry` | 单一提供商入口辅助工具 | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | 共享设置向导辅助工具 | Allowlist 提示、设置状态构建器 |
| `plugin-sdk/setup-runtime` | 设置时运行时辅助工具 | 对导入安全的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 |
| `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助工具 | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | 设置工具辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表 / 配置 / 操作 gate 辅助工具 |
| `plugin-sdk/account-id` | 账户 ID 辅助工具 | `DEFAULT_ACCOUNT_ID`、账户 ID 规范化 |
| `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表/配置/操作门控辅助工具 |
| `plugin-sdk/account-id` | account-id 辅助工具 | `DEFAULT_ACCOUNT_ID`、account-id 规范化 |
| `plugin-sdk/account-resolution` | 账户查找辅助工具 | 账户查找 + 默认回退辅助工具 |
| `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表 / 账户操作辅助工具 |
| `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表/账户操作辅助工具 |
| `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` |
| `plugin-sdk/channel-pairing` | 私信配对原语 | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 正在输入线路 | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | 配置 schema builder | 渠道配置 schema 类型 |
| `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复 / 冲突校验 |
| `plugin-sdk/channel-policy` | 群组 / 私信策略解析 | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 渠道配置 schema 类型 |
| `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复/冲突校验 |
| `plugin-sdk/channel-policy` | 群组/私信策略解析 | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | 账户状态跟踪 | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享路由 + envelope builder 辅助工具 |
| `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享路由 + envelope 构建辅助工具 |
| `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录与分发辅助工具 |
| `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析 / 匹配辅助工具 |
| `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析/匹配辅助工具 |
| `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 |
| `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站身份 / 发送委托辅助工具 |
| `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站身份/发送委托辅助工具 |
| `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 |
| `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 用于旧字段布局的智能体媒体负载 builder |
| `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅旧版渠道运行时工具 |
| `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 面向旧字段布局的智能体媒体负载构建器 |
| `plugin-sdk/channel-runtime` | 已弃用的兼容性垫片 | 仅旧版渠道运行时工具 |
| `plugin-sdk/channel-send-result` | 发送结果类型 | 回复结果类型 |
| `plugin-sdk/runtime-store` | 持久化插件存储 | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | 宽范围运行时辅助工具 | 运行时 / 日志 / 备份 / 插件安装辅助工具 |
| `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | logger / 运行时环境、超时、重试和 backoff 辅助工具 |
| `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令 / hooks / HTTP / 交互式辅助工具 |
| `plugin-sdk/hook-runtime` | hook 流水线辅助工具 | 共享 webhook / 内部 hook 流水线辅助工具 |
| `plugin-sdk/lazy-runtime` | 惰性运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/runtime` | 宽范围运行时辅助工具 | 运行时/日志/备份/插件安装辅助工具 |
| `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | Logger/运行时环境、超时、重试和退避辅助工具 |
| `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令/hooks/http/交互辅助工具 |
| `plugin-sdk/hook-runtime` | Hook 管道辅助工具 | 共享 webhook/内部 hook 管道辅助工具 |
| `plugin-sdk/lazy-runtime` | 延迟运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | 进程辅助工具 | 共享 exec 辅助工具 |
| `plugin-sdk/cli-runtime` | CLI 运行时辅助工具 | 命令格式化、等待、版本辅助工具 |
| `plugin-sdk/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端和渠道状态补丁辅助工具 |
| `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载 / 写入辅助工具 |
| `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口不可用时，提供回退稳定的 Telegram 命令校验辅助工具 |
| `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec / 插件审批负载、审批能力 / 配置文件辅助工具、原生审批路由 / 运行时辅助工具 |
| `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载/写入辅助工具 |
| `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口不可用时，提供稳定回退的 Telegram 命令校验辅助工具 |
| `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec/插件审批负载、审批能力/配置文件辅助工具、原生审批路由/运行时辅助工具 |
| `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | 审批人解析、同聊天操作认证 |
| `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批配置文件 / 过滤辅助工具 |
| `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力 / 投递适配器 |
| `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 共享审批处理器运行时辅助工具，包括基于能力驱动的原生审批加载 |
| `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标 / 账户绑定辅助工具 |
| `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec / 插件审批回复负载辅助工具 |
| `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register / get / watch 辅助工具 |
| `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信 gate、外部内容和密钥收集辅助工具 |
| `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批配置文件/过滤辅助工具 |
| `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力/投递适配器 |
| `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助工具 | 共享审批 Gateway 网关解析辅助工具 |
| `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 用于热点渠道入口点的轻量级原生审批适配器加载辅助工具 |
| `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 范围更广的审批处理器运行时辅助工具；若更窄的 adapter/gateway 接口已足够，优先使用它们 |
| `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标/账户绑定辅助工具 |
| `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec/插件审批回复负载辅助工具 |
| `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register/get/watch 辅助工具 |
| `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和 secret 收集辅助工具 |
| `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机 allowlist 和私有网络策略辅助工具 |
| `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | 固定 dispatcher、受保护 fetch、SSRF 策略辅助工具 |
| `plugin-sdk/collection-runtime` | 有界缓存辅助工具 | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | 诊断 gate 辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/diagnostic-runtime` | 诊断门控辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助工具 |
| `plugin-sdk/fetch-runtime` | 封装的 fetch / 代理辅助工具 | `resolveFetch`、代理辅助工具 |
| `plugin-sdk/host-runtime` | 宿主规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/fetch-runtime` | 封装的 fetch/代理辅助工具 | `resolveFetch`、代理辅助工具 |
| `plugin-sdk/host-runtime` | 主机规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`、策略运行器 |
| `plugin-sdk/allow-from` | allowlist 格式化 | `formatAllowFromLowercase` |
| `plugin-sdk/allow-from` | Allowlist 格式化 | `formatAllowFromLowercase` |
| `plugin-sdk/allowlist-resolution` | Allowlist 输入映射 | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | 命令 gate 和命令接口辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具 |
| `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入辅助工具 |
| `plugin-sdk/webhook-ingress` | webhook 请求辅助工具 | webhook 目标工具 |
| `plugin-sdk/webhook-request-guards` | webhook 请求体保护辅助工具 | 请求体读取 / 限制辅助工具 |
| `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 |
| `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | finalize + provider 分发辅助工具 |
| `plugin-sdk/command-auth` | 命令门控和命令接口辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具 |
| `plugin-sdk/secret-input` | Secret 输入解析 | Secret 输入辅助工具 |
| `plugin-sdk/webhook-ingress` | Webhook 请求辅助工具 | Webhook 目标工具 |
| `plugin-sdk/webhook-request-guards` | Webhook 请求体防护辅助工具 | 请求体读取/限制辅助工具 |
| `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划、分块 |
| `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | Finalize + 提供商分发辅助工具 |
| `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | 回复引用规划 | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本 / markdown 分块辅助工具 |
| `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本/markdown 分块辅助工具 |
| `plugin-sdk/session-store-runtime` | 会话存储辅助工具 | 存储路径 + updated-at 辅助工具 |
| `plugin-sdk/state-paths` | 状态路径辅助工具 | 状态和 OAuth 目录辅助工具 |
| `plugin-sdk/routing` | 路由 / 会话键辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键规范化辅助工具 |
| `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道 / 账户状态摘要 builder、运行时状态默认值、问题元数据辅助工具 |
| `plugin-sdk/routing` | 路由/会话键辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键规范化辅助工具 |
| `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道/账户状态摘要构建器、运行时状态默认值、问题元数据辅助工具 |
| `plugin-sdk/target-resolver-runtime` | 目标解析器辅助工具 | 共享目标解析器辅助工具 |
| `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | slug / 字符串规范化辅助工具 |
| `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | slug/字符串规范化辅助工具 |
| `plugin-sdk/request-url` | 请求 URL 辅助工具 | 从类请求输入中提取字符串 URL |
| `plugin-sdk/run-command` | 定时命令辅助工具 | 带规范化 stdout / stderr 的定时命令运行器 |
| `plugin-sdk/param-readers` | 参数读取器 | 通用工具 / CLI 参数读取器 |
| `plugin-sdk/run-command` | 定时命令辅助工具 | 带标准化 stdout/stderr 的定时命令运行器 |
| `plugin-sdk/param-readers` | 参数读取器 | 通用工具/CLI 参数读取器 |
| `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范发送目标字段 |
| `plugin-sdk/temp-path` | 临时路径辅助工具 | 共享临时下载路径辅助工具 |
| `plugin-sdk/logging-core` | 日志辅助工具 | 子系统 logger 和脱敏辅助工具 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助工具 | Markdown 表格模式辅助工具 |
| `plugin-sdk/reply-payload` | 消息回复类型 | 回复负载类型 |
| `plugin-sdk/provider-setup` | 经过整理的本地 / 自托管 provider 设置辅助工具 | 自托管 provider 发现 / 配置辅助工具 |
| `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管 provider 设置辅助工具 | 同样的自托管 provider 发现 / 配置辅助工具 |
| `plugin-sdk/provider-auth-runtime` | provider 运行时认证辅助工具 | 运行时 API 密钥解析辅助工具 |
| `plugin-sdk/provider-auth-api-key` | provider API 密钥设置辅助工具 | API 密钥新手引导 / 配置文件写入辅助工具 |
| `plugin-sdk/provider-auth-result` | provider auth-result 辅助工具 | 标准 OAuth auth-result builder |
| `plugin-sdk/provider-auth-login` | provider 交互式登录辅助工具 | 共享交互式登录辅助工具 |
| `plugin-sdk/provider-env-vars` | provider 环境变量辅助工具 | provider 认证环境变量查找辅助工具 |
| `plugin-sdk/provider-model-shared` | 共享 provider 模型 / 重放辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略 builder、provider 端点辅助工具以及 model-id 规范化辅助工具 |
| `plugin-sdk/provider-catalog-shared` | 共享 provider catalog 辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | provider 新手引导补丁 | 新手引导配置辅助工具 |
| `plugin-sdk/provider-http` | provider HTTP 辅助工具 | 通用 provider HTTP / 端点能力辅助工具 |
| `plugin-sdk/provider-web-fetch` | provider web-fetch 辅助工具 | web-fetch provider 注册 / 缓存辅助工具 |
| `plugin-sdk/provider-web-search-contract` | provider web 搜索契约辅助工具 | 窄范围 web 搜索配置 / 凭证契约辅助工具，例如 `enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域化凭证 setter / getter |
| `plugin-sdk/provider-web-search` | provider web 搜索辅助工具 | web 搜索 provider 注册 / 缓存 / 运行时辅助工具 |
| `plugin-sdk/provider-tools` | provider 工具 / schema 兼容辅助工具 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | provider 用量辅助工具 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` 以及其他 provider 用量辅助工具 |
| `plugin-sdk/provider-stream` | provider 流包装辅助工具 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装辅助工具 |
| `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助工具 | 自托管提供商发现/配置辅助工具 |
| `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管提供商设置辅助工具 | 相同的自托管提供商发现/配置辅助工具 |
| `plugin-sdk/provider-auth-runtime` | 提供商运行时认证辅助工具 | 运行时 API key 解析辅助工具 |
| `plugin-sdk/provider-auth-api-key` | 提供商 API key 设置辅助工具 | API key 新手引导/配置文件写入辅助工具 |
| `plugin-sdk/provider-auth-result` | 提供商 auth-result 辅助工具 | 标准 OAuth auth-result 构建器 |
| `plugin-sdk/provider-auth-login` | 提供商交互式登录辅助工具 | 共享交互式登录辅助工具 |
| `plugin-sdk/provider-env-vars` | 提供商环境变量辅助工具 | 提供商认证环境变量查找辅助工具 |
| `plugin-sdk/provider-model-shared` | 共享提供商模型/重放辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略构建器、提供商 endpoint 辅助工具以及 model-id 规范化辅助工具 |
| `plugin-sdk/provider-catalog-shared` | 共享提供商目录辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | 提供商 onboarding 补丁 | onboarding 配置辅助工具 |
| `plugin-sdk/provider-http` | 提供商 HTTP 辅助工具 | 通用提供商 HTTP/endpoint 能力辅助工具 |
| `plugin-sdk/provider-web-fetch` | 提供商 web-fetch 辅助工具 | Web-fetch 提供商注册/缓存辅助工具 |
| `plugin-sdk/provider-web-search-contract` | 提供商 web-search 契约辅助工具 | 窄范围 web-search 配置/凭证契约辅助工具，例如 `enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域凭证 setter/getter |
| `plugin-sdk/provider-web-search` | 提供商 web-search 辅助工具 | Web-search 提供商注册/缓存/运行时辅助工具 |
| `plugin-sdk/provider-tools` | 提供商工具/schema 兼容辅助工具 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | 提供商用量辅助工具 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` 以及其他提供商用量辅助工具 |
| `plugin-sdk/provider-stream` | 提供商流包装辅助工具 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装类型，以及共享 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装辅助工具 |
| `plugin-sdk/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体 fetch / transform / store 辅助工具以及媒体负载 builder |
| `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 图像 / 视频 / 音乐生成的共享故障切换辅助工具、候选项选择和缺失模型消息 |
| `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解 provider 类型以及面向 provider 的图像 / 音频辅助导出 |
| `plugin-sdk/text-runtime` | 共享文本辅助工具 | 去除助手可见文本、markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本工具以及相关文本 / 日志辅助工具 |
| `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取/转换/存储辅助工具以及媒体负载构建器 |
| `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 图像/视频/音乐生成的共享故障切换辅助工具、候选项选择和缺失模型提示 |
| `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解提供商类型以及面向提供商的图像/音频辅助工具导出 |
| `plugin-sdk/text-runtime` | 共享文本辅助工具 | 面向助手可见文本剥离、markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本工具，以及相关文本/日志辅助工具 |
| `plugin-sdk/text-chunking` | 文本分块辅助工具 | 出站文本分块辅助工具 |
| `plugin-sdk/speech` | 语音辅助工具 | 语音 provider 类型以及面向 provider 的 directive、注册表和校验辅助工具 |
| `plugin-sdk/speech-core` | 共享语音核心 | 语音 provider 类型、注册表、指令、规范化 |
| `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | provider 类型和注册表辅助工具 |
| `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型和注册表辅助工具 |
| `plugin-sdk/speech` | 语音辅助工具 | 语音提供商类型以及面向提供商的 directive、注册表和校验辅助工具 |
| `plugin-sdk/speech-core` | 共享语音核心 | 语音提供商类型、注册表、指令、规范化 |
| `plugin-sdk/realtime-transcription` | 实时转写辅助工具 | 提供商类型和注册表辅助工具 |
| `plugin-sdk/realtime-voice` | 实时语音辅助工具 | 提供商类型和注册表辅助工具 |
| `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障切换、认证和注册表辅助工具 |
| `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成 provider / 请求 / 结果类型 |
| `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障切换辅助工具、provider 查找和 model-ref 解析 |
| `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider / 请求 / 结果类型 |
| `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障切换辅助工具、provider 查找和 model-ref 解析 |
| `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复负载规范化 / 归约 |
| `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄范围渠道配置 schema 原语 |
| `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成提供商/请求/结果类型 |
| `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障切换辅助工具、提供商查找和 model-ref 解析 |
| `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成提供商/请求/结果类型 |
| `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障切换辅助工具、提供商查找和 model-ref 解析 |
| `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复负载规范化/归约 |
| `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄范围渠道 config-schema 原语 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入辅助工具 | 渠道配置写入授权辅助工具 |
| `plugin-sdk/channel-plugin-common` | 共享渠道前导模块 | 共享渠道插件前导导出 |
| `plugin-sdk/channel-status` | 渠道状态辅助工具 | 共享渠道状态快照 / 摘要辅助工具 |
| `plugin-sdk/allowlist-config-edit` | Allowlist 配置辅助工具 | Allowlist 配置编辑 / 读取辅助工具 |
| `plugin-sdk/channel-plugin-common` | 共享渠道前导层 | 共享渠道插件前导导出 |
| `plugin-sdk/channel-status` | 渠道状态辅助工具 | 共享渠道状态快照/摘要辅助工具 |
| `plugin-sdk/allowlist-config-edit` | Allowlist 配置辅助工具 | Allowlist 配置编辑/读取辅助工具 |
| `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 |
| `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证 / 保护辅助工具 |
| `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道 / 状态和环境代理辅助原语 |
| `plugin-sdk/webhook-targets` | webhook 目标辅助工具 | webhook 目标注册表和路由安装辅助工具 |
| `plugin-sdk/webhook-path` | webhook 路径辅助工具 | webhook 路径规范化辅助工具 |
| `plugin-sdk/web-media` | 共享 Web 媒体辅助工具 | 远程 / 本地媒体加载辅助工具 |
| `plugin-sdk/zod` | Zod 重新导出 | 面向插件 SDK 使用者重新导出的 `zod` |
| `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | memory 管理器 / 配置 / 文件 / CLI 辅助接口 |
| `plugin-sdk/memory-core-engine-runtime` | memory 引擎运行时门面 | memory 索引 / 搜索运行时门面 |
| `plugin-sdk/memory-core-host-engine-foundation` | memory 宿主基础引擎 | memory 宿主基础引擎导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | memory 宿主嵌入引擎 | memory 宿主嵌入引擎导出 |
| `plugin-sdk/memory-core-host-engine-qmd` | memory 宿主 QMD 引擎 | memory 宿主 QMD 引擎导出 |
| `plugin-sdk/memory-core-host-engine-storage` | memory 宿主存储引擎 | memory 宿主存储引擎导出 |
| `plugin-sdk/memory-core-host-multimodal` | memory 宿主多模态辅助工具 | memory 宿主多模态辅助工具 |
| `plugin-sdk/memory-core-host-query` | memory 宿主查询辅助工具 | memory 宿主查询辅助工具 |
| `plugin-sdk/memory-core-host-secret` | memory 宿主密钥辅助工具 | memory 宿主密钥辅助工具 |
| `plugin-sdk/memory-core-host-events` | memory 宿主事件日志辅助工具 | memory 宿主事件日志辅助工具 |
| `plugin-sdk/memory-core-host-status` | memory 宿主状态辅助工具 | memory 宿主状态辅助工具 |
| `plugin-sdk/memory-core-host-runtime-cli` | memory 宿主 CLI 运行时 | memory 宿主 CLI 运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-core` | memory 宿主核心运行时 | memory 宿主核心运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-files` | memory 宿主文件 / 运行时辅助工具 | memory 宿主文件 / 运行时辅助工具 |
| `plugin-sdk/memory-host-core` | memory 宿主核心运行时别名 | 面向 vendor-neutral 的 memory 宿主核心运行时辅助工具别名 |
| `plugin-sdk/memory-host-events` | memory 宿主事件日志别名 | 面向 vendor-neutral 的 memory 宿主事件日志辅助工具别名 |
| `plugin-sdk/memory-host-files` | memory 宿主文件 / 运行时别名 | 面向 vendor-neutral 的 memory 宿主文件 / 运行时辅助工具别名 |
| `plugin-sdk/memory-host-markdown` | 受管 markdown 辅助工具 | 面向 memory 邻接插件的共享受管 markdown 辅助工具 |
| `plugin-sdk/memory-host-search` | 活跃 memory 搜索门面 | 惰性 active-memory search-manager 运行时门面 |
| `plugin-sdk/memory-host-status` | memory 宿主状态别名 | 面向 vendor-neutral 的 memory 宿主状态辅助工具别名 |
| `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证/防护辅助工具 |
| `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道/状态和环境代理辅助原语 |
| `plugin-sdk/webhook-targets` | Webhook 目标辅助工具 | Webhook 目标注册表和路由安装辅助工具 |
| `plugin-sdk/webhook-path` | Webhook 路径辅助工具 | Webhook 路径规范化辅助工具 |
| `plugin-sdk/web-media` | 共享 Web 媒体辅助工具 | 远程/本地媒体加载辅助工具 |
| `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用者重新导出的 `zod` |
| `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | 内存管理器/配置/文件/CLI 辅助接口 |
| `plugin-sdk/memory-core-engine-runtime` | 内存引擎运行时外观层 | 内存索引/搜索运行时外观层 |
| `plugin-sdk/memory-core-host-engine-foundation` | 内存主机基础引擎 | 内存主机基础引擎导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | 内存主机嵌入引擎 | 内存主机嵌入引擎导出 |
| `plugin-sdk/memory-core-host-engine-qmd` | 内存主机 QMD 引擎 | 内存主机 QMD 引擎导出 |
| `plugin-sdk/memory-core-host-engine-storage` | 内存主机存储引擎 | 内存主机存储引擎导出 |
| `plugin-sdk/memory-core-host-multimodal` | 内存主机多模态辅助工具 | 内存主机多模态辅助工具 |
| `plugin-sdk/memory-core-host-query` | 内存主机查询辅助工具 | 内存主机查询辅助工具 |
| `plugin-sdk/memory-core-host-secret` | 内存主机 secret 辅助工具 | 内存主机 secret 辅助工具 |
| `plugin-sdk/memory-core-host-events` | 内存主机事件日志辅助工具 | 内存主机事件日志辅助工具 |
| `plugin-sdk/memory-core-host-status` | 内存主机状态辅助工具 | 内存主机状态辅助工具 |
| `plugin-sdk/memory-core-host-runtime-cli` | 内存主机 CLI 运行时 | 内存主机 CLI 运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-core` | 内存主机核心运行时 | 内存主机核心运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-files` | 内存主机文件/运行时辅助工具 | 内存主机文件/运行时辅助工具 |
| `plugin-sdk/memory-host-core` | 内存主机核心运行时别名 | 面向厂商中立的内存主机核心运行时辅助工具别名 |
| `plugin-sdk/memory-host-events` | 内存主机事件日志别名 | 面向厂商中立的内存主机事件日志辅助工具别名 |
| `plugin-sdk/memory-host-files` | 内存主机文件/运行时别名 | 面向厂商中立的内存主机文件/运行时辅助工具别名 |
| `plugin-sdk/memory-host-markdown` | 托管 markdown 辅助工具 | 面向内存相关插件的共享托管 markdown 辅助工具 |
| `plugin-sdk/memory-host-search` | 活跃内存搜索外观层 | 延迟活跃内存 search-manager 运行时外观层 |
| `plugin-sdk/memory-host-status` | 内存主机状态别名 | 面向厂商中立的内存主机状态辅助工具别名 |
| `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | memory-lancedb 辅助接口 |
| `plugin-sdk/testing` | 测试工具 | 测试辅助工具和 mock |
</Accordion>
此表刻意只包含常见迁移子集，而不是完整的 SDK 接口。完整的 200+ 入口点列表位于
`scripts/lib/plugin-sdk-entrypoints.json`。
此表有意只包含常见迁移子集，而不是完整的 SDK 接口。完整的 200 多个入口点列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。
该列表仍然包含一些内置插件辅助接口，例如
`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*`。这些接口仍然会为了内置插件维护和兼容性而导出，但它们被有意省略出常见迁移表，也不是新插件代码的推荐目标。
同样的规则也适用于其他内置辅助工具族，例如：
同样的规则也适用于其他内置辅助工具家族，例如：
- 浏览器支持辅助工具：`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`
- Matrix：`plugin-sdk/matrix*`
- LINE：`plugin-sdk/line*`
- IRC：`plugin-sdk/irc*`
- 内置辅助工具 / 插件接口，例如 `plugin-sdk/googlechat`、
- 内置辅助/插件接口，例如 `plugin-sdk/googlechat`、
`plugin-sdk/zalouser`、`plugin-sdk/bluebubbles*`、
`plugin-sdk/mattermost*`、`plugin-sdk/msteams`、
`plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/tlon`、
@ -332,38 +331,35 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚
`plugin-sdk/diagnostics-otel`、`plugin-sdk/diffs`、`plugin-sdk/llm-task`、
`plugin-sdk/thread-ownership` 和 `plugin-sdk/voice-call`
`plugin-sdk/github-copilot-token` 目前公开的窄范围 token 辅助接口包括
`DEFAULT_COPILOT_API_BASE_URL`、
`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。
`plugin-sdk/github-copilot-token` 当前公开的窄范围 token 辅助接口包括 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。
请使用与任务最匹配的最窄导入路径。如果你找不到某个导出，
请检查 `src/plugin-sdk/` 下的源码，或在 Discord 中提问。
请使用与你任务最匹配的最窄导入路径。如果你找不到某个导出，请检查 `src/plugin-sdk/` 下的源代码，或在 Discord 中提问。
## 移除时间线
| 时间 | 会发生什么 |
| ---------------------- | ----------------------------------------------------------------------- |
| **现在** | 已弃用接口会发出运行时警告 |
| **下一个主要版本** | 已弃用接口将被移除；仍在使用它们的插件将会失效 |
| **下一个主版本** | 已弃用接口将被移除；仍在使用它们的插件将会失败 |
所有 core 插件都已完成迁移。外部插件应在下一个主要版本之前完成迁移。
所有核心插件都已经完成迁移。外部插件应在下一个主版本之前完成迁移。
## 临时抑制警告
## 暂时抑制警告
在迁移期间，设置这些环境变量：
在你进行迁移期间，可以设置这些环境变量：
```bash
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
```
这只是临时的应急出口，不是永久解决方案。
这是一个临时逃生口，而不是永久解决方案。
## 相关内容
- [入门指南](/zh-CN/plugins/building-plugins) — 构建你的第一个插件
- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考
- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件
- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建 provider 插件
- [插件内部机制](/zh-CN/plugins/architecture) — 架构深入解析
- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件
- [插件内部机制](/zh-CN/plugins/architecture) — 架构深度解析
- [插件清单](/zh-CN/plugins/manifest) — 清单 schema 参考

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

@ -2,22 +2,22 @@
read_when:
- 你需要知道应该从哪个 SDK 子路径导入
- 你想查看 OpenClawPluginApi 上所有注册方法的参考
- 你正在查找某个特定的 SDK 导出项
- 你正在查找某个特定的 SDK 导出
sidebarTitle: SDK Overview
summary: 导入映射、注册 API 参考和 SDK 架构
title: 插件 SDK 概览
x-i18n:
generated_at: "2026-04-07T18:43:29Z"
generated_at: "2026-04-07T20:09:23Z"
model: gpt-5.4
provider: openai
source_hash: 68d9b78dab757747cfa0e315376af72040ef79453129c0fa051c4c9dd948060f
source_hash: c5a41bd82d165dfbb7fbd6e4528cf322e9133a51efe55fa8518a7a0a626d9d30
source_path: plugins/sdk-overview.md
workflow: 15
---
# 插件 SDK 概览
插件 SDK 是插件与核心之间的类型化契约。此页面是关于**导入什么**以及**你可以注册什么**的参考。
插件 SDK 是插件与核心之间的类型化契约。本页是关于**该导入什么**以及**你可以注册什么**的参考。
<Tip>
**在找操作指南吗？**
@ -28,24 +28,24 @@ x-i18n:
## 导入约定
始终从特定子路径导入：
始终从特定的子路径导入：
```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`。
保留的内置插件辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其宣传为公共接口，否则应将它们视为实现细节/兼容性表面。
保留的内置插件辅助工具子路径仍会出现在该生成列表中。除非某个文档页面明确将其作为公开接口推广，否则应将它们视为实现细节/兼容性接口。
### 插件入口点
@ -75,7 +75,7 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 |
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/验证辅助工具，并带有内置契约回退 |
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助工具，并带有内置契约回退 |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助工具 |
@ -89,20 +89,20 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
| `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 |
| `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 |
| `plugin-sdk/channel-status` | 共享渠道状态快照/摘要辅助工具 |
| `plugin-sdk/channel-config-primitives` | 狭义渠道配置 schema 原语 |
| `plugin-sdk/channel-config-primitives` | 狭义渠道配置 schema 基元 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 |
| `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 |
| `plugin-sdk/channel-plugin-common` | 共享渠道插件前置导出 |
| `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取辅助工具 |
| `plugin-sdk/group-access` | 共享群组访问决策辅助工具 |
| `plugin-sdk/direct-dm` | 共享直接私信认证/防护辅助工具 |
| `plugin-sdk/direct-dm` | 共享直接私信身份验证/保护辅助工具 |
| `plugin-sdk/interactive-runtime` | 交互式回复负载规范化/归约辅助工具 |
| `plugin-sdk/channel-inbound` | 入站去抖、提及匹配、提及策略辅助工具以及 envelope 辅助工具 |
| `plugin-sdk/channel-inbound` | 入站去抖、提及匹配、提及策略辅助工具，以及 envelope 辅助工具 |
| `plugin-sdk/channel-send-result` | 回复结果类型 |
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`、`createMessageToolCardSchema` |
| `plugin-sdk/channel-targets` | 目标解析/匹配辅助工具 |
| `plugin-sdk/channel-contract` | 渠道契约类型 |
| `plugin-sdk/channel-feedback` | 反馈/反应接线 |
| `plugin-sdk/channel-secret-runtime` | 狭义 secret 契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和 secret 目标类型 |
| `plugin-sdk/channel-secret-runtime` | 狭义密钥契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和密钥目标类型 |
</Accordion>
<Accordion title="提供商子路径">
@ -110,48 +110,50 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助工具 |
| `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商的专用设置辅助工具 |
| `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 新手引导/配置文件写入辅助工具，例如 `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API 密钥解析辅助工具 |
| `plugin-sdk/provider-auth-api-key` | API 密钥新手引导/配置文件写入辅助工具，例如 `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | 标准 OAuth auth-result 构建器 |
| `plugin-sdk/provider-auth-login` | 提供商插件的共享交互式登录辅助工具 |
| `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`、`ensureApiKeyFromOptionEnvOrPrompt`、`upsertAuthProfile`、`upsertApiKeyProfile`、`writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助工具，以及像 `normalizeNativeXaiModelId` 这样的模型 ID 规范化辅助工具 |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助工具，以及模型 ID 规范化辅助工具，例如 `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` |
| `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-contract` | 狭义 web-search 配置/凭证契约辅助工具，例如 `enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 和作用域凭证 setter/getter |
| `plugin-sdk/provider-web-search` | web-search 提供商注册/缓存/运行时辅助工具 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似功能 |
| `plugin-sdk/provider-web-fetch` | Web-fetch 提供商注册/缓存辅助工具 |
| `plugin-sdk/provider-web-search-contract` | 狭义 web-search 配置/凭证契约辅助工具，例如 `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-onboard` | 新手引导配置补丁辅助工具 |
| `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助工具 |
| `plugin-sdk/global-singleton` | 进程内本地 singleton/map/cache 辅助工具 |
</Accordion>
<Accordion title="认证与安全子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送者授权辅助工具 |
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天操作认证辅助工具 |
| `plugin-sdk/approval-client-runtime` | 原生执行审批配置文件/过滤器辅助工具 |
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作认证辅助工具 |
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件/过滤辅助工具 |
| `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 |
| `plugin-sdk/approval-handler-runtime` | 共享审批处理器运行时辅助工具，包括能力驱动的原生审批加载 |
| `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 |
| `plugin-sdk/approval-handler-adapter-runtime` | 面向高频渠道入口点的轻量级原生审批适配器加载辅助工具 |
| `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；当狭义适配器/Gateway 网关接缝已足够时，优先使用后者 |
| `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 |
| `plugin-sdk/approval-reply-runtime` | exec/plugin 审批回复负载辅助工具 |
| `plugin-sdk/approval-reply-runtime` | exec/插件审批回复负载辅助工具 |
| `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助工具 |
| `plugin-sdk/command-detection` | 共享命令检测辅助工具 |
| `plugin-sdk/command-surface` | 命令体规范化和命令表面辅助工具 |
| `plugin-sdk/command-surface` | 命令体规范化和命令接口辅助工具 |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | 用于渠道/插件 secret 表面的狭义 secret 契约收集辅助工具 |
| `plugin-sdk/secret-ref-runtime` | 用于 secret 契约/配置解析的狭义 `coerceSecretRef` 和 SecretRef 类型辅助工具 |
| `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和 secret 收集辅助工具 |
| `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-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch 和 SSRF 策略辅助工具 |
| `plugin-sdk/secret-input` | secret 输入解析辅助工具 |
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch，以及 SSRF 策略辅助工具 |
| `plugin-sdk/secret-input` | 密钥输入解析辅助工具 |
| `plugin-sdk/webhook-ingress` | webhook 请求/目标辅助工具 |
| `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助工具 |
</Accordion>
@ -160,54 +162,54 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/runtime` | 广义运行时/日志/备份/插件安装辅助工具 |
| `plugin-sdk/runtime-env` | 狭义运行时环境、logger、timeout、retry 和 backoff 辅助工具 |
| `plugin-sdk/runtime-env` | 狭义运行时环境、logger、超时、重试和退避辅助工具 |
| `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助工具 |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | 共享插件命令/hook/http/交互式辅助工具 |
| `plugin-sdk/hook-runtime` | 共享 webhook/内部 hook 管道辅助工具 |
| `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | 进程执行辅助工具 |
| `plugin-sdk/process-runtime` | 进程 exec 辅助工具 |
| `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助工具 |
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助工具 |
| `plugin-sdk/config-runtime` | 配置加载/写入辅助工具 |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约表面不可用时也能工作 |
| `plugin-sdk/approval-runtime` | exec/plugin 审批辅助工具、审批能力构建器、认证/配置文件辅助工具、原生路由/运行时辅助工具 |
| `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块、分发、心跳、回复规划器 |
| `plugin-sdk/reply-dispatch-runtime` | 狭义回复分发/完成辅助工具 |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约接口不可用时也适用 |
| `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-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | 狭义文本/Markdown 分块辅助工具 |
| `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助工具 |
| `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助工具 |
| `plugin-sdk/routing` | 路由/会话键/账户绑定辅助工具，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | 共享渠道/账户状态摘要辅助工具、运行时状态默认值和 issue 元数据辅助工具 |
| `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/param-readers` | 通用工具/CLI 参数读取器 |
| `plugin-sdk/request-url` | 从 fetch/request-like 输入中提取字符串 URL |
| `plugin-sdk/run-command` | 带定时功能的命令运行器，返回规范化的 stdout/stderr 结果 |
| `plugin-sdk/param-readers` | 常用工具/CLI 参数读取器 |
| `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 |
| `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 |
| `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助工具 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助工具 |
| `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 |
| `plugin-sdk/file-lock` | 可重入文件锁辅助工具 |
| `plugin-sdk/persistent-dedupe` | 基于磁盘的去重缓存辅助工具 |
| `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 |
| `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助工具 |
| `plugin-sdk/agent-config-primitives` | 狭义智能体运行时配置 schema 原语 |
| `plugin-sdk/agent-config-primitives` | 狭义智能体运行时配置 schema 基元 |
| `plugin-sdk/boolean-param` | 宽松布尔参数读取器 |
| `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 |
| `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 |
| `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助原语 |
| `plugin-sdk/extension-shared` | 共享被动渠道、状态和 ambient proxy 辅助基元 |
| `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 |
| `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 |
| `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助工具 |
| `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助工具 |
| `plugin-sdk/infra-runtime` | 系统事件/心跳辅助工具 |
| `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/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | 包装过的 fetch、代理和 pinned lookup 辅助工具 |
| `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 |
| `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 |
| `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助工具 |
@ -218,12 +220,12 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
<Accordion title="能力与测试子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具以及媒体负载构建器 |
| `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具，以及媒体负载构建器 |
| `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选项选择和缺失模型提示 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助工具导出 |
| `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如 assistant-visible-text 剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本实用工具 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助导出 |
| `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如助手可见文本剥离、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` | 实时语音提供商类型和注册表辅助工具 |
@ -243,38 +245,38 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
<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 主机基础引擎导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory 主机嵌入引擎导出 |
| `plugin-sdk/memory-core-host-engine-qmd` | Memory 主机 QMD 引擎导出 |
| `plugin-sdk/memory-core-host-engine-storage` | Memory 主机存储引擎导出 |
| `plugin-sdk/memory-core-host-multimodal` | Memory 主机多模态辅助工具 |
| `plugin-sdk/memory-core-host-query` | Memory 主机查询辅助工具 |
| `plugin-sdk/memory-core-host-secret` | Memory 主机 secret 辅助工具 |
| `plugin-sdk/memory-core-host-events` | Memory 主机事件日志辅助工具 |
| `plugin-sdk/memory-core-host-status` | Memory 主机状态辅助工具 |
| `plugin-sdk/memory-core-host-runtime-cli` | Memory 主机 CLI 运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-core` | Memory 主机核心运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-files` | Memory 主机文件/运行时辅助工具 |
| `plugin-sdk/memory-host-core` | 面向供应商中立的别名，用于 memory 主机核心运行时辅助工具 |
| `plugin-sdk/memory-host-events` | 面向供应商中立的别名，用于 memory 主机事件日志辅助工具 |
| `plugin-sdk/memory-host-files` | 面向供应商中立的别名，用于 memory 主机文件/运行时辅助工具 |
| `plugin-sdk/memory-host-markdown` | 面向 memory 邻接插件的共享托管 Markdown 辅助工具 |
| `plugin-sdk/memory-host-search` | 用于 search-manager 访问的活动 memory 运行时门面 |
| `plugin-sdk/memory-host-status` | 面向供应商中立的别名，用于 memory 主机状态辅助工具 |
| `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助表面 |
| `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding engine 导出 |
| `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 密钥辅助工具 |
| `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助工具 |
| `plugin-sdk/memory-core-host-status` | Memory host 状态辅助工具 |
| `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-search` | 用于访问搜索管理器的活动 Memory 运行时门面 |
| `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-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>
@ -284,51 +286,51 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
### 能力注册
| 方法 | 注册内容 |
| 方法 | 它注册的内容 |
| ------------------------------------------------ | -------------------------------- |
| `api.registerProvider(...)` | 文本推理（LLM） |
| `api.registerCliBackend(...)` | 本地 CLI 推理后端 |
| `api.registerChannel(...)` | 消息渠道 |
| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 |
| `api.registerProvider(...)` | 文本推理（LLM） |
| `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.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.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.registerMemoryPromptSupplement(builder)` | 可叠加的、与 Memory 相邻的提示词区段 |
| `api.registerMemoryCorpusSupplement(adapter)` | 可叠加的 Memory 搜索/读取语料 |
保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用插件特定前缀。
保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用特定于插件的前缀。
### CLI 注册元数据
`api.registerCli(registrar, opts?)` 接受两种顶层元数据：
`api.registerCli(registrar, opts?)` 接受两类顶层元数据：
- `commands`：由该 registrar 拥有的显式命令根
- `commands`：由 registrar 拥有的显式命令根
- `descriptors`：用于根 CLI 帮助、路由和惰性插件 CLI 注册的解析时命令描述符
如果你希望插件命令在正常的根 CLI 路径中保持惰性加载，请提供 `descriptors`，覆盖该 registrar 暴露的每个顶层命令根。
如果你希望插件命令在普通根 CLI 路径中保持惰性加载，请提供覆盖该 registrar 暴露的每个顶层命令根的 `descriptors`。
```typescript
api.registerCli(
@ -348,72 +350,72 @@ api.registerCli(
);
```
仅在你不需要惰性根 CLI 注册时才单独使用 `commands`。这种急切兼容路径仍受支持，但它不会为解析时惰性加载安装基于 descriptor 的占位符。
仅当你不需要惰性的根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍然受支持，但它不会为解析时惰性加载安装基于 descriptor 的占位符。
### CLI 后端注册
`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端的默认配置，例如 `codex-cli`。
`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（例如 `codex-cli`）的默认配置。
- 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。
- 后端 `config` 使用与 `agents.defaults.cliBackends.<id>` 相同的结构。
- 用户配置仍然优先生效。OpenClaw 会先将 `agents.defaults.cliBackends.<id>` 合并到插件默认值之上，再运行 CLI。
- 当后端在合并后需要兼容性重写时，请使用 `normalizeConfig`（例如规范化旧版 flag 结构）。
- 当某个后端在合并后需要兼容性重写时，使用 `normalizeConfig`（例如规范化旧的 flag 结构）。
### 独占槽位
| 方法 | 注册内容 |
| 方法 | 它注册的内容 |
| ------------------------------------------ | ------------------------------------- |
| `api.registerContextEngine(id, factory)` | 上下文引擎（一次仅一个处于激活状态） |
| `api.registerMemoryCapability(capability)` | 统一 memory 能力 |
| `api.registerMemoryPromptSection(builder)` | memory 提示区段构建器 |
| `api.registerMemoryFlushPlan(resolver)` | memory 刷新计划解析器 |
| `api.registerMemoryRuntime(runtime)` | memory 运行时适配器 |
| `api.registerContextEngine(id, factory)` | 上下文引擎（同一时间仅一个活动） |
| `api.registerMemoryCapability(capability)` | 统一 Memory 能力 |
| `api.registerMemoryPromptSection(builder)` | Memory 提示词区段构建器 |
| `api.registerMemoryFlushPlan(resolver)` | Memory 刷新计划解析器 |
| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 |
### Memory 嵌入适配器
| 方法 | 注册内容 |
| 方法 | 它注册的内容 |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 memory 嵌入适配器 |
| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 Memory 嵌入适配器 |
- `registerMemoryCapability` 是首选的独占 memory 插件 API。
- `registerMemoryCapability` 也可以暴露 `publicArtifacts.listArtifacts(...)`，这样配套插件就可以通过 `openclaw/plugin-sdk/memory-host-core` 消费导出的 memory 工件，而不是深入特定 memory 插件的私有布局。
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占 memory 插件 API。
- `registerMemoryEmbeddingProvider` 允许活动 memory 插件注册一个或多个嵌入适配器 ID（例如 `openai`、`gemini`，或自定义的插件定义 ID）。
- 用户配置，例如 `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 插件注册一个或多个嵌入适配器 ID（例如 `openai`、`gemini` 或插件自定义 ID）。
- 用户配置（例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）会基于这些已注册的适配器 ID 进行解析。
### 事件与生命周期
| 方法 | 作用 |
| 方法 | 它的作用 |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook |
| `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` | 当前配置快照（可用时为活动的内存中运行时快照） |
| `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` | 解析相对于插件根目录的路径 |
| `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` | 解析相对于插件根目录的路径 |
## 内部模块约定
@ -421,32 +423,27 @@ api.registerCli(
```
my-plugin/
api.ts # 面向外部使用者的公共导出
api.ts # 面向外部使用者的公开导出
runtime-api.ts # 仅供内部使用的运行时导出
index.ts # 插件入口点
setup-entry.ts # 轻量级仅设置入口（可选）
setup-entry.ts # 仅设置用的轻量入口点（可选）
```
<Warning>
永远不要在生产代码中通过 `openclaw/plugin-sdk/<your-plugin>`
导入你自己的插件。内部导入应通过 `./api.ts` 或
`./runtime-api.ts`。SDK 路径仅是对外契约。
不要在生产代码中通过 `openclaw/plugin-sdk/<your-plugin>` 导入你自己的插件。应通过 `./api.ts` 或 `./runtime-api.ts` 进行内部导入。SDK 路径仅是对外契约。
</Warning>
通过门面加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）现在会在 OpenClaw 已运行时优先使用活动运行时配置快照。如果尚不存在运行时快照，则会回退到磁盘上已解析的配置文件。
由门面加载的内置插件公开接口（`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` 导出提供商构建器以及新手引导/配置辅助工具
<Warning>
扩展生产代码也应避免导入 `openclaw/plugin-sdk/<other-plugin>`。
如果某个辅助工具确实需要共享，应将其提升到中立的 SDK 子路径，
例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或其他
面向能力的表面，而不是把两个插件耦合在一起。
扩展生产代码也应避免导入 `openclaw/plugin-sdk/<other-plugin>`。如果某个辅助工具确实需要共享，应将其提升到中立的 SDK 子路径，例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他面向能力的接口，而不是让两个插件彼此耦合。
</Warning>
## 相关内容
@ -455,5 +452,5 @@ my-plugin/
- [运行时辅助工具](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考
- [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、清单、配置 schema
- [测试](/zh-CN/plugins/sdk-testing) — 测试工具和 lint 规则
- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用表面迁移
- [插件内部机制](/zh-CN/plugins/architecture) — 深入架构与能力模型
- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用接口迁移
- [插件内部机制](/zh-CN/plugins/architecture) — 深入架构和能力模型