package.json метадані), маніфестів (openclaw.plugin.json), записів налаштування та схем конфігурації.
Метадані пакета
Вашpackage.json потребує поля openclaw, яке повідомляє системі Plugin, що надає ваш Plugin:
- Plugin каналу
- Plugin провайдера / базовий шаблон ClawHub
Якщо ви публікуєте Plugin зовнішньо в ClawHub, ці поля
compat і build обов’язкові. Канонічні фрагменти для публікації містяться в docs/snippets/plugin-publish/.Поля openclaw
Файли точок входу (відносно кореня пакета).
Легкий запис лише для налаштування (необов’язково).
Метадані каталогу каналів для поверхонь налаштування, вибору, швидкого старту та статусу.
Ідентифікатори провайдерів, зареєстровані цим Plugin.
Підказки встановлення:
npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery.Прапорці поведінки під час запуску.
openclaw.channel
openclaw.channel — це легкі метадані пакета для виявлення каналів і поверхонь налаштування до завантаження середовища виконання.
| Поле | Тип | Що це означає |
|---|---|---|
id | string | Канонічний ідентифікатор каналу. |
label | string | Основна мітка каналу. |
selectionLabel | string | Мітка вибору/налаштування, коли вона має відрізнятися від label. |
detailLabel | string | Вторинна детальна мітка для розширених каталогів каналів і поверхонь статусу. |
docsPath | string | Шлях документації для посилань налаштування та вибору. |
docsLabel | string | Перевизначена мітка для посилань документації, коли вона має відрізнятися від ідентифікатора каналу. |
blurb | string | Короткий опис для онбордингу/каталогу. |
order | number | Порядок сортування в каталогах каналів. |
aliases | string[] | Додаткові псевдоніми пошуку для вибору каналу. |
preferOver | string[] | Ідентифікатори Plugin/каналів нижчого пріоритету, які цей канал має випереджати. |
systemImage | string | Необов’язкова назва піктограми/системного зображення для UI-каталогів каналів. |
selectionDocsPrefix | string | Текст-префікс перед посиланнями документації на поверхнях вибору. |
selectionDocsOmitLabel | boolean | Показувати шлях документації напряму замість підписаного посилання документації в тексті вибору. |
selectionExtras | string[] | Додаткові короткі рядки, додані до тексту вибору. |
markdownCapable | boolean | Позначає канал як сумісний із markdown для рішень щодо вихідного форматування. |
exposure | object | Керування видимістю каналу для налаштування, налаштованих списків і поверхонь документації. |
quickstartAllowFrom | boolean | Долучає цей канал до стандартного потоку налаштування швидкого старту allowFrom. |
forceAccountBinding | boolean | Вимагає явного прив’язування облікового запису, навіть коли існує лише один обліковий запис. |
preferSessionLookupForAnnounceTarget | boolean | Надавати перевагу пошуку сеансу під час розв’язання цілей оголошення для цього каналу. |
exposure підтримує:
configured: включати канал у налаштовані/статусні поверхні списківsetup: включати канал в інтерактивні засоби вибору налаштування/конфігураціїdocs: позначати канал як публічний на поверхнях документації/навігації
showConfigured і showInSetup лишаються підтримуваними як застарілі псевдоніми. Надавайте перевагу exposure.openclaw.install
openclaw.install — це метадані пакета, а не метадані маніфесту.
| Поле | Тип | Що це означає |
|---|---|---|
clawhubSpec | string | Канонічна специфікація ClawHub для встановлення/оновлення та потоків онбордингового встановлення на вимогу. |
npmSpec | string | Канонічна специфікація npm для резервних потоків встановлення/оновлення. |
localPath | string | Локальний шлях розробки або вбудованого встановлення. |
defaultChoice | "clawhub" | "npm" | "local" | Бажане джерело встановлення, коли доступно кілька джерел. |
minHostVersion | string | Мінімальна підтримувана версія OpenClaw у формі >=x.y.z або >=x.y.z-prerelease. |
expectedIntegrity | string | Очікуваний рядок цілісності npm dist, зазвичай sha512-..., для закріплених встановлень. |
allowInvalidConfigRecovery | boolean | Дозволяє потокам перевстановлення вбудованого Plugin відновлюватися після конкретних збоїв застарілої конфігурації. |
requiredPlatformPackages | string[] | Обов’язкові платформозалежні псевдоніми npm, які перевіряються під час встановлення npm. |
Поведінка онбордингу
Поведінка онбордингу
Інтерактивний онбординг також використовує
openclaw.install для поверхонь встановлення на вимогу. Якщо ваш Plugin показує варіанти автентифікації провайдера або метадані налаштування/каталогу каналу до завантаження середовища виконання, онбординг може показати цей варіант, запропонувати ClawHub, npm або локальне встановлення, встановити чи ввімкнути Plugin, а потім продовжити вибраний потік. Варіанти онбордингу ClawHub використовують clawhubSpec і мають перевагу, коли присутні; варіанти npm потребують довірених метаданих каталогу з реєстровим npmSpec; точні версії та expectedIntegrity є необов’язковими закріпленнями npm. Якщо expectedIntegrity присутній, потоки встановлення/оновлення застосовують його для npm. Зберігайте метадані «що показувати» в openclaw.plugin.json, а метадані «як це встановити» — у package.json.Застосування minHostVersion
Застосування minHostVersion
Якщо
minHostVersion задано, його застосовують і встановлення, і завантаження реєстру маніфестів для невбудованих Plugin. Старіші хости пропускають зовнішні Plugin; недійсні рядки версій відхиляються. Передбачається, що вбудовані вихідні Plugin мають ту саму версію, що й checkout хоста.Закріплені встановлення npm
Закріплені встановлення npm
Для закріплених встановлень npm зберігайте точну версію в
npmSpec і додайте очікувану цілісність артефакту:Область дії allowInvalidConfigRecovery
Область дії allowInvalidConfigRecovery
allowInvalidConfigRecovery не є загальним обходом для зламаних конфігурацій. Він призначений лише для вузького відновлення вбудованого Plugin, щоб перевстановлення/налаштування могло виправити відомі залишки оновлення, як-от відсутній шлях вбудованого Plugin або застарілий запис channels.<id> для того самого Plugin. Якщо конфігурація зламана з непов’язаних причин, встановлення все одно завершується закритою відмовою й повідомляє оператору запустити openclaw doctor --fix.Відкладене повне завантаження
Plugin каналів можуть увімкнути відкладене завантаження за допомогою:setupEntry під час фази запуску до прослуховування, навіть для вже налаштованих каналів. Повний запис завантажується після того, як Gateway починає прослуховування.
Якщо ваш запис налаштування/повний запис реєструє RPC-методи Gateway, тримайте їх у префіксі, специфічному для Plugin. Зарезервовані основні адміністративні простори імен (config.*, exec.approvals.*, wizard.*, update.*) залишаються у власності core і завжди розв’язуються в operator.admin.
Маніфест Plugin
Кожен нативний Plugin має постачатиopenclaw.plugin.json у корені пакета. OpenClaw використовує його для перевірки конфігурації без виконання коду Plugin.
kind і channels:
Публікація в ClawHub
Для пакетів плагінів використовуйте команду ClawHub, призначену для пакетів:Застарілий псевдонім публікації лише для Skills призначений для Skills. Пакети Plugin завжди мають використовувати
clawhub package publish.Вхід налаштування
Файлsetup-entry.ts — це легка альтернатива index.ts, яку OpenClaw завантажує, коли йому потрібні лише поверхні налаштування (початкове налаштування, виправлення конфігурації, перевірка вимкненого каналу).
defineBundledChannelSetupEntry(...) з openclaw/plugin-sdk/channel-entry-contract замість defineSetupPluginEntry(...). Цей вбудований контракт також підтримує необов’язковий експорт runtime, щоб wiring runtime під час налаштування залишався легким і явним.
Коли OpenClaw використовує setupEntry замість повного входу
Коли OpenClaw використовує setupEntry замість повного входу
- Канал вимкнений, але потребує поверхонь налаштування/початкового налаштування.
- Канал увімкнений, але не налаштований.
- Відкладене завантаження увімкнено (
deferConfiguredChannelFullLoadUntilAfterListen).
Що setupEntry має зареєструвати
Що setupEntry має зареєструвати
- Об’єкт Plugin каналу (через
defineSetupPluginEntry). - Будь-які HTTP-маршрути, потрібні до прослуховування gateway.
- Будь-які методи gateway, потрібні під час запуску.
config.* або update.*.Що setupEntry НЕ має містити
Що setupEntry НЕ має містити
- Реєстрації CLI.
- Фонові служби.
- Важкі імпорти runtime (криптографія, SDK).
- Методи Gateway, потрібні лише після запуску.
Вузькі імпорти помічників налаштування
Для гарячих шляхів лише налаштування віддавайте перевагу вузьким швам помічників налаштування над ширшою парасолькоюplugin-sdk/setup, коли вам потрібна лише частина поверхні налаштування:
| Шлях імпорту | Для чого використовувати | Ключові експорти |
|---|---|---|
plugin-sdk/setup-runtime | runtime-помічники часу налаштування, які залишаються доступними в setupEntry / відкладеному запуску каналу | createSetupTranslator, createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy |
plugin-sdk/setup-adapter-runtime | застарілий псевдонім сумісності; використовуйте plugin-sdk/setup-runtime | createEnvPatchedAccountSetupAdapter |
plugin-sdk/setup-tools | помічники CLI/архівів/документації для налаштування/встановлення | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
plugin-sdk/setup, коли вам потрібен повний спільний набір інструментів налаштування, включно з помічниками виправлення конфігурації, як-от moveSingleAccountChannelSectionToDefaultAccount(...).
Використовуйте createSetupTranslator(...) для фіксованого тексту майстра налаштування. Він дотримується локалі
майстра CLI (OPENCLAW_LOCALE, потім системних змінних локалі) і повертається
до англійської. Зберігайте специфічний для Plugin текст налаштування в коді, яким володіє Plugin, і використовуйте
спільні ключі каталогу лише для поширених міток налаштування, тексту статусу та офіційного
тексту налаштування вбудованих Plugin.
Адаптери виправлень налаштування залишаються безпечними для гарячого шляху під час імпорту. Їхній вбудований lookup поверхні контракту просування одного облікового запису є лінивим, тому імпорт plugin-sdk/setup-runtime не завантажує завчасно discovery вбудованої поверхні контракту до фактичного використання адаптера.
Просування одного облікового запису, яким володіє канал
Коли канал оновлюється з конфігурації верхнього рівня для одного облікового запису доchannels.<id>.accounts.*, стандартна спільна поведінка переміщує просунуті значення, прив’язані до облікового запису, в accounts.default.
Вбудовані канали можуть звузити або перевизначити це просування через свою поверхню контракту налаштування:
singleAccountKeysToMove: додаткові ключі верхнього рівня, які мають перейти в просунутий обліковий записnamedAccountPromotionKeys: коли іменовані облікові записи вже існують, лише ці ключі переходять у просунутий обліковий запис; спільні ключі політики/доставки залишаються в корені каналуresolveSingleAccountPromotionTarget(...): вибирає, який наявний обліковий запис отримує просунуті значення
Matrix — поточний вбудований приклад. Якщо вже існує рівно один іменований обліковий запис Matrix або якщо
defaultAccount вказує на наявний неканонічний ключ, як-от Ops, просування зберігає цей обліковий запис замість створення нового запису accounts.default.Схема конфігурації
Конфігурація Plugin перевіряється за JSON Schema у вашому маніфесті. Користувачі налаштовують плагіни через:api.pluginConfig під час реєстрації.
Для конфігурації, специфічної для каналу, використовуйте натомість розділ конфігурації каналу:
Побудова схем конфігурації каналів
ВикористовуйтеbuildChannelConfigSchema, щоб перетворити схему Zod на обгортку ChannelConfigSchema, яку використовують артефакти конфігурації, якими володіє Plugin:
openclaw.plugin.json#channelConfigs, щоб схема конфігурації, налаштування та UI-поверхні могли перевіряти channels.<id> без завантаження runtime-коду.
Майстри налаштування
Плагіни каналів можуть надавати інтерактивні майстри налаштування дляopenclaw onboard. Майстер — це об’єкт ChannelSetupWizard у ChannelPlugin:
ChannelSetupWizard підтримує credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize тощо. Повні приклади див. у пакетах вбудованих Plugin (наприклад, Plugin Discord src/channel.setup.ts).
Спільні запити allowFrom
Спільні запити allowFrom
Для запитів allowlist DM, яким потрібен лише стандартний потік
note -> prompt -> parse -> merge -> patch, віддавайте перевагу спільним помічникам налаштування з openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) і createNestedChannelParsedAllowFromPrompt(...).Стандартний статус налаштування каналу
Стандартний статус налаштування каналу
Для блоків статусу налаштування каналу, які відрізняються лише мітками, оцінками та необов’язковими додатковими рядками, віддавайте перевагу
createStandardChannelSetupStatus(...) з openclaw/plugin-sdk/setup замість ручного створення того самого об’єкта status у кожному Plugin.Необов’язкова поверхня налаштування каналу
Необов’язкова поверхня налаштування каналу
Для необов’язкових поверхонь налаштування, які мають з’являтися лише в певних контекстах, використовуйте
createOptionalChannelSetupSurface з openclaw/plugin-sdk/channel-setup:plugin-sdk/channel-setup також надає нижчорівневі builders createOptionalChannelSetupAdapter(...) і createOptionalChannelSetupWizard(...), коли вам потрібна лише одна половина цієї поверхні необов’язкового встановлення.Згенерований необов’язковий адаптер/майстер відмовляє закрито під час реальних записів конфігурації. Вони повторно використовують одне повідомлення про необхідність встановлення в validateInput, applyAccountConfig і finalize та додають посилання на документацію, коли встановлено docsPath.Помічники налаштування на основі бінарних файлів
Помічники налаштування на основі бінарних файлів
Для UI налаштування на основі бінарних файлів віддавайте перевагу спільним делегованим помічникам замість копіювання того самого glue для бінарного файлу/статусу в кожен канал:
createDetectedBinaryStatus(...)для блоків стану, що відрізняються лише мітками, підказками, оцінками та виявленням бінарного файлаcreateCliPathTextInput(...)для текстових полів вводу на основі шляхуcreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...)іcreateDelegatedResolveConfigured(...), колиsetupEntryпотрібно відкладено переспрямувати до важчого повного майстраcreateDelegatedTextInputShouldPrompt(...), колиsetupEntryпотрібно лише делегувати рішенняtextInputs[*].shouldPrompt
Публікація та встановлення
Зовнішні плагіни: опублікуйте в ClawHub, потім установіть:- npm
- Лише ClawHub
- Специфікація пакета npm
Для встановлень із npm
openclaw plugins install встановлює пакет у проєкт окремого плагіна в ~/.openclaw/npm/projects із вимкненими lifecycle-скриптами. Тримайте дерева залежностей плагінів чистими JS/TS і уникайте пакетів, які потребують збірок postinstall.Запуск Gateway не встановлює залежності плагінів. Потоки встановлення npm/git/ClawHub відповідають за узгодження залежностей; локальні плагіни вже повинні мати встановлені залежності.
Пов’язане
- Створення плагінів — покроковий посібник із початку роботи
- Маніфест Plugin — повний довідник схеми маніфесту
- Точки входу SDK —
definePluginEntryіdefineChannelPluginEntry