Appearance
本页是 OpenClaw 插件 SDK 迁移指南，适合仍在使用旧版 plugin-sdk/compat、plugin-sdk/infra-runtime 或 openclaw/extension-api 的插件作者。第一个动作：搜索插件中这些导入路径，然后按步骤替换为 openclaw/plugin-sdk/<子路径> 的聚焦导入。下一个主版本将移除旧接口，迁移前可用 OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 临时抑制警告。
OpenClaw 插件 SDK 迁移：从旧版兼容层升级到现代子路径导入
OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，采用聚焦、有文档的导入路径。如果你的插件是在新架构之前构建的，本指南帮助你完成迁移。
正在变更的内容
旧版插件系统提供了多个开放导入表面：
openclaw/plugin-sdk/compat— 单一导入重新导出数十个 helper，在新插件架构构建期间用于保持旧版 hook 插件正常工作openclaw/plugin-sdk/infra-runtime— 宽泛的 runtime helper barrel，混合了系统事件、心跳状态、投递队列、fetch/proxy helper、文件 helper、审批类型和不相关的工具函数openclaw/plugin-sdk/config-runtime— 宽泛的配置兼容性 barrel，迁移窗口期仍携带废弃的直接加载/写入 helperopenclaw/extension-api— 给插件直接访问宿主端 helper（如嵌入式 agent runner）的桥接接口api.registerEmbeddedExtensionFactory(...)— 已移除的 Pi 专用捆绑扩展钩子，可观察tool_result等事件
上述导入表面现已废弃。它们在 runtime 仍然工作，但新插件禁止使用，现有插件应在下一个主版本移除它们之前完成迁移。Pi 专用的嵌入式扩展工厂注册 API 已被移除；改用 tool-result 中间件。
警告： 向后兼容层将在未来主版本中被移除。仍然从这些接口导入的插件届时将失效。Pi 专用的嵌入式扩展工厂注册已不再加载。
为什么做这个改变
旧方式带来了以下问题：
- 启动慢 — 导入一个 helper 会加载数十个无关模块
- 循环依赖 — 宽泛的重新导出容易产生导入循环
- API 边界不清 — 无法区分哪些导出是稳定 API，哪些是内部实现
现代插件 SDK 修复了这些问题：每个导入路径（openclaw/plugin-sdk/<subpath>）是一个小型、自包含的模块，有明确用途和文档化的合约。
旧版 Provider 便利接缝（如渠道品牌 helper 接缝）也已移除——这些只是私有 monorepo 快捷方式，不是稳定的插件合约。改用窄型通用 SDK 子路径代替。内置插件内部使用的 Provider 专属 helper 应留在该插件自己的 api.ts 或 runtime-api.ts 中。
Talk 与实时语音迁移计划
实时语音、电话、会议和浏览器 Talk 代码正在从表层本地的 turn 管理迁移到由 openclaw/plugin-sdk/realtime-voice 导出的共享 Talk 会话控制器。新控制器拥有通用的 Talk 事件信封、活跃 turn 状态、捕获状态、输出音频状态、近期事件历史以及过期 turn 拒绝。Provider 插件应保持管理厂商特有的实时会话；表层插件应保持管理捕获、播放和电话/会议特殊行为。
本次 Talk 迁移是有意做成破坏性清理的：
- 将共享控制器/runtime 原语保留在
plugin-sdk/realtime-voice - 将捆绑表层迁移到共享控制器：浏览器 relay、managed-room 交接、语音通话实时、语音通话流式 STT、Google Meet 实时、原生 push-to-talk
- 用最终的
talk.session.*和talk.client.*API 替换旧的 Talk RPC 家族 - 在 Gateway
hello-ok.features.events中发布一个实时 Talk 事件通道：talk.event - 删除旧的实时 HTTP 端点及任何请求时指令覆盖路径
新代码不应直接调用 createTalkEventSequencer(...)，除非实现底层适配器或测试 fixture。优先使用共享控制器，这样 turn 范围的事件不会在没有 turn id 时发出，过期的 turnEnd/turnCancel 调用不会清除更新的活跃 turn，输出音频生命周期事件在电话、会议、浏览器 relay、managed-room 交接和原生 Talk 客户端之间保持一致。
目标公有 API 形状及支持的 talk.session.create 组合见原文表格。不再在此重复。
移除方法对照表：
| 旧方法 | 新方法 |
|---|---|
talk.realtime.session | talk.client.create |
talk.realtime.toolCall | talk.client.toolCall |
talk.realtime.relayAudio | talk.session.appendAudio |
talk.realtime.relayCancel | talk.session.cancelOutput 或 talk.session.cancelTurn |
talk.realtime.relayToolResult | talk.session.submitToolResult |
talk.realtime.relayStop | talk.session.close |
talk.transcription.session | talk.session.create({ mode: "transcription" }) |
talk.transcription.relayAudio | talk.session.appendAudio |
talk.transcription.relayCancel | talk.session.cancelTurn |
talk.transcription.relayStop | talk.session.close |
talk.handoff.create | talk.session.create({ transport: "managed-room" }) |
talk.handoff.join | talk.session.join |
talk.handoff.revoke | talk.session.close |
统一控制词汇表也故意精简，见原文表格（不再重复）。不要为核心引入 Provider 或平台特例来实现这些。核心拥有 Talk 会话语义。Provider 插件拥有厂商会话设置。语音呼叫和 Google Meet 拥有电话/会议适配器。浏览器和原生应用拥有设备捕获/播放 UX。
兼容性策略
对外部插件，兼容性工作按以下顺序进行：
- 添加新合约
- 通过兼容适配器保持旧行为
- 发出诊断或警告，指出旧路径和替换路径
- 在测试中覆盖两条路径
- 记录废弃和迁移路径
- 仅在宣布的迁移窗口后移除，通常在主版本中
维护者可以使用 pnpm plugins:boundary-report 审计当前迁移队列。使用 pnpm plugins:boundary-report:summary 获取紧凑计数，--owner <id> 针对一个插件或兼容性所有者，pnpm plugins:boundary-report:ci 让 CI 关卡在废弃兼容记录、跨所有者保留 SDK 导入或未使用的保留 SDK 子路径时失败。报告按移除日期分组废弃兼容记录，计数本地代码/文档引用，呈现跨所有者保留 SDK 导入，并总结私有内存宿主 SDK 桥接，使兼容性清理显式而非依赖临时搜索。
如果清单字段仍被接受，插件作者可以继续使用它，直到文档和诊断另有说明。新代码应优先使用文档中替换项，但现有插件在普通次要版本中不应受影响。
迁移步骤
步骤 1：迁移 runtime 配置加载/写入 helper
捆绑插件应停止直接调用 api.runtime.config.loadConfig() 和 api.runtime.config.writeConfigFile(...)。优先使用已传入活跃调用路径的配置。需要当前进程快照的长期运行 handler 可使用 api.runtime.config.current()。长期运行的 agent 工具应在 execute 内部使用工具上下文的 ctx.getRuntimeConfig()，这样在配置写入之前创建的工具仍能看到刷新后的 runtime 配置。
配置写入必须通过事务性 helper 并选择写入后策略：
typescript
await api.runtime.config.mutateConfigFile({
afterWrite: { mode: "auto" },
mutate(draft) {
draft.plugins ??= {};
},
});当调用者知道更改需要干净的 gateway 重启时，使用 afterWrite: { mode: "restart", reason: "..." }；仅当调用者拥有后续处理且有意抑制重新加载计划时使用 afterWrite: { mode: "none", reason: "..." }。Mutation 结果包含类型化的 followUp 摘要供测试和日志记录；gateway 负责应用或计划重启。loadConfig 和 writeConfigFile 在迁移窗口期作为废弃的兼容性 helper 保留给外部插件，并带兼容性代码 runtime-config-load-write 发出一次警告。捆绑插件和仓库 runtime 代码受扫描守卫保护，在 pnpm check:deprecated-api-usage 和 pnpm check:no-runtime-action-load-config 中：新生产插件用法将直接失败，直接配置写入失败，gateway 服务器方法必须使用请求 runtime 快照，runtime 渠道发送/动作/客户端 helper 必须从其边界接收配置，长期运行的 runtime 模块不允许有 loadConfig() 调用。
新插件代码还应避免导入宽泛的 openclaw/plugin-sdk/config-runtime 兼容性 barrel。改用匹配任务的窄 SDK 子路径：
| 需求 | 导入 |
|---|---|
Config 类型如 OpenClawConfig | openclaw/plugin-sdk/config-contracts |
| 已加载配置断言和插件入口配置查找 | openclaw/plugin-sdk/plugin-config-runtime |
| 当前 runtime 快照读取 | openclaw/plugin-sdk/runtime-config-snapshot |
| 配置写入 | openclaw/plugin-sdk/config-mutation |
| 会话存储 helper | openclaw/plugin-sdk/session-store-runtime |
| Markdown 表格配置 | openclaw/plugin-sdk/markdown-table-runtime |
| 组策略 runtime helper | openclaw/plugin-sdk/runtime-group-policy |
| 秘密输入解析 | openclaw/plugin-sdk/secret-input-runtime |
| 模型/会话覆盖 | openclaw/plugin-sdk/model-session-runtime |
捆绑插件及其测试受扫描守卫防止使用宽泛 barrel，因此导入和 mock 保持在它们所需的行为附近。宽泛 barrel 仍为外部兼容性存在，但新代码不应依赖它。
步骤 2：迁移 Pi tool-result 扩展为中间件
捆绑插件必须将 Pi 专用的 api.registerEmbeddedExtensionFactory(...) tool-result handler 替换为 runtime 中立的中间件：
typescript
// Pi 和 Codex runtime 动态工具
api.registerAgentToolResultMiddleware(async (event) => {
return compactToolResult(event);
}, {
runtimes: ["pi", "codex"],
});同时更新插件清单：
json
{
"contracts": {
"agentToolResultMiddleware": ["pi", "codex"]
}
}外部插件无法注册 tool-result 中间件，因为它会在模型看到之前重写高信任工具输出。
步骤 3：迁移审批原生 handler 为能力事实
支持审批的渠道插件现在通过 approvalCapability.nativeRuntime 加上共享 runtime-context 注册表暴露原生审批行为。
关键变化：
- 用
approvalCapability.nativeRuntime替换approvalCapability.handler.loadRuntime(...) - 将审批专用认证/投递从遗留
plugin.auth/plugin.approvals接线移到approvalCapability ChannelPlugin.approvals已从公有渠道插件合约中移除；将投递/原生/渲染字段移到approvalCapabilityplugin.auth仅保留用于渠道登录/登出流程；核心不再读取那里的审批认证钩子- 通过
openclaw/plugin-sdk/channel-runtime-context注册渠道拥有的 runtime 对象，如客户端、令牌或 Bolt 应用 - 不要从原生审批 handler 发送插件拥有的重路由通知；核心现在从实际投递结果拥有路由到别处的通知
- 当将
channelRuntime传入createChannelManager(...)时，提供真实的createPluginRuntime().channel表面。部分桩将被拒绝。
参见 /plugins/sdk-channel-plugins 了解当前审批能力布局。
步骤 4：审查 Windows Spawn 回退行为
如果你的插件使用了 openclaw/plugin-sdk/windows-spawn，未解析的 Windows .cmd/.bat 包装器现在默认失败关闭，除非显式传 allowShellFallback: true：
typescript
// 迁移前
const program = applyWindowsSpawnProgramPolicy({ candidate });
// 迁移后
const program = applyWindowsSpawnProgramPolicy({
candidate,
// 只对确实需要 shell 回退的受信任兼容调用者设置此参数
allowShellFallback: true,
});如果调用者不依赖 shell 回退，不要设 allowShellFallback，改为处理抛出的错误。
步骤 5：找出废弃导入
搜索插件中来自废弃表面的导入：
bash
grep -r "plugin-sdk/compat" my-plugin/
grep -r "plugin-sdk/infra-runtime" my-plugin/
grep -r "plugin-sdk/config-runtime" my-plugin/
grep -r "openclaw/extension-api" my-plugin/步骤 6：替换为聚焦导入
旧表面中的每个导出都对应一个具体的现代导入路径：
typescript
// 迁移前（废弃的向后兼容层）
import {
createChannelReplyPipeline,
createPluginRuntimeStore,
resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";
// 迁移后（现代聚焦导入）
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";宿主端 helper 通过注入的插件 runtime 使用，而非直接导入：
typescript
// 迁移前（废弃的 extension-api 桥接）
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });
// 迁移后（注入的 runtime）
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });其他旧版桥接 helper 的对应关系：
| 旧导入 | 现代等效 |
|---|---|
resolveAgentDir | api.runtime.agent.resolveAgentDir |
resolveAgentWorkspaceDir | api.runtime.agent.resolveAgentWorkspaceDir |
resolveAgentIdentity | api.runtime.agent.resolveAgentIdentity |
resolveThinkingDefault | api.runtime.agent.resolveThinkingDefault |
resolveAgentTimeoutMs | api.runtime.agent.resolveAgentTimeoutMs |
ensureAgentWorkspace | api.runtime.agent.ensureAgentWorkspace |
| session store helper | api.runtime.agent.session.* |
步骤 7：替换宽泛的 infra-runtime 导入
openclaw/plugin-sdk/infra-runtime 仍为外部兼容性存在，但新代码应导入它实际需要的聚焦 helper surface：
| 需求 | 导入 |
|---|---|
| 系统事件队列 helper | openclaw/plugin-sdk/system-event-runtime |
| 心跳唤醒、事件和可见性 helper | openclaw/plugin-sdk/heartbeat-runtime |
| 待投递队列 drain | openclaw/plugin-sdk/delivery-queue-runtime |
| 渠道活动遥测 | openclaw/plugin-sdk/channel-activity-runtime |
| 内存去重缓存 | openclaw/plugin-sdk/dedupe-runtime |
| 安全的本地文件/媒体路径 helper | openclaw/plugin-sdk/file-access-runtime |
| 分发器感知的 fetch | openclaw/plugin-sdk/runtime-fetch |
| 代理和受保护 fetch helper | openclaw/plugin-sdk/fetch-runtime |
| SSRF 分发器策略类型 | openclaw/plugin-sdk/ssrf-dispatcher |
| 审批请求/解析类型 | openclaw/plugin-sdk/approval-runtime |
| 审批回复载荷和命令 helper | openclaw/plugin-sdk/approval-reply-runtime |
| 错误格式化 helper | openclaw/plugin-sdk/error-runtime |
| 传输就绪等待 | openclaw/plugin-sdk/transport-ready-runtime |
| 安全令牌 helper | openclaw/plugin-sdk/secure-random-runtime |
| 有界异步任务并发 | openclaw/plugin-sdk/concurrency-runtime |
| 数值强制转换 | openclaw/plugin-sdk/number-runtime |
| 进程本地异步锁 | openclaw/plugin-sdk/async-lock-runtime |
| 文件锁 | openclaw/plugin-sdk/file-lock |
捆绑插件受扫描守卫防止使用 infra-runtime，因此仓库代码不会回退到宽泛 barrel。
步骤 8：迁移渠道路由 helper
新渠道路由代码应使用 openclaw/plugin-sdk/channel-route。旧的路由键和可比较目标名称在迁移窗口期内保持为兼容别名，但新插件应直接描述行为的路由名称：
| 旧 helper | 现代 helper |
|---|---|
channelRouteIdentityKey(...) | channelRouteDedupeKey(...) |
channelRouteKey(...) | channelRouteCompactKey(...) |
ComparableChannelTarget | ChannelRouteParsedTarget |
resolveComparableTargetForChannel(...) | resolveRouteTargetForChannel(...) |
resolveComparableTargetForLoadedChannel(...) | resolveRouteTargetForLoadedChannel(...) |
comparableChannelTargetsMatch(...) | channelRouteTargetsMatchExact(...) |
comparableChannelTargetsShareRoute(...) | channelRouteTargetsShareConversation(...) |
现代路由 helper 在原生审批、回复抑制、入站去重、cron 投递和会话路由中一致地规范化 { channel, to, accountId, threadId }。如果你的插件拥有自定义目标语法，使用 resolveChannelRouteTargetWithParser(...) 将该解析器适配到同一个路由目标合约。
步骤 9：构建并测试
bash
pnpm build
pnpm test -- my-plugin/导入路径参考
常用导入路径表
| 导入路径 | 用途 | 关键导出 |
|---|---|---|
plugin-sdk/plugin-entry | 插件入口 helper | definePluginEntry |
plugin-sdk/core | 渠道入口定义/构建的兼容重新导出 | defineChannelPluginEntry, createChatChannelPlugin |
plugin-sdk/config-schema | 根配置 schema | OpenClawSchema |
plugin-sdk/provider-entry | 单 Provider 入口 helper | defineSingleProviderPluginEntry |
plugin-sdk/channel-core | 渠道入口定义和构建 helper | defineChannelPluginEntry, defineSetupPluginEntry, createChatChannelPlugin, createChannelPluginBase |
plugin-sdk/setup | 共享 setup 向导 helper | Setup 翻译器、allowlist 提示、setup status 构建器 |
plugin-sdk/setup-runtime | Setup 时 runtime helper | createSetupTranslator, 导入安全的 setup patch 适配器, lookup-note helper, promptResolvedAllowFrom, splitSetupEntries, 委派 setup 代理 |
plugin-sdk/setup-adapter-runtime | 废弃的 setup 适配器别名 | 改用 plugin-sdk/setup-runtime |
plugin-sdk/setup-tools | Setup 工具 helper | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
plugin-sdk/account-core | 多账号 helper | 账号列表/配置/动作门控 helper |
plugin-sdk/account-id | 账号 ID helper | DEFAULT_ACCOUNT_ID, 账号 ID 规范化 |
plugin-sdk/account-resolution | 账号查找 helper | 账号查找 + 默认回退 helper |
plugin-sdk/account-helpers | 窄账号 helper | 账号列表/账号动作 helper |
plugin-sdk/channel-setup | Setup 向导适配器 | createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, 以及 DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled, splitSetupEntries |
plugin-sdk/channel-pairing | DM 配对原语 | createChannelPairingController |
plugin-sdk/channel-reply-pipeline | 回复前缀、输入和源投递接线 | createChannelReplyPipeline, resolveChannelSourceReplyDeliveryMode |
plugin-sdk/channel-config-helpers | 配置适配器工厂和 DM 访问 helper | createHybridChannelConfigAdapter, resolveChannelDmAccess, resolveChannelDmAllowFrom, resolveChannelDmPolicy, normalizeChannelDmPolicy, normalizeLegacyDmAliases |
plugin-sdk/channel-config-schema | 配置 schema 构建器 | 共享渠道 config schema 原语和通用构建器 |
plugin-sdk/bundled-channel-config-schema | 捆绑配置 schema | OpenClaw 维护的捆绑插件专用；新插件必须定义插件本地 schema |
plugin-sdk/channel-config-schema-legacy | 废弃的捆绑配置 schema | 兼容别名；维护的捆绑插件使用 plugin-sdk/bundled-channel-config-schema |
plugin-sdk/telegram-command-config | Telegram 命令配置 helper | 命令名规范化、描述修剪、重复/冲突验证 |
plugin-sdk/channel-policy | 群组/DM 策略解析 | resolveChannelGroupRequireMention |
plugin-sdk/channel-lifecycle | 账号状态和草稿流生命周期 helper | createAccountStatusSink, 草稿预览完成 helper |
plugin-sdk/inbound-envelope | 入站信封 helper | 共享路由 + 信封构建 helper |
plugin-sdk/inbound-reply-dispatch | 入站回复 helper | 共享记录并调度 helper |
plugin-sdk/messaging-targets | 消息目标解析 | 目标解析/匹配 helper |
plugin-sdk/outbound-media | 出站媒体 helper | 共享出站媒体加载 |
plugin-sdk/outbound-send-deps | 出站发送依赖 helper | 轻量级 resolveOutboundSendDep 查找而不导入完整出站 runtime |
plugin-sdk/outbound-runtime | 出站 runtime helper | 出站投递、身份/发送委托、会话、格式化和载荷规划 helper |
plugin-sdk/thread-bindings-runtime | 线程绑定 helper | 线程绑定生命周期和适配器 helper |
plugin-sdk/agent-media-payload | 遗留媒体载荷 helper | 用于遗留字段布局的智能体媒体载荷构建器 |
plugin-sdk/channel-runtime | 废弃的兼容性垫片 | 遗留渠道 runtime 工具 |
plugin-sdk/channel-send-result | 发送结果类型 | 回复结果类型 |
plugin-sdk/runtime-store | 持久化插件存储 | createPluginRuntimeStore |
plugin-sdk/runtime | 宽泛 runtime helper | Runtime/日志/备份/插件安装 helper |
plugin-sdk/runtime-env | 窄 runtime 环境 helper | 日志器/runtime 环境、超时、重试和回退 helper |
plugin-sdk/plugin-runtime | 共享插件 runtime helper | 插件命令/钩子/HTTP/交互 helper |
plugin-sdk/hook-runtime | 钩子管道 helper | 共享 webhook/内部钩子管道 helper |
plugin-sdk/lazy-runtime | 惰性 runtime helper | createLazyRuntimeModule, createLazyRuntimeMethod, createLazyRuntimeMethodBinder, createLazyRuntimeNamedExport, createLazyRuntimeSurface |
plugin-sdk/process-runtime | 进程 helper | 共享 exec helper |
plugin-sdk/cli-runtime | CLI runtime helper | 命令格式化、等待、版本 helper |
plugin-sdk/gateway-runtime | Gateway helper | Gateway 客户端、事件循环就绪启动 helper 和渠道状态补丁 helper |
plugin-sdk/config-runtime | 废弃的配置兼容性垫片 | 优先使用 config-contracts, plugin-config-runtime, runtime-config-snapshot, 和 config-mutation |
plugin-sdk/telegram-command-config | Telegram 命令 helper | 当捆绑 Telegram 合约 surface 不可用时，使用回退稳定的 Telegram 命令验证 helper |
plugin-sdk/approval-runtime | 审批提示 helper | Exec/插件审批载荷、审批能力/配置文件 helper、原生审批路由/runtime helper 和结构化审批显示路径格式化 |
plugin-sdk/approval-auth-runtime | 审批认证 helper | 审批人解析、同聊天动作认证 |
plugin-sdk/approval-client-runtime | 审批客户端 helper | 原生 exec 审批配置文件/过滤器 helper |
plugin-sdk/approval-delivery-runtime | 审批投递 helper | 原生审批能力/投递适配器 |
plugin-sdk/approval-gateway-runtime | 审批 gateway helper | 共享审批 gateway 解析 helper |
plugin-sdk/approval-handler-adapter-runtime | 审批适配器 helper | 轻量级原生审批适配器加载 helper，用于热渠道入口点 |
plugin-sdk/approval-handler-runtime | 审批 handler helper | 更广泛的审批 handler runtime helper；当够用时优先使用更窄的适配器/gateway 接缝 |
plugin-sdk/approval-native-runtime | 审批目标 helper | 原生审批目标/账号绑定 helper |
plugin-sdk/approval-reply-runtime | 审批回复 helper | Exec/插件审批回复载荷 helper |
plugin-sdk/channel-runtime-context | 渠道 runtime-context helper | 通用渠道 runtime-context 注册/获取/观察 helper |
plugin-sdk/security-runtime | 安全 helper | 共享信任、DM 门控、根绑定文件/路径 helper、外部内容和密钥收集 helper |
plugin-sdk/ssrf-policy | SSRF 策略 helper | 主机允许列表和私有网络策略 helper |
plugin-sdk/ssrf-runtime | SSRF runtime helper | 固定分发器、受保护 fetch、SSRF 策略 helper |
plugin-sdk/system-event-runtime | 系统事件 helper | enqueueSystemEvent, peekSystemEventEntries |
plugin-sdk/heartbeat-runtime | 心跳 helper | 心跳唤醒、事件和可见性 helper |
plugin-sdk/delivery-queue-runtime | 投递队列 helper | drainPendingDeliveries |
plugin-sdk/channel-activity-runtime | 渠道活动 helper | recordChannelActivity |
plugin-sdk/dedupe-runtime | 去重 helper | 内存去重缓存 |
plugin-sdk/file-access-runtime | 文件访问 helper | 安全本地文件/媒体路径 helper |
plugin-sdk/transport-ready-runtime | 传输就绪 helper | waitForTransportReady |
plugin-sdk/collection-runtime | 有界缓存 helper | pruneMapToMaxSize |
plugin-sdk/diagnostic-runtime | 诊断门控 helper | isDiagnosticFlagEnabled, isDiagnosticsEnabled |
plugin-sdk/error-runtime | 错误格式化 helper | formatUncaughtError, isApprovalNotFoundError, 错误图 helper |
plugin-sdk/fetch-runtime | 包装 fetch/代理 helper | resolveFetch, 代理 helper, EnvHttpProxyAgent 选项 helper |
plugin-sdk/host-runtime | 主机规范化 helper | normalizeHostname, normalizeScpRemoteHost |
plugin-sdk/retry-runtime | 重试 helper | RetryConfig, retryAsync, 策略运行器 |
plugin-sdk/allow-from | 允许列表格式化 | formatAllowFromLowercase |
plugin-sdk/allowlist-resolution | 允许列表输入映射 | mapAllowlistResolutionInputs |
plugin-sdk/command-auth | 命令门控和命令 surface helper | resolveControlCommandGate, 发送者授权 helper, 命令注册 helper 包括动态参数菜单格式化 |
plugin-sdk/command-status | 命令状态/帮助渲染器 | buildCommandsMessage, buildCommandsMessagePaginated, buildHelpMessage |
plugin-sdk/secret-input | 秘密输入解析 | 秘密输入 helper |
plugin-sdk/webhook-ingress | Webhook 请求 helper | Webhook 目标工具 |
plugin-sdk/webhook-request-guards | Webhook body 守卫 helper | 请求体读取/限制 helper |
plugin-sdk/reply-runtime | 共享回复 runtime | 入站调度、心跳、回复规划器、分块 |
plugin-sdk/reply-dispatch-runtime | 窄回复调度 helper | 完成、provider 调度和会话标签 helper |
plugin-sdk/reply-history | 回复历史 helper | createChannelHistoryWindow; 废弃的 map-helper 兼容导出如 buildPendingHistoryContextFromMap, recordPendingHistoryEntry, 和 clearHistoryEntriesIfEnabled |
plugin-sdk/reply-reference | 回复引用规划 | createReplyReferencePlanner |
plugin-sdk/reply-chunking | 回复分块 helper | 文本/markdown 分块 helper |
plugin-sdk/session-store-runtime | 会话存储 helper | 存储路径 + 更新时间 helper |
plugin-sdk/state-paths | 状态路径 helper | 状态和 OAuth 目录 helper |
plugin-sdk/routing | 路由/会话键 helper | resolveAgentRoute, buildAgentSessionKey, resolveDefaultAgentBoundAccountId, 会话键规范化 helper |
plugin-sdk/status-helpers | 渠道状态 helper | 渠道/账号状态摘要构建器、runtime 状态默认值、问题元数据 helper |
plugin-sdk/target-resolver-runtime | 目标解析 helper | 共享目标解析 helper |
plugin-sdk/string-normalization-runtime | 字符串规范化 helper | Slug/字符串规范化 helper |
plugin-sdk/request-url | 请求 URL helper | 从请求类输入中提取字符串 URL |
plugin-sdk/run-command | 定时命令 helper | 带规范化 stdout/stderr 的定时命令运行器 |
plugin-sdk/param-readers | 参数读取器 | 常见工具/CLI 参数读取器 |
plugin-sdk/tool-payload | 工具载荷提取 | 从工具结果对象中提取规范载荷 |
plugin-sdk/tool-send | 工具发送提取 | 从工具参数中提取规范发送目标字段 |
plugin-sdk/temp-path | 临时路径 helper | 共享临时下载路径 helper |
plugin-sdk/logging-core | 日志 helper | 子系统日志器和脱敏 helper |
plugin-sdk/markdown-table-runtime | Markdown 表格 helper | Markdown 表格模式 helper |
plugin-sdk/reply-payload | 消息回复类型 | 回复载荷类型 |
plugin-sdk/provider-setup | 精选本地/自托管 Provider 设置 helper | 自托管 Provider 发现/配置 helper |
plugin-sdk/self-hosted-provider-setup | 聚焦 OpenAI 兼容自托管 Provider 设置 helper | 相同的自托管 Provider 发现/配置 helper |
plugin-sdk/provider-auth-runtime | Provider runtime 认证 helper | Runtime API 密钥解析 helper |
plugin-sdk/provider-auth-api-key | Provider API 密钥设置 helper | API 密钥入门/配置文件写入 helper |
plugin-sdk/provider-auth-result | Provider 认证结果 helper | 标准 OAuth 认证结果构建器 |
plugin-sdk/provider-selection-runtime | Provider 选择 helper | 已配置或自动 Provider 选择和原始 Provider 配置合并 |
plugin-sdk/provider-env-vars | Provider 环境变量 helper | Provider 认证环境变量查找 helper |
plugin-sdk/provider-model-shared | 共享 Provider 模型/回放 helper | ProviderReplayFamily, buildProviderReplayFamilyHooks, normalizeModelCompat, 共享回放策略构建器、Provider 端点 helper 和模型 ID 规范化 helper |
plugin-sdk/provider-catalog-shared | 共享 Provider 目录 helper | findCatalogTemplate, buildSingleProviderApiKeyCatalog, buildManifestModelProviderConfig, supportsNativeStreamingUsageCompat, applyProviderNativeStreamingUsageCompat |
plugin-sdk/provider-onboard | Provider 入门补丁 | 入门配置 helper |
plugin-sdk/provider-http | Provider HTTP helper | 通用 Provider HTTP/端点能力 helper，包括音频转录 multipart form helper |
plugin-sdk/provider-web-fetch | Provider web-fetch helper | Web-fetch Provider 注册/缓存 helper |
plugin-sdk/provider-web-search-config-contract | Provider web-search 配置 helper | 窄 web-search 配置/凭据 helper，用于不需要插件启用接线的 Provider |
plugin-sdk/provider-web-search-contract | Provider web-search 合约 helper | 窄 web-search 配置/凭据合约 helper，如 createWebSearchProviderContractFields, enablePluginInConfig, resolveProviderWebSearchPluginConfig, 和作用域凭据设置器/获取器 |
plugin-sdk/provider-web-search | Provider web-search helper | Web-search Provider 注册/缓存/runtime helper |
plugin-sdk/provider-tools | Provider 工具/schema 兼容 helper | ProviderToolCompatFamily, buildProviderToolCompatFamilyHooks, 和 DeepSeek/Gemini/OpenAI schema 清理+诊断 |
plugin-sdk/provider-usage | Provider 用量 helper | fetchClaudeUsage, fetchGeminiUsage, fetchGithubCopilotUsage, 和其他 Provider 用量 helper |
plugin-sdk/provider-stream | Provider 流式传输 helper | ProviderStreamFamily, buildProviderStreamFamilyHooks, composeProviderStreamWrappers, 流包装器类型, 和共享 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器 helper |
plugin-sdk/provider-transport-runtime | Provider 传输 helper | 原生 Provider 传输 helper，如受保护 fetch、传输消息转换和可写传输事件流 |
plugin-sdk/keyed-async-queue | 有序异步队列 | KeyedAsyncQueue |
plugin-sdk/media-runtime | 共享媒体 helper | 媒体 fetch/transform/store helper, ffprobe 支持视频尺寸探测和媒体载荷构建器 |
plugin-sdk/media-generation-runtime | 共享媒体生成 helper | 共享故障切换 helper、候选选择和缺失模型消息用于图像/视频/音乐生成 |
plugin-sdk/media-understanding | 媒体理解 helper | 媒体理解 Provider 类型加上 Provider 面向图像/音频 helper 导出 |
plugin-sdk/text-runtime | 废弃的宽泛文本兼容导出 | 使用 string-coerce-runtime, text-chunking, text-utility-runtime, 和 logging-core |
plugin-sdk/text-chunking | 文本分块 helper | 出站文本分块 helper |
plugin-sdk/speech | 语音 helper | 语音 Provider 类型加上 Provider 面向指令、注册、验证 helper 和 OpenAI 兼容 TTS 构建器 |
plugin-sdk/speech-core | 共享语音核心 | 语音 Provider 类型、注册、指令、规范化 |
plugin-sdk/realtime-transcription | 实时转录 helper | Provider 类型、注册 helper 和共享 WebSocket 会话 helper |
plugin-sdk/realtime-voice | 实时语音 helper | Provider 类型、注册/解析 helper、桥接会话 helper、共享 agent talk-back 队列、转录/事件健康、回声抑制和快速上下文咨询 helper |
plugin-sdk/image-generation | 图像生成 helper | 图像生成 Provider 类型加上图像 asset/data URL helper 和 OpenAI 兼容图像 Provider 构建器 |
plugin-sdk/image-generation-core | 共享图像生成核心 | 图像生成类型、故障切换、认证和注册 helper |
plugin-sdk/music-generation | 音乐生成 helper | 音乐生成 Provider/请求/结果类型 |
plugin-sdk/music-generation-core | 共享音乐生成核心 | 音乐生成类型、故障切换 helper、Provider 查找和模型参考解析 |
plugin-sdk/video-generation | 视频生成 helper | 视频生成 Provider/请求/结果类型 |
plugin-sdk/video-generation-core | 共享视频生成核心 | 视频生成类型、故障切换 helper、Provider 查找和模型参考解析 |
plugin-sdk/interactive-runtime | 交互回复 helper | 交互回复载荷规范化/减少 |
plugin-sdk/channel-config-primitives | 渠道配置原语 | 窄渠道配置 schema 原语 |
plugin-sdk/channel-config-writes | 渠道配置写入 helper | 渠道配置写入认证 helper |
plugin-sdk/channel-plugin-common | 共享渠道序言 | 共享渠道插件序言导出 |
plugin-sdk/channel-status | 渠道状态 helper | 共享渠道状态快照/摘要 helper |
plugin-sdk/allowlist-config-edit | 允许列表配置 helper | 允许列表配置编辑/读取 helper |
plugin-sdk/group-access | 组访问 helper | 共享组访问决策 helper |
plugin-sdk/direct-dm | 直接 DM helper | 共享直接 DM 认证/守卫 helper |
plugin-sdk/extension-shared | 共享扩展 helper | 被动渠道/状态和环境代理 helper 原语 |
plugin-sdk/webhook-targets | Webhook 目标 helper | Webhook 目标注册和路由安装 helper |
plugin-sdk/webhook-path | 废弃的 webhook 路径别名 | 使用 plugin-sdk/webhook-ingress |
plugin-sdk/web-media | 共享 web 媒体 helper | 远程/本地媒体加载 helper |
plugin-sdk/zod | 废弃的 Zod 兼容重新导出 | 直接从 zod 导入 zod |
plugin-sdk/memory-core | 捆绑 memory-core helper | 内存管理器/配置/文件/CLI helper 表面 |
plugin-sdk/memory-core-engine-runtime | 内存引擎 runtime 外观 | 内存索引/搜索 runtime 外观 |
plugin-sdk/memory-core-host-engine-foundation | 内存宿主基础引擎 | 内存宿主基础引擎导出 |
plugin-sdk/memory-core-host-engine-embeddings | 内存宿主嵌入引擎 | 内存嵌入合约、注册表访问、本地 Provider 和通用批量/远程 helper；具体远程 Provider 在其所属插件中 |
plugin-sdk/memory-core-host-engine-qmd | 内存宿主 QMD 引擎 | 内存宿主 QMD 引擎导出 |
plugin-sdk/memory-core-host-engine-storage | 内存宿主存储引擎 | 内存宿主存储引擎导出 |
plugin-sdk/memory-core-host-multimodal | 内存宿主多模态 helper | 内存宿主多模态 helper |
plugin-sdk/memory-core-host-query | 内存宿主查询 helper | 内存宿主查询 helper |
plugin-sdk/memory-core-host-secret | 内存宿主秘密 helper | 内存宿主秘密 helper |
plugin-sdk/memory-core-host-events | 废弃的内存事件别名 | 使用 plugin-sdk/memory-host-events |
plugin-sdk/memory-core-host-status | 内存宿主状态 helper | 内存宿主状态 helper |
plugin-sdk/memory-core-host-runtime-cli | 内存宿主 CLI runtime | 内存宿主 CLI runtime helper |
plugin-sdk/memory-core-host-runtime-core | 内存宿主核心 runtime | 内存宿主核心 runtime helper |
plugin-sdk/memory-core-host-runtime-files | 内存宿主文件/runtime helper | 内存宿主文件/runtime helper |
plugin-sdk/memory-host-core | 内存宿主核心 runtime 别名 | 供应商中立的内存宿主核心 runtime helper 别名 |
plugin-sdk/memory-host-events | 内存宿主事件日志别名 | 供应商中立的内存宿主事件日志 helper 别名 |
plugin-sdk/memory-host-files | 废弃的内存文件/runtime 别名 | 使用 plugin-sdk/memory-core-host-runtime-files |
plugin-sdk/memory-host-markdown | 托管 Markdown helper | 内存相邻插件的共享托管 Markdown helper |
plugin-sdk/memory-host-search | 活跃内存搜索外观 | 惰性活跃内存搜索管理器 runtime 外观 |
plugin-sdk/memory-host-status | 废弃的内存宿主状态别名 | 使用 plugin-sdk/memory-core-host-status |
plugin-sdk/testing | 测试工具 | 仓库本地废弃兼容 barrel；使用聚焦仓库本地测试子路径如 plugin-sdk/plugin-test-runtime, plugin-sdk/channel-test-helpers, plugin-sdk/channel-target-testing, plugin-sdk/test-env, 和 plugin-sdk/test-fixtures |
此表是常见迁移子集，非完整 SDK surface。编译器入口点清单位于 scripts/lib/plugin-sdk-entrypoints.json；包导出从公开子集生成。
捆绑插件专用的保留 helper 接缝已从公开 SDK 导出映射中退役，除了显式记录的兼容外观，如为已发布的 @openclaw/discord@2026.3.13 包保留的废弃 plugin-sdk/discord 垫片。所有者专属 helper 位于所属插件包内；共享宿主行为应通过通用 SDK 合约移动，如 plugin-sdk/gateway-runtime, plugin-sdk/security-runtime, 和 plugin-sdk/plugin-config-runtime。
使用匹配任务的最窄导入。如果找不到导出，检查 src/plugin-sdk/ 的源或询问维护者哪个通用合约应该拥有它。
活跃废弃项
以下废弃项适用于插件 SDK、Provider 合约、runtime 表面和清单。每一项今天仍工作，但将在未来主版本中移除。每一项下方的条目将旧 API 映射到其规范替换。
command-auth 帮助构建器 → command-status
**旧 (`openclaw/plugin-sdk/command-auth`)**: `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage`.
**新 (`openclaw/plugin-sdk/command-status`)**: 相同签名，相同导出——只是从更窄的子路径导入。`command-auth` 将它们作为兼容桩重新导出。
```typescript
// 迁移前
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";
// 迁移后
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";
```
Mention 门控 helper → resolveInboundMentionDecision
**旧**: `resolveInboundMentionRequirement({ facts, policy })` 和 `shouldDropInboundForMention(...)` 来自 `openclaw/plugin-sdk/channel-inbound` 或 `openclaw/plugin-sdk/channel-mention-gating`.
**新**: `resolveInboundMentionDecision({ facts, policy })`——返回单个决策对象而非两个拆分调用。
下游渠道插件（Slack, Discord, Matrix, MS Teams）已切换。
渠道 runtime 垫片和渠道动作 helper
`openclaw/plugin-sdk/channel-runtime` 是旧渠道插件的兼容垫片。新代码不要导入，使用 `openclaw/plugin-sdk/channel-runtime-context` 注册 runtime 对象。
`channelActions*` helper 在 `openclaw/plugin-sdk/channel-actions` 中与原始“动作”渠道导出一起废弃。通过语义化的 `presentation` 表面暴露能力——渠道插件声明它们渲染什么（卡片、按钮、选择器），而不是它们接受哪些原始动作名称。
Web 搜索 Provider tool() helper → createTool() 在插件上
**旧**: `tool()` 工厂来自 `openclaw/plugin-sdk/provider-web-search`.
**新**: 直接在 Provider 插件上实现 `createTool(...)`。OpenClaw 不再需要 SDK helper 注册工具包装器。
纯文本渠道信封 → BodyForAgent
**旧**: `formatInboundEnvelope(...)` (和 `ChannelMessageForAgent.channelEnvelope`) 从入站渠道消息构建平面纯文本提示信封。
**新**: `BodyForAgent` 加上结构化用户上下文块。渠道插件将路由元数据（线程、主题、回复、反应）作为类型化字段附加，而不是将它们拼接成提示字符串。`formatAgentEnvelope(...)` helper 仍受支持用于合成的助手面向信封，但入站纯文本信封正在淘汰。
受影响区域：`inbound_claim`, `message_received`, 以及任何自定义渠道插件中后处理了 `channelEnvelope` 文本的。
deactivate 钩子 → gateway_stop
**旧**: `api.on("deactivate", handler)`.
**新**: `api.on("gateway_stop", handler)`。事件和上下文是相同的关闭清理合约；仅钩子名更改。
```typescript
// 迁移前
api.on("deactivate", async (event, ctx) => {
await stopPluginService(ctx);
});
// 迁移后
api.on("gateway_stop", async (event, ctx) => {
await stopPluginService(ctx);
});
```
`deactivate` 作为废弃兼容性别名保留到 2026-08-16 之后。
Provider 发现类型 → Provider 目录类型
四个发现类型别名现在是目录时代类型的薄包装：
| 旧别名 | 新类型 |
| --- | --- |
| `ProviderDiscoveryOrder` | `ProviderCatalogOrder` |
| `ProviderDiscoveryContext` | `ProviderCatalogContext` |
| `ProviderDiscoveryResult` | `ProviderCatalogResult` |
| `ProviderPluginDiscovery` | `ProviderPluginCatalog` |
加上遗留 `ProviderCapabilities` 静态包——Provider 插件应使用显式 Provider 钩子如 `buildReplayPolicy`, `normalizeToolSchemas`, 和 `wrapStreamFn` 而非静态对象。
Thinking 策略钩子 → resolveThinkingProfile
**旧**（`ProviderThinkingPolicy` 上的三个独立钩子）: `isBinaryThinking(ctx)`, `supportsXHighThinking(ctx)`, 和 `resolveDefaultThinkingLevel(ctx)`.
**新**: 单个 `resolveThinkingProfile(ctx)` 返回包含规范 `id`、可选 `label` 和排序级别列表的 `ProviderThinkingProfile`。OpenClaw 按配置文件排名自动降级过时存储的值。
实现一个钩子而不是三个。遗留钩子在废弃窗口期内继续工作，但不与配置文件结果组合。
外部 OAuth Provider 回退 → contracts.externalAuthProviders
**旧**: 实现 `resolveExternalOAuthProfiles(...)` 而不在插件清单中声明 Provider.
**新**: 在插件清单中声明 `contracts.externalAuthProviders` **并**实现 `resolveExternalAuthProfiles(...)`。旧的“认证回退”路径在运行时发出警告，并将被移除。
```json
{
"contracts": {
"externalAuthProviders": ["anthropic", "openai"]
}
}
```
Provider 环境变量查找 → setup.providers[].envVars
**旧** 清单字段: `providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`.
**新**: 将相同的环境变量查找镜像到清单的 `setup.providers[].envVars`。这将在 setup/status 环境元数据集中在一处，避免仅为了回答环境变量查找而启动插件 runtime。
`providerAuthEnvVars` 通过兼容适配器保持支持，直到废弃窗口关闭。
内存插件注册 → registerMemoryCapability
**旧**: 三个独立调用 - `api.registerMemoryPromptSection(...)`, `api.registerMemoryFlushPlan(...)`, `api.registerMemoryRuntime(...)`.
**新**: 在内存状态 API 上调用一个 `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`.
相同插槽，单一注册调用。附加内存 helper（`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`, `registerMemoryEmbeddingProvider`）不受影响。
子 agent 会话消息类型重命名
两个遗留类型别名仍从 `src/plugins/runtime/types.ts` 导出：
| 旧 | 新 |
| --- | --- |
| `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` |
| `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` |
runtime 方法 `readSession` 废弃，改用 `getSessionMessages`。相同签名；旧方法调用新方法。
runtime.tasks.flow → runtime.tasks.managedFlows
**旧**: `runtime.tasks.flow` (单数) 返回实时 task-flow 访问器。
**新**: `runtime.tasks.managedFlows` 为在 flow 中创建、更新、取消或运行子任务的插件保留托管 TaskFlow 突变 runtime。如果插件只需要基于 DTO 的读取，使用 `runtime.tasks.flows`。
```typescript
// 迁移前
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// 迁移后
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);
```
嵌入式扩展工厂 → agent tool-result 中间件
已在“迁移步骤 → 迁移 Pi tool-result 扩展为中间件”中覆盖。此处包含以保持完整性：已移除的 Pi 专用 `api.registerEmbeddedExtensionFactory(...)` 路径被替换为 `api.registerAgentToolResultMiddleware(...)` 并在 `contracts.agentToolResultMiddleware` 中显式列出 runtime。
OpenClawSchemaType 别名 → OpenClawConfig
`openclaw/plugin-sdk` 重新导出的 `OpenClawSchemaType` 现在是一行 `OpenClawConfig` 的别名。优先使用规范名称。
```typescript
// 迁移前
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// 迁移后
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";
```
INFO
扩展级别的废弃（位于 extensions/ 下的捆绑渠道/Provider 插件内部）在其自己的 api.ts 和 runtime-api.ts barrel 中跟踪。它们不影响第三方插件合约，不在此列出。如果你直接使用捆绑插件的本地 barrel，在升级前阅读该 barrel 中的废弃注释。
移除时间表
| 时间 | 内容 |
|---|---|
| 现在 | 废弃 surface 在 runtime 产生警告 |
| 下一个主版本 | 废弃 surface 被移除，仍使用它们的插件将失效 |
所有 core 插件已完成迁移。外部插件应在下一个主版本前完成迁移。
临时抑制警告
迁移过程中，可以通过以下环境变量临时抑制警告：
bash
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run这只是临时逃生通道，不是永久解决方案。
相关文档
- 插件开发入门 — 构建你的第一个插件
- SDK 概览 — 完整子路径导入参考
- 渠道插件开发 — 构建渠道插件
- Provider 插件开发 — 构建 Provider 插件
- 插件内部架构 — 架构深度解析
- 插件清单 — 清单 schema 参考
常见问题
Q: 我的插件用了 plugin-sdk/compat，现在 gateway 每次启动都打警告，怎么快速定位所有用法？
A: 运行 grep -r "plugin-sdk/compat" my-plugin/ 以及 grep -r "extension-api" my-plugin/，然后对照本页的导入路径表逐一替换。通常一个 import 语句拆分成 2-3 个聚焦导入即可。迁移期间可以用 OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 抑制警告。
Q: plugin-sdk/infra-runtime 和 plugin-sdk/config-runtime 还能用吗？迁移后必须全部替换吗？
A: 这两个 barrel 仍为外部插件兼容性保留，但新代码不应使用。如果插件只用了其中一两个 helper，直接替换成对应的窄子路径即可（如 system-event-runtime、plugin-config-runtime）。捆绑插件受扫描守卫限制，不允许使用宽泛 barrel。下个主版本会移除这些 barrel，建议尽早迁移。
Q: 迁移后如何确认已完全移除旧接口的使用？
A: 运行 openclaw gateway run 不再看到 OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED 或 OPENCLAW_EXTENSION_API_DEPRECATED 警告，即代表迁移完成。也可以在测试套件中加断言检查无旧导入路径。