package.json), маніфестів (openclaw.plugin.json), точок входу для налаштування та схем конфігурації.
Метадані пакета
Вашpackage.json має містити поле openclaw, яке повідомляє системі плагінів, що надає ваш плагін:
- Плагін каналу
- Плагін провайдера / базова конфігурація ClawHub
Для зовнішньої публікації в 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
Застосування minHostVersion
Якщо задано
minHostVersion, його вимоги застосовуються як під час встановлення, так і під час завантаження реєстру маніфестів невбудованих плагінів. Старіші хости пропускають зовнішні плагіни; некоректні рядки версій відхиляються. Вважається, що версія вбудованих плагінів із початкового коду збігається з версією вивіреної копії хоста.Встановлення npm із закріпленою версією
Встановлення npm із закріпленою версією
Для встановлень npm із закріпленою версією зберігайте точну версію в
npmSpec і додайте очікувану цілісність артефакту:Область дії allowInvalidConfigRecovery
Область дії allowInvalidConfigRecovery
allowInvalidConfigRecovery не є загальним способом обійти пошкоджені конфігурації. Воно призначене лише для вузького відновлення вбудованого плагіна, даючи повторному встановленню або налаштуванню змогу виправити відомі залишки оновлення, як-от відсутній шлях до вбудованого плагіна або застарілий запис channels.<id> для того самого плагіна. Якщо конфігурацію пошкоджено з непов’язаних причин, встановлення все одно завершується безпечною відмовою та повідомляє оператору запустити openclaw doctor --fix.Відкладене повне завантаження
Плагіни каналів можуть увімкнути відкладене завантаження за допомогою:setupEntry під час етапу запуску до початку прослуховування, навіть для вже налаштованих каналів. Повна точка входу завантажується після того, як Gateway починає прослуховування.
Якщо ваша точка входу для налаштування або повна точка входу реєструє методи RPC Gateway, використовуйте для них префікс, специфічний для плагіна. Зарезервовані основні адміністративні простори імен (config.*, exec.approvals.*, wizard.*, update.*) залишаються у власності ядра та завжди нормалізуються до operator.admin.
Маніфест плагіна
Кожен нативний Plugin повинен постачати файлopenclaw.plugin.json у корені пакета. OpenClaw використовує його для перевірки конфігурації без виконання коду Plugin.
channels (а для Plugin постачальників — providers):
Публікація в ClawHub
Пакети Skills і Plugin використовують окремі команди публікації в ClawHub. Для пакетів Plugin використовуйте спеціальну команду для пакетів:clawhub skill publish <path> — це інша команда для публікації каталогу Skills, а не пакета Plugin. Див. Публікація в ClawHub.Точка входу налаштування
setup-entry.ts — це полегшена альтернатива index.ts, яку OpenClaw завантажує, коли потрібні лише поверхні налаштування (початкове налаштування, виправлення конфігурації, перевірка вимкненого каналу):
defineBundledChannelSetupEntry(...) з openclaw/plugin-sdk/channel-entry-contract замість defineSetupPluginEntry(...). Цей контракт для вбудованих компонентів також підтримує необов’язковий експорт runtime, щоб підключення середовища виконання під час налаштування залишалося легким і явним.
Коли OpenClaw використовує setupEntry замість повної точки входу
Коли OpenClaw використовує setupEntry замість повної точки входу
- Канал вимкнено, але йому потрібні поверхні налаштування або початкового налаштування.
- Канал увімкнено, але не налаштовано.
- Увімкнено відкладене завантаження (
deferConfiguredChannelFullLoadUntilAfterListen).
Що має реєструвати setupEntry
Що має реєструвати setupEntry
- Об’єкт Plugin каналу (через
defineSetupPluginEntry). - Усі маршрути HTTP, потрібні до початку прослуховування Gateway.
- Усі методи Gateway, потрібні під час запуску.
config.* або update.*.Що setupEntry НЕ повинен містити
Що setupEntry НЕ повинен містити
- Реєстрації 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 так:api.pluginConfig під час реєстрації.
Для конфігурації, специфічної для каналу, натомість використовуйте розділ конфігурації каналу:
Побудова схем конфігурації каналів
ВикористовуйтеbuildChannelConfigSchema, щоб перетворити схему Zod на обгортку ChannelConfigSchema, яку використовують артефакти конфігурації, що належать Plugin:
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.
Спільні запити allowFrom
Спільні запити allowFrom
Для запитів списку дозволених відправників особистих повідомлень, яким потрібен лише стандартний процес
примітка -> запит -> розбір -> об’єднання -> виправлення, надавайте перевагу спільним допоміжним засобам налаштування з 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
- Лише ClawHub
- Специфікація пакета npm
clawhub:, npm:, git: або npm-pack: — див. Керування плагінами.Для встановлень із npm команда
openclaw plugins install установлює пакет в окремий для кожного плагіна проєкт у ~/.openclaw/npm/projects із вимкненими сценаріями життєвого циклу (--ignore-scripts). Використовуйте в деревах залежностей плагінів лише JS/TS і уникайте пакетів, які потребують збирання через postinstall.Під час запуску Gateway залежності плагінів не встановлюються. Потоки встановлення з npm, git і ClawHub відповідають за узгодження залежностей; залежності локальних плагінів уже мають бути встановлені.
Пов’язані матеріали
- Створення плагінів — покроковий посібник із початку роботи
- Маніфест плагіна — повний довідник зі схеми маніфесту
- Точки входу SDK —
definePluginEntryіdefineChannelPluginEntry