插件 SDK 迁移

OpenClaw 已将宽泛的向后兼容层替换为由小型、聚焦导入构成的现代插件 架构。如果你的插件早于这一变更，本指南可帮助它迁移到当前契约。

变更内容

过去，多个完全开放的导入表面允许插件从单一入口点访问几乎所有内容：

• openclaw/plugin-sdk 和 openclaw/plugin-sdk/compat - 在构建聚焦式 SDK 期间重新导出了数十个辅助程序。现在这两个根入口均已移除；请改为导入有文档说明的子路径。
• openclaw/plugin-sdk/infra-runtime - 一个宽泛的桶式导出，混合了系统 事件、Heartbeat 状态、投递队列、fetch/代理辅助程序、文件辅助程序、 审批类型和不相关的实用程序。
• openclaw/plugin-sdk/config-runtime - 一个宽泛的配置桶式导出，仅为其 后续兼容窗口而保留；直接运行时加载/写入辅助程序已移除。
• openclaw/extension-api - 一个已移除的桥接层，曾允许插件直接 访问主机端辅助程序，例如嵌入式智能体运行器。
• api.registerEmbeddedExtensionFactory(...) - 一个已移除的、仅供嵌入式运行器使用的 钩子，曾观察 tool_result 等嵌入式运行器事件。请改用智能体 工具结果中间件（参阅将嵌入式工具结果扩展迁移到 中间件）。

根 SDK、兼容桶式导出、扩展桥接层和嵌入式扩展工厂 均已移除。infra-runtime 和 config-runtime 仅在各自单独记录的 后续窗口中保留；新插件应使用聚焦式子路径。

OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已有文档说明的 插件行为。破坏性契约变更会先经过兼容适配器、诊断、文档和弃用窗口。 这适用于 SDK 导入、清单字段、设置 API、钩子和运行时 注册行为。

原因

• 启动缓慢 - 导入一个辅助程序会加载数十个不相关的模块。
• 循环依赖 - 宽泛的重新导出很容易产生导入循环。
• API 表面不明确 - 无法区分稳定导出与内部导出。

现在，每个 openclaw/plugin-sdk/<subpath> 都是一个小型、自包含且 具有明确文档契约的模块。

面向内置渠道的旧提供商便捷接口也已移除 - 以渠道命名的辅助程序快捷方式只是私有单体仓库中的便利设施，并非 稳定的插件契约。请改用精简的通用 SDK 子路径。在 内置插件工作区内，将提供商拥有的辅助程序保留在该插件自身的 api.ts 或 runtime-api.ts 中：

• Anthropic 将 Claude 专用的流式辅助程序保留在自身的 api.ts / contract-api.ts 接口中。
• OpenAI 将提供商构建器、默认模型辅助程序和实时提供商 构建器保留在自身的 api.ts 中。
• OpenRouter 将提供商构建器及新手引导/配置辅助程序保留在自身的 api.ts 中。

兼容策略

外部插件兼容性工作遵循以下顺序：

1. 添加新契约。
2. 通过兼容适配器继续接入旧行为。
3. 发出诊断或警告，指出旧路径和替代路径。
4. 在测试中覆盖两条路径。
5. 记录弃用和迁移路径。
6. 仅在公布的迁移窗口结束后移除，通常是在一个主 版本中。

如果某个清单字段仍被接受，请继续使用它，直到文档和 诊断另有说明。新代码应优先采用有文档说明的替代方案； 现有插件不应在普通次版本发布期间中断。

已发布渠道设置兼容性

通过 2026.7.1 发布的 Slack、Discord、Signal 和 Microsoft Teams 软件包会从 openclaw/plugin-sdk/bundled-channel-config-schema 导入 渠道专用配置架构。已发布的 Slack 和 Discord 软件包还会从 openclaw/plugin-sdk/setup-runtime 导入 createLegacyCompatChannelDmPolicy 和 promptLegacyChannelAllowFromForAccount。

这些导出仍作为已弃用的运行时兼容适配器提供。 新插件和重新发布的插件应在本地拥有自身的配置架构和设置策略， 并使用 channel-config-schema 和 setup-runtime 中的通用原语。只有在最低支持的已发布软件包版本 不再导入这些兼容导出后，才能将其移除。

渠道设置输入字段兼容性

ChannelSetupInput 现在仅永久保留跨渠道设置封装的类型定义。 渠道专用字段仍在已弃用的兼容层级中保留类型定义， 以便现有外部插件在插件作者将这些字段迁移到插件本地设置输入类型期间 仍可编译。

