Skip to main content
OpenClaw 会在移除旧的插件契约之前，通过命名的兼容性适配器继续连接这些旧契约。这可以在 SDK、manifest、setup、config 和 agent runtime 契约演进的同时，保护现有的内置插件和外部插件。

​
兼容性注册表

插件兼容性契约记录在核心注册表中，位于 src/plugins/compat/registry.ts。每条记录包括：
  • 稳定的兼容性代码
  • 状态：active、deprecated、removal-pending 或 removed
  • 所有者：sdk、config、setup、channel、provider、plugin-execution、 agent-runtime 或 core
  • 适用时的引入日期和弃用日期
  • 所有者维护者批准后，准确的 removeAfter 日期或命名的 removalGate；两者均没有的记录仍不符合移除条件
  • 替代方案指导
  • 覆盖旧行为和新行为的文档、诊断信息和测试
该注册表是维护者规划以及未来插件检查器校验的依据。如果插件面向外部的行为发生变化，请在添加适配器的同一次变更中，添加或更新兼容性记录。 Doctor 修复和迁移兼容性单独记录在 src/commands/doctor/shared/deprecation-compat.ts。这些记录涵盖旧的配置形状、安装账本布局，以及在运行时兼容路径移除后可能仍需保留的修复 shim。 每条 Doctor 兼容性记录都声明了 introduced 和 removeAfter。 当某条记录在 removeAfter 当日或之后仍处于 deprecated 状态时， pnpm check:doctor-deprecation-registry 检查会失败；维护者必须在有受支持的升级证明后将其移除，或将其移至 removal-pending 并记录相应的阻塞因素。removal-pending 记录不会导致日期检查失败，但在满足升级条件之前，仍会保留在明确的审核队列中。 发布检查应同时检查两个注册表。不要仅仅因为匹配的运行时或配置兼容性记录已过期，就删除 Doctor 迁移；应先确认不存在仍需要该修复的受支持升级路径。在发布规划期间也要重新验证每条替代方案注释，因为随着提供方和渠道移出核心，插件所有权和配置覆盖范围可能会发生变化。

​
弃用政策

OpenClaw 不应在引入替代方案的同一版本中移除已文档化的插件契约。迁移顺序：
  1. 添加新契约。
  2. 通过命名的兼容性适配器保留旧行为。
  3. 当插件作者可以采取行动时，发出诊断或警告。
  4. 文档化替代方案和时间线。
  5. 测试旧路径和新路径。
  6. 等待已宣布的迁移窗口结束。
  7. 仅在获得明确的破坏性变更发布批准后才移除。
弃用记录必须包含警告开始日期、替代方案、文档链接，以及以下两者之一：不晚于警告开始后三个月的最终移除日期，或明确的版本边界，例如 next-plugin-sdk-major。除非维护者明确决定其为永久兼容性并将其标记为 active，否则不要添加具有无限期移除窗口的弃用兼容路径。

​
当前兼容性区域

2026 年 7 月的清理移除了已过期的根 SDK、manifest、provider、runtime、 registry-flag 和 plugin-owned web-config 别名。Doctor 迁移仍会单独跟踪， 因此受支持的升级路径仍然可以修复旧配置。 剩余的、带日期的兼容性区域包括：
  • 迁移指南中列出的 9 月 SDK 子路径窗口
  • api.on("subagent_spawning", ...) hook 别名
  • 特定于 memory 的 embedding 注册和 beta.5 session-store bridge
  • 下文所述的 WhatsApp 入站回调别名
  • 显式 channel target 解析和 openclaw/plugin-sdk/messaging-targets
  • 嵌入式 Pi agent 别名
  • 已随附的 agent-harness SDK 别名，其移除需等待新的、对外文档化的迁移决定
  • 下文列出的 2026 年 10 月 SDK 注解族
活跃的、无日期的 registry 记录涵盖受支持的行为，而不是待移除债务， 包括激活提示、插件捕获、捆绑插件启用以及生成的 channel-config 回退。 仅注解的兼容性审计新增了以下带日期的记录。其 removeAfter 日期表示最早的审查日期，而不是在其所述读取方或迁移条件 仍未满足时移除相关接口的许可。 pnpm plugins:boundary-report 会将 removal-pending 记录与 deprecated 记录分开报告。 某个到期的 removal-pending 记录在其报告的迁移条件满足且其读取方引用被清除之前， 仍会被阻止；现有的 --fail-on-eligible-compat gate 仍只适用于带日期的 deprecated 记录。读取方引用是用于分流的 surface-token 匹配；在批准移除之前， 请使用已发布构件扫描。

​
Channel prompt-context 标识符别名

新的 channel 插件应使用 MsgContext.ChannelPromptContext、 MsgContext.ChannelStructuredContext、ChannelStructuredContextEntry 和 SupplementalContextFacts.channelStructuredContext。较旧的 UntrustedContext、UntrustedStructuredContext、 UntrustedStructuredContextEntry 以及 supplemental untrustedContext 名称 仍作为已弃用的 SDK 别名保留至 2026-09-08（registry 记录 sdk-untrusted-context-identifier-aliases）。入站最终化会将这些已弃用字段 折叠到 channel 命名的字段中，并从 runtime context 中移除旧键。 安全 runtime 同样导出 buildChannelMetadata；已弃用的 buildUntrustedChannelMetadata 别名按相同时间表保留。

​
WhatsApp 入站回调扁平别名

WhatsApp runtime 回调会传递 WebInboundMessage：即规范的 嵌套 event、payload、quote、group 和 platform 上下文，以及 已弃用的、针对已发布回调字段的扁平别名。新的回调代码应读取嵌套上下文。 构造干净的嵌套回调消息的代码可以使用 WebInboundCallbackMessage；仍然注入 旧的扁平测试或插件消息的兼容监听器应使用 LegacyFlatWebInboundMessage 或 WebInboundMessageInput。 扁平别名会一直可用到 2026-08-30；该窗口仅适用于扁平别名访问，不适用于 嵌套形态，后者才是规范的 runtime 契约。每个扁平别名的 TypeScript @deprecated 注解都会写明其精确的嵌套替代项。常见示例如下：
  • id、timestamp 和 isBatched 移到 event 下。
  • body、mediaPath、mediaType、mediaFileName、mediaUrl、location 和 channelStructuredContext 移到 payload 下。
  • to、chatId、sender/self 字段、sendComposing、reply(...) 和 sendMedia(...) 移到 platform 下。
  • replyTo* 字段移到 quote 下；群组主题/参与者/提及字段移到 group 下。
payload.channelStructuredContext 会从入站 provider payload 中提取。 插件在将其 payload 视为权威数据之前，应检查 label、source 和 type。

​
WhatsApp 入站 admission 字段

被接受的 WhatsApp 回调消息会携带 admission，这是一个对外安全的信封， 用于承载接纳该消息的访问控制决策。新的回调代码应从 msg.admission 而不是旧的顶层 admission 字段读取 admission 事实。 顶层字段会一直可用到 2026-08-30。每个字段的 TypeScript @deprecated 注解都会写明替代项：
  • from 和 conversationId 移到 admission.conversation.id。
  • accountId 移到 admission.accountId。
  • accessControlPassed 是 admission.ingress.decision === "allow" 的派生兼容视图； 对于已经携带 admission 的消息，写入旧布尔值不会重写 ingress 图。
  • chatType 移到 admission.conversation.kind。

​
插件检查器包

插件检查器应位于核心 OpenClaw 仓库之外，作为一个独立的包／仓库存在，并依托版本化的兼容性与清单契约。第一天的 CLI 应为：
它应输出清单／Schema 验证、正在检查的契约兼容性版本、安装／源码元数据检查、冷路径导入检查，以及弃用／兼容性警告。使用 --json 以便在 CI 注释中获得稳定、可机器读取的输出。OpenClaw core 应公开检查器可以消费的契约和 fixtures，但不应从主 openclaw 包中发布检查器二进制。

​
维护者验收通道

在验证外部检查器与 OpenClaw 插件包的兼容性时，对可安装包验收通道使用基于 Crabbox 的 Blacksmith Testbox。包构建完成后，从一个干净的 OpenClaw 检出环境中运行：
请将此通道保持为维护者可选启用，因为它会安装一个外部 npm 包，并且可能检查仓库外克隆的插件包。本地仓库的防护覆盖 SDK 导出映射、兼容性注册表元数据、已弃用 SDK 导入的清理进度，以及打包扩展的导入边界；Testbox 检查器证明则覆盖外部插件作者实际消费它时的包行为。

​
发布说明

发布说明应包含即将到来的插件弃用信息，包括目标日期 以及迁移文档链接，且应在兼容性路径变为 removal-pending 或 removed 之前提供。