Внутрішні компоненти Plugin

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

Публічна модель можливостей

Можливості — це публічна модель нативного Plugin-а всередині OpenClaw. Кожен нативний Plugin OpenClaw реєструється для одного або кількох типів можливостей:

Позиція щодо зовнішньої сумісності

Модель можливостей уже інтегрована в core і сьогодні використовується вбудованими/нативними Plugin-ами, але сумісність зовнішніх Plugin-ів досі потребує суворішої планки, ніж «це експортовано, отже це заморожено».

Реєстрація можливостей — це цільовий напрям. Застарілі hooks залишаються найбезпечнішим шляхом без поломок для зовнішніх Plugin-ів під час переходу. Експортовані допоміжні підшляхи не всі однакові — віддавайте перевагу вузьким задокументованим контрактам над випадковими допоміжними експортами.

Форми Plugin-ів

OpenClaw класифікує кожен завантажений Plugin за формою на основі його фактичної поведінки реєстрації (а не лише статичних метаданих):

Використовуйте openclaw plugins inspect <id>, щоб побачити форму Plugin-а та розбивку можливостей. Див. довідник CLI для деталей.

Застарілі hooks

Hook before_agent_start залишається підтримуваним як шлях сумісності для Plugin-ів лише з hooks. Застарілі реальні Plugin-и досі залежать від нього.

Напрям:

• підтримувати його працездатність
• документувати його як застарілий
• віддавати перевагу before_model_resolve для роботи з перевизначенням моделі/провайдера
• віддавати перевагу before_prompt_build для роботи зі зміною prompt
• видаляти лише після того, як реальне використання зменшиться, а покриття fixtures доведе безпечність міграції

Сигнали сумісності

Коли ви запускаєте openclaw doctor або openclaw plugins inspect <id>, ви можете побачити одну з цих міток:

Ані hook-only, ані before_agent_start сьогодні не зламають ваш Plugin: hook-only є рекомендаційним сигналом, а before_agent_start лише викликає попередження. Ці сигнали також з’являються в openclaw status --all і openclaw plugins doctor.

Огляд архітектури

Система Plugin-ів OpenClaw має чотири шари:

Саме для CLI Plugin-ів виявлення root-команд поділено на дві фази:

• metadata під час parsing надходять з registerCli(..., { descriptors: [...] })
• справжній модуль CLI Plugin-а може залишатися lazy та реєструватися під час першого виклику

Це утримує CLI-код, що належить Plugin-у, всередині Plugin-а, водночас даючи OpenClaw змогу резервувати імена root-команд до parsing.

Важлива межа дизайну:

• валідація manifest/config має працювати з metadata manifest/schema без виконання коду Plugin-а
• нативне виявлення можливостей може завантажувати trusted entry-код Plugin-а, щоб побудувати registry snapshot без активації
• нативна runtime-поведінка походить зі шляху register(api) модуля Plugin-а з api.registrationMode === "full"

Цей поділ дає OpenClaw змогу валідувати config, пояснювати відсутні/вимкнені Plugin-и та будувати підказки UI/schema до активації повного runtime.

Snapshot метаданих Plugin-а і lookup table

Під час запуску Gateway створює один PluginMetadataSnapshot для поточного snapshot config. Snapshot містить лише metadata: він зберігає installed plugin index, manifest registry, manifest diagnostics, owner maps, нормалізатор id Plugin-а та manifest records. Він не містить завантажених модулів Plugin-ів, SDK провайдерів, вмісту package або runtime exports.

Валідація config, що враховує Plugin-и, startup auto-enable і bootstrap Plugin-ів Gateway використовують цей snapshot замість незалежної перебудови metadata manifest/index. PluginLookUpTable виводиться з того самого snapshot і додає startup plugin plan для поточної runtime config.

Після запуску Gateway зберігає поточний metadata snapshot як замінний runtime-продукт. Повторне runtime-виявлення провайдерів може запозичувати цей snapshot замість реконструкції installed index і manifest registry для кожного provider-catalog pass. Snapshot очищується або замінюється під час shutdown Gateway, змін config/plugin inventory та записів installed index; callers повертаються до холодного шляху manifest/index, коли немає сумісного поточного snapshot. Перевірки сумісності мають включати корені виявлення Plugin-ів, такі як plugins.load.paths і default agent workspace, оскільки workspace Plugin-и є частиною metadata scope.

Snapshot і lookup table утримують повторювані startup-рішення на fast path:

• ownership каналів
• deferred channel startup
• startup plugin ids
• ownership провайдерів і backend CLI
• ownership setup provider, command alias, model catalog provider і manifest contract
• валідація plugin config schema і channel config schema
• startup auto-enable decisions

Межа безпеки — це заміна snapshot, а не mutation. Перебудовуйте snapshot, коли змінюються config, plugin inventory, install records або persisted index policy. Не трактуйте його як широкий mutable global registry і не зберігайте необмежені historical snapshots. Runtime-завантаження Plugin-ів залишається окремим від metadata snapshots, щоб stale runtime state не міг бути прихований за metadata cache.