OpenClaw 不发布主版本。2026-07-22 的注册表扫描检查了 426 个已发布的树外渠道插件，并移除了 21 个没有读取方的字段。 保留的 22 个字段各自都有已知的已发布读取方。只要某个字段不再被 任何已发布插件读取，就会立即将其删除；随着插件作者迁移到插件本地 设置输入类型，保留集合会不断缩小。

同一次扫描还移除了 23 个没有已发布依赖方的旧版未声明适配器提升键。 仍保留六个常用键以及仅用于设置的 rooms 键。 随着已发布插件声明 singleAccountKeysToMove，该集合也会不断缩小。

共享类型没有索引签名。插件拥有的键仍可存在于 运行时输入对象上；请在插件本地交叉类型中声明它们，或通过 所属插件的设置架构收窄其类型。

旧版未声明适配器提升层级遵循相同的读取方驱动 策略。请声明 singleAccountKeysToMove；当插件不需要额外提升键时，也应包含空数组， 以便逐个键停用共享回退机制。

验证读取方

1. 使用每个 nextCursor 对 https://clawhub.ai/api/v1/packages?family=code-plugin&limit=100 进行分页查询，并保留其 categories 包含 channels 的软件包。
2. 添加来自 npm search --json --searchlimit=1000 "openclaw channel plugin" 的 npm 候选项。通过在 GitHub 中搜索 openclaw/plugin-sdk/channel-setup、openclaw/plugin-sdk/setup 和 openclaw/plugin-sdk/core 的代码，添加仅有源代码的候选项。
3. 解析每个候选项的最新已发布版本。运行 npm pack <package>@<version> --json --pack-destination <temp-dir>，将其解包，并检查已发布的 dist JavaScript 和声明中是否存在直接或解构字段读取。如果软件包没有 npm 版本，请下载 ClawHub 工件。
4. 记录软件包、版本、字段或提升键以及匹配文件。只有在没有任何已发布插件工件读取某个字段或键时，才能删除它。确保保留字段和键列表旁代码注释中的读取方名称与扫描结果保持同步。

这只是源代码/类型兼容性记录。它没有运行时适配器或 兼容性注册表条目，因为运行时设置输入对象和设置 行为均未改变。

使用 pnpm plugins:boundary-report 审计当前迁移队列：

pnpm plugins:boundary-report:ci 会启用全部三个失败标志。已弃用的 记录通常会设置明确的 removeAfter 日期，而不是含糊的“下一个 主版本”。如果记录的所有者尚未批准日期，则不设置 removeAfter，该记录会显示为 no-date，并且永远不符合移除条件。 报告按日期对已弃用记录进行分组，统计本地代码/文档引用， 显示跨所有者的保留 SDK 导入，并汇总私有 内存主机 SDK 桥接层。保留的 SDK 子路径必须有可追踪的所有者使用记录； 未使用的保留导出应从公共 SDK 中移除。

旧版媒体投影

media-legacy-projection 兼容性记录涵盖旧的并行 媒体字段、有效负载构建器、钩子元数据别名和媒体模板 名称。其批准的 removeAfter 日期为 2026-10-01（在事实优先的 替代方案发布两个发布周期之后）。届时还必须完成一次无异常的已发布插件 工件扫描才能移除；请在该日期前完成迁移。

对于渠道入口，请将单数/复数形式的 MediaPath、MediaUrl、 MediaType、MediaPaths、MediaUrls、MediaTypes、 MediaTranscribedIndexes、MediaWorkspaceDir 和 MediaStaged 替换为有序 事实：

 const media = toInboundMediaFacts([  { path: saved.path, url: nativeUrl, contentType: saved.contentType, messageId },]); const ctx = finalizeInboundContext({ Body: caption, media });

在 inbound_claim 和 message_received 钩子中使用 event.media。如果远程 媒体尚未在本地暂存，请使用 event.originalMedia 进行身份标识/诊断， 并等待 event.media；event.mediaStagingPending 可区分该 状态。不要从 event.metadata 读取已弃用的单数/复数属性。

对于 CLI 媒体模型，请将 {{MediaPath}}、{{MediaUrl}}、{{MediaType}} 和 {{MediaDir}} 替换为 {{AttachmentPath}}、{{AttachmentUrl}}、 {{AttachmentContentType}} 和 {{AttachmentDir}}。当附件位置很重要时，请使用 {{AttachmentIndex}}。

