Skip to main content
Довідка щодо пакування плагінів (метаданих package.json), маніфестів (openclaw.plugin.json), точок входу для налаштування та схем конфігурації.
Шукаєте покрокову інструкцію? Практичні посібники розглядають пакування в контексті: плагіни каналів і плагіни провайдерів.

Метадані пакета

Ваш package.json має містити поле openclaw, яке повідомляє системі плагінів, що надає ваш плагін:
Для зовнішньої публікації в ClawHub потрібні compat і build. Канонічні фрагменти для публікації містяться в docs/snippets/plugin-publish/.

Поля openclaw

string[]
Файли точок входу (відносно кореня пакета). Допустимі початкові файли для розробки в робочому просторі та вивіреній копії git.
string[]
Зібрані відповідники JavaScript для extensions, яким надається перевага, коли OpenClaw завантажує встановлений пакет npm. Порядок визначення початкових і зібраних файлів див. у розділі Точки входу SDK.
string
Полегшена точка входу лише для налаштування (необов’язкова).
string
Зібраний відповідник JavaScript для setupEntry. Потребує також заданого setupEntry.
object
Резервна ідентичність плагіна { id, label }, яка використовується, коли плагін не має метаданих каналу або провайдера, з яких можна отримати ідентифікатор чи мітку.
object
Метадані каталогу каналів для налаштування, засобу вибору, швидкого запуску та представлень стану.
object
Підказки щодо встановлення: npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery, requiredPlatformPackages.
object
Прапорці поведінки під час запуску.
object
Діапазон версій pluginApi, які підтримує цей плагін. Обов’язковий для зовнішніх публікацій у ClawHub.
Ідентифікатори провайдерів (providers: string[]) — це метадані маніфесту, а не пакета. Оголошуйте їх у openclaw.plugin.json, а не тут — див. Маніфест плагіна.

openclaw.channel

openclaw.channel — це легкі метадані пакета для виявлення каналів і представлень налаштування до завантаження середовища виконання. Приклад:
exposure підтримує:
  • configured: включати канал до представлень списків налаштованих каналів і стану
  • setup: включати канал до інтерактивних засобів вибору налаштування та конфігурації
  • docs: позначати канал як загальнодоступний у представленнях документації та навігації
showConfigured і showInSetup надалі підтримуються як застарілі псевдоніми. Надавайте перевагу exposure.

openclaw.install

openclaw.install — це метадані пакета, а не маніфесту.
Інтерактивне початкове налаштування використовує openclaw.install у представленнях встановлення на вимогу: якщо ваш плагін надає варіанти автентифікації провайдера або метадані налаштування чи каталогу каналів до завантаження середовища виконання, початкове налаштування може запропонувати встановлення з ClawHub, npm або локального джерела, установити чи ввімкнути плагін, а потім продовжити вибраний процес. Варіанти ClawHub використовують clawhubSpec, і їм надається перевага за наявності; для варіантів npm потрібні довірені метадані каталогу зі значенням npmSpec реєстру (точні версії та expectedIntegrity є необов’язковими закріпленнями, які застосовуються під час встановлення або оновлення, якщо їх задано). Зберігайте відомості про те, «що показувати», у openclaw.plugin.json, а про те, «як це встановити», — у package.json.
Якщо задано minHostVersion, його вимоги застосовуються як під час встановлення, так і під час завантаження реєстру маніфестів невбудованих плагінів. Старіші хости пропускають зовнішні плагіни; некоректні рядки версій відхиляються. Вважається, що версія вбудованих плагінів із початкового коду збігається з версією вивіреної копії хоста.
Для встановлень npm із закріпленою версією зберігайте точну версію в npmSpec і додайте очікувану цілісність артефакту:
allowInvalidConfigRecovery не є загальним способом обійти пошкоджені конфігурації. Воно призначене лише для вузького відновлення вбудованого плагіна, даючи повторному встановленню або налаштуванню змогу виправити відомі залишки оновлення, як-от відсутній шлях до вбудованого плагіна або застарілий запис channels.<id> для того самого плагіна. Якщо конфігурацію пошкоджено з непов’язаних причин, встановлення все одно завершується безпечною відмовою та повідомляє оператору запустити openclaw doctor --fix.

Відкладене повне завантаження

Плагіни каналів можуть увімкнути відкладене завантаження за допомогою:
Коли цей параметр увімкнено, OpenClaw завантажує лише setupEntry під час етапу запуску до початку прослуховування, навіть для вже налаштованих каналів. Повна точка входу завантажується після того, як Gateway починає прослуховування.
Вмикайте відкладене завантаження, лише якщо ваш setupEntry реєструє все, що потрібно Gateway до початку прослуховування (реєстрацію каналу, маршрути HTTP, методи Gateway). Якщо повна точка входу відповідає за обов’язкові можливості запуску, збережіть типову поведінку.
Якщо ваша точка входу для налаштування або повна точка входу реєструє методи RPC Gateway, використовуйте для них префікс, специфічний для плагіна. Зарезервовані основні адміністративні простори імен (config.*, exec.approvals.*, wizard.*, update.*) залишаються у власності ядра та завжди нормалізуються до operator.admin.

