OpenClaw 用现代插件架构取代了广泛的向后兼容层，该架构由小型、聚焦的导入构建而成¶

如果你的插件早于这一变更，本指南可助你将其迁移到当前契约。

变更内容¶

过去，几个宽泛的导入面曾让插件可以从单一入口点访问几乎所有内容：

• openclaw/plugin-sdk 和 openclaw/plugin-sdk/compat：在聚焦 SDK 构建期间重新导出了数十个辅助函数。现在这两个根入口都已移除。请改用文档化的子路径。
• openclaw/plugin-sdk/infra-runtime：一个宽泛的 barrel，混合了系统事件、心跳状态、投递队列、fetch/proxy 辅助函数、文件辅助函数、审批类型以及不相关的工具。
• openclaw/plugin-sdk/config-runtime：为兼容性而保留的宽泛配置 barrel，包含已弃用的直接导出 loadConfig 和 writeConfigFile。这些方法已从注入的插件运行时中移除，但并未从这个保留的 barrel 中移除。
• openclaw/extension-api：一个已移除的桥接层，曾让插件直接访问主机端辅助函数，例如嵌入式 agent 运行器。
• api.registerEmbeddedExtensionFactory(...)：一个已移除的、仅嵌入式运行器使用的钩子，曾观察诸如 tool_result 之类的嵌入式运行器事件。请改用 agent 工具结果中间件（参见将嵌入式工具结果扩展迁移到中间件）。

根 SDK、compat barrel、扩展桥接层以及嵌入式扩展工厂均已被移除。infra-runtime 和 config-runtime 仅保留用于它们各自单独记录的后续弃用窗口。新插件应使用聚焦子路径。

OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有文档记录的插件行为。破坏性契约变更会先经过兼容适配器、诊断、文档和弃用窗口。这适用于 SDK 导入、manifest 字段、设置 API、钩子和运行时注册行为。

ChatCommandDefinition.category 保留 2026.8.1 SDK 所接受的 "docks" 值。命令列表会在 Tools 下显示这些遗留定义。该类别不会启用渠道停靠，也不会恢复已退役的停靠命令。新的定义应使用 "tools"。

捆绑的 ACP 集成应等待本地 openclaw/plugin-sdk/acp-runtime 门面中的 readAcpSessionEntryAsync 完成会话元数据读取。该门面仍然是 JavaScript 兼容导出；其声明不包含在类型化公共 SDK 中。基于文件的读取在 SQLite worker 上运行，并在整个元数据联接过程中保持会话生命周期。基于文件的结果是分离的快照，即使提供了 clone: false 也是如此。返回的 storeReadFailed 标志仍然区分不可读的会话存储与缺失的元数据；当该标志被设置时，启动清理必须保留绑定。未绑定的遗留 ACP 元数据仍可能伴随该标志；它并不能证实会话行。源退役和 worker 失败会使读取被拒绝，且不得将其视为会话不存在。

随 v2026.9.4 发布的同步 readAcpSessionEntry 和 getAcpSessionManager().resolveSession() 契约，对于该兼容导出的现有消费者仍然可用。它们在运行时使用中已被弃用。普通的 ACP manager 和 Gateway 调用方应使用 readAcpSessionEntryAsync 和 getAcpSessionManager().resolveSessionAsync()。Discord 和 Telegram 的启动绑定清理保留其现有的同步读取器，直到条件删除能在变更所有者处验证元数据。该清理迁移仍未完成。移除同步契约需要另行宣布的破坏性 SDK 发布。Incognito 读取保留其现有的原生内存所有者，直到该所有者的 worker 迁移完成。

原因¶

• 启动缓慢：导入一个辅助函数会加载数十个不相关的模块。
• 循环依赖：宽泛的重新导出让导入循环很容易产生。
• API 表面不清晰：无法区分稳定导出与内部导出。

类型化公共 SDK 按聚焦子路径组织，并带有文档化契约。并非每个 SDK 构建入口点都是公共插件 API。