对于本地媒体读取策略，请从 openclaw/plugin-sdk/media-local-roots 导入 getAgentScopedMediaLocalRoots(...) 或 getAgentScopedMediaLocalRootsForSources(...)。 openclaw/plugin-sdk/agent-media-payload 门面及其 buildAgentMediaPayload(...) 投影已弃用。

如何迁移

await api.runtime.config.mutateConfigFile({  afterWrite: { mode: "auto" },  mutate(draft) {    draft.plugins ??= {};  },});

// OpenClaw 运行时工具和 Codex 运行时动态工具（结果可能会被// 转换）。Codex 原生工具结果也会被转发以供观察，// 但其转换后的输出绝不会传递给模型：Codex// PostToolUse 钩子契约无法替换原生工具响应。api.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"]  }}

// 之前const program = applyWindowsSpawnProgramPolicy({ candidate }); // 之后const program = applyWindowsSpawnProgramPolicy({  candidate,  // 仅为有意接受经由 shell 回退的可信兼容性调用方  // 设置此项。  allowShellFallback: true,});

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/

// 之前（已弃用的向后兼容层）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";

// 之前（已弃用的 extension-api 桥接）import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // 之后（注入的运行时）const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test my-plugin/

导入路径参考

公共软件包导出映射是可导入 SDK 子路径的权威来源。请使用 SDK 概览中链接的专题 SDK 指南，并优先选择文档中最精确的公共子路径。scripts/lib/plugin-sdk-entrypoints.json 中的编译器清单还包含用于构建内置插件的私有本地条目；这些条目出现在其中并不意味着它们是公共软件包导出项。

此表仅列出常用迁移子集，并非完整的 SDK 接口。编译器入口点清单位于 scripts/lib/plugin-sdk-entrypoints.json；软件包导出项从公共子集生成。

为内置插件保留的辅助接口已从公共 SDK 导出映射中移除，但明确记录的兼容性外观除外，例如为仍直接导入已发布 @openclaw/discord 软件包的外部插件保留的已弃用 plugin-sdk/discord 垫片。所有者专用辅助函数位于其所属插件软件包内；共享主机行为通过 plugin-sdk/gateway-runtime、plugin-sdk/security-runtime 和注入的插件 API 等通用 SDK 契约提供。

请使用与任务匹配的最精确导入。如果找不到某个导出项，请检查 src/plugin-sdk/ 中的源代码，或询问维护者应由哪个通用契约负责。

已移除的兼容性接口

2026 年 7 月的清理移除了根 SDK 和兼容性聚合入口、扩展 API 桥接、已过期的 SDK 子路径别名、未使用的 SDK 子路径，以及仅供内置使用的 SDK 模块的公共导出。仅供内置使用的模块仍可由其仓库所有者通过私有本地构建映射使用；无法从已发布的软件包中导入这些模块。

进程全局 API 提供商发布

registerApiProvider(...) 和 unregisterApiProviders(...) 已从 openclaw/plugin-sdk/llm 中移除。它们将 API 传输发布到进程全局状态中，之后由生命周期所有的模型运行时复制到每个已准备的注册表中。

提供商插件应通过 api.registerProvider(...) 注册文本推理提供商。构造 ApiRegistry 的主机所有代码和测试应直接在该注册表上注册，以便将提供商所有权和拆卸范围限定在已准备的运行时中。

私有测试聚合入口

openclaw/plugin-sdk/testing 仅供仓库本地使用，且未包含在已发布的软件包工件中，因此已在其 2026-07-28 removeAfter 日期之前移除。仓库测试使用精确子路径，例如 plugin-sdk/plugin-test-runtime、plugin-sdk/channel-test-helpers、plugin-sdk/channel-target-testing、 plugin-sdk/test-env 和 plugin-sdk/test-fixtures。

迁移参考

这些映射涵盖已于 2026 年 7 月移除的表面，以及后续时间窗口内仍处于活跃状态的弃用项。映射是迁移指导，并不表示旧表面仍然可用；请查阅兼容性注册表和移除时间线以了解当前状态。

// 之前import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // 之后import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// 之前api.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // 之后api.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

// 之前api.on("subagent_spawning", async () => ({  status: "ok",  threadBindingReady: true,  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },})); // 之后api.on("subagent_spawned", async (event) => {  await observeSubagentLaunch(event);});

{  "contracts": {    "externalAuthProviders": ["anthropic", "openai"]  }}

// 之前const flow = api.runtime.tasks.flow.fromToolContext(ctx);// 之后const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// 之前import type { OpenClawSchemaType } from "openclaw/plugin-sdk";// 之后import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";

