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

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

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

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

Вашому 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[]Файли точок входу (відносно кореня пакета)
setupEntrystringЛегка точка входу лише для налаштування (необов’язково)
channelobjectМетадані каталогу каналів для налаштування, вибору, швидкого старту та поверхонь стану
providersstring[]Ідентифікатори провайдерів, зареєстрованих цим плагіном
installobjectПідказки для встановлення: npmSpec, localPath, defaultChoice, minHostVersion, allowInvalidConfigRecovery
startupobjectПрапорці поведінки під час запуску

openclaw.channel

openclaw.channel — це недорогі метадані пакета для виявлення каналів і поверхонь налаштування до завантаження середовища виконання.
ПолеТипЩо це означає
idstringКанонічний ідентифікатор каналу.
labelstringОсновна мітка каналу.
selectionLabelstringМітка у виборі/налаштуванні, якщо вона має відрізнятися від label.
detailLabelstringДодаткова мітка для багатших каталогів каналів і поверхонь стану.
docsPathstringШлях до документації для посилань налаштування й вибору.
docsLabelstringПеревизначення мітки для посилань на документацію, якщо вона має відрізнятися від ідентифікатора каналу.
blurbstringКороткий опис для онбордингу/каталогу.
ordernumberПорядок сортування в каталогах каналів.
aliasesstring[]Додаткові псевдоніми пошуку для вибору каналу.
preferOverstring[]Ідентифікатори плагінів/каналів нижчого пріоритету, які цей канал має випереджати.
systemImagestringНеобов’язкова назва значка/system-image для UI-каталогів каналів.
selectionDocsPrefixstringТекст-префікс перед посиланнями на документацію в поверхнях вибору.
selectionDocsOmitLabelbooleanПоказувати шлях до документації напряму замість підписаного посилання в тексті вибору.
selectionExtrasstring[]Додаткові короткі рядки, додані в тексті вибору.
markdownCapablebooleanПозначає канал як сумісний із Markdown для рішень щодо вихідного форматування.
exposureobjectКерування видимістю каналу для налаштування, списків налаштованих каналів і поверхонь документації.
quickstartAllowFrombooleanВмикає для цього каналу стандартний потік налаштування quickstart allowFrom.
forceAccountBindingbooleanВимагає явної прив’язки облікового запису, навіть якщо існує лише один обліковий запис.
preferSessionLookupForAnnounceTargetbooleanНадає перевагу пошуку сесії під час визначення announce-target для цього каналу.
Приклад:
{
  "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 — це метадані пакета, а не метадані маніфесту.
ПолеТипЩо це означає
npmSpecstringКанонічна npm-специфікація для потоків встановлення/оновлення.
localPathstringЛокальний шлях для розробки або вбудованого встановлення.
defaultChoice"npm" | "local"Бажане джерело встановлення, коли доступні обидва варіанти.
minHostVersionstringМінімальна підтримувана версія OpenClaw у формі >=x.y.z.
allowInvalidConfigRecoverybooleanДає змогу потокам перевстановлення вбудованих плагінів відновлюватися після окремих збоїв через застарілу конфігурацію.
Якщо задано minHostVersion, його перевіряють як під час встановлення, так і під час завантаження реєстру маніфестів. Старіші хости пропускають плагін; некоректні рядки версій відхиляються. allowInvalidConfigRecovery — це не загальний обхід для зламаних конфігурацій. Він призначений лише для вузького відновлення вбудованих плагінів, щоб перевстановлення/налаштування могло виправити відомі залишки після оновлення, як-от відсутній шлях до вбудованого плагіна або застарілий запис channels.<id> для цього самого плагіна. Якщо конфігурація зламана з інших причин, встановлення все одно завершується із закритою відмовою та пропонує оператору виконати openclaw doctor --fix.

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

Плагіни каналів можуть увімкнути відкладене завантаження за допомогою:
{
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}
Якщо цю можливість увімкнено, OpenClaw завантажує лише setupEntry під час передслуховувальної фази запуску, навіть для вже налаштованих каналів. Повна точка входу завантажується після того, як gateway починає слухати.
Вмикайте відкладене завантаження лише тоді, коли ваш setupEntry реєструє все, що gateway потрібно до початку прослуховування (реєстрацію каналів, HTTP-маршрути, методи gateway). Якщо повна точка входу володіє необхідними можливостями запуску, залиште поведінку за замовчуванням.
Якщо ваш setup/full entry реєструє RPC-методи gateway, залишайте їх на префіксі, специфічному для плагіна. Зарезервовані простори імен основного адміністратора (config.*, exec.approvals.*, wizard.*, update.*) належать ядру й завжди зіставляються з 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
  }
}
Див. Plugin Manifest, щоб отримати повний довідник зі схеми.

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

