Перейти до основного вмісту
OpenClaw підтримує старіші контракти plugins підключеними через іменовані адаптери сумісності перед їх видаленням. Це захищає наявні вбудовані й зовнішні plugins, поки контракти 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.

​
Канал приймання супровідником

Використовуйте Crabbox-backed Blacksmith Testbox для каналу приймання встановлюваного пакета під час перевірки зовнішнього інспектора з пакетами plugins OpenClaw. Запускайте його з чистого checkout 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 і може інспектувати пакети plugins, клоновані поза репозиторієм. Локальні запобіжники репозиторію охоплюють мапу експорту SDK, метадані реєстру сумісності, скорочення застарілих SDK-імпортів і межі імпорту вбудованих extensions; proof інспектора Testbox охоплює пакет так, як його споживають автори зовнішніх plugins.

​
Політика виведення з ужитку

OpenClaw не має видаляти задокументований контракт plugin у тому самому релізі, який запроваджує його заміну. Послідовність міграції така:
  1. Додайте новий контракт.
  2. Залиште стару поведінку підключеною через іменований адаптер сумісності.
  3. Виводьте діагностику або попередження, коли автори plugins можуть діяти.
  4. Задокументуйте заміну та графік.
  5. Протестуйте і старий, і новий шляхи.
  6. Дочекайтеся оголошеного вікна міграції.
  7. Видаляйте лише з явним схваленням breaking-release.
Застарілі записи мають містити дату початку попереджень, заміну, посилання на документацію та фінальну дату видалення не пізніше ніж через три місяці після початку попереджень. Не додавайте застарілий шлях сумісності з відкритим вікном видалення, якщо супровідники явно не вирішили, що це постійна сумісність, і не позначили його як active натомість.

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

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

​
Плоскі псевдоніми вхідного callback WhatsApp

Callbacks середовища виконання WhatsApp доставляють WebInboundMessage: канонічні вкладені контексти event, payload, quote, group і platform плюс застарілі плоскі псевдоніми для доставлених полів callback. Новий код callback має читати вкладені контексти. Код, який створює чисті вкладені повідомлення callback, може використовувати WebInboundCallbackMessage; слухачі сумісності, які все ще інжектують старі плоскі тестові повідомлення або повідомлення plugin, мають використовувати LegacyFlatWebInboundMessage або WebInboundMessageInput. Плоскі псевдоніми залишаються доступними до 2026-08-30. Це вікно видалення застосовується лише до доступу через плоскі псевдоніми; вкладена форма callback є канонічним контрактом середовища виконання. Анотації 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 витягується з вхідних payloads провайдера. Plugins мають перевіряти label, source і type, перш ніж вважати його payload авторитетним.

​
Поля допуску вхідних повідомлень WhatsApp

Прийняті повідомлення callback WhatsApp тепер містять admission, публічно безпечну оболонку для рішення контролю доступу, яке допустило повідомлення. Новий код callback має читати факти допуску з msg.admission замість старіших полів допуску верхнього рівня. Поля верхнього рівня залишаються доступними до 2026-08-30. Анотації TypeScript @deprecated називають кожну заміну:
  • from і conversationId переходять до admission.conversation.id.
  • accountId переходить до admission.accountId.
  • accessControlPassed є похідним сумісним представленням admission.ingress.decision === "allow"; у повідомленнях, які вже містять admission, запис старого булевого значення не переписує граф ingress.
  • chatType переходить до admission.conversation.kind.

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

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