Совместимость плагинов

OpenClaw сохраняет подключение старых контрактов плагинов через именованные адаптеры совместимости до их удаления. Это защищает существующие встроенные и внешние плагины по мере развития контрактов SDK, манифеста, настройки, конфигурации и среды выполнения агента.

Реестр совместимости

Контракты совместимости плагинов отслеживаются в основном реестре по адресу src/plugins/compat/registry.ts. Каждая запись содержит:

• стабильный код совместимости
• статус: active, deprecated, removal-pending или removed
• владелец: sdk, config, setup, channel, provider, plugin-execution, agent-runtime или core
• даты введения и объявления устаревшим, если применимо
• рекомендации по замене
• документацию, диагностику и тесты, охватывающие старое и новое поведение

Реестр служит источником данных для планирования сопровождающими и будущих проверок инспектором плагинов. Если поведение, доступное плагинам, изменяется, добавьте или обновите запись совместимости в том же изменении, которое добавляет адаптер.

Совместимость исправлений и миграций doctor отслеживается отдельно по адресу src/commands/doctor/shared/deprecation-compat.ts. Эти записи охватывают старые формы конфигурации, структуры журнала установок и адаптеры исправления, которые, возможно, потребуется сохранять после удаления пути совместимости среды выполнения.

При проверке релиза следует проверять оба реестра. Не удаляйте миграцию doctor только потому, что истёк срок соответствующей записи совместимости среды выполнения или конфигурации; сначала убедитесь, что не осталось поддерживаемого пути обновления, которому всё ещё требуется это исправление. Во время планирования релиза также повторно проверяйте каждую аннотацию замены, поскольку владение плагинами и объём конфигурации могут меняться по мере переноса провайдеров и каналов из ядра.

Политика объявления устаревшим

OpenClaw не должен удалять документированный контракт плагина в том же релизе, в котором представлена его замена. Последовательность миграции:

1. Добавьте новый контракт.
2. Сохраните старое поведение через именованный адаптер совместимости.
3. Выводите диагностические сообщения или предупреждения, когда авторы плагинов могут принять меры.
4. Документируйте замену и сроки.
5. Тестируйте как старый, так и новый пути.
6. Дождитесь окончания объявленного окна миграции.
7. Удаляйте только с явным одобрением релиза с несовместимыми изменениями.

Записи, объявленные устаревшими, должны включать дату начала предупреждений, замену, ссылку на документацию и окончательную дату удаления не позднее чем через три месяца после начала предупреждений. Не добавляйте устаревший путь совместимости с неопределённым окном удаления, если только сопровождающие явно не решили, что это постоянная совместимость, и не пометили его как active.

Текущие области совместимости

В настоящее время реестр отслеживает около 70 кодов совместимости в следующих областях. Новый код плагинов должен использовать замену в каждой области и соответствующем руководстве по миграции; существующие плагины могут продолжать использовать путь совместимости, пока документация, диагностика и примечания к релизу не объявят окно удаления.

• устаревшие широкие импорты 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
• список разрешённых встроенных плагинов и поведение их включения
• устаревшие метаданные переменных среды провайдера/канала в манифесте
• устаревшие хуки плагинов провайдеров и псевдонимы типов, пока провайдеры переходят на явные хуки каталога, аутентификации, рассуждения, повторного воспроизведения и транспорта
• устаревшие псевдонимы среды выполнения, такие как api.runtime.taskFlow, api.runtime.subagent.getSession, api.runtime.stt, а также устаревшие api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...)
• плоские поля обратного вызова WhatsApp WebInboundMessage (см. ниже)
• поля допуска верхнего уровня WhatsApp WebInboundMessage (см. ниже)
• устаревшая раздельная регистрация плагинов памяти, пока плагины памяти переходят на registerMemoryCapability
• устаревшая регистрация провайдеров векторных представлений, специфичная для памяти, пока такие провайдеры переходят на api.registerEmbeddingProvider(...) и contracts.embeddingProviders
• устаревшие вспомогательные средства SDK каналов для собственных схем сообщений, фильтрации упоминаний, форматирования входящего конверта и вложенной структуры возможностей подтверждения
• устаревшие псевдонимы ключа маршрута канала и вспомогательного средства сопоставимых целей, пока плагины переходят на openclaw/plugin-sdk/channel-route
• подсказки активации, заменяемые владением вкладами манифеста
• резервный механизм среды выполнения setup-api, пока дескрипторы настройки переходят на статические метаданные setup.requiresRuntime: false
• хуки провайдера discovery, пока хуки каталога провайдеров переходят на catalog.run(...)
• метаданные канала showConfigured / showInSetup, пока пакеты каналов переходят на openclaw.channel.exposure
• устаревшие ключи конфигурации политики среды выполнения, пока doctor переносит операторов на agentRuntime
• резервный механизм сгенерированных метаданных конфигурации встроенных каналов, пока внедряются ориентированные на реестр метаданные channelConfigs
• сохраняемые флаги среды отключения реестра плагинов и миграции установок, пока процессы исправления переносят операторов на openclaw plugins registry --refresh и openclaw doctor --fix
• устаревшие принадлежащие плагинам пути конфигурации веб-поиска, получения данных из интернета и x_search, пока doctor переносит их в plugins.entries.<plugin>.config
• устаревшая созданная конфигурация plugins.installs и псевдонимы путей загрузки встроенных плагинов, пока метаданные установки перемещаются в управляемый состоянием журнал плагинов

