---
read_when:
    - Ви підтримуєте OpenClaw Plugin
    - Ви бачите попередження про сумісність Plugin
    - Ви плануєте міграцію SDK Plugin або маніфесту
summary: Контракти сумісності Plugin, метадані про застарівання та очікування щодо міграції
title: Сумісність Plugin
x-i18n:
    generated_at: "2026-04-28T11:18:59Z"
    model: gpt-5.5
    provider: openai
    source_hash: 344dbaac86db7259adc09bc91b7fbe7ba540fc6fdd96cc422918ccf2c34d9cec
    source_path: plugins/compatibility.md
    workflow: 16
---

OpenClaw зберігає старіші контракти plugin підключеними через іменовані адаптери сумісності перед їх видаленням. Це захищає наявні вбудовані та зовнішні plugins, поки контракти SDK, маніфесту, налаштування, конфігурації та runtime агентів еволюціонують.

## Реєстр сумісності

Контракти сумісності plugin відстежуються в основному реєстрі за адресою
`src/plugins/compat/registry.ts`.

Кожен запис має:

- стабільний код сумісності
- статус: `active`, `deprecated`, `removal-pending` або `removed`
- власник: SDK, конфігурація, налаштування, канал, провайдер, виконання plugin, runtime агента
  або ядро
- дати впровадження та застарівання, коли застосовно
- рекомендації щодо заміни
- документація, діагностика та тести, які охоплюють стару й нову поведінку

Реєстр є джерелом для планування супроводу та майбутніх перевірок інспектора plugin. Якщо поведінка, видима для plugin, змінюється, додайте або оновіть запис сумісності в тій самій зміні, яка додає адаптер.

Сумісність виправлень Doctor і міграцій відстежується окремо за адресою
`src/commands/doctor/shared/deprecation-compat.ts`. Ці записи охоплюють старі форми конфігурації, макети журналу встановлень і допоміжні модулі виправлення, які можуть потребувати збереження доступності після видалення runtime-шляху сумісності.

Релізні перевірки мають перевіряти обидва реєстри. Не видаляйте міграцію Doctor лише тому, що відповідний runtime-запис або запис сумісності конфігурації завершився; спочатку перевірте, що немає підтримуваного шляху оновлення, якому все ще потрібне виправлення. Також повторно перевіряйте кожну анотацію заміни під час планування релізу, оскільки володіння plugin і конфігураційний footprint можуть змінюватися, коли провайдери та канали переміщуються з ядра.

## Пакет інспектора plugin

Інспектор plugin має жити поза основним репозиторієм OpenClaw як окремий пакет/репозиторій, що спирається на версіоновані контракти сумісності та маніфесту.

CLI першого дня має бути:

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

Він має виводити:

- перевірку маніфесту/схеми
- версію сумісності контракту, що перевіряється
- перевірки метаданих встановлення/джерела
- перевірки імпортів холодного шляху
- попередження про застарівання та сумісність

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

### Смуга приймання для супровідників

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

```sh
blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
blacksmith testbox run --id <tbx_id> "pnpm install && pnpm build && npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/telegram --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- <clawhub-plugin-dir> --json"
blacksmith testbox stop <tbx_id>
```

Залишайте цю смугу opt-in для супровідників, оскільки вона встановлює зовнішній npm-пакет і може перевіряти пакети plugin, клоновані поза репозиторієм. Локальні захисти репозиторію охоплюють мапу експорту SDK, метадані реєстру сумісності, скорочення застарілих імпортів SDK і межі імпортів вбудованих extensions; доказ інспектора в Testbox охоплює пакет так, як його споживають автори зовнішніх plugin.

## Політика застарівання

OpenClaw не має видаляти задокументований контракт plugin у тому самому релізі, який вводить його заміну.

Послідовність міграції:

1. Додайте новий контракт.
2. Залиште стару поведінку підключеною через іменований адаптер сумісності.
3. Виводьте діагностику або попередження, коли автори plugin можуть діяти.
4. Задокументуйте заміну та timeline.
5. Тестуйте старий і новий шляхи.
6. Зачекайте протягом оголошеного вікна міграції.
7. Видаляйте лише з явним схваленням breaking-релізу.

Застарілі записи мають містити дату початку попереджень, заміну, посилання на документацію та фінальну дату видалення не пізніше ніж через три місяці після початку попереджень. Не додавайте застарілий шлях сумісності з відкритим вікном видалення, якщо супровідники явно не вирішили, що це постійна сумісність, і не позначили його як `active`.

## Поточні області сумісності

Поточні записи сумісності включають:

- застарілі широкі імпорти SDK, такі як `openclaw/plugin-sdk/compat`
- застарілі форми plugin лише з хуками та `before_agent_start`
- застарілі entrypoints plugin `activate(api)`, поки plugins мігрують на
  `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`
- allowlist вбудованих plugin і поведінку ввімкнення
- застарілі метадані маніфесту env-var провайдерів/каналів
- застарілі хуки plugin провайдерів і псевдоніми типів, поки провайдери переходять на
  явні хуки каталогу, авторизації, thinking, replay і транспорту
- застарілі runtime-псевдоніми, такі як `api.runtime.taskFlow`,
  `api.runtime.subagent.getSession`, `api.runtime.stt` і застарілі
  `api.runtime.config.loadConfig()` / `api.runtime.config.writeConfigFile(...)`
- застарілу розділену реєстрацію memory-plugin, поки memory plugins переходять на
  `registerMemoryCapability`
- застарілі допоміжні модулі SDK каналу для нативних схем повідомлень, mention gating,
  форматування вхідного envelope і вкладення approval capability
- застарілі псевдоніми ключа маршруту каналу та helper для comparable-target, поки plugins
  переходять на `openclaw/plugin-sdk/channel-route`
- activation hints, які замінюються володінням внесками маніфесту
- застаріле неявне завантаження sidecar під час старту для plugins, які не оголосили
  `activation.onStartup`; супровідники можуть тестувати майбутню суворішу поведінку з
  `OPENCLAW_DISABLE_LEGACY_IMPLICIT_STARTUP_SIDECARS=1`
- runtime fallback `setup-api`, поки дескриптори налаштування переходять на холодні
  метадані `setup.requiresRuntime: false`
- хуки `discovery` провайдера, поки хуки каталогу провайдера переходять на
  `catalog.run(...)`
- метадані каналу `showConfigured` / `showInSetup`, поки пакети каналів переходять
  на `openclaw.channel.exposure`
- застарілі ключі конфігурації runtime-policy, поки Doctor мігрує операторів на
  `agentRuntime`
- fallback згенерованих метаданих конфігурації вбудованого каналу, поки впроваджуються registry-first
  метадані `channelConfigs`
- збережені env-прапорці вимкнення реєстру plugin і install-migration, поки
  потоки виправлення мігрують операторів на `openclaw plugins registry --refresh` і
  `openclaw doctor --fix`
- застарілі шляхи конфігурації вебпошуку, web fetch і x_search, якими володіє plugin, поки
  Doctor мігрує їх до `plugins.entries.<plugin>.config`
- застарілу створену автором конфігурацію `plugins.installs` і псевдоніми load-path вбудованих plugin,
  поки метадані встановлення переходять у керований станом журнал plugin

Новий код plugin має надавати перевагу заміні, зазначеній у реєстрі та в конкретному посібнику з міграції. Наявні plugins можуть продовжувати використовувати шлях сумісності, доки документація, діагностика та примітки до релізу не оголосять вікно видалення.

## Примітки до релізу

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