Правило cache задокументовано в внутрішній архітектурі Plugin-ів: metadata manifest і discovery є fresh, якщо caller не тримає explicit snapshot, lookup table або manifest registry для поточного flow. Приховані metadata caches і wall-clock TTL не є частиною завантаження Plugin-ів. Лише caches runtime loader, module і dependency-artifact можуть зберігатися після фактичного завантаження коду або installed artifacts.

Деякі callers холодного шляху досі реконструюють manifest registries напряму з persisted installed plugin index замість отримання Gateway PluginLookUpTable. Цей шлях тепер реконструює registry on demand; віддавайте перевагу передаванню поточної lookup table або explicit manifest registry через runtime flows, коли caller уже має один із них.

Планування активації

Планування активації є частиною control plane. Callers можуть запитувати, які Plugin-и релевантні для конкретної команди, провайдера, каналу, route, agent harness або можливості, перш ніж завантажувати ширші runtime registries.

Planner зберігає сумісність поточної manifest-поведінки:

• поля activation.* є явними підказками планувальника
• providers, channels, commandAliases, setup.providers, contracts.tools і хуки залишаються резервним механізмом володіння маніфестом
• API планувальника лише з ids залишається доступним для наявних викликачів
• API плану повідомляє мітки причин, щоб діагностика могла відрізняти явні підказки від резервного механізму володіння

Канальні плагіни та спільний інструмент повідомлень

Канальним плагінам не потрібно реєструвати окремий інструмент надсилання/редагування/реакцій для звичайних дій чату. OpenClaw тримає один спільний інструмент message у ядрі, а канальні плагіни володіють специфічними для каналу виявленням і виконанням за ним.

Поточна межа така:

• ядро володіє хостом спільного інструмента message, підключенням до промпта, обліком сесій/тредів і диспетчеризацією виконання
• канальні плагіни володіють виявленням дій у межах області, виявленням можливостей і будь-якими специфічними для каналу фрагментами схеми
• канальні плагіни володіють специфічною для провайдера граматикою розмов сесії, наприклад тим, як id розмов кодують id тредів або успадковуються від батьківських розмов
• канальні плагіни виконують фінальну дію через свій адаптер дій

Для канальних плагінів поверхня SDK — це ChannelMessageActionAdapter.describeMessageTool(...). Цей уніфікований виклик виявлення дає плагіну змогу повертати видимі дії, можливості та внески до схеми разом, щоб ці частини не розходилися.

Коли специфічний для каналу параметр інструмента повідомлень несе джерело медіа, наприклад локальний шлях або URL віддаленого медіа, плагін також має повертати mediaSourceParams із describeMessageTool(...). Ядро використовує цей явний список, щоб застосовувати нормалізацію шляхів пісочниці та підказки вихідного доступу до медіа без жорсткого кодування назв параметрів, якими володіє плагін. Надавайте перевагу мапам у межах дії, а не одному пласкому списку на весь канал, щоб параметр медіа лише для профілю не нормалізувався для непов’язаних дій на кшталт send.

Ядро передає область виконання в цей крок виявлення. Важливі поля включають:

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• довірений вхідний requesterSenderId

Це важливо для контекстно-чутливих плагінів. Канал може приховувати або відкривати дії повідомлень на основі активного облікового запису, поточної кімнати/треду/повідомлення або довіреної ідентичності запитувача без жорсткого кодування специфічних для каналу гілок у ядрі інструмента message.

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

