Appearance
本页是 OpenClaw 插件 SDK 迁移指南，面向仍在使用旧版 plugin-sdk/compat 或 openclaw/extension-api 兼容层的插件作者。涵盖变更原因、四步迁移流程、常用导入路径对照表（200+ 子路径摘要），以及临时抑制废弃警告的环境变量。下一个主版本将彻底移除旧接口，建议尽早迁移。
OpenClaw 插件 SDK 迁移
OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，采用聚焦、有文档的导入路径。如果你的插件是在新架构之前构建的，本指南帮助你完成迁移。
正在变更的内容
旧版插件系统提供了两个开放接口：
openclaw/plugin-sdk/compat— 单一导入重新导出数十个 helper，在新插件架构构建期间用于保持旧版 hook 插件正常工作openclaw/extension-api— 给插件直接访问宿主端 helper（如嵌入式 agent runner）的桥接接口
两个接口现已废弃。它们在 runtime 仍然工作，但新插件禁止使用，现有插件应在下一个主版本移除它们之前完成迁移。
警告： 向后兼容层将在未来的主版本中被移除。仍然从这些接口导入的插件届时将失效。
为什么做这个改变
旧方式带来了以下问题：
- 启动慢 — 导入一个 helper 会加载数十个无关模块
- 循环依赖 — 宽泛的重新导出容易产生导入循环
- API 边界不清 — 无法区分哪些导出是稳定 API，哪些是内部实现
现代插件 SDK 修复了这些问题：每个导入路径（openclaw/plugin-sdk/<subpath>）是一个小型、自包含的模块，有明确用途和文档化的合约。
旧版 Provider 便利接缝（如 openclaw/plugin-sdk/slack、openclaw/plugin-sdk/discord 等渠道品牌 helper 接缝）也已移除——这些只是私有 monorepo 快捷方式，不是稳定的插件合约。改用窄型通用 SDK 子路径代替。
迁移步骤
步骤 1：审查 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，改为处理抛出的错误。
步骤 2：找出废弃导入
搜索插件中来自废弃接口的导入：
bash
grep -r "plugin-sdk/compat" my-plugin/
grep -r "openclaw/extension-api" my-plugin/步骤 3：替换为聚焦导入
旧接口中的每个导出都对应一个具体的现代导入路径：
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.* |
步骤 4：构建并测试
bash
pnpm build
pnpm test -- my-plugin/常用导入路径参考
以下是常用迁移子路径，覆盖大多数插件的迁移需求：
| 导入路径 | 用途 | 关键导出 |
|---|---|---|
plugin-sdk/plugin-entry | 插件入口 helper | definePluginEntry |
plugin-sdk/channel-core | 渠道入口和构建 helper | defineChannelPluginEntry、createChatChannelPlugin |
plugin-sdk/config-schema | 根配置 schema | OpenClawSchema |
plugin-sdk/provider-entry | 单 Provider 入口 helper | defineSingleProviderPluginEntry |
plugin-sdk/setup-runtime | Setup 时 runtime helper | 安全的 setup patch 适配器、lookup-note、promptResolvedAllowFrom |
plugin-sdk/channel-setup | 可选安装 setup 面 | createOptionalChannelSetupSurface 等 |
plugin-sdk/channel-pairing | DM 配对原语 | createChannelPairingController |
plugin-sdk/channel-reply-pipeline | 回复前缀+输入接线 | createChannelReplyPipeline |
plugin-sdk/account-core | 多账号配置 helper | 账号列表/配置/动作门控 |
plugin-sdk/approval-runtime | 审批 helper | exec/插件审批载荷、能力构建器、原生路由 |
plugin-sdk/runtime-store | 插件持久化存储 | createPluginRuntimeStore |
plugin-sdk/command-auth | 命令门控 helper | resolveControlCommandGate、发送者授权 helper |
plugin-sdk/security-runtime | 安全 helper | 信任/DM 门控/外部内容/密钥收集 helper |
plugin-sdk/reply-runtime | 共享回复 runtime | 入站调度/心跳/回复规划器/分块 |
plugin-sdk/provider-auth | Provider 认证 helper | createProviderApiKeyAuthMethod |
plugin-sdk/provider-model-shared | 共享 Provider 模型/回放 helper | ProviderReplayFamily、buildProviderReplayFamilyHooks |
plugin-sdk/provider-stream | Provider 流式传输 helper | ProviderStreamFamily、buildProviderStreamFamilyHooks |
plugin-sdk/provider-tools | Provider 工具 schema 兼容 helper | buildProviderToolCompatFamilyHooks、Gemini schema 清理 |
plugin-sdk/memory-core | 内置 memory-core helper | 内存管理器/配置/文件/CLI helper |
plugin-sdk/testing | 测试工具 | 测试 helper 和 mock |
此表是常见迁移子路径的子集，非完整 SDK 接口。完整 200+ 入口点列表在
scripts/lib/plugin-sdk-entrypoints.json。
移除时间表
| 时间 | 内容 |
|---|---|
| 现在 | 废弃接口在 runtime 产生警告 |
| 下一个主版本 | 废弃接口被移除，仍使用的插件将失效 |
所有 core 插件已完成迁移。外部插件应在下一个主版本前完成迁移。
临时抑制警告
迁移过程中，可以通过以下环境变量临时抑制警告：
bash
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run这只是临时逃生通道，不是永久解决方案。
相关文档
- 插件开发入门 — 构建你的第一个插件
- SDK 概览 — 完整子路径导入参考
- 渠道插件开发 — 构建渠道插件
- Provider 插件开发 — 构建 Provider 插件
- 插件内部架构 — 架构深度解析
常见问题
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/feishu、plugin-sdk/matrix 这类接缝还能用吗？
A: 这些是内置插件专用的维护和兼容接缝，不建议第三方插件使用。外部插件应改用通用 SDK 子路径（如 plugin-sdk/channel-core、plugin-sdk/setup-runtime 等）。这些内置 helper 在后续版本中可能发生破坏性变更且不作通知。
Q: 迁移后如何确认已完全移除旧接口的使用？
A: 运行 openclaw gateway run 不再看到 OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED 或 OPENCLAW_EXTENSION_API_DEPRECATED 警告，即代表迁移完成。也可以在测试套件中加断言检查无旧导入路径。