插件 SDK 迁移

OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，使用聚焦且有文档说明的导入。如果你的插件是在新架构之前构建的，本指南可帮助你迁移。

有哪些变化

旧插件系统提供了两个完全开放的表面，让插件可以从单一入口点导入它们需要的任何内容：

• openclaw/plugin-sdk/compat - 一个单一导入，会重新导出数十个辅助工具。它的引入是为了在新插件架构构建期间，让较旧的基于钩子的插件继续工作。
• openclaw/plugin-sdk/infra-runtime - 一个宽泛的运行时辅助工具桶，混合了系统事件、Heartbeat 状态、投递队列、fetch/proxy 辅助工具、文件辅助工具、审批类型和无关实用工具。
• openclaw/plugin-sdk/config-runtime - 一个宽泛的配置兼容桶，在迁移窗口期间仍携带已弃用的直接加载/写入辅助工具。
• openclaw/extension-api - 一个桥接层，让插件可以直接访问主机侧辅助工具，例如嵌入式 Agent 运行器。
• api.registerEmbeddedExtensionFactory(...) - 一个已移除的仅限 Pi 的内置插件钩子，可观察嵌入式运行器事件，例如 tool_result。

这些宽泛的导入表面现在已弃用。它们在运行时仍然可用，但新插件不得使用它们，现有插件也应在下一个主要版本移除它们之前完成迁移。仅限 Pi 的嵌入式插件工厂注册 API 已被移除；请改用工具结果中间件。

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

为什么做出此变更

旧方法会导致问题：

• 启动缓慢 - 导入一个辅助工具会加载数十个无关模块
• 循环依赖 - 宽泛的重新导出很容易产生导入循环
• API 表面不清晰 - 无法判断哪些导出是稳定的，哪些是内部的

现代插件 SDK 修复了这一点：每个导入路径（openclaw/plugin-sdk/\<subpath\>）都是一个小型、自包含的模块，具有清晰用途和已记录的契约。

用于内置渠道的旧版提供商便捷衔接点也已移除。带渠道品牌的辅助衔接点是私有单仓库快捷方式，不是稳定的插件契约。请改用窄范围的通用 SDK 子路径。在内置插件工作区内，将提供商所有的辅助工具保留在该插件自己的 api.ts 或 runtime-api.ts 中。

当前内置提供商示例：

• Anthropic 将 Claude 专用流辅助工具保留在它自己的 api.ts / contract-api.ts 衔接点中
• OpenAI 将提供商构建器、默认模型辅助工具和实时提供商构建器保留在它自己的 api.ts 中
• OpenRouter 将提供商构建器和新手引导/配置辅助工具保留在它自己的 api.ts 中

Talk 和实时语音迁移计划

实时语音、电话、会议和浏览器 Talk 代码正在从表面本地的轮次记账迁移到由 openclaw/plugin-sdk/realtime-voice 导出的共享 Talk 会话控制器。新的控制器负责通用 Talk 事件信封、活动轮次状态、采集状态、输出音频状态、最近事件历史和过期轮次拒绝。提供商插件应继续负责厂商专用实时会话；表面插件应继续负责采集、播放、电话和会议差异。

这次 Talk 迁移有意采用破坏性清理：

1. 将共享控制器/运行时原语保留在 plugin-sdk/realtime-voice 中。
2. 将内置表面迁移到共享控制器：浏览器中继、托管房间交接、语音通话实时、语音通话流式 STT、Google Meet 实时和原生按键通话。
3. 用最终的 talk.session.* 和 talk.client.* API 替换旧 Talk RPC 系列。
4. 在 Gateway 网关 hello-ok.features.events 中公开一个实时 Talk 事件渠道：talk.event。
5. 删除旧的实时 HTTP 端点和任何请求时指令覆盖路径。

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

目标公共 API 形态如下：

// Gateway-owned Talk session 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 }); // Client-owned provider session 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 });

