概述
OpenClaw 通过命名兼容性适配器维护旧版插件契约，在 SDK、manifest、配置和 Agent 运行时契约演进过程中保护现有插件。
核心要点
兼容性注册表位置：
- 运行时兼容性：
src/plugins/compat/registry.ts - Doctor 修复/迁移兼容性：
src/commands/doctor/shared/deprecation-compat.ts
每条兼容性记录包含：
- 稳定的兼容性代码
- 状态：
active、deprecated、removal-pending、removed - 所有者：SDK/配置/设置/Channel/Provider/插件执行/Agent 运行时/核心
- 引入和废弃日期
- 替换指导、文档、诊断和测试
废弃策略（7步迁移序列）：
- 添加新契约
- 通过命名兼容性适配器保持旧行为
- 当插件作者可以行动时发出诊断/警告
- 记录替换和时间线
- 测试新旧两条路径
- 等待公告的迁移窗口
- 仅在明确的破坏性发布批准后删除
废弃记录要求：
- 必须包含警告开始日期、替换方案、文档链接
- 最终删除日期不超过警告开始后三个月
- 不得添加开放式删除窗口的废弃路径
当前兼容性领域（部分）：
- 旧版宽泛 SDK 导入（
openclaw/plugin-sdk/compat） - 旧版 hook-only 插件形状和
before_agent_start - 旧版
activate(api)入口点（迁移到register(api)） - 旧版 SDK 别名（
openclaw/extension-api、openclaw/plugin-sdk/channel-runtime等） - 旧版 Provider/Channel 环境变量 manifest 元数据
- 旧版运行时别名（
api.runtime.taskFlow、api.runtime.stt等） - 旧版内存插件分割注册
setup-api运行时回退（迁移到setup.requiresRuntime: false）
配置/使用
插件检查器 CLI（计划中）：
openclaw-plugin-inspector ./my-plugin
openclaw-plugin-inspector ./my-plugin --json # CI 用机器可读输出维护者验收通道：
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"相关页面
- concepts/plugin-architecture — 插件能力模型和兼容性立场
- concepts/plugin-manifest — Manifest 格式和废弃字段
- concepts/plugin-building — 新插件开发（使用当前 API）