> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # Совместимость 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 первого дня должен быть: ```sh theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw-plugin-inspector ./my-plugin ``` Он должен выводить: * проверку манифеста/схемы * версию совместимости контракта, которая проверяется * проверки метаданных установки/источника * проверки импорта холодного пути * предупреждения об устаревании и совместимости Используйте `--json` для стабильного машиночитаемого вывода в аннотациях CI. Ядро OpenClaw должно предоставлять контракты и фикстуры, которые инспектор может использовать, но не должно публиковать бинарный файл инспектора из основного пакета `openclaw`. ### Приемочный путь сопровождающих Используйте Blacksmith Testbox на базе Crabbox для приемочного пути устанавливаемого пакета при проверке внешнего инспектора на пакетах Plugin OpenClaw. Запускайте его из чистой рабочей копии OpenClaw после сборки пакета: ```sh theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 -- --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..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`.