Для допоміжних засобів виконання, якими володіє канал, вбудовані плагіни мають тримати runtime виконання всередині власних модулів розширення. Ядро більше не володіє runtime дій повідомлень Discord, Slack, Telegram або WhatsApp під src/agents/tools. Ми не публікуємо окремі підшляхи plugin-sdk/*-action-runtime, а вбудовані плагіни мають імпортувати власний локальний runtime-код безпосередньо зі своїх модулів, якими володіє розширення.

Та сама межа загалом застосовується до названих за провайдером швів SDK: ядро не має імпортувати специфічні для каналу зручні барелі для Slack, Discord, Signal, WhatsApp або подібних розширень. Якщо ядру потрібна поведінка, воно має або споживати власний барель api.ts / runtime-api.ts вбудованого плагіна, або просунути потребу у вузьку загальну можливість у спільному SDK.

Вбудовані плагіни дотримуються того самого правила. runtime-api.ts вбудованого плагіна не має реекспортувати власний брендований фасад openclaw/plugin-sdk/<plugin-id>. Ці брендовані фасади залишаються shim-сумісністю для зовнішніх плагінів і старіших споживачів, але вбудовані плагіни мають використовувати локальні експорти плюс вузькі загальні підшляхи SDK, такі як openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/runtime-store або openclaw/plugin-sdk/webhook-ingress. Новий код не має додавати специфічні для plugin-id фасади SDK, якщо цього не вимагає межа сумісності для наявної зовнішньої екосистеми.

Зокрема для опитувань є два шляхи виконання:

• outbound.sendPoll — спільна базова лінія для каналів, що відповідають загальній моделі опитування
• actions.handleAction("poll") — бажаний шлях для специфічної для каналу семантики опитувань або додаткових параметрів опитування

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

Див. Внутрішня архітектура плагінів для повної послідовності запуску.

Модель володіння можливостями

OpenClaw розглядає нативний плагін як межу володіння для компанії або функції, а не як набір непов’язаних інтеграцій.

Це означає:

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

Бажаний кінцевий стан такий:

• OpenAI живе в одному плагіні, навіть якщо охоплює текстові моделі, мовлення, зображення та майбутнє відео
• інший постачальник може зробити те саме для власної поверхні
• каналам байдуже, який плагін постачальника володіє провайдером; вони споживають спільний контракт можливості, відкритий ядром

Ключова відмінність така:

• плагін = межа володіння
• можливість = контракт ядра, який кілька плагінів можуть реалізовувати або споживати

Тож якщо OpenClaw додає нову доменну область, наприклад відео, перше запитання не "який провайдер має жорстко закодувати обробку відео?" Перше запитання — "яким є контракт можливості відео в ядрі?" Коли цей контракт існує, плагіни постачальників можуть реєструватися відповідно до нього, а канальні/функціональні плагіни можуть його споживати.

Якщо можливості ще не існує, правильний крок зазвичай такий:

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

Шарування можливостей

Використовуйте цю ментальну модель, коли вирішуєте, де має бути код:

Наприклад, TTS дотримується такої форми:

• ядро володіє політикою TTS під час відповіді, порядком резервування, налаштуваннями та доставкою в канал
• openai, elevenlabs і microsoft володіють реалізаціями синтезу
• voice-call споживає runtime-помічник TTS для телефонії

Той самий шаблон варто надавати перевагу для майбутніх можливостей.

Приклад плагіна компанії з кількома можливостями

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

    describeImageWithModel,  transcribeOpenAiCompatibleAudio,} from "openclaw/plugin-sdk/media-understanding"; const plugin: OpenClawPluginDefinition = {  id: "exampleai",  name: "ExampleAI",  register(api) {    api.registerProvider({      id: "exampleai",      // auth/model catalog/runtime hooks    });     api.registerSpeechProvider({      id: "exampleai",      // vendor speech config — implement the SpeechProviderPlugin interface directly    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      async describeImage(req) {        return describeImageWithModel({          provider: "exampleai",          model: req.model,          input: req.input,        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          provider: "exampleai",          model: req.model,          input: req.input,        });      },    });     api.registerWebSearchProvider(      createPluginBackedWebSearchProvider({        id: "exampleai-search",        // credential + fetch logic      }),    );  },}; export default plugin;

Важливі не точні назви помічників. Важлива форма:

• один плагін володіє поверхнею постачальника
• ядро все ще володіє контрактами можливостей
• канали та функціональні плагіни споживають помічники api.runtime.*, а не код постачальника
• контрактні тести можуть перевіряти, що плагін зареєстрував можливості, якими заявляє, що володіє

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

OpenClaw уже розглядає розуміння зображень/аудіо/відео як одну спільну можливість. Та сама модель володіння застосовується і там:

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

Генерація відео вже використовує ту саму послідовність: ядро володіє типізованим контрактом можливості та runtime-помічником, а плагіни постачальників реєструють реалізації api.registerVideoGenerationProvider(...) відповідно до нього.

Потрібен конкретний контрольний список розгортання? Див. Кулінарну книгу можливостей.

Контракти та примусове забезпечення

Поверхня API плагінів навмисно типізована й централізована в OpenClawPluginApi. Цей контракт визначає підтримувані точки реєстрації та runtime-помічники, на які може покладатися плагін.

Чому це важливо:

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

Є два шари примусового забезпечення:

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

Що має входити до контракту

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

Модель виконання

Нативні плагіни OpenClaw працюють у процесі разом із Gateway. Вони не ізольовані в пісочниці. Завантажений нативний плагін має ту саму межу довіри на рівні процесу, що й код ядра.

Сумісні пакети безпечніші за замовчуванням, бо OpenClaw наразі розглядає їх як пакети метаданих/контенту. У поточних релізах це здебільшого означає вбудовані Skills.

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

Для назв вбудованих пакетів робочої області тримайте ідентифікатор плагіна прив'язаним до npm-назви: @openclaw/<id> за замовчуванням або схвалений типізований суфікс, як-от -provider, -plugin, -speech, -sandbox чи -media-understanding, коли пакет навмисно надає вужчу роль плагіна.

Межа експорту

OpenClaw експортує можливості, а не зручності реалізації.

Залишайте реєстрацію можливостей публічною. Скорочуйте експорти допоміжних засобів, що не є контрактами:

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

Зарезервовані допоміжні підшляхи вбудованих плагінів вилучено зі згенерованої карти експорту SDK. Тримайте специфічні для власника допоміжні засоби всередині пакета плагіна-власника; просувайте лише повторно використовувану поведінку хоста до загальних контрактів SDK, таких як plugin-sdk/gateway-runtime, plugin-sdk/security-runtime і plugin-sdk/plugin-config-runtime.

Внутрішні механізми й довідка

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

Пов'язане

• Створення плагінів
• Маніфест Plugin
• Налаштування SDK Plugin