浏览器所有的 WebRTC/提供商 websocket 会话使用 talk.client.create，因为浏览器拥有提供商协商和媒体传输，而 Gateway 网关拥有凭证、指令和工具策略。talk.session.* 是由 Gateway 网关管理的通用表面，适用于 gateway-relay 实时、gateway-relay 转录和 managed-room 原生 STT/TTS 会话。

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

受支持的 talk.session.create 组合有意保持很小：

已移除的方法映射：

统一控制词汇也有意保持窄范围：

不要在核心中引入提供商或平台特殊情况来实现这项工作。 核心负责 Talk 会话语义。提供商插件负责厂商会话设置。 语音通话和 Google Meet 负责电话/会议适配器。浏览器和原生 应用负责设备采集/播放 UX。

兼容性策略

对于外部插件，兼容性工作按此顺序进行：

1. 添加新契约
2. 保持旧行为通过兼容性适配器连接
3. 发出诊断或警告，指出旧路径和替代方案
4. 在测试中覆盖两条路径
5. 记录弃用和迁移路径
6. 仅在已公告的迁移窗口后移除，通常在主版本发布中移除

维护者可以用 pnpm plugins:boundary-report 审计当前迁移队列。使用 pnpm plugins:boundary-report:summary 获取 紧凑计数，使用 --owner <id> 针对单个插件或兼容性所有者，并在 CI 门禁需要因到期的 兼容性记录、跨所有者保留 SDK 导入或未使用的保留 SDK 子路径而失败时使用 pnpm plugins:boundary-report:ci。报告会按移除日期分组已弃用的 兼容性记录，统计本地代码/文档引用，暴露跨所有者保留 SDK 导入，并总结私有 memory-host SDK 桥接，使兼容性清理保持显式，而不是依赖临时搜索。保留 SDK 子路径必须有已跟踪的所有者用法； 未使用的保留辅助导出应从公共 SDK 中移除。

如果某个清单字段仍被接受，插件作者可以继续使用它，直到 文档和诊断另行说明。新代码应优先使用已记录的 替代项，但现有插件不应在普通次版本 发布期间中断。

如何迁移

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

// Pi and Codex runtime dynamic toolsapi.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["pi", "codex"],});

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

// Beforeconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Afterconst program = applyWindowsSpawnProgramPolicy({  candidate,  // Only set this for trusted compatibility callers that intentionally  // accept shell-mediated fallback.  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/

// Before (deprecated backwards-compatibility layer)import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // After (modern focused imports)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";

// Before (deprecated extension-api bridge)import { runEmbeddedPiAgent } from "openclaw/extension-api";const result = await runEmbeddedPiAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

导入路径参考

此表有意只列出通用迁移子集，而不是完整 SDK 表面。编译器入口点清单位于 scripts/lib/plugin-sdk-entrypoints.json；包导出会从 公共子集生成。

预留的内置插件辅助衔接面已从公共 SDK 导出映射中退役，但明确记录的兼容性门面除外，例如已弃用的 plugin-sdk/discord shim，它是为已发布的 @openclaw/discord@2026.3.13 包保留的。所有者专属辅助函数位于 所属插件包内；共享主机行为应通过通用 SDK 契约移动，例如 plugin-sdk/gateway-runtime、plugin-sdk/security-runtime 和 plugin-sdk/plugin-config-runtime。

使用与任务匹配的最窄导入。如果找不到导出， 请检查 src/plugin-sdk/ 中的源代码，或询问维护者哪个通用契约 应拥有它。

活跃弃用项

适用于插件 SDK、提供商契约、 运行时表面和清单的更窄弃用项。每一项现在仍可工作，但会在 未来的主版本中移除。每个条目下方的内容会把旧 API 映射到其 规范替代项。

// Beforeimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Afterimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

// Beforeconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Afterconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Beforeimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Afterimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

移除时间线

所有核心插件都已经迁移。外部插件应在下一个主版本发布前迁移。

临时抑制警告

在迁移期间设置这些环境变量：

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

这是临时逃生口，不是永久解决方案。

相关内容

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