迁移到 SDK
OpenClaw 用一个由小型、聚焦导入构建的现代插件架构,取代了广泛的向后兼容层。如果你的插件早于该变更,本指南可帮助其迁移到当前契约。
发生了什么变化¶
多个开放的导入表面过去允许插件从单个入口点访问几乎任何内容:
openclaw/plugin-sdk和openclaw/plugin-sdk/compat- 在构建聚焦 SDK 期间重新导出了数十个辅助函数。这两个根路径现已移除。请改为导入有文档说明的子路径。openclaw/plugin-sdk/infra-runtime- 一个混合了系统事件、心跳状态、投递队列、fetch/proxy 辅助函数、文件辅助函数、审批类型以及无关实用工具的宽泛 barrel。openclaw/plugin-sdk/config-runtime- 一个已移除的宽泛配置 barrel,包括其已弃用的直接loadConfig和writeConfigFile导出。openclaw/plugin-sdk/channel-lifecycle、channel-message和channel-reply-pipeline- 已移除的通道兼容门面。请使用聚焦的出站和入站契约,并检查每个命名导出。openclaw/extension-api- 一个已移除的桥接,曾让插件直接访问宿主端辅助函数,例如嵌入式 agent runner。api.registerEmbeddedExtensionFactory(...)- 一个已移除的仅用于嵌入式 runner 的钩子,曾观察嵌入式 runner 事件,例如tool_result。请改用 agent tool-result 中间件(参见将嵌入式 tool-result 扩展迁移到中间件)。
根 SDK、兼容 barrel、扩展桥接、嵌入式扩展工厂以及五个通道/配置/基础设施兼容门面已被移除。后者的退役于 2026 年 9 月 30 日获得 SDK 所有者的明确批准;参见移除时间线。
Warning
导入已移除 SDK 或扩展表面的插件将无法再加载。升级前请遵循导入路径映射。
OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已文档化的插件行为。破坏性契约变更会先经过兼容适配器、诊断、文档和弃用窗口。这适用于 SDK 导入、manifest 字段、setup API、钩子以及运行时注册行为。
ChatCommandDefinition.category 保留 2026.8.1 SDK 接受的 "docks" 值。命令列表会在 Tools 下显示这些遗留定义。该类别不会启用通道停靠,也不会恢复已退役的停靠命令。新定义应使用 "tools"。
捆绑的 ACP 集成应等待来自本地 openclaw/plugin-sdk/acp-runtime 门面的 readAcpSessionEntryAsync,用于读取会话元数据。该门面仍是一个 JavaScript 兼容导出;其声明被排除在类型化公共 SDK 之外。基于文件的读取在 SQLite workers 上运行,并在整个元数据 join 过程中保持会话生命周期。基于文件的结果是分离的快照,即使提供了 clone: false 也是如此。返回的 storeReadFailed 标志仍然用于区分不可读的会话存储与缺失的元数据;当该标志被设置时,启动清理必须保留绑定。未绑定的遗留 ACP 元数据仍可能伴随该标志出现;它不会证明会话行有效。源退役和 worker 失败会拒绝读取,且不得被视为会话不存在。
同步的 readAcpSessionEntry 和 getAcpSessionManager().resolveSession() 契约在 v2026.9.4 中发布,仍可供该兼容导出的现有使用者使用。它们已弃用于运行时使用。普通 ACP manager 和 Gateway 调用方使用 readAcpSessionEntryAsync 和 getAcpSessionManager().resolveSessionAsync()。Discord 和 Telegram 启动绑定清理保留其现有同步读取器,直到条件删除能够在变更所有者处验证元数据。其非活动 incognito 组合接受一个已准备的会话读取器,其当前源断言到达绑定事务和提交授权。该准备保留原始 actor 修订版本和 ACP 元数据发布 fence,直到清理释放它。本地 prepareAcpSessionEntryRead 辅助函数捕获现有私有 actor 绑定并提供该保留读取器;没有绑定时返回 undefined。Discord 和 Telegram 启动清理默认使用它。普通生产获取保持原生,直到原子 incognito 激活;受保护的持久清理仍是单独工作。通过本地 openclaw/plugin-sdk/acp-runtime 门面暴露的 IncognitoSessionEndedError 和 IncognitoSessionSyncAccessError 必须通过清理和状态探测传播。在将其他失败视为会话不存在或探测不确定之前,使用 rethrowIncognitoSessionError(error);它还识别嵌套拒绝。移除同步契约需要单独宣布的破坏性 SDK 发布。Incognito 读取保留其现有原生内存所有者,直到该所有者的 worker 迁移。
会话重置新鲜度¶
通道运行时使用者在决定会话是否需要重置时,应等待 runtime.channel.session.resolveEntryResetFreshnessAsync(...)。基于文件的条目和 transcript 生命周期时间戳从同一 worker 快照读取,并在验证和清理过程中保留原始数据库所有者。在 v2026.9.8 中发布的同步 resolveEntryResetFreshness(...) 方法仍可供现有 JavaScript 使用者使用,并已弃用于运行时使用;移除需要下一个 Plugin SDK 主版本和明确的破坏性发布批准。两种方法都保留现有重置策略和进程持有的 incognito 行为。
原因¶
- 启动缓慢 - 导入一个辅助函数会加载数十个无关模块。
- 循环依赖 - 宽泛的重新导出使导入循环很容易产生。
- API 表面不清晰 - 无法区分稳定导出和内部导出。
类型化公共 SDK 按聚焦的子路径组织,并带有文档化的契约。并非每个 SDK 构建入口都是公共插件 API。
捆绑渠道的旧版 provider 便捷接缝也已移除——带有渠道品牌标识的辅助函数快捷方式是私有 mono-repo 中的便利设施,而不是稳定的插件契约。请改用窄范围的通用 SDK 子路径。在捆绑插件工作区中,将 provider 拥有的辅助函数保留在该插件自己的 api.ts 或 runtime-api.ts 中:
- Anthropic 在其自己的
api.ts/contract-api.ts接缝中保留 Claude 特定的流式辅助函数。 - OpenAI 在其自己的
api.ts中保留 provider 构建器、默认模型辅助函数和实时 provider 构建器。 - OpenRouter 在其自己的
api.ts中保留 provider 构建器以及入门/配置辅助函数。
各主题所在位置¶
单页版本的每个章节都位于下面六个页面之一。 单页版本中的锚点在此处仍然有效。
迁移步骤¶
如何迁移插件 — 有序的迁移步骤。
- 等待个人模型账户操作
- 等待会话转录持久化
- 等待扩展会话变更
- 等待 provider 重放元数据
- 如何迁移
- 迁移运行时配置加载/写入辅助函数
- 将嵌入式 tool-result 扩展迁移到 middleware
- 将 approval-native handler 迁移到 capability facts
- 审计 Windows wrapper 回退行为
- 查找已弃用的导入
- 替换为聚焦的导入
- 替换宽泛的
infra-runtime导入 - 迁移渠道路由辅助函数
- 构建和测试
导入路径¶
导入路径参考 — 哪个类型化公共子路径替代每个旧版导入。
已移除的接口及替代方案¶
已移除的接口及替代方案 — 移除了哪些内容,以及每个旧版 API 的替代方案。
- 已移除的兼容性接口
- 进程全局 API-provider 发布
- Deactivate hook 别名
- 私有测试 barrel
- 迁移参考
command-auth帮助构建器 ->command-status- Mention 门控辅助函数 ->
resolveInboundMentionDecision - 渠道运行时 shim 和渠道 actions 辅助函数
- Web 搜索 provider 的
tool()辅助函数 -> 插件上的createTool() - 纯文本渠道信封 ->
BodyForAgent subagent_spawninghook -> 核心线程绑定- Provider 发现类型 -> provider 目录类型
- Thinking 策略 hook ->
resolveThinkingProfile - 外部 auth provider ->
contracts.externalAuthProviders - Provider 环境变量查找 ->
setup.providers[].envVars - Memory 插件注册 ->
registerMemoryCapability - Memory embedding provider API
- 原始渠道发送结果 ->
OutboundDeliveryResult - Subagent 会话消息类型已重命名
- 已移除的会话和转录文件 API
- Agent harness attempt 参数 -> V2 host-capability 契约
- 嵌入式扩展工厂 -> agent tool-result middleware
OpenClawSchemaType别名 ->OpenClawConfig
Talk 与语音¶
Talk 与实时语音迁移 — 统一的 Talk 会话 API 及其方法映射。
兼容性记录¶
兼容性策略与记录 — 哪些内容被保留、原因,以及在什么条件下可以移除。
- 兼容性策略
- 保留的辅助函数契约
- Harness 尝试结果迁移
- 模型提供方结果兼容性
- Memory 读取缺失结果
- Config 记录迁移
- 插件状态迁移声明
- AuthStorage SQLite 迁移
- 已发布频道设置兼容性
- 频道设置输入字段兼容性
- 验证读取器
- 媒体旧版投影
时间线¶
移除时间线 — 已弃用接口何时符合移除条件。
相关¶
- 入门 - 构建你的第一个插件
- SDK 概览 - 完整的子路径导入参考
- 频道插件 - 构建频道插件
- 提供方插件 - 构建提供方插件
- 插件内部机制 - 架构深入解析
- 插件清单 - 清单模式参考
- 插件钩子 - 类型化与自定义钩子接口
对于已移除的 Tasks 和 TaskFlow 接口,请参阅 Tasks 和 TaskFlow API 移除.
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw