Plugin maintainer reference

Сумісність Plugin

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 не повинен видаляти документований контракт плагіна в тому самому випуску, у якому впроваджується його заміна. Послідовність міграції:

Додайте новий контракт.
Збережіть стару поведінку через іменований адаптер сумісності.
Виводьте діагностичні повідомлення або попередження, коли автори плагінів можуть вжити заходів.
Задокументуйте заміну та часові межі.
Тестуйте як старий, так і новий шляхи.
Дочекайтеся завершення оголошеного періоду міграції.
Видаляйте лише з явним схваленням випуску з несумісними змінами.

Записи про застарівання мають містити дату початку попереджень, заміну, посилання на документацію та остаточну дату видалення не пізніше ніж через три місяці після початку попереджень. Не додавайте застарілий шлях сумісності з невизначеним періодом видалення, якщо супроводжувачі явно не вирішили, що це постійна сумісність, і натомість не позначили його як 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.

Was this useful?