概述
OpenClaw 已从宽泛的向后兼容层迁移到现代插件 SDK，使用聚焦的、有文档的导入。旧系统提供了两个宽泛的面：openclaw/plugin-sdk/compat 和 openclaw/plugin-sdk/infra-runtime，现已废弃。
警告： 向后兼容层将在下一个主要版本中移除。Pi-only 嵌入式扩展工厂注册（api.registerEmbeddedExtensionFactory）已被移除。
核心 API
迁移步骤
1. 迁移运行时配置加载/写入
// 旧（废弃）
api.runtime.config.loadConfig()
api.runtime.config.writeConfigFile(...)
// 新
const cfg = api.runtime.config.current();
await api.runtime.config.mutateConfigFile({
afterWrite: { mode: "auto" },
mutate(draft) { draft.plugins ??= {}; },
});2. 迁移 Pi 工具结果扩展到中间件
// 旧（已移除）
api.registerEmbeddedExtensionFactory(...)
// 新
api.registerAgentToolResultMiddleware(async (event) => {
return compactToolResult(event);
}, { runtimes: ["pi", "codex"] });3. 替换宽泛的 infra-runtime 导入
| 需求 | 导入 |
|---|---|
| 系统事件队列 | openclaw/plugin-sdk/system-event-runtime |
| 心跳辅助工具 | openclaw/plugin-sdk/heartbeat-runtime |
| 安全令牌辅助工具 | openclaw/plugin-sdk/secure-random-runtime |
| 错误格式化 | openclaw/plugin-sdk/error-runtime |
| 代理和守卫 fetch | openclaw/plugin-sdk/fetch-runtime |
| 文件锁 | openclaw/plugin-sdk/file-lock |
4. 替换宽泛的 config-runtime 导入
| 需求 | 导入 |
|---|---|
| 配置类型 | openclaw/plugin-sdk/config-contracts |
| 运行时快照读取 | openclaw/plugin-sdk/runtime-config-snapshot |
| 配置写入 | openclaw/plugin-sdk/config-mutation |
| 会话存储辅助工具 | openclaw/plugin-sdk/session-store-runtime |
5. 迁移 Channel 路由辅助工具
| 旧辅助工具 | 新辅助工具 |
|---|---|
channelRouteIdentityKey(...) | channelRouteDedupeKey(...) |
channelRouteKey(...) | channelRouteCompactKey(...) |
ComparableChannelTarget | ChannelRouteParsedTarget |
comparableChannelTargetsMatch(...) | channelRouteTargetsMatchExact(...) |
Talk 和实时语音迁移
旧 Talk RPC 方法映射：
| 旧方法 | 新方法 |
|---|---|
talk.realtime.session | talk.client.create |
talk.realtime.relayAudio | talk.session.appendAudio |
talk.realtime.relayCancel | talk.session.cancelOutput |
talk.realtime.relayStop | talk.session.close |
talk.transcription.session | talk.session.create({ mode: "transcription" }) |
活跃废弃项
| 废弃项 | 替换 |
|---|---|
resolveInboundMentionRequirement(...) | resolveInboundMentionDecision(...) |
ProviderDiscoveryOrder | ProviderCatalogOrder |
api.registerMemoryPromptSection/FlushPlan/Runtime | api.registerMemoryCapability(...) |
runtime.tasks.flow | runtime.tasks.managedFlows |
OpenClawSchemaType | OpenClawConfig |
临时抑制警告
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run相关页面
- concepts/plugin-sdk-overview — 完整子路径导入参考
- concepts/plugin-sdk-subpaths — 子路径目录
- concepts/plugin-building — 插件构建入门
- concepts/plugin-manifest — 清单 Schema 参考