English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Plugins

Сумісність Plugin

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

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

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

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

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

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

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

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

Пакет інспектора плагінів

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

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

openclaw-plugin-inspector ./my-plugin

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

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

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

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

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

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/[email protected] -- ./extensions/telegram --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/[email protected] -- ./extensions/discord --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/[email protected] -- <clawhub-plugin-dir> --json"
blacksmith testbox stop <tbx_id>

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

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

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

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

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

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

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

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

  • старі широкі імпорти SDK, як-от openclaw/plugin-sdk/compat
  • старі форми плагінів лише з hooks і before_agent_start
  • старі точки входу плагінів 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
  • allowlist вбудованих плагінів і поведінку ввімкнення
  • старі метадані маніфесту env-var для провайдерів/каналів
  • старі hooks плагінів провайдерів і псевдоніми типів, поки провайдери переходять на явні hooks каталогу, автентифікації, thinking, replay і транспорту
  • старі псевдоніми середовища виконання, як-от api.runtime.taskFlow, api.runtime.subagent.getSession, api.runtime.stt і застарілі api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...)
  • стару розділену реєстрацію memory-плагінів, поки memory-плагіни переходять на registerMemoryCapability
  • старі допоміжні засоби SDK каналів для нативних схем повідомлень, обмеження mentions, форматування вхідного конверта та вкладення можливостей схвалення
  • старий ключ маршруту каналу та псевдоніми допоміжних засобів comparable-target, поки плагіни переходять на openclaw/plugin-sdk/channel-route
  • підказки активації, які замінюються власністю внесків маніфесту
  • fallback середовища виконання setup-api, поки дескриптори налаштування переходять на холодні метадані setup.requiresRuntime: false
  • hooks discovery провайдерів, поки hooks каталогу провайдерів переходять на catalog.run(...)
  • метадані каналів showConfigured / showInSetup, поки пакети каналів переходять на openclaw.channel.exposure
  • старі ключі конфігурації runtime-policy, поки Doctor мігрує операторів на agentRuntime
  • fallback згенерованих метаданих конфігурації вбудованих каналів, поки з’являються registry-first метадані channelConfigs
  • збережені env-прапори вимкнення реєстру плагінів і міграції встановлень, поки потоки виправлення мігрують операторів на openclaw plugins registry --refresh і openclaw doctor --fix
  • старі шляхи конфігурації вебпошуку, веботримання та x_search, що належать плагінам, поки Doctor мігрує їх у plugins.entries.<plugin>.config
  • старі авторські конфігурації plugins.installs і псевдоніми шляхів завантаження вбудованих плагінів, поки метадані встановлення переміщуються в керований станом журнал плагінів

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

Нотатки до релізу

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