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

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

Вашому package.json потрібне поле openclaw, яке повідомляє системі плагінів, що надає ваш плагін: 
{
  "name": "@myorg/openclaw-my-channel",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "channel": {
      "id": "my-channel",
      "label": "My Channel",
      "blurb": "Short description of the channel."
    }
  }
}
Якщо ви публікуєте плагін зовні на ClawHub, ці поля compat і build обов’язкові. Канонічні фрагменти для публікації розміщені в docs/snippets/plugin-publish/.

​
Поля openclaw

​
extensions
string[]
Файли точок входу (відносно кореня пакета).
​
setupEntry
string
Легковаговий запис лише для налаштування (необов’язково).
​
channel
object
Метадані каталогу каналів для налаштування, вибирача, швидкого старту й поверхонь стану.
​
providers
string[]
Ідентифікатори провайдерів, зареєстровані цим плагіном.
​
install
object
Підказки встановлення: npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery.
​
startup
object
Прапорці поведінки запуску.

​
openclaw.channel

openclaw.channel — це легкі метадані пакета для виявлення каналів і поверхонь налаштування до завантаження runtime.
ПолеТипЩо означає
idstringКанонічний ідентифікатор каналу.
labelstringОсновна мітка каналу.
selectionLabelstringМітка вибирача/налаштування, коли вона має відрізнятися від label.
detailLabelstringВторинна детальна мітка для розширених каталогів каналів і поверхонь стану.
docsPathstringШлях документації для посилань налаштування й вибору.
docsLabelstringПеревизначення мітки для посилань документації, коли вона має відрізнятися від ідентифікатора каналу.
blurbstringКороткий опис для онбордингу/каталогу.
ordernumberПорядок сортування в каталогах каналів.
aliasesstring[]Додаткові псевдоніми пошуку для вибору каналу.
preferOverstring[]Ідентифікатори плагінів/каналів нижчого пріоритету, які цей канал має випереджати.
systemImagestringНеобов’язкова назва іконки/system-image для каталогів UI каналів.
selectionDocsPrefixstringТекст-префікс перед посиланнями документації в поверхнях вибору.
selectionDocsOmitLabelbooleanПоказувати шлях документації напряму замість підписаного посилання документації в тексті вибору.
selectionExtrasstring[]Додаткові короткі рядки, додані до тексту вибору.
markdownCapablebooleanПозначає канал як сумісний із markdown для рішень щодо вихідного форматування.
exposureobjectЕлементи керування видимістю каналу для налаштування, списків налаштованого й поверхонь документації.
quickstartAllowFrombooleanДолучає цей канал до стандартного потоку налаштування швидкого старту allowFrom.
forceAccountBindingbooleanВимагає явного прив’язування облікового запису, навіть коли існує лише один обліковий запис.
preferSessionLookupForAnnounceTargetbooleanНадає перевагу пошуку сесії під час визначення цілей оголошень для цього каналу.
Приклад: 
{
  "openclaw": {
    "channel": {
      "id": "my-channel",
      "label": "My Channel",
      "selectionLabel": "My Channel (self-hosted)",
      "detailLabel": "My Channel Bot",
      "docsPath": "/channels/my-channel",
      "docsLabel": "my-channel",
      "blurb": "Webhook-based self-hosted chat integration.",
      "order": 80,
      "aliases": ["mc"],
      "preferOver": ["my-channel-legacy"],
      "selectionDocsPrefix": "Guide:",
      "selectionExtras": ["Markdown"],
      "markdownCapable": true,
      "exposure": {
        "configured": true,
        "setup": true,
        "docs": true
      },
      "quickstartAllowFrom": true
    }
  }
}
exposure підтримує:
  • configured: включати канал у поверхні списків налаштованого/стану
  • setup: включати канал в інтерактивні вибирачі налаштування/конфігурування
  • docs: позначати канал як публічний у поверхнях документації/навігації
showConfigured і showInSetup залишаються підтримуваними як застарілі псевдоніми. Віддавайте перевагу exposure.

