Внутрішня будова Plugin

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

Загальнодоступна модель можливостей

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

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

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

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

Форми плагінів

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

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

Застарілі перехоплювачі

Перехоплювач before_agent_start залишається підтримуваним шляхом сумісності для плагінів лише з перехоплювачами. Реальні застарілі плагіни досі залежать від нього.

Напрям:

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

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

openclaw doctor, openclaw plugins inspect <id>, openclaw status --all і openclaw plugins doctor відображають такі сповіщення про сумісність:

Жоден із рекомендаційних сигналів або попереджень наразі не порушує роботу вашого плагіна. Ці сигнали також відображаються в openclaw status --all і openclaw plugins doctor.

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

Система плагінів OpenClaw складається з чотирьох рівнів:

Зокрема для CLI плагінів виявлення кореневих команд розділено на два етапи:

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

Завдяки цьому код CLI, що належить плагіну, залишається всередині плагіна, а OpenClaw усе одно може зарезервувати назви кореневих команд до початку аналізу.

Важлива межа проєктування:

• перевірка маніфесту й конфігурації має працювати на основі метаданих маніфесту та схеми без виконання коду плагіна
• виявлення нативних можливостей може завантажувати код точки входу довіреного плагіна, щоб створити неактивувальний знімок реєстру
• нативна поведінка під час виконання походить зі шляху register(api) модуля плагіна, коли api.registrationMode === "full"

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

Знімок метаданих плагінів і таблиця пошуку

Під час запуску Gateway створює один PluginMetadataSnapshot для поточного знімка конфігурації. Цей знімок містить лише метадані: індекс установлених плагінів, реєстр маніфестів, діагностичні дані маніфестів, карти власників, нормалізатор ідентифікаторів плагінів і записи маніфестів. Він не містить завантажених модулів плагінів, SDK провайдерів, вмісту пакетів або експортів середовища виконання.

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

Після запуску Gateway зберігає поточний знімок метаданих як замінний продукт середовища виконання. Повторне виявлення провайдерів під час виконання може використовувати цей знімок замість повторного створення індексу встановлених компонентів і реєстру маніфестів для кожного проходу каталогу провайдерів. Знімок очищається або замінюється під час завершення роботи Gateway, зміни конфігурації чи переліку плагінів, а також запису індексу встановлених компонентів; якщо сумісного поточного знімка немає, виклики повертаються до холодного шляху маніфесту й індексу. Перевірки сумісності мають охоплювати корені виявлення плагінів, як-от plugins.load.paths і типовий робочий простір агента, оскільки плагіни робочого простору входять до області метаданих.

Знімок і таблиця пошуку зберігають повторювані рішення під час запуску на швидкому шляху:

• володіння каналами
• відкладений запуск каналів
• ідентифікатори плагінів запуску
• володіння провайдерами та серверами CLI
• володіння провайдером налаштування, псевдонімами команд, провайдером каталогу моделей і контрактами маніфестів
• перевірка схеми конфігурації плагінів і схеми конфігурації каналів
• рішення щодо автоматичного ввімкнення під час запуску

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

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

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

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

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

Планувальник зберігає сумісність із поточною поведінкою маніфесту:

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

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

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

Поточна межа відповідальності:

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

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

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

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

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

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

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

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

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

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

Безпосередньо для опитувань існують два шляхи виконання:

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

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

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

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

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

Це означає:

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

Очікуваний кінцевий стан:

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

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

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

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

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

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

Рівні можливостей

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

Наприклад, TTS відповідає цій структурі:

• ядро відповідає за політику TTS під час відповіді, порядок резервування, налаштування та доставлення каналом
• elevenlabs, google, microsoft і openai відповідають за реалізації синтезу
• voice-call використовує допоміжний засіб середовища виконання 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({          ...req,          provider: "exampleai",        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          ...req,          provider: "exampleai",        });      },    });     api.registerWebSearchProvider(      createPluginBackedWebSearchProvider({        id: "exampleai-search",        // credential + fetch logic      }),    );  },}; export default plugin;

Важливі не точні назви допоміжних засобів, а структура:

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

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

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

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

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

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

Контракти та забезпечення дотримання

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

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

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

Існує два рівні забезпечення дотримання:

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

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

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

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

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

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

Пов’язані матеріали

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