Плоские псевдонимы входящих обратных вызовов WhatsApp

Обратные вызовы среды выполнения WhatsApp передают WebInboundMessage: канонические вложенные контексты event, payload, quote, group и platform, а также устаревшие плоские псевдонимы поставляемых полей обратного вызова. Новый код обратных вызовов должен читать вложенные контексты. Код, создающий сообщения обратного вызова с чистой вложенной структурой, может использовать WebInboundCallbackMessage; слушатели совместимости, которые всё ещё внедряют старые плоские тестовые сообщения или сообщения плагинов, должны использовать LegacyFlatWebInboundMessage или WebInboundMessageInput.

Плоские псевдонимы остаются доступными до 2026-08-30; это окно относится только к доступу через плоские псевдонимы, но не к вложенной структуре, которая является каноническим контрактом среды выполнения. Аннотация TypeScript @deprecated каждого плоского псевдонима указывает его точную вложенную замену. Распространённые примеры:

• id, timestamp и isBatched перемещаются в event.
• body, mediaPath, mediaType, mediaFileName, mediaUrl, location и untrustedStructuredContext перемещаются в payload.
• to, chatId, поля отправителя/самого пользователя, sendComposing, reply(...) и sendMedia(...) перемещаются в platform.
• поля replyTo* перемещаются в quote; поля темы группы, участника и упоминания перемещаются в group.

payload.untrustedStructuredContext извлекается из входящих полезных данных провайдера. Плагины должны проверять label, source и type, прежде чем считать значение payload достоверным.

Поля допуска входящих сообщений WhatsApp

Принятые сообщения обратного вызова WhatsApp содержат admission — безопасный для публичного использования конверт решения контроля доступа, на основании которого сообщение было допущено. Новый код обратных вызовов должен читать сведения о допуске из msg.admission вместо старых полей допуска верхнего уровня.

Поля верхнего уровня остаются доступными до 2026-08-30. Аннотация TypeScript @deprecated каждого поля указывает его замену:

• from и conversationId перемещаются в admission.conversation.id.
• accountId перемещается в admission.accountId.
• accessControlPassed — это производное представление совместимости для admission.ingress.decision === "allow"; в сообщениях, уже содержащих admission, запись устаревшего логического значения не изменяет граф поступления.
• chatType перемещается в admission.conversation.kind.

Пакет инспектора плагинов

Инспектор плагинов должен находиться вне основного репозитория OpenClaw как отдельный пакет/репозиторий, основанный на версионируемых контрактах совместимости и манифеста. CLI первого выпуска должен выглядеть так:

openclaw-plugin-inspector ./my-plugin

Он должен выводить результаты проверки манифеста/схемы, проверяемую версию совместимости контрактов, проверки метаданных установки/источника, проверки импорта холодного пути и предупреждения об устаревании/совместимости. Используйте --json для стабильного машиночитаемого вывода в аннотациях CI. Ядро OpenClaw должно предоставлять контракты и фикстуры, которые может использовать инспектор, но не должно публиковать исполняемый файл инспектора из основного пакета openclaw.

Приёмочный контур для сопровождающих

Используйте Blacksmith Testbox на базе Crabbox для контура приёмки устанавливаемого пакета при проверке внешнего инспектора на пакетах плагинов OpenClaw. Запускайте его из чистой рабочей копии 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.