​
openclaw.install

openclaw.install — це метадані пакета, а не метадані маніфесту.
ПолеТипЩо означає
clawhubSpecstringКанонічна специфікація ClawHub для встановлення/оновлення та потоків онбордингу з установленням на вимогу.
npmSpecstringКанонічна специфікація npm для резервних потоків встановлення/оновлення.
localPathstringЛокальний шлях розробки або комплектного встановлення.
defaultChoice"clawhub" | "npm" | "local"Бажане джерело встановлення, коли доступні кілька джерел.
minHostVersionstringМінімальна підтримувана версія OpenClaw у формі >=x.y.z або >=x.y.z-prerelease.
expectedIntegritystringОчікуваний рядок цілісності npm dist, зазвичай sha512-..., для закріплених встановлень.
allowInvalidConfigRecoverybooleanДозволяє потокам перевстановлення комплектних плагінів відновлюватися після конкретних збоїв застарілої конфігурації.
Інтерактивний онбординг також використовує openclaw.install для поверхонь установлення на вимогу. Якщо ваш плагін надає варіанти автентифікації провайдера або метадані налаштування/каталогу каналів до завантаження runtime, онбординг може показати цей вибір, запросити встановлення через ClawHub, npm або локально, встановити чи ввімкнути плагін, а потім продовжити вибраний потік. Варіанти онбордингу ClawHub використовують clawhubSpec і мають перевагу, коли присутні; варіанти npm потребують довірених метаданих каталогу з registry npmSpec; точні версії та expectedIntegrity є необов’язковими фіксаціями npm. Якщо expectedIntegrity присутнє, потоки встановлення/оновлення примусово застосовують його для npm. Зберігайте метадані «що показувати» в openclaw.plugin.json, а метадані «як це встановити» — у package.json.
Якщо minHostVersion задано, його застосовують і встановлення, і завантаження реєстру маніфестів для некомплектних плагінів. Старіші хости пропускають зовнішні плагіни; недійсні рядки версій відхиляються. Комплектні вихідні плагіни вважаються співверсійними з checkout хоста.
Для закріплених встановлень npm зберігайте точну версію в npmSpec і додайте очікувану цілісність артефакту:
{
  "openclaw": {
    "install": {
      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",
      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",
      "defaultChoice": "npm"
    }
  }
}
allowInvalidConfigRecovery не є загальним обходом для зламаних конфігурацій. Він призначений лише для вузького відновлення комплектних плагінів, щоб перевстановлення/налаштування могло виправити відомі залишки після оновлення, як-от відсутній шлях комплектного плагіна або застарілий запис channels.<id> для того самого плагіна. Якщо конфігурація зламана з не пов’язаних причин, установлення все одно завершується закритою помилкою й повідомляє оператору запустити openclaw doctor --fix.

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

Плагіни каналів можуть увімкнути відкладене завантаження за допомогою: 
{
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}
Коли це ввімкнено, OpenClaw завантажує лише setupEntry під час фази запуску до прослуховування, навіть для вже налаштованих каналів. Повний запис завантажується після того, як gateway починає прослуховування.
Умикайте відкладене завантаження лише тоді, коли ваш setupEntry реєструє все, що gateway потребує до початку прослуховування (реєстрація каналу, HTTP-маршрути, методи gateway). Якщо повний запис володіє потрібними можливостями запуску, залиште поведінку за замовчуванням.
Якщо ваш запис налаштування/повний запис реєструє RPC-методи gateway, тримайте їх на префіксі, специфічному для плагіна. Зарезервовані простори імен адміністрування core (config.*, exec.approvals.*, wizard.*, update.*) залишаються у власності core і завжди зіставляються з operator.admin.

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

