插件 SDK 迁移指南

OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，采用专注、有文档的子路径导入。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。

发生了什么变化

旧插件系统提供了两个"大开口"，让插件从单一入口点导入任何所需内容：

openclaw/plugin-sdk/compat — 一个重新导出了数十个辅助函数的单一导入。它在新插件架构建设期间被引入，用于保持旧版基于 hook 的插件正常工作。
openclaw/extension-api — 一个桥接器，给插件提供了对宿主端辅助工具（如内嵌 agent 运行器）的直接访问。

这两个接口现在都已弃用。它们在运行时仍然有效，但新插件不得使用它们，现有插件应在下一个主版本移除它们之前完成迁移。

警告： 向后兼容层将在未来的主版本中被移除。仍然从这些接口导入的插件届时将会失效。

为什么要改变

旧方式带来了一些问题：

启动慢 — 导入一个辅助函数会加载数十个无关模块
循环依赖 — 宽泛的重新导出很容易造成导入循环
API 接口不清晰 — 无法区分哪些导出是稳定的，哪些是内部实现

现代插件 SDK 解决了这些问题：每个导入路径（openclaw/plugin-sdk/<subpath>）都是一个小型、独立的模块，有明确的用途和已记录的契约。

如何迁移

第一步：找出废弃导入

在你的插件中搜索来自两个废弃接口的导入：

bash

grep -r "plugin-sdk/compat" my-plugin/
grep -r "openclaw/extension-api" my-plugin/

第二步：替换为专注导入

旧接口的每个导出都对应一个具体的现代导入路径：

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";

对于宿主端辅助工具，使用注入的插件运行时而不是直接导入：

typescript

// 之前（废弃的 extension-api 桥接）
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });

// 之后（注入的运行时）
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

其他遗留桥接辅助工具的对应关系：

旧导入	现代等价
`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 辅助工具	`api.runtime.agent.session.*`

第三步：构建并测试

bash

pnpm build
pnpm test -- my-plugin/

导入路径参考

完整导入路径表：

导入路径	用途	主要导出
`plugin-sdk/plugin-entry`	规范插件入口辅助	`definePluginEntry`
`plugin-sdk/core`	渠道入口定义、渠道 builder、基础类型	`defineChannelPluginEntry`, `createChatChannelPlugin`
`plugin-sdk/channel-setup`	Setup wizard 适配器	`createOptionalChannelSetupSurface`
`plugin-sdk/channel-pairing`	DM 配对原语	`createChannelPairingController`
`plugin-sdk/channel-reply-pipeline`	回复前缀 + 打字指示器接线	`createChannelReplyPipeline`
`plugin-sdk/channel-config-helpers`	配置适配器工厂	`createHybridChannelConfigAdapter`
`plugin-sdk/channel-config-schema`	配置 schema builder	渠道配置 schema 类型
`plugin-sdk/channel-policy`	群组/DM 策略解析	`resolveChannelGroupRequireMention`
`plugin-sdk/channel-lifecycle`	账户状态追踪	`createAccountStatusSink`
`plugin-sdk/channel-runtime`	运行时接线辅助	渠道运行时工具
`plugin-sdk/channel-send-result`	发送结果类型	回复结果类型
`plugin-sdk/runtime-store`	持久化插件存储	`createPluginRuntimeStore`
`plugin-sdk/allow-from`	白名单格式化	`formatAllowFromLowercase`
`plugin-sdk/allowlist-resolution`	白名单输入映射	`mapAllowlistResolutionInputs`
`plugin-sdk/command-auth`	命令门控	`resolveControlCommandGate`
`plugin-sdk/secret-input`	密钥输入解析	密钥输入辅助工具
`plugin-sdk/webhook-ingress`	Webhook 请求辅助	Webhook 目标工具
`plugin-sdk/reply-payload`	消息回复类型	回复载荷类型
`plugin-sdk/provider-onboard`	Provider 引导补丁	引导配置辅助
`plugin-sdk/keyed-async-queue`	有序异步队列	`KeyedAsyncQueue`
`plugin-sdk/testing`	测试工具	测试辅助和 mock

选择最窄的、符合需求的导入路径。如果找不到某个导出，请查看 src/plugin-sdk/ 目录下的源码，或在 Discord 上提问。

移除时间表

时间	发生的事情
当前	废弃接口在运行时发出警告
下一个主版本	废弃接口将被移除；仍在使用它们的插件将会失效

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

临时屏蔽警告

在迁移过程中，可设置以下环境变量来临时屏蔽警告：

bash

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

这是临时应急方案，不是永久解决办法。

插件 SDK 迁移指南 ​

发生了什么变化 ​

为什么要改变 ​

如何迁移 ​

导入路径参考 ​

移除时间表 ​

临时屏蔽警告 ​

相关链接 ​

插件 SDK 迁移指南

发生了什么变化

为什么要改变

如何迁移

导入路径参考

移除时间表

临时屏蔽警告

相关链接