Маніфест плагіна

Кожен нативний Plugin повинен постачати файл openclaw.plugin.json у корені пакета. OpenClaw використовує його для перевірки конфігурації без виконання коду Plugin.
Для Plugin каналів додайте channels (а для Plugin постачальників — providers):
Навіть Plugin без конфігурації повинні постачати схему. Порожня схема є допустимою:
Повний довідник зі схеми див. у розділі Маніфест Plugin.

Публікація в ClawHub

Пакети Skills і Plugin використовують окремі команди публікації в ClawHub. Для пакетів Plugin використовуйте спеціальну команду для пакетів:
clawhub skill publish <path> — це інша команда для публікації каталогу Skills, а не пакета Plugin. Див. Публікація в ClawHub.

Точка входу налаштування

setup-entry.ts — це полегшена альтернатива index.ts, яку OpenClaw завантажує, коли потрібні лише поверхні налаштування (початкове налаштування, виправлення конфігурації, перевірка вимкненого каналу):
Це дає змогу не завантажувати важкий код середовища виконання (криптографічні бібліотеки, реєстрації CLI, фонові служби) під час процесів налаштування. Вбудовані канали робочого простору, які зберігають безпечні для налаштування експорти в допоміжних модулях, можуть використовувати defineBundledChannelSetupEntry(...) з openclaw/plugin-sdk/channel-entry-contract замість defineSetupPluginEntry(...). Цей контракт для вбудованих компонентів також підтримує необов’язковий експорт runtime, щоб підключення середовища виконання під час налаштування залишалося легким і явним.
  • Канал вимкнено, але йому потрібні поверхні налаштування або початкового налаштування.
  • Канал увімкнено, але не налаштовано.
  • Увімкнено відкладене завантаження (deferConfiguredChannelFullLoadUntilAfterListen).
  • Об’єкт Plugin каналу (через defineSetupPluginEntry).
  • Усі маршрути HTTP, потрібні до початку прослуховування Gateway.
  • Усі методи Gateway, потрібні під час запуску.
Ці методи Gateway для запуску все одно не повинні використовувати зарезервовані простори імен адміністрування ядра, як-от config.* або update.*.
  • Реєстрації CLI.
  • Фонові служби.
  • Важкі імпорти середовища виконання (криптографічні бібліотеки, SDK).
  • Методи Gateway, потрібні лише після запуску.

Вузькоспеціалізовані імпорти допоміжних засобів налаштування

Для часто використовуваних шляхів, призначених лише для налаштування, надавайте перевагу вузькоспеціалізованим інтерфейсам допоміжних засобів налаштування замість ширшого універсального інтерфейсу plugin-sdk/setup, якщо вам потрібна лише частина поверхні налаштування: Використовуйте ширший інтерфейс plugin-sdk/setup, якщо вам потрібен повний спільний набір інструментів налаштування, зокрема допоміжні засоби виправлення конфігурації, як-от moveSingleAccountChannelSectionToDefaultAccount(...). Використовуйте createSetupTranslator(...) для фіксованого тексту майстра налаштування. Він використовує локаль майстра CLI (OPENCLAW_LOCALE, а потім системні змінні локалі) і за відсутності перекладу повертається до англійської мови. Зберігайте специфічний для Plugin текст налаштування в коді, що належить Plugin, а ключі спільного каталогу використовуйте лише для загальних міток налаштування, тексту стану й тексту налаштування офіційних вбудованих Plugin. Адаптери виправлення налаштувань залишаються безпечними для імпорту в часто використовуваних шляхах. Пошук поверхні контракту для підвищення вбудованої конфігурації одного облікового запису виконується відкладено, тому імпорт plugin-sdk/setup-runtime не запускає завчасно виявлення поверхні вбудованого контракту, доки адаптер фактично не буде використано.

Підвищення конфігурації одного облікового запису, кероване каналом

Коли канал переходить від конфігурації одного облікового запису верхнього рівня до channels.<id>.accounts.*, стандартна спільна поведінка переміщує підвищені значення, що стосуються облікового запису, до accounts.default. Вбудовані канали можуть звузити або перевизначити це підвищення через свою поверхню контракту налаштування:
  • singleAccountKeysToMove: додаткові ключі верхнього рівня, які потрібно перемістити до підвищеного облікового запису
  • namedAccountPromotionKeys: якщо іменовані облікові записи вже існують, до підвищеного облікового запису переміщуються лише ці ключі; спільні ключі політики й доставки залишаються в корені каналу
  • resolveSingleAccountPromotionTarget(...): вибирає, який наявний обліковий запис отримає підвищені значення
Matrix — поточний вбудований приклад. Якщо вже існує рівно один іменований обліковий запис Matrix або якщо defaultAccount указує на наявний неканонічний ключ, як-от Ops, підвищення зберігає цей обліковий запис замість створення нового запису accounts.default.