Кожен нативний плагін має постачати openclaw.plugin.json у корені пакета. OpenClaw використовує це для перевірки конфігурації без виконання коду плагіна. 
{
  "id": "my-plugin",
  "name": "My Plugin",
  "description": "Adds My Plugin capabilities to OpenClaw",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "webhookSecret": {
        "type": "string",
        "description": "Webhook verification secret"
      }
    }
  }
}
Для плагінів каналів додайте kind і channels: 
{
  "id": "my-channel",
  "kind": "channel",
  "channels": ["my-channel"],
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}
Навіть плагіни без конфігурації мають постачати схему. Порожня схема є дійсною: 
{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}
Див. Маніфест плагіна для повного довідника схеми.

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

Для пакетів плагінів використовуйте команду ClawHub, специфічну для пакета: 
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
Застарілий alias публікації лише для skills призначений для skills. Пакети Plugin завжди мають використовувати clawhub package publish.

​
Запис налаштування

Файл setup-entry.ts — це легка альтернатива index.ts, яку OpenClaw завантажує, коли йому потрібні лише поверхні налаштування (онбординг, виправлення конфігурації, перевірка вимкненого каналу). 
// setup-entry.ts
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { myChannelPlugin } from "./src/channel.js";

export default defineSetupPluginEntry(myChannelPlugin);
Це дає змогу не завантажувати важкий runtime-код (криптографічні бібліотеки, реєстрації CLI, фонові сервіси) під час потоків налаштування. Пакетні канали робочого простору, які тримають setup-safe експорти в sidecar-модулях, можуть використовувати defineBundledChannelSetupEntry(...) з openclaw/plugin-sdk/channel-entry-contract замість defineSetupPluginEntry(...). Цей пакетний контракт також підтримує необов’язковий експорт runtime, щоб runtime-зв’язування під час налаштування залишалося легким і явним.
  • Канал вимкнено, але йому потрібні поверхні налаштування/онбордингу.
  • Канал увімкнено, але не налаштовано.
  • Увімкнено відкладене завантаження (deferConfiguredChannelFullLoadUntilAfterListen).
  • Об’єкт channel plugin (через defineSetupPluginEntry).
  • Будь-які HTTP routes, потрібні до gateway listen.
  • Будь-які gateway methods, потрібні під час запуску.
Ці startup gateway methods усе одно мають уникати зарезервованих core admin namespaces, як-от config.* або update.*.
  • Реєстрації CLI.
  • Фонові сервіси.
  • Важкі runtime imports (crypto, SDKs).
  • Gateway methods, потрібні лише після запуску.

​
Вузькі імпорти помічників налаштування

Для гарячих setup-only шляхів віддавайте перевагу вузьким швам помічників налаштування замість ширшого umbrella plugin-sdk/setup, коли вам потрібна лише частина поверхні налаштування:
Шлях імпортуДля чого використовуватиКлючові експорти
plugin-sdk/setup-runtimeruntime-помічники під час налаштування, доступні в setupEntry / deferred channel startupcreatePatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy
plugin-sdk/setup-adapter-runtimeзастарілий compatibility alias; використовуйте plugin-sdk/setup-runtimecreateEnvPatchedAccountSetupAdapter
plugin-sdk/setup-toolsпомічники setup/install CLI/archive/docsformatCliCommand, 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 account
  • namedAccountPromotionKeys: коли 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 через: 
{
  plugins: {
    entries: {
      "my-plugin": {
        config: {
          webhookSecret: "abc123",
        },
      },
    },
  },
}
Ваш Plugin отримує цю конфігурацію як api.pluginConfig під час реєстрації. Для конфігурації, специфічної для каналу, використовуйте натомість розділ конфігурації каналу: 
{
  channels: {
    "my-channel": {
      token: "bot-token",
      allowFrom: ["user1", "user2"],
    },
  },
}

​
Створення схем конфігурації каналів

Використовуйте buildChannelConfigSchema, щоб перетворити Zod schema на wrapper ChannelConfigSchema, який використовується plugin-owned config artifacts: 
import { z } from "zod";
import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";

const accountSchema = z.object({
  token: z.string().optional(),
  allowFrom: z.array(z.string()).optional(),
  accounts: z.object({}).catchall(z.any()).optional(),
  defaultAccount: z.string().optional(),
});

