English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

快速开始

插件兼容性

Edit source

OpenClaw 会通过命名兼容性适配器保持旧版插件契约连通，然后再移除它们。这能在 SDK、清单、设置、配置和智能体运行时契约演进期间，保护现有的内置插件和外部插件。

兼容性注册表

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

每条记录包含：

  • 稳定的兼容性代码
  • 状态：active、deprecated、removal-pending 或 removed
  • 所有者：SDK、配置、设置、渠道、提供商、插件执行、智能体运行时或核心
  • 适用时的引入日期和弃用日期
  • 替代方案指导
  • 覆盖旧行为和新行为的文档、诊断和测试

该注册表是维护者规划和未来插件检查器检查的来源。如果面向插件的行为发生变化，请在添加适配器的同一次变更中添加或更新兼容性记录。

Doctor 修复和迁移兼容性在 src/commands/doctor/shared/deprecation-compat.ts 中单独跟踪。这些记录覆盖旧配置形态、安装台账布局，以及在运行时兼容路径移除后可能仍需保留可用的修复垫片。

发布扫查应同时检查两个注册表。不要仅仅因为匹配的运行时或配置兼容性记录已过期就删除 Doctor 迁移；请先确认没有仍需要该修复的受支持升级路径。还应在发布规划期间重新验证每条替代方案注释，因为随着提供商和渠道移出核心，插件所有权和配置覆盖面可能会变化。

插件检查器包

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

第一天的 CLI 应为：

sh
openclaw-plugin-inspector ./my-plugin

它应输出：

  • 清单/模式校验
  • 正在检查的契约兼容性版本
  • 安装/来源元数据检查
  • 冷路径导入检查
  • 弃用和兼容性警告

在 CI 注释中使用 --json 获取稳定的机器可读输出。OpenClaw 核心应公开检查器可使用的契约和 fixtures，但不应从主 openclaw 包发布检查器二进制文件。

维护者验收通道

在针对 OpenClaw 插件包验证外部检查器时，请使用由 Crabbox 支持的 Blacksmith Testbox 运行可安装包验收通道。包构建完成后，从干净的 OpenClaw checkout 中运行：

sh
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
  • 插件迁移到 register(api) 期间的旧版 activate(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 类型别名
  • 内置插件允许列表和启用行为
  • 旧版提供商/渠道环境变量清单元数据
  • 提供商迁移到显式 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 期间的旧版渠道路由键和可比较目标辅助函数别名
  • 正在由清单贡献所有权替代的激活提示
  • 设置描述符迁移到冷 setup.requiresRuntime: false 元数据期间的 setup-api 运行时回退
  • 提供商 catalog 钩子迁移到 catalog.run(...) 期间的提供商 discovery 钩子
  • 渠道包迁移到 openclaw.channel.exposure 期间的渠道 showConfigured / showInSetup 元数据
  • Doctor 将操作员迁移到 agentRuntime 期间的旧版运行时策略配置键
  • registry-first channelConfigs 元数据落地期间生成的内置渠道配置元数据回退
  • 修复流程将操作员迁移到 openclaw plugins registry --refresh 和 openclaw doctor --fix 期间，持久化插件注册表禁用和安装迁移环境标志
  • Doctor 将旧版插件所有的 Web 搜索、Web 获取和 x_search 配置路径迁移到 plugins.entries.<plugin>.config 期间的这些路径
  • 安装元数据迁移到由状态管理的插件台账期间，旧版 plugins.installs 作者配置和内置插件加载路径别名

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

发布说明

发布说明应包含即将到来的插件弃用项、目标日期以及迁移文档链接。该警告需要在兼容性路径移动到 removal-pending 或 removed 之前发生。

Was this useful?