Совместимость Plugin

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

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

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

Каждая запись содержит:

• стабильный код совместимости
• статус: active, deprecated, removal-pending или removed
• владелец: SDK, конфигурация, настройка, канал, провайдер, выполнение Plugin, среда выполнения агента или ядро
• даты введения и устаревания, когда применимо
• рекомендации по замене
• документацию, диагностику и тесты, покрывающие старое и новое поведение

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

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

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

Пакет инспектора Plugin

Инспектор Plugin должен жить вне основного репозитория OpenClaw как отдельный пакет/репозиторий, опирающийся на версионированные контракты совместимости и манифеста.

CLI первого дня должен быть:

openclaw-plugin-inspector ./my-plugin

Он должен выводить:

• проверку манифеста/схемы
• версию совместимости контракта, которая проверяется
• проверки метаданных установки/источника
• проверки импорта холодного пути
• предупреждения об устаревании и совместимости

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

Приемочный путь сопровождающих

Используйте Blacksmith Testbox на базе Crabbox для приемочного пути устанавливаемого пакета при проверке внешнего инспектора на пакетах Plugin 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-пакет и может проверять пакеты Plugin, клонированные вне репозитория. Локальные защитные проверки репозитория покрывают карту экспортов SDK, метаданные реестра совместимости, сокращение устаревших импортов SDK и границы импортов встроенных расширений; доказательство инспектора в Testbox покрывает пакет так, как его используют внешние авторы Plugin.

Политика устаревания

OpenClaw не должен удалять документированный контракт Plugin в том же релизе, который вводит его замену.

Последовательность миграции:

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

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

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

Текущие записи совместимости включают:

• старые широкие импорты SDK, такие как openclaw/plugin-sdk/compat
• старые формы Plugin только с хуками и before_agent_start
• старые имена cleanup-хуков api.on("deactivate", ...), пока Plugin переходят на gateway_stop
• старые точки входа Plugin activate(api), пока Plugin переходят на 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
• поведение списка разрешенных встроенных Plugin и их включения
• старая manifest-метадата env-var для провайдеров/каналов
• старые хуки Plugin провайдеров и псевдонимы типов, пока провайдеры переходят на явные хуки каталога, аутентификации, thinking, replay и транспорта
• старые псевдонимы среды выполнения, такие как api.runtime.taskFlow, api.runtime.subagent.getSession, api.runtime.stt, а также устаревшие api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...)
• плоские поля обратного вызова WhatsApp WebInboundMessage, такие как body, chatId, reply(...) и mediaPath, пока потребители обратных вызовов переходят на вложенные контексты WebInboundCallbackMessage event, payload, quote, group и platform
• поля допуска верхнего уровня WhatsApp WebInboundMessage, такие как from, conversationId, accountId, accessControlPassed и chatType, пока потребители обратных вызовов переходят на оболочку admission
• старая раздельная регистрация memory-plugin, пока Plugin памяти переходят на registerMemoryCapability
• старая регистрация embedding-провайдера, специфичная для памяти, пока embedding-провайдеры переходят на api.registerEmbeddingProvider(...) и contracts.embeddingProviders
• старые помощники SDK канала для нативных схем сообщений, ограничения упоминаний, форматирования входящей оболочки и вложенности возможностей approval
• старый ключ маршрута канала и псевдонимы помощников comparable-target, пока Plugin переходят на openclaw/plugin-sdk/channel-route
• подсказки активации, которые заменяются владением вкладом в манифесте
• fallback среды выполнения setup-api, пока дескрипторы настройки переходят на холодную метадату setup.requiresRuntime: false
• хуки провайдера discovery, пока хуки каталога провайдера переходят на catalog.run(...)
• метадата канала showConfigured / showInSetup, пока пакеты каналов переходят на openclaw.channel.exposure
• старые конфигурационные ключи runtime-policy, пока doctor мигрирует операторов на agentRuntime
• fallback сгенерированной метадаты конфигурации встроенного канала, пока внедряется metadata channelConfigs с приоритетом реестра
• сохраненные env-флаги отключения реестра Plugin и миграции установок, пока потоки исправления мигрируют операторов на openclaw plugins registry --refresh и openclaw doctor --fix
• старые пути конфигурации web search, web fetch и x_search, принадлежащие Plugin, пока doctor мигрирует их в plugins.entries.<plugin>.config
• старая авторская конфигурация plugins.installs и псевдонимы путей загрузки встроенных Plugin, пока метаданные установки перемещаются в управляемый состоянием журнал Plugin

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

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

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

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

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

payload.untrustedStructuredContext извлекается из входящих payload провайдера. Plugin должны проверять 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, запись старого boolean не переписывает граф ingress.
• chatType перемещается в admission.conversation.kind.

Заметки к релизу

Заметки к релизу должны включать предстоящие устаревания Plugin с целевыми датами и ссылками на документацию по миграции. Это предупреждение должно появиться до того, как путь совместимости перейдет в removal-pending или removed.