Схема конфігурації

Конфігурація Plugin перевіряється за схемою JSON у вашому маніфесті. Користувачі налаштовують Plugin так:
Ваш Plugin отримує цю конфігурацію як api.pluginConfig під час реєстрації. Для конфігурації, специфічної для каналу, натомість використовуйте розділ конфігурації каналу:

Побудова схем конфігурації каналів

Використовуйте buildChannelConfigSchema, щоб перетворити схему Zod на обгортку ChannelConfigSchema, яку використовують артефакти конфігурації, що належать Plugin:
Якщо ви вже описуєте контракт як схему JSON або TypeBox, використовуйте безпосередній допоміжний засіб, щоб OpenClaw міг пропустити перетворення Zod на схему JSON у шляхах метаданих:
Для сторонніх Plugin контрактом холодного шляху й надалі є маніфест Plugin: віддзеркальте згенеровану схему JSON у openclaw.plugin.json#channelConfigs, щоб поверхні схеми конфігурації, налаштування та інтерфейсу користувача могли перевіряти channels.<id> без завантаження коду середовища виконання.

Майстри налаштування

Plugin каналів можуть надавати інтерактивні майстри налаштування для openclaw onboard. Майстер — це об’єкт ChannelSetupWizard у ChannelPlugin:
ChannelSetupWizard також підтримує textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize тощо. Повний приклад вбудованого Plugin див. у файлі src/setup-core.ts Plugin Discord.
Для запитів списку дозволених відправників особистих повідомлень, яким потрібен лише стандартний процес примітка -> запит -> розбір -> об’єднання -> виправлення, надавайте перевагу спільним допоміжним засобам налаштування з openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) і createNestedChannelParsedAllowFromPrompt(...).
Для блоків стану налаштування каналу, що відрізняються лише мітками, оцінками й необов’язковими додатковими рядками, надавайте перевагу createStandardChannelSetupStatus(...) з openclaw/plugin-sdk/setup замість ручного створення однакового об’єкта status у кожному Plugin.
Для необов’язкових поверхонь налаштування, які мають з’являтися лише в певних контекстах, використовуйте createOptionalChannelSetupSurface з openclaw/plugin-sdk/channel-setup:
plugin-sdk/channel-setup також надає низькорівневі конструктори createOptionalChannelSetupAdapter(...) і createOptionalChannelSetupWizard(...), якщо вам потрібна лише одна частина цієї поверхні необов’язкового встановлення.Згенеровані необов’язкові адаптер і майстер під час фактичного запису конфігурації завершують роботу з помилкою за замовчуванням. Вони повторно використовують одне повідомлення про необхідність установлення в validateInput, applyAccountConfig і finalize та додають посилання на документацію, коли задано docsPath.
Для інтерфейсів налаштування на основі бінарних файлів віддавайте перевагу спільним делегованим допоміжним засобам замість дублювання однакової логіки роботи з бінарними файлами та станами в кожному каналі:
  • createDetectedBinaryStatus(...) для блоків стану, які відрізняються лише мітками, підказками, оцінками та виявленням бінарного файла
  • createCliPathTextInput(...) для текстових полів введення шляхів
  • createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...) і createDelegatedResolveConfigured(...), коли setupEntry має ліниво делегувати роботу складнішому повнофункціональному майстру
  • createDelegatedTextInputShouldPrompt(...), коли setupEntry потрібно лише делегувати рішення textInputs[*].shouldPrompt

Публікація та встановлення

Зовнішні плагіни: опублікуйте в ClawHub, а потім установіть:
Специфікації пакетів без префікса встановлюються з npm під час переходу на запуск, якщо назва не збігається з ідентифікатором вбудованого або офіційного плагіна; у такому разі OpenClaw натомість використовує відповідну локальну або офіційну копію. Для детермінованого вибору джерела використовуйте clawhub:, npm:, git: або npm-pack: — див. Керування плагінами.
Плагіни в репозиторії: розміщуйте їх у дереві робочого простору вбудованих плагінів; вони автоматично виявляються під час збирання.
Для встановлень із npm команда openclaw plugins install установлює пакет в окремий для кожного плагіна проєкт у ~/.openclaw/npm/projects із вимкненими сценаріями життєвого циклу (--ignore-scripts). Використовуйте в деревах залежностей плагінів лише JS/TS і уникайте пакетів, які потребують збирання через postinstall.
Під час запуску Gateway залежності плагінів не встановлюються. Потоки встановлення з npm, git і ClawHub відповідають за узгодження залежностей; залежності локальних плагінів уже мають бути встановлені.
Метадані вбудованих пакетів задаються явно, а не виводяться зі зібраного JavaScript під час запуску Gateway. Залежності середовища виконання мають бути в пакеті плагіна, якому вони належать; запуск упакованого OpenClaw ніколи не відновлює та не дублює залежності плагінів.

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