const configSchema = buildChannelConfigSchema(accountSchema);
Якщо ви вже створюєте контракт як JSON Schema або TypeBox, використовуйте direct helper, щоб OpenClaw міг пропустити перетворення Zod-to-JSON-Schema на metadata paths: 
import { Type } from "typebox";
import { buildJsonChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";

const configSchema = buildJsonChannelConfigSchema(
  Type.Object({
    token: Type.Optional(Type.String()),
    allowFrom: Type.Optional(Type.Array(Type.String())),
  }),
);
Для third-party plugins cold-path contract усе ще є plugin manifest: віддзеркальте згенеровану JSON Schema в openclaw.plugin.json#channelConfigs, щоб schema конфігурації, налаштування та поверхні UI могли перевіряти channels.<id> без завантаження runtime-коду.

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

Channel plugins можуть надавати інтерактивні майстри налаштування для openclaw onboard. Майстер — це об’єкт ChannelSetupWizard у ChannelPlugin: 
import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";

const setupWizard: ChannelSetupWizard = {
  channel: "my-channel",
  status: {
    configuredLabel: "Connected",
    unconfiguredLabel: "Not configured",
    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),
  },
  credentials: [
    {
      inputKey: "token",
      providerHint: "my-channel",
      credentialLabel: "Bot token",
      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",
      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",
      keepPrompt: "Keep current token?",
      inputPrompt: "Enter your bot token:",
      inspect: ({ cfg, accountId }) => {
        const token = (cfg.channels as any)?.["my-channel"]?.token;
        return {
          accountConfigured: Boolean(token),
          hasConfiguredValue: Boolean(token),
        };
      },
    },
  ],
};
Тип ChannelSetupWizard підтримує credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize та інше. Повні приклади дивіться в пакетах bundled plugin (наприклад, у Discord Plugin src/channel.setup.ts).
Для 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:
import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup";

const setupSurface = createOptionalChannelSetupSurface({
  channel: "my-channel",
  label: "My Channel",
  npmSpec: "@myorg/openclaw-my-channel",
  docsPath: "/channels/my-channel",
});
// Returns { setupAdapter, setupWizard }
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-backed setup UIs віддавайте перевагу спільним delegated helpers замість копіювання однакового binary/status glue в кожен канал:
  • createDetectedBinaryStatus(...) для status blocks, які відрізняються лише labels, hints, scores і binary detection
  • createCliPathTextInput(...) для path-backed text inputs
  • createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...) і createDelegatedResolveConfigured(...), коли setupEntry має ліниво пересилати до важчого full wizard
  • createDelegatedTextInputShouldPrompt(...), коли setupEntry має лише делегувати рішення textInputs[*].shouldPrompt

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

Зовнішні plugins: опублікуйте в ClawHub, потім встановіть: 
openclaw plugins install @myorg/openclaw-my-plugin
Bare package specs встановлюються з npm під час launch cutover.
Плагіни в репозиторії: розмістіть їх у дереві робочої області вбудованих плагінів, і вони автоматично виявлятимуться під час збірки. Користувачі можуть установити: 
openclaw plugins install <package-name>
Для встановлень із npm openclaw plugins install установлює пакет у ~/.openclaw/npm із вимкненими сценаріями життєвого циклу. Тримайте дерева залежностей плагінів суто JS/TS і уникайте пакетів, які потребують збірок postinstall.
Запуск Gateway не встановлює залежності плагінів. Потоки встановлення npm/git/ClawHub відповідають за узгодження залежностей; локальні плагіни вже повинні мати встановлені залежності.
Метадані вбудованого пакета є явними, а не виводяться зі зібраного JavaScript під час запуску Gateway. Runtime-залежності належать пакету плагіна, який ними володіє; запуск упакованого OpenClaw ніколи не відновлює й не дзеркалює залежності плагінів.

​
Пов’язане