Довідник із пакування плагінів (метаданіDocumentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
package.json), маніфестів (openclaw.plugin.json), записів налаштування та схем конфігурації.
Метадані пакета
Вашомуpackage.json потрібне поле openclaw, яке повідомляє системі плагінів, що надає ваш плагін:
- Channel plugin
- Provider plugin / ClawHub baseline
Якщо ви публікуєте плагін зовні на ClawHub, ці поля
compat і build обов’язкові. Канонічні фрагменти для публікації розміщені в docs/snippets/plugin-publish/.Поля openclaw
Файли точок входу (відносно кореня пакета).
Легковаговий запис лише для налаштування (необов’язково).
Метадані каталогу каналів для налаштування, вибирача, швидкого старту й поверхонь стану.
Ідентифікатори провайдерів, зареєстровані цим плагіном.
Підказки встановлення:
npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery.Прапорці поведінки запуску.
openclaw.channel
openclaw.channel — це легкі метадані пакета для виявлення каналів і поверхонь налаштування до завантаження runtime.
| Поле | Тип | Що означає |
|---|---|---|
id | string | Канонічний ідентифікатор каналу. |
label | string | Основна мітка каналу. |
selectionLabel | string | Мітка вибирача/налаштування, коли вона має відрізнятися від label. |
detailLabel | string | Вторинна детальна мітка для розширених каталогів каналів і поверхонь стану. |
docsPath | string | Шлях документації для посилань налаштування й вибору. |
docsLabel | string | Перевизначення мітки для посилань документації, коли вона має відрізнятися від ідентифікатора каналу. |
blurb | string | Короткий опис для онбордингу/каталогу. |
order | number | Порядок сортування в каталогах каналів. |
aliases | string[] | Додаткові псевдоніми пошуку для вибору каналу. |
preferOver | string[] | Ідентифікатори плагінів/каналів нижчого пріоритету, які цей канал має випереджати. |
systemImage | string | Необов’язкова назва іконки/system-image для каталогів 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 | Дозволяє потокам перевстановлення комплектних плагінів відновлюватися після конкретних збоїв застарілої конфігурації. |
Onboarding behavior
Onboarding behavior
Інтерактивний онбординг також використовує
openclaw.install для поверхонь установлення на вимогу. Якщо ваш плагін надає варіанти автентифікації провайдера або метадані налаштування/каталогу каналів до завантаження runtime, онбординг може показати цей вибір, запросити встановлення через ClawHub, npm або локально, встановити чи ввімкнути плагін, а потім продовжити вибраний потік. Варіанти онбордингу ClawHub використовують clawhubSpec і мають перевагу, коли присутні; варіанти npm потребують довірених метаданих каталогу з registry npmSpec; точні версії та expectedIntegrity є необов’язковими фіксаціями npm. Якщо expectedIntegrity присутнє, потоки встановлення/оновлення примусово застосовують його для npm. Зберігайте метадані «що показувати» в openclaw.plugin.json, а метадані «як це встановити» — у package.json.minHostVersion enforcement
minHostVersion enforcement
Якщо
minHostVersion задано, його застосовують і встановлення, і завантаження реєстру маніфестів для некомплектних плагінів. Старіші хости пропускають зовнішні плагіни; недійсні рядки версій відхиляються. Комплектні вихідні плагіни вважаються співверсійними з checkout хоста.Pinned npm installs
Pinned npm installs
Для закріплених встановлень npm зберігайте точну версію в
npmSpec і додайте очікувану цілісність артефакту:allowInvalidConfigRecovery scope
allowInvalidConfigRecovery scope
allowInvalidConfigRecovery не є загальним обходом для зламаних конфігурацій. Він призначений лише для вузького відновлення комплектних плагінів, щоб перевстановлення/налаштування могло виправити відомі залишки після оновлення, як-от відсутній шлях комплектного плагіна або застарілий запис channels.<id> для того самого плагіна. Якщо конфігурація зламана з не пов’язаних причин, установлення все одно завершується закритою помилкою й повідомляє оператору запустити openclaw doctor --fix.Відкладене повне завантаження
Плагіни каналів можуть увімкнути відкладене завантаження за допомогою:setupEntry під час фази запуску до прослуховування, навіть для вже налаштованих каналів. Повний запис завантажується після того, як gateway починає прослуховування.
Якщо ваш запис налаштування/повний запис реєструє RPC-методи gateway, тримайте їх на префіксі, специфічному для плагіна. Зарезервовані простори імен адміністрування core (config.*, exec.approvals.*, wizard.*, update.*) залишаються у власності core і завжди зіставляються з operator.admin.
Маніфест плагіна
Кожен нативний плагін має постачатиopenclaw.plugin.json у корені пакета. OpenClaw використовує це для перевірки конфігурації без виконання коду плагіна.
kind і channels:
Публікація в ClawHub
Для пакетів плагінів використовуйте команду ClawHub, специфічну для пакета:Застарілий alias публікації лише для skills призначений для skills. Пакети Plugin завжди мають використовувати
clawhub package publish.Запис налаштування
Файлsetup-entry.ts — це легка альтернатива index.ts, яку OpenClaw завантажує, коли йому потрібні лише поверхні налаштування (онбординг, виправлення конфігурації, перевірка вимкненого каналу).
defineBundledChannelSetupEntry(...) з openclaw/plugin-sdk/channel-entry-contract замість defineSetupPluginEntry(...). Цей пакетний контракт також підтримує необов’язковий експорт runtime, щоб runtime-зв’язування під час налаштування залишалося легким і явним.
Коли OpenClaw використовує setupEntry замість повного entry
Коли OpenClaw використовує setupEntry замість повного entry
- Канал вимкнено, але йому потрібні поверхні налаштування/онбордингу.
- Канал увімкнено, але не налаштовано.
- Увімкнено відкладене завантаження (
deferConfiguredChannelFullLoadUntilAfterListen).
Що setupEntry має зареєструвати
Що setupEntry має зареєструвати
- Об’єкт channel plugin (через
defineSetupPluginEntry). - Будь-які HTTP routes, потрібні до gateway listen.
- Будь-які gateway methods, потрібні під час запуску.
config.* або update.*.Що setupEntry НЕ має містити
Що setupEntry НЕ має містити
- Реєстрації CLI.
- Фонові сервіси.
- Важкі runtime imports (crypto, SDKs).
- Gateway methods, потрібні лише після запуску.
Вузькі імпорти помічників налаштування
Для гарячих setup-only шляхів віддавайте перевагу вузьким швам помічників налаштування замість ширшого umbrellaplugin-sdk/setup, коли вам потрібна лише частина поверхні налаштування:
| Шлях імпорту | Для чого використовувати | Ключові експорти |
|---|---|---|
plugin-sdk/setup-runtime | runtime-помічники під час налаштування, доступні в setupEntry / deferred channel startup | createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy |
plugin-sdk/setup-adapter-runtime | застарілий compatibility alias; використовуйте plugin-sdk/setup-runtime | createEnvPatchedAccountSetupAdapter |
plugin-sdk/setup-tools | помічники setup/install CLI/archive/docs | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
plugin-sdk/setup, коли потрібен повний спільний toolbox налаштування, включно з config-patch помічниками, як-от moveSingleAccountChannelSectionToDefaultAccount(...).
Setup patch adapters залишаються безпечними для hot-path під час імпорту. Їхній пакетний single-account promotion contract-surface lookup є лінивим, тому імпорт plugin-sdk/setup-runtime не завантажує заздалегідь bundled contract-surface discovery до фактичного використання адаптера.
Channel-owned single-account promotion
Коли канал оновлюється з single-account top-level config доchannels.<id>.accounts.*, стандартна спільна поведінка переносить promoted account-scoped values до accounts.default.
Пакетні канали можуть звузити або перевизначити це promotion через свою setup contract surface:
singleAccountKeysToMove: додаткові top-level keys, які мають перейти до promoted accountnamedAccountPromotionKeys: коли named accounts уже існують, лише ці keys переходять до promoted account; shared policy/delivery keys залишаються в корені каналуresolveSingleAccountPromotionTarget(...): вибрати, який наявний account отримає promoted values
Matrix — поточний пакетний приклад. Якщо вже існує рівно один named Matrix account або якщо
defaultAccount вказує на наявний non-canonical key, як-от Ops, promotion зберігає цей account замість створення нового запису accounts.default.Схема конфігурації
Конфігурація Plugin перевіряється за JSON Schema у вашому manifest. Користувачі налаштовують plugins через:api.pluginConfig під час реєстрації.
Для конфігурації, специфічної для каналу, використовуйте натомість розділ конфігурації каналу:
Створення схем конфігурації каналів
ВикористовуйтеbuildChannelConfigSchema, щоб перетворити Zod schema на wrapper ChannelConfigSchema, який використовується plugin-owned config artifacts:
openclaw.plugin.json#channelConfigs, щоб schema конфігурації, налаштування та поверхні UI могли перевіряти channels.<id> без завантаження runtime-коду.
Майстри налаштування
Channel plugins можуть надавати інтерактивні майстри налаштування дляopenclaw onboard. Майстер — це об’єкт ChannelSetupWizard у ChannelPlugin:
ChannelSetupWizard підтримує credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize та інше. Повні приклади дивіться в пакетах bundled plugin (наприклад, у Discord Plugin src/channel.setup.ts).
Спільні підказки allowFrom
Спільні підказки allowFrom
Для DM allowlist prompts, яким потрібен лише стандартний потік
note -> prompt -> parse -> merge -> patch, віддавайте перевагу спільним setup helpers з openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) і createNestedChannelParsedAllowFromPrompt(...).Стандартний статус налаштування каналу
Стандартний статус налаштування каналу
Для блоків channel setup status, які відрізняються лише labels, scores і необов’язковими extra lines, віддавайте перевагу
createStandardChannelSetupStatus(...) з openclaw/plugin-sdk/setup замість ручного створення такого самого об’єкта status у кожному Plugin.Необов’язкова поверхня налаштування каналу
Необов’язкова поверхня налаштування каналу
Для optional setup surfaces, які мають з’являтися лише в певних контекстах, використовуйте
createOptionalChannelSetupSurface з openclaw/plugin-sdk/channel-setup:plugin-sdk/channel-setup також надає lower-level builders createOptionalChannelSetupAdapter(...) і createOptionalChannelSetupWizard(...), коли вам потрібна лише одна половина цієї optional-install surface.Згенеровані optional adapter/wizard fail closed для реальних config writes. Вони повторно використовують одне install-required message у validateInput, applyAccountConfig і finalize, а також додають docs link, коли задано docsPath.Помічники налаштування на основі binary
Помічники налаштування на основі binary
Для binary-backed setup UIs віддавайте перевагу спільним delegated helpers замість копіювання однакового binary/status glue в кожен канал:
createDetectedBinaryStatus(...)для status blocks, які відрізняються лише labels, hints, scores і binary detectioncreateCliPathTextInput(...)для path-backed text inputscreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...)іcreateDelegatedResolveConfigured(...), колиsetupEntryмає ліниво пересилати до важчого full wizardcreateDelegatedTextInputShouldPrompt(...), колиsetupEntryмає лише делегувати рішенняtextInputs[*].shouldPrompt
Публікація та встановлення
Зовнішні plugins: опублікуйте в ClawHub, потім встановіть:- npm
- Лише ClawHub
- специфікація пакета npm
Для встановлень із npm
openclaw plugins install установлює пакет у ~/.openclaw/npm із вимкненими сценаріями життєвого циклу. Тримайте дерева залежностей плагінів суто JS/TS і уникайте пакетів, які потребують збірок postinstall.Запуск Gateway не встановлює залежності плагінів. Потоки встановлення npm/git/ClawHub відповідають за узгодження залежностей; локальні плагіни вже повинні мати встановлені залежності.
Пов’язане
- Створення плагінів — покроковий посібник для початку роботи
- Маніфест Plugin — повний довідник схеми маніфесту
- Точки входу SDK —
definePluginEntryіdefineChannelPluginEntry