Вузькі імпорти допоміжних засобів налаштування

Для гарячих шляхів лише налаштування віддавайте перевагу вузьким швам допоміжних засобів налаштування замість ширшої парасольки plugin-sdk/setup, коли вам потрібна лише частина поверхні налаштування:
Шлях імпортуВикористовуйте дляКлючові експорти
plugin-sdk/setup-runtimeдопоміжні засоби runtime під час налаштування, які залишаються доступними в setupEntry / відкладеному запуску каналуcreatePatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy
plugin-sdk/setup-adapter-runtimeадаптери налаштування облікових записів, що враховують середовищеcreateEnvPatchedAccountSetupAdapter
plugin-sdk/setup-toolsдопоміжні засоби CLI/архівів/документації для налаштування/встановленняformatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR
Використовуйте ширший шов plugin-sdk/setup, коли вам потрібен повний спільний набір інструментів налаштування, включно з допоміжними засобами patch-конфігурації, такими як moveSingleAccountChannelSectionToDefaultAccount(...). Адаптери patch для налаштування залишаються безпечними для імпорту на гарячому шляху. Їхня вбудована ледача перевірка contract-surface для підвищення одного облікового запису є лінивою, тому імпорт plugin-sdk/setup-runtime не завантажує завчасно виявлення вбудованої contract-surface до фактичного використання адаптера.

Підвищення одного облікового запису, яке належить каналу

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

Схема конфігурації

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

Побудова схем конфігурації каналу

Використовуйте buildChannelConfigSchema з openclaw/plugin-sdk/core, щоб перетворити схему 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 src/channel.setup.ts) для повних прикладів. Для запитів списку дозволених DM, яким потрібен лише стандартний потік note -> prompt -> parse -> merge -> patch, віддавайте перевагу спільним допоміжним засобам налаштування з 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 відмовляють у закритому режимі під час реальних записів конфігурації. Вони повторно використовують одне повідомлення про необхідність встановлення у validateInput, applyAccountConfig і finalize, а також додають посилання на документацію, якщо задано docsPath. Для UI налаштування, що спираються на бінарні файли, віддавайте перевагу спільним делегованим допоміжним засобам замість копіювання однакового glue-коду бінарних файлів/стану в кожен канал:
  • createDetectedBinaryStatus(...) для блоків стану, що відрізняються лише мітками, підказками, оцінками та виявленням бінарного файла
  • createCliPathTextInput(...) для текстових полів на основі шляху
  • createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...) і createDelegatedResolveConfigured(...), коли setupEntry має ліниво переспрямовувати до важчого повного майстра
  • 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-пакета, коли вам потрібен шлях npm після резервного переходу з ClawHub:
openclaw plugins install @myorg/openclaw-my-plugin
Плагіни в репозиторії: розмістіть їх у дереві workspace вбудованих плагінів, і вони автоматично виявлятимуться під час збірки. Користувачі можуть встановлювати:
openclaw plugins install <package-name>
Для встановлень із джерела npm openclaw plugins install виконує npm install --ignore-scripts (без lifecycle-скриптів). Зберігайте дерева залежностей плагіна чистими JS/TS і уникайте пакетів, які потребують збірок через postinstall.

Пов’язане

  • SDK Entry PointsdefinePluginEntry і defineChannelPluginEntry
  • Plugin Manifest — повний довідник зі схемою маніфесту
  • Building Plugins — покроковий посібник для початку роботи