OpenClaw使用兼容性适配器保留旧插件契约，避免直接移除导致插件失效。兼容性记录在src/plugins/compat/registry.ts，状态包括active、deprecated、removal-pending、removed；弃用策略要求同一发布版本不能同时移除旧契约，至少需经过三个月迁移窗口。插件维护者可使用openclaw-plugin-inspector检查兼容性警告，并参考注册表中的替换指引进行迁移。

OpenClaw插件兼容性配置：注册表、弃用策略与检查器

OpenClaw在移除旧插件契约之前，会通过命名兼容性适配器保持其可用。这样可以保护现有内置和外部插件，同时SDK、manifest、setup、config和智能体运行时契约继续演进。

兼容性注册表

插件兼容性契约记录在核心注册表文件 src/plugins/compat/registry.ts 中。

每条记录包含：

• 稳定的兼容性代码
• 状态：active、deprecated、removal-pending 或 removed
• 所有者：SDK、config、setup、channel、provider、插件执行、智能体运行时或核心
• 引入和弃用日期（如适用）
• 替换指引
• 覆盖新旧行为的文档、诊断和测试

注册表是维护者规划插件和未来插件检查器检查的依据。如果插件相关的行为发生变化，应在添加适配器的同一变更中新增或更新兼容性记录。

Doctor修复和迁移兼容性另外记录在 src/commands/doctor/shared/deprecation-compat.ts 中，覆盖旧配置格式、安装账本布局以及修复垫片，这些可能在运行时兼容性路径移除后仍需保留。

发布扫描应同时检查两个注册表。即使对应的运行时或配置兼容性记录过期，也不要直接删除doctor迁移，除非确认不存在仍需要该修复的升级路径。同时，在发布规划期间重新验证每个替换注释，因为提供商和渠道可能从核心移出，导致插件所有权和配置覆盖范围变化。

插件检查器包

插件检查器应作为独立包/仓库存在于OpenClaw核心仓库之外，并由版本化的兼容性和manifest契约支持。

初始化CLI命令为：

openclaw-plugin-inspector ./my-plugin

输出应包括：

• manifest/schema验证
• 正在检查的契约兼容性版本
• 安装/源元数据检查
• 冷路径导入检查
• 弃用和兼容性警告

使用 --json 参数生成稳定的机器可读输出，用于CI注释。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检查器验证则覆盖插件作者作为外部消费者实际使用的包。

弃用策略

OpenClaw不应在引入替代品的同一发布版本中移除已文档化的插件契约。

迁移顺序如下：

1. 添加新契约。
2. 通过命名兼容性适配器保留旧行为。
3. 当插件作者可以采取行动时发出诊断或警告。
4. 记录替代品和时间线。
5. 同时测试新旧路径。
6. 等待公告的迁移窗口。
7. 仅在有明确的破坏性发布批准时才能移除。

弃用记录必须包含警告开始日期、替代品、文档链接和最终移除日期，且最终移除日期不超过警告开始后的三个月。除非维护者明确决定该兼容性路径为永久并标记为 active，否则不要添加无截止日期的弃用兼容性路径。

当前兼容性领域

当前兼容性记录涵盖：

• 旧的宽泛SDK导入，如 openclaw/plugin-sdk/compat
• 旧的仅钩子插件形状和 before_agent_start
• 旧的 api.on("deactivate", ...) 清理钩子名称，插件迁移到 gateway_stop
• 旧的 activate(api) 插件入口点，插件迁移到 register(api)
• 旧的SDK别名，如 openclaw/extension-api、openclaw/plugin-sdk/channel-runtime、openclaw/plugin-sdk/command-auth 状态构建器、openclaw/plugin-sdk/test-utils（被聚焦的 openclaw/plugin-sdk/* 测试子路径替换）、以及 ClawdbotConfig / OpenClawSchemaType 类型别名
• 内置插件允许列表和启用行为
• 旧的提供商/渠道环境变量manifest元数据
• 旧的提供商插件钩子和类型别名，提供商迁移到显式catalog、auth、thinking、replay和transport钩子
• 旧运行时别名，如 api.runtime.taskFlow、api.runtime.subagent.getSession、api.runtime.stt、以及弃用的 api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...)
• 旧内存插件的拆分注册，迁移到 registerMemoryCapability
• 旧渠道SDK助手，用于原生消息模式、提及守卫、入站信封格式化和审批能力嵌套
• 旧渠道路由键和可比较目标助手别名，插件迁移到 openclaw/plugin-sdk/channel-route
• 激活提示，被manifest贡献所有权替换
• setup-api 运行时回退，设置描述符迁移到冷 setup.requiresRuntime: false 元数据
• 提供商 discovery 钩子，提供商catalog钩子迁移到 catalog.run(...)
• 渠道 showConfigured / showInSetup 元数据，渠道包迁移到 openclaw.channel.exposure
• 旧运行时策略配置键，doctor将操作员迁移到 agentRuntime
• 生成的内置渠道配置元数据回退，注册表优先的 channelConfigs 元数据落地
• 持久化插件注册表禁用和安装迁移环境标志，修复流程将操作员迁移到 openclaw plugins registry --refresh 和 openclaw doctor --fix
• 旧插件拥有的web搜索、web fetch和x_search配置路径，doctor将配置迁移到 plugins.entries.<plugin>.config
• 旧 plugins.installs 编写配置和内置插件加载路径别名，安装元数据移入状态管理的插件账本

新插件代码应优先使用注册表和具体迁移指南中列出的替换项。现有插件可以继续使用兼容性路径，直到文档、诊断和发布说明宣布移除窗口。

发布说明

发布说明应包含即将到来的插件弃用信息，附带目标日期和迁移文档链接。该警告需要在兼容性路径变为 removal-pending 或 removed 之前发出。

常见问题

看到插件兼容性警告怎么解决？

检查 src/plugins/compat/registry.ts 中对应兼容性代码的状态和替换指引。如果状态为 deprecated，按替换项迁移；如果为 removal-pending，尽快迁移，否则插件可能失效。运行 openclaw-plugin-inspector ./my-plugin --json 可获取具体警告。

如何检查我维护的插件是否兼容？

使用 openclaw-plugin-inspector 工具，传入插件目录并加 --json 参数，输出包含manifest验证、依赖注入检查、兼容性版本和弃用警告。也可在CI中通过Crabbox+Blacksmith Testbox集成运行验收测试。

弃用策略的时间窗口是多久？

从警告开始到最终移除不超过三个月。OpenClaw不会在引入替代品的同一发布版本中移除旧契约，必须等待公告的迁移窗口且获得破坏性发布批准才能移除。