插件兼容性
OpenClaw 在移除旧版插件契约之前,会先通过命名兼容性适配器保持这些契约可用。这可以在 SDK、manifest、setup、config 和 agent runtime 契约演进期间,保护现有的捆绑插件和外部插件。
所有插件 API 均为实验性。 插件作者应固定并测试受支持的 OpenClaw 宿主版本。此稳定性指定不会取消下文所述的现有弃用窗口、兼容性适配器或受支持升级迁移。
兼容性注册表¶
插件兼容性契约在核心注册表 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 中单独跟踪。这些记录涵盖旧配置形状、安装台账布局以及修复垫片,这些内容在运行时兼容性路径移除后可能仍需保持可用。
每个 Doctor 兼容性记录都声明 introduced 和 removeAfter。
当记录在 removeAfter 当天或之后仍为 deprecated 时,pnpm check:doctor-deprecation-registry 守卫会失败;维护者必须在受支持升级证明后将其移除,或将其移至 removal-pending 并记录阻塞原因。removal-pending 记录不会导致日期守卫失败,但会保留在显式审查队列中,直到其升级条件得到满足。
经维护者批准的 Doctor 截止日期续期会将原始日期保留为 previousRemoveAfter,将批准日期记录为 renewedAt,并设置一个新的 removeAfter,最迟不超过三个月后。续期仅改变审查时间;它不会改变运行时兼容性、配置处理、迁移行为或生命周期状态。2026 年 8 月 29 日,当前全部 44 条 Doctor 记录均续期至 2026 年 11 月 29 日。
发布清理应检查两个注册表。不要仅因为匹配的运行时或配置兼容性记录已过期就删除 Doctor 迁移;首先验证不存在仍需要该修复的受支持升级路径。在发布规划期间也要重新验证每个替代注释,因为随着 provider 和 channel 移出核心,插件所有权和配置占用可能会发生变化。
弃用策略¶
OpenClaw 不应在引入替代方案的同一发布中移除已记录的插件契约。迁移顺序:
- 添加新契约。
- 通过命名兼容性适配器保持旧行为可用。
- 在插件作者可以采取行动时发出诊断或警告。
- 记录替代方案和计划时间线。
- 测试旧路径和新路径。
- 等待已宣布的迁移窗口结束。
- 仅在获得明确的破坏性发布批准后移除。
已弃用记录必须包含警告开始日期、替代方案、文档链接,以及警告开始后不超过三个月的最终移除日期,或明确的版本边界(例如 next-plugin-sdk-major)。除非维护者明确决定其为永久兼容性并将其标记为 active,否则不要添加具有开放式移除窗口的已弃用兼容性路径。
当前兼容性领域¶
2026 年 7 月的清理移除了已过期的根 SDK、manifest、provider、runtime、registry-flag 和插件拥有的 web-config 别名。Doctor 迁移仍单独跟踪,以便受支持的升级路径仍能修复旧配置。
剩余的带日期兼容性领域包括:
- 迁移指南中列出的已续期 10 月 1 日 SDK 子路径窗口
- 已发布的 agent-harness SDK 别名,其移除正等待一项新的对外文档化迁移决定
- 下文列出的 2026 年 10 月 SDK 注释族
活动且无日期的注册表记录涵盖受支持的行为,而非移除债务,包括激活提示、插件捕获、捆绑插件启用以及生成的 channel-config 回退。
仅针对注释的兼容性审计添加了这些带日期的记录。它们的 removeAfter 日期是最早审查日期,而不是在其所述读取方或迁移条件仍未满足时移除某个接口面的许可。10 个 10 月 1 日的注释族现在为 removal-pending,原始日期以及下文按族列出的移除条件保留在审查队列中。这并不授权移除,也不声称已完成已发布读取方清理。
| 兼容性代码 | 移除条件 | removeAfter |
|---|---|---|
plugin-sdk-channel-setup-input-fields |
重复已发布插件产物清理,并仅移除没有读取方的字段。 | 2026-10-01 |
plugin-sdk-broad-runtime-barrels |
将捆绑和已索引的外部消费者迁移到聚焦的 SDK 子路径。 | 2026-10-01 |
plugin-sdk-provider-owned-helper-shims |
将每个已弃用的 provider 辅助函数迁移到其 provider 本地 API,并证明没有已发布读取方仍然存在。 | 2026-10-01 |
message-presentation-legacy-bridges |
将回复生产者和官方 channel 包迁移到 MessagePresentation。 |
2026-10-01 |
| 兼容性代码 | 移除条件 | removeAfter |
|---|---|---|
plugin-sdk-focused-compat-aliases |
证明每个列出的别名都没有捆绑或已发布的读取方。 | 2026-10-01 |
agent-harness-terminal-result-aliases |
将 harness 迁移到 terminal 和 visibleReplies,然后证明旧版结果字段未被读取。 |
2026-10-01 |
official-plugin-export-aliases |
将频道展示和 Discord 超时消费者迁移到规范 API,并清除已发布的读取方。 | 2026-10-01 |
memory-host-compatibility-aliases |
在退役覆盖项之前,验证规范内存表和保留的旧版数据。 | 2026-10-01 |
plugin-runtime-api-compat-aliases |
将扁平的插件注册/运行时调用迁移到其命名空间化或聚焦的替代项。 | 2026-10-01 |
plugin-provider-manifest-compat-aliases |
将 kind/setup/catalog 的所有权迁移到 manifest 和模型目录注册。 | 2026-10-01 |
plugin-sdk-session-agent-resolution-aliases |
将已发布插件迁移到严格的会话代理解析,并提供显式或已准备的所有者。 | 2026-11-29 |
pnpm plugins:boundary-report 会单独报告 removal-pending 记录,而不是与已弃用记录混在一起。已到期的 removal-pending 记录会保持阻塞状态,直到其报告的迁移条件得到满足,并且其读取方引用被清除;现有的 --fail-on-eligible-compat 门禁仍仅适用于带有日期的 deprecated 记录。读取方引用是用于分诊的表面令牌匹配;在授权移除之前,请使用已发布产物扫描。
已弃用的 sourceVisibleReplies harness 字段仍受支持,因为 2026 年 7 月的 @openclaw/codex 版本仍会生成该字段。在新插件中,请使用 deliveryDefaults.visibleReplies。终端结果别名也仍受支持,适用于已发布的生成方,包括 openclaw-deepseek-harness@0.2.0。
会话存储桥接退役¶
SDK 所有者已批准于 2026 年 9 月 30 日退役 deprecated-session-store-beta5-api,取代其原先 10 月 12 日的兼容性截止日期。受支持插件的截止点排除了 v2026.7.1-beta.5 以及任何其他导入了已退役的整个存储或转录路径桥接的插件版本。在升级宿主之前,请将这些插件升级到使用范围化行操作和基于身份的转录 API 的版本。
已发布的 @openclaw/codex@2026.9.7 和 @openclaw/feishu@2026.9.7 包已从已退役的导入中迁移出去。它们的 2026.7.1-beta.5 包仍在使用该桥接;仅凭更新的版本号并不能证明其他版本或插件已完成迁移。
openclaw/plugin-sdk/session-store-runtime 和 resolveStorePath(...) 仍受支持。已移除的导出、选项类型和包根别名列于会话 API 迁移指南。此次退役会改变受支持的 SDK 表面;规范 SQLite 存储以及旧版状态导入和 Doctor 迁移保持不变。
同步插件状态¶
plugin-state-sync-keyed-store 指代现有的同步键控存储适配器。其 2026 年 9 月 11 日的弃用使用 next-plugin-sdk-major 移除门禁,采用编辑器注释和文档,而不是新的运行时警告。现有的同步方法、插件信任资格和事务回调语义保持不变。请使用状态存储迁移指南迁移到可等待的 openKeyedStore 操作。移除仍需要受支持的外部插件迁移以及显式的破坏性版本发布批准。
会话代理解析别名¶
新插件应使用 resolveSessionAgentIdsStrict 或 resolveSessionAgentIdStrict,并提供显式代理、代理范围的会话密钥、已准备的回退代理,或持久化的固定存储所有者。
较旧的 resolveSessionAgentIds 和 resolveSessionAgentId Plugin SDK 导出仅在严格解析因未提供所有者而失败时,保留环境系统代理回退。这些别名将空或仅包含空白的代理 ID 视为省略;严格解析器会拒绝提供的空白 ID。它们不会覆盖显式、代理范围、持久化、冲突或已退役的所有者结果。这些别名自 2026 年 8 月 29 日起弃用,并将在 2026 年 11 月 29 日前保持可用。移除还需要已发布插件读取方扫描以及显式的破坏性版本发布批准。
身份验证配置冷却分类¶
AuthProfileStore.usageStats[*].cooldownReason 仍然是封闭的规范 AuthProfileFailureReason 联合类型。宿主策略将 WHAM HTTP 401 记录为 auth,将 HTTP 403 记录为 auth_permanent。
cooldownClassification 是可选的附加宿主诊断。其当前值为 wham_token_expired 和 wham_account_dead。显示此字段的插件必须为未来可选的分类保留默认值或回退值。规范故障转移使用 resolveProfilesUnavailableReason;该诊断仅为展示状态,绝不能用作授权。
频道提示上下文标识符别名¶
新的频道插件应使用 MsgContext.ChannelPromptContext、MsgContext.ChannelStructuredContext、ChannelStructuredContextEntry 和 SupplementalContextFacts.channelStructuredContext。较旧的 UntrustedContext、UntrustedStructuredContext、UntrustedStructuredContextEntry 以及补充 untrustedContext 名称仍作为已弃用的 SDK 别名保留。其 2026-09-08 移除审查日期保持不变,但注册表记录 sdk-untrusted-context-identifier-aliases 现在为 removal-pending:移除仍需要验证已发布插件读取方的迁移,以及显式的破坏性版本发布批准。入站最终化会将这些已弃用字段折叠到频道命名字段中,并从运行时上下文中移除旧键。
安全运行时同样导出 buildChannelMetadata;已弃用的
buildUntrustedChannelMetadata 别名在相同的待移除条件下仍可用。
WhatsApp 入站回调退役¶
2026 年 8 月的 WhatsApp 回调兼容窗口已关闭。运行时
回调现在仅接受 WebInboundCallbackMessage:嵌套的 event、
payload、quote、group 和 platform 上下文,以及必需的公共
admission 信封。扁平回调字段和顶层 admission 别名不再被接受。
payload.channelStructuredContext 从入站提供商负载中提取。
插件在将其 payload 视为权威数据之前,应检查 label、source 和 type。
插件检查器包¶
插件检查器应位于核心 OpenClaw 仓库之外,作为一个 独立的包/仓库,由版本化的兼容性和清单契约提供支持。初始 CLI 应为:
它应输出清单/模式验证、正在检查的契约兼容版本、安装/来源元数据检查、冷路径导入
检查,以及弃用/兼容性警告。在 CI 注释中,使用 --json 获取稳定的
机器可读输出。OpenClaw 核心应暴露检查器可消费的契约和测试夹具,但不应从主 openclaw 包发布检查器二进制文件。
维护者验收通道¶
在针对 OpenClaw 插件包验证外部检查器时,使用由 Crabbox 支持的 Blacksmith Testbox 作为可安装包验收通道。在包构建完成后,从干净的 OpenClaw 检出运行它:
pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "pnpm install && pnpm build && npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/telegram --json"
pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json"
pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- <clawhub-plugin-dir> --json"
由于该通道会安装外部 npm 包,并可能检查在仓库外克隆的插件包,因此应保持该通道对维护者为可选启用。本地仓库守卫覆盖 SDK 导出映射、兼容性注册表元数据、已弃用 SDK 导入的逐步清理,以及捆绑扩展的导入边界;Testbox 检查器证明覆盖外部插件作者消费该包时的情况。
发布说明¶
发布说明应包含即将弃用的插件及其目标日期,以及迁移文档链接,在兼容路径进入 removal-pending 或 removed 之前。
相关¶
已移除的表面、其替代项以及移除时间线。
兼容性记录可以弃用的清单字段。
安装、更新和检查已安装的插件。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw