Перейти до основного вмісту

Налаштування та конфігурація плагіна

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

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

Ваш 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:
openclaw-clawhub-package.json
{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2",
      "minGatewayVersion": "2026.3.24-beta.2"
    },
    "build": {
      "openclawVersion": "2026.3.24-beta.2",
      "pluginSdkVersion": "2026.3.24-beta.2"
    }
  }
}
Якщо ви публікуєте плагін зовні в ClawHub, ці поля compat і build є обов’язковими. Канонічні фрагменти для публікації розміщено в docs/snippets/plugin-publish/.

Поля openclaw

ПолеТипОпис
extensionsstring[]Файли entry point’ів (відносно кореня пакета)
setupEntrystringПолегшений запис лише для налаштування (необов’язково)
channelobjectМетадані каталогу каналів для налаштування, пікера, quickstart і поверхонь статусу
providersstring[]Id провайдерів, які реєструє цей плагін
installobjectПідказки для встановлення: npmSpec, localPath, defaultChoice, minHostVersion, allowInvalidConfigRecovery
startupobjectПрапорці поведінки під час запуску

openclaw.channel

openclaw.channel — це недорогі метадані пакета для виявлення каналу і поверхонь налаштування до завантаження середовища виконання.
ПолеТипЩо це означає
idstringКанонічний id каналу.
labelstringОсновна мітка каналу.
selectionLabelstringМітка для пікера/налаштування, якщо вона має відрізнятися від label.
detailLabelstringДодаткова мітка для докладніших каталогів каналів і поверхонь статусу.
docsPathstringШлях до документації для посилань у налаштуванні та виборі.
docsLabelstringЗаміна мітки для посилань на документацію, якщо вона має відрізнятися від id каналу.
blurbstringКороткий опис для онбордингу/каталогу.
ordernumberПорядок сортування в каталогах каналів.
aliasesstring[]Додаткові псевдоніми для пошуку каналу.
preferOverstring[]Менш пріоритетні id плагінів/каналів, які цей канал має перевершувати.
systemImagestringНеобов’язкова назва icon/system-image для каталогів UI каналів.
selectionDocsPrefixstringПрефіксний текст перед посиланнями на документацію на поверхнях вибору.
selectionDocsOmitLabelbooleanПоказує шлях до документації напряму замість підписаного посилання в тексті вибору.
selectionExtrasstring[]Додаткові короткі рядки, що додаються до тексту вибору.
markdownCapablebooleanПозначає канал як такий, що підтримує markdown для вихідного форматування.
showConfiguredbooleanКерує тим, чи показують поверхні списку налаштованих каналів цей канал.
quickstartAllowFrombooleanДодає цей канал до стандартного потоку налаштування quickstart allowFrom.
forceAccountBindingbooleanВимагає явної прив’язки облікового запису, навіть якщо існує лише один запис.
preferSessionLookupForAnnounceTargetbooleanВіддає перевагу пошуку сесії під час визначення announce targets для цього каналу.
Приклад:
{
  "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,
      "quickstartAllowFrom": true
    }
  }
}

openclaw.install

openclaw.install — це метадані пакета, а не метадані маніфесту.
ПолеТипЩо це означає
npmSpecstringКанонічна npm-специфікація для потоків встановлення/оновлення.
localPathstringЛокальний шлях встановлення для розробки або вбудованого пакета.
defaultChoice"npm" | "local"Бажане джерело встановлення, якщо доступні обидва варіанти.
minHostVersionstringМінімальна підтримувана версія OpenClaw у формі >=x.y.z.
allowInvalidConfigRecoverybooleanДозволяє потокам перевстановлення вбудованих плагінів відновлюватися після певних збоїв застарілої конфігурації.
Якщо задано minHostVersion, його перевіряють і потоки встановлення, і завантаження реєстру маніфестів. Старіші хости пропускають плагін; некоректні рядки версій відхиляються. allowInvalidConfigRecovery не є загальним обходом для зламаних конфігурацій. Це лише вузький механізм відновлення для вбудованих плагінів, щоб перевстановлення/налаштування могло виправити відомі залишки після оновлення, як-от відсутній шлях до вбудованого плагіна або застарілий запис channels.<id> для цього ж плагіна. Якщо конфігурація зламана з непов’язаних причин, встановлення все одно завершується fail-closed і радить оператору запустити openclaw doctor --fix.

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

Плагіни каналів можуть увімкнути відкладене завантаження так:
{
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}
Коли це ввімкнено, OpenClaw під час фази запуску до початку прослуховування завантажує лише setupEntry, навіть для вже налаштованих каналів. Повний entry завантажується після того, як gateway починає слухати.
Вмикайте відкладене завантаження лише тоді, коли ваш setupEntry реєструє все, що gateway потребує до початку прослуховування (реєстрацію каналу, HTTP-маршрути, методи gateway). Якщо необхідні можливості запуску належать повному entry, залишайте типову поведінку.
Якщо ваш setup/full entry реєструє gateway RPC methods, використовуйте для них префікс, специфічний для плагіна. Зарезервовані простори імен основного admin (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": {}
  }
}
Навіть плагіни без конфігурації мають постачатися зі schema. Порожня schema є коректною:
{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}
Повний довідник schema див. у Маніфесті плагіна.

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

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

Setup entry

Файл 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-реєстрацій, фонових сервісів) під час потоків налаштування. Коли OpenClaw використовує setupEntry замість повного entry:
  • Канал вимкнено, але потрібні поверхні налаштування/онбордингу
  • Канал увімкнено, але не налаштовано
  • Увімкнено відкладене завантаження (deferConfiguredChannelFullLoadUntilAfterListen)