面向捆绑渠道的旧式 provider 便捷接缝也已移除——渠道品牌化的辅助快捷方式本是 monorepo 内部的私有便利实现，而非稳定的插件契约。请改用窄而通用的 SDK 子路径。在捆绑插件工作区内，将 provider 自有的辅助函数保留在该插件自身的 api.ts 或 runtime-api.ts 中：

• Anthropic 将 Claude 专属的流辅助函数保留在其自身的 api.ts / contract-api.ts 接缝中。
• OpenAI 将 provider 构建器、默认模型辅助函数和实时 provider 构建器保留在其自身的 api.ts 中。
• OpenRouter 将 provider 构建器以及 onboarding/config 辅助函数保留在其自身的 api.ts 中。

每个主题的位置¶

单页版本中的每个小节都位于以下六个页面之一。来自单页版本的锚点在此仍然有效。

迁移步骤¶

如何迁移插件 — 有序的迁移步骤。

• 如何迁移
• 迁移运行时配置加载/写入辅助函数
• 将嵌入式工具结果扩展迁移到中间件
• 将审批原生处理器迁移到能力事实
• 审计 Windows 包装器回退行为
• 查找已弃用的导入
• 替换为聚焦导入
• 替换宽泛的 infra-runtime 导入
• 迁移渠道路由辅助函数
• 构建与测试

导入路径¶

导入路径参考 — 每个旧版导入由哪个 typed-public 子路径替代。

• 导入路径参考
• 保留的通道门面映射

已移除的接口与替代方案¶

已移除的接口与替代方案 — 已移除的内容，以及每个旧版 API 的替代方案。

• 已移除的兼容性接口
• 进程级全局 API 提供方发布
• Deactivate 钩子别名
• 私有测试桶文件
• 迁移参考
• command-auth 帮助构建器 -> command-status
• 提及门控辅助函数 -> resolveInboundMentionDecision
• 通道运行时填充层与通道操作辅助函数
• Web 搜索提供方的 tool() 辅助函数 -> 插件上的 createTool()
• 纯文本通道信封 -> BodyForAgent
• subagent_spawning 钩子 -> 核心线程绑定
• Provider 发现类型 -> Provider 目录类型
• 思考策略钩子 -> resolveThinkingProfile
• 外部认证提供方 -> contracts.externalAuthProviders
• Provider 环境变量查找 -> setup.providers[].envVars
• Memory 插件注册 -> registerMemoryCapability
• Memory 嵌入提供方 API
• 原始通道发送结果 -> OutboundDeliveryResult
• 子代理会话消息类型已重命名
• 已移除的会话与转录文件 API
• Agent harness 尝试参数 -> V2 宿主能力契约
• 嵌入式扩展工厂 -> agent 工具结果中间件
• OpenClawSchemaType 别名 -> OpenClawConfig

Talk 与语音¶

Talk 与实时语音迁移 — 统一的 Talk 会话 API 及其方法映射。

• Talk 与实时语音迁移

兼容性记录¶

兼容性策略与记录 — 保留了什么、为什么保留，以及在什么条件下可以移除。

• 兼容性策略
• 保留的辅助契约
• Harness 尝试结果迁移
• 模型提供方结果兼容性
• Memory 读取缺失结果
• 配置记录迁移
• 插件状态迁移声明
• AuthStorage SQLite 迁移
• 已发布的通道设置兼容性
• 通道设置输入字段兼容性
• 验证读取器
• Media 旧版投影

时间线¶

移除时间线 — 已弃用接口何时具备被移除的资格。

• 移除时间线

相关¶

• 入门指南 - 构建你的第一个插件
• SDK 概览 - 完整的子路径导入参考
• 通道插件 - 构建通道插件
• 提供商插件 - 构建提供商插件
• 插件内部机制 - 架构深入解析
• 插件清单 - 清单架构参考
• 插件钩子 - 类型化钩子和自定义钩子接口

对于已移除的 Tasks 和 TaskFlow 接口，请参阅 Tasks 和 TaskFlow API 移除。