Talk 和实时语音迁移

实时语音、电话、会议和浏览器 Talk 代码共享一个由 openclaw/plugin-sdk/realtime-voice 导出的 Talk 会话控制器。该控制器负责通用 Talk 事件封装、活动轮次状态、采集状态、 音频输出状态、最近事件历史记录和过期轮次拒绝。提供商插件负责供应商特定的实时会话。 浏览器会议插件使用 openclaw/plugin-sdk/meeting-runtime 处理会话、浏览器、音频、节点主机、 Agent 咨询和语音通话机制，然后实现 MeetingPlatformAdapter， 以处理 URL 规则、DOM 脚本、手动操作映射、字幕、创建和拨入计划。 平台 REST API、OAuth、工件、选择器和传输字段名称仍保留在插件中。 浏览器权限计划会接收请求的会议 URL，以便每个平台仅授予其确切支持的来源。 会话运行时还必须在确认浏览器离开后规范化平台特定的实时健康状态； 历史转录字段可以保留，但离开后字幕和音频就绪状态不得继续处于活动状态。

所有内置界面都在共享控制器上运行：浏览器中继、托管房间交接、 语音通话实时会话、语音通话流式 STT、Google Meet 实时会话以及原生按键通话。 Gateway 网关在 hello-ok.features.events 中公布一个实时 Talk 事件渠道： talk.event。

除非实现低级适配器或测试夹具，否则新代码不应直接调用 createTalkEventSequencer(...)。请使用共享控制器，以确保无法在没有轮次 ID 的情况下发出 轮次范围事件，过期的 turnEnd / turnCancel 调用无法清除 较新的活动轮次，并确保音频输出生命周期事件在电话、会议、浏览器中继、 托管房间交接和原生 Talk 客户端之间保持一致。

公共 API 结构：

// Gateway 网关负责的 Talk 会话 API。await gateway.request("talk.session.create", {  mode: "realtime",  transport: "gateway-relay",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.session.appendAudio", { sessionId, audioBase64 });await gateway.request("talk.session.cancelOutput", { sessionId, reason: "barge-in" });await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "working" },  options: { willContinue: true },});await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "already_delivered" },  options: { suppressResponse: true },});await gateway.request("talk.session.submitToolResult", { sessionId, callId, result });await gateway.request("talk.session.close", { sessionId }); // 客户端负责的提供商会话 API。await gateway.request("talk.client.create", {  mode: "realtime",  transport: "webrtc",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.client.toolCall", { sessionKey, callId, name, args });await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

浏览器负责的 WebRTC/提供商 WebSocket 会话使用 talk.client.create， 因为浏览器负责提供商协商和媒体传输，而 Gateway 网关负责凭据、指令和工具策略。 talk.session.* 是 Gateway 网关管理的通用界面，用于 Gateway 网关中继实时会话、 Gateway 网关中继转录以及托管房间原生 STT/TTS 会话。

对于将实时选择器放在 talk.provider / talk.providers 旁边的旧版配置，应使用 openclaw doctor --fix 修复；Talk 运行时不会将语音/TTS 提供商配置重新解释为实时提供商配置。

受支持的 talk.session.create 组合被有意限制在较小范围内：

供从旧版 talk.realtime.* / talk.transcription.* / talk.handoff.* 系列迁移的读者参考的方法映射（均已移除）：

统一控制词汇也被刻意限制在较小范围内：

不要在核心中引入提供商或平台特例来实现此功能。 核心负责 Talk 会话语义。提供商插件负责供应商会话设置。 语音通话和 Google Meet 负责电话/会议适配器。浏览器和原生应用 负责设备采集/播放用户体验。

移除时间线

以下剩余的公共 SDK 子路径均有由注册表支持的移除窗口。 7 月 30 日对应的条目已在维护者提前授权的清理后移除： 未使用的子路径已删除，早期的兼容性别名已删除，并且 仅供内置组件使用的模块已降级为私有本地构建映射。

所有核心插件都已完成迁移。外部插件应在 下一个主要版本发布前迁移。运行 pnpm plugins:boundary-report，查看插件所用接口中 哪些兼容性记录最早到期。

暂时禁止显示警告

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

这只是临时的应急手段，并非永久解决方案。

相关内容

• 入门指南 - 构建你的第一个插件
• SDK 概览 - 完整的子路径导入参考
• 渠道插件 - 构建渠道插件
• 提供商插件 - 构建提供商插件
• 插件内部机制 - 深入解析架构
• Plugin Manifest - 清单架构参考