Що має реєструвати setupEntry:
  • Об’єкт плагіна каналу (через defineSetupPluginEntry)
  • Будь-які HTTP-маршрути, потрібні до початку прослуховування gateway
  • Будь-які методи gateway, потрібні під час запуску
Ці стартові методи gateway усе одно мають уникати зарезервованих просторів імен основного admin, таких як config.* або update.*. Що НЕ має містити setupEntry:
  • CLI-реєстрації
  • Фонові сервіси
  • Важкі runtime-імпорти (crypto, SDK)
  • Методи gateway, потрібні лише після запуску

Вузькі імпорти setup helpers

Для гарячих шляхів лише для налаштування віддавайте перевагу вузьким seams setup helper’ів замість ширшого umbrella plugin-sdk/setup, коли вам потрібна лише частина поверхні налаштування:
Шлях імпортуДля чого використовуватиКлючові експорти
plugin-sdk/setup-runtimeruntime helpers на етапі налаштування, які лишаються доступними в setupEntry / під час відкладеного запуску каналуcreatePatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy
plugin-sdk/setup-adapter-runtimeenvironment-aware account setup adapterscreateEnvPatchedAccountSetupAdapter
plugin-sdk/setup-toolsCLI/archive/docs helpers для setup/installformatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR
Використовуйте ширший seam plugin-sdk/setup, коли вам потрібен повний спільний набір інструментів для налаштування, зокрема helpers для patch конфігурації, як-от moveSingleAccountChannelSectionToDefaultAccount(...). Адаптери patch налаштування лишаються безпечними для імпорту на гарячому шляху. Їхній вбудований лінивий пошук contract surface для підвищення single-account не виконується завчасно, тому імпорт plugin-sdk/setup-runtime не призводить до раннього завантаження виявлення bundled contract-surface до фактичного використання адаптера.

Підвищення single-account, що належить каналу

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

Schema конфігурації

Конфігурація плагіна проходить валідацію за JSON Schema у вашому маніфесті. Користувачі налаштовують плагіни через:
{
  plugins: {
    entries: {
      "my-plugin": {
        config: {
          webhookSecret: "abc123",
        },
      },
    },
  },
}
Ваш плагін отримує цю конфігурацію як api.pluginConfig під час реєстрації. Для конфігурації, специфічної для каналу, використовуйте натомість розділ конфігурації каналу:
{
  channels: {
    "my-channel": {
      token: "bot-token",
      allowFrom: ["user1", "user2"],
    },
  },
}

Побудова schema конфігурації каналу

Використовуйте buildChannelConfigSchema з openclaw/plugin-sdk/core, щоб перетворити schema Zod на обгортку ChannelConfigSchema, яку валідує OpenClaw:
import { z } from "zod";
import { buildChannelConfigSchema } from "openclaw/plugin-sdk/core";

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);

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

Плагіни каналів можуть надавати інтерактивні майстри налаштування для 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 та інше. Повні приклади див. у пакетах вбудованих плагінів (наприклад, у Discord plugin src/channel.setup.ts). Для prompt’ів списку дозволів DM, яким потрібен лише стандартний потік note -> prompt -> parse -> merge -> patch, віддавайте перевагу спільним setup helper’ам з openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) і createNestedChannelParsedAllowFromPrompt(...). Для блоків статусу налаштування каналу, які відрізняються лише мітками, оцінками та необов’язковими додатковими рядками, віддавайте перевагу createStandardChannelSetupStatus(...) з openclaw/plugin-sdk/setup замість ручного створення однакового об’єкта status у кожному плагіні. Для необов’язкових поверхонь налаштування, які мають з’являтися лише в певних контекстах, використовуйте 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 також надає нижчорівневі конструктори createOptionalChannelSetupAdapter(...) і createOptionalChannelSetupWizard(...), коли вам потрібна лише одна половина цієї необов’язкової поверхні встановлення. Згенеровані необов’язкові adapter/wizard працюють у режимі fail-closed під час реального запису конфігурації. Вони повторно використовують одне повідомлення про необхідність встановлення у validateInput, applyAccountConfig і finalize, а також додають посилання на документацію, якщо задано docsPath. Для UI налаштування на основі бінарних файлів віддавайте перевагу спільним delegated helper’ам замість копіювання однакової логіки binary/status у кожен канал:
  • createDetectedBinaryStatus(...) для блоків статусу, що відрізняються лише мітками, підказками, оцінками та виявленням бінарного файлу
  • createCliPathTextInput(...) для текстових полів, прив’язаних до шляху
  • createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...) і createDelegatedResolveConfigured(...), коли setupEntry має ліниво переспрямовувати до важчого повного wizard
  • createDelegatedTextInputShouldPrompt(...), коли setupEntry потрібно лише делегувати рішення textInputs[*].shouldPrompt

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

Зовнішні плагіни: опублікуйте в ClawHub або npm, а потім установіть:
openclaw plugins install @myorg/openclaw-my-plugin
OpenClaw спочатку пробує ClawHub і автоматично переходить до npm. Ви також можете явно примусово використовувати ClawHub:
openclaw plugins install clawhub:@myorg/openclaw-my-plugin   # лише ClawHub
Відповідного перевизначення npm: немає. Використовуйте звичайну npm-spec пакета, коли хочете шлях npm після fallback з ClawHub:
openclaw plugins install @myorg/openclaw-my-plugin
Плагіни в репозиторії: розміщуйте їх у дереві workspace вбудованих плагінів, і вони автоматично виявлятимуться під час збирання. Користувачі можуть установлювати:
openclaw plugins install <package-name>
Для встановлень із npm openclaw plugins install виконує npm install --ignore-scripts (без lifecycle scripts). Зберігайте дерева залежностей плагіна чистими JS/TS і уникайте пакетів, які потребують збирання через postinstall.

Пов’язане