--- read_when: - Створення або налагодження нативних Plugin OpenClaw - Розуміння моделі можливостей Plugin або меж відповідальності - Робота над конвеєром завантаження Plugin або реєстром - Реалізація хуків середовища виконання провайдера або Plugin-ів каналів sidebarTitle: Internals summary: 'Внутрішня будова Plugin: модель можливостей, володіння, контракти, конвеєр завантаження та runtime-помічники' title: Внутрішні компоненти Plugin x-i18n: generated_at: "2026-06-27T17:48:49Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 0e36f77594f16d7f03e31be81a241a15fb15c0b160f22a4dce863f6da184dfe3 source_path: plugins/architecture.md workflow: 16 --- Це **поглиблений довідник з архітектури** системи Plugin в OpenClaw. Для практичних посібників почніть з однієї зі спеціалізованих сторінок нижче. Посібник для кінцевих користувачів із додавання, увімкнення та усунення проблем із Plugin-ами. Навчальний матеріал для першого Plugin-а з найменшим робочим маніфестом. Створіть Plugin каналу обміну повідомленнями. Створіть Plugin провайдера моделі. Довідник з карти імпортів і API реєстрації. ## Публічна модель можливостей Можливості — це публічна модель **нативного Plugin-а** всередині OpenClaw. Кожен нативний Plugin OpenClaw реєструється для одного або кількох типів можливостей: | Можливість | Метод реєстрації | Приклади Plugin-ів | | ---------------------- | ------------------------------------------------ | ------------------------------------ | | Текстовий інференс | `api.registerProvider(...)` | `openai`, `anthropic` | | Backend інференсу CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | | Embeddings | `api.registerEmbeddingProvider(...)` | Plugin-и векторів, що належать провайдерам | | Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | | Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | | Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` | | Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | | Джерело транскриптів | `api.registerTranscriptSourceProvider(...)` | `discord` | | Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | | Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | | Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | | Web fetch | `api.registerWebFetchProvider(...)` | `firecrawl` | | Web search | `api.registerWebSearchProvider(...)` | `google` | | Канал / обмін повідомленнями | `api.registerChannel(...)` | `msteams`, `matrix` | | Виявлення Gateway | `api.registerGatewayDiscoveryService(...)` | `bonjour` | Plugin, який реєструє нуль можливостей, але надає hooks, інструменти, служби виявлення або фонові служби, є **застарілим Plugin-ом лише з hooks**. Цей шаблон досі повністю підтримується. ### Позиція щодо зовнішньої сумісності Модель можливостей уже інтегрована в core і сьогодні використовується вбудованими/нативними Plugin-ами, але сумісність зовнішніх Plugin-ів досі потребує суворішої планки, ніж «це експортовано, отже це заморожено». | Ситуація з Plugin-ом | Рекомендації | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | Наявні зовнішні Plugin-и | Зберігайте працездатність інтеграцій на основі hooks; це базова лінія сумісності. | | Нові вбудовані/нативні Plugin-и | Віддавайте перевагу явній реєстрації можливостей замість vendor-specific reach-ins або нових дизайнів лише на hooks. | | Зовнішні Plugin-и, що впроваджують реєстрацію можливостей | Дозволено, але вважайте допоміжні поверхні, специфічні для можливостей, такими, що розвиваються, якщо документація не позначає їх стабільними. | Реєстрація можливостей — це цільовий напрям. Застарілі hooks залишаються найбезпечнішим шляхом без поломок для зовнішніх Plugin-ів під час переходу. Експортовані допоміжні підшляхи не всі однакові — віддавайте перевагу вузьким задокументованим контрактам над випадковими допоміжними експортами. ### Форми Plugin-ів OpenClaw класифікує кожен завантажений Plugin за формою на основі його фактичної поведінки реєстрації (а не лише статичних метаданих): Реєструє рівно один тип можливості (наприклад, Plugin лише провайдера, як `mistral`). Реєструє кілька типів можливостей (наприклад, `openai` володіє текстовим інференсом, мовленням, розумінням медіа та генерацією зображень). Реєструє лише hooks (типізовані або custom), без можливостей, інструментів, команд чи служб. Реєструє інструменти, команди, служби або routes, але без можливостей. Використовуйте `openclaw plugins inspect `, щоб побачити форму Plugin-а та розбивку можливостей. Див. [довідник CLI](/uk/cli/plugins#inspect) для деталей. ### Застарілі hooks Hook `before_agent_start` залишається підтримуваним як шлях сумісності для Plugin-ів лише з hooks. Застарілі реальні Plugin-и досі залежать від нього. Напрям: - підтримувати його працездатність - документувати його як застарілий - віддавати перевагу `before_model_resolve` для роботи з перевизначенням моделі/провайдера - віддавати перевагу `before_prompt_build` для роботи зі зміною prompt - видаляти лише після того, як реальне використання зменшиться, а покриття fixtures доведе безпечність міграції ### Сигнали сумісності Коли ви запускаєте `openclaw doctor` або `openclaw plugins inspect `, ви можете побачити одну з цих міток: | Сигнал | Значення | | -------------------------- | ------------------------------------------------------------ | | **config valid** | Config коректно розбирається, а Plugin-и resolve | | **compatibility advisory** | Plugin використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) | | **legacy warning** | Plugin використовує `before_agent_start`, який є deprecated | | **hard error** | Config недійсний або Plugin не вдалося завантажити | Ані `hook-only`, ані `before_agent_start` сьогодні не зламають ваш Plugin: `hook-only` є рекомендаційним сигналом, а `before_agent_start` лише викликає попередження. Ці сигнали також з’являються в `openclaw status --all` і `openclaw plugins doctor`. ## Огляд архітектури Система Plugin-ів OpenClaw має чотири шари: OpenClaw знаходить кандидатні Plugin-и з налаштованих шляхів, коренів workspace, глобальних коренів Plugin-ів і вбудованих Plugin-ів. Виявлення спочатку читає нативні маніфести `openclaw.plugin.json` плюс підтримувані bundle-маніфести. Core вирішує, чи виявлений Plugin увімкнений, вимкнений, заблокований або вибраний для ексклюзивного slot, наприклад memory. Нативні Plugin-и OpenClaw завантажуються в процесі та реєструють можливості в центральному registry. Упакований JavaScript завантажується через нативний `require`; сторонній локальний TypeScript source є аварійним fallback Jiti. Сумісні bundles нормалізуються в записи registry без імпорту runtime-коду. Решта OpenClaw читає registry, щоб надавати інструменти, канали, налаштування провайдерів, hooks, HTTP routes, команди CLI та служби. Саме для 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-ів](/uk/plugins/architecture-internals#plugin-cache-boundary): 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 плану повідомляє мітки причин, щоб діагностика могла відрізняти явні підказки від резервного механізму володіння Не розглядайте `activation` як хук життєвого циклу або заміну для `register(...)`. Це метадані, які використовуються для звуження завантаження. Надавайте перевагу полям володіння, коли вони вже описують зв’язок; використовуйте `activation` лише для додаткових підказок планувальника. ### Канальні плагіни та спільний інструмент повідомлень Канальним плагінам не потрібно реєструвати окремий інструмент надсилання/редагування/реакцій для звичайних дій чату. 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/`. Ці брендовані фасади залишаються 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")` — бажаний шлях для специфічної для каналу семантики опитувань або додаткових параметрів опитування Тепер ядро відкладає спільний парсинг опитування до моменту, коли диспетчеризація опитування плагіна відхилить дію, тож обробники опитувань, якими володіє плагін, можуть приймати специфічні для каналу поля опитування без попереднього блокування загальним парсером опитувань. Див. [Внутрішня архітектура плагінів](/uk/plugins/architecture-internals) для повної послідовності запуску. ## Модель володіння можливостями OpenClaw розглядає нативний плагін як межу володіння для **компанії** або **функції**, а не як набір непов’язаних інтеграцій. Це означає: - плагін компанії зазвичай має володіти всіма поверхнями цієї компанії, зверненими до OpenClaw - плагін функції зазвичай має володіти повною поверхнею функції, яку він вводить - канали мають споживати спільні можливості ядра замість спеціально повторно реалізовувати поведінку провайдера `openai` володіє текстовим інференсом, мовленням, голосом у реальному часі, розумінням медіа та генерацією зображень. `google` володіє текстовим інференсом плюс розумінням медіа, генерацією зображень і вебпошуком. `qwen` володіє текстовим інференсом плюс розумінням медіа та генерацією відео. `elevenlabs` і `microsoft` володіють мовленням; `firecrawl` володіє web-fetch; `minimax` / `mistral` / `moonshot` / `zai` володіють бекендами розуміння медіа. `voice-call` володіє транспортом дзвінків, інструментами, CLI, маршрутами та мостом медіапотоків Twilio, але споживає спільні можливості мовлення, транскрипції в реальному часі та голосу в реальному часі замість прямого імпорту плагінів постачальників. Бажаний кінцевий стан такий: - OpenAI живе в одному плагіні, навіть якщо охоплює текстові моделі, мовлення, зображення та майбутнє відео - інший постачальник може зробити те саме для власної поверхні - каналам байдуже, який плагін постачальника володіє провайдером; вони споживають спільний контракт можливості, відкритий ядром Ключова відмінність така: - **плагін** = межа володіння - **можливість** = контракт ядра, який кілька плагінів можуть реалізовувати або споживати Тож якщо OpenClaw додає нову доменну область, наприклад відео, перше запитання не "який провайдер має жорстко закодувати обробку відео?" Перше запитання — "яким є контракт можливості відео в ядрі?" Коли цей контракт існує, плагіни постачальників можуть реєструватися відповідно до нього, а канальні/функціональні плагіни можуть його споживати. Якщо можливості ще не існує, правильний крок зазвичай такий: Визначте відсутню можливість у ядрі. Відкрийте її через API/runtime плагіна типізованим способом. Підключіть канали/функції до цієї можливості. Дайте плагінам постачальників реєструвати реалізації. Це зберігає явне володіння, уникаючи поведінки ядра, яка залежить від одного постачальника або одноразового специфічного для плагіна шляху коду. ### Шарування можливостей Використовуйте цю ментальну модель, коли вирішуєте, де має бути код: Спільна оркестрація, політика, резервний механізм, правила злиття конфігурації, семантика доставки та типізовані контракти. Специфічні для постачальника API, автентифікація, каталоги моделей, синтез мовлення, генерація зображень, майбутні відеобекенди, кінцеві точки використання. Інтеграція Slack/Discord/voice-call/etc., яка споживає можливості ядра й представляє їх на поверхні. Наприклад, TTS дотримується такої форми: - ядро володіє політикою TTS під час відповіді, порядком резервування, налаштуваннями та доставкою в канал - `openai`, `elevenlabs` і `microsoft` володіють реалізаціями синтезу - `voice-call` споживає runtime-помічник TTS для телефонії Той самий шаблон варто надавати перевагу для майбутніх можливостей. ### Приклад плагіна компанії з кількома можливостями Плагін компанії має сприйматися цілісним ззовні. Якщо OpenClaw має спільні контракти для моделей, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації відео, отримання вебданих і вебпошуку, постачальник може володіти всіма своїми поверхнями в одному місці: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; import { 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 уже розглядає розуміння зображень/аудіо/відео як одну спільну можливість. Та сама модель володіння застосовується і там: Ядро визначає контракт розуміння медіа. Плагіни постачальників реєструють `describeImage`, `transcribeAudio` і `describeVideo`, коли застосовно. Канали та функціональні плагіни споживають спільну поведінку ядра замість прямого підключення до коду постачальника. Це уникає вбудовування припущень одного провайдера щодо відео в ядро. Плагін володіє поверхнею постачальника; ядро володіє контрактом можливості та резервною поведінкою. Генерація відео вже використовує ту саму послідовність: ядро володіє типізованим контрактом можливості та runtime-помічником, а плагіни постачальників реєструють реалізації `api.registerVideoGenerationProvider(...)` відповідно до нього. Потрібен конкретний контрольний список розгортання? Див. [Кулінарну книгу можливостей](/uk/plugins/adding-capabilities). ## Контракти та примусове забезпечення Поверхня API плагінів навмисно типізована й централізована в `OpenClawPluginApi`. Цей контракт визначає підтримувані точки реєстрації та runtime-помічники, на які може покладатися плагін. Чому це важливо: - автори плагінів отримують один стабільний внутрішній стандарт - ядро може відхиляти дубльоване володіння, наприклад два плагіни, що реєструють той самий id провайдера - запуск може показувати діагностику з діями для неправильних реєстрацій - контрактні тести можуть забезпечувати володіння вбудованих плагінів і запобігати тихому розходженню Є два шари примусового забезпечення: Реєстр плагінів перевіряє реєстрації під час завантаження плагінів. Приклади: дублікати ідентифікаторів провайдерів, дублікати ідентифікаторів мовленнєвих провайдерів і неправильно сформовані реєстрації створюють діагностику плагінів замість невизначеної поведінки. Вбудовані плагіни фіксуються в контрактних реєстрах під час тестових запусків, щоб OpenClaw міг явно перевіряти власність. Сьогодні це використовується для провайдерів моделей, мовленнєвих провайдерів, провайдерів вебпошуку та власності на вбудовані реєстрації. Практичний ефект полягає в тому, що OpenClaw заздалегідь знає, який плагін володіє якою поверхнею. Це дає ядру й каналам змогу безшовно компонуватися, бо власність оголошена, типізована й тестована, а не неявна. ### Що має входити до контракту - типізовані - малі - специфічні для можливості - належать ядру - повторно використовуються кількома плагінами - споживаються каналами/функціями без знання постачальника - специфічна для постачальника політика, прихована в ядрі - одноразові обхідні механізми плагінів, які обходять реєстр - код каналу, що звертається прямо до реалізації постачальника - спеціальні об'єкти часу виконання, які не є частиною `OpenClawPluginApi` або `api.runtime` Коли маєте сумнів, піднімайте рівень абстракції: спершу визначте можливість, а потім дозвольте плагінам підключатися до неї. ## Модель виконання Нативні плагіни OpenClaw працюють **у процесі** разом із Gateway. Вони не ізольовані в пісочниці. Завантажений нативний плагін має ту саму межу довіри на рівні процесу, що й код ядра. Наслідки нативного плагіна: плагін може реєструвати інструменти, мережеві обробники, хуки та сервіси; помилка в плагіні може аварійно завершити або дестабілізувати gateway; а зловмисний нативний плагін еквівалентний виконанню довільного коду всередині процесу OpenClaw. Сумісні пакети безпечніші за замовчуванням, бо OpenClaw наразі розглядає їх як пакети метаданих/контенту. У поточних релізах це здебільшого означає вбудовані Skills. Використовуйте списки дозволених і явні шляхи встановлення/завантаження для невбудованих плагінів. Розглядайте плагіни робочої області як код для часу розробки, а не як продукційні значення за замовчуванням. Для назв вбудованих пакетів робочої області тримайте ідентифікатор плагіна прив'язаним до npm-назви: `@openclaw/` за замовчуванням або схвалений типізований суфікс, як-от `-provider`, `-plugin`, `-speech`, `-sandbox` чи `-media-understanding`, коли пакет навмисно надає вужчу роль плагіна. **Примітка щодо довіри:** `plugins.allow` довіряє **ідентифікаторам плагінів**, а не походженню джерела. Плагін робочої області з тим самим ідентифікатором, що й вбудований плагін, навмисно заміщує вбудовану копію, коли цей плагін робочої області ввімкнено/додано до списку дозволених. Це нормально й корисно для локальної розробки, тестування патчів і термінових виправлень. Довіра до вбудованого плагіна визначається зі знімка джерела — маніфесту й коду на диску під час завантаження, — а не з метаданих встановлення. Пошкоджений або підмінений запис встановлення не може непомітно розширити поверхню довіри вбудованого плагіна понад те, що заявляє фактичне джерело. ## Межа експорту OpenClaw експортує можливості, а не зручності реалізації. Залишайте реєстрацію можливостей публічною. Скорочуйте експорти допоміжних засобів, що не є контрактами: - допоміжні підшляхи, специфічні для вбудованого плагіна - підшляхи інфраструктури часу виконання, не призначені як публічний API - зручні допоміжні засоби, специфічні для постачальника - допоміжні засоби налаштування/онбордингу, які є деталями реалізації Зарезервовані допоміжні підшляхи вбудованих плагінів вилучено зі згенерованої карти експорту SDK. Тримайте специфічні для власника допоміжні засоби всередині пакета плагіна-власника; просувайте лише повторно використовувану поведінку хоста до загальних контрактів SDK, таких як `plugin-sdk/gateway-runtime`, `plugin-sdk/security-runtime` і `plugin-sdk/plugin-config-runtime`. ## Внутрішні механізми й довідка Про конвеєр завантаження, модель реєстру, хуки часу виконання провайдерів, HTTP-маршрути Gateway, схеми інструментів повідомлень, визначення цілей каналів, каталоги провайдерів, плагіни рушія контексту та посібник із додавання нової можливості див. [внутрішні механізми архітектури Plugin](/uk/plugins/architecture-internals). ## Пов'язане - [Створення плагінів](/uk/plugins/building-plugins) - [Маніфест Plugin](/uk/plugins/manifest) - [Налаштування SDK Plugin](/uk/plugins/sdk-setup)