插件 SDK 迁移

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

# 变化内容

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

• openclaw/plugin-sdk/compat - 单个导入，重新导出了数十个辅助工具。它的引入是为了在构建新插件架构期间，让较旧的基于钩子的插件继续工作。
• openclaw/plugin-sdk/infra-runtime - 宽泛的运行时辅助工具桶，混合了系统事件、Heartbeat 状态、投递队列、fetch/proxy 辅助工具、文件辅助工具、审批类型和无关实用工具。
• openclaw/plugin-sdk/config-runtime - 宽泛的配置兼容性桶，在迁移窗口期间仍携带已弃用的直接加载/写入辅助工具。
• openclaw/extension-api - 一个桥接层，让插件可以直接访问主机侧辅助工具，例如嵌入式智能体运行器。
• 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 });
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 转录以及托管房间原生 STT/TTS 会话。

将实时选择器放在 talk.provider / talk.providers 旁边的旧配置应使用 openclaw doctor --fix 修复；运行时 Talk 不会将 speech/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 gate 应因到期兼容性记录、跨所有者保留 SDK 导入或未使用的保留 SDK 子路径失败时使用 pnpm plugins:boundary-report:ci。该报告按移除日期对已弃用的兼容性记录分组，统计本地代码/文档引用，暴露跨所有者保留 SDK 导入，并汇总私有 memory-host SDK bridge，确保兼容性清理保持明确，而不是依赖临时搜索。保留 SDK 子路径必须有跟踪的所有者使用情况；未使用的保留 helper 导出应从公共 SDK 中移除。

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

# 如何迁移

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

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

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

// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });

// After
const 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 build
pnpm test -- my-plugin/

# 导入路径参考

此表刻意只列出常见迁移子集，而不是完整 SDK 表面。200 多个入口点的完整列表位于 scripts/lib/plugin-sdk-entrypoints.json。

预留的内置插件辅助接缝已从公共 SDK 导出映射中退休，但明确记录的兼容门面除外，例如为已发布的 @openclaw/[email protected] 包保留的已弃用 plugin-sdk/discord shim。特定所有者的辅助工具位于其所属插件包内部；共享的宿主行为应通过通用 SDK 契约迁移，例如 plugin-sdk/gateway-runtime、plugin-sdk/security-runtime 和 plugin-sdk/plugin-config-runtime。

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

# 活跃弃用项

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

// Before
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

# 移除时间线

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

# 临时抑制警告

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

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

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

# 相关内容

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