---
read_when:
    - Ви супроводжуєте Plugin OpenClaw
    - Ви бачите попередження про сумісність плагіна
    - Ви плануєте міграцію SDK або маніфесту плагіна
summary: Контракти сумісності Plugin, метадані припинення підтримки та вимоги до міграції
title: Сумісність Plugin
x-i18n:
    generated_at: "2026-07-12T13:31:27Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 26f737e40175652cb24327c91d2af9dbf72b1b254011115f5b512a309707711c
    source_path: plugins/compatibility.md
    workflow: 16
---

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 має виглядати так:

```sh
openclaw-plugin-inspector ./my-plugin
```

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

### Приймальний контур для супроводжувачів

Використовуйте Blacksmith Testbox на базі Crabbox для приймального контуру
встановлюваного пакета під час перевірки зовнішнього інспектора на пакетах
плагінів OpenClaw. Запускайте його з чистої робочої копії OpenClaw після
збирання пакета:

```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 охоплює пакет так, як його використовують автори зовнішніх плагінів.

## Примітки до випуску

Примітки до випуску мають містити майбутні застарівання плагінів із
цільовими датами й посиланнями на документацію з міграції до того, як шлях
сумісності перейде до стану `removal-pending` або `removed`.
